\documentclass{nlctdoc} \usepackage[a4paper,left=1.75in]{geometry} \usepackage{alltt} \usepackage{mfirstuc} \usepackage{pifont} \usepackage[utf8]{inputenc} \ifpdf \usepackage[T1]{fontenc} \usepackage{metalogo} \else \providecommand{\XeLaTeX}{XeLaTeX} \providecommand{\XeTeX}{XeTeX} \fi \usepackage{cmap} \usepackage[colorlinks, bookmarks, hyperindex=false, pdfauthor={Nicola L.C. Talbot}, pdftitle={mfirstuc.sty: uppercasing first letter}, pdfkeywords={LaTeX,package,uppercase}]{hyperref} \IndexPrologue{% \section*{\indexname}\markright{\indexname} \addcontentsline{toc}{section}{\indexname}} \begin{document} \MakeShortVerb{|} \title{mfirstuc.sty v2.03: uppercasing first letter} \author{Nicola L.C. Talbot\\[10pt] Dickimaw Books\\ \url{http://www.dickimaw-books.com/}} \date{2016-07-29} \maketitle \tableofcontents \section{Introduction} \label{sec:intro} The \styfmt{mfirstuc} package was originally part of the \styfmt{glossaries} bundle for use with commands like \cs{Gls}, but as the commands provided by \styfmt{mfirstuc} may be used without \styfmt{glossaries}, the two have been split into separately maintained packages. \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\ upper casing command. For example, \begin{verbatim} \MakeUppercase word \end{verbatim} but for commands like \cs{Gls} the word may be embedded within the argument of another command, such as a~font changing command. This makes things more complicated for a~general purpose solution, so the \styfmt{mfirstuc} package provides: \begin{definition}[\DescribeMacro{\makefirstuc}] \cs{makefirstuc}\marg{stuff} \end{definition} This makes the first object of \meta{stuff} upper case unless \meta{stuff} starts with a control sequence followed by a non-empty group, in which case the first object in the group is converted to upper case. \textbf{No expansion is performed on the argument.} \begin{important} 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|\textcolor{red}{text}| you need to define, say, \verb|\red| as \verb|\color{red}| and use \verb|\red{text}|. \end{important} Examples: \begin{itemize} \item |\makefirstuc{abc}| produces \makefirstuc{abc}. \item |\makefirstuc{\emph{abc}}| produces \makefirstuc{\emph{abc}} (\ics{MakeUppercase} has been applied to the letter \qt{a} rather than \cs{emph}). Note however that \begin{verbatim} \makefirstuc{{\em abc}} \end{verbatim} produces \makefirstuc{{\em abc}} (first object is |{\em abc}| so this is equivalent to |\MakeUppercase{\em abc}|), and \begin{verbatim} {\makefirstuc{\em abc}} \end{verbatim} produces {\makefirstuc{\em abc}} (|\em| doesn't have an argument therefore first object is |\em| and so is equivalent to |{\MakeUppercase{\em}abc}|). \item |\makefirstuc{{\'a}bc}| produces \makefirstuc{{\'a}bc}. \item |\makefirstuc{\ae bc}| produces \makefirstuc{\ae bc}. \item |\makefirstuc{{\ae}bc}| produces \makefirstuc{{\ae}bc}. \item |\makefirstuc{{ä}bc}| produces \makefirstuc{{ä}bc}. \end{itemize} Note that non-Latin or accented characters appearing at the start of the text must be placed in a group (even if you are using the \sty{inputenc} package). The reason for this restriction is detailed in \sectionref{sec:utf8}. \begin{important} In version 1.02 of \styfmt{mfirstuc}, a bug fix resulted in a change in output if the first object is a control sequence followed by an empty group. Prior to version 1.02, |\makefirstuc{\ae{}bc}| produced \ae Bc. However as from version 1.02, it now produces \AE bc. \end{important} Note also that \begin{verbatim} \newcommand{\abc}{abc} \makefirstuc{\abc} \end{verbatim} produces: ABC. This is because the first object in the argument of \cs{makefirstuc} is \cs{abc}, so it does |\MakeUppercase{\abc}|. Whereas: \begin{verbatim} \newcommand{\abc}{abc} \expandafter\makefirstuc\expandafter{\abc} \end{verbatim} produces: Abc. There is a short cut command which will do this: \begin{definition}[\DescribeMacro{\xmakefirstuc}] \cs{xmakefirstuc}\marg{stuff} \end{definition} This is equivalent to \cs{expandafter}\cs{makefirstuc}\cs{expandafter}\marg{stuff}. So \begin{verbatim} \newcommand{\abc}{abc} \xmakefirstuc{\abc} \end{verbatim} produces: \newcommand{\abc}{abc}% \xmakefirstuc{\abc}. \begin{important} \cs{xmakefirstuc} only performs one level expansion on the \emph{first} object in its argument. It does not fully expand the entire argument. \end{important} As from version 1.10, there is now a command that fully expands the entire argument before applying \cs{makefirstuc}: \begin{definition}[\DescribeMacro\emakefirstuc] \cs{emakefirstuc}\marg{text} \end{definition} Examples: \begin{verbatim} \newcommand{\abc}{\xyz a} \newcommand{\xyz}{xyz} No expansion: \makefirstuc{\abc}. First object one-level expansion: \xmakefirstuc{\abc}. Fully expanded: \emakefirstuc{\abc}. \end{verbatim} produces: \renewcommand{\abc}{\xyz a}% \newcommand{\xyz}{xyz} No expansion: \makefirstuc{\abc}. First object one-level expansion: \xmakefirstuc{\abc}. Fully expanded: \emakefirstuc{\abc}. If you use \styfmt{mfirstuc} without the \sty{glossaries} package, the standard \cs{MakeUppercase} command is used. If used with \sty{glossaries}, \ics{MakeTextUppercase} (defined by the \sty{textcase} package) is used instead. If you are using \styfmt{mfirstuc} without the \styfmt{glossaries} package and want to use \ics{MakeTextUppercase} instead, you can redefine \begin{definition}[\DescribeMacro\glsmakefirstuc] \cs{glsmakefirstuc}\marg{text} \end{definition} For example: \begin{verbatim} \renewcommand{\glsmakefirstuc}[1]{\MakeTextUppercase #1} \end{verbatim} Remember to also load \sty{textcase} (\styfmt{glossaries} loads this automatically). \section{Capitalise the First Letter of Each Word in a Phrase or Sentence (Title Case)} \label{sec:capitalisewords} New to mfirstuc v1.06: \begin{definition}[\DescribeMacro{\capitalisewords}] \cs{capitalisewords}\marg{text} \end{definition} 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}. 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: \begin{verbatim} \capitalisewords{\textbf{a sample phrase}} \end{verbatim} which produces: \begin{display} \capitalisewords{\textbf{a sample phrase}} \end{display} with: \begin{verbatim} \textbf{\capitalisewords{a sample phrase}} \end{verbatim} which produces: \begin{display} \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} This is a short cut for \cs{expandafter}\cs{capitalisewords}\cs{expandafter}\marg{text}. As from version 1.10, there is now a command that fully expands the entire argument before applying \cs{capitalisewords}: \begin{definition}[\DescribeMacro\ecapitalisewords] \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} \newcommand{\xyz}{one two three} No expansion: \capitalisewords{\abc}. 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 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.) Examples: \begin{enumerate} \item \begin{verbatim} \capitalisewords{a book of rhyme.} \end{verbatim} produces: \capitalisewords{a book of rhyme.} \item \begin{verbatim} \capitalisewords{a book\space of rhyme.} \end{verbatim} produces: \capitalisewords{a book\space of rhyme.} \item \begin{verbatim} \newcommand{\mytitle}{a book\space of rhyme.} \capitalisewords{\mytitle} \end{verbatim} produces: \newcommand{\mytitle}{a book\space of rhyme.} \capitalisewords{\mytitle} (No expansion is performed on \cs{mytitle}.) Compare with next example: \item \begin{verbatim} \newcommand{\mytitle}{a book\space of rhyme.} \xcapitalisewords{\mytitle} \end{verbatim} produces: \xcapitalisewords{\mytitle} However \begin{verbatim} \ecapitalisewords{\mytitle} \end{verbatim} produces: \ecapitalisewords{\mytitle} \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] \cs{MFUnocap}\marg{word} \end{definition} This only has a local effect. The global version is: \begin{definition}[\DescribeMacro\gMFUnocap] \cs{gMFUnocap}\marg{word} \end{definition} For example: \begin{verbatim} \capitalisewords{the wind in the willows} \MFUnocap{in}% \MFUnocap{the}% \capitalisewords{the wind in the willows} \end{verbatim} produces: \begin{display} \capitalisewords{the wind in the willows} \MFUnocap{in}% \MFUnocap{the}% \capitalisewords{the wind in the willows} \end{display} The list of words that shouldn't be capitalised can be cleared using \begin{definition}[\DescribeMacro\MFUclear] \cs{MFUclear} \end{definition} 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 dispute over whether prepositions should be capitalised, I~don't intend to add them to this package. If you want to write a similar package for another language, all you need to do is create a file with the extension \texttt{.sty} that starts with \begin{verbatim} \NeedsTeXFormat{LaTeX2e} \end{verbatim} The next line should identify the package. For example, if you have called the file \texttt{mfirstuc-french.sty} then you need: \begin{verbatim} \ProvidesPackage{mfirstuc-french} \end{verbatim} It's a good idea to also add a version in the final optional argument, for example: \begin{verbatim} \ProvidesPackage{mfirstuc-french}[2014/07/30 v1.0] \end{verbatim} Next load \styfmt{mfirstuc}: \begin{verbatim} \RequirePackage{mfirstuc} \end{verbatim} Now add all your \cs{MFUnocap} commands. For example: \begin{verbatim} \MFUnocap{de} \end{verbatim} At the end of the file add: \begin{verbatim} \endinput \end{verbatim} Put the file somewhere on \TeX's path, and now you can use this 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} The \cs{makefirstuc} command works by utilizing the fact that, in most cases, \TeX\ doesn't require a regular argument to be enclosed in braces if it only consists of a single token. (This is why you can do, say, \verb|\frac12| instead of \verb|\frac{1}{2}| or \verb|x^2| instead of \verb|x^{2}|, although some users frown on this practice.) A~simplistic version of the \cs{makefirstuc} command is: \begin{verbatim} \newcommand*{\FirstUC}[1]{\MakeUppercase #1} \end{verbatim} Here \begin{verbatim} \FirstUC{abc} \end{verbatim} is equivalent to \begin{verbatim} \MakeUppercase abc \end{verbatim} and since \cs{MakeUppercase} requires an argument, it grabs the first token (the character ``a'' in this case) and uses that as the argument so that the result is: Abc. The \sty{glossaries} package needs to take into account the fact that the text may be contained in the argument of a formatting command, such as \cs{acronymfont}, so \cs{makefirstuc} has to be more complicated than the trivial \cs{FirstUC} shown above, but at its basic level, \cs{makefirstuc} uses this same method and is the reason why, in most cases, you don't need to enclose the first character in braces. So if \begin{alltt} \cs{MakeUppercase} \meta{stuff} \end{alltt} works, then \begin{alltt} \cs{makefirstuc}\marg{stuff} \end{alltt} should also work and so should \begin{alltt} \cs{makefirstuc}\{\cs{foo}\marg{stuff}\} \end{alltt} but if \begin{alltt} \cs{MakeUppercase} \meta{stuff} \end{alltt} doesn't work, then neither will \begin{alltt} \cs{makefirstuc}\marg{stuff} \end{alltt} nor \begin{alltt} \cs{makefirstuc}\{\cs{foo}\marg{stuff}\} \end{alltt} Try the following document: \begin{alltt} \cs{documentclass}\{article\} \cs{usepackage}[utf8]\{inputenc\} \cs{usepackage}[T1]\{fontenc\} \cs{begin}\{document\} \cs{MakeUppercase} \~abc \cs{end}\{document\} \end{alltt} This will result in the error: \begin{verbatim} ! Argument of \UTFviii@two@octets has an extra }. \end{verbatim} This is why \verb|\makefirstuc{|\texttt{\~abc}\verb|}| won't work. It will only work if the character \texttt{\~a} is placed inside a group. The reason for this error message is due to \TeX\ having been written before Unicode was invented. Although \texttt{\~a} may look like a single character in your text editor, from \TeX's point of view it's \emph{two} tokens. So \begin{alltt} \cs{MakeUppercase} \~abc \end{alltt} tries to apply \cs{MakeUppercase} to just the first octet of \~a. This means that the second octet has been separated from the first octet, which is the cause of the error. In this case the argument isn't a single token, so the two tokens (the first and second octet of \~a) must be grouped: \begin{alltt} \cs{MakeUppercase}\{\~a\}bc \end{alltt} Note that \XeTeX\ (and therefore \XeLaTeX) is a modern implementation of \TeX\ designed to work with Unicode and therefore doesn't suffer from this drawback. Now let's look at the \XeLaTeX\ equivalent of the above example: \begin{alltt} \cs{documentclass}\{article\} \cs{usepackage}\{fontspec\} \cs{begin}\{document\} \cs{MakeUppercase} \~abc \cs{end}\{document\} \end{alltt} 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}