% This file is public domain
 % If you want to use arara, you need the following directive:
 % arara: pdflatex: { synctex: on }
 % arara: pdflatex: { synctex: on }
\documentclass{article}

\usepackage[a4paper]{geometry}
\usepackage{color}
\usepackage{mfirstuc-english}% also loads mfirstuc.sty
\usepackage[hidelinks]{hyperref}

\title{Sample Document Illustrating the mfirstuc Package}
\author{Nicola Talbot}

\begin{document}
\maketitle

\tableofcontents

\section{First Letter Upper Case}

\verb|\makefirstuc{abc}.|
\makefirstuc{abc}.

\verb|\makefirstuc{{\em abc}}.|
\makefirstuc{{\em abc}}.

\verb|\makefirstuc{\emph{abc}}.|
\makefirstuc{\emph{abc}}.

\verb|\makefirstuc{\ae bc}.|
\makefirstuc{\ae bc}.

\verb|\makefirstuc{{\ae}bc}.|
\makefirstuc{{\ae}bc}.

\verb|\newcommand{\abc}{abc}\xmakefirstuc{\abc}.|
\newcommand{\abc}{abc}%
\xmakefirstuc{\abc}.

\newcommand*{\mytext}{\protect\textbf{some text}}
Protected formatting: \xmakefirstuc{\mytext}.

\renewcommand*{\mytext}{\ae\oe{some text}}
Sequential commands: \xmakefirstuc{\mytext}.

