nameauth (12mar13)

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

1 files changed, 141 insertions, 21 deletions

diff --git a/Master/texmf-dist/source/latex/nameauth/nameauth.dtx b/Master/texmf-dist/source/latex/nameauth/nameauth.dtx
index 178b4e0c17a..903fa0d4c6d 100644
--- a/Master/texmf-dist/source/latex/nameauth/nameauth.dtx
+++ b/Master/texmf-dist/source/latex/nameauth/nameauth.dtx
@@ -1,6 +1,7 @@
 % \iffalse meta-comment
 %
-% Copyright (C) 2011 by Charles P. Schaum <charles dot schaum at att dot net> ---------------------------------------------------------------------------
+% Copyright (C) 2011 by Charles P. Schaum <charles dot schaum at att dot net>
+% ---------------------------------------------------------------------------
 % 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.
@@ -25,7 +26,7 @@
 %<package>\NeedsTeXFormat{LaTeX2e}[2005/12/01]
 %<package>\ProvidesPackage{nameauth}
 %<*package>
-    [2013/02/22 v1.5 name authority macros to aid consistent display and indexing of names]
+    [2013/03/10 v1.6 name authority macros to aid consistent display and indexing of names]
 %</package>
 %
 %<*driver>
@@ -57,7 +58,7 @@
 \usepackage{makeidx}
 \usepackage{multicol}
 \usepackage[toc]{multitoc}
-\usepackage{nameauth}[2013/02/22]
+\usepackage{nameauth}[2013/03/10]
 \usepackage{hypdoc}
 \usepackage{tikz}
 \makeindex
@@ -65,6 +66,33 @@
 \EnableCrossrefs
 \CodelineIndex
 \RecordChanges
+\begin{nameauth}
+  \< Wash & George & Washington & >
+  \< Soto & Hernando & de Soto & >
+  \< JRock & John David & Rockefeller, II & >
+  \< JayR & John David & Rockefeller, IV & Jay >
+  \< Aris & & Aristotle & >
+  \< Eliz & & Elizabeth, I & >
+  \< Dagb & & Dagobert & I > 
+  \< Konoe & Fumimaro & Konoe & >
+  \< Yamt & & Yamamoto, Isoroku & >
+  \< Yosh & & Yoshida & Shigeru >
+\end{nameauth}
+\TagName{Louis}[the Pious]{, emperor}
+\TagName{Ptolemy I}[Soter]{, king}
+\TagName{Henry}[VIII]{, king}
+\TagName{Charles}[the Bald]{, emperor}
+\TagName{Francis, I}{, king}
+\TagName{Demetrius, I Soter}{, king}
+\TagName{Charles, V}{, emperor}
+\TagName{Louis, XIV}{, king}
+\TagName{Dagobert}[I]{, king}
+\TagName{Elizabeth, I}{, queen}
+\TagName{Leo, I}{, pope}
+\TagName[George]{Washington}{, president}
+\TagName{Gregory, I}{, pope}
+\TagName[Fumimaro]{Konoe}{, PM}
+\TagName{Yoshida}[Shigeru]{, PM}
 \begin{document}
   \DocInput{nameauth.dtx}
   \PrintChanges
@@ -73,7 +101,7 @@
 %</driver>
 % \fi
 %
-% \CheckSum{1572}
+% \CheckSum{1676}
 %
 % \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
@@ -107,20 +135,10 @@
 % \changes{v1.26}{2012/04/24}{First-letter caps fixed; fixed sorting of name suffixes in index}
 % \changes{v1.4}{2012/07/24}{Fixed issues moving argument problems, added several features}
 % \changes{v1.5}{2013/02/22}{Minor bugfixes; added several features}
+% \changes{v1.6}{2013/03/10}{Added |nameauth| environment}
 %
 % \DoNotIndex{\@empty, \@gobble, \@period, \@token, \protected@edef, \zap@space, \bfseries, \bgroup, \csgdef, \csname, \csundef, \DeclareOption, \def, \detokenize, \edef, \egroup, \else, \endcsname, \endinput, \ExecuteOptions, \expandafter, \fi, \Forenames, \futurelet, \hbox, \if, \ifcsname, \ifx, \ignorespaces, \index, \itshape, \leavevmode, \let, \newcommand, \newcommandx, \newenvironment, \newif, \PackageWarning, \ProcessOptions, \relax, \renewcommand, \RequirePackage, \scshape, \space, \textbackslash, \uppercase, \WithSuffix}
 %
