1 files changed, 164 insertions, 14 deletions

diff --git a/Master/texmf-dist/doc/latex/mfirstuc/sample-mfirstuc.tex b/Master/texmf-dist/doc/latex/mfirstuc/sample-mfirstuc.tex
index 5fe9d92b48c..eb1104be59a 100644
--- a/Master/texmf-dist/doc/latex/mfirstuc/sample-mfirstuc.tex
+++ b/Master/texmf-dist/doc/latex/mfirstuc/sample-mfirstuc.tex
@@ -3,20 +3,31 @@
  % arara: pdflatex: { synctex: on }
 \documentclass{article}
 
-\usepackage{mfirstuc-english}
+\usepackage[a4paper]{geometry}
+\usepackage{color}
+\usepackage{mfirstuc-english}% also loads mfirstuc.sty
 
 \begin{document}
+This is a sample document illustrating the mfirstuc package.
 
+\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}.
 
@@ -26,30 +37,169 @@ Protected formatting: \xmakefirstuc{\mytext}.
 \renewcommand*{\mytext}{\ae\oe{some text}}
 Sequential commands: \xmakefirstuc{\mytext}.
 
-\capitalisewords{the wind in the willows}
+\section{Title Case (Formatting)}
+
+Formatting for the entire phrase must go outside
+\verb|\capitalisewords| (unlike \verb|\makefirstuc|). Compare:
+
+\verb|\capitalisewords{\textbf{a small book of rhyme.}}|
+\capitalisewords{\textbf{a small book of rhyme.}}
+
+with:
+
+\verb|\textbf{\capitalisewords{a small book of rhyme.}}|
+\textbf{\capitalisewords{a small book of rhyme.}}
+
+\medskip
+
+Use \verb|\capitalisefmtwords| instead (full stop outside
+argument to check for spurious spaces):
+
+\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} book of rhyme}.|
+\capitalisefmtwords{\textbf{a} small book of rhyme}.
+
+\verb|\capitalisefmtwords{\textbf{a 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
+
+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|.)
+
+\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}.
 
-\capitalisewords{a book of rhyme.}
+\begin{verbatim}
+\capitalisefmtwords{\textbf{\emph{a small} book of} rhyme}.
+\end{verbatim}
+\capitalisefmtwords{\textbf{\emph{a small} book of} rhyme}.
 
-\MFUclear
+\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{Title Case (No Formatting)}
+
+\bgroup
+
+\verb|\capitalisewords{the wind in the willows}|
 \capitalisewords{the wind in the willows}
 
-\capitalisewords{a book of rhyme.}
+\verb|\capitalisewords{a small book of rhyme.}|
+\capitalisewords{a small book of rhyme.}
 
-\capitalisewords{a book\space of rhyme.}
+\medskip
 
-\newcommand{\mytitle}{a book\space of rhyme.}
-\capitalisewords{\mytitle}
+\verb|\space| isn't considered a word boundary for
+\verb|\capitalisewords| as shown below:
 
-\xcapitalisewords{\mytitle}
+\begin{verbatim}
+\capitalisewords{a small\space book of rhyme.}
+\end{verbatim}
+\capitalisewords{a small\space book of rhyme.}
 
-Formatting for the entire phrase must go outside
-\verb|\capitalisewords| (unlike \verb|\makefirstuc|). Compare:
+\medskip
+No expansion is performed on the argument of
+\verb|\capitalisewords|:
 
-\capitalisewords{\textbf{a book of rhyme.}}
+\verb|\newcommand{\mytitle}{a small\space book of rhyme.}|
+\newcommand{\mytitle}{a small\space book of rhyme.}
 
-with:
+\verb|\capitalisewords{\mytitle}|
+\capitalisewords{\mytitle}
 
-\textbf{\capitalisewords{a book of rhyme.}}
+\verb|\xcapitalisewords{\mytitle}|
+\xcapitalisewords{\mytitle}
 
+\egroup
 \end{document}