\verb|\makefirstuc{\MFUskippunc{?`}c\'omo est\'as?}|
\makefirstuc{\MFUskippunc{?`}c\'omo est\'as?}

\renewcommand{\mytext}{\MFUskippunc{?`}c\'omo est\'as?}
Fully expanded:
\emakefirstuc{\mytext}

\section{Title Case (No Formatting Commands)}

\bgroup

\verb|\capitalisewords{the wind in the willows}|
\capitalisewords{the wind in the willows}

\verb|\capitalisewords{a small book of rhyme.}|
\capitalisewords{a small book of rhyme.}

\medskip

\verb|\space| isn't considered a word boundary for
\verb|\capitalisewords| as shown below:

\begin{verbatim}
\capitalisewords{a small\space book of rhyme.}
\end{verbatim}
\capitalisewords{a small\space book of rhyme.}

\medskip
No expansion is performed on the argument of
\verb|\capitalisewords|:

\verb|\newcommand{\mytitle}{a small book of rhyme.}|
\newcommand{\mytitle}{a small book of rhyme.}

\verb|\capitalisewords{\mytitle}|
\capitalisewords{\mytitle}

\verb|\xcapitalisewords{\mytitle}|
\xcapitalisewords{\mytitle}

\egroup

Formatting for the entire phrase must go outside
\verb|\capitalisewords| (unlike \verb|\makefirstuc|). Compare:

\begin{verbatim}
\capitalisewords{\textbf{a small book of rhyme.}}
\end{verbatim}
\capitalisewords{\textbf{a small book of rhyme.}}

\begin{verbatim}
\textbf{\capitalisewords{a small book of rhyme.}}
\end{verbatim}
\textbf{\capitalisewords{a small book of rhyme.}}

\medskip

Use \verb|\capitalisefmtwords| instead. The starred form
is limited to one text-block command at the start of the argument.

\begin{verbatim}
\capitalisefmtwords*{\emph{a small book of rhyme}}
\end{verbatim}
\capitalisefmtwords*{\emph{a small book of rhyme}}

Additional text-block commands can cause unexpected results.

\begin{verbatim}
\capitalisefmtwords*{\emph{a small} book \textbf{of rhyme}}
\end{verbatim}
\capitalisefmtwords*{\emph{a small} book \textbf{of rhyme}}

\section{Title Case (Contains Text-Block Formatting Commands)}

The unstarred form of \verb|\capitalisefmtwords| is still a bit
experimental and is only designed
for phrases that contain text-block commands with a single
argument, which should be a word or sub-phrase.

\verb|\capitalisefmtwords{\textbf{a small book of rhyme}}.|
\capitalisefmtwords{\textbf{a small book of rhyme}}.

\verb|\capitalisefmtwords{\textbf{a small book} of rhyme}.|
\capitalisefmtwords{\textbf{a small book} of rhyme}.

\verb|\capitalisefmtwords{a \textbf{small book} of rhyme}.|
\capitalisefmtwords{a \textbf{small book} of rhyme}.

\verb|\capitalisefmtwords{\textbf{a} small book of rhyme}.|
\capitalisefmtwords{\textbf{a} small book of rhyme}.

\verb|\capitalisefmtwords{a small book \textbf{of rhyme}}.|
\capitalisefmtwords{a small book \textbf{of rhyme}}.

\medskip

Be careful of trailing spaces at the end a group. They can confuse
things.

\verb|\capitalisefmtwords{\textbf{a small }book of rhyme}.|
\capitalisefmtwords{\textbf{a small }book of rhyme}.

\verb|\capitalisefmtwords{\textbf{a small book }of rhyme}.|
\capitalisefmtwords{\textbf{a small book }of rhyme}.

\verb|\capitalisefmtwords{\textbf{a small book of }rhyme}.|
\capitalisefmtwords{\textbf{a small book of }rhyme}.

\medskip

Use semantic commands for things like quotations:

\begin{verbatim}
\newcommand*{\qt}[1]{``#1''}
\capitalisefmtwords{\qt{a small book of rhyme.}}
\end{verbatim}
\newcommand*{\qt}[1]{``#1''}
\capitalisefmtwords{\qt{a small book of rhyme.}}

\smallskip

(But make them robust if you intend using commands like
\verb|\ecapitalisefmtwords|.)
Similarly for other types of punctuation:
\begin{verbatim}
\newcommand*{\esq}[1]{'?#1?}
\capitalisefmtwords{\esq{D\'onde est\'a libro}}
\end{verbatim}
\newcommand*{\esq}[1]{?`#1?}
\capitalisefmtwords{\esq{D\'onde est\'a libro}}

\medskip

Anything more complicated than a simple one-argument text-block
command requires the starred version.

\begin{verbatim}
\newcommand*{\swap}[2]{{#2}{#1}}
\capitalisefmtwords*{\textbf{an \swap{un}{usually} small book of} rhyme}.
\end{verbatim}
\newcommand*{\swap}[2]{{#2}{#1}}
\capitalisefmtwords*{\textbf{an \swap{un}{usually} small book of} rhyme}.

\medskip

Nested text-block commands:

\begin{verbatim}
\capitalisefmtwords{\textbf{a \emph{small book} of} rhyme}.
\end{verbatim}
\capitalisefmtwords{\textbf{a \emph{small book} of} rhyme}.

\begin{verbatim}
\capitalisefmtwords{\textbf{a \emph{small book}} of rhyme}.
\end{verbatim}
\capitalisefmtwords{\textbf{a \emph{small book}} of rhyme}.

\begin{verbatim}
\capitalisefmtwords{\textbf{\emph{a small} book of} rhyme}.
\end{verbatim}
\capitalisefmtwords{\textbf{\emph{a small} book of} rhyme}.

\medskip

An empty brace at the start of a word will suppress the
case-changing.

\begin{verbatim}
\capitalisefmtwords{\textbf{a small {}book of} rhyme}.
\end{verbatim}
\capitalisefmtwords{\textbf{a small {}book of} rhyme}.

\medskip

Suppress case-changing for problematic commands by inserting
an empty group in front:

\begin{verbatim}
\capitalisefmtwords{{}\textcolor{red}{a} small book of
{}\textcolor{red}{rhyme}}.
\end{verbatim}
\capitalisefmtwords{{}\textcolor{red}{a} small book of
{}\textcolor{red}{rhyme}}.

\medskip

If possible provide semantic command instead.

\begin{verbatim}
\newcommand*{\alert}[1]{\textcolor{red}{#1}}
\capitalisefmtwords{\alert{a} small book of \alert{rhyme}}.
\end{verbatim}
\newcommand*{\alert}[1]{\textcolor{red}{#1}}
\capitalisefmtwords{\alert{a} small book of \alert{rhyme}}.

\medskip

No formatting commands in the following example:

\verb|\capitalisefmtwords{a small book of rhyme}.|
\capitalisefmtwords{a small book of rhyme}.

\medskip

Avoid scoped declarations. The next example doesn't work.

\begin{verbatim}
\capitalisefmtwords{{\bfseries a \emph{small book} of} rhyme.}
\end{verbatim}
\capitalisefmtwords{{\bfseries a \emph{small book} of} rhyme.}

\medskip

If a command isn't followed by a grouped argument, the
case-change is applied to the command (on the assumption
that it's a character command, such as \verb|\ae|). This can
have an odd effect if case-changing has no meaning for that command.
As illustrated next:

\verb|\capitalisefmtwords{\relax a book of rhyme.}|
\capitalisefmtwords{\relax a book of rhyme.}

\section{Compound Words}

Use \verb|\MFUhyphentrue| to title case each part of
a compound word.

Default:
\begin{verbatim}
\capitalisewords{a fast-paced book of rhyme}.
\capitalisefmtwords{a \textbf{fast-paced} book of rhyme}.
\end{verbatim}
\capitalisewords{a fast-paced book of rhyme}.
\capitalisefmtwords{a \textbf{fast-paced} book of rhyme}.

Compare with
\begin{verbatim}
\MFUhyphentrue
\capitalisewords{a fast-paced book of rhyme}.
\capitalisefmtwords{a \textbf{fast-paced} book of rhyme}.
\end{verbatim}
\MFUhyphentrue
\capitalisewords{a fast-paced book of rhyme}.
\capitalisefmtwords{a \textbf{fast-paced} book of rhyme}.

\end{document}