-% \TagName{Louis}[the Pious]{, emperor}%
-% \TagName{Ptolemy I}[Soter]{, king}%
-% \TagName{Henry}[VIII]{, English king}%
-% \TagName{Charles}[the Bald]{, emperor}%
-% \TagName{Francis, I}{, French king}%
-% \TagName{Demetrius, I Soter}{, king}%
-% \TagName{Charles, V}{, emperor}%
-% \TagName{Louis, XIV}{, French king}%
-% \TagName{Leo, I}{, pope}
-% \TagName{Gregory, I}{, pope}
-%
 % \GetFileInfo{nameauth.dtx}
 % \title{The \textsf{nameauth} package}
 % \author{Charles P. Schaum \\ \texttt{charles dot schaum at att dot net}}
@@ -215,7 +233,7 @@
 % \subsection{Quick Start Guide}
 % \label{sec:start}
 %
-% This general section gets one using many of the package features right away. Read the columns below in a left to right, top to bottom order. The basic patterns for \cmd{\Name}\oarg{arg1}\marg{arg2}\oarg{arg3} are:\\
+% This page introduces basic concepts. The next pages offer simplified approaches and hints to avoid errors. Read the columns below in a left to right, top to bottom order. The basic patterns for \cmd{\Name}\oarg{arg1}\marg{arg2}\oarg{arg3} are:\\
 %
 %\begin{tikzpicture}[line/.style={draw,thick}]
 %  \node [matrix,column sep=4cm] (tipsi) at (3,3)
@@ -289,7 +307,62 @@
 % \indent\textsuperscript{4}When expressing Eastern names via \cmd{\Name}\oarg{Eastern FNN}\marg{Eastern SNN}, they will appear in the index as the Western form \meta{SNN, FNN} even if \cmd{\RevName} is used to create an Eastern word order in the text.\\[1ex]
 % \indent\textsuperscript{5}When expressing Eastern names using the form \cmd{\Name}\marg{Eastern SNN, FNN} or \cmd{\Name}\marg{Eastern SNN}\oarg{Eastern FNN}, such names will appear in the index using the Eastern form \meta{SNN FNN} even if \cmd{\RevName} is used to create a Western word order in the text.\\[1.5ex]
 % If given the choice, use the |nocomma| option and the \meta{Name$_1$, Name$_2$} forms for suffixes and affixes in order to take advantage of extra space removal and other features that minimize possible errors.
+% \clearpage
+%
+% \DescribeMacro{nameauth} A simplified interface has been introduced as of version 1.6. The |nameauth| environment  (best used in the document preamble) sets up a list of shorthands used in place of \cmd{\Name},  \cmd{\Name*}, and  \cmd{\FName}. The syntax is:
+%
+% \begin{quote}
+% |\begin{nameauth}|\\
+% |  \<| \meta{cseq-abbreviation1} |&| \meta{arg1} |&| \meta{arg2} |&| \meta{arg3} |>|\\
+% |  \<| \meta{cseq-abbreviation2} |&| \meta{arg1} |&| \meta{arg2} |&| \meta{arg3} |>| \dots\\
+% |\end{nameauth}|
+% \end{quote}
+% Each instance of \meta{cseq-abbreviation} creates three macros. The control sequence itself is an abbreviation for \cmd{\Name}. The form with an L prefixed stands in for \cmd{\Name*}. The form with an S prefixed stands in for \cmd{\FName}. The next example shows most of the name forms from the previous page:
+%
+% \begin{quote}
+%|\begin{nameauth}|\\
+%|  \< Wash & George & Washington & >|\\
+%|  \< Soto & Hernando & de Soto & >|\\
+%|  \< JRock & John David & Rockefeller, II & >|\\
+%|  \< JayR & John David & Rockefeller, IV & Jay >|\\
+%|  \< Aris & & Aristotle & >|\\
+%|  \< Eliz & & Elizabeth, I & >|\\
+%|  \< Dagb & & Dagobert & I >|\\
+%|  \< Konoe & Fumimaro & Konoe & >|\\
+%|  \< Yamt & & Yamamoto, Isoroku & >|\\
+%|  \< Yosh & & Yoshida & Shigeru >|\\
+%|\end{nameauth}|
+% \end{quote}
+% There must be four arguments. Placement of ampersands is key to avoiding error. Leading and trailing spaces are stripped. Using various macros explained later, one can do the following:
 %
