titlecaps (12apr13)

git-svn-id: svn://tug.org/texlive/trunk@29902 c570f23f-e606-0410-a88d-b1316a301751

3 files changed, 412 insertions, 0 deletions

diff --git a/Master/texmf-dist/doc/latex/titlecaps/README b/Master/texmf-dist/doc/latex/titlecaps/README
new file mode 100644
index 00000000000..05bd3a320ad
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/titlecaps/README
@@ -0,0 +1,7 @@
+The titlecaps package is intended for setting rich text into titling
+capitals (in which the first character of words are capitalized).  It
+automatically accounts for diacritical marks (like umlauts), national
+symbols (like "ae"), punctuation, and font changing commands that alter
+the appearance or size of the text.  It allows a list of predesignated
+words to be protected as lower-cased, and also allows for titling
+exceptions of various sorts.
diff --git a/Master/texmf-dist/doc/latex/titlecaps/titlecaps.pdf b/Master/texmf-dist/doc/latex/titlecaps/titlecaps.pdf
new file mode 100644
index 00000000000..4863cf7f3a2
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/titlecaps/titlecaps.pdf
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}
+
+
+