From a680fbdd019a24e851538a6dfde26ef301a0a286 Mon Sep 17 00:00:00 2001
From: Karl Berry
mfirstuc.sty v2.03: uppercasing first letter
+class="cmr-17">mfirstuc.sty v2.04: uppercasing first letter
2016-07-29
-http://www.dickimaw-books.com/
Contents
- Contents
2 2 Capitalising the First Letter of a Word
-
3 3 Capitalise the First Letter of Each Word in a Phrase or Sentence (Title Case)
-
3.1 3.1 PDF Bookmarks
-
3.2 3.2 Excluding Words From Case-Changing
-
4 4 UTF-8
The The mfirstuc package was originally part of the glossaries bundle for use with commands like
-glossaries bundle for use with commands
+like \Gls, but as the commands provided by mfirstuc may be used without glossaries, the two have
-been split into separately maintained packages.
+class="cmss-10">glossaries, the two
+have been split into separately maintained packages.
+
+
+
A simple word can be capitalised just using the standard LATEX upper casing command. For
-example,
+ 1. Introduction
+2 Capitalising the First Letter of a Word
-
A simple word can be capitalised just using the standard LATEX upper casing command. +For example, @@ -390,30 +397,67 @@ class="cmtt-10">\makefirstuc{{ä}bc} produces Äbc. -
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 Note that non-Latin or accented characters appearing at the start of the text should be
+placed in a group (even if you are using the inputenc package). The reason for this restriction is detailed in
- package). The reason for this restriction
+is detailed in §4 UTF-8.
- New to version 2.04: There is now limited support for UTF-8 characters with the
+inputenc package, provided that you load datatool-base (at least v2.24) before mfirstuc
+(datatool-base is loaded automatically with newer versions of glossaries). If available mfirstuc
+will now use datatool-base’s \dtl@getfirst@UTFviii command which is still experimental.
+See the datatool manual for further details.
+
+
+
+ (Package ordering is important.)
+
- Note also that
+
+ Note also that
produces: ABC. This is because the first object in the argument of produces: ABC. This is because the first object in the argument of \makefirstuc is \abc, so
it does \MakeUppercase{\abc}. Whereas:
produces: Abc. There is a short cut command which will do this:
- produces: Abc. There is a short cut command which will do this:
+
+
This is equivalent to \expandafter\makefirstuc\expandafter{⟨stuff ⟩}. So
produces: Abc.
- produces: Abc.
+
- As from version 1.10, there is now a command that fully expands the entire argument
+
+ As from version 1.10, there is now a command that fully expands the entire argument
before applying \makefirstuc:
-
- Examples:
+
+ Examples:
produces: No expansion: XYZA. First object one-level expansion: XYZa. Fully expanded:
+ produces: No expansion: XYZA. First object one-level expansion: XYZa. Fully expanded:
Xyza.
- If you use If you use mfirstuc without the glossaries package, the standard package, the standard \MakeUppercase command
is used. If used with glossaries, , \MakeTextUppercase (defined by the (defined by the textcase package) is used
+ id="dx1-3016"> package) is used
instead. If you are using mfirstuc without the glossaries package and want to use
\MakeTextUppercase instead, you can redefine
-
+
For example:
Remember to also load Remember to also load textcase ( (glossaries loads this automatically).
-
+
+
+
New to mfirstuc v1.06:
- New to mfirstuc v1.06:
+
+
This command applies \makefirstuc to each word in ⟨§3.2
Excluding Words From Case-Changing for excluding words (such as “of”) from the
case-changing.
- The actual capitalisation of each word is done using (new to version 2.03):
- The actual capitalisation of each word is done using (new to version 2.03):
+
+
This just does \makefirstuc{⟨word⟩} by default, but its behaviour is determined by the
conditional:
-
- If you want to title case each part of a compound word containing hyphens, you can enable
+
+ If you want to title case each part of a compound word containing hyphens, you can enable
this using
-
+
or switch it back off again using:
-
+
Compare
which produces: which produces: which produces: which produces: Formatting for the entire phrase must go outside Formatting for the entire phrase must go outside \capitalisewords (unlike
\makefirstuc). Compare:
@@ -611,10 +657,10 @@ class="cmtt-10">\makefirstuc which produces: which produces: which produces: which produces: As from version 2.03, there is now a command for phrases that may include a formatting
+ As from version 2.03, there is now a command for phrases that may include a formatting
command:
-
+
where ⟨phrase⟩ may be just words (as with \capitalisewords) or may be entirely enclosed in a
@@ -667,17 +713,24 @@ class="cmitt-10">words Examples:
+
+ The starred form only permits a text-block command at the start of the phrase.
+ Examples:
produces: produces: produces: produces: produces: produces: produces: produces: Grouping causes interference:
+ produces: produces: If there is a text-block command within the argument of the starred form, it’s assumed to
+be at the start of the argument. Unexpected results can occur if there are other commands.
+For example
+
+
+
+ produces: produces: Grouping causes interference:
+
+
+
+ produces: produces: produces: produces: Avoid complicated commands in the unstarred version. For example, the following
+breaks:
+
+
+
+ However it works okay with the starred form and the simpler \capitalisewords:
+
+
+
+ Produces:
+
This is a short cut for \expandafter\capitalisewords\expandafter{⟨text⟩}.
- As from version 1.10, there is now a command that fully expands the entire argument
+ As from version 1.10, there is now a command that fully expands the entire argument
before applying \capitalisewords:
-
- There are also similar shortcut commands for the version that allows formatting
+
+ There are also similar shortcut commands for the version that allows text-block
commands:
-
-This is a short cut for \expandafter\capitalisefmtwords\expandafter{⟨
+The unstarred version is a short cut for \expandafter\capitalisefmtwords\expandafter
+{⟨text⟩}.
- For full expansion:
- For full expansion:
+
-Take care with this as it may expand non-robust semantic commands to replacement text that
-breaks the functioning of \capitalisefmtwords. Use robust semantic commands where
-possible.
- Examples:
+
+Take care with this as it may expand non-robust semantic commands to replacement
+text that breaks the functioning of \capitalisefmtwords. Use robust semantic
+commands where possible. Again this has a starred version that uses the starred form of
+\capitalisefmtwords.
+ Examples:
produces: produces: (Remember that the spaces need to be explicit. In the second case above, using
+ (Remember that the spaces need to be explicit. In the second case above, using
\xcapitalisewords, the space before “four” has been hidden within \space so it’s not
recognised as a word boundary, but in the third case, \space has been expanded to an actual
space character.)
- Examples:
+ Examples:
produces: A Book Of Rhyme.
+ produces: A Book Of Rhyme.
produces: A Book of Rhyme.
+ produces: A Book of Rhyme.
produces: A BOOK OF RHYME. (No expansion is performed on produces: A BOOK OF RHYME. (No expansion is performed on \mytitle.) Compare
with next example:
produces: A Book of Rhyme.
- However
+ produces: A Book of Rhyme.
+ However
produces: A Book Of Rhyme.
-
+ produces: A Book Of Rhyme. (\space has been expanded to an actual space
+ character.)
+ produces:
- If you want to provide an alternative for the PDF bookmark, you can use
+ If you want to provide an alternative for the PDF bookmark, you can use hyperref’s
\texorpdfstring
- Alternatively, you can use Alternatively, you can use hyperref’s mechanism for disabling commands within the
bookmarks. For example:
@@ -933,73 +1107,73 @@ bookmarks. For example:
- See the
+ See the hyperref manual for further details.
-
+
As from v1.09, you can specify words which shouldn’t be capitalised unless they occur at the
+ As from v1.09, you can specify words which shouldn’t be capitalised unless they occur at the
start of ⟨text⟩ using:
-
+
This only has a local effect. The global version is:
-
- For example:
+
+ For example:
produces: produces:
- You can also simply place an empty group in front of a word if you don’t want that specific
+
+ 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:
produces: produces: produces produces The package \nameref{sec:nocap} The package mfirstuc-english loads mfirstuc and uses If you want to write a similar package for another language, all you need to do is create a
+ If you want to write a similar package for another language, all you need to do is create a
file with the extension .sty that starts with
The next line should identify the package. For example, if you have called the file
+ The next line should identify the package. For example, if you have called the file
mfirstuc-french.sty then you need:
It’s a good idea to also add a version in the final optional argument, for example:
+ It’s a good idea to also add a version in the final optional argument, for example:
Next load Next load mfirstuc:
Now add all your Now add all your \MFUnocap commands. For example:
At the end of the file add:
+ At the end of the file add:
- Put the file somewhere on T
+ 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.
-
+
+
+
The The \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
@@ -1101,35 +1279,35 @@ class="cmtt-10">\frac{1}{2} or A simplistic version of the A simplistic version of the \makefirstuc command is:
Here
+ Here
is equivalent to
+ is equivalent to
and since and since \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 The glossaries package needs to take into account the fact that the text may be contained
in the argument of a formatting command, such as \foo{⟨stuff⟩}}
+ Try the following document: Try the following document: This will result in the error:
+ This will result in the error:
This is why This is why \makefirstuc{ãbc} won’t work. It will only work if the character ã is placed
inside a group.
- The reason for this error message is due to T The reason for this error message is due to TEX having been written before Unicode was
invented. Although ã may look like a single character in your text editor, from T}bc
Note that XeTeX (and therefore XeLaTeX) is a modern implementation of T 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: This works correctly when compiled with XeLaTeX. This means that This works correctly when compiled with XeLaTeX. This means that \makefirstuc{ã and the fontspec package.
+ Version 2.24 of datatool-base added the command \dtl@getfirst@UTFviii which
+attempts to grab both octets. If this command has been defined, mfirstuc will use it when it
+tries to split the first character from the rest of the word. See the datatool documented code
+for further details.
-
D
+datatool-base package 6, 19 E
\ecapitalisefmtwords 8 F
fontspec package 13 G
glossaries package 4, 12 H
hyperref package 9 I
\ifMFUhyphen 5 M
\makefirstuc 2 T
textcase package 4 X
\xcapitalisefmtwords 8
\usepackage[T1]{fontenc}
+
\usepackage[utf8]{inputenc}
+
\usepackage{datatool-base}[2016/01/12]% v2.24+
+
\usepackage{mfirstuc}
+
\begin{document}
+
\makefirstuc{élite}
+
\end{document}
+
\makefirstuc{\abc}
\expandafter\makefirstuc\expandafter{\abc}
-
\xmakefirstuc{\abc}
-
\newcommand{\xyz}{xyz}
No expansion: \makefirstuc{\abc}.
First object one-level expansion: \xmakefirstuc{\abc}.
Fully expanded: \emakefirstuc{\abc}.
-3 Capitalise the First Letter of Each Word in a Phrase or Sentence (Title
-Case)
-3. Capitalise the First Letter of Each Word in a Phrase or Sentence (Title Case)
+
-
-
-
-
-
Server-side Includes
\capitalisewords{server-side includes}
Server-Side Includes
A sample phrase
A Sample Phrase
-
A Small Book Of Rhyme
A Small Book Of Rhyme
A Small Book Of Rhyme
@@ -718,25 +771,88 @@ href="#sec:nocap">Excluding Words From
-
\capitalisefmtwords{\textbf{a \emph{small book}} of rhyme}
A Small Book of Rhyme
\capitalisefmtwords*{\emph{a small book of rhyme}}
+
A Small Book of Rhyme
+
\capitalisefmtwords*{a small book of rhyme}
+
A Small Book of Rhyme
+
\capitalisefmtwords*{\emph{a small} book \textbf{of rhyme}}
+
A Small Book Of rhyme
+
\capitalisefmtwords*{a \emph{very small} book of rhyme}
+
A Very small Book of Rhyme
+
A Small book Of Rhyme
a Small book Of Rhyme
\capitalisefmtwords{a \swap{bo}{ok} of rhyme}
+
\capitalisefmtwords*{a \swap{bo}{ok} of rhyme}
+
\capitalisewords{a \swap{bo}{ok} of rhyme}
+
A okBo Of Rhyme
+
A okBo Of Rhyme
+
-
-
-
-
\newcommand{\xyz}{one two three}
No expansion: \capitalisewords{\abc}.
First object one-level expansion: \xcapitalisewords{\abc}.
Fully expanded: \ecapitalisewords{\abc}.
No expansion: ONE TWO THREE FOUR FIVE.
First object one-level expansion: ONE TWO THREE four Five.
Fully expanded: One Two Three Four Five.
\capitalisewords{\mytitle}
\xcapitalisewords{\mytitle}
\capitalisewords{a \swap{bo}{ok} of rhyme}
+
\ecapitalisewords{a \swap{bo}{ok} of rhyme}
+
A okBo Of Rhyme
+
A OKbo Of Rhyme
+ 3.1 PDF Bookmarks
-3.1 PDF Bookmarks
+
(PDFDocEncoding):
(hyperref) removing ‘\capitalisewords’
{\capitalisewords{a book of rhyme}}% TeX
{A Book of Rhyme}% PDF
}
\let\capitalisewords\@firstofone
}
3.2 Excluding Words From Case-Changing
-3.2 Excluding Words From Case-Changing
+
-
-
\MFUnocap{in}%
\MFUnocap{the}%
\capitalisewords{the wind in the willows}
The Wind In The Willows
The Wind in the Willows
-
\capitalisewords{the {}wind in the willows}
The wind In The Willows
This Is Section Excluding Words From Case-Changing.
4 UTF-8
-4. UTF-8
+x^2 instead of x^{2}, although some
users frown on this practice.)
-Index
-Index
C
-
+class="cmti-10">8
+
+class="cmti-10">12
\ecapitalisewords 8
+class="cmti-10">12
\emakefirstuc 4
+class="cmti-10">7
+class="cmss-10">fontspec package 19
+class="cmss-10">glossaries package 6, 7, 17
\glsmakefirstuc 4
+class="cmti-10">7
\gMFUnocap 10
+class="cmti-10">15
+class="cmss-10">hyperref package 14
+class="cmti-10">8
inputenc package 3
+class="cmss-10">inputenc package 6
+class="cmti-10">5
mfirstuc-english package 10
+class="cmss-10">mfirstuc package 6, 19
+mfirstuc-english package 15
+
+
+
\MFUcapword 5
+class="cmti-10">8
\MFUclear 10
+class="cmti-10">15
\MFUhyphenfalse 5
+class="cmti-10">8
\MFUhyphentrue 5
+class="cmti-10">8
\MFUnocap 9
+class="cmti-10">15
+class="cmss-10">textcase package 7
-
-
-
+class="cmti-10">12
\xcapitalisewords 7
+class="cmti-10">12
\xmakefirstuc 4
+class="cmti-10">7