+% \begin{multicols}{2}
+% \noindent|\Wash|:  \Wash \\
+% |\Wash|: \Wash \\
+% |\LWash|: \LWash \\
+% |\SWash|: \SWash \\
+% |\RevComma\LWash|: \RevComma\LWash \\
+% |\Soto|: \Soto \\
+% |\Soto|: \Soto \\
+% |\CapThis\Soto|: \CapThis\Soto \\
+% |\JRock|: \JRock \\
+% |\JRock|: \JRock \\
+% |\JayR|: \JayR \\
+% |\SJayR{} \JayR|: \SJayR{} \JayR\\
+% |\Aris|: \Aris \\
+% |\Eliz|: \Eliz \\
+% |\Eliz|: \Eliz \\
+% |\Dagb|: \Dagb \\
+% |\Dagb|: \Dagb \\
+% |\Konoe|: \Konoe \\
+% |\RevName\LKonoe|: \RevName\LKonoe \\
+% |\CapName\LKonoe|: \CapName\LKonoe \\
+% |\CapName\RevName\LKonoe|: \\ \indent\CapName\RevName\LKonoe \\
+% |\CapName\Yamt|: \\ \indent\CapName\Yamt \\
+% |\RevName\LYamt|: \RevName\LYamt \\
+% |\Yosh|: \Yosh
+% \end{multicols}
+%
+% \noindent As with |\TagName|, one must add extra comment delimiters if the environment is used in the text body. This environment can augment the other macros.
 % \subsubsection{Additional Hints}
 % \IndexInactive\NamesInactive
 % \begin{tabular}{lp{4in}}
@@ -301,8 +374,8 @@
 % A:&Bringhurst's \emph{Elements of Typographic Style} calls for no spaces or thin spaces between initials. Use \cmd{\frenchspacing}.\\[1ex]
 % Q:&|\Name[Davey]{Jones}[a Monkee]| shows ``\Name[Davey]{Jones}[a Monkee]'' or just ``\Name[Davey]{Jones}[a Monkee].'' \cmd{\FName} gives ``\FName[Davey]{Jones}[a Monkee].''\\[0.5ex]
 % A:&\cmd{\Name}\oarg{Forenames}\marg{Surnames}\oarg{Nicknames} creates a nickname, not an affix or sobriquet.\\[1ex]
-% Q:&|\Name[Henry]{VII}| prints either ``\Name*[Henry]{VII}'' or ``\Name[Henry]{VII}.'' Adding [Tudor] creates ``\Name*[Henry]{VII}[Tudor]'' and ``\Name[Henry]{VII}[Tudor].''\\[0.5ex]
-% A:&\cmd{\Name}\oarg{King}\marg{Affix} will not work. Even though Mulvany, \emph{Indexing Books}, talks about forenames and optional surnames for royals, we prevent ambiguity by encoding royal names as surnames with optional affixes. Use \cmd{\Name}\marg{King, Affix} if possible, or \cmd{\Name}\marg{King}\oarg{Affix} with the |comma| option. |\Name{Henry, VII}| gives ``\Name{Henry, VII}'' and ``\Name{Henry, VII}.'' Manually add ``Tudor'' in the text and use |\TagName{Henry, VII}{, Tudor}| to add the tag automatically to the index entry.\\[1ex]
+% Q:&|\Name[Henry]{VIII}| prints either ``\Name*[Henry]{VIII}'' or ``\Name[Henry]{VIII}.'' Adding [Tudor] creates ``\Name*[Henry]{VIII}[Tudor]'' and ``\Name[Henry]{VIII}[Tudor].''\\[0.5ex]
+% A:&\cmd{\Name}\oarg{King}\marg{Affix} will not work. Even though Mulvany, \emph{Indexing Books}, talks about forenames and optional surnames for royals, we prevent ambiguity by encoding royal names as surnames with optional affixes. Use \cmd{\Name}\marg{King, Affix} if possible, or \cmd{\Name}\marg{King}\oarg{Affix} with the |comma| option. For example, |\Name{Henry, VIII}| gives ``\Name{Henry, VIII}'' and ``\Name{Henry, VIII}.'' Manually add ``Tudor'' in the text and use |\TagName{Henry, VIII}{, Tudor}| to add the tag automatically to the index entry.\ForgetName[Henry]{VIII}\ForgetName{Henry, VIII}\\[1ex]
 % Q:&|\Name{Aethelred, the really}[Unraedig]| shows ``\Name{Aethelred, the really}[Unraedig]'' or ``\Name{Aethelred, the really}[Unraedig].''\\[0.5ex]
 % A:&The form \cmd{\Name}\marg{Mononym, Affix$_1$}\oarg{Affix$_2$} creates two sobriquets, but badly. Use either \cmd{\Name}\marg{Mononym, Affix} or \cmd{\Name}\marg{Mononym}\oarg{Affix} with |comma|. Mix the forms either at your peril or at your whimsy.\\[1ex]
 % Q:&|\AKA{Boris}[the Animal]{Just Boris}| fails.\\[0.5ex]
@@ -425,7 +498,7 @@
 % {\large\strut}|\Name*[Martin Luther]{King, Jr.}| & \Name*[Martin Luther]{King, Jr.}
 % \end{tabular}
 % \end{quote}
