summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/glossaries/mfirstuc-manual.tex
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/doc/latex/glossaries/mfirstuc-manual.tex')
-rw-r--r--Master/texmf-dist/doc/latex/glossaries/mfirstuc-manual.tex106
1 files changed, 104 insertions, 2 deletions
diff --git a/Master/texmf-dist/doc/latex/glossaries/mfirstuc-manual.tex b/Master/texmf-dist/doc/latex/glossaries/mfirstuc-manual.tex
index 7ce8cb0a6c8..84d09ecc7d1 100644
--- a/Master/texmf-dist/doc/latex/glossaries/mfirstuc-manual.tex
+++ b/Master/texmf-dist/doc/latex/glossaries/mfirstuc-manual.tex
@@ -5,7 +5,11 @@
\usepackage{pifont}
\usepackage[utf8]{inputenc}
\ifpdf
-\usepackage[T1]{fontenc}
+ \usepackage[T1]{fontenc}
+ \usepackage{metalogo}
+\else
+ \providecommand{\XeLaTeX}{XeLaTeX}
+ \providecommand{\XeTeX}{XeTeX}
\fi
\usepackage{cmap}
\usepackage[colorlinks,
@@ -24,6 +28,10 @@ Dickimaw Books\\
\date{2014-07-30}
\maketitle
+ \tableofcontents
+
+ \section{Introduction}
+ \label{sec:intro}
The \styfmt{glossaries} bundle includes the package
\sty{mfirstuc} which provides the command:
@@ -66,7 +74,8 @@ therefore first object is |\em| and so is equivalent to
\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) due to expansion issues.
+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
@@ -123,6 +132,9 @@ For example:
Remember to also load \sty{textcase} (\styfmt{glossaries} loads this
automatically).
+\section{Capitalise 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}
@@ -264,4 +276,94 @@ 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.
+\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 \verb|\FirstUC{abc}| is equivalent to \verb|\MakeUppercase abc|
+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 \verb|\MakeUppercase |\meta{stuff} works,
+then \verb|\makefirstuc|\marg{stuff} should also work and so should
+\verb|\makefirstuc{\foo|\marg{stuff}\verb|}|, but if
+\verb|\MakeUppercase |\meta{stuff} doesn't work, then neither will
+\verb|\makefirstuc|\marg{stuff}
+(or \verb|\makefirstuc{\foo|\marg{stuff}\verb|}|).
+
+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}.
+
\end{document}