diff options
Diffstat (limited to 'Master/texmf-dist/doc/latex/titlecaps/titlecaps.tex')
| -rw-r--r-- | Master/texmf-dist/doc/latex/titlecaps/titlecaps.tex | 405 |
1 files changed, 405 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/latex/titlecaps/titlecaps.tex b/Master/texmf-dist/doc/latex/titlecaps/titlecaps.tex new file mode 100644 index 00000000000..c5492298c93 --- /dev/null +++ b/Master/texmf-dist/doc/latex/titlecaps/titlecaps.tex @@ -0,0 +1,405 @@ +\documentclass{article} +\def\version{1.0} +%% Copyright 2013 Steven B. Segletes +% +% 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.3c 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 Steven B. Segletes. +% +\usepackage{titlecaps} +\usepackage{needspace} +\parskip 1em +\parindent 0em +\newcommand\rl{\rule{1em}{0in}} +\def\tcp{\textsf{titlecaps}} +\def\QL{\titlecap{quirks, tricks and limitations}} +\usepackage{verbatimbox} +\let\vb\verb +\def\bs{$\backslash$} +\reversemarginpar +\marginparwidth 1.6in +\newcommand\margtt[1]{\marginpar{\hfill\ttfamily#1}} +\newcommand\margcmd[1]{\marginpar{\hfill\ttfamily\char'134#1}} +\begin{document} +\begin{center} +\LARGE The {\tcp} Package\\ +\rule{0em}{.7em}\small Routines for setting rich-text input into +Titling Caps\\ +\rule{0em}{2.7em}\large Steven B. Segletes\\ +steven.b.segletes.civ@mail.mil\\ +\rule{0em}{1.7em}\today\\ +v\version +\end{center} + +\Addlcwords{for a is but and with of in as the etc on to if} +\section{\titlecap{description and commands}} + +The {\tcp} package is intended to be used to convert lower-cased text +into titling caps, wherein the first letter of every word is +capitalized, except for words designated to remain in lower case, for +example prepositions and conjunctions. While this function has been +performed elsewhere, for example in the \textsf{stringstrings} package, +it is here significantly enhanced. The \textsf{stringstrings} +implementation of titling caps is particularly limited because of its +slow speed (I criticize \textsf{stringstrings} because I wrote it). +Furthermore, that implementation only works on textual expressions, +which do not contain any font-modification commands. + +In contrast, the {\tcp} package is set up to work in conjunction with +font-modification commands that change the family, series, or shape of +the font. Likewise, it will work with the fontsize changing commands +(\vb|\tiny|, \vb|\scriptsize|\ldots\SoftSpace\vb|\Huge|) embedded in the +argument. It is also, unlike the \textsf{stringstrings} version, able +to screen out most punctuation when deciding whether a word is +predesignated as lower case. Furthermore, it looks for symbols that +might signify the beginning of a new text ``group'', such as (, [, \{, +`, and -, and thereafter titles the word that follows, even though the +first alphabetic letter is not technically at the lead of the ``word.'' + +The primary commands that have been implemented in this package are the +following:\\ +\itshape +\rl\vb|\titlecap[|option\vb|]{|rich text\vb|}|\\ +\rl\vb|\Addlcwords{|designated lower-case space-separated word list\vb|}|\\ +\rl\vb|\Resetlcwords|\\ +\upshape +In addition, the following auxiliary commands are also available:\\ +\itshape +\rl\vb|\textnc{|text\verb|}|\\ +\rl\vb|\def\converttilde{|\textup{T} or \textup{F}\vb|}|\\ +\rl\vb|\noatinsidetc|\\ +\rl\vb|\usestringstringsnames| +% (addlcwords,resetlcwords,addlcword,capitalizetitle,getargs) +\upshape + +~\\ +The \vb|\titlecap| command\margcmd{titlecap} is the primary contribution +of this package. It will (within constraints) capitalize the first +letter of each word in the argument. The primary constraint under which +it operates is the existence of a predefined lower-cased word list that +is set by the user, using the \verb|\Addlcwords| +command\margcmd{Addlcwords}. These predefined lower-cased words are +passed as an argument to \verb|\Addlcwords| in a space-separated list. +Subsequent invocations add to the existing list of predefined +lower-cased words. The user may clear the list of predefined +lower-cased words through the issuance of the \verb|\Resetlcwords| +command\margcmd{Resetlcwords}. + +When \verb|\titlecap| is invoked, it first breaks the argument into +individual pieces that constitute ``words.'' Note, however, that these +``words'' may include punctuation and text formatting commands +interspersed with the actual text. This is an essential challenge to +overcome. + +After breaking the argument into words, \verb|\titlecap| will attempt to +match each word of the argument to the list of predesignated lower-cased +words. In order to assist this process, the command (temporarily) +screens out text-formatting commands and punctuation marks from the +argument, so that their presence does not inhibit a word match with the +lower-cased word list (see {\QL} for exceptions). It +flags matches, so that these matching words will not later be titled. + +The command will then reconstitute the ``words'' of the argument with +their punctuation and font-changing commands intact. In the default +invocation, \verb|\titlecap| will capitalize the first word of the +argument, even if that word is on the lower-cased word list. This +default may be overridden with the command's optional argument. +Employing anything other than a capital ``P'' will treat the first word +of the argument like any other word, meaning it will be title-capped +only if it does not appear on the predesignated lower-cased word list. + +The algorithm that searches the ``words'' of the argument character by +character, in order to titlecap the first letter of a word, is, generally +speaking, able to process only textual content. However, special +provisions have been enacted to handle the following text-formatting +commands within the argument of \verb|\titlecap|: + +\begin{minipage}{\textwidth} +\rl +\begin{tabular}{llll} +\verb|\textup| & \verb|\upshape| & \verb|\tiny| & \verb|\Huge|\\ +\verb|\textit| & \verb|\itshape| & \verb|\scriptsize| & + \verb|\textnc|\footnote{This command is introduced by this package.}\\ +\verb|\textsc| & \verb|\scshape| & \verb|\footnotesize|&\\ +\verb|\textsl| & \verb|\slshape| & \verb|\small|&\\ +\verb|\textmd| & \verb|\mdseries| & \verb|\normalsize|&\\ +\verb|\textbf| & \verb|\bfseries| & \verb|\large|&\\ +\verb|\textrm| & \verb|\rmfamily| & \verb|\Large|&\\ +\verb|\textsf| & \verb|\sffamily| & \verb|\LARGE|&\\ +\verb|\texttt| & \verb|\ttfamily| & \verb|\huge|&\\ +\end{tabular} +\end{minipage} + +Other macros can generally be handled in the argument to +\verb|\titlecap| only if they expand to textual content. + +\needspace{3\baselineskip} +Once the first word of the argument has been titled ``by force'' (or +not, with the use of the optional arguement), the command proceeds +through each word, deciding whether or not to title the word, based on +the lower-cased word flag that has previously been set. The {\tcp} +package can notably handle the titling of strings containing both +diacritical marks found in various languages (such as \`o, \'o, \^o, +\"o, \~o, \=o, \.o, \u o, \v o, \H o, \t{oo}, \c o, \d o, and \b o), as +well as national symbols (such as \oe, \ae, and \o~[see {\QL}]). + +While punctuation had been earlier screened out in order to search for +predefined lower-cased words, that is a slightly different problem from +that of figuring out how to titlecap a punctuated word not on the +lower-cased list. While many punctuation marks trail a word and are, +therefore, not a problem, several punctuation marks lead a word, or +indicate a group separator, even in the absence of whitespace. +\verb|\titlecap| must make sure that these sorts of punctuation marks do +not inhibit the capitalization of the subsequent letter. To this end, +\verb|\titlecap| looks for instances of the following five characters: +-, (, [, \{, and `, and flags the next character for possible +capitalization (unless the word had been previously identified as +predefined lower-cased [see {\QL}]). + +\section{\QL} + +While {\tcp} has been set up to run with certain embedded size and +font-changing commands, it will not, in general, work with macros in the +argument, unless the macros expand directly to a text string. + +The {\tcp} package is designed to work with diacritical marks (for +example, umlauts) as well as national symbols (symbols like \ae, \oe, +\textit{etc.}). There remain, however, two national symbols which are +not handled properly by this package. They are {\aa} and {\l}. They +will not be capitalized, even if found at the beginning of a word. + +The {\tcp} package is designed to screen out punctuation when searching +for words that are pre-designated as lower-cased. So, for example, the +word (\textit{if}) or \textit{``if''} or [\textit{if} or \textit{if,} +will all be found to match \textit{if} when it is predesignated as lower +cased. However, {\tcp} cannot screen out the curly braces \verb|\{| and +\verb|\}| from the punctuation list. Thus, \{if\} will be capitalized +as \{If\} by \tcp. A workaround is detailed in each of the next two +paragraphs. + +To prevent a word from being titled (to force it into lower case), it +can be immediately preceded by a \verb|\relax|. In this way, the +\verb|\relax| is titled, rather than the following word. This method +can be used to for one-time exceptions to titling, or to overcome the +curly-brace problem described above, as in \verb|\{\relax if\}|. + +The package introduces a command, \verb|\textnc|\margcmd{textnc} +(standing for ``text no-change''), which forces its argument to be +independently considered as text, regardless of any surrounding +punctuation or other characters. Thus, this approach may also be used +to address the curly-brace issue as \verb|\{\textnc{it}\}|. In this +case, ``if'' would be titled if it is not on the lower-cased word list, +but left in lower case if it were on the lower-cased word list. The +\verb|\textnc| command is useful in a number of ways inside the argument +to \verb|\titlecap|, but always to signify its argument is to be treated +as a block of text, independently evaluated for its predesignated +lower-cased content. + +If a separator like, let's say, a left paren, is used without +whitespace, in the fashion of ``\verb|a(b)|,'' then neither \verb|a| nor +\verb|b| could possibly be detected as lower-cased words, since +the ``word'' without punctuation would be \verb|ab|, which is neither +\verb|a| nor is it \verb|b|. For individual instances or exceptions, +the insertion of a \verb|\relax| prior to ``\verb|a|'' or ``\verb|b|'' +would prevent titling of these terms. Alternately, the word +``\verb|ab|'' could be added to the predesignated lower-cased words +list, in which case, ``\verb|a(b)|'' would be preserved in lower case. +A third (and perhaps preferred) method is the use of the +\verb|\textnc{}| construct, which is introduced solely for the purpose +of designating embedded text as a separate word grouping. Thus, +\verb|\textnc{a}(\textnc{b})| as an argument to \verb|\titlecap| would +guarantee that both ``\verb|a|'' and ``\verb|b|'' would be independently +examined for their presence in the lower-cased word list, irrespective +of any surrounding punctuation. In this paragraph, the letters +``\verb|a|'' and ``\verb|b|'' have been used for simplicity, but could +actually represent words or groups of words. + +By \LaTeX{} convention, the construct ``\vb|very \large big|'' will +associate the \vb|\large| as the first letter of \vb|big|, rather than +as the last letter of \vb|very|. Unfortunately, leaving it that way +will screw up the titling of \vb|big|. Thus, when adapting the use of +fontsize changes to the {\tcp} package, the prior space is unskipped, +and a space is added after the fontsize change invocation, so that the +fontsize change command is at the end of the prior word, rather than at +the beginning of the next word. The one adverse side effect to this +approach is that a space \textbf{will} appear after a fontsize command, +even if one is not desired (for example, changing font size just prior +to punctuation). One can either issue a \vb|\unskip| following the +fontsize change to back-gobble the newly introduced space, or else place +the fontsize change following the punctuation. + +While \vb|\uppercase| will not work within the argument of a +\vb|\titlecap|, it was found that enclosing part of the argument in +double braces \margtt{\char'173\char'173~\char'175\char'175}will produce +upper case for that double-enclosed text. Thus,\\ +\rl\vb|\titlecap{This is a {{v\"ery}} big test}|\\ +will produce \titlecap{This is a {{v\"ery}} big test}. + +The implementation to make the fontsize change commands work within the +arguments of \vb|\titlecap| required the use of \vb|\makeatletter| +within \vb|\titlecap| itself (which is revoked with a +\vb|\makeatother| upon exit from \vb|\titlecap|). If that is not +considered a ``good practice'' for your situation, then you can disable +this feature with the command \vb|\noatintc|\margcmd{noatintc}. +However, it is likely, at that point, that the fontsize changing +commands as arguments will break the \vb|\titlecap| command. + +Except in the case of the various \vb|\text|\textit{xx}\vb|{}| commands, +for which special provision has been made, and for the double-brace +quirk mentioned above, the argument of \vb|\titlecap| should not contain +braces used as group delimiters, for example, in the fashion of:\\ +\rl\vb|\titlecap{this is a {\itshape test of|\\ +\rl\rl\vb|the} emergency broadcast system}|\\ It may not break the code, +but will likely not produce a desired result. If groupings must be +placed in the argument, using \verb|\textnc{}| to condition the argument +is recommended. Thus,\\ +\rl\vb|\titlecap{this is a \textnc{\itshape test of|\\ +\rl\rl\vb|the} emergency broadcast system}|\\ +will result in ``% +\titlecap{this is a \textnc{\itshape test of the} emergency +broadcast system}'' (of course, in this case, a \vb|\textit{}| would +have worked directly, without a problem). + +There should be no direct use or need to nest \vb|\titlecap| commands. +However, if it is absolutely necessary, the embedded invocation of +\verb|\titlecap| should be expressed as\\ +\rl\verb|\titlecap{...\titlecap\textnc{...}...}|. + +\section{\titlecap{auxiliary commands}} + +In addition to the primary commands offered by this package, there are +several auxiliary commands. + +As described in the section {\QL}, the \verb|\textnc|\margcmd{textnc} +command was introduced when additional grouping must occur inside the +argument of a \verb|\titlecap| command. The argument of \verb|\textnc| +will itself make no changes to its argument, but will force +\verb|\titlecap| to independtly evaluate the \verb|\textnc| argument for +its lower-cased content, regardless of any surrounding punctuation or +text. The command may only be \textit{needed} within an argument to +\verb|\titlecap|. However, if your application requires its invocation +outside of a \verb|\titlecap| argument, it will merely output the +argument without any modification. + +By default, the {\tcp} package treats hardspaces ($\sim$) as characters and +not white space. This default treatment can be changed by setting the +following parameter: \verb|\def\converttilde{T}|\margcmd{converttilde}. +Following that invocation, hardspaces in the argument of +\verb|\titlecap| should be indistinguishable from white space. + +The command \verb|\noatinsidetc|\margcmd{noatinsidetc} was briefly +described in {\QL}. Its invocation will prevent the \verb|\titlecap| +command from employing the \verb|\makeatletter| command, if this is +considered bad practice for your setting. However, its invocation will +likely make the {\tcp} package unable to process fontsize command +changes. + +The last of these auxiliary commands is +\verb|\usestringstringsnames|\margcmd{usestringstringsnames}. This +command will redefine certain command names previously defined by the +\textsf{stringstrings} package to instead use the corresponding commands +of the {\tcp} package, in essence redirecting the \textsf{stringstrings} +invocation to the current package. The redirected commands include the +following (note: see the \textsf{stringstrings} package documentation +for command arguments and options):\\ +\rl\verb|\addlcwords|\\ +\rl\verb|\resetlcwords|\\ +\rl\verb|\addlcword|\\ +\rl\verb|\getargs|\\ +\rl\verb|\capitalizetitle|\\ +If this command is invoked without the prior loading of the +\textsf{stringstrings} package, these commands will still be enabled for +subsequent use. Because the {\tcp} package produces output which can +include font changes and other material that cannot be placed into an +\verb|\edef|, the output of the quiet version of the newly redirected +\verb|\capitalizetitle[q]| produces a \verb|\def\thestring{}| rather +than an \verb|\edef\thestring{}|. + +\section{Acknowledgements} + +I would like to acknowledge the assistance of David Carlisle who, +through the \textsf{tex.stackexchange} website, assisted with both the +string parsing and punctuation screening techniques of this package: + +\verb|http://tex.stackexchange.com/questions/101604/parsing-strings|\\ +\verb|-containing-diacritical-marks-macros| + +\verb|http://tex.stackexchange.com/questions/105735/ignoring|\\ +\verb|-punctuation-during-comparison| + +\clearpage +\section{\titlecap{a \ttfamily\bs titlecap \rmfamily demonstration +for beginners,\\ expressed in \texttt{\bs titlecap}}} + +\Resetlcwords +\Addlcwords{for a is but and with of in as the etc on to if} +%\noatinsidetc +\titlecap{% +%{ +to know that none of the words typed in this paragraph were initially +upper cased might be of interest to you. it is done to demonstrate the +behavioral features of this package. first, you should know the words +that i have pre-designated as lower case. they are: ``for a is but and +with of in as the etc on to if.'' you can define your own list. note +that punctuation, like the period following the word ``if'' did not mess +up the search for lower case (nor did the quotation marks just now). +punctuation which is screened out of the lower-cased word search pattern +include . , : ; ( ) [ ] ? ! ` ' however, I cannot screen text braces; +\{for example in\} is titled, versus (for example in), since the braces +are not screened out in the search for pre-designated lower-case words +like for and in. However, \texttt{\bs textnc} provides a workaround: +\{\textnc{for example in}\}. titlecap will consider capitalizing +following a (, [, \{, or - symbol, such as (abc-def). you can use your +text\textit{\relax xx} commands, like i just did here with the prior xx, +but if you want the argument of that command to not be titled, you +either need, in this example, to add \textit{xx} to the lowercase word +list, which you can see i did not. instead, i put ``\bs relax~xx'' as +the argument, so that, in essence, the \bs relax was capitalized, not +the x. Or you could use \texttt{\bs textnc} . here i demonstrate that +text boldface, \textbf{as in the \bs textbf command}, also works fine, +as do \texttt{texttt}, \textsl{textsl}, \textsc{textsc}, +\textsf{textsf}, \textit{etc}. titlecap will work on diacritical marks, +such as \"apfel, \c cacao \textit{etc.}, \scriptsize fontsize \LARGE +changing commands\normalsize\unskip, as well as national symbols such as +\o laf, \ae gis, and \oe dipus. unfortunately, i could not get it to +work on the \aa~nor the \l~symbols. the method will work with some +things in math mode, capitalizing symbols if there is a leading space, +$x^2$ can become $ x^2$, and it can process but it will not capitalize +the greek symbols, such as $\alpha$, and will choke on most macros, if +they are not direct character expansions. Additionally, +\textsf{titlecaps} also works with font changing declarations, for +example, \bs itshape\bs sffamily. \itshape\sffamily you can see that it +works fine. likewise, any subsequent \bs textxx command will, upon +completion, return the font to its prior state, such as this +\textbf{textbf of some text}. you can see that i have returned to the +prior font, which was italic sans-serif. now I will return to upright +roman\upshape\rmfamily. a condition that will not behave well is inner +braces, such as \ttfamily \bs titlecap\{blah \{inner brace material\} +blah-blah\}. \rmfamily see the section on quirks and limitations for a +workaround involving \texttt{\bs textnc}. titlecap will always +capitalize the first word of the argument (\textbf{even if it is on the +lower-case word list}), unless \texttt{\bs titlecap} is invoked with an +optional argument that is anything other than a capital p. in that case, +the first word will be titled \textit{unless} it is on the lowercase +word list. for example, i will do a \bs titlecap[\relax s]\{\relax +a~big~man\} and get ``\titlecap[s]\textnc{a big man}'' with the ``a'' +not titled. i hope this package is useful to you, but as far as using +\textsf{titlecaps} on such large paragraphs\ldots \textbf{do not try +this at home!}} + +\section{Code Listing} + +\verbatiminput{titlecaps.sty} + +\end{document} + + + |