diff options
author | Norbert Preining <norbert@preining.info> | 2019-09-02 13:46:59 +0900 |
---|---|---|
committer | Norbert Preining <norbert@preining.info> | 2019-09-02 13:46:59 +0900 |
commit | e0c6872cf40896c7be36b11dcc744620f10adf1d (patch) | |
tree | 60335e10d2f4354b0674ec22d7b53f0f8abee672 /macros/latex/contrib/mfirstuc |
Initial commit
Diffstat (limited to 'macros/latex/contrib/mfirstuc')
-rw-r--r-- | macros/latex/contrib/mfirstuc/CHANGES | 95 | ||||
-rw-r--r-- | macros/latex/contrib/mfirstuc/README | 41 | ||||
-rw-r--r-- | macros/latex/contrib/mfirstuc/mfirstuc-code.pdf | bin | 0 -> 260995 bytes | |||
-rw-r--r-- | macros/latex/contrib/mfirstuc/mfirstuc-manual.html | 1614 | ||||
-rw-r--r-- | macros/latex/contrib/mfirstuc/mfirstuc-manual.pdf | bin | 0 -> 294426 bytes | |||
-rw-r--r-- | macros/latex/contrib/mfirstuc/mfirstuc-manual.tex | 878 | ||||
-rw-r--r-- | macros/latex/contrib/mfirstuc/mfirstuc.dtx | 1429 | ||||
-rw-r--r-- | macros/latex/contrib/mfirstuc/mfirstuc.ins | 35 | ||||
-rw-r--r-- | macros/latex/contrib/mfirstuc/sample-mfirstuc.pdf | bin | 0 -> 114720 bytes | |||
-rw-r--r-- | macros/latex/contrib/mfirstuc/sample-mfirstuc.tex | 285 |
10 files changed, 4377 insertions, 0 deletions
diff --git a/macros/latex/contrib/mfirstuc/CHANGES b/macros/latex/contrib/mfirstuc/CHANGES new file mode 100644 index 0000000000..77f20bd2ed --- /dev/null +++ b/macros/latex/contrib/mfirstuc/CHANGES @@ -0,0 +1,95 @@ +mfirstuc change log: + +v2.06: + + * \makefirstuc: added check for nested commands. + +v2.05: + + * bug fix in \@mfu@applytofirst (#1 must be grouped) + +v2.04: + + * bug fixes in \capitalisefmtwords and \@gls@split + + * added starred form of \capitalisefmtwords + +v2.03: + + * Fixed test for \protect at the start of \makefirstuc + + * Add new conditional \ifMFUhyphen and new command + \MFUcapword + + * New commands \capitalisefmtwords, \xcapitalisefmtwords + and \ecapitalisefmtwords (like \capitalisewords etc + but allows for text-block formatting commands within + the argument). + +v2.02: + + * Fixed bug in \capitalisewords + http://www.dickimaw-books.com/cgi-bin/bugtracker.cgi?action=view&key=104 + +v2.01: + + * Added check for initial \protect in \makefirstuc + +v2.0: + + * Split from glossaries bundle. + + * Fixed bug that occurred when the first two tokens of + \makefirstuc are both control sequences. + +v1.10: + + * added \ecapitalisewords, \emakefirstuc + +v1.09: + + * Added \MFUnocap + + * New package: mfirstuc-english.sty + +v1.08: + + * Made \makefirstuc and \capitalisewords robust + +v1.07: + + * Added \mfirstucMakeUppercase to allow the user to switch from + \MakeUppercase to another case changing command. + +v1.06: + + * added \capitalisewords, \xcapitalisewords + +v1.05: + + * added \glsmakefirstuc (replaces \@gls@makefirstuc) to make + it easier to customise. + +v1.04: + + * fixed bug occurring when initial control sequence + in the argument of \makefirstuc has more than one + argument. + +v1.02: + + * Fixed bug that transfered grouping, (e.g + \makefirstuc{\emph{abc}xyz} moved the xyz into the \emph) + + * If group following initial command is empty, \MakeUppercase + is applied to the command, e.g. \makefirstuc{\ae{}bc} now + produces \MakeUppercase\ae{}bc. + +v1.01: + + * Added \xmakefirstuc (expands argument before applying \makefirstuc) + +v1.0: + + * Initial version + diff --git a/macros/latex/contrib/mfirstuc/README b/macros/latex/contrib/mfirstuc/README new file mode 100644 index 0000000000..0f406a84a8 --- /dev/null +++ b/macros/latex/contrib/mfirstuc/README @@ -0,0 +1,41 @@ +LaTeX Package : mfirstuc v2.06 + +Last Modified : 2017-11-14 + +Author : Nicola Talbot + +This package provides \makefirstuc{<stuff>} which makes the first object of +<stuff> upper case unless <stuff> starts with a control +sequence followed by a non-empty group, in which case the first +object in the group is converted to upper case. Examples: + + \makefirstuc{abc} -> Abc + \makefirstuc{\emph{abc}} -> \emph{Abc} + \makefirstuc{{\'a}bc} -> \'Abc + \makefirstuc{\ae bc} -> \AE bc + \makefirstuc{{\ae}bc} -> \AE bc + \makefirstuc{\ae{}bc} -> \AE{}bc + +The package also provides \capitalisewords{<phrase>} which applies +\makefirstuc to each word in the <phrase>, where the words are +separated by regular spaces. (Exceptions can be made for words that +shouldn't be converted.) + +The mfirstuc package was originally bundled with the glossaries +package. + +LaTeX2HTML + +This package comes with a LaTeX2HTML style file mfirstuc.perl which +should be placed in the relevant LaTeX2HTML styles directory, but +note that some commands may not be implemented or may be implemented +in a different way. + +LICENCE + +This material is subject to the LaTeX Project Public License. +See http://www.ctan.org/license/lppl1.3 +for the details of that license. + +Author's home page: http://www.dickimaw-books.com/ + diff --git a/macros/latex/contrib/mfirstuc/mfirstuc-code.pdf b/macros/latex/contrib/mfirstuc/mfirstuc-code.pdf Binary files differnew file mode 100644 index 0000000000..50469d6193 --- /dev/null +++ b/macros/latex/contrib/mfirstuc/mfirstuc-code.pdf diff --git a/macros/latex/contrib/mfirstuc/mfirstuc-manual.html b/macros/latex/contrib/mfirstuc/mfirstuc-manual.html new file mode 100644 index 0000000000..e94be007b6 --- /dev/null +++ b/macros/latex/contrib/mfirstuc/mfirstuc-manual.html @@ -0,0 +1,1614 @@ +<?xml version="1.0" encoding="utf-8" ?> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" + "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> +<!--http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd--> +<html xmlns="http://www.w3.org/1999/xhtml" +> +<head><title></title> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> +<meta name="generator" content="TeX4ht (http://www.tug.org/tex4ht/)" /> +<meta name="originator" content="TeX4ht (http://www.tug.org/tex4ht/)" /> +<!-- xhtml,fn-in,css-in,uni-html4,utf8 --> +<meta name="src" content="mfirstuc-manual.tex" /> + +<style type="text/css"> +<!-- + +/* start css.sty */ +.cmr-17{font-size:170%;} +.cmr-12{font-size:120%;} +.cmtt-12{font-size:120%;font-family: monospace;} +.cmtt-12{font-family: monospace;} +.cmtt-12{font-family: monospace;} +.cmtt-12{font-family: monospace;} +.cmtt-10{font-family: monospace;} +.cmtt-10{font-family: monospace;} +.cmtt-10{font-family: monospace;} +.cmtt-10{font-family: monospace;} +.cmss-10{ font-family: sans-serif;} +.cmss-10{ font-family: sans-serif;} +.cmtt-9{font-size:90%;font-family: monospace;} +.cmtt-9{font-family: monospace;} +.cmtt-9{font-family: monospace;} +.cmtt-9{font-family: monospace;} +.cmitt-10{font-family: monospace; font-style: italic;} +.cmti-10{ font-style: italic;} +.cmbx-10{ font-weight: bold;} +.cmbxti-10{ font-weight: bold; font-style: italic;} +.cmssi-10{ font-family: sans-serif; font-style: oblique;} +.cmssi-10{ font-family: sans-serif; font-style: oblique;} +p.noindent { text-indent: 0em } +td p.noindent { text-indent: 0em; margin-top:0em; } +p.nopar { text-indent: 0em; } +p.indent{ text-indent: 1.5em } +@media print {div.crosslinks {visibility:hidden;}} +a img { border-top: 0; border-left: 0; border-right: 0; } +center { margin-top:1em; margin-bottom:1em; } +td center { margin-top:0em; margin-bottom:0em; } +.Canvas { position:relative; } +img.math{vertical-align:middle;} +li p.indent { text-indent: 0em } +li p:first-child{ margin-top:0em; } +li p:last-child, li div:last-child { margin-bottom:0.5em; } +li p~ul:last-child, li p~ol:last-child{ margin-bottom:0.5em; } +.enumerate1 {list-style-type:decimal;} +.enumerate2 {list-style-type:lower-alpha;} +.enumerate3 {list-style-type:lower-roman;} +.enumerate4 {list-style-type:upper-alpha;} +div.newtheorem { margin-bottom: 2em; margin-top: 2em;} +.obeylines-h,.obeylines-v {white-space: nowrap; } +div.obeylines-v p { margin-top:0; margin-bottom:0; } +.overline{ text-decoration:overline; } +.overline img{ border-top: 1px solid black; } +td.displaylines {text-align:center; white-space:nowrap;} +.centerline {text-align:center;} +.rightline {text-align:right;} +div.verbatim {font-family: monospace; white-space: nowrap; text-align:left; clear:both; } +.fbox {padding-left:3.0pt; padding-right:3.0pt; text-indent:0pt; border:solid black 0.4pt; } +div.fbox {display:table} +div.center div.fbox {text-align:center; clear:both; padding-left:3.0pt; padding-right:3.0pt; text-indent:0pt; border:solid black 0.4pt; } +div.minipage{width:100%;} +div.center, div.center div.center {text-align: center; margin-left:1em; margin-right:1em;} +div.center div {text-align: left;} +div.flushright, div.flushright div.flushright {text-align: right;} +div.flushright div {text-align: left;} +div.flushleft {text-align: left;} +.underline{ text-decoration:underline; } +.underline img{ border-bottom: 1px solid black; margin-bottom:1pt; } +.framebox-c, .framebox-l, .framebox-r { padding-left:3.0pt; padding-right:3.0pt; text-indent:0pt; border:solid black 0.4pt; } +.framebox-c {text-align:center;} +.framebox-l {text-align:left;} +.framebox-r {text-align:right;} +span.thank-mark{ vertical-align: super } +span.footnote-mark sup.textsuperscript, span.footnote-mark a sup.textsuperscript{ font-size:80%; } +div.footnotes{border-top:solid 1px black; border-bottom:solid 1px black; padding-bottom:1ex; padding-top:0.5ex; margin-right:15%; margin-top:2ex; font-style:italic; font-size:85%;} +div.footnotes p{margin-top:0; margin-bottom:0; text-indent:0;} +div.tabular, div.center div.tabular {text-align: center; margin-top:0.5em; margin-bottom:0.5em; } +table.tabular td p{margin-top:0em;} +table.tabular {margin-left: auto; margin-right: auto;} +td p:first-child{ margin-top:0em; } +td p:last-child{ margin-bottom:0em; } +div.td00{ margin-left:0pt; margin-right:0pt; } +div.td01{ margin-left:0pt; margin-right:5pt; } +div.td10{ margin-left:5pt; margin-right:0pt; } +div.td11{ margin-left:5pt; margin-right:5pt; } +table[rules] {border-left:solid black 0.4pt; border-right:solid black 0.4pt; } +td.td00{ padding-left:0pt; padding-right:0pt; } +td.td01{ padding-left:0pt; padding-right:5pt; } +td.td10{ padding-left:5pt; padding-right:0pt; } +td.td11{ padding-left:5pt; padding-right:5pt; } +table[rules] {border-left:solid black 0.4pt; border-right:solid black 0.4pt; } +.hline hr, .cline hr{ height : 1px; margin:0px; } +.tabbing-right {text-align:right;} +span.TEX {letter-spacing: -0.125em; } +span.TEX span.E{ position:relative;top:0.5ex;left:-0.0417em;} +a span.TEX span.E {text-decoration: none; } +span.LATEX span.A{ position:relative; top:-0.5ex; left:-0.4em; font-size:85%;} +span.LATEX span.TEX{ position:relative; left: -0.4em; } +div.float, div.figure {margin-left: auto; margin-right: auto;} +div.float img {text-align:center;} +div.figure img {text-align:center;} +.marginpar {width:20%; float:right; text-align:left; margin-left:auto; margin-top:0.5em; font-size:85%; text-decoration:underline;} +.marginpar p{margin-top:0.4em; margin-bottom:0.4em;} +table.equation {width:100%;} +.equation td{text-align:center; } +td.equation { margin-top:1em; margin-bottom:1em; } +td.equation-label { width:5%; text-align:center; } +td.eqnarray4 { width:5%; white-space: normal; } +td.eqnarray2 { width:5%; } +table.eqnarray-star, table.eqnarray {width:100%;} +div.eqnarray{text-align:center;} +div.array {text-align:center;} +div.pmatrix {text-align:center;} +table.pmatrix {width:100%;} +span.pmatrix img{vertical-align:middle;} +div.pmatrix {text-align:center;} +table.pmatrix {width:100%;} +span.bar-css {text-decoration:overline;} +img.cdots{vertical-align:middle;} +.partToc a, .partToc, .likepartToc a, .likepartToc {line-height: 200%; font-weight:bold; font-size:110%;} +.chapterToc a, .chapterToc, .likechapterToc a, .likechapterToc, .appendixToc a, .appendixToc {line-height: 200%; font-weight:bold;} +.index-item, .index-subitem, .index-subsubitem {display:block} +div.caption {text-indent:-2em; margin-left:3em; margin-right:1em; text-align:left;} +div.caption span.id{font-weight: bold; white-space: nowrap; } +h1.partHead{text-align: center} +p.bibitem { text-indent: -2em; margin-left: 2em; margin-top:0.6em; margin-bottom:0.6em; } +p.bibitem-p { text-indent: 0em; margin-left: 2em; margin-top:0.6em; margin-bottom:0.6em; } +.paragraphHead, .likeparagraphHead { margin-top:2em; font-weight: bold;} +.subparagraphHead, .likesubparagraphHead { font-weight: bold;} +.quote {margin-bottom:0.25em; margin-top:0.25em; margin-left:1em; margin-right:1em; text-align:justify;} +.verse{white-space:nowrap; margin-left:2em} +div.maketitle {text-align:center;} +h2.titleHead{text-align:center;} +div.maketitle{ margin-bottom: 2em; } +div.author, div.date {text-align:center;} +div.thanks{text-align:left; margin-left:10%; font-size:85%; font-style:italic; } +.quotation {margin-bottom:0.25em; margin-top:0.25em; margin-left:1em; } +h1.partHead{text-align: center} +.abstract p {margin-left:5%; margin-right:5%;} +div.abstract {width:100%;} +.alltt P { margin-bottom : 0em; margin-top : 0em; } +.alltt { margin-bottom : 1em; margin-top : 1em; } +div.important { border : solid red; } +div.verbatim { font-family: monospace; white-space: nowrap; text-align:left; clear:both; padding-top: 2ex; padding-bottom: 2ex;} +span#textcolor1{color:#FF0000} +/* end css.sty */ + + +--> +</style> +</head><body +> +<!--l. 36--><p class="noindent" ><a + id="top"></a> +</p><!--l. 36--><p class="indent" > + + + +</p><!--l. 36--><p class="indent" > + + + +</p> +<div class="center" +> +<!--l. 36--><p class="noindent" > +</p><!--l. 36--><p class="noindent" ><span +class="cmr-17">mfirstuc.sty v2.06: uppercasing first letter</span> +</p> +<div class="tabular"> <table id="TBL-1" class="tabular" +cellspacing="0" cellpadding="0" +><colgroup id="TBL-1-1g"><col +id="TBL-1-1" /></colgroup><tr + style="vertical-align:baseline;" id="TBL-1-1-"><td style="white-space:nowrap; text-align:center;" id="TBL-1-1-1" +class="td11"> <span +class="cmr-12">Nicola L.C. Talbot </span></td> +</tr><tr +class="vspace" style="font-size:10.0pt"><td +> </td></tr><tr + style="vertical-align:baseline;" id="TBL-1-2-"><td style="white-space:nowrap; text-align:center;" id="TBL-1-2-1" +class="td11"> <span +class="cmr-12">Dickimaw Books </span></td> +</tr><tr + style="vertical-align:baseline;" id="TBL-1-3-"><td style="white-space:nowrap; text-align:center;" id="TBL-1-3-1" +class="td11"><a +href="http://www.dickimaw-books.com/" class="url" ><span +class="cmtt-12">http://www.dickimaw-books.com/</span></a></td></tr></table> +</div> +<!--l. 36--><p class="noindent" ><span +class="cmr-12">2017-11-14</span></p></div> + + + + <h2 class="likechapterHead"><a + id="x1-1000"></a>Contents</h2> + <div class="tableofcontents"> + <span class="chapterToc" >1 <a +href="#sec:intro" id="QQ2-1-2">Introduction</a></span> +<br /> <span class="chapterToc" >2 <a +href="#sec:makefirstuc" id="QQ2-1-3">Capitalising the First Letter of a Word</a></span> +<br /> <span class="chapterToc" >3 <a +href="#sec:capitalisewords" id="QQ2-1-4">Capitalise the First Letter of Each Word in a Phrase or Sentence (Title Case)</a></span> +<br />  <span class="sectionToc" >3.1 <a +href="#sec:pdfbookmarks" id="QQ2-1-5">PDF Bookmarks</a></span> +<br />  <span class="sectionToc" >3.2 <a +href="#sec:nocap" id="QQ2-1-6">Excluding Words From Case-Changing</a></span> +<br /> <span class="chapterToc" >4 <a +href="#sec:utf8" id="QQ2-1-7">UTF-8</a></span> + </div> + + + +<!--l. 39--><p class="indent" > <div class="chapter"><h2 class="chapterHead">1. <a + id="sec:intro"></a>Introduction</h2> +</p><!--l. 42--><p class="indent" > The <span +class="cmss-10">mfirstuc </span>package was originally part of the <span +class="cmss-10">glossaries </span>bundle for use with commands +like <span +class="cmtt-10">\Gls</span>, but as the commands provided by <span +class="cmss-10">mfirstuc </span>may be used without <span +class="cmss-10">glossaries</span>, the two +have been split into separately maintained packages. +</p><!--l. 48--><p class="indent" > <div class="important" title="Important Note"> 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. </div> +</p><!--l. 53--><p class="noindent" > +</p><!--l. 55--><p class="indent" > Here are some examples of semantic commands: + </p><ol class="enumerate1" > + <li + class="enumerate" id="x1-2002x1">Quoted material: + + + + <div class="verbatim" id="verbatim-1"> + \newcommand{\qt}[1]{``#1''} +</div> + <!--l. 60--><p class="nopar" > (or use the <span +class="cmss-10">csquotes </span>package). With this, the following works: + + + +</p> + <div class="verbatim" id="verbatim-2"> + \makefirstuc{\qt{word}} +</div> + <!--l. 65--><p class="nopar" > This produces: <spacer type=vertical size=10><span class="obeylines-h"> + <br />“Word” + <br /><spacer type=vertical size=10></span> + Whereas + + + +</p> + <div class="verbatim" id="verbatim-3"> + \makefirstuc{``word''} +</div> + <!--l. 73--><p class="nopar" > fails (no case-change and double open quote becomes two single open quotes): + <spacer type=vertical size=10><span class="obeylines-h"> + <br />‘‘word” + <br /><spacer type=vertical size=10></span> + </p></li> + <li + class="enumerate" id="x1-2004x2">Font styles or colours: + + + + <div class="verbatim" id="verbatim-4"> + \newcommand*{\alert}[1]{\textcolor{red}{#1}} +</div> + <!--l. 83--><p class="nopar" > Now the following is possible: + + + +</p> + <div class="verbatim" id="verbatim-5"> + \makefirstuc{\alert{word}} +</div> + <!--l. 87--><p class="nopar" > This produces <spacer type=vertical size=10><span class="obeylines-h"> + <br /><span id="textcolor1">Word</span> + <br /><spacer type=vertical size=10></span> + Note that <span class="obeylines-h"><span class="verb"><span +class="cmtt-10">\makefirstuc{\textcolor{red}{word}}</span></span></span> fails (with an error) because the + case-changing interferes with the label.</p></li></ol> +<!--l. 97--><p class="indent" > Define these semantic commands robustly if you intend using any of the commands +that fully expand their argument (<span +class="cmtt-10">\emakefirstuc</span>, <span +class="cmtt-10">\ecapitalisewords </span>and +<span +class="cmtt-10">\ecapitalisefmtwords</span>). + + + +</p> +<!--l. 102--><p class="indent" > </div> +</p><!--l. 102--><p class="noindent" ><a +href="#top">Top</a><div class="chapter"><h2 class="chapterHead">2. <a + id="sec:makefirstuc"></a>Capitalising the First Letter of a Word</h2> +</p><!--l. 105--><p class="indent" > A simple word can be capitalised just using the standard <span class="LATEX">L<span class="A">A</span><span class="TEX">T<span +class="E">E</span>X</span></span> upper casing command. +For example, + + + +</p> + <div class="verbatim" id="verbatim-6"> +\MakeUppercase word +</div> +<!--l. 109--><p class="nopar" > but for commands like <span +class="cmtt-10">\Gls </span>the word may be embedded within the argument of another +command, such as a font changing command. This makes things more complicated for +a general purpose solution, so the <span +class="cmss-10">mfirstuc </span>package provides: +</p><!--l. 114--><p class="indent" > <hr><div title="Definition"><span class="marginpar"><span +class="cmtt-9">\makefirstuc</span><span +class="cmtt-9"> </span></span><a + id="dx1-3001"></a> <span +class="cmtt-10">\makefirstuc{</span>⟨<span +class="cmitt-10">stuff</span>⟩<span +class="cmtt-10">} </span></div><hr> +</p><!--l. 116--><p class="noindent" > +This makes the first object of ⟨<span +class="cmti-10">stuff </span>⟩ upper case unless ⟨<span +class="cmti-10">stuff </span>⟩ starts with a control sequence +followed by a non-empty group, in which case the first object in the group is converted to +upper case. <span +class="cmbx-10">No expansion is performed on the argument.</span> +</p><!--l. 123--><p class="indent" > <div class="important" title="Important Note"> If ⟨<span +class="cmti-10">stuff </span>⟩ starts with a control sequence that takes more than one argument, the +case-changing will always be applied to the <span +class="cmti-10">first </span>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 <span class="obeylines-h"><span class="verb"><span +class="cmtt-10">\textcolor{red}{text}</span></span></span> you need to define, say, <span class="obeylines-h"><span class="verb"><span +class="cmtt-10">\red</span></span></span> as +<span class="obeylines-h"><span class="verb"><span +class="cmtt-10">\color{red}</span></span></span> and use <span class="obeylines-h"><span class="verb"><span +class="cmtt-10">\red{text}</span></span></span>. </div> +</p><!--l. 131--><p class="noindent" > +</p><!--l. 133--><p class="indent" > Examples: </p> + <ul class="itemize1"> + <li class="itemize"><span class="obeylines-h"><span class="verb"><span +class="cmtt-10">\makefirstuc{abc}</span></span></span> produces Abc. + </li> + <li class="itemize"><span class="obeylines-h"><span class="verb"><span +class="cmtt-10">\makefirstuc{\emph{abc}}</span></span></span> produces <span +class="cmti-10">Abc </span>(<span +class="cmtt-10">\MakeUppercase</span><a + id="dx1-3002"></a> has been applied to the + letter “a” rather than <span +class="cmtt-10">\emph</span>). Note however that + + + + <div class="verbatim" id="verbatim-7"> + \makefirstuc{{\em abc}} +</div> + <!--l. 142--><p class="nopar" > produces <span +class="cmti-10">ABC </span>(first object is <span class="obeylines-h"><span class="verb"><span +class="cmtt-10">{\em</span><span +class="cmtt-10"> abc}</span></span></span> so this is equivalent to <span class="obeylines-h"><span class="verb"><span +class="cmtt-10">\MakeUppercase{\em</span><span +class="cmtt-10"> abc}</span></span></span>), + and + + + +</p> + <div class="verbatim" id="verbatim-8"> + {\makefirstuc{\em abc}} +</div> + <!--l. 147--><p class="nopar" > produces abc (<span class="obeylines-h"><span class="verb"><span +class="cmtt-10">\em</span></span></span> doesn’t have an argument therefore first object is <span class="obeylines-h"><span class="verb"><span +class="cmtt-10">\em</span></span></span> and so is + equivalent to <span class="obeylines-h"><span class="verb"><span +class="cmtt-10">{\MakeUppercase{\em}abc}</span></span></span>). + </p></li> + <li class="itemize"><span class="obeylines-h"><span class="verb"><span +class="cmtt-10">\makefirstuc{{\’a}bc}</span></span></span> produces Ábc. + </li> + <li class="itemize"><span class="obeylines-h"><span class="verb"><span +class="cmtt-10">\makefirstuc{\ae</span><span +class="cmtt-10"> bc}</span></span></span> produces Æbc. + </li> + <li class="itemize"><span class="obeylines-h"><span class="verb"><span +class="cmtt-10">\makefirstuc{{\ae}bc}</span></span></span> produces Æbc. + </li> + <li class="itemize"><span class="obeylines-h"><span class="verb"><span +class="cmtt-10">\makefirstuc{{</span><span +class="cmtt-10">ä</span><span +class="cmtt-10">}bc}</span></span></span> produces Äbc. + </li></ul> +<!--l. 162--><p class="indent" > 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 <span +class="cmss-10">inputenc</span><a + id="dx1-3003"></a> package). The reason for this restriction +is detailed in <a +href="#sec:utf8"><span +class="cmsy-10">§</span>4 </a><a +href="#sec:utf8">UTF-8<!--tex4ht:ref: sec:utf8 --></a>. +</p><!--l. 167--><p class="indent" > <span +class="cmbx-10">New to version 2.04: </span>There is now limited support for UTF-8 characters with the +<span +class="cmss-10">inputenc</span><a + id="dx1-3004"></a> package, provided that you load <span +class="cmss-10">datatool-base</span><a + id="dx1-3005"></a> (at least v2.24) before <span +class="cmss-10">mfirstuc</span> +(<span +class="cmss-10">datatool-base</span><a + id="dx1-3006"></a> is loaded automatically with newer versions of <span +class="cmss-10">glossaries</span><a + id="dx1-3007"></a>). If available <span +class="cmss-10">mfirstuc</span><a + id="dx1-3008"></a> +will now use <span +class="cmss-10">datatool-base</span><a + id="dx1-3009"></a>’s <span +class="cmtt-10">\dtl@getfirst@UTFviii</span><a + id="dx1-3010"></a> command which is still experimental. +See the <span +class="cmss-10">datatool </span>manual for further details. + + + +</p> + <div class="verbatim" id="verbatim-9"> +\documentclass{article} + <br />\usepackage[T1]{fontenc} + <br />\usepackage[utf8]{inputenc} + <br />\usepackage{datatool-base}[2016/01/12]% v2.24+ + <br />\usepackage{mfirstuc} + <br />\begin{document} + <br />\makefirstuc{élite} + <br />\end{document} +</div> +<!--l. 188--><p class="nopar" > (Package ordering is important.) +</p><!--l. 191--><p class="indent" > <div class="important" title="Important Note"> In version 1.02 of <span +class="cmss-10">mfirstuc</span>, a bug fix resulted in a change in output if the first object is a +control sequence followed by an empty group. Prior to version 1.02, <span class="obeylines-h"><span class="verb"><span +class="cmtt-10">\makefirstuc{\ae{}bc}</span></span></span> +produced æBc. However as from version 1.02, it now produces Æbc. </div> +</p><!--l. 197--><p class="noindent" > +</p><!--l. 199--><p class="indent" > Note also that + + + +</p> + <div class="verbatim" id="verbatim-10"> +\newcommand{\abc}{abc} + <br />\makefirstuc{\abc} +</div> +<!--l. 203--><p class="nopar" > produces: ABC. This is because the first object in the argument of <span +class="cmtt-10">\makefirstuc </span>is <span +class="cmtt-10">\abc</span>, so +it does <span class="obeylines-h"><span class="verb"><span +class="cmtt-10">\MakeUppercase{\abc}</span></span></span>. Whereas: + + + +</p> + <div class="verbatim" id="verbatim-11"> +\newcommand{\abc}{abc} + <br />\expandafter\makefirstuc\expandafter{\abc} +</div> +<!--l. 210--><p class="nopar" > produces: Abc. There is a short cut command which will do this: +</p><!--l. 212--><p class="indent" > <hr><div title="Definition"><span class="marginpar"><span +class="cmtt-9">\xmakefirstuc</span><span +class="cmtt-9"> </span></span><a + id="dx1-3011"></a> <span +class="cmtt-10">\xmakefirstuc{</span>⟨<span +class="cmitt-10">stuff</span>⟩<span +class="cmtt-10">} </span></div><hr> +</p><!--l. 214--><p class="noindent" > +This is equivalent to <span +class="cmtt-10">\expandafter\makefirstuc\expandafter{</span>⟨<span +class="cmti-10">stuff </span>⟩<span +class="cmtt-10">}</span>. So + + + +</p> + <div class="verbatim" id="verbatim-12"> +\newcommand{\abc}{abc} + <br />\xmakefirstuc{\abc} +</div> +<!--l. 219--><p class="nopar" > produces: Abc. +</p><!--l. 224--><p class="indent" > <div class="important" title="Important Note"> <span +class="cmtt-10">\xmakefirstuc </span>only performs one level expansion on the <span +class="cmti-10">first </span>object in its argument. It +does not fully expand the entire argument. </div> +</p><!--l. 228--><p class="noindent" > +</p><!--l. 230--><p class="indent" > As from version 1.10, there is now a command that fully expands the entire argument +before applying <span +class="cmtt-10">\makefirstuc</span>: +</p><!--l. 232--><p class="indent" > <hr><div title="Definition"><span class="marginpar"><span +class="cmtt-9">\emakefirstuc</span><span +class="cmtt-9"> </span></span><a + id="dx1-3012"></a> <span +class="cmtt-10">\emakefirstuc{</span>⟨<span +class="cmitt-10">text</span>⟩<span +class="cmtt-10">} </span></div><hr> +</p><!--l. 234--><p class="noindent" > +</p><!--l. 236--><p class="indent" > Examples: + + + +</p> + <div class="verbatim" id="verbatim-13"> +\newcommand{\abc}{\xyz a} + <br />\newcommand{\xyz}{xyz} + <br />No expansion: \makefirstuc{\abc}. + <br />First object one-level expansion: \xmakefirstuc{\abc}. + <br />Fully expanded: \emakefirstuc{\abc}. +</div> +<!--l. 243--><p class="nopar" > produces: No expansion: XYZA. First object one-level expansion: XYZa. Fully expanded: +Xyza. +</p><!--l. 251--><p class="indent" > If you use <span +class="cmss-10">mfirstuc </span>without the <span +class="cmss-10">glossaries</span><a + id="dx1-3013"></a> package, the standard <span +class="cmtt-10">\MakeUppercase </span>command +is used. If used with <span +class="cmss-10">glossaries</span><a + id="dx1-3014"></a>, <span +class="cmtt-10">\MakeTextUppercase</span><a + id="dx1-3015"></a> (defined by the <span +class="cmss-10">textcase</span><a + id="dx1-3016"></a> package) is used +instead. If you are using <span +class="cmss-10">mfirstuc </span>without the <span +class="cmss-10">glossaries </span>package and want to use +<span +class="cmtt-10">\MakeTextUppercase</span><a + id="dx1-3017"></a> instead, you can redefine +</p><!--l. 257--><p class="indent" > <hr><div title="Definition"><span class="marginpar"><span +class="cmtt-9">\glsmakefirstuc</span><span +class="cmtt-9"> </span></span><a + id="dx1-3018"></a> <span +class="cmtt-10">\glsmakefirstuc{</span>⟨<span +class="cmitt-10">text</span>⟩<span +class="cmtt-10">} </span></div><hr> +</p><!--l. 259--><p class="noindent" > +For example: + + + +</p> + <div class="verbatim" id="verbatim-14"> +\renewcommand{\glsmakefirstuc}[1]{\MakeTextUppercase #1} +</div> +<!--l. 263--><p class="nopar" > Remember to also load <span +class="cmss-10">textcase</span><a + id="dx1-3019"></a> (<span +class="cmss-10">glossaries </span>loads this automatically). + + + +</p> +<!--l. 267--><p class="indent" > </div> +</p><!--l. 267--><p class="noindent" ><a +href="#top">Top</a><div class="chapter"><h2 class="chapterHead">3. <a + id="sec:capitalisewords"></a>Capitalise the First Letter of Each Word in a Phrase or Sentence (Title Case)</h2> +</p><!--l. 270--><p class="indent" > New to mfirstuc v1.06: +</p><!--l. 271--><p class="indent" > <hr><div title="Definition"><span class="marginpar"><span +class="cmtt-9">\capitalisewords</span><span +class="cmtt-9"> </span></span><a + id="dx1-4001"></a> <span +class="cmtt-10">\capitalisewords{</span>⟨<span +class="cmitt-10">text</span>⟩<span +class="cmtt-10">} </span></div><hr> +</p><!--l. 273--><p class="noindent" > +This command applies <span +class="cmtt-10">\makefirstuc</span><a + id="dx1-4002"></a> to each word in ⟨<span +class="cmti-10">text</span>⟩ 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 <span class="obeylines-h"><span class="verb"><span +class="cmtt-10">~</span></span></span> or <span +class="cmtt-10">\space</span>. Note that no expansion is performed on ⟨<span +class="cmti-10">text</span>⟩. See <a +href="#sec:nocap"><span +class="cmsy-10">§</span>3.2 +</a><a +href="#sec:nocap">Excluding Words From Case-Changing<!--tex4ht:ref: sec:nocap --></a> for excluding words (such as “of”) from the +case-changing. +</p><!--l. 281--><p class="indent" > The actual capitalisation of each word is done using (new to version 2.03): +</p><!--l. 283--><p class="indent" > <hr><div title="Definition"><span class="marginpar"><span +class="cmtt-9">\MFUcapword</span><span +class="cmtt-9"> </span></span><a + id="dx1-4003"></a> <span +class="cmtt-10">\MFUcapword{</span>⟨<span +class="cmitt-10">word</span>⟩<span +class="cmtt-10">} </span></div><hr> +</p><!--l. 285--><p class="noindent" > +This just does <span +class="cmtt-10">\makefirstuc{</span>⟨<span +class="cmti-10">word</span>⟩<span +class="cmtt-10">} </span>by default, but its behaviour is determined by the +conditional: +</p><!--l. 288--><p class="indent" > <hr><div title="Definition"><span class="marginpar"><span +class="cmtt-9">\ifMFUhyphen</span><span +class="cmtt-9"> </span></span><a + id="dx1-4004"></a> <span +class="cmtt-10">\ifMFUhyphen </span></div><hr> +</p><!--l. 290--><p class="noindent" > +</p><!--l. 292--><p class="indent" > If you want to title case each part of a compound word containing hyphens, you can enable +this using +</p><!--l. 294--><p class="indent" > <hr><div title="Definition"><span class="marginpar"><span +class="cmtt-9">\MFUhyphentrue</span><span +class="cmtt-9"> </span></span><a + id="dx1-4005"></a> <span +class="cmtt-10">\MFUhyphentrue </span></div><hr> +</p><!--l. 296--><p class="noindent" > +or switch it back off again using: +</p><!--l. 298--><p class="indent" > <hr><div title="Definition"><span class="marginpar"><span +class="cmtt-9">\MFUhyphenfalse</span><span +class="cmtt-9"> </span></span><a + id="dx1-4006"></a> <span +class="cmtt-10">\MFUhyphenfalse </span></div><hr> +</p><!--l. 300--><p class="noindent" > +Compare + + + +</p> + <div class="verbatim" id="verbatim-15"> +\capitalisewords{server-side includes} +</div> +<!--l. 304--><p class="nopar" > which produces: <spacer type=vertical size=10><span class="obeylines-h"> + <br />Server-side Includes + <br /><spacer type=vertical size=10></span> +with + + + +</p> + <div class="verbatim" id="verbatim-16"> +\MFUhyphentrue + <br />\capitalisewords{server-side includes} +</div> +<!--l. 313--><p class="nopar" > which produces: <spacer type=vertical size=10><span class="obeylines-h"> + <br />Server-Side Includes + <br /><spacer type=vertical size=10></span> +</p><!--l. 320--><p class="indent" > Formatting for the entire phrase must go outside <span +class="cmtt-10">\capitalisewords </span>(unlike +<span +class="cmtt-10">\makefirstuc</span>). Compare: + + + +</p> + <div class="verbatim" id="verbatim-17"> +\capitalisewords{\textbf{a sample phrase}} +</div> +<!--l. 324--><p class="nopar" > which produces: <spacer type=vertical size=10><span class="obeylines-h"> + <br /><span +class="cmbx-10">A sample phrase</span> + <br /><spacer type=vertical size=10></span> +with: + + + +</p> + <div class="verbatim" id="verbatim-18"> +\textbf{\capitalisewords{a sample phrase}} +</div> +<!--l. 332--><p class="nopar" > which produces: <spacer type=vertical size=10><span class="obeylines-h"> + <br /><span +class="cmbx-10">A Sample Phrase</span> + <br /><spacer type=vertical size=10></span> +</p><!--l. 338--><p class="indent" > As from version 2.03, there is now a command for phrases that may include a formatting +command: +</p><!--l. 341--><p class="indent" > <hr><div title="Definition"><span +class="cmtt-10">\capitalisefmtwords{</span>⟨<span +class="cmitt-10">phrase</span>⟩<span +class="cmtt-10">} </span></div><hr> +</p><!--l. 342--><p class="noindent" > +where ⟨<span +class="cmti-10">phrase</span>⟩ may be just words (as with <span +class="cmtt-10">\capitalisewords</span>) or may be entirely enclosed in a +formatting command in the form </p><div class="alltt"> +<div class="obeylines-v"> +<span +class="cmtt-10">\capitalisefmtwords</span><span +class="cmsy-10">{</span>⟨<span +class="cmitt-10">cs</span>⟩<span +class="cmtt-10">{</span>⟨<span +class="cmitt-10">phrase</span>⟩<span +class="cmtt-10">}</span><span +class="cmsy-10">}</span> +</div> +</div> or contain formatted sub-phrases <div class="alltt"> +<div class="obeylines-v"> +<span +class="cmtt-10">\capitalisefmtwords</span><span +class="cmsy-10">{</span>⟨<span +class="cmitt-10">words</span>⟩<span +class="cmtt-10"> </span>⟨<span +class="cmitt-10">cs</span>⟩<span +class="cmtt-10">{</span>⟨<span +class="cmitt-10">sub-phrase</span>⟩<span +class="cmtt-10">}</span><span +class="cmtt-10"> </span>⟨<span +class="cmitt-10">words</span>⟩<span +class="cmsy-10">}</span> +</div> +</div> Avoid scoped declarations. +<!--l. 354--><p class="indent" > <div class="important" title="Important Note"> <span +class="cmtt-10">\capitalisefmtwords </span>is only designed for phrases that contain text-block commands +with a single argument, which should be a word or sub-phrase. Anything more complicated is +likely to break. Instead, use the starred form or <span +class="cmtt-10">\capitalisewords</span>. </div> +</p><!--l. 360--><p class="noindent" > +</p><!--l. 362--><p class="indent" > The starred form only permits a text-block command at the start of the phrase. +</p><!--l. 365--><p class="indent" > Examples: + </p><ol class="enumerate1" > + <li + class="enumerate" id="x1-4008x1">Phrase entirely enclosed in a formatting command: + + + + <div class="verbatim" id="verbatim-19"> + \capitalisefmtwords{\textbf{a small book of rhyme}} +</div> + <!--l. 370--><p class="nopar" > produces: <spacer type=vertical size=10><span class="obeylines-h"> + <br /><span +class="cmbx-10">A Small Book Of Rhyme</span> + <br /><spacer type=vertical size=10></span> + </p></li> + <li + class="enumerate" id="x1-4010x2">Sub-phrase enclosed in a formatting command: + + + + <div class="verbatim" id="verbatim-20"> + \capitalisefmtwords{a \textbf{small book} of rhyme} +</div> + <!--l. 379--><p class="nopar" > produces: <spacer type=vertical size=10><span class="obeylines-h"> + <br />A <span +class="cmbx-10">Small Book </span>Of Rhyme + <br /><spacer type=vertical size=10></span> + </p></li> + <li + class="enumerate" id="x1-4012x3">Nested text-block commands: + + + + <div class="verbatim" id="verbatim-21"> + \capitalisefmtwords{\textbf{a \emph{small book}} of rhyme} +</div> + <!--l. 388--><p class="nopar" > produces: <spacer type=vertical size=10><span class="obeylines-h"> + <br /><span +class="cmbx-10">A </span><span +class="cmbxti-10">Small Book </span>Of Rhyme + <br /><spacer type=vertical size=10></span> + </p></li> + <li + class="enumerate" id="x1-4014x4">Indicating words that shouldn’t have the case changed (see <a +href="#sec:nocap"><span +class="cmsy-10">§</span>3.2 </a><a +href="#sec:nocap">Excluding Words From + Case-Changing<!--tex4ht:ref: sec:nocap --></a>): + + + + <div class="verbatim" id="verbatim-22"> + \MFUnocap{of} +  <br />\capitalisefmtwords{\textbf{a \emph{small book}} of rhyme} +</div> + <!--l. 399--><p class="nopar" > produces: <spacer type=vertical size=10><span class="obeylines-h"> + <br /><span +class="cmbx-10">A </span><span +class="cmbxti-10">Small Book </span>of Rhyme + <br /><spacer type=vertical size=10></span> + </p></li> + <li + class="enumerate" id="x1-4016x5">Starred form: + + + + <div class="verbatim" id="verbatim-23"> + \MFUnocap{of} +  <br />\capitalisefmtwords*{\emph{a small book of rhyme}} +</div> + <!--l. 410--><p class="nopar" > produces: <spacer type=vertical size=10><span class="obeylines-h"> + <br /><span +class="cmti-10">A Small Book of Rhyme</span> + <br /><spacer type=vertical size=10></span> + </p></li> + <li + class="enumerate" id="x1-4018x6">The starred form also works with just text (no text-block command): + + + + <div class="verbatim" id="verbatim-24"> + \MFUnocap{of} +  <br />\capitalisefmtwords*{a small book of rhyme} +</div> + <!--l. 422--><p class="nopar" > produces: <spacer type=vertical size=10><span class="obeylines-h"> + <br />A Small Book of Rhyme + <br /><spacer type=vertical size=10></span> +</p> + </li></ol> +<!--l. 431--><p class="indent" > 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 + + + +</p> + <div class="verbatim" id="verbatim-25"> +\MFUnocap{of} + <br />\capitalisefmtwords*{\emph{a small} book \textbf{of rhyme}} +</div> +<!--l. 438--><p class="nopar" > produces: <spacer type=vertical size=10><span class="obeylines-h"> + <br /><span +class="cmti-10">A Small </span>Book <span +class="cmbx-10">Of rhyme</span> + <br /><spacer type=vertical size=10></span> +(In this case <span class="obeylines-h"><span class="verb"><span +class="cmtt-10">\textbf{of</span><span +class="cmtt-10"> rhyme}</span></span></span> is considered a single word.) Similarly if the text-block +command occurs in the middle of the argument: + + + +</p> + <div class="verbatim" id="verbatim-26"> +\MFUnocap{of} + <br />\capitalisefmtwords*{a \emph{very small} book of rhyme} +</div> +<!--l. 450--><p class="nopar" > produces: <spacer type=vertical size=10><span class="obeylines-h"> + <br />A <span +class="cmti-10">Very small </span>Book of Rhyme + <br /><spacer type=vertical size=10></span> +(In this case <span class="obeylines-h"><span class="verb"><span +class="cmtt-10">\emph{very</span><span +class="cmtt-10"> small}</span></span></span> is considered a single word.) +</p><!--l. 459--><p class="indent" > Grouping causes interference: + + + +</p> + <div class="verbatim" id="verbatim-27"> +\capitalisefmtwords{{a \emph{small book}} of rhyme} +</div> +<!--l. 462--><p class="nopar" > produces: <spacer type=vertical size=10><span class="obeylines-h"> + <br />A <span +class="cmti-10">Small book </span>Of Rhyme + <br /><spacer type=vertical size=10></span> +As with all the commands described here, avoid declarations. For example, the following +fails: + + + +</p> + <div class="verbatim" id="verbatim-28"> +\capitalisefmtwords{{\bfseries a \emph{small book}} of rhyme} +</div> +<!--l. 471--><p class="nopar" > produces: <spacer type=vertical size=10><span class="obeylines-h"> + <br />a <span +class="cmti-10">Small book </span>Of Rhyme + <br /><spacer type=vertical size=10></span> +</p><!--l. 477--><p class="indent" > Avoid complicated commands in the unstarred version. For example, the following +breaks: + + + +</p> + <div class="verbatim" id="verbatim-29"> +\newcommand*{\swap}[2]{{#2}{#1}} + <br />\capitalisefmtwords{a \swap{bo}{ok} of rhyme} +</div> +<!--l. 482--><p class="nopar" > However it works okay with the starred form and the simpler <span +class="cmtt-10">\capitalisewords</span>: + + + +</p> + <div class="verbatim" id="verbatim-30"> +\newcommand*{\swap}[2]{{#2}{#1}} + <br />\capitalisefmtwords*{a \swap{bo}{ok} of rhyme} + <br />\capitalisewords{a \swap{bo}{ok} of rhyme} +</div> +<!--l. 490--><p class="nopar" > Produces: <spacer type=vertical size=10><span class="obeylines-h"> + <br />A okBo Of Rhyme + <br />A okBo Of Rhyme + <br /><spacer type=vertical size=10></span> +Note that the case change is applied to the first argument. +</p><!--l. 500--><p class="indent" > <hr><div title="Definition"><span class="marginpar"><span +class="cmtt-9">\xcapitalisewords</span><span +class="cmtt-9"> </span></span><a + id="dx1-4019"></a> <span +class="cmtt-10">\xcapitalisewords{</span>⟨<span +class="cmitt-10">text</span>⟩<span +class="cmtt-10">} </span></div><hr> +</p><!--l. 502--><p class="noindent" > +This is a short cut for <span +class="cmtt-10">\expandafter\capitalisewords\expandafter{</span>⟨<span +class="cmti-10">text</span>⟩<span +class="cmtt-10">}</span>. +</p><!--l. 506--><p class="indent" > As from version 1.10, there is now a command that fully expands the entire argument +before applying <span +class="cmtt-10">\capitalisewords</span>: +</p><!--l. 508--><p class="indent" > <hr><div title="Definition"><span class="marginpar"><span +class="cmtt-9">\ecapitalisewords</span><span +class="cmtt-9"> </span></span><a + id="dx1-4020"></a> <span +class="cmtt-10">\ecapitalisewords{</span>⟨<span +class="cmitt-10">text</span>⟩<span +class="cmtt-10">} </span></div><hr> +</p><!--l. 510--><p class="noindent" > +</p><!--l. 512--><p class="indent" > There are also similar shortcut commands for the version that allows text-block +commands: +</p><!--l. 514--><p class="indent" > <hr><div title="Definition"><span class="marginpar"><span +class="cmtt-9">\xcapitalisefmtwords</span><span +class="cmtt-9"> </span></span><a + id="dx1-4021"></a> <span +class="cmtt-10">\xcapitalisefmtwords{</span>⟨<span +class="cmitt-10">text</span>⟩<span +class="cmtt-10">} </span></div><hr> +</p><!--l. 516--><p class="noindent" > +The unstarred version is a short cut for <span +class="cmtt-10">\expandafter\capitalisefmtwords\expandafter</span> +<span +class="cmtt-10">{</span>⟨<span +class="cmti-10">text</span>⟩<span +class="cmtt-10">}</span>. Similarly the starred version of <span +class="cmtt-10">\xcapitalisefmtwords </span>uses the starred version of +<span +class="cmtt-10">\capitalisefmtwords</span>. +</p><!--l. 522--><p class="indent" > For full expansion: +</p><!--l. 523--><p class="indent" > <hr><div title="Definition"><span class="marginpar"><span +class="cmtt-9">\ecapitalisefmtwords</span><span +class="cmtt-9"> </span></span><a + id="dx1-4022"></a> <span +class="cmtt-10">\ecapitalisefmtwords{</span>⟨<span +class="cmitt-10">text</span>⟩<span +class="cmtt-10">} </span></div><hr> +</p><!--l. 525--><p class="noindent" > +Take care with this as it may expand non-robust semantic commands to replacement +text that breaks the functioning of <span +class="cmtt-10">\capitalisefmtwords</span>. Use robust semantic +commands where possible. Again this has a starred version that uses the starred form of +<span +class="cmtt-10">\capitalisefmtwords</span>. +</p><!--l. 532--><p class="indent" > Examples: + + + +</p> + <div class="verbatim" id="verbatim-31"> +\newcommand{\abc}{\xyz\space four five} + <br />\newcommand{\xyz}{one two three} + <br />No expansion: \capitalisewords{\abc}. + <br />First object one-level expansion: \xcapitalisewords{\abc}. + <br />Fully expanded: \ecapitalisewords{\abc}. +</div> +<!--l. 539--><p class="nopar" > produces: <spacer type=vertical size=10><span class="obeylines-h"> + <br />No expansion: ONE TWO THREE FOUR FIVE. + <br />First object one-level expansion: ONE TWO THREE four Five. + <br />Fully expanded: One Two Three Four Five. + <br /><spacer type=vertical size=10></span> +</p><!--l. 549--><p class="indent" > (Remember that the spaces need to be explicit. In the second case above, using +<span +class="cmtt-10">\xcapitalisewords</span>, the space before “four” has been hidden within <span +class="cmtt-10">\space </span>so it’s not +recognised as a word boundary, but in the third case, <span +class="cmtt-10">\space </span>has been expanded to an actual +space character.) +</p><!--l. 555--><p class="indent" > Examples: + </p><ol class="enumerate1" > + <li + class="enumerate" id="x1-4024x1"> + + + + <div class="verbatim" id="verbatim-32"> + \capitalisewords{a book of rhyme.} +</div> + <!--l. 560--><p class="nopar" > produces: A Book Of Rhyme. + </p></li> + <li + class="enumerate" id="x1-4026x2"> + + + + <div class="verbatim" id="verbatim-33"> + \capitalisewords{a book\space of rhyme.} +</div> + <!--l. 567--><p class="nopar" > produces: A Book of Rhyme. + </p></li> + <li + class="enumerate" id="x1-4028x3"> + + + + <div class="verbatim" id="verbatim-34"> + \newcommand{\mytitle}{a book\space of rhyme.} +  <br />\capitalisewords{\mytitle} +</div> + <!--l. 575--><p class="nopar" > produces: A BOOK OF RHYME. (No expansion is performed on <span +class="cmtt-10">\mytitle</span>.) Compare + with next example: + </p></li> + <li + class="enumerate" id="x1-4030x4"> + + + + <div class="verbatim" id="verbatim-35"> + \newcommand{\mytitle}{a book\space of rhyme.} +  <br />\xcapitalisewords{\mytitle} +</div> + <!--l. 585--><p class="nopar" > produces: A Book of Rhyme. + </p><!--l. 589--><p class="noindent" >However + + + +</p> + <div class="verbatim" id="verbatim-36"> + \ecapitalisewords{\mytitle} +</div> + <!--l. 592--><p class="nopar" > produces: A Book Of Rhyme. (<span +class="cmtt-10">\space </span>has been expanded to an actual space + character.) + </p></li> + <li + class="enumerate" id="x1-4032x5"> + + + + <div class="verbatim" id="verbatim-37"> + \newcommand*{\swap}[2]{{#2}{#1}} +  <br />\capitalisewords{a \swap{bo}{ok} of rhyme} +  <br />\ecapitalisewords{a \swap{bo}{ok} of rhyme} +</div> + <!--l. 603--><p class="nopar" > produces: <spacer type=vertical size=10><span class="obeylines-h"> + <br />A okBo Of Rhyme + <br />A OKbo Of Rhyme + <br /><spacer type=vertical size=10></span> + This is because the argument of <span +class="cmtt-10">\ecapitalisewords </span>is fully expanded before being + passed to <span +class="cmtt-10">\capitalisewords </span>so that last example is equivalent to: + + + +</p> + <div class="verbatim" id="verbatim-38"> + \capitalisewords{a {ok}{bo} of rhyme} +</div> + <!--l. 616--><p class="nopar" ></p></li></ol> +<!--l. 619--><p class="noindent" ><a +href="#top">Top</a><h3 class="sectionHead"></p><h3 class="sectionHead"><span class="titlemark">3.1 </span> <a + id="sec:pdfbookmarks"></a>PDF Bookmarks</h3> +<!--l. 622--><p class="noindent" ><div class="important" title="Important Note"> If you are using <span +class="cmss-10">hyperref</span><a + id="dx1-5001"></a> and want to use <span +class="cmtt-10">\capitalisewords</span>, <span +class="cmtt-10">\capitalisefmtwords </span>or +<span +class="cmtt-10">\makefirstuc</span><a + id="dx1-5002"></a> (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: + + + +</p> + <div class="verbatim" id="verbatim-39"> +Package hyperref Warning: Token not allowed in a PDF string + <br />(PDFDocEncoding): + <br />(hyperref)                removing `\capitalisewords' +</div> +<!--l. 632--><p class="nopar" > </div> +</p><!--l. 633--><p class="noindent" > +</p><!--l. 635--><p class="noindent" >If you want to provide an alternative for the PDF bookmark, you can use <span +class="cmss-10">hyperref</span><a + id="dx1-5003"></a>’s +<span +class="cmtt-10">\texorpdfstring</span><a + id="dx1-5004"></a> command. For example: + + + +</p> + <div class="verbatim" id="verbatim-40"> +\chapter{\texorpdfstring + <br />  {\capitalisewords{a book of rhyme}}% TeX + <br />  {A Book of Rhyme}% PDF + <br />} +</div> +<!--l. 642--><p class="nopar" > Alternatively, you can use <span +class="cmss-10">hyperref</span><a + id="dx1-5005"></a>’s mechanism for disabling commands within the +bookmarks. For example: + + + +</p> + <div class="verbatim" id="verbatim-41"> +\pdfstringdefDisableCommands{% + <br /> \let\capitalisewords\@firstofone + <br />} +</div> +<!--l. 649--><p class="nopar" > +</p><!--l. 651--><p class="indent" > See the <span +class="cmss-10">hyperref</span><a + id="dx1-5006"></a> manual for further details. +</p><!--l. 653--><p class="noindent" > +</p> +<!--l. 653--><p class="noindent" ><a +href="#top">Top</a><h3 class="sectionHead"></p><h3 class="sectionHead"><span class="titlemark">3.2 </span> <a + id="sec:nocap"></a>Excluding Words From Case-Changing</h3> +<!--l. 656--><p class="noindent" >As from v1.09, you can specify words which shouldn’t be capitalised unless they occur at the +start of ⟨<span +class="cmti-10">text</span>⟩ using: +</p><!--l. 658--><p class="indent" > <hr><div title="Definition"><span class="marginpar"><span +class="cmtt-9">\MFUnocap</span><span +class="cmtt-9"> </span></span><a + id="dx1-6001"></a> <span +class="cmtt-10">\MFUnocap{</span>⟨<span +class="cmitt-10">word</span>⟩<span +class="cmtt-10">} </span></div><hr> +</p><!--l. 660--><p class="noindent" > +This only has a local effect. The global version is: +</p><!--l. 662--><p class="indent" > <hr><div title="Definition"><span class="marginpar"><span +class="cmtt-9">\gMFUnocap</span><span +class="cmtt-9"> </span></span><a + id="dx1-6002"></a> <span +class="cmtt-10">\gMFUnocap{</span>⟨<span +class="cmitt-10">word</span>⟩<span +class="cmtt-10">} </span></div><hr> +</p><!--l. 664--><p class="noindent" > +</p><!--l. 666--><p class="indent" > For example: + + + +</p> + <div class="verbatim" id="verbatim-42"> +\capitalisewords{the wind in the willows} + <br />\MFUnocap{in}% + <br />\MFUnocap{the}% + <br />\capitalisewords{the wind in the willows} +</div> +<!--l. 674--><p class="nopar" > produces: <spacer type=vertical size=10><span class="obeylines-h"> + <br />The Wind In The Willows + <br />The Wind in the Willows + <br /><spacer type=vertical size=10></span> +The list of words that shouldn’t be capitalised can be cleared using +</p><!--l. 685--><p class="indent" > <hr><div title="Definition"><span class="marginpar"><span +class="cmtt-9">\MFUclear</span><span +class="cmtt-9"> </span></span><a + id="dx1-6003"></a> <span +class="cmtt-10">\MFUclear </span></div><hr> +</p><!--l. 687--><p class="noindent" > +</p><!--l. 689--><p class="indent" > 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: + + + +</p> + <div class="verbatim" id="verbatim-43"> +\MFUclear + <br />\capitalisewords{the {}wind in the willows} +</div> +<!--l. 695--><p class="nopar" > produces: <spacer type=vertical size=10><span class="obeylines-h"> + <br />The wind In The Willows + <br /><spacer type=vertical size=10></span> +This is also a useful way of protecting commands that shouldn’t be parsed. For +example: + + + +</p> + <div class="verbatim" id="verbatim-44"> +\capitalisewords{this is section {}\nameref{sec:nocap}.} +</div> +<!--l. 705--><p class="nopar" > produces <spacer type=vertical size=10><span class="obeylines-h"> + <br />This Is Section <a +href="#sec:nocap">Excluding Words From Case-Changing<!--tex4ht:ref: sec:nocap --></a>. + <br /><spacer type=vertical size=10></span> +(No case-changing is applied to <span class="obeylines-h"><span class="verb"><span +class="cmtt-10">\nameref{sec:nocap}</span></span></span>. It just happens to already be in title +case.) +</p><!--l. 713--><p class="indent" > The package <span +class="cmss-10">mfirstuc-english</span><a + id="dx1-6004"></a> loads <span +class="cmss-10">mfirstuc </span>and uses <span +class="cmtt-10">\MFUnocap </span>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 dispute +over whether prepositions should be capitalised, I don’t intend to add them to this +package. +</p><!--l. 720--><p class="indent" > If you want to write a similar package for another language, all you need to do is create a +file with the extension <span +class="cmtt-10">.sty </span>that starts with + + + +</p> + <div class="verbatim" id="verbatim-45"> +\NeedsTeXFormat{LaTeX2e} +</div> +<!--l. 725--><p class="nopar" > The next line should identify the package. For example, if you have called the file +<span +class="cmtt-10">mfirstuc-french.sty </span>then you need: + + + +</p> + <div class="verbatim" id="verbatim-46"> +\ProvidesPackage{mfirstuc-french} +</div> +<!--l. 730--><p class="nopar" > It’s a good idea to also add a version in the final optional argument, for example: + + + +</p> + <div class="verbatim" id="verbatim-47"> +\ProvidesPackage{mfirstuc-french}[2014/07/30 v1.0] +</div> +<!--l. 735--><p class="nopar" > Next load <span +class="cmss-10">mfirstuc</span>: + + + +</p> + <div class="verbatim" id="verbatim-48"> +\RequirePackage{mfirstuc} +</div> +<!--l. 739--><p class="nopar" > Now add all your <span +class="cmtt-10">\MFUnocap </span>commands. For example: + + + +</p> + <div class="verbatim" id="verbatim-49"> +\MFUnocap{de} +</div> +<!--l. 743--><p class="nopar" > At the end of the file add: + + + +</p> + <div class="verbatim" id="verbatim-50"> +\endinput +</div> +<!--l. 747--><p class="nopar" > +</p><!--l. 749--><p class="indent" > Put the file somewhere on <span class="TEX">T<span +class="E">E</span>X</span>’s path, and now you can use this package in your +document. You might also consider <a +href="http://ctan.org/upload" >uploading it to CTAN</a> in case other users find it +useful. + + + +</p> +<!--l. 754--><p class="indent" > </div> +</p><!--l. 754--><p class="noindent" ><a +href="#top">Top</a><div class="chapter"><h2 class="chapterHead">4. <a + id="sec:utf8"></a>UTF-8</h2> +</p><!--l. 757--><p class="indent" > The <span +class="cmtt-10">\makefirstuc </span>command works by utilizing the fact that, in most cases, <span class="TEX">T<span +class="E">E</span>X</span> 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, <span class="obeylines-h"><span class="verb"><span +class="cmtt-10">\frac12</span></span></span> instead of <span class="obeylines-h"><span class="verb"><span +class="cmtt-10">\frac{1}{2}</span></span></span> or <span class="obeylines-h"><span class="verb"><span +class="cmtt-10">x^2</span></span></span> instead of <span class="obeylines-h"><span class="verb"><span +class="cmtt-10">x^{2}</span></span></span>, although some +users frown on this practice.) +</p><!--l. 764--><p class="indent" > A simplistic version of the <span +class="cmtt-10">\makefirstuc </span>command is: + + + +</p> + <div class="verbatim" id="verbatim-51"> +\newcommand*{\FirstUC}[1]{\MakeUppercase #1} +</div> +<!--l. 767--><p class="nopar" > Here + + + +</p> + <div class="verbatim" id="verbatim-52"> +\FirstUC{abc} +</div> +<!--l. 771--><p class="nopar" > is equivalent to + + + +</p> + <div class="verbatim" id="verbatim-53"> +\MakeUppercase abc +</div> +<!--l. 775--><p class="nopar" > and since <span +class="cmtt-10">\MakeUppercase </span>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. +</p><!--l. 780--><p class="indent" > The <span +class="cmss-10">glossaries</span><a + id="dx1-7001"></a> package needs to take into account the fact that the text may be contained +in the argument of a formatting command, such as <span +class="cmtt-10">\acronymfont</span>, so <span +class="cmtt-10">\makefirstuc </span>has to be +more complicated than the trivial <span +class="cmtt-10">\FirstUC </span>shown above, but at its basic level, <span +class="cmtt-10">\makefirstuc</span> +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 </p><div class="alltt"> +<div class="obeylines-v"> +<span +class="cmtt-10">\MakeUppercase</span><span +class="cmtt-10"> </span>⟨<span +class="cmitt-10">stuff</span>⟩ +</div> +</div> works, then <div class="alltt"> +<div class="obeylines-v"> +<span +class="cmtt-10">\makefirstuc{</span>⟨<span +class="cmitt-10">stuff</span>⟩<span +class="cmtt-10">}</span> +</div> +</div> should also work and so should <div class="alltt"> +<div class="obeylines-v"> +<span +class="cmtt-10">\makefirstuc</span><span +class="cmsy-10">{</span><span +class="cmtt-10">\foo{</span>⟨<span +class="cmitt-10">stuff</span>⟩<span +class="cmtt-10">}</span><span +class="cmsy-10">}</span> +</div> +</div> but if <div class="alltt"> +<div class="obeylines-v"> +<span +class="cmtt-10">\MakeUppercase</span><span +class="cmtt-10"> </span>⟨<span +class="cmitt-10">stuff</span>⟩ +</div> +</div> doesn’t work, then neither will <div class="alltt"> +<div class="obeylines-v"> +<span +class="cmtt-10">\makefirstuc{</span>⟨<span +class="cmitt-10">stuff</span>⟩<span +class="cmtt-10">}</span> +</div> +</div> nor <div class="alltt"> +<div class="obeylines-v"> +<span +class="cmtt-10">\makefirstuc</span><span +class="cmsy-10">{</span><span +class="cmtt-10">\foo{</span>⟨<span +class="cmitt-10">stuff</span>⟩<span +class="cmtt-10">}</span><span +class="cmsy-10">}</span> +</div> +</div> +<!--l. 812--><p class="indent" > Try the following document: </p><div class="alltt"> + + + +<div class="obeylines-v"> +<span +class="cmtt-10">\documentclass</span><span +class="cmsy-10">{</span><span +class="cmtt-10">article</span><span +class="cmsy-10">}</span> +<br /> +<br /><span +class="cmtt-10">\usepackage[utf8]</span><span +class="cmsy-10">{</span><span +class="cmtt-10">inputenc</span><span +class="cmsy-10">}</span> +<br /><span +class="cmtt-10">\usepackage[T1]</span><span +class="cmsy-10">{</span><span +class="cmtt-10">fontenc</span><span +class="cmsy-10">}</span> +<br /> +<br /><span +class="cmtt-10">\begin</span><span +class="cmsy-10">{</span><span +class="cmtt-10">document</span><span +class="cmsy-10">}</span> +<br /> +<br /><span +class="cmtt-10">\MakeUppercase</span><span +class="cmtt-10"> </span><span +class="cmtt-10">ã</span><span +class="cmtt-10">bc</span> +<br /> +<br /><span +class="cmtt-10">\end</span><span +class="cmsy-10">{</span><span +class="cmtt-10">document</span><span +class="cmsy-10">}</span> +</div> +</div> +<!--l. 826--><p class="indent" > This will result in the error: + + + +</p> + <div class="verbatim" id="verbatim-54"> +! Argument of \UTFviii@two@octets has an extra }. +</div> +<!--l. 829--><p class="nopar" > This is why <span class="obeylines-h"><span class="verb"><span +class="cmtt-10">\makefirstuc{</span></span></span><span +class="cmtt-10">ã</span><span +class="cmtt-10">bc</span><span class="obeylines-h"><span class="verb"><span +class="cmtt-10">}</span></span></span> won’t work. It will only work if the character <span +class="cmtt-10">ã</span> is placed +inside a group. +</p><!--l. 834--><p class="indent" > The reason for this error message is due to <span class="TEX">T<span +class="E">E</span>X</span> having been written before Unicode was +invented. Although <span +class="cmtt-10">ã</span> may look like a single character in your text editor, from <span class="TEX">T<span +class="E">E</span>X</span>’s point +of view it’s <span +class="cmti-10">two </span>tokens. So </p><div class="alltt"> +<div class="obeylines-v"> +<span +class="cmtt-10">\MakeUppercase</span><span +class="cmtt-10"> </span><span +class="cmtt-10">ã</span><span +class="cmtt-10">bc</span> +</div> +</div> tries to apply <span +class="cmtt-10">\MakeUppercase </span>to just the first octet of ã. 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 ã) must be +grouped: <div class="alltt"> +<div class="obeylines-v"> +<span +class="cmtt-10">\MakeUppercase</span><span +class="cmsy-10">{</span><span +class="cmtt-10">ã</span><span +class="cmsy-10">}</span><span +class="cmtt-10">bc</span> +</div> +</div> +<!--l. 850--><p class="indent" > Note that XeTeX (and therefore XeLaTeX) is a modern implementation of <span class="TEX">T<span +class="E">E</span>X</span> 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: </p><div class="alltt"> +<div class="obeylines-v"> +<span +class="cmtt-10">\documentclass</span><span +class="cmsy-10">{</span><span +class="cmtt-10">article</span><span +class="cmsy-10">}</span> +<br /> +<br /><span +class="cmtt-10">\usepackage</span><span +class="cmsy-10">{</span><span +class="cmtt-10">fontspec</span><span +class="cmsy-10">}</span> +<br /> +<br /><span +class="cmtt-10">\begin</span><span +class="cmsy-10">{</span><span +class="cmtt-10">document</span><span +class="cmsy-10">}</span> +<br /> +<br /><span +class="cmtt-10">\MakeUppercase</span><span +class="cmtt-10"> </span><span +class="cmtt-10">ã</span><span +class="cmtt-10">bc</span> +<br /> +<br /><span +class="cmtt-10">\end</span><span +class="cmsy-10">{</span><span +class="cmtt-10">document</span><span +class="cmsy-10">}</span> +</div> +</div> +<!--l. 866--><p class="indent" > This works correctly when compiled with XeLaTeX. This means that <span +class="cmtt-10">\makefirstuc</span><span class="obeylines-h"><span class="verb"><span +class="cmtt-10">{</span></span></span><span +class="cmtt-10">ã</span><span +class="cmtt-10">bc</span><span class="obeylines-h"><span class="verb"><span +class="cmtt-10">}</span></span></span> +will work <span +class="cmti-10">provided you use XeLaTeX</span><span +class="cmti-10"> and the </span><span +class="cmssi-10">fontspec</span><a + id="dx1-7002"></a> <span +class="cmti-10">package</span>. +</p><!--l. 870--><p class="indent" > Version 2.24 of <span +class="cmss-10">datatool-base</span><a + id="dx1-7003"></a> added the command <span +class="cmtt-10">\dtl@getfirst@UTFviii </span>which +attempts to grab both octets. If this command has been defined, <span +class="cmss-10">mfirstuc</span><a + id="dx1-7004"></a> will use it when it +tries to split the first character from the rest of the word. See the <a +href="http://mirrors.ctan.org/macros/latex/contrib/datatool/datatool-code.pdf" ><span +class="cmss-10">datatool </span>documented code</a> +for further details. + + + +</p> +<!--l. 2--><p class="indent" > </div> +</p><!--l. 2--><p class="noindent" ><a +href="#top">Top</a></p><h2 class="likechapterHead"><a + id="x1-80004"></a>Index</h2> + <span +class="cmbx-10">C</span> + <div class="theindex"><span class="index-item"><span class="obeylines-h"><span class="verb"><span +class="cmtt-10">\capitalisewords</span></span></span>  <span +class="cmti-10">8 </span><br /></span> +<p class="theindex"> <span +class="cmbx-10">D</span> +<span class="index-item"><span +class="cmss-10">datatool-base </span>package  6, 19 <br /></span> +</p><p class="theindex"> <span +class="cmbx-10">E</span> +<span class="index-item"><span class="obeylines-h"><span class="verb"><span +class="cmtt-10">\ecapitalisefmtwords</span></span></span>  <span +class="cmti-10">12 </span><br /></span> +<span class="index-item"><span class="obeylines-h"><span class="verb"><span +class="cmtt-10">\ecapitalisewords</span></span></span>  <span +class="cmti-10">12 </span><br /></span> +<span class="index-item"><span class="obeylines-h"><span class="verb"><span +class="cmtt-10">\emakefirstuc</span></span></span>  <span +class="cmti-10">7 </span><br /></span> +</p><p class="theindex"> <span +class="cmbx-10">F</span> +<span class="index-item"><span +class="cmss-10">fontspec </span>package  19 <br /></span> +</p><p class="theindex"> <span +class="cmbx-10">G</span> +<span class="index-item"><span +class="cmss-10">glossaries </span>package  6, 7, 17 <br /></span> +<span class="index-item"><span class="obeylines-h"><span class="verb"><span +class="cmtt-10">\glsmakefirstuc</span></span></span>  <span +class="cmti-10">7 </span><br /></span> +<span class="index-item"><span class="obeylines-h"><span class="verb"><span +class="cmtt-10">\gMFUnocap</span></span></span>  <span +class="cmti-10">15 </span><br /></span> +</p><p class="theindex"> <span +class="cmbx-10">H</span> +<span class="index-item"><span +class="cmss-10">hyperref </span>package  14 <br /></span> +</p><p class="theindex"> <span +class="cmbx-10">I</span> +<span class="index-item"><span class="obeylines-h"><span class="verb"><span +class="cmtt-10">\ifMFUhyphen</span></span></span>  <span +class="cmti-10">8 </span><br /></span> +<span class="index-item"><span +class="cmss-10">inputenc </span>package  6 <br /></span> +</p><p class="theindex"> <span +class="cmbx-10">M</span> +<span class="index-item"><span class="obeylines-h"><span class="verb"><span +class="cmtt-10">\makefirstuc</span></span></span>  <span +class="cmti-10">5 </span><br /></span> +<span class="index-item"><span +class="cmss-10">mfirstuc </span>package  6, 19 <br /></span> + + + +<span class="index-item"><span +class="cmss-10">mfirstuc-english </span>package  15 <br /></span> +<span class="index-item"><span class="obeylines-h"><span class="verb"><span +class="cmtt-10">\MFUcapword</span></span></span>  <span +class="cmti-10">8 </span><br /></span> +<span class="index-item"><span class="obeylines-h"><span class="verb"><span +class="cmtt-10">\MFUclear</span></span></span>  <span +class="cmti-10">15 </span><br /></span> +<span class="index-item"><span class="obeylines-h"><span class="verb"><span +class="cmtt-10">\MFUhyphenfalse</span></span></span>  <span +class="cmti-10">8 </span><br /></span> +<span class="index-item"><span class="obeylines-h"><span class="verb"><span +class="cmtt-10">\MFUhyphentrue</span></span></span>  <span +class="cmti-10">8 </span><br /></span> +<span class="index-item"><span class="obeylines-h"><span class="verb"><span +class="cmtt-10">\MFUnocap</span></span></span>  <span +class="cmti-10">15 </span><br /></span> +</p><p class="theindex"> <span +class="cmbx-10">T</span> +<span class="index-item"><span +class="cmss-10">textcase </span>package  7 <br /></span> +</p><p class="theindex"> <span +class="cmbx-10">X</span> +<span class="index-item"><span class="obeylines-h"><span class="verb"><span +class="cmtt-10">\xcapitalisefmtwords</span></span></span>  <span +class="cmti-10">12 </span><br /></span> +<span class="index-item"><span class="obeylines-h"><span class="verb"><span +class="cmtt-10">\xcapitalisewords</span></span></span>  <span +class="cmti-10">12 </span><br /></span> +<span class="index-item"><span class="obeylines-h"><span class="verb"><span +class="cmtt-10">\xmakefirstuc</span></span></span>  <span +class="cmti-10">7 </span><br /></span> +</p></div> + +</body></html> + + + + diff --git a/macros/latex/contrib/mfirstuc/mfirstuc-manual.pdf b/macros/latex/contrib/mfirstuc/mfirstuc-manual.pdf Binary files differnew file mode 100644 index 0000000000..6b5940eff8 --- /dev/null +++ b/macros/latex/contrib/mfirstuc/mfirstuc-manual.pdf diff --git a/macros/latex/contrib/mfirstuc/mfirstuc-manual.tex b/macros/latex/contrib/mfirstuc/mfirstuc-manual.tex new file mode 100644 index 0000000000..71430da10a --- /dev/null +++ b/macros/latex/contrib/mfirstuc/mfirstuc-manual.tex @@ -0,0 +1,878 @@ +\documentclass[report]{nlctdoc} + +\usepackage[a4paper,left=1.75in]{geometry} +\usepackage{alltt} +\usepackage{mfirstuc} +\usepackage{pifont} +\usepackage[utf8]{inputenc} +\ifpdf + \usepackage[T1]{fontenc} + \usepackage{metalogo} +\else + \providecommand{\XeLaTeX}{XeLaTeX} + \providecommand{\XeTeX}{XeTeX} +\fi +\usepackage{cmap} +\usepackage[colorlinks, + bookmarks, + hyperindex=false, + pdfauthor={Nicola L.C. Talbot}, + pdftitle={mfirstuc.sty: uppercasing first letter}, + pdfkeywords={LaTeX,package,uppercase}]{hyperref} + +\IndexPrologue{% +\chapter*{\indexname}\markright{\indexname} +\addcontentsline{toc}{chapter}{\indexname}} + +\begin{document} +\MakeShortVerb{|} + \title{mfirstuc.sty v2.06: +uppercasing first letter} + \author{Nicola L.C. Talbot\\[10pt] +Dickimaw Books\\ +\url{http://www.dickimaw-books.com/}} + + \date{2017-11-14} + \maketitle + \tableofcontents + + \chapter{Introduction} + \label{sec:intro} + +The \styfmt{mfirstuc} package was originally part of the +\styfmt{glossaries} bundle for use with commands like \cs{Gls}, but +as the commands provided by \styfmt{mfirstuc} may be used without +\styfmt{glossaries}, the two have been split into separately +maintained packages. + +\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}). + +\chapter{Capitalising the First Letter of a Word} +\label{sec:makefirstuc} + +A simple word can be capitalised just using the standard \LaTeX\ +upper casing command. For example, +\begin{verbatim} +\MakeUppercase word +\end{verbatim} +but for commands like \cs{Gls} the word may be embedded within the +argument of another command, such as a~font changing command. This +makes things more complicated for a~general purpose solution, so +the \styfmt{mfirstuc} package provides: +\begin{definition}[\DescribeMacro{\makefirstuc}] +\cs{makefirstuc}\marg{stuff} +\end{definition} +This makes the first object of +\meta{stuff} upper case unless \meta{stuff} starts with a control +sequence followed by a non-empty group, in which case the first +object in the group is converted to upper case. +\textbf{No expansion is performed on the argument.} + +\begin{important} +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|\textcolor{red}{text}| +you need to define, say, \verb|\red| as \verb|\color{red}| and use +\verb|\red{text}|. +\end{important} + +Examples: +\begin{itemize} +\item |\makefirstuc{abc}| produces \makefirstuc{abc}. + +\item |\makefirstuc{\emph{abc}}| produces \makefirstuc{\emph{abc}} +(\ics{MakeUppercase} has been applied to the letter \qt{a} rather +than \cs{emph}). Note however that +\begin{verbatim} +\makefirstuc{{\em abc}} +\end{verbatim} +produces \makefirstuc{{\em abc}} (first object is |{\em abc}| so +this is equivalent to |\MakeUppercase{\em abc}|), and +\begin{verbatim} +{\makefirstuc{\em abc}} +\end{verbatim} +produces {\makefirstuc{\em abc}} (|\em| doesn't have an argument +therefore first object is |\em| and so is equivalent to +|{\MakeUppercase{\em}abc}|). + +\item |\makefirstuc{{\'a}bc}| produces \makefirstuc{{\'a}bc}. + +\item |\makefirstuc{\ae bc}| produces \makefirstuc{\ae bc}. + +\item |\makefirstuc{{\ae}bc}| produces \makefirstuc{{\ae}bc}. + +\item |\makefirstuc{{ä}bc}| produces \makefirstuc{{ä}bc}. + +\end{itemize} + +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 \sty{inputenc} package). The reason for this restriction +is detailed in \sectionref{sec:utf8}. + +\textbf{New to version 2.04:} There is now limited support for +UTF-8 characters with the \sty{inputenc} package, provided that +you load \sty{datatool-base} (at least v2.24) before +\styfmt{mfirstuc} (\sty{datatool-base} is loaded automatically with newer versions +of \sty{glossaries}). If available +\sty{mfirstuc} will now use \sty{datatool-base}'s +\ics{dtl@getfirst@UTFviii} command which is still experimental. +See the \styfmt{datatool} manual for further details. + +\begin{verbatim} +\documentclass{article} + +\usepackage[T1]{fontenc} +\usepackage[utf8]{inputenc} + +\usepackage{datatool-base}[2016/01/12]% v2.24+ +\usepackage{mfirstuc} + +\begin{document} +\makefirstuc{élite} +\end{document} +\end{verbatim} +(Package ordering is important.) + +\begin{important} +In version 1.02 of \styfmt{mfirstuc}, a bug fix resulted in a change +in output if the first object is a control sequence followed by +an empty group. Prior to version 1.02, |\makefirstuc{\ae{}bc}| +produced \ae Bc. However as from version 1.02, it now produces +\AE bc. +\end{important} + +Note also that +\begin{verbatim} +\newcommand{\abc}{abc} +\makefirstuc{\abc} +\end{verbatim} +produces: ABC. This is because the first object in the argument of +\cs{makefirstuc} is \cs{abc}, so it does |\MakeUppercase{\abc}|. +Whereas: +\begin{verbatim} +\newcommand{\abc}{abc} +\expandafter\makefirstuc\expandafter{\abc} +\end{verbatim} +produces: Abc. There is a short cut command which will do this: +\begin{definition}[\DescribeMacro{\xmakefirstuc}] +\cs{xmakefirstuc}\marg{stuff} +\end{definition} +This is equivalent to \cs{expandafter}\cs{makefirstuc}\cs{expandafter}\marg{stuff}. So +\begin{verbatim} +\newcommand{\abc}{abc} +\xmakefirstuc{\abc} +\end{verbatim} +produces: +\newcommand{\abc}{abc}% +\xmakefirstuc{\abc}. + +\begin{important} +\cs{xmakefirstuc} only performs one level expansion on the +\emph{first} object in its argument. It does not fully expand the entire +argument. +\end{important} + +As from version 1.10, there is now a command that fully expands the +entire argument before applying \cs{makefirstuc}: +\begin{definition}[\DescribeMacro\emakefirstuc] +\cs{emakefirstuc}\marg{text} +\end{definition} + +Examples: +\begin{verbatim} +\newcommand{\abc}{\xyz a} +\newcommand{\xyz}{xyz} +No expansion: \makefirstuc{\abc}. +First object one-level expansion: \xmakefirstuc{\abc}. +Fully expanded: \emakefirstuc{\abc}. +\end{verbatim} +produces: +\renewcommand{\abc}{\xyz a}% +\newcommand{\xyz}{xyz} +No expansion: \makefirstuc{\abc}. +First object one-level expansion: \xmakefirstuc{\abc}. +Fully expanded: \emakefirstuc{\abc}. + +If you use \styfmt{mfirstuc} without the \sty{glossaries} package, +the standard \cs{MakeUppercase} command is used. If used with +\sty{glossaries}, \ics{MakeTextUppercase} (defined by the \sty{textcase} +package) is used instead. If you are using \styfmt{mfirstuc} +without the \styfmt{glossaries} package and want to use +\ics{MakeTextUppercase} instead, you can redefine +\begin{definition}[\DescribeMacro\glsmakefirstuc] +\cs{glsmakefirstuc}\marg{text} +\end{definition} +For example: +\begin{verbatim} +\renewcommand{\glsmakefirstuc}[1]{\MakeTextUppercase #1} +\end{verbatim} +Remember to also load \sty{textcase} (\styfmt{glossaries} loads this +automatically). + +\chapter{Capitalise the First Letter of 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} +\end{definition} +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}. 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: +\begin{verbatim} +\capitalisewords{\textbf{a sample phrase}} +\end{verbatim} +which produces: +\begin{display} +\capitalisewords{\textbf{a sample phrase}} +\end{display} +with: +\begin{verbatim} +\textbf{\capitalisewords{a sample phrase}} +\end{verbatim} +which produces: +\begin{display} +\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. + +\begin{important} +\cs{capitalisefmtwords} is only designed for phrases that contain +text-block commands with a single +argument, which should be a word or sub-phrase. Anything +more complicated is likely to break. Instead, use the +starred form or \cs{capitalisewords}. +\end{important} + +The starred form only permits a text-block command at the +start of the phrase. + +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} + +\item Starred form: +\begin{verbatim} +\MFUnocap{of} +\capitalisefmtwords*{\emph{a small book of rhyme}} +\end{verbatim} +produces: +\begin{display} +\MFUnocap{of} +\capitalisefmtwords*{\emph{a small book of rhyme}} +\end{display} + +\item The starred form also works with just text (no text-block +command): +\begin{verbatim} +\MFUnocap{of} +\capitalisefmtwords*{a small book of rhyme} +\end{verbatim} +produces: +\begin{display} +\MFUnocap{of} +\capitalisefmtwords*{a small book of rhyme} +\end{display} + +\end{enumerate} + +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 +\begin{verbatim} +\MFUnocap{of} +\capitalisefmtwords*{\emph{a small} book \textbf{of rhyme}} +\end{verbatim} +produces: +\begin{display} +\MFUnocap{of} +\capitalisefmtwords*{\emph{a small} book \textbf{of rhyme}} +\end{display} +(In this case \verb|\textbf{of rhyme}| is considered a +single word.) Similarly if the text-block command occurs +in the middle of the argument: +\begin{verbatim} +\MFUnocap{of} +\capitalisefmtwords*{a \emph{very small} book of rhyme} +\end{verbatim} +produces: +\begin{display} +\MFUnocap{of} +\capitalisefmtwords*{a \emph{very small} book of rhyme} +\end{display} +(In this case \verb|\emph{very small}| is considered a +single word.) + +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} + +Avoid complicated commands in the unstarred version. For example, +the following breaks: +\begin{verbatim} +\newcommand*{\swap}[2]{{#2}{#1}} +\capitalisefmtwords{a \swap{bo}{ok} of rhyme} +\end{verbatim} +However it works okay with the starred form and the simpler +\cs{capitalisewords}: +\begin{verbatim} +\newcommand*{\swap}[2]{{#2}{#1}} +\capitalisefmtwords*{a \swap{bo}{ok} of rhyme} + +\capitalisewords{a \swap{bo}{ok} of rhyme} +\end{verbatim} +Produces: +\begin{display} +\newcommand*{\swap}[2]{{#2}{#1}} +\capitalisefmtwords*{a \swap{bo}{ok} of rhyme} + +\capitalisewords{a \swap{bo}{ok} of rhyme} +\end{display} +Note that the case change is applied to the first argument. + +\begin{definition}[\DescribeMacro{\xcapitalisewords}] +\cs{xcapitalisewords}\marg{text} +\end{definition} +This is a short cut for +\cs{expandafter}\cs{capitalisewords}\cs{expandafter}\marg{text}. + +As from version 1.10, there is now a command that fully expands the +entire argument before applying \cs{capitalisewords}: +\begin{definition}[\DescribeMacro\ecapitalisewords] +\cs{ecapitalisewords}\marg{text} +\end{definition} + +There are also similar shortcut commands for the version that allows +text-block commands: +\begin{definition}[\DescribeMacro{\xcapitalisefmtwords}] +\cs{xcapitalisefmtwords}\marg{text} +\end{definition} +The unstarred version is a short cut for +\cs{expandafter}\cs{capitalisefmtwords}\cs{expandafter}\marg{text}. +Similarly the starred version of \cs{xcapitalisefmtwords} +uses the starred version of \cs{capitalisefmtwords}. + +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. Again this has a starred version that uses +the starred form of \cs{capitalisefmtwords}. + +Examples: +\begin{verbatim} +\newcommand{\abc}{\xyz\space four five} +\newcommand{\xyz}{one two three} +No expansion: \capitalisewords{\abc}. +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 +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.) + +Examples: +\begin{enumerate} +\item +\begin{verbatim} +\capitalisewords{a book of rhyme.} +\end{verbatim} +produces: +\capitalisewords{a book of rhyme.} + +\item +\begin{verbatim} +\capitalisewords{a book\space of rhyme.} +\end{verbatim} +produces: +\capitalisewords{a book\space of rhyme.} + +\item +\begin{verbatim} +\newcommand{\mytitle}{a book\space of rhyme.} +\capitalisewords{\mytitle} +\end{verbatim} +produces: +\newcommand{\mytitle}{a book\space of rhyme.} +\capitalisewords{\mytitle} +(No expansion is performed on \cs{mytitle}.) Compare with next example: + +\item +\begin{verbatim} +\newcommand{\mytitle}{a book\space of rhyme.} +\xcapitalisewords{\mytitle} +\end{verbatim} +produces: +\xcapitalisewords{\mytitle} + +However +\begin{verbatim} +\ecapitalisewords{\mytitle} +\end{verbatim} +produces: +\ecapitalisewords{\mytitle} +(\cs{space} has been expanded to an actual space character.) + +\item +\begin{verbatim} +\newcommand*{\swap}[2]{{#2}{#1}} +\capitalisewords{a \swap{bo}{ok} of rhyme} + +\ecapitalisewords{a \swap{bo}{ok} of rhyme} +\end{verbatim} +produces: +\begin{display} +\newcommand*{\swap}[2]{{#2}{#1}} +\capitalisewords{a \swap{bo}{ok} of rhyme} + +\ecapitalisewords{a \swap{bo}{ok} of rhyme} +\end{display} +This is because the argument of \cs{ecapitalisewords} is +fully expanded before being passed to \cs{capitalisewords} so +that last example is equivalent to: +\begin{verbatim} +\capitalisewords{a {ok}{bo} of rhyme} +\end{verbatim} +\end{enumerate} + +\section{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. + +\section{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] +\cs{MFUnocap}\marg{word} +\end{definition} +This only has a local effect. The global version is: +\begin{definition}[\DescribeMacro\gMFUnocap] +\cs{gMFUnocap}\marg{word} +\end{definition} + +For example: +\begin{verbatim} +\capitalisewords{the wind in the willows} + +\MFUnocap{in}% +\MFUnocap{the}% + +\capitalisewords{the wind in the willows} +\end{verbatim} +produces: +\begin{display} +\capitalisewords{the wind in the willows} + +\MFUnocap{in}% +\MFUnocap{the}% + +\capitalisewords{the wind in the willows} +\end{display} +The list of words that shouldn't be capitalised can be cleared using +\begin{definition}[\DescribeMacro\MFUclear] +\cs{MFUclear} +\end{definition} + +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}|. +It just happens to already be in title case.) + +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 +dispute over whether prepositions should be capitalised, I~don't +intend to add them to this package. + +If you want to write a similar package for another language, all you +need to do is create a file with the extension \texttt{.sty} +that starts with +\begin{verbatim} +\NeedsTeXFormat{LaTeX2e} +\end{verbatim} +The next line should identify the package. For example, if you have +called the file \texttt{mfirstuc-french.sty} then you need: +\begin{verbatim} +\ProvidesPackage{mfirstuc-french} +\end{verbatim} +It's a good idea to also add a version in the final optional +argument, for example: +\begin{verbatim} +\ProvidesPackage{mfirstuc-french}[2014/07/30 v1.0] +\end{verbatim} +Next load \styfmt{mfirstuc}: +\begin{verbatim} +\RequirePackage{mfirstuc} +\end{verbatim} +Now add all your \cs{MFUnocap} commands. For example: +\begin{verbatim} +\MFUnocap{de} +\end{verbatim} +At the end of the file add: +\begin{verbatim} +\endinput +\end{verbatim} + +Put the file somewhere on \TeX's path, and now you can use this +package in your document. You might also consider +\href{http://ctan.org/upload}{uploading it to CTAN} in case +other users find it useful. + +\chapter{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 +\begin{verbatim} +\FirstUC{abc} +\end{verbatim} +is equivalent to +\begin{verbatim} +\MakeUppercase abc +\end{verbatim} +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 +\begin{alltt} +\cs{MakeUppercase} \meta{stuff} +\end{alltt} +works, +then +\begin{alltt} +\cs{makefirstuc}\marg{stuff} +\end{alltt} +should also work and so should +\begin{alltt} +\cs{makefirstuc}\{\cs{foo}\marg{stuff}\} +\end{alltt} +but if +\begin{alltt} +\cs{MakeUppercase} \meta{stuff} +\end{alltt} +doesn't work, then neither will +\begin{alltt} +\cs{makefirstuc}\marg{stuff} +\end{alltt} +nor +\begin{alltt} +\cs{makefirstuc}\{\cs{foo}\marg{stuff}\} +\end{alltt} + +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}. + +Version 2.24 of \sty{datatool-base} added the +command \cs{dtl@getfirst@UTFviii} which attempts to grab both octets. If this command +has been defined, \sty{mfirstuc} will use it when it tries to split +the first character from the rest of the word. See the +\href{http://mirrors.ctan.org/macros/latex/contrib/datatool/datatool-code.pdf}{\styfmt{datatool} +documented code} for further details. + +\PrintIndex +\end{document} diff --git a/macros/latex/contrib/mfirstuc/mfirstuc.dtx b/macros/latex/contrib/mfirstuc/mfirstuc.dtx new file mode 100644 index 0000000000..708531ba48 --- /dev/null +++ b/macros/latex/contrib/mfirstuc/mfirstuc.dtx @@ -0,0 +1,1429 @@ +%\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 diff --git a/macros/latex/contrib/mfirstuc/mfirstuc.ins b/macros/latex/contrib/mfirstuc/mfirstuc.ins new file mode 100644 index 0000000000..59773096d4 --- /dev/null +++ b/macros/latex/contrib/mfirstuc/mfirstuc.ins @@ -0,0 +1,35 @@ +% mfirstuc.ins generated using makedtx version 1.2 2017/11/14 12:21 +\input docstrip + +\preamble + + mfirstuc.dtx + Copyright 2017 Nicola 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 or (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. + + This work consists of the files mfirstuc.dtx and mfirstuc.ins and the derived files mfirstuc.sty, mfirstuc-english.sty, sample-mfirstuc.tex, mfirstuc.perl. + +\endpreamble + +\askforoverwritefalse + +\generate{\file{mfirstuc.sty}{\usepreamble\defaultpreamble +\usepostamble\defaultpostamble\from{mfirstuc.dtx}{mfirstuc.sty,package}} +\file{mfirstuc-english.sty}{\usepreamble\defaultpreamble +\usepostamble\defaultpostamble\from{mfirstuc.dtx}{mfirstuc-english.sty,package}} +\file{sample-mfirstuc.tex}{\nopreamble\nopostamble\from{mfirstuc.dtx}{sample-mfirstuc.tex}} +\file{mfirstuc.perl}{\nopreamble\nopostamble\from{mfirstuc.dtx}{mfirstuc.perl}} +} + +\endbatchfile diff --git a/macros/latex/contrib/mfirstuc/sample-mfirstuc.pdf b/macros/latex/contrib/mfirstuc/sample-mfirstuc.pdf Binary files differnew file mode 100644 index 0000000000..ce43ddad2b --- /dev/null +++ b/macros/latex/contrib/mfirstuc/sample-mfirstuc.pdf diff --git a/macros/latex/contrib/mfirstuc/sample-mfirstuc.tex b/macros/latex/contrib/mfirstuc/sample-mfirstuc.tex new file mode 100644 index 0000000000..718515cb8f --- /dev/null +++ b/macros/latex/contrib/mfirstuc/sample-mfirstuc.tex @@ -0,0 +1,285 @@ + % 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}. + +\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 + +\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} |