summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/mfirstuc/mfirstuc-manual.tex
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/doc/latex/mfirstuc/mfirstuc-manual.tex')
-rw-r--r--Master/texmf-dist/doc/latex/mfirstuc/mfirstuc-manual.tex294
1 files changed, 268 insertions, 26 deletions
diff --git a/Master/texmf-dist/doc/latex/mfirstuc/mfirstuc-manual.tex b/Master/texmf-dist/doc/latex/mfirstuc/mfirstuc-manual.tex
index 8dc9701bfa9..26c3ce9149d 100644
--- a/Master/texmf-dist/doc/latex/mfirstuc/mfirstuc-manual.tex
+++ b/Master/texmf-dist/doc/latex/mfirstuc/mfirstuc-manual.tex
@@ -1,5 +1,6 @@
\documentclass{nlctdoc}
+\usepackage[a4paper,left=1.75in]{geometry}
\usepackage{alltt}
\usepackage{mfirstuc}
\usepackage{pifont}
@@ -19,14 +20,19 @@
pdftitle={mfirstuc.sty: uppercasing first letter},
pdfkeywords={LaTeX,package,uppercase}]{hyperref}
+\IndexPrologue{%
+\section*{\indexname}\markright{\indexname}
+\addcontentsline{toc}{section}{\indexname}}
+
\begin{document}
- \title{mfirstuc.sty v2.02:
+\MakeShortVerb{|}
+ \title{mfirstuc.sty v2.03:
uppercasing first letter}
\author{Nicola L.C. Talbot\\[10pt]
Dickimaw Books\\
\url{http://www.dickimaw-books.com/}}
- \date{2015-12-17}
+ \date{2016-07-29}
\maketitle
\tableofcontents
@@ -39,7 +45,61 @@ as the commands provided by \styfmt{mfirstuc} may be used without
\styfmt{glossaries}, the two have been split into separately
maintained packages.
-\section{Capitalising a Word}
+\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\
@@ -65,7 +125,7 @@ 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|\color{red}{text}|
+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}
@@ -179,7 +239,7 @@ For example:
Remember to also load \sty{textcase} (\styfmt{glossaries} loads this
automatically).
-\section{Capitalise Each Word in a Phrase or Sentence (Title Case)}
+\section{Capitalise the First Letter of Each Word in a Phrase or Sentence (Title Case)}
\label{sec:capitalisewords}
New to mfirstuc v1.06:
@@ -190,7 +250,47 @@ 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}.
+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:
@@ -210,6 +310,82 @@ which produces:
\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}
@@ -222,6 +398,23 @@ entire argument before applying \cs{capitalisewords}:
\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}
@@ -231,11 +424,13 @@ 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
@@ -243,21 +438,6 @@ 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.)
-\begin{important}
-If you are using \sty{hyperref} and want to use \cs{capitalisewords}
-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}
-If you want to provide an alternative for the PDF bookmark, you can
-use \sty{hyperref}'s \ics{texorpdfstring} command. See the
-\sty{hyperref} manual for further details.
-\end{important}
-
Examples:
\begin{enumerate}
\item
@@ -301,6 +481,43 @@ produces:
\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]
@@ -334,10 +551,33 @@ The list of words that shouldn't be capitalised can be cleared using
\cs{MFUclear}
\end{definition}
-The package \sty{mfirstuc-english} loads \sty{mfirstuc} and uses
+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
+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.
@@ -357,7 +597,7 @@ argument, for example:
\begin{verbatim}
\ProvidesPackage{mfirstuc-french}[2014/07/30 v1.0]
\end{verbatim}
-Next load \sty{mfirstuc}:
+Next load \styfmt{mfirstuc}:
\begin{verbatim}
\RequirePackage{mfirstuc}
\end{verbatim}
@@ -371,8 +611,9 @@ At the end of the file add:
\end{verbatim}
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.
+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}
@@ -490,4 +731,5 @@ 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}