diff options
Diffstat (limited to 'Master/texmf-dist/doc/latex/mfirstuc/mfirstuc-manual.tex')
-rw-r--r-- | Master/texmf-dist/doc/latex/mfirstuc/mfirstuc-manual.tex | 294 |
1 files changed, 268 insertions, 26 deletions
diff --git a/Master/texmf-dist/doc/latex/mfirstuc/mfirstuc-manual.tex b/Master/texmf-dist/doc/latex/mfirstuc/mfirstuc-manual.tex index 8dc9701bfa9..26c3ce9149d 100644 --- a/Master/texmf-dist/doc/latex/mfirstuc/mfirstuc-manual.tex +++ b/Master/texmf-dist/doc/latex/mfirstuc/mfirstuc-manual.tex @@ -1,5 +1,6 @@ \documentclass{nlctdoc} +\usepackage[a4paper,left=1.75in]{geometry} \usepackage{alltt} \usepackage{mfirstuc} \usepackage{pifont} @@ -19,14 +20,19 @@ pdftitle={mfirstuc.sty: uppercasing first letter}, pdfkeywords={LaTeX,package,uppercase}]{hyperref} +\IndexPrologue{% +\section*{\indexname}\markright{\indexname} +\addcontentsline{toc}{section}{\indexname}} + \begin{document} - \title{mfirstuc.sty v2.02: +\MakeShortVerb{|} + \title{mfirstuc.sty v2.03: uppercasing first letter} \author{Nicola L.C. Talbot\\[10pt] Dickimaw Books\\ \url{http://www.dickimaw-books.com/}} - \date{2015-12-17} + \date{2016-07-29} \maketitle \tableofcontents @@ -39,7 +45,61 @@ as the commands provided by \styfmt{mfirstuc} may be used without \styfmt{glossaries}, the two have been split into separately maintained packages. -\section{Capitalising a Word} +\begin{important} +The commands described here all have limitations. To minimise +problems, use text-block style semantic commands with one argument +(the text that requires case-changing), and avoid scoped +declarations. +\end{important} + +Here are some examples of semantic commands: +\begin{enumerate} +\item Quoted material: +\begin{verbatim} +\newcommand{\qt}[1]{``#1''} +\end{verbatim} +(or use the \styfmt{csquotes} package). With this, the following +works: +\begin{verbatim} +\makefirstuc{\qt{word}} +\end{verbatim} +This produces: +\begin{display} +\makefirstuc{\qt{word}} +\end{display} +Whereas +\begin{verbatim} +\makefirstuc{``word''} +\end{verbatim} +fails (no case-change and double open quote becomes two single open +quotes): +\begin{display} +\makefirstuc{``word''} +\end{display} + +\item Font styles or colours: +\begin{verbatim} +\newcommand*{\alert}[1]{\textcolor{red}{#1}} +\end{verbatim} +Now the following is possible: +\begin{verbatim} +\makefirstuc{\alert{word}} +\end{verbatim} +This produces +\begin{display} +\newcommand*{\alert}[1]{\textcolor{red}{#1}}% +\makefirstuc{\alert{word}} +\end{display} +Note that \verb|\makefirstuc{\textcolor{red}{word}}| fails +(with an error) because the case-changing interferes with the label. +\end{enumerate} + +Define these semantic commands robustly if you intend using +any of the commands that fully expand their argument +(\cs{emakefirstuc}, \cs{ecapitalisewords} and +\cs{ecapitalisefmtwords}). + +\section{Capitalising the First Letter of a Word} \label{sec:makefirstuc} A simple word can be capitalised just using the standard \LaTeX\ @@ -65,7 +125,7 @@ If \meta{stuff} starts with a control sequence that takes more than one argument, the case-changing will always be applied to the \emph{first} argument. If the text that requires the case change is in one of the other arguments, you must hide the earlier arguments -in a wrapper command. For example, instead of \verb|\color{red}{text}| +in a wrapper command. For example, instead of \verb|\textcolor{red}{text}| you need to define, say, \verb|\red| as \verb|\color{red}| and use \verb|\red{text}|. \end{important} @@ -179,7 +239,7 @@ For example: Remember to also load \sty{textcase} (\styfmt{glossaries} loads this automatically). -\section{Capitalise Each Word in a Phrase or Sentence (Title Case)} +\section{Capitalise the First Letter of Each Word in a Phrase or Sentence (Title Case)} \label{sec:capitalisewords} New to mfirstuc v1.06: @@ -190,7 +250,47 @@ This command applies \ics{makefirstuc} to each word in \meta{text} where the space character is used as the word separator. Note that it has to be a plain space character, not another form of space, such as \verb|~| or \cs{space}. Note that no expansion is performed -on \meta{text}. +on \meta{text}. See \sectionref{sec:nocap} for excluding +words (such as \qt{of}) from the case-changing. + +The actual capitalisation of each word is done using +(new to version 2.03): +\begin{definition}[\DescribeMacro\MFUcapword] +\cs{MFUcapword}\marg{word} +\end{definition} +This just does \cs{makefirstuc}\marg{word} by default, but +its behaviour is determined by the conditional: +\begin{definition}[\DescribeMacro\ifMFUhyphen] +\cs{ifMFUhyphen} +\end{definition} + +If you want to title case each part of +a compound word containing hyphens, you can enable this using +\begin{definition}[\DescribeMacro\MFUhyphentrue] +\cs{MFUhyphentrue} +\end{definition} +or switch it back off again using: +\begin{definition}[\DescribeMacro\MFUhyphenfalse] +\cs{MFUhyphenfalse} +\end{definition} +Compare +\begin{verbatim} +\capitalisewords{server-side includes} +\end{verbatim} +which produces: +\begin{display} +\capitalisewords{server-side includes} +\end{display} +with +\begin{verbatim} +\MFUhyphentrue +\capitalisewords{server-side includes} +\end{verbatim} +which produces: +\begin{display} +\MFUhyphentrue +\capitalisewords{server-side includes} +\end{display} Formatting for the entire phrase must go outside \cs{capitalisewords} (unlike \cs{makefirstuc}). Compare: @@ -210,6 +310,82 @@ which produces: \textbf{\capitalisewords{a sample phrase}} \end{display} +As from version 2.03, there is now a command for phrases that may +include a formatting command: +\begin{definition} +\cs{capitalisefmtwords}\marg{phrase} +\end{definition} +where \meta{phrase} may be just words (as with \cs{capitalisewords}) +or may be entirely enclosed in a formatting command in the form +\begin{alltt} +\cs{capitalisefmtwords}\{\meta{cs}\marg{phrase}\} +\end{alltt} +or contain formatted sub-phrases +\begin{alltt} +\cs{capitalisefmtwords}\{\meta{words} \meta{cs}\marg{sub-phrase} \meta{words}\} +\end{alltt} +Avoid scoped declarations. + +Examples: +\begin{enumerate} +\item Phrase entirely enclosed in a formatting command: +\begin{verbatim} +\capitalisefmtwords{\textbf{a small book of rhyme}} +\end{verbatim} +produces: +\begin{display} +\capitalisefmtwords{\textbf{a small book of rhyme}} +\end{display} + +\item Sub-phrase enclosed in a formatting command: +\begin{verbatim} +\capitalisefmtwords{a \textbf{small book} of rhyme} +\end{verbatim} +produces: +\begin{display} +\capitalisefmtwords{a \textbf{small book} of rhyme} +\end{display} + +\item Nested text-block commands: +\begin{verbatim} +\capitalisefmtwords{\textbf{a \emph{small book}} of rhyme} +\end{verbatim} +produces: +\begin{display} +\capitalisefmtwords{\textbf{a \emph{small book}} of rhyme} +\end{display} + +\item Indicating words that shouldn't have the case changed +(see \sectionref{sec:nocap}): +\begin{verbatim} +\MFUnocap{of} +\capitalisefmtwords{\textbf{a \emph{small book}} of rhyme} +\end{verbatim} +produces: +\begin{display} +\MFUnocap{of} +\capitalisefmtwords{\textbf{a \emph{small book}} of rhyme} +\end{display} +\end{enumerate} + +Grouping causes interference: +\begin{verbatim} +\capitalisefmtwords{{a \emph{small book}} of rhyme} +\end{verbatim} +produces: +\begin{display} +\capitalisefmtwords{{a \emph{small book}} of rhyme} +\end{display} +As with all the commands described here, avoid declarations. +For example, the following fails: +\begin{verbatim} +\capitalisefmtwords{{\bfseries a \emph{small book}} of rhyme} +\end{verbatim} +produces: +\begin{display} +\capitalisefmtwords{{\bfseries a \emph{small book}} of rhyme} +\end{display} + \begin{definition}[\DescribeMacro{\xcapitalisewords}] \cs{xcapitalisewords}\marg{text} \end{definition} @@ -222,6 +398,23 @@ entire argument before applying \cs{capitalisewords}: \cs{ecapitalisewords}\marg{text} \end{definition} +There are also similar shortcut commands for the version that allows +formatting commands: +\begin{definition}[\DescribeMacro{\xcapitalisefmtwords}] +\cs{xcapitalisefmtwords}\marg{text} +\end{definition} +This is a short cut for +\cs{expandafter}\cs{capitalisefmtwords}\cs{expandafter}\marg{text}. + +For full expansion: +\begin{definition}[\DescribeMacro\ecapitalisefmtwords] +\cs{ecapitalisefmtwords}\marg{text} +\end{definition} +Take care with this as it may expand non-robust semantic commands +to replacement text that breaks the functioning of +\cs{capitalisefmtwords}. Use robust semantic commands +where possible. + Examples: \begin{verbatim} \newcommand{\abc}{\xyz\space four five} @@ -231,11 +424,13 @@ First object one-level expansion: \xcapitalisewords{\abc}. Fully expanded: \ecapitalisewords{\abc}. \end{verbatim} produces: +\begin{display} \renewcommand{\abc}{\xyz\space four five}% \renewcommand{\xyz}{one two three} No expansion: \capitalisewords{\abc}. First object one-level expansion: \xcapitalisewords{\abc}. Fully expanded: \ecapitalisewords{\abc}. +\end{display} (Remember that the spaces need to be explicit. In the second case above, using \cs{xcapitalisewords}, the space before \qt{four} has @@ -243,21 +438,6 @@ been hidden within \cs{space} so it's not recognised as a word boundary, but in the third case, \cs{space} has been expanded to an actual space character.) -\begin{important} -If you are using \sty{hyperref} and want to use \cs{capitalisewords} -or \ics{makefirstuc} (or the expanded variants) -in a section heading, the PDF bookmarks won't be able to use the command -as it's not expandable, so you will get a warning that looks like: -\begin{verbatim} -Package hyperref Warning: Token not allowed in a PDF string -(PDFDocEncoding): -(hyperref) removing `\capitalisewords' -\end{verbatim} -If you want to provide an alternative for the PDF bookmark, you can -use \sty{hyperref}'s \ics{texorpdfstring} command. See the -\sty{hyperref} manual for further details. -\end{important} - Examples: \begin{enumerate} \item @@ -301,6 +481,43 @@ produces: \end{enumerate} +\subsection{PDF Bookmarks} +\label{sec:pdfbookmarks} + +\begin{important} +If you are using \sty{hyperref} and want to use +\cs{capitalisewords}, \cs{capitalisefmtwords} +or \ics{makefirstuc} (or the expanded variants) +in a section heading, the PDF bookmarks won't be able to use the command +as it's not expandable, so you will get a warning that looks like: +\begin{verbatim} +Package hyperref Warning: Token not allowed in a PDF string +(PDFDocEncoding): +(hyperref) removing `\capitalisewords' +\end{verbatim} +\end{important} + +If you want to provide an alternative for the PDF bookmark, you can +use \sty{hyperref}'s \ics{texorpdfstring} command. For example: +\begin{verbatim} +\chapter{\texorpdfstring + {\capitalisewords{a book of rhyme}}% TeX + {A Book of Rhyme}% PDF +} +\end{verbatim} +Alternatively, you can use \sty{hyperref}'s mechanism for +disabling commands within the bookmarks. For example: +\begin{verbatim} +\pdfstringdefDisableCommands{% + \let\capitalisewords\@firstofone +} +\end{verbatim} + +See the \sty{hyperref} manual for further details. + +\subsection{Excluding Words From Case-Changing} +\label{sec:nocap} + As from v1.09, you can specify words which shouldn't be capitalised unless they occur at the start of \meta{text} using: \begin{definition}[\DescribeMacro\MFUnocap] @@ -334,10 +551,33 @@ The list of words that shouldn't be capitalised can be cleared using \cs{MFUclear} \end{definition} -The package \sty{mfirstuc-english} loads \sty{mfirstuc} and uses +You can also simply place an empty group in front of a word +if you don't want that specific instance to be capitalised. +For example: +\begin{verbatim} +\MFUclear +\capitalisewords{the {}wind in the willows} +\end{verbatim} +produces: +\begin{display} +\MFUclear +\capitalisewords{the {}wind in the willows} +\end{display} +This is also a useful way of protecting commands that +shouldn't be parsed. For example: +\begin{verbatim} +\capitalisewords{this is section {}\nameref{sec:nocap}.} +\end{verbatim} +produces +\begin{display} +\capitalisewords{this is section {}\nameref{sec:nocap}.} +\end{display} +(No case-changing is applied to \verb|\nameref{sec:nocap}|.) + +The package \sty{mfirstuc-english} loads \styfmt{mfirstuc} and uses \cs{MFUnocap} to add common English articles and conjunctions, such as ``a'', ``an'', ``and'', ``but''. You may want to add other -words to this list, such as prepositions, but as there's some +words to this list, such as prepositions but, as there's some dispute over whether prepositions should be capitalised, I~don't intend to add them to this package. @@ -357,7 +597,7 @@ argument, for example: \begin{verbatim} \ProvidesPackage{mfirstuc-french}[2014/07/30 v1.0] \end{verbatim} -Next load \sty{mfirstuc}: +Next load \styfmt{mfirstuc}: \begin{verbatim} \RequirePackage{mfirstuc} \end{verbatim} @@ -371,8 +611,9 @@ At the end of the file add: \end{verbatim} Put the file somewhere on \TeX's path, and now you can use this -package in your document. You might also consider uploading it -to CTAN in case other users find it useful. +package in your document. You might also consider +\href{http://ctan.org/upload}{uploading it to CTAN} in case +other users find it useful. \section{UTF-8} \label{sec:utf8} @@ -490,4 +731,5 @@ This works correctly when compiled with \XeLaTeX. This means that \cs{makefirstuc}\verb|{|\texttt{\~abc}\verb|}| will work \emph{provided you use \XeLaTeX\ and the \sty{fontspec} package}. +\PrintIndex \end{document} |