path: root/macros/latex/contrib/mfirstuc/mfirstuc.dtx

%\iffalse
% mfirstuc.dtx generated using makedtx version 1.2 (c) Nicola Talbot
% Command line args:
%   -codetitle "Main Package Code"
%   -author "Nicola Talbot"
%   -macrocode ".*\.perl"
%   -macrocode ".*\.tex"
%   -src "mfirstuc.sty\Z=>mfirstuc.sty"
%   -src "mfirstuc-english.sty\Z=>mfirstuc-english.sty"
%   -src "(sample.*\.tex)\Z=>\1"
%   -src "(.*\.perl)\Z=>\1"
%   -setambles ".*\.perl=>\nopreamble\nopostamble"
%   -setambles ".*\.tex=>\nopreamble\nopostamble"
%   -comment ".*\.perl"
%   -comment ".*\.tex"
%   -doc "mfirstuc-codedoc.tex"
%   mfirstuc
% Created on 2017/11/14 12:21
%\fi
%\iffalse
%<*package>
%% \CharacterTable
%%  {Upper-case    \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z
%%   Lower-case    \a\b\c\d\e\f\g\h\i\j\k\l\m\n\o\p\q\r\s\t\u\v\w\x\y\z
%%   Digits        \0\1\2\3\4\5\6\7\8\9
%%   Exclamation   \!     Double quote  \"     Hash (number) \#
%%   Dollar        \$     Percent       \%     Ampersand     \&
%%   Acute accent  \'     Left paren    \(     Right paren   \)
%%   Asterisk      \*     Plus          \+     Comma         \,
%%   Minus         \-     Point         \.     Solidus       \/
%%   Colon         \:     Semicolon     \;     Less than     \<
%%   Equals        \=     Greater than  \>     Question mark \?
%%   Commercial at \@     Left bracket  \[     Backslash     \\
%%   Right bracket \]     Circumflex    \^     Underscore    \_
%%   Grave accent  \`     Left brace    \{     Vertical bar  \|
%%   Right brace   \}     Tilde         \~}
%</package>
%\fi
% \iffalse
% Doc-Source file to use with LaTeX2e
% Copyright (C) 2017 Nicola Talbot, all rights reserved.
% \fi
% \iffalse
%<*driver>
\documentclass{nlctdoc}

\iffalse
mfirstuc-codedoc.tex is a stub file used by makedtx to create
mfirstuc.dtx
\fi

\usepackage[utf8]{inputenc}
\usepackage[T1]{fontenc}
\usepackage[colorlinks,
            bookmarks,
            hyperindex=false,
            pdfauthor={Nicola L.C. Talbot},
            pdftitle={mfirstuc.sty: Documented code}]{hyperref}

\RecordChanges

\renewcommand*{\main}[1]{\hyperpage{#1}}

\setcounter{IndexColumns}{2}
\setlength\IndexMin{100pt}

\CheckSum{691}

\begin{document}
\DocInput{mfirstuc.dtx}
\end{document}
%</driver>
%\fi
%\MakeShortVerb{"}
%\DeleteShortVerb{\|}
%
% \title{Documented Code For mfirstuc v2.06}
% \author{Nicola L.C. Talbot\\[10pt]
%Dickimaw Books\\
%\url{http://www.dickimaw-books.com/}}
%
% \date{2017-11-14}
% \maketitle
%
%\tableofcontents
%
%\section{Introduction}
%
%This is the documented code for the \styfmt{mfirstuc} package.
%See \texttt{mfirstuc-manual.pdf} for the main user guide.
%
%
%\StopEventually{%
%  \phantomsection
%  \addcontentsline{toc}{section}{Change History}%
%  \raggedright
%  \PrintChanges
%  \PrintIndex
%}
%
%
%
%\section{Main Package Code}
%\iffalse
%    \begin{macrocode}
%<*mfirstuc.sty>
%    \end{macrocode}
%\fi
%\subsection{Mfirstuc Documented Code}
%\label{sec:code:mfirstuc}
%\changes{2.0}{2015/09/09}{package split from glossaries}
%    \begin{macrocode}
\NeedsTeXFormat{LaTeX2e}
\ProvidesPackage{mfirstuc}[2017/11/14 v2.06 (NLCT)]
%    \end{macrocode}
% Requires \sty{etoolbox}:\changes{1.06}{2012/05/21}{now requires
% etoolbox}
%    \begin{macrocode}
\RequirePackage{etoolbox}
%    \end{macrocode}
%\begin{macro}{\makefirstuc}
% Syntax:
%\begin{definition}
% \cs{makefirstuc}\marg{text}
%\end{definition}
% Makes the first letter uppercase, but will
% skip initial control sequences if they are followed by a group
% and make the first thing in the group uppercase, unless the group
% is empty.
% Thus \verb|\makefirstuc{abc}| will produce: Abc, 
% \verb|\makefirstuc{\ae bc}| will produce: \AE bc, but
% \verb|\makefirstuc{\emph{abc}}| will produce \emph{Abc}.
% This is required by \ics{Gls} and \ics{Glspl}.
%\changes{1.08}{2013-11-04}{made robust}
%    \begin{macrocode}
\newif\if@glscs
\newtoks\@glsmfirst
\newtoks\@glsmrest
\newrobustcmd*{\makefirstuc}[1]{%
%    \end{macrocode}
% Check if argument starts with \cs{protect} which needs to be
% skipped.
%\changes{2.01}{2015-12-08}{added check for \cs{protect}}
%    \begin{macrocode}
  \@MFU@p@makefirstuc#1\relax\relax\relax\@end@MFU@protected{#1}%
}
%    \end{macrocode}
%\end{macro}
%
%\begin{macro}{\@MFU@protect}
%\changes{2.03}{2016-07-29}{new}
%    \begin{macrocode}
\newcommand*{\@MFU@protect}{\protect}
%    \end{macrocode}
%\end{macro}
%
%\begin{macro}{\@MFU@p@makefirstuc}
% Internal command to do the required action.
%    \begin{macrocode}
\def\@MFU@p@makefirstuc#1#2#3\@end@MFU@protected#4{%
%    \end{macrocode}
%\changes{2.03}{2016-07-29}{changed test}
%Test if the first argument is \cs{protect}.
%    \begin{macrocode}
  \def\gls@argi{#1}%
  \ifx\gls@argi\@MFU@protect
   \@makefirstuc{#2#3}%
  \else
   \@makefirstuc{#4}%
  \fi
}
%    \end{macrocode}
%\end{macro}
%
%\begin{macro}{\@makefirstuc}
% Internal command to do the required action.
%    \begin{macrocode}
\newcommand*{\@makefirstuc}[1]{%
  \def\gls@argi{#1}%
  \ifx\gls@argi\@empty
%    \end{macrocode}
% If the argument is empty, do nothing.
%    \begin{macrocode}
  \else
%    \end{macrocode}
%\changes{1.03}{2008/12/22}{changed \cs{protected@edef} to \cs{def}}
%    \begin{macrocode}
    \def\@gls@tmp{\ #1}%
    \@onelevel@sanitize\@gls@tmp
    \expandafter\@gls@checkcs\@gls@tmp\relax\relax
    \if@glscs
%    \end{macrocode}
% Check if we have two sequential control sequences.
%\changes{2.0}{2015/09/09}{added check for two control sequences}
%    \begin{macrocode}
     \expandafter\def\expandafter\@gls@tmp\expandafter{\expandafter
       \ \@gobble #1}%
     \@onelevel@sanitize\@gls@tmp
     \expandafter\@gls@checkcs\@gls@tmp\relax\relax
     \if@glscs\@glscsfalse\else\@glscstrue\fi
    \fi
    \if@glscs
      \@gls@getbody #1{}\@nil
      \ifx\@gls@rest\@empty
        \glsmakefirstuc{#1}%
      \else
        \expandafter\@gls@split\@gls@rest\@nil
        \ifx\@gls@first\@empty
           \glsmakefirstuc{#1}%
        \else
%    \end{macrocode}
%\changes{2.06}{2017-11-14}{check for inner control sequence}
%Does \cs{@gls@first} start with a control sequence?
%    \begin{macrocode}
           \edef\@gls@tmp\expandafter{\noexpand\ \expandonce\@gls@first}%
           \@onelevel@sanitize\@gls@tmp
           \expandafter\@gls@checkcs\@gls@tmp\relax\relax
           \if@glscs
             \edef\@gls@domfirstuc{\expandonce\@gls@body
              {\noexpand\makefirstuc{\expandonce\@gls@first
               \expandonce\@gls@rest}%
              }%
             }%
           \else
             \expandafter\@glsmfirst\expandafter{\@gls@first}%
             \expandafter\@glsmrest\expandafter{\@gls@rest}%
%    \end{macrocode}
%\changes{2.06}{2017-11-14}{added braces to \cs{glsmakefirstuc} argument}
%    \begin{macrocode}
             \edef\@gls@domfirstuc{\noexpand\@gls@body
               {\noexpand\glsmakefirstuc{\the\@glsmfirst}}%
               \the\@glsmrest}%
           \fi
           \@gls@domfirstuc
        \fi
      \fi
    \else
      \glsmakefirstuc{#1}%
    \fi
  \fi
}
%    \end{macrocode}
%\end{macro}
%\begin{macro}{\@gls@split}
% Put first argument in \cs{@gls@first} and second argument in
% \cs{@gls@rest}:
%\changes{2.03}{2016-07-29}{added check for datatool-base UTF-8 support}
%    \begin{macrocode}
\ifdef\dtl@getfirst@UTFviii
{%
  \def\@gls@split#1#2\@nil{%
   \ifbool{@dtl@utf8}
    {%
      \expandafter\dtl@if@two@octets#1#2\relax\dtl@end@if@two@octets
      {%
        \dtl@getfirst@UTFviii#1#2\@nil\end@dtl@getfirst@UTFviii
        \let\@gls@first\dtl@first
        \let\@gls@rest\dtl@rest
      }%
      {%
        \def\@gls@first{#1}\def\@gls@rest{#2}%
      }%
    }%
    {%
%    \end{macrocode}
%\changes{2.04}{2016-07-31}{added missing false part}
%    \begin{macrocode}
      \def\@gls@first{#1}\def\@gls@rest{#2}%
    }%
  }
}%
{%
  \def\@gls@split#1#2\@nil{%
    \def\@gls@first{#1}\def\@gls@rest{#2}%
  }
}
%    \end{macrocode}
%\end{macro}
%    \begin{macrocode}
\def\@gls@checkcs#1 #2#3\relax{%
  \def\@gls@argi{#1}\def\@gls@argii{#2}%
  \ifx\@gls@argi\@gls@argii
    \@glscstrue
  \else
    \@glscsfalse
  \fi
}
%    \end{macrocode}
% Has \sty{datatool-base} v2.24 (or above) been loaded? If so and we
% have UTF-8 enabled, we can grab the first octet.
%\begin{macro}{\@mfu@applytofirst}
%\changes{2.03}{2016-07-29}{new}
%    \begin{macrocode}
\ifdef\dtl@getfirst@UTFviii
{%
  \def\@mfu@applytofirst#1#2\@mfu@end@applytofirst#3{%
    \expandafter\dtl@if@two@octets#1#2\relax\dtl@end@if@two@octets
    {%
       \dtl@getfirst@UTFviii#1#2\@nil\end@dtl@getfirst@UTFviii
       \expandafter#3\expandafter{\dtl@first}\dtl@rest
    }%
    {%
%    \end{macrocode}
%First argument needs to be grouped in case it consists of more than
%one token.
%\changes{2.05}{2017-11-10}{grouped first argument}
%    \begin{macrocode}
      #3{#1}#2%
    }%
  }%
}%
{%
%    \end{macrocode}
%First argument needs to be grouped in case it consists of more than
%one token.
%\changes{2.05}{2017-11-10}{grouped first argument}
%    \begin{macrocode}
  \def\@mfu@applytofirst#1#2\@mfu@end@applytofirst#3{#3{#1}#2}
}
%    \end{macrocode}
%\end{macro}
%
%\begin{macro}{\MFUapplytofirst}
%\changes{2.03}{2016-07-29}{new}
%\begin{definition}
%\cs{MFUapplytofirst}\marg{cs}\marg{text}
%\end{definition}
% Apply \meta{cs} to first token of text, or first UTF-8 character
% if \sty{datatool-base} v2.24 above has been loaded with the utf8
% support enabled.
%    \begin{macrocode}
\ifdef\dtl@getfirst@UTFviii
{%
  \newcommand*{\MFUapplytofirst}[2]{%
    \ifbool{@dtl@utf8}
    {%
       \ifblank{#2}%
       {#1{#2}}%
       {%
         \ifblank{#1}%
         {#1#2}%
         {%
           \@mfu@applytofirst#2\@mfu@end@applytofirst#1\relax
         }%
       }%
    }%
    {%
      #1#2%
    }%
  }
}%
{%
  \newcommand*{\MFUapplytofirst}[2]{#1#2}
}
%    \end{macrocode}
%\end{macro}
%
%\begin{macro}{\@gls@makefirstuc}
% Make first thing upper case:
%    \begin{macrocode}
\def\@gls@makefirstuc#1{\MFUapplytofirst\mfirstucMakeUppercase{#1}}
%    \end{macrocode}
%\end{macro}
%
%\begin{macro}{\mfirstucMakeUppercase}
% Allow user to replace \cs{MakeUppercase} with another case
% changing command.
%    \begin{macrocode}
\newcommand*{\mfirstucMakeUppercase}{\MakeUppercase}
%    \end{macrocode}
%\end{macro}
%\begin{macro}{\glsmakefirstuc}
%\changes{1.05}{2011/04/02}{new}
% Provide a user command to make it easier to customise.
%    \begin{macrocode}
\newcommand*{\glsmakefirstuc}[1]{\@gls@makefirstuc{#1}}
%    \end{macrocode}
%\end{macro}
%
% Get the first grouped argument and store in \cs{@gls@body}.
%    \begin{macrocode}
\def\@gls@getbody#1#{\def\@gls@body{#1}\@gls@gobbletonil}
%    \end{macrocode}
% Scoup up everything to \cs{@nil} and store in \cs{@gls@rest}:
%    \begin{macrocode}
\def\@gls@gobbletonil#1\@nil{\def\@gls@rest{#1}}
%    \end{macrocode}
%
%\begin{macro}{\xmakefirstuc}
% Expand argument once before applying \cs{makefirstuc}
% (added v1.01).
%    \begin{macrocode}
\newcommand*{\xmakefirstuc}[1]{%
  \expandafter\makefirstuc\expandafter{#1}%
}
%    \end{macrocode}
%\end{macro}
%
%\begin{macro}{\emakefirstuc}
%\changes{1.10}{2015/05/03}{new}
% Fully expand argument before applying \cs{makefirstuc}
%    \begin{macrocode}
\newrobustcmd*{\emakefirstuc}[1]{%
  \protected@edef\@MFU@caparg{#1}%
  \expandafter\makefirstuc\expandafter{\@MFU@caparg}%
}
%    \end{macrocode}
%\end{macro}
%
%\begin{macro}{\capitalisewords}
%\changes{1.06}{2012/05/21}{new}
% Capitalise each word in the argument. Words are considered to be
% separated by plain spaces (i.e.\ non-breakable spaces won't be
% considered a word break).
%\changes{1.08}{2013-11-04}{made robust}
%\changes{1.09}{2017-07-30}{added check for words that shouldn't be
%capitalised}
%    \begin{macrocode}
\newrobustcmd*{\capitalisewords}[1]{%
  \let\@mfu@checkword\@gobble
  \def\gls@add@space{}%
  \let\@mfu@domakefirstuc\MFUcapword
  \mfu@capitalisewords#1 \@nil\mfu@endcap
}
%    \end{macrocode}
%\end{macro}
%
%\begin{macro}{\@mfu@mid@capitalisewords}
%\changes{2.03}{2016-07-29}{new}
%\cs{@mfu@checkword} needs to be set before use.
%    \begin{macrocode}
\newcommand*{\@mfu@mid@capitalisewords}[1]{%
  \def\gls@add@space{}%
  \let\@mfu@domakefirstuc\MFUcapword
  \mfu@capitalisewords#1 \@nil\mfu@endcap
}
%    \end{macrocode}
%\end{macro}
%
%    \begin{macrocode}
\def\mfu@capitalisewords#1 #2\mfu@endcap{%
  \def\mfu@cap@first{#1}%
  \def\mfu@cap@second{#2}%
  \gls@add@space
  \@mfu@checkword{#1}%
  \@mfu@domakefirstuc{#1}%
  \def\gls@add@space{ }%
  \ifx\mfu@cap@second\@nnil
    \let\next@mfu@cap\mfu@noop
  \else
    \let\next@mfu@cap\mfu@capitalisewords
    \let\@mfu@checkword\mfu@checkword
  \fi
  \next@mfu@cap#2\mfu@endcap
}
\def\mfu@noop#1\mfu@endcap{}
%    \end{macrocode}
%
%\begin{macro}{\ifMFUhyphen}
%\changes{2.03}{2016-07-29}{new}
%Split on hyphens.
%    \begin{macrocode}
\newif\ifMFUhyphen
\MFUhyphenfalse
%    \end{macrocode}
%\end{macro}
%
%\begin{macro}{\MFUcapword}
%\changes{2.03}{2016-07-29}{new}
%    \begin{macrocode}
\newcommand*{\MFUcapword}[1]{%
  \ifMFUhyphen
   \@MFUcapword#1-\@nil\@endMFUcapword
  \else
    \makefirstuc{#1}%
  \fi
}
%    \end{macrocode}
%\end{macro}
%
%\begin{macro}{\@MFUcapword}
%\changes{2.03}{2016-07-29}{new}
%    \begin{macrocode}
\def\@MFUcapword#1-#2\@endMFUcapword{%
  \makefirstuc{#1}%
  \def\@mfu@argii{#2}%
  \ifx\@mfu@argii\@nnil
  \else
    -\@MFUcapword#2\@endMFUcapword
  \fi
}
%    \end{macrocode}
%\end{macro}
%
%\begin{macro}{\mfu@checkword}
% Check if word should be capitalised.
% This originally used \sty{etoolbox}'s \ics{ifinlist} command
% but this doesn't work if the word contains grouping.
%\changes{1.09}{2017-07-30}{new}
%\changes{2.02}{2015-12-17}{modified to use loop instead of \cs{ifinlist}}
%    \begin{macrocode}
\newcommand*\mfu@checkword[1]{%
  \def\mfu@checkword@arg{#1}%
  \let\@mfu@domakefirstuc\MFUcapword
  \forlistloop\mfu@checkword@do\@mfu@nocaplist
}
%    \end{macrocode}
%\end{macro}
%
%\begin{macro}{\mfu@checkword@do}
% Handler for loop used by \cs{mfu@checkword}
%\changes{2.02}{2015-12-17}{new}
%    \begin{macrocode}
\newcommand*{\mfu@checkword@do}[1]{%
  \def\mfu@checkword@argii{#1}%
  \ifdefequal\mfu@checkword@arg\mfu@checkword@argii
  {%
    \let\@mfu@domakefirstuc\@firstofone
    \listbreak
  }%
  {%
%    \end{macrocode}
%Need to check if \cs{@mfu@terminator} has been tacked onto the end.
%    \begin{macrocode}
    \def\mfu@checkword@argii{#1{\@mfu@terminator}}%
    \ifdefequal\mfu@checkword@arg\mfu@checkword@argii
    {%
      \let\@mfu@domakefirstuc\@firstofone
      \listbreak
    }%
    {}%
  }%
}
%    \end{macrocode}
%\end{macro}
%
%\begin{macro}{\@mfu@nocaplist}
% List of words that shouldn't be capitalised.
%\changes{1.09}{2017-07-30}{new}
%    \begin{macrocode}
\newcommand*{\@mfu@nocaplist}{}
%    \end{macrocode}
%\end{macro}
%
%\begin{macro}{\MFUnocap}
% Provide the user with a means to add a word to the list.
% (No expansion performed on the argument.)
%    \begin{macrocode}
\newcommand*{\MFUnocap}[1]{\listadd{\@mfu@nocaplist}{#1}}
%    \end{macrocode}
%\end{macro}
%\begin{macro}{\gMFUnocap}
% Global version.
%\changes{1.09}{2017-07-30}{new}
%    \begin{macrocode}
\newcommand*{\gMFUnocap}[1]{\listgadd{\@mfu@nocaplist}{#1}}
%    \end{macrocode}
%\end{macro}
%
%\begin{macro}{\MFUclear}
% Clear the list
%\changes{1.09}{2017-07-30}{new}
%    \begin{macrocode}
\newcommand*{\MFUclear}{\renewcommand*{\@mfu@nocaplist}{}}
%    \end{macrocode}
%\end{macro}
%
%\begin{macro}{\xcapitalisewords}
%\changes{1.06}{2012/05/21}{new}
% Short-cut command:
%    \begin{macrocode}
\newcommand*{\xcapitalisewords}[1]{%
  \expandafter\capitalisewords\expandafter{#1}%
}
%    \end{macrocode}
%\end{macro}
%
%\begin{macro}{\ecapitalisewords}
%\changes{1.10}{2015/05/03}{new}
% Fully expand argument before applying \cs{capitalisewords}
%    \begin{macrocode}
\newrobustcmd*{\ecapitalisewords}[1]{%
  \protected@edef\@MFU@caparg{#1}%
  \expandafter\capitalisewords\expandafter{\@MFU@caparg}%
}
%    \end{macrocode}
%\end{macro}
%
%\begin{macro}{\@mfu@nil}
%    \begin{macrocode}
\newcommand\@mfu@nil{\unskip}
%    \end{macrocode}
%\end{macro}
%
%\begin{macro}{\@mfu@nnil}
%    \begin{macrocode}
\newcommand*\@mfu@nnil{\@mfu@nil}
%    \end{macrocode}
%\end{macro}
%
%\begin{macro}{\capitalisefmtwords}
%\changes{2.03}{2016-07-29}{new}
%Like \cs{capitalisewords} but assumes that the phrase contains
%formatting text-block commands.
%    \begin{macrocode}
\newcommand*{\capitalisefmtwords}{%
  \@ifstar\@s@capitalisefmtwords\@ns@capitalisefmtwords
}
%    \end{macrocode}
%\end{macro}
%
%\begin{macro}{\@s@capitalisefmtwords}
%\changes{2.04}{2016-07-31}{new}
% Starred form.
%    \begin{macrocode}
\newcommand*{\@s@capitalisefmtwords}[1]{%
  \@@s@checkgrp@@capitalisefmtwords#1\@nil
}
%    \end{macrocode}
%\end{macro}
%
%\begin{macro}{\@@s@checkgrp@capitalisefmtwords}
%\changes{2.04}{2016-07-31}{new}
%    \begin{macrocode}
\newcommand*{\@@s@checkgrp@@capitalisefmtwords}{%
  \@ifnextchar\bgroup{\@@s@nocs@capitalisefmtwords}{\@@s@capitalisefmtwords}%
}
%    \end{macrocode}
%\end{macro}
%
%\begin{macro}{\@@s@nocs@capitalisefmtwords}
%\changes{2.04}{2016-07-31}{new}
%Argument starts with a group.
%    \begin{macrocode}
\def\@@s@nocs@capitalisefmtwords#1\@nil{%
  \capitalisewords{#1}%
}
%    \end{macrocode}
%\end{macro}
%
%\begin{macro}{\@@s@capitalisefmtwords}
%\changes{2.04}{2016-07-31}{new}
%    \begin{macrocode}
\newcommand*{\@@s@capitalisefmtwords}[1]{%
  \def\gls@argi{#1}%
  \ifx\gls@argi\@MFU@protect
%    \end{macrocode}
%Skip \cs{protect}
%    \begin{macrocode}
    \let\@mfu@capfmtwordsnext\@@s@capitalisefmtwords
  \else
    \ifx\gls@argi\@nnil
%    \end{macrocode}
%Nothing to do.
%    \begin{macrocode}
      \let\@mfu@capfmtwordsnext\relax
    \else
      \def\@gls@tmp{\ #1}%
      \@onelevel@sanitize\@gls@tmp
      \expandafter\@gls@checkcs\@gls@tmp\relax\relax
      \if@glscs
        \def\@mfu@capfmtwordsnext{\@@s@cs@capitalisefmtwords#1}%
      \else
        \def\@mfu@capfmtwordsnext{\@@s@nocs@capitalisefmtwords#1}%
      \fi
    \fi
  \fi
  \@mfu@capfmtwordsnext
}
%    \end{macrocode}
%\end{macro}
%
%\begin{macro}{\@@s@cs@capitalisefmtwords}
%\changes{2.04}{2016-07-31}{new}
%    \begin{macrocode}
\newcommand*{\@@s@cs@capitalisefmtwords}[1]{%
  \@ifnextchar\bgroup
   {\@@s@cs@g@capitalisefmtwords#1}%
   {\@@s@cs@ng@capitalisefmtwords#1}%
}
%    \end{macrocode}
%\end{macro}
%
%\begin{macro}{\@@s@cs@g@capitalisefmtwords}
%\changes{2.04}{2016-07-31}{new}
%    \begin{macrocode}
\def\@@s@cs@g@capitalisefmtwords#1#2#3\@nil{%
  #1{\capitalisewords{#2}}%
  \ifblank{#3}%
  {}%
  {%
    \def\gls@add@space{}%
    \let\@mfu@checkword\mfu@checkword
    \mfu@capitalisewords#3 \@nil\mfu@endcap
  }%
}
%    \end{macrocode}
%\end{macro}
%
%\begin{macro}{\@@s@cs@ng@capitalisefmtwords}
%\changes{2.04}{2016-07-31}{new}
%    \begin{macrocode}
\def\@@s@cs@ng@capitalisefmtwords#1#2\@nil{%
  \capitalisewords{#1#2}%
}
%    \end{macrocode}
%\end{macro}
%
%\begin{macro}{\@ns@capitalisefmtwords}
%\changes{2.04}{2016-07-31}{new}
% Unstarred form.
%    \begin{macrocode}
\newcommand*{\@ns@capitalisefmtwords}[1]{%
  \let\@mfu@checkword\@gobble
  \def\gls@add@space{}%
  \@capitalisefmtwords#1 \@mfu@nil{} \unskip
}
%    \end{macrocode}
%\end{macro}
%\begin{macro}{\@capitalisefmtwords}
%\changes{2.03}{2016-07-29}{new}
%Take care of group at the start of the word.
%    \begin{macrocode}
\newcommand*{\@capitalisefmtwords}{%
  \@ifnextchar\bgroup{\@capitalise@g@fmtwords}{\@capitalise@ng@fmtwords}%
}
\newcommand*{\@capitalise@g@fmtwords}[1]{%
  \@capitalise@ng@fmtwords{{#1}}%
}
\def\@mfu@ifnil#1#2\@mfu@end@nil#3#4{%
  \def\gls@argi{#1}%
  \ifx\gls@argi\@mfu@nnil
    #3%
  \else
    #4%
  \fi
}
\def\@capitalise@ng@fmtwords#1 {%
  \@mfu@ifnil#1\relax\relax\@mfu@end@nil
  {%
    \def\@mfu@capfmtwordsnext{#1}%
  }%
  {%
    \def\@mfu@capfmtwordsnext{%
       \@capitalise@fmtwords#1\@mfu@nil
       \def\gls@add@space{ }%
       \let\@mfu@checkword\mfu@checkword
       \@@cap@nofmtphrase}%
  }%
  \@mfu@capfmtwordsnext
}%
%    \end{macrocode}
%\end{macro}
%\begin{macro}{\@capitalise@fmtwords}
%\changes{2.03}{2016-07-29}{new}
%    \begin{macrocode}
\def\@capitalise@fmtwords#1{%
  \@mfu@ifnil#1\relax\relax\@mfu@end@nil
  {%
%    \end{macrocode}
%Do nothing.
%    \begin{macrocode}
    \def\@mfu@capfmtwordsnext{#1}%
  }%
  {%
    \def\gls@argi{#1}%
    \ifx\gls@argi\@MFU@protect
%    \end{macrocode}
%Skip \cs{protect}
%    \begin{macrocode}
      \def\@mfu@capfmtwordsnext{\@capitalise@fmtwords}%
    \else
      \def\@gls@tmp{\ #1}%
      \@onelevel@sanitize\@gls@tmp
      \expandafter\@gls@checkcs\@gls@tmp\relax\relax
      \if@glscs
       \def\@mfu@capfmtwordsnext{\@@capitalisefmtwords#1}%
      \else
       \ifx\gls@argi\@empty
         \def\@mfu@capfmtwordsnext{\@@capnofmtphrase{}}%
       \else
         \def\@mfu@capfmtwordsnext{\@@capnofmtphrase#1}%
       \fi
      \fi
    \fi
  }%
  \@mfu@capfmtwordsnext
}
%    \end{macrocode}
%\end{macro}
%
%\begin{macro}{\@@capitalisefmtwords}
%\changes{2.03}{2016-07-29}{new}
%Check for a group following argument.
%    \begin{macrocode}
\def\@@capitalisefmtwords#1{%
  \@ifnextchar\bgroup{\@@capfmtsubphrase#1}{\@@capnofmtphrase#1}%
}
%    \end{macrocode}
%\end{macro}
%
%\begin{macro}{\@@capnofmtphrase}
%\changes{2.03}{2016-07-29}{new}
%    \begin{macrocode}
\def\@@capnofmtphrase{%
  \@ifnextchar\bgroup{\@@cap@g@nofmtphrase}{\@@cap@ng@nofmtphrase}%
}
%    \end{macrocode}
%\end{macro}
%\begin{macro}{\@@cap@ng@nofmtphrase}
%\changes{2.04}{2016-07-31}{new}
%    \begin{macrocode}
\def\@@cap@ng@nofmtphrase#1\@mfu@nil{%
  \gls@add@space
  \@mfu@mid@capitalisewords{#1}%
  \def\gls@add@space{ }%
}
%    \end{macrocode}
%\end{macro}
%\begin{macro}{\@@cap@g@nofmtphrase}
%\changes{2.04}{2016-07-31}{new}
%    \begin{macrocode}
\def\@@cap@g@nofmtphrase#1{%
  \@@cap@ng@nofmtphrase{{#1}}%
}
%    \end{macrocode}
%\end{macro}
%
%\begin{macro}{\@mfu@terminator}
%\changes{2.04}{2016-07-31}{new}
%    \begin{macrocode}
\newcommand*\@mfu@terminator{\hbox{}}
%    \end{macrocode}
%\end{macro}
%
%\begin{macro}{\@@capfmtsubphrase}
%\changes{2.03}{2016-07-29}{new}
%    \begin{macrocode}
\def\@@capfmtsubphrase#1#2#3{%
%    \end{macrocode}
%Protect any trailing space at the end of the second argument.
%    \begin{macrocode}
  #1{\@capitalisefmtwords#2{\@mfu@terminator} \@mfu@nil{} \unskip}%
  \def\gls@add@space{ }%
  \let\@mfu@checkword\mfu@checkword
  \@mfu@ifnil#1\relax\relax\@mfu@end@nil
  {\let\@mfu@fmtsubphrasenext\relax}%
  {\def\@mfu@fmtsubphrasenext{#3}}%
  \@mfu@fmtsubphrasenext
}
%    \end{macrocode}
%\end{macro}
%
%\begin{macro}{\@@cap@nofmtphrase}
%\changes{2.03}{2016-07-29}{new}
%    \begin{macrocode}
\def\@@cap@nofmtphrase#1 {%
  \@mfu@ifnil#1\relax\relax\@mfu@end@nil
  {%
    \def\@mfu@capnofmtwordsnext{#1 }%
  }%
  {%
    \def\@mfu@capnofmtwordsnext{%
      \@capitalisefmtwords#1 \@mfu@nil{} \unskip
      \def\gls@add@space{ }%
      \let\@mfu@checkword\mfu@checkword
      \@capitalisefmtwords
    }%
  }%
  \@mfu@capnofmtwordsnext
}
%    \end{macrocode}
%\end{macro}
%
%\begin{macro}{\xcapitalisefmtwords}
%\changes{2.03}{2016-07-29}{new}
% Short-cut command:
%    \begin{macrocode}
\newcommand*{\xcapitalisefmtwords}{%
  \@ifstar\@s@xcapitalisefmtwords\@ns@xcapitalisefmtwords
}
%    \end{macrocode}
%\end{macro}
%\begin{macro}{\@s@xcapitalisefmtwords}
%\changes{2.04}{2016-07-31}{new}
% Starred version
%    \begin{macrocode}
\newcommand*{\@s@xcapitalisefmtwords}[1]{%
  \expandafter\@s@capitalisefmtwords\expandafter{#1}%
}
%    \end{macrocode}
%\end{macro}
%
%\begin{macro}{\@ns@xcapitalisefmtwords}
%\changes{2.04}{2016-07-31}{new}
% Unstarred version
%    \begin{macrocode}
\newcommand*{\@ns@xcapitalisefmtwords}[1]{%
  \expandafter\@ns@capitalisefmtwords\expandafter{#1}%
}
%    \end{macrocode}
%\end{macro}
%
%\begin{macro}{\ecapitalisefmtwords}
%\changes{2.03}{2016-07-29}{new}
%    \begin{macrocode}
\newrobustcmd*{\ecapitalisefmtwords}{%
  \@ifstar\@s@ecapitalisefmtwords\@ns@ecapitalisefmtwords
}
%    \end{macrocode}
%\end{macro}
%\begin{macro}{\@s@ecapitalisefmtwords}
%\changes{2.04}{2016-07-31}{new}
%Starred version
%    \begin{macrocode}
\newcommand*{\@s@ecapitalisefmtwords}[1]{%
  \protected@edef\@MFU@caparg{#1}%
  \expandafter\@s@capitalisefmtwords\expandafter{\@MFU@caparg}%
}
%    \end{macrocode}
%\end{macro}
%
%\begin{macro}{\@ns@ecapitalisefmtwords}
%\changes{2.04}{2016-07-31}{new}
%Unstarred version
%    \begin{macrocode}
\newcommand*{\@ns@ecapitalisefmtwords}[1]{%
  \protected@edef\@MFU@caparg{#1}%
  \expandafter\@ns@capitalisefmtwords\expandafter{\@MFU@caparg}%
}
%    \end{macrocode}
%\end{macro}
%\iffalse
%    \begin{macrocode}
%</mfirstuc.sty>
%    \end{macrocode}
%\fi
%\iffalse
%    \begin{macrocode}
%<*mfirstuc-english.sty>
%    \end{macrocode}
%\fi
%\subsection{Mfirstuc-english Documented Code}
%\label{sec:code:mfirstuc-english}
%    \begin{macrocode}
\NeedsTeXFormat{LaTeX2e}
\ProvidesPackage{mfirstuc-english}[2017/11/14 v2.06 (NLCT)]
%    \end{macrocode}
% Load \sty{mfirstuc} if not already loaded:
%    \begin{macrocode}
\RequirePackage{mfirstuc}
%    \end{macrocode}
% Add no-cap words. This list isn't complete. I~don't intend adding
% disputed words. Additional words can be added to the document in
% a~similar manner.
%    \begin{macrocode}
\MFUnocap{a}
\MFUnocap{an}
\MFUnocap{and}
\MFUnocap{but}
\MFUnocap{for}
\MFUnocap{in}
\MFUnocap{of}
\MFUnocap{or}
\MFUnocap{no}
\MFUnocap{nor}
\MFUnocap{so}
\MFUnocap{some}
\MFUnocap{the}
\MFUnocap{with}
\MFUnocap{yet}
%    \end{macrocode}
%\iffalse
%    \begin{macrocode}
%</mfirstuc-english.sty>
%    \end{macrocode}
%\fi
%\iffalse
%    \begin{macrocode}
%<*sample-mfirstuc.tex>
%    \end{macrocode}
%\fi
%\iffalse
%    \begin{macrocode}
 % 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}.

% I know \textbf is robust already and doesn't need protecting.
% This is just to test what happens if the argument starts
% with \protect
\newcommand*{\mytext}{\protect\textbf{some text}}
Protected formatting: \xmakefirstuc{\mytext}.

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

\section{Title Case (No Formatting Commands)}

\bgroup
%Clearing ``nocap'' words.
%\verb|\MFUclear|
%\MFUclear
%(localised by group)

\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}
%    \end{macrocode}
%\fi
%\iffalse
%    \begin{macrocode}
%</sample-mfirstuc.tex>
%    \end{macrocode}
%\fi
%\iffalse
%    \begin{macrocode}
%<*mfirstuc.perl>
%    \end{macrocode}
%\fi
%\iffalse
%    \begin{macrocode}
# File        : mfirstuc.perl
# Author      : Nicola L. C. Talbot
# Date        : 2012-09-21
# Version     : 1.0
# Description : LaTeX2HTML (limited!) implementation of mfirstuc package

# This is a LaTeX2HTML style implementing the mfirstuc package, and
# is distributed as part of the glossaries package.
# Copyright 2007 Nicola L.C. Talbot
# This work may be distributed and/or modified under the
# conditions of the LaTeX Project Public License, either version 1.3
# of this license of (at your option) any later version.
# The latest version of this license is in
#   http://www.latex-project.org/lppl.txt
# and version 1.3 or later is part of all distributions of LaTeX
# version 2005/12/01 or later.
#
# This work has the LPPL maintenance status `maintained'.
#
# The Current Maintainer of this work is Nicola Talbot.

use warnings;

package main;

sub do_cmd_makefirstuc{
   local($_) = @_;

   local($id,$text);

   $text = &missing_braces unless
      s/$next_pair_pr_rx/$id=$1;$text=$2;''/eo;

   &translate_commands("\\glsmakefirstuc $text") . $_;
}

sub do_cmd_xmakefirstuc{
   local($_) = @_;

   local($id,$text);
  
   $text = &missing_braces unless
      s/$next_pair_pr_rx/$id=$1;$text=$2;''/eo;

   unless ($id)
   {
      $id = ++$global{'max_id'};
   }
   
   &translate_commands("\\expandafter \\makefirstuc $OP$id$CP$text$OP$id$CP")
   . $_;
}

sub do_cmd_glsmakefirstuc{
   local($_) = @_;

   local($id,$text);

   $text = &get_next_object unless
      s/$next_pair_pr_rx/$id=$1;$text=$2;''/eo;

   &do_real_makefirstuc($text).$_;
}

sub do_real_makefirstuc{
   local($text) = @_;

   if ($text=~/^((?:\s*<[^>]+>\s*)+)(.*)/)
   {
      $text = $1 . ucfirst($2);
   }
   else
   {
      $text = ucfirst($text);
   }

   $text;
}

sub do_cmd_capitalisewords{
   local($_) = @_;

   local($id,$text);

   $text = &missing_braces unless
      s/$next_pair_pr_rx/$id=$1;$text=$2;''/eo;

   local($newtext) = '';

   foreach my $word (split ' ', $text)
   {
      $id = ++$global{'max_id'};

      $word = &translate_commands("\\makefirstuc $OP$id$CP$word$OP$id$CP");

      if ($newtext)
      {
         $newtext .= ' ' . $word;
      }
      else
      {
         $newtext = $word;
      }
   }

   $newtext.$_;
}

sub get_next_object{
    local($next, $revert, $thisline);
    local($this_cmd) = $cmd;
    $this_cmd =~ s/^\\// unless ($cmd eq "\\");
    if (/^[\s%]*([^\n]*)\n/ ) {
        $thisline = &revert_to_raw_tex($1)
    } else {
        $thisline = &revert_to_raw_tex($_);
    }
    s/^\s*//;
    if ($_ =~ s/$next_token_rx//) { $next = $& };
    $next =~ s/$comment_mark(\d+\n?)?//g;
    if ($next =~ /^\\(\W|\d|[a-zA-z]*\b)/) {
        $revert = $next = "\\".$1;
    } elsif ($next =~ /\W/) {
        $revert = &revert_to_raw_tex($next);
    } else { $revert = $next };
    $next;
}

1;
%    \end{macrocode}
%\fi
%\iffalse
%    \begin{macrocode}
%</mfirstuc.perl>
%    \end{macrocode}
%\fi
%\Finale
\endinput