summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2012-01-30 23:49:34 +0000
committerKarl Berry <karl@freefriends.org>2012-01-30 23:49:34 +0000
commit034fde36e1b3172016db6037511e0118d5ed04f6 (patch)
tree21feb78903f5f2df15a65c42ddce12ee5dc43fd9 /Master/texmf-dist/source/latex
parentdfc05b7d118ea655b9bb7c08ac6a7c74eecafa22 (diff)
nameauth (30jan12)
git-svn-id: svn://tug.org/texlive/trunk@25244 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/source/latex')
-rw-r--r--Master/texmf-dist/source/latex/nameauth/nameauth.dtx441
1 files changed, 239 insertions, 202 deletions
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 @@
%<package>\NeedsTeXFormat{LaTeX2e}[2005/12/01]
%<package>\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]
%</package>
%
%<*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 @@
%</driver>
% \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
%</package>