From 034fde36e1b3172016db6037511e0118d5ed04f6 Mon Sep 17 00:00:00 2001 From: Karl Berry Date: Mon, 30 Jan 2012 23:49:34 +0000 Subject: nameauth (30jan12) git-svn-id: svn://tug.org/texlive/trunk@25244 c570f23f-e606-0410-a88d-b1316a301751 --- .../texmf-dist/source/latex/nameauth/nameauth.dtx | 441 +++++++++++---------- 1 file changed, 239 insertions(+), 202 deletions(-) (limited to 'Master/texmf-dist/source/latex') diff --git a/Master/texmf-dist/source/latex/nameauth/nameauth.dtx b/Master/texmf-dist/source/latex/nameauth/nameauth.dtx index c60ad2b2907..4ab17d642f6 100644 --- a/Master/texmf-dist/source/latex/nameauth/nameauth.dtx +++ b/Master/texmf-dist/source/latex/nameauth/nameauth.dtx @@ -26,7 +26,7 @@ %\NeedsTeXFormat{LaTeX2e}[2005/12/01] %\ProvidesPackage{nameauth} %<*package> - [2012/01/19 v0.75 name authority macros to aid consistent display and indexing of names] + [2012/01/29 v0.8 name authority macros to aid consistent display and indexing of names] % % %<*driver> @@ -37,7 +37,7 @@ \usepackage{lmodern} \usepackage{makeidx} \usepackage{newunicodechar} -\usepackage{nameauth}[2011/12/26] +\usepackage{nameauth}[2012/01/29] \begingroup\lccode`!=`\\\lowercase{\endgroup\def\bsc{!}} \makeindex \frenchspacing @@ -57,7 +57,7 @@ % % \fi % -% \CheckSum{416} +% \CheckSum{318} % % \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 @@ -78,8 +78,9 @@ % % \changes{v0.7}{2011/12/26}{Initial version} % \changes{v0.75}{2012/01/19}{New features described; documentation clarified} +% \changes{v0.8}{2012/01/29}{Refactoring to improve functionality and compatibility; documentation expanded} % -% \DoNotIndex{\newcommand, \newenvironment, \@empty, \@gobble, \bfseries, \bgroup, \def, \egroup, \else, \endcsname, \endinput, \ExecuteOptions, \fi, \if, \ifx, \IfBooleanTF, \IfValueTF, \itshape, \let, \newif, \relax, \renewcommand, \RequirePackage, \scshape, \space} +% \DoNotIndex{\newcommand, \newenvironment, \@empty, \@gobble, \bfseries, \bgroup, \def, \egroup, \else, \endcsname, \endinput, \ExecuteOptions, \fi, \if, \ifx, \IfBooleanTF, \IfValueTF, \itshape, \let, \newif, \relax, \renewcommand, \RequirePackage, \scshape, \space, \DeclareDocumentCommand, \DeclareOption, \ProcessOptions} % % \providecommand*{\url}{\texttt} % \GetFileInfo{nameauth.dtx} @@ -122,6 +123,81 @@ % \end{quote} % \clearpage % +% \subsection{Quick Start Guide} +% \changes{v0.8}{2012/01/29}{Added quick start guide for the impatient} +% +% This page and the next comprise a ``cheat sheet'' for the impatient. None of the examples in this subsection generate index entries. These examples simply help you get used to the package: +% +% \begin{enumerate}\setlength\itemsep{0pt}\small +% \item The indexed forms of the names always remain the same. +% \item Always use the same form of reference for, e.g., \texttt{\bsc Name[John]\{Smith\}} or\newline \texttt{\bsc Name\{Louis\}[XIV]}, otherwise point 1 will become false. +% \item Typing longer name references allows you to rearrange text and let \LaTeX{} figure out first references and name forms. This package trades some work for consistency. +% \item Checking against the index will help you debug your \texttt{\bsc Name} references, \emph{inter alia}. +% \item Start using the macros you \emph{need}, then work from there. +% \end{enumerate} +% +% \bgroup\small +% \begin{tabular}{p{1.8in}p{2.3in}} +% \normalsize\strut\textbf{I want to\dots} & \normalsize\textbf{I need to use} (for example)\dots \\\hline +% Print a full Western name (first reference) & \texttt{\bsc Name*[John]\{Smith\}} or\newline \texttt{\bsc Name[John]\{Smith\}}\\\hline +% Print a full Western name (subsequent reference) & \texttt{\bsc Name*[John]\{Smith\}}\\\hline +% Print a short Western name (subsequent reference) & \texttt{\bsc Name[John]\{Smith\}}\\\hline +% Print a Western name that has a longer form in the text than in the index (first reference) & \texttt{\bsc Name*[J.Q.]\{Public\}[Jane Q.]} or\newline \texttt{\bsc Name[J.Q.]\{Public\}[Jane Q.]}\\\hline +% Now the full name without the longer form & \texttt{\bsc Name*[J.Q.]\{Public\}}\\\hline +% Same person, last name only (subsequent reference) & \dag\texttt{\bsc Name[J.Q.]\{Public\}} or\newline \texttt{\bsc Name[J.Q.]\{Public\}[Jane Q.]}\\\hline +% Print an ancient name & \texttt{\bsc Name\{Plato\}} or \texttt{\bsc Name*\{Plato\}}\\\hline +% Print a full Eastern name (first reference) & \texttt{\bsc Name*\{Mao\}[Tse-tung]} or\newline \texttt{\bsc Name\{Mao\}[Tse-tung]}\\\hline +% Print a full Eastern name (subsequent reference) & \texttt{\bsc Name*\{Mao\}[Tse-tung]}\\\hline +% Print a short Eastern name (subsequent reference) & \texttt{\bsc Name\{Mao\}[Tse-tung]}\\\hline +% Print a full enumerated name (first reference) & \texttt{\bsc Name*\{Louis\}[XIV]} or\newline \texttt{\bsc Name\{Louis\}[XIV]}\\\hline +% Shorter subsequent reference & \texttt{\bsc Name\{Louis\}[XIV]}\\\hline +% Print an ancient name and sobriquet & \texttt{\bsc Name*\{Antiochus V\}[Eupator]} or\newline \texttt{\bsc Name\{Antiochus V\}[Eupator]}\\\hline +% Shorter subsequent reference to ``Antiochus V''; for name only, \emph{consistently} use ``V Eupator'' & \texttt{\bsc Name\{Antiochus V\}[Eupator]}\\\hline +% \end{tabular} +% +% \smallskip\dag{} Using this form can cause unwanted results if you rearrange text. +% \egroup +% \clearpage +% +% \bgroup\small +% \begin{tabular}{p{1.6in}p{2.5in}} +% \normalsize\strut\textbf{I want to\dots} & \normalsize\textbf{I need to use} (for example)\dots \\\hline +% Index, but do not print a reference to ``Public, J.Q.'' & \texttt{\bsc IndexName[J.Q.]\{Public\}} or\newline \ddag\texttt{\bsc IndexName[J.Q.]\{Public\}[Jane Q.]}\\\hline +% Index, but do not print a reference to ``Plato'' & \texttt{\bsc IndexName\{Plato\}}\\\hline +% Index, but do not print a reference to ``Mao Tse-tung'' & \P\texttt{\bsc IndexName\{Mao\}[Tse-tung]}\\\hline +% Index, but do not print a reference to ``Louis XIV'' & \P\texttt{\bsc IndexName\{Louis\}[XIV]}\\\hline +% Index, but do not print a reference to ``Antiochus V Eupator'' & \P\texttt{\bsc IndexName\{Antiochus V\}[Eupator]}\\\hline +% \end{tabular} +% +% \smallskip\ddag{} The alternate names are ignored in this case.\\ +% \indent\P{} ``Unofficial'' variants are neither shown nor encouraged. +% \egroup +% +%\bigskip +% \bgroup\small +% \begin{tabular}{p{1.5in}p{2.6in}} +% \normalsize\strut\textbf{I want to\dots} & \normalsize\textbf{I need to use} (for example)\dots \\\hline +% Print a full Western name followed by a lesser-known name in parentheses (first reference) & \texttt{\bsc PName*[Bob]\{Hope\}[Leslie Townes]\{Hope\}} or\newline \texttt{\bsc PName[Bob]\{Hope\}[Leslie Townes]\{Hope\}}\\\hline +% Print a full Western name followed by a lesser-known name in parentheses (subsequent reference) & \texttt{\bsc PName*[Bob]\{Hope\}[Leslie Townes]\{Hope\}}\\\hline +% Print a surname only, followed by a full lesser-known name in parentheses (subsequent reference) & \texttt{\bsc PName[Bob]\{Hope\}[Leslie Townes]\{Hope\}}\\\hline +% Print a mononym followed by a lesser-known name in parentheses & \texttt{\bsc PName*\{Prince\}[Prince Rogers]\{Nelson\}} or\newline \texttt{\bsc PName\{Prince\}[Prince Rogers]\{Nelson\}}\\\hline +% Print a name, then another name that only cross-references it in the index & a tribute to \texttt{\bsc Name\{Ari Up\}, born \newline \bsc AKA\{Ari Up\}[Arianne]\{Forster\}\dots}\\\hline +% \end{tabular} +% \egroup +% +% \bigskip +% These (and possibly other combinations) will likely fail: +% \begin{enumerate}\setlength\itemsep{0pt}\small +% \item \texttt{\bsc Name[First]\{Ancient\}[Sobriquet]} and \texttt{\bsc Name[King]\{Number\}[Sobriquet]} +% \item \texttt{\bsc Name\{Ancient\}[Sobriquet] \bsc AKA\{Ancient Sobriquet\}[OtherFirst]\{OtherLast\}} +% \item \texttt{\bsc Name\{Queen\}[Number] \bsc AKA\{Queen Number\}[OtherFirst]\{OtherLast\}} +% \item \texttt{\bsc Name\{EastFamily\}[EastFirst] \bsc AKA\{EastFamily EastFirst\}[OtherFirst]\{OtherLast\}} +% \item E.g. \texttt{\bsc Name[]\{Kreskin\}[The Amazing] (\bsc AKA\{Kreskin\}[Joseph]\{Kresge\})} +% \item Using \texttt{\bsc PName} in the same way as \texttt{\bsc AKA} above. +% \item Using \texttt{\bsc Name} with a lot of people having the same surname or mononym and different numbers without disambiguation in the text. +% \item Getting the pairing of \texttt{\{} and \texttt{\}} or \texttt{[} and \texttt{]} messed up. +% \end{enumerate} +% % \subsection{Basic Macros} % % \subsubsection{\texttt{\bsc Name} and \texttt{\bsc Name*}} @@ -232,7 +308,7 @@ % \end{tabular} % \end{quote} % -% Here is a general table of options. Sobriquets and suffixes do mix, but not well: +% Here is a general table of options. Sobriquets and suffixes do mix, but not well. Therefore their use together is not shown. % % \begin{quote}\small % \begin{tabular}{llp{1.4cm}p{4cm}}\hline @@ -243,9 +319,6 @@ % \texttt{Forename} & \texttt{SurnameB, Suffix} & (none) & \Name[Forename]{SurnameB, Suffix} (\texttt{\bsc Name})\\ % \texttt{Forename} & \texttt{SurnameB, Suffix} & (none) & \Name*[Forename]{SurnameB, Suffix} (\texttt{\bsc Name*})\\ % \texttt{Forename} & \texttt{SurnameB, Suffix} & (none) & \Name[Forename]{SurnameB, Suffix} (\texttt{\bsc Name})\\\hline -% (none) & \texttt{SurnameC, Suffix} & \texttt{Sobriquet} & \Name{SurnameC, Suffix}[Sobriquet] (\texttt{\bsc Name})\\ -% (none) & \texttt{SurnameC, Suffix} & \texttt{Sobriquet} & \Name*{SurnameC, Suffix}[Sobriquet] (\texttt{\bsc Name*})\\ -% (none) & \texttt{SurnameC, Suffix} & \texttt{Sobriquet} & \Name{SurnameC, Suffix}[Sobriquet] (\texttt{\bsc Name})\\\hline % \end{tabular} % \end{quote} % @@ -292,7 +365,7 @@ % \Name[C.F.W.]{Walther}[Carl Ferdinand Wilhelm] was a major figure in nineteenth-century American Lutheran history. \Name[C.F.W.]{Walther} used his full name when signing official documents. To his family, friends, and close colleagues, however, he was simply Ferdinand\IndexName[C.F.W.]{Walther}. % \end{quote} % -% One can use this macro for special cases, like referring to works written or produced by joint or multiple authors: +% One can use this macro for special cases, like referring to works by joint or multiple authors or simply indexing names consistently with this package: % % \begin{quote} % \bgroup\ttfamily @@ -309,10 +382,10 @@ % \ForgetName{Antiochus IV}[Epiphanes]% % \begin{quote} % \bgroup\ttfamily -% First Maccabees recounts the suppression of Jewish customs\break under the Seleucid king \bsc Name\{Antiochus IV\}[Epiphanes]. His behavior was so egregious that he became an early model for the later profile of Antichrist\break \bsc IndexName\{Antiochus IV\}[Epiphanes]. +% First Maccabees recounts the suppression of Jewish customs\break under the Seleucid king \bsc Name\{Antiochus IV\}[Epiphanes]. His behavior was so egregious that he became an early model for the later profile of Antichrist.\break \bsc IndexName\{Antiochus IV\}[Epiphanes] % \egroup % -% First Maccabees recounts the suppression of Jewish customs under the Seleucid king \Name{Antiochus IV}[Epiphanes]. His behavior was so egregious that he became an early model for the later profile of Antichrist \IndexName{Antiochus IV}[Epiphanes]. +% First Maccabees recounts the suppression of Jewish customs under the Seleucid king \Name{Antiochus IV}[Epiphanes]. His behavior was so egregious that he became an early model for the later profile of Antichrist.\IndexName{Antiochus IV}[Epiphanes] % \end{quote} % % \texttt{\bsc IndexName} may be helpful in a pinch, but it lacks certain safeguards for handling pseudonyms that the following macros introduce. @@ -352,12 +425,10 @@ % Perhaps the greatest medieval theologian was \Name{Thomas}[Aquinas] (Thomas of Aquino), also known as \textit{Doctor Angelicus}. His name ``Aquinas'' is not a surname, so many modern scholars refer to him as \Name{Thomas}[Aquinas]. % \end{quote} % -% This also means, unfortunately, that Eastern names, as touched on earlier, will have to be indexed manually. +% This also means, unfortunately, that pen names used with Eastern names will have to be indexed manually. % % \DescribeMacro{\PName} -% People may use pseudonyms or \emph{noms de plume}. Sometimes they become known by epithets or monikers. There are two macros to handle this. The first of these macros, \texttt{\bsc PName}, opens with the well-known name under which a person is indexed, followed by the lesser-known name, which it sets in parentheses. -% -%Like \texttt{\bsc Name}, \texttt{\bsc PName} has starred and unstarred forms, but those forms only operate on the name that is indexed, not on the second, lesser-known name. The syntax is: +% Pseudonyms, \emph{noms de plume}, epithets, and monikers can be handled with two macros: \texttt{\bsc PName} and \texttt{\bsc AKA}. The macro \texttt{\bsc PName} takes a well-known name, followed by as lesser-known name. Like \texttt{\bsc Name}, \texttt{\bsc PName} has starred and unstarred forms, but those forms only operate on the main name that is indexed, not on the second, lesser-known name. The syntax is: % \begin{quote} % \texttt{\bsc PName}\oarg{FNN}\marg{SNN}\oarg{lesser-known FNN}\marg{lesser-known SNN} % \end{quote} @@ -397,8 +468,16 @@ % % \texttt{\bsc AKA} creates an index entry that cross-references to the ``main'' name given. It is assumed that a \texttt{\bsc Name} macro occurs somewhere in reference to the indexed name. No error checking otherwise occurs for this. % -% Pseudonyms cannot be indexed with page numbers. They only work as ``see'' cross-references. \texttt{\bsc Name} will print its arguments and emit a warning if you give a pen name as its arguments. If you want to index a pseudonym with page numbers, use \texttt{\bsc Name} for both the main name and the pseudonym, then manually cross-reference them. -% +% Pseudonyms cannot be indexed with page numbers. They only work as ``see'' cross-references. \texttt{\bsc Name} will print its arguments and emit a warning if you give a pen name. If you want to index a pseudonym with page numbers, use \texttt{\bsc Name} for both the main name and the pseudonym, then manually cross-reference them, e.g.:\medskip +% +% \bgroup\small\index{Rambam|seealso{Maimonides}} +% \begin{tabular}{p{0.7in}ll}\hline +% Authoritative Name & Alternate Name & Example of Use\\\hline +% \Name{Maimonides} & \AKA{Maimonides}{Moses ben-Maimon} & \texttt{\bsc AKA\{Maimonides\}\{Moses ben-Maimon\}}\\ +% \Name{Maimonides} & \Name{Rambam} & \verb!\Name{Rambam}!\\& & \verb!\index{Rambam|seealso{Maimonides}!\\\hline +% \end{tabular} +% \egroup +% % \texttt{\bsc AKA} will not create multiple instances of a cross-reference. This prevents bogus multiple cross-references in the index, but it also excludes the special case where one moniker applies to multiple people, e.g.: \PName*[Willebrord]{Snel van Royen}{Snellius} and his son \PName*[Rudolph]{Snel van Royen}{Snellius}. % \index{Snellius|see {Snel van Royen, Rudolph}}% % Do not use \texttt{\bsc IndexName} in this case. One must add a manual index entry as a workaround: @@ -458,15 +537,33 @@ % % \subsubsection{Font Attributes} % \label{sec:FontAttributes} +% \changes{v0.8}{2012/01/29}{Expanded description of functionality} % % \DescribeMacro{\NamesFormat} % The first time a name is printed, it is formatted with the font attribute stored in \texttt{\bsc NamesFormat}. This is set with the class options or manually. \texttt{\bsc NamesFormat} can use either the command form or the declaration form of selecting font attributes, e.g., \texttt{\bsc textsc} or \texttt{\bsc scshape}. By redefining this macro, one can ``hook'' into the special typesetting of the first occurrence of a name. Consider the following: % % \begin{quote} -% \texttt{\bsc renewcommand\{\bsc NamesFormat\}[1]\{\bsc textsc\{\#1\}\%}\\ -% \texttt{\bsc ifinner\bsc else\bsc marginpar\{\#1\}\bsc fi\}} +% \texttt{\bsc renewcommand\{\bsc NamesFormat\}[1]\{\bsc textbf\{\#1\}\%}\\ +% \texttt{\bsc ifinner\bsc else\bsc marginpar\{\bsc scriptsize \#1\}\bsc fi\}} % \end{quote} % +% If we \texttt{\bsc let} the value of \texttt{\bsc NamesFormat} to save the current value and implement a temporary change like the above, we get: +% +% \let\oldformat\NamesFormat +% \renewcommand{\NamesFormat}[1]{\textbf{#1}\ifinner\else\marginpar{\scriptsize #1}\fi} +% +%\begin{quote} +% \texttt{\bsc Name\{Vlad III\}[Dracula] became known as Vlad Ţepeş, ``The Impaler,'' after his death. He was the son of \bsc Name\{Vlad II\}[Dracul]. Later references to \bsc Name\{Vlad III\}[Dracula] appear thus.}\bigskip +% +% \Name{Vlad III}[Dracula] became known as Vlad Ţepeş, ``The Impaler,'' after his death. He was the son of \Name{Vlad II}[Dracul]. Later references to \Name{Vlad III}[Dracula] appear thus. +% \end{quote} +% +% \let\NamesFormat\oldformat +% +% After using \texttt{\bsc let} to revert \texttt{\bsc NamesFormat}, a first occurrence again takes the form: \ForgetName{Vlad III}[Dracula]\Name{Vlad III}[Dracula].\\ +% +% Let me again stress that with names like \Name*{Vlad II}[Dracul] and \Name*{Vlad III}[Dracula], you cannot use either \texttt{\bsc PName} or \texttt{\bsc AKA}. Attempting to do so will fail. You must use as a guide the examples given above for \Name*{Jean}[sans Peur] and \Name*{Thomas}[Aquinas]. +% % \subsection{Formatting Certain Sections} % \label{sec:SectionFormat} % @@ -535,137 +632,158 @@ % \end{macrocode} % % \subsection{Internal Macros} -% \begin{macro}{\@CleanName} +% \begin{macro}{\@nameauth@CleanName} +% \changes{v0.8}{2012/01/29}{Renamed macro to help compatibility} % \begin{macrocode} -\newcommand*{\@CleanName}[1]{\expandafter\zap@space\detokenize{#1} \@empty} +\newcommand*{\@nameauth@CleanName}[1]{\expandafter\zap@space\detokenize{#1} \@empty} % \end{macrocode} % \end{macro} % Thanks to \Name*[Heiko]{Oberdiek}, this macro produces a ``sanitized'' string based on the forename/surname parameters of \texttt{\bsc Name} and friends. With this we can construct a control sequence name (\texttt{\bsc csname}). Testing for the presence of that control sequence determines the existence of pseudonyms and the first occurrence of a name. % -% \begin{macro}{\@Zapsuffix} +% \begin{macro}{\@nameauth@Zapsuffix} % \begin{macrocode} -\newcommand{\@Zapsuffix}[1]{% - \def\@@Zapsuff##1,##2*{##1}% - {\@@Zapsuff#1,*}% +\newcommand{\@nameauth@Zapsuffix}[1]{% + \def\@@Zapsuffix##1,##2*{##1}% + {\@@Zapsuffix#1,*}% } % \end{macrocode} % \end{macro} % This macro does what it says. Anything starting with a comma and ending with the end of the name is stripped off. That includes ``Sr.,'' ``Jr.,'' ``III,'' and so on. % -% \begin{macro}{\@CheckDot} +% \begin{macro}{\@nameauth@CheckDot} +% \changes{v0.8}{2012/01/29}{Renamed macro to help compatibility} % \begin{macrocode} -\def\@CheckDot{\futurelet\@token\@EvalDot} +\def\@nameauth@CheckDot{\futurelet\@token\@nameauth@EvalDot} % \end{macrocode} % \end{macro} -% This macro assigns the lookahead token \texttt{\bsc @token} to be evaluated by \texttt{\bsc @EvalDot} while keeping \texttt{\bsc @token} non-destructively on the list of input tokens. I use this method instead of \texttt{\bsc @nextchar} because I do not want to gobble spaces. +% This macro assigns the lookahead token \texttt{\bsc @token} to be evaluated by \texttt{\bsc @nameauth@EvalDot} while keeping \texttt{\bsc @token} non-destructively on the list of input tokens. I use this method instead of \texttt{\bsc @nextchar} because I do not want to gobble spaces. % -% \begin{macro}{\@EvalDot} +% \begin{macro}{\@nameauth@EvalDot} +% \changes{v0.8}{2012/01/29}{Renamed macro to help compatibility} % \begin{macrocode} -\def\@EvalDot{\let\@period=.\ifx\@token\@period\expandafter\@gobble \fi} +\def\@nameauth@EvalDot{\let\@period=.\ifx\@token\@period\expandafter\@gobble \fi} % \end{macrocode} % \end{macro} -% \texttt{\bsc @EvalDot} checks of \texttt{\bsc @token} is a period. If so it gobbles it by using \texttt{\bsc expandafter} to get past the grouping. Another \texttt{\bsc expandafter} occurs immediately before the invocation of \texttt{\bsc @CheckDot} in \texttt{\bsc Name} and \texttt{\bsc AKA}. +% \texttt{\bsc @nameauth@EvalDot} checks of \texttt{\bsc @token} is a period. If so it gobbles it by using \texttt{\bsc expandafter} to get past the grouping. Another \texttt{\bsc expandafter} occurs immediately before the invocation of \texttt{\bsc @nameauth@CheckDot} in \texttt{\bsc Name} and \texttt{\bsc AKA}. % -% \begin{macro}{\@TestDot} +% \begin{macro}{\@nameauth@TestDot} +% \changes{v0.8}{2012/01/29}{Renamed macro to help compatibility} % \begin{macrocode} -\newcommand*{\@TestDot}[1]{% - \def\TestDot##1.\TestEnd##2\TestStop{\TestPunct{##2}}% - \def\TestPunct##1{\ifx\TestPunct##1\TestPunct\else\@nameauth@Puncttrue\fi}% - \@nameauth@Punctfalse% - \TestDot#1\TestEnd.\TestEnd\TestStop% +\newcommand*{\@nameauth@TestDot}[1]{% + \def\TestDot##1.\TestEnd##2\TestStop{\TestPunct{##2}}% + \def\TestPunct##1{\ifx\TestPunct##1\TestPunct\else\@nameauth@Puncttrue\fi}% + \@nameauth@Punctfalse% + \TestDot#1\TestEnd.\TestEnd\TestStop% } % \end{macrocode} % \end{macro} -% While \texttt{\bsc @CheckDot} looks \emph{ahead} for a period, \texttt{\bsc @TestDot}---based on a snippet by \Name*[Uwe]{Lueck}---checks for a terminal period in the name passed to it, ignoring medial periods. This string test is compatible with the \textsf{microtype} package. +% While \texttt{\bsc @nameauth@CheckDot} looks \emph{ahead} for a period, \texttt{\bsc @nameauth@TestDot}---based on a snippet by \Name*[Uwe]{Lueck}---checks for a terminal period in the name passed to it, ignoring medial periods. This string test is compatible with the \textsf{microtype} package. % -% \begin{macro}{\@FmtName} +% \begin{macro}{\@nameauth@FmtName} +% \changes{v0.8}{2012/01/29}{Renamed macro to help compatibility} % \begin{macrocode} -\DeclareDocumentCommand\@FmtName{s m}% +\DeclareDocumentCommand\@nameauth@FmtName{s m}% {% - \@TestDot{#2}% - \IfBooleanTF{#1}{#2}{\bgroup\NamesFormat{#2}\egroup}% + \@nameauth@TestDot{#2}% + \IfBooleanTF{#1}{#2}{\bgroup\NamesFormat{#2}\egroup}% } % \end{macrocode} % \end{macro} -% \texttt{\bsc @FmtName} is where the first occurrences of a name are formatted. Notice how \texttt{\bsc NamesFormat} sits between a \texttt{\bsc bgroup} and an \texttt{\bsc egroup} to localize the font change. It is adjacent to the brackets that enclose the second parameter, allowing one to hook into the name formatting procedure. +% \texttt{\bsc @nameauth@FmtName} is where the first occurrences of a name are formatted. Notice how \texttt{\bsc NamesFormat} sits between a \texttt{\bsc bgroup} and an \texttt{\bsc egroup} to localize the font change. It is adjacent to the brackets that enclose the second parameter, allowing one to hook into the name formatting procedure. % -% \begin{macro}{\@FName} +% \subsection{User Interface Macros} +% \begin{macro}{\Name} % \changes{v0.75}{2012/01/19}{Added ``sobriquet'' feature} +% \changes{v0.8}{2012/01/29}{Merged all major functionality here} % \begin{macrocode} -\DeclareDocumentCommand\@FName{o m o}% +\DeclareDocumentCommand\Name{s o m o}% {% - \IfValueTF{#1}% - {\IfValueTF{#3}{\def\@ForeNames{#3}}{\def\@ForeNames{#1}}% - \ifcsname\@CleanName{#1#2!PN!}\endcsname% - \@FmtName*{#1 #2}% + \@nameauth@Punctfalse% + \IfValueTF{#2}% + {\IfValueTF{#4}{\def\@ForeNames{#4}}{\def\@ForeNames{#2}}% + \ifcsname\@nameauth@CleanName{#2#3!PN!}\endcsname% + \@nameauth@FmtName*{#2 #3}% \PackageWarning{nameauth}% - {You cannot create a page reference from the pen name: #1 #2.}% + {You cannot create a page reference from the pen name: #2 #3.}% \else% \if@nameauth@DoFormat% - \ifcsname\@CleanName{#1#2!MN!}\endcsname% - \@FmtName*{\@ForeNames{\space}#2}\index{#2,{\space}#1}% + \ifcsname\@nameauth@CleanName{#2#3!MN!}\endcsname% + \IfBooleanTF{#1}% + {\@nameauth@FmtName*{\@ForeNames{\space}#3}\index{#3,{\space}#2}}% + {\@nameauth@FmtName*{\@nameauth@Zapsuffix{#3}}\index{#3,{\space}#2}}% \else% - \csgdef{\@CleanName{#1#2!MN!}}{}% - \@FmtName{\@ForeNames{\space}#2}\index{#2,{\space}#1}% + \csgdef{\@nameauth@CleanName{#2#3!MN!}}{}% + \@nameauth@FmtName{\@ForeNames{\space}#3}\index{#3,{\space}#2}% \fi% \else% - \ifcsname\@CleanName{#1#2!NF!}\endcsname% - \@FmtName*{\@ForeNames{\space}#2}\index{#2,{\space}#1}% + \ifcsname\@nameauth@CleanName{#2#3!NF!}\endcsname% + \IfBooleanTF{#1}% + {\@nameauth@FmtName*{\@ForeNames{\space}#3}\index{#3,{\space}#2}}% + {\@nameauth@FmtName*{\@nameauth@Zapsuffix{#3}}\index{#3,{\space}#2}}% \else% - \csgdef{\@CleanName{#1#2!NF!}}{}% - \@FmtName*{\@ForeNames{\space}#2}\index{#2,{\space}#1}% + \csgdef{\@nameauth@CleanName{#2#3!NF!}}{}% + \@nameauth@FmtName*{\@ForeNames{\space}#3}\index{#3,{\space}#2}% \fi% \fi% \fi}% - {\IfValueTF{#3} - {\ifcsname\@CleanName{#2#3!PN!}\endcsname% - \@FmtName*{#2 #3}% + {\IfValueTF{#4} + {\ifcsname\@nameauth@CleanName{#3#4!PN!}\endcsname% + \@nameauth@FmtName*{#3 #4}% \PackageWarning{nameauth}% - {You cannot create a page reference from the pen name: #2 #3.}% + {You cannot create a page reference from the pen name: #3 #4.}% \else% \if@nameauth@DoFormat% - \ifcsname\@CleanName{#2#3!MN!}\endcsname% - \@FmtName*{#2 #3}\index{#2 #3}% + \ifcsname\@nameauth@CleanName{#3#4!MN!}\endcsname% + \IfBooleanTF{#1}% + {\@nameauth@FmtName*{#3 #4}\index{#3 #4}}% + {\@nameauth@FmtName*{\@nameauth@Zapsuffix{#3}}\index{#3 #4}}% \else% - \csgdef{\@CleanName{#2#3!MN!}}{}% - \@FmtName{#2 #3}\index{#2 #3}% - \fi% + \csgdef{\@nameauth@CleanName{#3#4!MN!}}{}% + \@nameauth@FmtName{#3 #4}\index{#3 #4}% + \fi% \else% - \ifcsname\@CleanName{#2#3!NF!}\endcsname% - \@FmtName*{#2 #3}\index{#2 #3}% + \ifcsname\@nameauth@CleanName{#3#4!NF!}\endcsname% + \IfBooleanTF{#1}% + {\@nameauth@FmtName*{#3 #4}\index{#3 #4}}% + {\@nameauth@FmtName*{\@nameauth@Zapsuffix{#3}}\index{#3 #4}}% \else% - \csgdef{\@CleanName{#2#3!NF!}}{}% - \@FmtName*{#2 #3}\index{#2 #3}% - \fi% + \csgdef{\@nameauth@CleanName{#3#4!NF!}}{}% + \@nameauth@FmtName*{#3 #4}\index{#3 #4}% + \fi% \fi% \fi}% - {\ifcsname\@CleanName{#2!PN!}\endcsname% - \@FmtName*{#2}% + {\ifcsname\@nameauth@CleanName{#3!PN!}\endcsname% + \@nameauth@FmtName*{#3}% \PackageWarning{nameauth}% - {You cannot create a page reference from the pen name: #2.}% + {You cannot create a page reference from the pen name: #3.}% \else% \if@nameauth@DoFormat% - \ifcsname\@CleanName{#2!MN!}\endcsname% - \@FmtName*{#2}\index{#2}% + \ifcsname\@nameauth@CleanName{#3!MN!}\endcsname% + \IfBooleanTF{#1}% + {\@nameauth@FmtName*{#3}\index{#3}}% + {\@nameauth@FmtName*{\@nameauth@Zapsuffix{#3}}\index{#3}}% \else% - \csgdef{\@CleanName{#2!MN!}}{}% - \@FmtName{#2}\index{#2}% - \fi% + \csgdef{\@nameauth@CleanName{#3!MN!}}{}% + \@nameauth@FmtName{#3}\index{#3}% + \fi% \else% - \ifcsname\@CleanName{#2!NF!}\endcsname% - \@FmtName*{#2}\index{#2}% - \else% - \csgdef{\@CleanName{#2!NF!}}{}% - \@FmtName*{#2}\index{#2}% + \ifcsname\@nameauth@CleanName{#3!NF!}\endcsname% + \IfBooleanTF{#1}% + {\@nameauth@FmtName*{#3}\index{#3}}% + {\@nameauth@FmtName*{\@nameauth@Zapsuffix{#3}}\index{#3}}% + \else% + \csgdef{\@nameauth@CleanName{#3!NF!}}{}% + \@nameauth@FmtName*{#3}\index{#3}% \fi% \fi% \fi}% }% + \if@nameauth@Punct\expandafter\@nameauth@CheckDot\fi% } % \end{macrocode} % \end{macro} % -% \texttt{\bsc @FName} (full name) first checks for the forenames argument. Two outcomes are possible. +% \texttt{\bsc Name} first checks for the forenames argument. Two outcomes are possible. % \begin{enumerate} % \item Forenames are present. In this case, the alternate names argument creates two choices. % \begin{enumerate} @@ -679,104 +797,17 @@ % \end{enumerate} % \end{enumerate} % -% A check occurs for a control sequence based on the names given and the suffix \texttt{!PN!} (for pen name) wrapped in a pair of bangs. This is how \texttt{\bsc AKA} protects cross-references. If the control sequence exists, then \texttt{\bsc @FName} only prints the name given and emits a warning. One cannot use \texttt{\bsc ForgetName} to expunge a pen name. This is a deliberate decision to avoid corruption of the index cross-references. +% A check occurs for a control sequence based on the names given and the suffix \texttt{!PN!} (for pen name). This is how \texttt{\bsc AKA} protects cross-references. If the control sequence exists, then \texttt{\bsc Name} only prints the name given and emits a warning. One cannot use \texttt{\bsc ForgetName} to expunge a pen name. This is a deliberate decision to avoid corruption of the index cross-references. % -% The next branch involves the boolean value \texttt{@nameauth@DoFormat}, which is controlled by \texttt{\bsc NamesActive} and \texttt{\bsc NamesInactive}. If formatting is active, choose the unstarred form of \texttt{\bsc @FmtName}, which applies the formatting hook. Otherwise use the starred form that applies no formatting. +% The next branch involves the boolean value \texttt{@nameauth@DoFormat}, which is controlled by \texttt{\bsc NamesActive} and \texttt{\bsc NamesInactive}. If formatting is active, choose the unstarred form of \texttt{\bsc @nameauth@FmtName}, which applies the formatting hook. Otherwise use the starred form that applies no formatting. % -% The state of \texttt{@nameauth@DoFormat} also controls the suffix used in the control sequences: \texttt{!MN!} for main name or \texttt{!NF!} for no format. Suffixes are enclosed in pairs of bangs. +% The state of \texttt{@nameauth@DoFormat} also controls the suffix used in the control sequences: \texttt{!MN!} for main name or \texttt{!NF!} for no format. This is the heart of the \texttt{frontmatter} / \texttt{mainmatter} mechanism. % -% \begin{macro}{\@LName} -% \changes{v0.75}{2012/01/19}{Added ``sobriquet'' feature} -% \begin{macrocode} -\DeclareDocumentCommand\@LName{o m o}% -{% - \IfValueTF{#1}% - {\IfValueTF{#3}{\def\@ForeNames{#3}}{\def\@ForeNames{#1}}% - \ifcsname\@CleanName{#1#2!PN!}\endcsname% - \@FmtName*{#1 #2}% - \PackageWarning{nameauth}% - {You cannot create a page reference from the pen name: #1 #2.}% - \else% - \if@nameauth@DoFormat% - \ifcsname\@CleanName{#1#2!MN!}\endcsname% - \@FmtName*{\@Zapsuffix{#2}}\index{#2,{\space}#1}% - \else% - \csgdef{\@CleanName{#1#2!MN!}}{}% - \@FmtName{\@ForeNames{\space}#2}\index{#2,{\space}#1}% - \fi% - \else% - \ifcsname\@CleanName{#1#2!NF!}\endcsname% - \@FmtName*{\@Zapsuffix{#2}}\index{#2,{\space}#1}% - \else% - \csgdef{\@CleanName{#1#2!NF!}}{}% - \@FmtName*{\@ForeNames{\space}#2}\index{#2,{\space}#1}% - \fi% - \fi% - \fi}% - {\IfValueTF{#3} - {\ifcsname\@CleanName{#2#3!PN!}\endcsname% - \@FmtName*{#2 #3}% - \PackageWarning{nameauth}% - {You cannot create a page reference from the pen name: #2 #3.}% - \else% - \if@nameauth@DoFormat% - \ifcsname\@CleanName{#2#3!MN!}\endcsname% - \@FmtName*{\@Zapsuffix{#2}}\index{#2 #3}% - \else% - \csgdef{\@CleanName{#2#3!MN!}}{}% - \@FmtName{#2 #3}\index{#2 #3}% - \fi% - \else% - \ifcsname\@CleanName{#2#3!NF!}\endcsname% - \@FmtName*{\@Zapsuffix{#2}}\index{#2 #3}% - \else% - \csgdef{\@CleanName{#2#3!NF!}}{}% - \@FmtName*{#2 #3}\index{#2 #3}% - \fi% - \fi% - \fi}% - {\ifcsname\@CleanName{#2!PN!}\endcsname% - \@FmtName*{#2}% - \PackageWarning{nameauth}% - {You cannot create a page reference from the pen name: #2.}% - \else% - \if@nameauth@DoFormat% - \ifcsname\@CleanName{#2!MN!}\endcsname% - \@FmtName*{\@Zapsuffix{#2}}\index{#2}% - \else% - \csgdef{\@CleanName{#2!MN!}}{}% - \@FmtName{#2}\index{#2}% - \fi% - \else% - \ifcsname\@CleanName{#2!NF!}\endcsname% - \@FmtName*{\@Zapsuffix{#2}}\index{#2}% - \else% - \csgdef{\@CleanName{#2!NF!}}{}% - \@FmtName*{#2}\index{#2}% - \fi% - \fi% - \fi}% - }% -} -% \end{macrocode} -% \end{macro} -% \texttt{\bsc @LName} (last name only) differs little from \texttt{\bsc @FName} apart from its use of \texttt{\bsc @ZapSuffix} and its printing of surnames only \emph{except} in the first occurrence of a name. One could make a good case that \texttt{\bsc @FName} and \texttt{\bsc @LName} should be combined. When I tried that, the result introduced bugs that proved difficult to track down. This version simply worked, so I stuck with it. +% Where longer and shorter versions of names are printed, there the star parameter controls those outcomes. % -% \Name*[Marc van]{Dongen} provided the basic structure for these two macros. +% The use of \texttt{\bsc expandafter} before \texttt{\bsc @nameauth@CheckDot} works with the other use of \texttt{\bsc expandafter} mentioned with \texttt{\bsc @nameauth@EvalDot} above to move past the closing brace and fetch the period as lookahead. That is only done when the check for a terminal period in the name succeeds. % -% \subsection{User Interface Macros} -% \begin{macro}{\Name} -% \changes{v0.75}{2012/01/19}{Added ``sobriquet'' feature} -% \begin{macrocode} -\DeclareDocumentCommand\Name{s o m o}% -{% - \@nameauth@Punctfalse% - \IfBooleanTF{#1}{\@FName[#2]{#3}[#4]}{\@LName[#2]{#3}[#4]}% - \if@nameauth@Punct\expandafter\@CheckDot\fi% -} -% \end{macrocode} -% \end{macro} -% \texttt{\bsc Name} and \texttt{\bsc Name*} call \texttt{\bsc @LName} and \texttt{\bsc @FName}, respectively. The use of \texttt{\bsc expandafter} before \texttt{\bsc @CheckDot} works with the other use of \texttt{\bsc expandafter} mentioned with \texttt{\bsc @EvalDot} above to move past the closing brace and fetch the period as lookahead. That is only done when the check for a terminal period in the name succeeds. +% \Name*[Marc van]{Dongen} provided the basic structure for this macro. % % \begin{macro}{\PName} % \begin{macrocode} @@ -796,19 +827,21 @@ {% \@nameauth@Punctfalse% \IfValueTF{#3}% - {\@FmtName*{#3 #4}\ifcsname\@CleanName{#3#4!PN!}\endcsname\relax\else% - \csgdef{\@CleanName{#3#4!PN!}}{}% - \IfValueTF{#1}% - {\index{#4,{\space}#3|see{#2,{\space}#1}}}% - {\index{#4,{\space}#3|see{#2}}}% - \fi}% - {\@FmtName*{#4}\ifcsname\@CleanName{#4!PN!}\endcsname\relax\else% - \csgdef{\@CleanName{#4!PN!}}{}% - \IfValueTF{#1}% - {\index{#4|see{#2,{\space}#1}}}% - {\index{#4|see{#2}}}% - \fi}% - \if@nameauth@Punct\expandafter\@CheckDot\fi% + {\@nameauth@FmtName*{#3 #4}% + \ifcsname\@nameauth@CleanName{#3#4!PN!}\endcsname\relax\else% + \csgdef{\@nameauth@CleanName{#3#4!PN!}}{}% + \IfValueTF{#1}% + {\index{#4,{\space}#3|see{#2,{\space}#1}}}% + {\index{#4,{\space}#3|see{#2}}}% + \fi}% + {\@nameauth@FmtName*{#4}% + \ifcsname\@nameauth@CleanName{#4!PN!}\endcsname\relax\else% + \csgdef{\@nameauth@CleanName{#4!PN!}}{}% + \IfValueTF{#1}% + {\index{#4|see{#2,{\space}#1}}}% + {\index{#4|see{#2}}}% + \fi}% + \if@nameauth@Punct\expandafter\@nameauth@CheckDot\fi% } % \end{macrocode} % \end{macro} @@ -821,10 +854,13 @@ \DeclareDocumentCommand\IndexName{o m o}% {% \IfValueTF{#1}% - {\ifcsname\@CleanName{#1#2!PN!}\endcsname\else\index{#2,{\space}#1}\fi}% + {\ifcsname\@nameauth@CleanName{#1#2!PN!}\endcsname% + \else\index{#2,{\space}#1}\fi}% {\IfValueTF{#3} - {\ifcsname\@CleanName{#2#3!PN!}\endcsname\else\index{#2 #3}\fi} - {\ifcsname\@CleanName{#2!PN!}\endcsname\else\index{#2}\fi}% + {\ifcsname\@nameauth@CleanName{#2#3!PN!}\endcsname% + \else\index{#2 #3}\fi} + {\ifcsname\@nameauth@CleanName{#2!PN!}\endcsname% + \else\index{#2}\fi}% }% } % \end{macrocode} @@ -838,16 +874,19 @@ \DeclareDocumentCommand\ForgetName{o m o}% {% \IfValueTF{#1}% - {\csundef{\@CleanName{#1#2!MN!}}\csundef{\@CleanName{#1#2!NF!}}}% + {\csundef{\@nameauth@CleanName{#1#2!MN!}}% + \csundef{\@nameauth@CleanName{#1#2!NF!}}}% {\IfValueTF{#3}% - {\csundef{\@CleanName{#2#3!MN!}}\csundef{\@CleanName{#2#3!NF!}}}% - {\csundef{\@CleanName{#2!MN!}}\csundef{\@CleanName{#2!NF!}}}% + {\csundef{\@nameauth@CleanName{#2#3!MN!}}% + \csundef{\@nameauth@CleanName{#2#3!NF!}}}% + {\csundef{\@nameauth@CleanName{#2!MN!}}% + \csundef{\@nameauth@CleanName{#2!NF!}}}% }% } % \end{macrocode} % \end{macro} % -% \texttt{\bsc ForgetName} uses the \eTeX facilities to undefine control sequences that \texttt{\bsc @FName} and \texttt{\bsc @LName} use to define them. Using \texttt{\bsc @ifdefined} does not create a control sequence equivalent to \texttt{\bsc relax}, thus using less resources. +% \texttt{\bsc ForgetName} uses the \eTeX facilities to undefine control sequences created by \texttt{\bsc Name}. Using \texttt{\bsc @ifdefined} does not create a control sequence equivalent to \texttt{\bsc relax}, thus using less resources. % % \begin{macro}{\NamesInactive} % \begin{macrocode} @@ -862,10 +901,8 @@ \newcommand{\NamesActive}{\@nameauth@DoFormattrue} % \end{macrocode} % \end{macro} -% -% \begin{macrocode} +% \clearpage \endinput -% \end{macrocode} % % \iffalse % -- cgit v1.2.3