-% See Section~\ref{sec:suffix} for more on comma-delimited suffixes. Full-stop detection also works with \cmd{\FName} in cases like the fictional \FName[J.D.]{Rock, III} where one might discuss |``who shot \FName[J.D.]{Rock, III}.''| ``who shot \FName[J.D.]{Rock, III}.''
+% \IndexInactive See Section~\ref{sec:suffix} for more on comma-delimited suffixes. Full-stop detection also works with \cmd{\FName} in cases like the fictional \FName[J.R.]{Wing, III} where one might discuss |``who shot \FName[J.R.]{Wing, III}.''| ``who shot \FName[J.R.]{Wing, III}.''\IndexActive
 %
 % \subsection{Affixes and Eastern Names}
 %
@@ -436,7 +509,7 @@
 %
 % \DescribeMacro{\ShowComma}
 % The |comma| option is restrictive, but helpful in reproducing older texts. \cmd{\ShowComma} permits the default |nocomma| option, yet forces a comma to appear between the name and suffix: |\ShowComma\Name[Louis]{Gossett, Jr.}| \ShowComma\Name[Louis]{Gossett, Jr.}. A caveat is that one must use \cmd{\ShowComma} consistently with that name thereafter or risk errors.
-
+%
 %The |comma| option and \cmd{\ShowComma} restrict the use of some royal names and Eastern names. \cmd{\AKA} and \cmd{\PName} cannot create cross-references to these forms, but \cmd{\AKA} can cross-reference \emph{from} these forms in its second set of arguments. These restricted forms are shown below:
 %
 % \begin{quote}\ForgetName{Henry}[VIII]
@@ -540,7 +613,6 @@
 % English names with the particles \emph{de}, \emph{de\ la}, \emph{d'}, \emph{von}, \emph{van}, and \emph{ten} generally keep them with the last name, using varied capitalization. \emph{Le}, \emph{La}, and \emph{L'} are capitalized unless preceded by \emph{de}. In English, these particles go in the \meta{SNN} field of \cmd{\Name}, e.g., \ForgetName[Walter]{de la Mare}\Name[Walter]{de la Mare}. To capitalize the first particle in a subsequent \cmd{\Name} reference at the beginning of a sentence, use |\CapThis\Name[Walter]{de la Mare}|. \CapThis\Name[Walter]{de la Mare} will think it fair. \CapThis\Name{du Cange} (\AKA{du Cange}[Charles]{du Fresne}) would too, because \cmd{\CapThis} works universally as of version 1.4.
 %
 % Names foreign to English often associate these particles with the \meta{FNN} field of \cmd{\Name}. Yet these particles are not really first names. Using \cmd{\FName} with alternate forenames avoids that issue. See also Section~\ref{sec:Particles}.
-
 %
 % \subsubsection{Hyphenation}
 %
@@ -2154,6 +2226,54 @@
 \newcommand{\IndexActive}{\@nameauth@DoIndextrue}
 %    \end{macrocode}
 % \end{macro}
+%
+% \begin{environment}{nameauth}
+% \changes{v1.6}{2013/03/10}{Added |nameauth| environment}
+% The |nameauth| environment provides a means to implement shorthand references to names in a document.
+%    \begin{macrocode}
+\newenvironment{nameauth}{%
+  \begingroup%
+  \csdef{<}##1&##2&##3&##4>{%
+    \protected@edef\arga{\trim@spaces{##1}}%
+    \protected@edef\argb{\trim@spaces{##2}}%
+    \protected@edef\argc{\trim@spaces{##3}}%
+    \protected@edef\argd{\trim@spaces{##4}}%
+    \ifx\arga\@empty
+        \PackageError{nameauth}%
+        {environment nameauth: Control sequence missing.}%
+    \else
+      \ifx\argc\@empty
+        \PackageError{nameauth}%
+        {environment nameauth: Essential name missing.}%
+      \else
+        \ifx\argd\@empty
+          \ifx\argb\@empty
+            \csxdef{\arga}{\Name{\argc}}%
+            \csxdef{L\arga}{\Name*{\argc}}%
+            \csxdef{S\arga}{\FName{\argc}}%
+          \else
+            \csxdef{\arga}{\Name[\argb]{\argc}}%
+            \csxdef{L\arga}{\Name*[\argb]{\argc}}%
+            \csxdef{S\arga}{\FName[\argb]{\argc}}%
+          \fi
+        \else
+          \ifx\argb\@empty
+            \csxdef{\arga}{\Name{\argc}[\argd]}%
+            \csxdef{L\arga}{\Name*{\argc}[\argd]}%
+            \csxdef{S\arga}{\FName{\argc}[\argd]}%
+          \else
+            \csxdef{\arga}{\Name[\argb]{\argc}[\argd]}%
+            \csxdef{L\arga}{\Name*[\argb]{\argc}[\argd]}%
+            \csxdef{S\arga}{\FName[\argb]{\argc}[\argd]}%
+          \fi
+        \fi
+      \fi
+    \fi
+    \ignorespaces%
+  }%
+}{\endgroup}
+%    \end{macrocode}
+% \end{environment}
 % \clearpage
 % \Finale
 \endinput