summaryrefslogtreecommitdiff
path: root/Master
diff options
context:
space:
mode:
Diffstat (limited to 'Master')
-rw-r--r--Master/texmf-dist/doc/latex/nameauth/Makefile4
-rw-r--r--Master/texmf-dist/doc/latex/nameauth/README5
-rw-r--r--Master/texmf-dist/doc/latex/nameauth/README.txt5
-rw-r--r--Master/texmf-dist/doc/latex/nameauth/examples.tex179
-rw-r--r--Master/texmf-dist/doc/latex/nameauth/nameauth.pdfbin804568 -> 817013 bytes
-rw-r--r--Master/texmf-dist/source/latex/nameauth/nameauth.dtx1212
-rw-r--r--Master/texmf-dist/source/latex/nameauth/nameauth.ins4
-rw-r--r--Master/texmf-dist/tex/latex/nameauth/nameauth.sty125
8 files changed, 1115 insertions, 419 deletions
diff --git a/Master/texmf-dist/doc/latex/nameauth/Makefile b/Master/texmf-dist/doc/latex/nameauth/Makefile
index e3989ed9cba..67fcb7ed051 100644
--- a/Master/texmf-dist/doc/latex/nameauth/Makefile
+++ b/Master/texmf-dist/doc/latex/nameauth/Makefile
@@ -28,13 +28,15 @@ inst: all
cp Makefile $(UTREE)/source/latex/$(NAME)
cp $(NAME).sty $(UTREE)/tex/latex/$(NAME)
cp $(NAME).pdf $(UTREE)/doc/latex/$(NAME)
+ cp examples.tex $(UTREE)/doc/latex/$(NAME)
install: all
sudo mkdir -p $(LOCAL)/{tex,source,doc}/latex/$(NAME)
sudo cp $(NAME).dtx $(LOCAL)/source/latex/$(NAME)
sudo cp Makefile $(LOCAL)/source/latex/$(NAME)
sudo cp $(NAME).sty $(LOCAL)/tex/latex/$(NAME)
sudo cp $(NAME).pdf $(LOCAL)/doc/latex/$(NAME)
+ sudo cp examples.tex $(LOCAL)/doc/latex/$(NAME)
zip: all
ln -sf . $(NAME)
- zip -Drq $(PWD)/$(NAME)-$(VERS).zip $(NAME)/{README,Makefile,$(NAME).{pdf,dtx}}
+ zip -Drq $(PWD)/$(NAME)-$(VERS).zip $(NAME)/{README,examples.tex,Makefile,$(NAME).{pdf,dtx}}
rm $(NAME)
diff --git a/Master/texmf-dist/doc/latex/nameauth/README b/Master/texmf-dist/doc/latex/nameauth/README
index 1063131bddd..9729f7af648 100644
--- a/Master/texmf-dist/doc/latex/nameauth/README
+++ b/Master/texmf-dist/doc/latex/nameauth/README
@@ -16,6 +16,7 @@ Files Distribution
README This file
nameauth.pdf Documentation
+examples.tex Some longer example macros from the documentation
Makefile Automates building with GNU make 3.81
nameauth.dtx Documented LaTeX file containing both code and documentation
@@ -59,13 +60,13 @@ Normally you create the following manual installation directories for user:
$TEXMFHOME/source/latex/nameauth dtx file
$TEXMFHOME/tex/latex/nameauth sty file
-$TEXMFHOME/doc/latex/nameauth pdf file
+$TEXMFHOME/doc/latex/nameauth pdf file, README, examples.tex
and you create the following manual installation directories for local site:
$TEXMFLOCAL/source/latex/nameauth dtx file
$TEXMFLOCAL/tex/latex/nameauth sty file
-$TEXMFLOCAL/doc/latex/nameauth pdf file
+$TEXMFLOCAL/doc/latex/nameauth pdf file, README, examples.tex
The above environment variables often are /usr/local/texlive/texmf-local and
~/texmf.
diff --git a/Master/texmf-dist/doc/latex/nameauth/README.txt b/Master/texmf-dist/doc/latex/nameauth/README.txt
index 1063131bddd..9729f7af648 100644
--- a/Master/texmf-dist/doc/latex/nameauth/README.txt
+++ b/Master/texmf-dist/doc/latex/nameauth/README.txt
@@ -16,6 +16,7 @@ Files Distribution
README This file
nameauth.pdf Documentation
+examples.tex Some longer example macros from the documentation
Makefile Automates building with GNU make 3.81
nameauth.dtx Documented LaTeX file containing both code and documentation
@@ -59,13 +60,13 @@ Normally you create the following manual installation directories for user:
$TEXMFHOME/source/latex/nameauth dtx file
$TEXMFHOME/tex/latex/nameauth sty file
-$TEXMFHOME/doc/latex/nameauth pdf file
+$TEXMFHOME/doc/latex/nameauth pdf file, README, examples.tex
and you create the following manual installation directories for local site:
$TEXMFLOCAL/source/latex/nameauth dtx file
$TEXMFLOCAL/tex/latex/nameauth sty file
-$TEXMFLOCAL/doc/latex/nameauth pdf file
+$TEXMFLOCAL/doc/latex/nameauth pdf file, README, examples.tex
The above environment variables often are /usr/local/texlive/texmf-local and
~/texmf.
diff --git a/Master/texmf-dist/doc/latex/nameauth/examples.tex b/Master/texmf-dist/doc/latex/nameauth/examples.tex
new file mode 100644
index 00000000000..5719834e614
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/nameauth/examples.tex
@@ -0,0 +1,179 @@
+% This is an example file used with the nameauth package.
+%
+%
+% Below we print the argument both in the text and in a margin paragraph
+% unless we are in internal vertical mode.
+%
+% This macro is suitable to replace \NamesFormat and \FrontNamesFormat.
+%
+\renewcommand*\NamesFormat[1]%
+{%
+ #1%
+ \ifinner
+ \else
+ \marginpar{\raggedleft\scriptsize #1}%
+ \fi
+}
+%
+% Below we print the argument in the text and then we query the text tag
+% database to see if we can print a text tag after the argument.
+%
+% This macro is suitable to replace \NamesFormat and \FrontNamesFormat.
+%
+\newif\ifNoTextTag
+\makeatletter
+\renewcommand*\NamesFormat[1]%
+{%
+ \let\ex\expandafter%
+ #1%
+ \if@nameauth@InName
+ \ifNoTextTag
+ \else
+ \ex\ex\ex\ex\ex\ex\ex\NameQueryInfo\ex\ex\ex\ex\ex\ex\ex[%
+ \ex\ex\ex\the\ex\ex\ex\@nameauth@toksa\ex\ex\ex]%
+ \ex\ex\ex{\ex\the\ex\@nameauth@toksb\ex}\ex[\the\@nameauth@toksc]%
+ \fi
+ \fi
+ \if@nameauth@InAKA
+ \ifNoTextTag
+ \else
+ \ex\ex\ex\ex\ex\ex\ex\NameQueryInfo\ex\ex\ex\ex\ex\ex\ex[%
+ \ex\ex\ex\the\ex\ex\ex\@nameauth@toksa\ex\ex\ex]%
+ \ex\ex\ex{\ex\the\ex\@nameauth@toksb\ex}\ex[\the\@nameauth@toksc]%
+ \fi
+ \fi
+ \global\NoTextTagfalse%
+}
+\makeatother
+%
+% Below we create a Boolean value \ifSC and set it true.
+%
+% We then create a macro \DoFormat that prints its argument in
+% small caps if a Boolean value is true, or makes no font change
+% and prints the the argument of the value is false.
+%
+% The next macro ignores its argument, sets \SCfalse, then
+% uses some control sequences internal to the naming macros to
+% parse and print the current name values without any formatting.
+%
+% The final macro is suitable to replace \MainNameHook and \FrontNameHook.
+%
+\makeatletter
+\newif\ifSC
+\SCtrue
+\def\DoFormat#1{%
+ \ifSC
+ \textsc{#1}%
+ \else
+ #1%
+ \fi
+}
+\newcommand*\MainNameHook[1]{%
+ \let\ex\expandafter%
+ \SCfalse\ignorespaces%
+ \protected@edef\arga{\ex\trim@spaces\ex{\the\@nameauth@toksa}}%
+ \protected@edef\argb{\ex\trim@spaces\ex{\the\@nameauth@toksb}}%
+ \protected@edef\testb{\ex\@nameauth@Root\ex{\the\@nameauth@toksb}}%
+ \protected@edef\argc{\ex\trim@spaces\ex{\the\@nameauth@toksc}}%
+ \ifx\argb\testb
+ \protected@edef\Suff{\@empty}%
+ \let\Reversed\argb%
+ \let\SNN\argb%
+ \let\Short\argb%
+ \else
+ \protected@edef\Suff{\ex\@nameauth@Suffix\ex{\the\@nameauth@toksb}}%
+ \protected@edef\Reversed{\Suff\Space\testb}%
+ \protected@edef\SNN{\testb\Space\Suff}%
+ \if@nameauth@RevThis
+ \let\Short\Suff%
+ \else
+ \let\Short\testb%
+ \fi
+ \fi
+ \if@nameauth@InAKA
+ \ifx\arga\@empty
+ \ifx\argc\@empty
+ \if@nameauth@RevThis
+ \Reversed%
+ \else
+ \SNN%
+ \fi
+ \else
+ \if@nameauth@AltAKA
+ \argc%
+ \else
+ \if@nameauth@RevThis
+ \ex\argc\ex\Space\SNN%
+ \else
+ \ex\SNN\ex\space\argc%
+ \fi
+ \fi
+ \fi
+ \else
+ \ifx\argc\@empty
+ \let\FNN\arga%
+ \else
+ \let\FNN\argc%
+ \fi
+ \if@nameauth@AltAKA
+ \FNN%
+ \else
+ \if@nameauth@RevThis
+ \ex\SNN\ex\Space\FNN%
+ \else
+ \ex\FNN\ex\space\SNN%
+ \fi
+ \fi
+ \fi
+ \else
+ \ifx\arga\@empty
+ \ifx\argc\@empty
+ \if@nameauth@FullName
+ \if@nameauth@RevThis
+ \Reversed%
+ \else
+ \SNN%
+ \fi
+ \else
+ \Short%
+ \fi
+ \else
+ \if@nameauth@FullName
+ \if@nameauth@RevThis
+ \ex\argc\ex\space\SNN%
+ \else
+ \ex\SNN\ex\space\argc%
+ \fi
+ \else
+ \if@nameauth@RevThis
+ \argc%
+ \else
+ \Short%
+ \fi
+ \fi
+ \fi
+ \else
+ \ifx\argc\@empty
+ \let\FNN\arga%
+ \else
+ \let\FNN\argc%
+ \fi
+ \let\Short\FNN%
+ \if@nameauth@FullName
+ \if@nameauth@RevThis
+ \ex\SNN\ex\Space\FNN%
+ \else
+ \ex\FNN\ex\space\SNN%
+ \fi
+ \else
+ \if@nameauth@FirstName
+ \Short%
+ \else
+ \testb%
+ \fi
+ \fi
+ \fi
+ \fi
+}
+\makeatother
+
diff --git a/Master/texmf-dist/doc/latex/nameauth/nameauth.pdf b/Master/texmf-dist/doc/latex/nameauth/nameauth.pdf
index 914d0935b89..f7a04d2b1ff 100644
--- a/Master/texmf-dist/doc/latex/nameauth/nameauth.pdf
+++ b/Master/texmf-dist/doc/latex/nameauth/nameauth.pdf
Binary files differ
diff --git a/Master/texmf-dist/source/latex/nameauth/nameauth.dtx b/Master/texmf-dist/source/latex/nameauth/nameauth.dtx
index eb0f6f57201..67e6c6be43e 100644
--- a/Master/texmf-dist/source/latex/nameauth/nameauth.dtx
+++ b/Master/texmf-dist/source/latex/nameauth/nameauth.dtx
@@ -23,6 +23,7 @@ Files Distribution
README This file
nameauth.pdf Documentation
+examples.tex Some longer example macros from the documentation
Makefile Automates building with GNU make 3.81
nameauth.dtx Documented LaTeX file containing both code and documentation
@@ -66,13 +67,13 @@ Normally you create the following manual installation directories for user:
$TEXMFHOME/source/latex/nameauth dtx file
$TEXMFHOME/tex/latex/nameauth sty file
- $TEXMFHOME/doc/latex/nameauth pdf file
+ $TEXMFHOME/doc/latex/nameauth pdf file, README, examples.tex
and you create the following manual installation directories for local site:
$TEXMFLOCAL/source/latex/nameauth dtx file
$TEXMFLOCAL/tex/latex/nameauth sty file
- $TEXMFLOCAL/doc/latex/nameauth pdf file
+ $TEXMFLOCAL/doc/latex/nameauth pdf file, README, examples.tex
The above environment variables often are /usr/local/texlive/texmf-local and
~/texmf.
@@ -130,7 +131,7 @@ http://www.latex-project.org/lppl.txt
This work is "maintained" (as per LPPL maintenance status) by
Charles P. Schaum.
-This work consists of the file nameauth.dtx and a Makefile.
+This work consists of the files nameauth.dtx, examples.tex, and a Makefile.
Running "make" generates the derived files README, nameauth.pdf and nameauth.sty.
Running "make inst" installs the files in the user's TeX tree.
Running "make install" installs the files in the local TeX tree.
@@ -168,7 +169,7 @@ Running "make install" installs the files in the local TeX tree.
%<package>\NeedsTeXFormat{LaTeX2e}[1999/12/01]
%<package>\ProvidesPackage{nameauth}
%<*package>
- [2016/03/18 v2.42 Name authority mechanism for consistency in text and index]
+ [2016/04/06 v2.5 Name authority mechanism for consistency in text and index]
%</package>
%<*driver>
\documentclass[11pt]{ltxdoc}
@@ -249,6 +250,12 @@ Running "make install" installs the files in the local TeX tree.
\< KempW & Thomas & à~Kempis & >
\< Lewis & Clive Staples & Lewis & C.S. >
\< Jack & Clive Staples & Lewis & Jack >
+ \< JQA & John Quincy & \noexpand\DoFormat{Adams} & >
+ \< Aeths & & \noexpand\DoFormat{Æþelstan} & >
+ \< Chas & & \noexpand\DoFormat{Charles}, I & >
+ \< Cao & & \noexpand\DoFormat{Cao}, Cao & >
+ \< JRIII & John David & \noexpand\DoFormat{Rockefeller}, III & >
+ \< SDJR & Sammy & \noexpand\DoFormat{Davis}, \noexpand\DoFormat{Jr}. & >
\end{nameauth}
\TagName[George]{Washington}{, president|hyperpage}
\TagName[Hernando]{de Soto}{|hyperpage}
@@ -277,7 +284,7 @@ Running "make install" installs the files in the local TeX tree.
\TagName[Walter]{de la Mare}{|hyperpage}
\TagName[Johann Wolfgang von]{Goethe}{|hyperpage}
\TagName[Adolf]{Harnack}{|hyperpage}
-\TagName{Antiochus, IV}{ Epiphanes, king|hyperpage}
+\TagName{Antiochus, IV}{ Epi\-phanes, king|hyperpage}
\TagName{Chiang}[Kai-shek]{, president|hyperpage}
\TagName{Louis, XIV}{, king|hyperpage}
\TagName{Leo, I}{, pope|hyperpage}
@@ -358,6 +365,19 @@ Running "make install" installs the files in the local TeX tree.
\TagName[Mustafa]{Kemal}{|hyperpage}
\PretagName[Catherine]{\textsc{de'~Medici}}{de Medici, Catherine}
\TagName[Catherine]{\textsc{de'~Medici}}{|hyperpage}
+\PretagName[John Quincy]{\noexpand\DoFormat{Adams}}{Adams, John Quincy}
+\TagName[John Quincy]{\noexpand\DoFormat{Adams}}{, president|hyperpage}
+\PretagName{\noexpand\DoFormat{Æþelstan}}{Aethelstan}
+\TagName{\noexpand\DoFormat{Æþelstan}}{, king|hyperpage}
+\PretagName{\noexpand\DoFormat{Charles}, I}{Charles 1}
+\TagName{\noexpand\DoFormat{Charles}, I}{, king|hyperpage}
+\PretagName{\noexpand\DoFormat{Cao}, Cao}{Cao Cao}
+\TagName{\noexpand\DoFormat{Cao}, Cao}{|hyperpage}
+\PretagName[John David]{\noexpand\DoFormat{Rockefeller}, III}{Rockefeller, John David, III}
+\TagName[John David]{\noexpand\DoFormat{Rockefeller}, III}{|hyperpage}
+\PretagName[Sammy]{\noexpand\DoFormat{Davis}, \noexpand\DoFormat{Jr}.}{Davis, Sammy, Jr.}
+\TagName[Sammy]{\noexpand\DoFormat{Davis}, \noexpand\DoFormat{Jr}.}{|hyperpage}
+\PretagName{\noexpand\DoFormat{Mengde}}{Mengde}
\IndexActual{=}
\begin{document}
\DocInput{\jobname.dtx}
@@ -365,7 +385,7 @@ Running "make install" installs the files in the local TeX tree.
%</driver>
% \fi
%
-% \CheckSum{3249}
+% \CheckSum{3321}
%
% \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
@@ -404,12 +424,17 @@ Running "make install" installs the files in the local TeX tree.
% \changes{v2.2}{2015/12/01}{Add interface hooks and docs; fix bugs}
% \changes{v2.3}{2016/01/05}{Improve docs and hooks; add features}
% \changes{v2.4}{2016/03/15}{Add text tagging features, add generic hooks, and prevent recursion}
-% \changes{v2.41}{2016/03/17}{instantiate token registers only once}
-% \changes{v2.42}{2016/03/18}{do not use \cmd{\cmd} in section headings}
+% \changes{v2.41}{2016/03/17}{Instantiate token registers only once}
+% \changes{v2.42}{2016/03/18}{Do not use \cmd{\cmd} in section headings}
+% \changes{v2.5}{2016/04/06}{More examples; no default formatting}
% \GetFileInfo{\jobname.dtx}
% \DoNotIndex{\@empty, \@gobble, \@period, \@token, \trim@spaces, \zap@space}
% \DoNotIndex{\begingroup, \bfseries, \bgroup, \csdef, \csgdef, \csname, \csundef, \DeclareOption, \def, \detokenize, \edef, \egroup, \else, \endcsname, \endgroup, \endinput, \ExecuteOptions, \expandafter, \fi, \futurelet, \global, \hbox, \if, \ifcsname, \ifx, \ignorespaces, \index, \itshape, \leavevmode, \let, \newcommand, \newcommandx, \newenvironment, \newif, \nobreakspace, \PackageError, \PackageWarning, \ProcessOptions, \relax, \renewcommand, \RequirePackage, \scshape, \space, \textbackslash, \uppercase}
%
+% \newif\ifSC
+% \SCtrue
+% \def\DoFormat#1{\ifSC\textsc{#1}\else#1\fi}
+%
%\title{\textsf{nameauth} --- Name authority mechanism for consistency in text and index\thanks{This file
% describes version \fileversion, last revised \filedate.}
%}
@@ -417,7 +442,7 @@ Running "make install" installs the files in the local TeX tree.
%\date{Released \filedate}
%
%\maketitle
-%
+%
% \begin{abstract}
% \noindent The \textsf{nameauth} package automates the formatting and indexing of names. This aids the use of a \textbf{name authority} and the process of textual reordering and revision without needing to retype name references.
% \end{abstract}
@@ -427,45 +452,60 @@ Running "make install" installs the files in the local TeX tree.
%
% \section{Introduction}
%
-% \subsection{Preliminaries}
+% \subsection{Summary Overview}
%
-% When publications use hundreds of names, it takes time and money to check them. This package automates much of that work. \textbf{Context determines name forms} unless otherwise modified, meaning that \textbf{you usually do not have to retype names} when editing a document. You can \textbf{implement a name authority} that allows for name variants in the text and consistent index entries. With \textsf{nameauth} you can handle some \textbf{cross-cultural naming conventions.} Additionally, you can use \textbf{index sort keys and tags} automatically after assigning them.
+% When publications use hundreds of names, it takes time and money to check them. This package automates much of that work:
+% \begin{itemize}
+% \item \textbf{Context} determines name forms unless otherwise modified.
+% \item The macros \textbf{reduce retyping of names} when editing a document.
+% \item You can implement a \textbf{name authority}, a master list of names that permits known name variants.
+% \item \textbf{Consistent index entries} work with these variants.
+% \item Some \textbf{cross-cultural naming conventions} are possible.
+% \item \textbf{index automatic sort keys and tags} aid cross-cultural work.
+% \end{itemize}
%
% This package grew from generalized needs for translating old German and Latin texts. Design principles include:
% \begin{enumerate}\small
-% \item Format and vary name forms according to standard syntax in the body text, independent of the index.
+% \item Format and vary name forms according to standard syntax in the body text, independent of the index, following English standards:
% \begin{itemize}[noitemsep]
% \item Default to long name references first, then shorter ones.
% \item Use alternate names only in the body text, not the index.
% \item Perform name caps and reversing only in the body text.
% \end{itemize}
-% \item Perform typographic formatting of names only in the body text. Reflect source text typography with English conventions, but only \emph{after} syntactic formatting is complete.
-% \item Allow typographic formatting to be customized and permit control sequences in names (Sections~\ref{sec:accents}, \ref{sec:formatting}, and~\ref{sec:IndexSort}) to allow Continental and non-English standards.
-% \item Always aim to reduce keystrokes.
-% \item Accommodate the broadest set of names while minimizing keystrokes.
+% \item Post-process names only in the body text. Reflect English conventions by default, but only \emph{after} syntactic formatting is complete.
+% \item Enable Continental and non-English standards through modularized post-processing, whose English-standard defaults may be bypassed and modified (Sections~\ref{sec:accents}, \ref{sec:formatting}, \ref{sec:IndexSort}, and~\ref{sec:Hooksc}).
+% \item Reduce keystrokes while accommodating the broadest set of names.
% \end{enumerate}
%
+% \subsection{Milestone Changes}
+%
+% With version 2.5 the \textsf{nameauth} package turns a corner to a new period of cross-cultural use. No formatting is selected by default. Now you can have one format for first uses of names in the main matter, another for first uses in the front matter, and one each for subsequent uses in the main and front matter. This allows for greater customization, depending on individual needs.
+%
+% \subsection{Technical Notes}
% This manual performs something of a ``torture test'' on this package. You might want to avoid doing that if you are a beginner. It is designed to be compatible with A4 and US letter. Macro references are minimized for a ``clean'' index, showing how \textsf{nameauth} handles indexing.
%
% \textsf{Nameauth} depends on \textsf{etoolbox}, \textsf{ifxetex}, \textsf{ifluatex}, \textsf{suffix}, \textsf{trimspaces}, and \textsf{xargs}. It was tested with \texttt{latex,} \texttt{lualatex,} \texttt{pdflatex,} and \texttt{xelatex,} along with \texttt{makeindex} and \texttt{texindy.} This manual was typeset with \ifxetex\texttt{xelatex}\else\ifluatex\ifpdf\texttt{lualatex} in \texttt{pdf} mode\else\texttt{lualatex} in \texttt{dvi} mode\fi\else\ifpdf\texttt{pdflatex}\else\texttt{latex}\fi\fi\fi{} using \texttt{makeindex} and \texttt{gind.ist.}
%
% Indexing generally conforms to the standard in Nancy C. Mulvany, \emph{Indexing Books} (Chicago: University of Chicago Press, 1994). This should be suitable for a very wide application across a number of disciplines.
%
-% Thanks to \Name[Marc van]{Dongen}, \Name[Enrico]{Gregorio}, \Name[Philipp]{Stephani},\break \Name[Heiko]{Oberdiek}, \Name[Uwe]{Lueck}, and \Name[Robert]{Schlicht} for their assistance in the early versions of this package.\vfill
+% \subsection{Thanks}
+%
+% Thanks to \Name[Marc van]{Dongen}, \Name[Enrico]{Gregorio}, \Name[Philipp]{Stephani}, \Name[Heiko]{Oberdiek}, \Name[Uwe]{Lueck}, and \Name[Robert]{Schlicht} for their assistance in the early versions of this package.
+%
%
-% \bgroup\setlength{\fboxsep}{5pt}\noindent\fbox{\parbox{0.97\textwidth}{\small\strut This documentation uses names of living and historical figures because users refer to real people. At no time do I intend any disrespect or statement of bias regarding any particular person, culture, or tradition. All names are used only for teaching purposes.}}\egroup
+% \subsection{Disclaimer}
+%
+% This documentation uses names of living and historical figures because users refer to real people. At no time do I intend any disrespect or statement of bias regarding any particular person, culture, or tradition. All names are used only for teaching purposes.
%\clearpage
%
% \subsection{What's In A Name?}
% \label{sec:NameTypes}
%
-% Name forms are ambiguous apart from historical and cultural contexts. The \textsf{nameauth} package helps you encode names from as many contexts as possible.
+% Name forms are ambiguous apart from historical and cultural contexts. The \textsf{nameauth} package helps you encode names from as many contexts as possible. In this manual we refer to three classes of names, shown below. Professional writing often calls for the full form of a person's name to be used in its first occurrence, with shorter forms used thereafter. This package adapts that principle to the classes of names below.
%
-% In this manual we refer to three classes of names. A ``surnames'' argument, \meta{SNN}, denotes a ``required name,'' that is, a Western surname, an Eastern family name, or an ancient/medieval name.\footnote{Some professional literature speaks of forenames and optional surnames. See Mulvany, \emph{Indexing Books}, pages 152--82, which I used as a guide along with the \emph{Chicago Manual of Style}. That approach does not work in \LaTeX, where we use optional forenames for the same effect.}
+% In each class there is a required ``surnames'' argument, \meta{SNN}. This can be a Western surname, an Eastern family name, or the personal name of an ancient, medieval, or royal person.\footnote{Some professional literature speaks of forenames and optional surnames. See Mulvany, \emph{Indexing Books}, pages 152--82, which I used as a guide along with the \emph{Chicago Manual of Style}. That approach does not work in \LaTeX, where we use optional forenames for the same effect.}
% Other naming systems can be adapted to these categories, \emph{e.g.}, Icelandic, Hungarian, etc.
%
-% Professional writing often calls for the full form of a person's name to be used in its first occurrence, with shorter forms used thereafter. This package adapts that principle to all the forms below.
-%
%\begin{enumerate}[noitemsep]
%\item Western name:\\[1ex]
%\begin{tikzpicture}[line/.style={draw,thick}]\normalsize
@@ -571,37 +611,31 @@ Running "make install" installs the files in the local TeX tree.
% \end{scope}
%\end{tikzpicture}
%\end{enumerate}
-%\clearpage
%
-% Another way to think about these over-generalized classes of names is to pretend that you know \emph{nothing at all} about names. How would you make sense out of the following?
-% \begin{quote}\small\NamesInactive\setstretch{1.2}
+% Another way to think about these classes of names is to pretend that you know \emph{nothing at all} about names. How would you make sense out of the following?
+% \begin{quote}\small\setstretch{1.2}
% \begin{tabular}{lll}\toprule
% Longer Name & Shorter Name & Indexed Name\\\midrule
% \Wash & \Wash\ForgetName[George]{Washington} & Washington, George\\
% \JRII & \JRII\ForgetName[John David]{Rockefeller, II} & Rockefeller, John David, II\\
% \Name*[Clive Staples]{Lewis} & \LLewis & Lewis, Clive Staples\\
% \Name*[Clive Staples]{Lewis} & \LJack\ForgetName[Clive Staples]{Lewis} & Lewis, Clive Staples\\
-% \Yamt & \Yamt\ForgetName{Yammamoto, Isoroku} & Yammamoto Isoroku\\
+% \Yamt & \Yamt\ForgetName{Yamamoto, Isoroku} & Yamamoto Isoroku\\
% \Aris & \Aris\ForgetName{Aristotle} & Aristotle\\
% \Eliz & \Eliz\ForgetName{Elizabeth, I} & Elizabeth I\\
% \Attil & \Attil\ForgetName{Attila, the Hun} & Attila the Hun\\\bottomrule
-% \end{tabular}\NamesActive
+% \end{tabular}
% \end{quote}
%
-% The position of a name alone does not reveal whether it is a personal or family name. You have to know the cultures of the respective names, what the affixes mean, what triggers the different handling of affixes, and so on.
-%
-% Some of the humanities literature says that you should view the forenames as essential and the surnames as optional. Yet problems emerge when you have to drop the forename reference in professional or courteous writing, when you have to consider multiple alternate names, and when you have to consider those cases where the family name comes first.
-%
-% Nevertheless, if you notice a few consistent relationships, that will help you work out how the \textsf{nameauth} package encodes names:
+% The position of a name alone does not reveal whether it is a personal name or a family name. Nevertheless, if you notice a few consistent relationships, that will help you work out how the \textsf{nameauth} package encodes names:
% \begin{enumerate}\small
-% \item The long form of a name corresponds with the reordered indexed form.
-% \item All Western index forms have surname(s) first, followed by a comma, then the forename(s), then a comma if needed, then the affix if it exists.
-% \item All Western name forms have both forename(s) and surname(s). The forename(s) can change/drop in the text, but not in the index.
-% \item Eastern name forms \meta{Surname(s)} \meta{Forename(s)}, with royal and ancient name forms \meta{Name(s)} \meta{Affix}, should not have commas in their index entries. The forename(s) and affixes cannot change (in this package), but they can drop in the text, but not the index.
+% \item The long form of a name corresponds with the reordered indexed form. That means the long forms of names must be the macro arguments.
+% \item All Western index forms have surname(s) first, followed by a comma, then the forename(s), then a comma if needed, then the affix if it exists. That means Western names handle suffixes and name ordering differently than other names.
+% \item All Western name forms have both forename(s) and surname(s). The forename(s) can change/drop in the text, but not in the index. That means the presence of an optional forename denotes a Western name instead of another name form.
+% \item Eastern name forms \meta{Surname(s)} \meta{Forename(s)}, with royal and ancient name forms \meta{Name(s)} \meta{Affix}, should not have commas in their index entries. The forename(s) and affixes cannot change (in this package), but they can drop in the text, but not the index. All these name forms basically work the same, except that an ancient or medieval personal name has the same position that an Eastern family name has. Their arguments, therefore, have much the same syntax.
% \end{enumerate}
-% From this we conclude that all naming macros must be given the long name information in their arguments, then decide what to drop, change, and reorder depending on form and context. Since Eastern, ancient, and royal names share a set of similarities, they can allow context to disambiguate their use, over against Western names, which have to be handled differently.
%
-% All this being said, the publisher's way of handling things may trump the (arguably) canonical way. This package allows some ``borderline'' options and name forms to accommodate that.\footnote{Some publishers not only use commas with Eastern forms in the index, but sometimes the forms are just wrong. For example, one sees \NamesInactive\Name{Sun, Yat-sen} \NamesActive indexed as ``Yat-sen, Sun'' (instead of either ``Sun, Yat-sen'' or ``Sun Yat-sen'') in Immanuel Geiss, \emph{Personen: Die biographische Dimension der Weltgeschichte}, Geschichte Griffbereit vol. 2 (Munich: Wissen Media Verlag, 2002), 720. The six-volume series is otherwise a helpful resource.}
+% All this being said, the publisher's way of handling things may trump the (arguably) canonical way. This package allows some ``borderline'' options and name forms to accommodate that.\footnote{Some publishers not only use commas with Eastern forms in the index, but sometimes the forms are just wrong. For example, one sees \Name{Sun, Yat-sen}\ForgetName{Sun, Yat-sen} indexed as ``Yat-sen, Sun'' (instead of either ``Sun, Yat-sen'' or ``Sun Yat-sen'') in Immanuel Geiss, \emph{Personen: Die biographische Dimension der Weltgeschichte}, Geschichte Griffbereit vol. 2 (Munich: Wissen Media Verlag, 2002), 720. The six-volume series is otherwise a helpful resource.}
% The most prominent example includes the ``non-native'' Eastern names discussed in Sections~\ref{sec:options} and~\ref{sec:Eastern}.
% \clearpage
% \section{Usage}
@@ -612,21 +646,26 @@ Running "make install" installs the files in the local TeX tree.
% |\usepackage[|\meta{$option_1$}|,|\meta{$option_2$}|,|\dots|]{nameauth}|\medskip
%
% \noindent From the user's perspective these options proceed from the most general to more specific details. Package options address the following:
-% \begin{enumerate}
+% \begin{enumerate}[noitemsep]
% \item Enable or disable features (formatting, indexing, index sorting)
% \item Affect the syntax of names (commas, capitalization, and reversing)
% \item Typographic display of names (formatted or not, and how)
% \end{enumerate}
-% \begin{tabular}{p{\textwidth}}\toprule\hfil\bfseries Default options are in boldface.\hfil\\\bottomrule\end{tabular}
%
-% \begin{center}\Large\bfseries Enable/Disable Features\end{center}
+% \noindent\begin{tabular}{p{0.97\textwidth}}\toprule\hfil\bfseries Default options are in boldface.\hfil\\\bottomrule\end{tabular}
+%
+% \begin{center}\Large\bfseries Choose Features\end{center}
%
-% \noindent{\large\bfseries Enable/Disable Formatting}\\[2ex]
+% \noindent{\large\bfseries Choose Formatting}\\[2ex]
% \begin{tabular}{p{0.22\textwidth}p{0.6\textwidth}}
-% \quad\bfseries\texttt{mainmatter} & \bfseries Choose ``main-matter names'' and formatting hooks (see formatting options below), starting at the beginning of a document.\\[1ex]
-% \quad\texttt{frontmatter} & Choose ``front-matter names'' and hooks; retain syntactic formatting.\\[2ex]
+% \quad\bfseries\texttt{mainmatter} & \bfseries Start with ``main-matter names'' and formatting hooks (see page ~\pageref{page:PostProcess}).\\[1ex]
+% \quad\texttt{frontmatter} & Start with ``front-matter names'' and hooks.\\[1ex]
+% \quad\texttt{alwaysformat} & Use only respective ``first use'' formatting hooks.\\[1ex]
+% \quad\texttt{formatAKA} & Format names declared by \cmd{\AKA} like other main- and front-matter names.\\[2ex]
% \end{tabular}\\
-% The default |mainmatter| option starts formatting names immediately. Use the |frontmatter| option to suppress name formatting until you want it to start via \cmd{\NamesActive}. These options have no additional effects on the index, but they implement two completely separate systems of first/subsequent names. These systems manage names in separate contexts. See Section~\ref{sec:DisableFormat}.\bigskip
+% The default |mainmatter| option and the |frontmatter| option enable two different systems of formatting and first/subsequent use. \cmd{\NamesActive} starts the main matter system when |frontmatter| is used. See Section~\ref{sec:FrontFormat}.
+%
+% The \texttt{alwaysformat} option disables ``subsequent use'' hooks globally. Using \texttt{formatAKA} lets \cmd{\AKA} use ``first-use'' hooks for one time and ``subsequent-use'' hooks thereafter, without needing \texttt{alwaysformat.}\bigskip
%
% \noindent{\large\bfseries Enable/Disable Indexing}\\[2ex]
% \begin{tabular}{p{0.22\textwidth}p{0.6\textwidth}}
@@ -671,34 +710,44 @@ Running "make install" installs the files in the local TeX tree.
% \noindent{\large\bfseries Reverse Name Order}\\[2ex]
% \begin{tabular}{p{0.22\textwidth}p{0.6\textwidth}}
% \quad\bfseries\texttt{notreversed} & \bfseries Print names in the order specified by \cmd{\Name} and the other macros.\\[1ex]
-% \quad\texttt{allreversed} & Print name forms in ``smart'' reverse order.\\[1ex]
+% \quad\texttt{allreversed} & Print all name forms in ``smart'' reverse order.\\[1ex]
% \quad\texttt{allrevcomma} & Print all names in ``Surname, Forenames'' order, meant for Western names.\\[2ex]
% \end{tabular}\\
% See Section~\ref{sec:Eastern} for related macros to control name reversing by section or by name. This also affects how Eastern names will appear in the index.
%
% So-called ``last-comma-first'' lists of names via \texttt{allrevcomma} (Section~\ref{sec:LastFirst}) are \emph{not} the same as the \texttt{comma} option. They are designed for Western names.\clearpage
%
-% \begin{center}\Large\bfseries Typographic Display of Names\end{center}
+% \begin{center}\Large\bfseries Name Post-Processing\end{center}
+% \label{page:PostProcess}
%
-% Section~\ref{sec:formatting} explains in greater detail that typographic display is different from the syntactic formatting of names and occurs after syntactic formatting is complete. This package is designed with type hierarchies in mind.\footnote{See Robert Bringhurst, \emph{The Elements of Typographic Style}, version 3.2 (Point Roberts, Washington: Hartley \& Marks, 2008), 53--60.}
+% Sections~\ref{sec:CustomHooks}, \ref{sec:formatting}, and~\ref{sec:Hooksa}ff. explain this topic in greater detail. Post-processing follows syntactic formatting and does not affect the index.\footnote{This package was designed with type hierarchies in mind, although it has become more flexible. See Robert Bringhurst, \emph{The Elements of Typographic Style}, version 3.2 (Point Roberts, Washington: Hartley \& Marks, 2008), 53--60.}
%
-% As of version 2.4, ``typographic formatting'' has become a generalized concept of ``name post-processing'' via the hook macros \cmd{\NamesFormat,} \cmd{\MainNameHook,} and \cmd{\FrontNameHook.} Sections~\ref{sec:formatting} and~\ref{sec:moreC} offer substantially more complex possibilities for such hooks.\footnote{I drew some inspiration from the typography in Bernhard Lohse, \emph{Luthers Theologie} (G\"ottingen: Vandenhoeck \& Ruprecht, 1995) and the five-volume series by Jaroslav J. Pelikan Jr., The Christian Tradition: A History of the Development of Doctrine (Chicago: Chicago UP, 1971--89). Each volume in the series has its own title.}
-%
-% Even though English typography was the design choice for this package, one can use this package in Continental (German, etc.) and other typographic standards, as Section~\ref{sec:formatting} discusses. One must use sort tags, as Section~\ref{sec:IndexSort} explains.
+% As of version 2.4, ``typographic formatting'' has become a generalized concept of ``name post-processing'' via these hook macros:
+% \begin{itemize}
+% \item \cmd{\NamesFormat} formats first uses of main-matter names.
+% \item \cmd{\MainNameHook} formats subsequent uses of main-matter names.
+% \item \cmd{\FrontNamesFormat} formats first uses of front-matter names.
+% \item \cmd{\FrontNameHook} formats subsequent uses of front-matter names.
+% \end{itemize}
%
-% Continental standards include formatting surnames only. However, \textsf{nameauth} uses some ambiguous name forms.\footnote{By default, \textsf{nameauth} uses a ``serendipitous ambiguity'' of ancient, Eastern, and suffixed name forms handled by the \meta{Surname, affix} pattern that is resolved subtly by several factors.}
-% Continental users must add control sequences directly in the naming macro arguments. In that case, use the |noformat| option and the simplified interface to minimize keystrokes. Continental users may lose some capitalization features; see Section~\ref{sec:standards}.
+% Sections~\ref{sec:CustomHooks} and~\ref{sec:Hooksa}ff. offer substantially more complex possibilities for such hooks.\footnote{I drew some inspiration from the typography in Bernhard Lohse, \emph{Luthers Theologie} (G\"ottingen: Vandenhoeck \& Ruprecht, 1995) and the five-volume series by Jaroslav J. Pelikan Jr., The Christian Tradition: A History of the Development of Doctrine (Chicago: Chicago UP, 1971--89). Each volume in the series has its own title.}
+% By default, they do nothing.
%
-% Otherwise, the options below are meant generally for applications in English typography. The default is |smallcaps| because this package was developed to aid my editing and translation of older German and Latin documents into English. I do apologize for any inconvenience in design choices.\bigskip
+% English typography has been the default design choice for this package. Still, one can use German, French, and similar standards, which I group as ``Continental.'' Sections~\ref{sec:formatting} and~\ref{sec:Hooksc} have more on the topic, as well as the use of sort tags in Section~\ref{sec:IndexSort}. Continental standards format surnames only, both in the text and in the index. This conflicts with some deliberately ambiguous name forms in \textsf{nameauth}.\footnote{Ancient, Eastern, and suffixed name forms have the same pattern.}
+% To get formatting in the index one must add it in the macro arguments. The simplified interface aids this process. Continental users also may lose some capitalization features; see Section~\ref{sec:standards}.\bigskip
%
% \noindent{\large\bfseries Formatting Attributes}\\[2ex]
% \begin{tabular}{p{0.22\textwidth}p{0.6\textwidth}}
-% \quad\texttt{alwaysformat} & If formatting is enabled by the |mainmatter| option or by \cmd{\NamesActive}, this option causes all names to have typographic formatting applied to them, whether first or subsequent uses.\\[1ex]
-% \quad\bfseries\texttt{smallcaps} & \bfseries Set the first use of a name in small caps.\\[1ex]
-% \quad\texttt{italic} & Italicize the first occurrence of a name.\\[1ex]
-% \quad\texttt{boldface} & Set the first use of a name in boldface.\\[1ex]
-% \quad\texttt{noformat} & Do not define a default format. Can be used with custom formatting.\\[2ex]
+% \quad\texttt{smallcaps} & Set the first use of an entire name in small caps.\\[1ex]
+% \quad\texttt{italic} & Set the first use of an entire name in italic.\\[1ex]
+% \quad\texttt{boldface} & Set the first use of an entire name in boldface.\\[1ex]
+% \quad\bfseries\texttt{noformat} & \bfseries Do not define a default format.\\[2ex]
% \end{tabular}\\
+% The options that assign a font change are intended for ``quick'' solutions based on English typography. They change only \cmd{\NamesFormat}, the macro that formats first instances of names in the main matter.\\
+%
+% \noindent\begin{tabular}{p{0.97\textwidth}}\toprule\hfil\bfseries Versions 2.5 and onward assign no default formatting to names.\hfil\\\bottomrule\end{tabular}\bigskip
+%
+% Many users will not be affected by these changes because many prefer the |noformat| option. If you did use the default option in the past, you can recover that behavior with the |smallcaps| option.
% \clearpage
%
% \subsection{Quick Start Guide}
@@ -885,7 +934,7 @@ Running "make install" installs the files in the local TeX tree.
% \label{sec:simplestart}%
%
% \DescribeEnv{nameauth}
-% The |nameauth| environment allows one to save typing and aid consistency by using shorthands. It replaces the use of \cmd{\Name,} \cmd{\Name*,} and \cmd{\FName,} but not the other naming macros. Thus one must remain aware of the main interface.
+% The |nameauth| environment can replace \cmd{\Name,} \cmd{\Name*,} and \cmd{\FName} with shorthands. This aids consistency and brevity. Still, one must use all the other macros of the main interface. Both interfaces interoperate with each other.
%
% The simplified interface produces control sequences that are fully compatible with the main interface. Although not required, |nameauth| is best used in the document preamble to avoid undefined control sequences.\footnote{The |nameauth| environment uses \cmd{\ignorespaces} to mitigate the need for trailing \texttt{\%.}} The italicized comments at right are not part of the example proper, but are there for explanation. Macro fields have uniform widths only to help compare argument types.
%
@@ -1066,7 +1115,9 @@ Running "make install" installs the files in the local TeX tree.
%\end{quote}
%
% \ForgetName[Albert]{Einstein}\ForgetName{Confucius}\ForgetName[M.T.]{Cicero}\ForgetName{Charles, the Bald}%
-% Here we have the equivalent with the simplified interface. |\Einstein,| |\LEinstein,| and |\Einstein| produce \Einstein, \LEinstein, and \Einstein. |\CBald| and |\CBald| give \CBald\ and \CBald. |\Confucius| yields \Confucius\ and \Confucius. |\Cicero| prints \Cicero\ and \Cicero, while |\LCicero[Marcus Tullius]| gives \LCicero[Marcus Tullius]. The next page explains why this form may be preferable in some cases for name variants when using the simplified interface.
+% Here we have the equivalent with the simplified interface. |\Einstein,| |\LEinstein,| and |\Einstein| produce \Einstein, \LEinstein, and \Einstein. |\CBald| and |\CBald| give \CBald\ and \CBald. |\Confucius| yields \Confucius.
+%
+% |\Cicero| prints \Cicero\ and \Cicero, while |\LCicero[Marcus Tullius]| gives \LCicero[Marcus Tullius]. The next page explains why this form may be preferable in some cases for name variants when using the simplified interface.
% \clearpage
%
% \subsubsection{Forenames: \texttt{\textbackslash FName}}
@@ -1079,12 +1130,7 @@ Running "make install" installs the files in the local TeX tree.
% \begin{quote}
% \cmd{\FName}\oarg{FNN}\marg{SNN}\oarg{Alternate names}
% \end{quote}
-% This macro always prints full name when a name is first used. That prevents a first-name reference before a person has been introduced. To force a short name as a first reference, you could use a macro to incorporate:
-% \begin{quote}
-% \cmd{\SubvertName}\oarg{FNN}\marg{SNN}|%|\\
-% \cmd{\makeatletter}\cmd{\@nameauth@FirstFormattrue}\cmd{\makeatother}|%|\\
-% \cmd{\FName}\oarg{FNN}\marg{SNN}
-% \end{quote}
+% This macro always prints a full name when a name is first used. That prevents a first-name reference before a person has been introduced.\footnote{One can force a short name by using \cmd{\SubvertName}\oarg{FNN}\marg{SNN} \cmd{\makeatletter} \cmd{\@nameauth@FirstFormattrue} \cmd{\makeatother} \cmd{\FName}\oarg{FNN}\marg{SNN}. Nevertheless, this seems to be overkill. It would be easier to type the name manually, then use \cmd{\IndexName.}}
% By design, \cmd{\FName} \emph{never} prints Eastern personal names, so that ancient names also work (cf. Section~\ref{sec:PatRef}). Examples of general use include: \ForgetName[Albert]{Einstein}\ForgetName{Confucius}\ForgetName[M.T.]{Cicero}\ForgetName{Charles, the Bald}%
%
% \begin{quote}\small\setstretch{1.2}
@@ -1102,7 +1148,9 @@ Running "make install" installs the files in the local TeX tree.
%
% With the simplified interface example from the previous page, |\SEinstein,| |\SConfucius,| |\SCicero,| and |\SCBald| give us \SEinstein, \SConfucius, \SCicero, and \SCBald. |\SCicero[Marcus Tullius]| gives \SCicero[Marcus Tullius]. However, with the macro |\FName[Chesley B.]{Sullenberger, III}[Sully]| we have ``\FName[Chesley B.]{Sullenberger, III}[Sully]'' and ``\FName[Chesley B.]{Sullenberger, III}[Sully].'' Please use caution!
%
-%\ForgetName[Clive Staples]{Lewis} This may not always be a ``bug.'' Remembering Section~\ref{sec:simplestart}, you can use \Lewis\ or ``\SJack.'' |\FName[Clive Staples]{Lewis}[C.S.]| or \cmd{\Lewis} gives the first form, while |\FName[Clive Staples]{Lewis}[Jack]| or \cmd{\Jack} gives the second. |\SJayR| gave \ForgetName[John David]{Rockefeller, IV}\SJayR\ and \SJayR, but the index entry remains ``Rockefeller, John David, IV.'' Using ``default nicknames'' in the simplified interface has some caveats:
+%\ForgetName[Clive Staples]{Lewis} This may not always be a ``bug.'' Remembering Section~\ref{sec:simplestart}, you can use \Lewis\ or ``\SJack.'' |\FName[Clive Staples]{Lewis}[C.S.]| or \cmd{\Lewis} gives the first form, while |\FName[Clive Staples]{Lewis}[Jack]| or \cmd{\Jack} gives the second. |\SJayR| gave \ForgetName[John David]{Rockefeller, IV}\SJayR\ and \SJayR, but the index entry remains ``Rockefeller, John David, IV.''
+%
+% Using ``default nicknames'' in the simplified interface has some caveats:
%
% \begin{nameauth}%
% \< Ches & Chesley B. & Sullenberger, III & >%
@@ -1173,10 +1221,10 @@ Running "make install" installs the files in the local TeX tree.
%
% Please\marginpar{\small\raggedleft\cmd{\global}} note that \cmd{\ReverseActive} and \cmd{\ReverseInactive} can be used explicitly as a pair. They also can be used singly within an explicit scope, where the effects cease after leaving that scope. Use \cmd{\global} to force a global effect.
%
-% This list of Japanese music artists shows \cmd{\RevName} in action. Names in Western order, then non-native Eastern order are marked with a dagger ({\dag}). All other names are in native Eastern, then Western order. Forms using the old syntax are in parentheses. Name formatting is turned off in order to focus on reversing:
+% This list of Japanese music artists shows \cmd{\RevName} in action. Names in Western order, then non-native Eastern order are marked with a dagger ({\dag}). All other names are in native Eastern, then Western order. Forms using the old syntax are in parentheses:
%
%
-% \begin{quote}\small\NamesInactive\setstretch{1.2}
+% \begin{quote}\small\setstretch{1.2}
% \begin{tabular}{lll}\toprule
% & \emph{unchanged} & |\RevName|\\\midrule
% \dag|\Name*[Aiko]{Nakano}| & \dag\Name*[Aiko]{Nakano} & \dag\RevName\Name*[Aiko]{Nakano}\\
@@ -1189,13 +1237,13 @@ Running "make install" installs the files in the local TeX tree.
% \DescribeMacro{\AllCapsActive}
% \DescribeMacro{\AllCapsInactive}
% \DescribeMacro{\CapName}
-% Use \cmd{\AllCapsActive}, \cmd{\AllCapsInactive}, and \cmd{\CapName} for fully-capitalized family names in the body text. These macros are analogous to the reversing macros above and may be used alone or with those and other state-toggling macros, \emph{e.g.} \cmd{\CapName}\cmd{\RevName}\cmd{\Name}\dots.
+% Use \cmd{\AllCapsActive}, \cmd{\AllCapsInactive}, and \cmd{\CapName} for fully-capitalized family names in the body text. These macros are analogous to the reversing macros above and may be used alone or with those and other state-toggling macros, \emph{e.g.} \cmd{\CapName}\cmd{\RevName}\cmd{\Name}\marg{SNN, Affix}.
%
% Both\marginpar{\small\raggedleft\cmd{\global}} \cmd{\AllCapsActive} and \cmd{\AllCapsInactive} have the same local restrictions as the other state-changing macros. Use \cmd{\global} to force a global effect.
%
-% In the example below, names in Western order, then non-native Eastern order are marked with a dagger ({\dag}). All other names are in native Eastern, then Western order. Forms using the old syntax are in parentheses. Name formatting is turned off in order to focus on capitalizing and reversing:
+% In the example below, names in Western order, then non-native Eastern order are marked with a dagger ({\dag}). All other names are in native Eastern, then Western order. Forms using the old syntax are in parentheses:
%
-% \begin{quote}\small\NamesInactive\setstretch{1.2}
+% \begin{quote}\small\setstretch{1.2}
% \begin{tabular}{l@{ }l@{ }l}\toprule
% & \emph{unchanged} & |\CapName\RevName|\\\midrule
% \dag|\Name*[Yoko]{Kanno}| & \dag\CapName\Name*[Yoko]{Kanno} & \dag\CapName\RevName\Name*[Yoko]{Kanno}\\
@@ -1205,7 +1253,7 @@ Running "make install" installs the files in the local TeX tree.
% \end{tabular}
% \end{quote}\smallskip
%
-% Notice how capitalization is independent of formatting. The reversing and capitalization macros also work with \cmd{\AKA}. They affect only the text, not the index. For caps in the text and index see Section~\ref{sec:formatting}.
+% Capitalization and reversing precede post-processing. The reversing and capitalization macros also work with \cmd{\AKA}. They affect only the text, not the index. For caps in the text and index see Section~\ref{sec:formatting}.
%
% \subsection{Other Naming Topics}
% {\hfill\large\bfseries\emph{Language-Related Issues}\hfill}\vspace{-2ex}
@@ -1271,12 +1319,12 @@ Running "make install" installs the files in the local TeX tree.
% \begin{quote}
% \def\sep{\vrule width0.5pt\kern-0.5pt}%
% \begin{tabular}{ll}\hline
-% & \hphantom{\textsc{E.}}\sep\,\sep\hphantom{\textsc{B.}}\sep\hphantom{\ }\sep\hphantom{\textsc{White}\ and\ }\hphantom{E.}\sep\,\sep\hphantom{B.}\sep\hphantom{\ }\sep\hphantom{White}\\
-% \cmd{\White} and \cmd{\LWhite} & \White\ and \LWhite\\
-% & \hphantom{\textsc{E.}}\sep\,\sep\hphantom{\textsc{B.}}\sep\hphantom{\ }\sep\hphantom{\textsc{White}\ and\ }\hphantom{E.}\sep\,\sep\hphantom{B.}\sep\hphantom{\ }\sep\hphantom{White}\\\hline
-% & \hphantom{\textsc{E.}}\sep\ \sep\hphantom{\textsc{B.}}\sep\ \sep\hphantom{\textsc{White} and\ }\hphantom{E.}\sep\ \sep\hphantom{B.}\sep\ \sep\hphantom{White}\\
-% Normal text:\hfill & \textsc{E. B. White} and E. B. White.\\
-% & \hphantom{\textsc{E.}}\sep\ \sep\hphantom{\textsc{B.}}\sep\ \sep\hphantom{\textsc{White} and\ }\hphantom{E.}\sep\ \sep\hphantom{B.}\sep\ \sep\hphantom{White}\\\hline
+% & \hphantom{E.}\sep\,\sep\hphantom{B.}\sep\hphantom{\ }\sep\hphantom{White}\\
+% \cmd{\White} and \cmd{\LWhite} & \White\\
+% & \hphantom{E.}\sep\,\sep\hphantom{B.}\sep\hphantom{\ }\sep\hphantom{White}\\\hline
+% & \hphantom{E.}\sep\ \sep\hphantom{B.}\sep\ \sep\hphantom{White}\\
+% Normal text:\hfill & {E. B. White}\\
+% & \hphantom{E.}\sep\ \sep\hphantom{B.}\sep\ \sep\hphantom{White}\\\hline
% \end{tabular}
% \end{quote}
%
@@ -1305,9 +1353,8 @@ Running "make install" installs the files in the local TeX tree.
%\DescribeMacro{\RevComma}
% The reversing macros \cmd{\ReverseCommaActive}, \cmd{\ReverseCommaInactive}, and \cmd{\RevComma}\ allow the easy generation of name lists ordered as \meta{SNN}, \meta{FNN} or \meta{SNN}, \meta{Alt. names}. The first two are broad toggles, while the third works on a per-name basis.
% Both\marginpar{\small\raggedleft\cmd{\global}} \cmd{\ReverseCommaActive} and \cmd{\ReverseCommaInactive} have the same local restrictions as the other state-changing macros unless you use \cmd{\global.}
-% Eastern, medieval, and royal names do not work with these macros. Name formatting has been turned off to focus on reversing and commas:
+% Eastern, medieval, and royal names do not work with these macros:
%
-% \NamesInactive
% \begin{quote}\small\setstretch{1.2}
% \begin{tabular}{lll}\toprule
% \Name*[J.S.]{Mill}[John Stuart] & \RevComma\Name*[J.S.]{Mill}[John Stuart] & OK\\
@@ -1317,12 +1364,11 @@ Running "make install" installs the files in the local TeX tree.
% \Name*{Anaximander} & \RevComma\Name*{Anaximander} & OK\\\bottomrule
% \end{tabular}
% \end{quote}
-% \NamesActive
%
% {\hfill\large\bfseries\emph{Technical-Related Issues}\hfill}\vspace{-2ex}
% \subsubsection{Fault Tolerance}
%
-% Especially since version 2.0, the \textsf{nameauth} package minimizes possible side effects of malformed input and macros that expand to being empty in required values. To reduce errors, \cmd{\Name}, \cmd{\FName}, \cmd{\AKA}, and \cmd{\IndexName} ignore leading and trailing spaces\,---\,but not medial spaces\,---\,making the following equivalent:
+% The \textsf{nameauth} package protects against some typing errors and malformed input. Several macros ignore leading and trailing spaces, but not medial spaces as illustrated by the variations below that are automatically corrected:
%
% \begin{quote}\small\ForgetName[Martin Luther]{King, Jr.}\setstretch{1.2}
% \begin{tabular}{ll}\toprule
@@ -1338,7 +1384,7 @@ Running "make install" installs the files in the local TeX tree.
%
% \subsubsection{Detecting Punctuation}
%
-% In Western names, affixes like ``Jr.'' (junior), ``Sr.'' (senior), ``d.\,J.'' (\textit{der J\"ungere}), and ``d.\,\"A.'' (\textit{der \"Altere}) can colide with the full stop in a sentance. \cmd{\Name}, \cmd{\FName}, and \cmd{\AKA} check for a trailing period in the name that they print in the text. If they find it, they check if the next token is a full stop and gobble it if so:
+% In Western names, affixes like ``Jr.'' (junior), ``Sr.'' (senior), ``d.\,J.'' (\textit{der J\"ungere}), and ``d.\,\"A.'' (\textit{der \"Altere}) can collide with the full stop in a sentence. \cmd{\Name}, \cmd{\FName}, and \cmd{\AKA} detect this in a name and gobble the subsequent full stop as needed:
%
% \begin{quote}\footnotesize\ForgetName[Martin Luther]{King, Jr.}\setstretch{1.2}
% \begin{tabular}{r@{\hbox to 1em{\hfil}}c@{\hbox to 1em{\hfil}}l}\toprule
@@ -1347,11 +1393,10 @@ Running "make install" installs the files in the local TeX tree.
% |\Name[Martin Luther]{King, Jr.}.| & $2\rightarrow1$ & \Name[Martin Luther]{King, Jr.}.\\
% |\Name[Martin Luther]{King, Jr.}|\texttt{\textvisiblespace} & $1\rightarrow0$ & \Name[Martin Luther]{King, Jr.}\\
% |\Name*[Martin Luther]{King, Jr.}.| & $2\rightarrow1$ & \Name*[Martin Luther]{King, Jr.}.\\
-% |\Name*[Martin Luther]{King, Jr.}|\texttt{\textvisiblespace} & $1\rightarrow1$ & \Name*[Martin Luther]{King, Jr.}\\
-% |{\Name*[Martin Luther]{King, Jr.}}.| & $2\rightarrow2$ & {\Name*[Martin Luther]{King, Jr.}}.\footnotemark\\\bottomrule
+% |\Name*[Martin Luther]{King, Jr.}|\texttt{\textvisiblespace} & $1\rightarrow1$ & \Name*[Martin Luther]{King, Jr.}\\\bottomrule
% \end{tabular}
% \end{quote}
-% \footnotetext{Grouping tokens and other items can frustrate the full stop detection mechanism.}
+% Grouping tokens can frustrate this: |{\Name*[Martin Luther]{King, Jr.}}.| produces ``{\Name*[Martin Luther]{King, Jr.}}.'' (two periods). Enclosing |{Jr.}| within braces or a macro will do the same. If you must format the affix, leave the period outside: |\Name[Martin Luther]{\textsc{King}, \textsc{Jr}.}| Cf. Section~\ref{sec:formatting}.
%
% \subsubsection{Accented Names}
% \label{sec:accents}
@@ -1374,24 +1419,98 @@ Running "make install" installs the files in the local TeX tree.
% |\Name{Æthelred, II}|\hfill \Name{Æthelred, II} instead of \Name{Æthelred, II}
% \end{quote}
%
-% See Section~\ref{sec:Unicode} on how to add additional Unicode glyphs to the default set under NFSS, \textsf{inputenc}, and \textsf{fontenc}. One may use expandable control sequences in names (thanks \Name*[Robert]{Schlicht}). Also, you can define letters with \cmd{\edef} and \cmd{\noexpand} to use in names, as some do to ``protect'' accented letters in names. As of version 2.0 of \textsf{nameauth} helpful concerns expressed by \Name[Patrick]{Cousot} have been addressed.
+% See Section~\ref{sec:Unicode} on how to add additional Unicode glyphs to the default set under NFSS, \textsf{inputenc}, and \textsf{fontenc}. One may use expandable control sequences in names (thanks \Name*[Robert]{Schlicht}). Also, you can use \cmd{\edef} and \cmd{\noexpand} in names (Section~\ref{sec:Hooksc}). Since \textsf{nameauth} version 2.0, helpful concerns of \Name[Patrick]{Cousot} have been addressed.
%
-% \subsubsection{Custom Formatting}
-% \label{sec:formatting}
+% \subsubsection{Format: Hooks}
+% \label{sec:CustomHooks}
%
% There are two kinds of formatting at work:
% \begin{enumerate}\small
% \item \textbf{Syntactic Formatting:} This includes reversing names, capitalizing the first letter in the \meta{SNN} field in the body text, and capitalizing the root when \meta{SNN} is a \meta{root, suffix} pair.
-% \item \textbf{Typographic Formatting:} This happens after a name has been parsed and reordered as needed into the final form it will take in the text.
+% \item \textbf{Name Post-Processing:} This happens in the hook macros after a name has been parsed into the final form it will take in the text.
% \end{enumerate}
-% Typographic formatting\marginpar{\small\raggedleft Continental\\ small caps} does not affect the index. However, literal control sequences in the macro arguments of \cmd{\Name} and friends do make it into the index. Use this method with the \texttt{noformat} option to suppress default formatting, which we simulate here. One also must use \cmd{\PretagName} to get proper index sorting:
-% \NamesInactive
+%
+% \DescribeMacro{\NamesFormat}
+% \DescribeMacro{\FrontNamesFormat}
+% \DescribeMacro{\MainNameHook}
+% \DescribeMacro{\FrontNameHook}
+% Starting with version 2.5, the ``main-matter'' and ``front-matter'' systems are fully qualified and independent systems of formatting and first/subsequent name use. The main-matter system uses \cmd{\NamesFormat} to post-process first occurrences of names and \cmd{\MainNameHook} to post-process subsequent uses. The front-matter system uses \cmd{\FrontNamesFormat} to post-process first occurrences of names and \cmd{\FrontNameHook} to post-process subsequent uses. The \texttt{alwaysformat} option causes every name to be formatted as a ``first-use.''
+%
+% Section~\ref{sec:FrontFormat} offers more about how to switch the systems and what that implies. For now, we focus on custom formatting at work:
+% \begin{quote}\small
+% |\renewcommand*{\NamesFormat}{\scshape}|\\
+% |\renewcommand*{\FrontNamesFormat}{\bfseries}|
+% \end{quote}
+%
+% We leave \cmd{\MainNameHook} and \cmd{\FrontNameHook} unchanged so that the resulting names are not formatted. Here we have text in the front matter. It has the \cmd{\bfseries} formatting.
+% \ForgetName[Albert]{Einstein}\ForgetName{Confucius}\ForgetName[M.T.]{Cicero}\ForgetName{Charles, the Bald}
+% \begin{quote}\small\setstretch{1.2}
+% \NamesInactive\renewcommand*{\NamesFormat}{\scshape}\renewcommand*{\FrontNamesFormat}{\bfseries}
+% \begin{tabular}{ll}\toprule
+% |\Name[Albert]{Einstein}| & \Name[Albert]{Einstein}\\
+% |\Name[Albert]{Einstein}| & \Name[Albert]{Einstein}\\\midrule
+% |\Name{Confucius}| & \Name{Confucius}\\
+% |\Name{Confucius}| & \Name{Confucius}\\\midrule
+% |\Name[M.T.]{Cicero}[Marcus Tullius]| & \Name[M.T.]{Cicero}[Marcus Tullius]\\
+% |\Name[M.T.]{Cicero}[Marcus Tullius]| & \Name[M.T.]{Cicero}[Marcus Tullius]\\\midrule
+% |\Name{Charles, the Bald}| & \Name{Charles, the Bald}\\
+% |\Name{Charles, the Bald}| & \Name{Charles, the Bald}\\\bottomrule
+% \end{tabular}
+% \end{quote}
+%
+% Next we have text in the main matter. It has the \cmd{\scshape} formatting.
+% \begin{quote}\small\setstretch{1.2}
+% \renewcommand*{\NamesFormat}{\scshape}\renewcommand*{\FrontNamesFormat}{\bfseries}
+% \begin{tabular}{ll}\toprule
+% |\Name[Albert]{Einstein}| & \Name[Albert]{Einstein}\\
+% |\Name[Albert]{Einstein}| & \Name[Albert]{Einstein}\\\midrule
+% |\Name{Confucius}| & \Name{Confucius}\\
+% |\Name{Confucius}| & \Name{Confucius}\\\midrule
+% |\Name[M.T.]{Cicero}[Marcus Tullius]| & \Name[M.T.]{Cicero}[Marcus Tullius]\\
+% |\Name[M.T.]{Cicero}[Marcus Tullius]| & \Name[M.T.]{Cicero}[Marcus Tullius]\\\midrule
+% |\Name{Charles, the Bald}| & \Name{Charles, the Bald}\\
+% |\Name{Charles, the Bald}| & \Name{Charles, the Bald}\\\bottomrule
+% \end{tabular}
+% \end{quote}
+%
+% Finally we simulate the \texttt{alwaysformat} option for text in both the main matter and the front matter:
+% \ForgetName[Albert]{Einstein}\ForgetName{Confucius}\ForgetName[M.T.]{Cicero}\ForgetName{Charles, the Bald}
+% \begin{quote}\small\setstretch{1.2}
+% \makeatletter\@nameauth@AlwaysFormattrue\makeatother
+% \renewcommand*{\NamesFormat}{\scshape}\renewcommand*{\FrontNamesFormat}{\bfseries}
+% \begin{tabular}{ll}\toprule
+% \textit{Front Matter}\global\NamesInactive\\\midrule
+% |\Name[Albert]{Einstein}| & \Name[Albert]{Einstein}\\
+% |\Name[Albert]{Einstein}| & \Name[Albert]{Einstein}\\\midrule
+% |\Name{Confucius}| & \Name{Confucius}\\
+% |\Name{Confucius}| & \Name{Confucius}\\\midrule
+% \textit{Main Matter}\global\NamesActive\\\midrule
+% |\Name[M.T.]{Cicero}[Marcus Tullius]| & \Name[M.T.]{Cicero}[Marcus Tullius]\\
+% |\Name[M.T.]{Cicero}[Marcus Tullius]| & \Name[M.T.]{Cicero}[Marcus Tullius]\\\midrule
+% |\Name{Charles, the Bald}| & \Name{Charles, the Bald}\\
+% |\Name{Charles, the Bald}| & \Name{Charles, the Bald}\\\bottomrule
+% \end{tabular}
+% \makeatletter\@nameauth@AlwaysFormatfalse\makeatother
+% \end{quote}
+%
+% The process of modularizing this post-processing began in version 2.4. Sections~\ref{sec:Hooksb}ff. discuss more on how one can redefine the formatting hooks.
+% \clearpage
+%
+% \subsubsection{Format: Continental}
+% \label{sec:formatting}
+%
+% Name post-processing\marginpar{\small\raggedleft Continental\\ small caps} does not affect the index. Control sequences in the name arguments themselves do affect the index. Section~\ref{sec:IndexSort} describes how to use \cmd{\PretagName} to get proper index sorting with names containing control sequences and extended Unicode characters.
+%
+% In this example, you get something that corresponds with the Continental system. The surname is formatted in both the body text and the index. It is always formatted, everywhere:
% \begin{quote}
% \indent|\PretagName[Greta]{\textsc{Garbo}}{Garbo, Greta}|\\
% \indent|\Name[Greta]{\textsc{Garbo}}|
% \end{quote}
-% You get \Name[Greta]{\textsc{Garbo}}, then \Name[Greta]{\textsc{Garbo}}, even in the front matter because this formatting is persistent. Use |``Garbo''\IndexName\Name[Greta]{\textsc{Garbo}}| for a ``Garbo'' reference. |\Name[\normalfont{Greta}]{\textsc{Garbo}}| may look like the name above, but it is a different name with a different index entry. Keep the formatting simple to gain both flexibility and consistency.
-% \clearpage
+% You get \Name[Greta]{\textsc{Garbo}}, then \Name[Greta]{\textsc{Garbo}}\,---\,even in the front matter. Section~\ref{sec:Hooksc} shows a more advanced example that will suppress the small caps except for first uses, but will retain the small caps in the index.
+%
+% Of course, one could always create a manual reference if desired. For example, one can type |``Garbo''\IndexName\Name[Greta]{\textsc{Garbo}}| for a ``Garbo'' reference.
+%
+% Some interesting things can happen when you put control sequences in the naming macro arguments. |\Name[\normalfont{Greta}]{\textsc{Garbo}}| will produce a name in the text and in the index that looks exactly like name above. Regardless of its looks, however, it is a a different name with different first/subsequent uses and a different index entry.
%
% A comma delimiter will split the macro argument, potentially causing unbalanced braces. Avoid this by formatting the name and suffix separately:
% \begin{quote}\small
@@ -1404,7 +1523,12 @@ Running "make install" installs the files in the local TeX tree.
% |\end{nameauth}|
% \end{quote}
%
-% \cmd{\Fukuyama} produces \Fukuyama\ and \Fukuyama. Of course, you could type all-capital surnames without control sequences. Likewise, \cmd{\Howell} generates \Howell\ and \Howell. We now revert to normal formatting.\NamesActive\medskip
+% \cmd{\Fukuyama} produces \Fukuyama\ and \Fukuyama. Of course, you could type all-capital surnames without control sequences. Likewise, \cmd{\Howell} generates \Howell\ and \Howell.\medskip
+%
+% \subsubsection{Format: Engine}
+% \label{sec:NewEngine}
+%
+% Assuming that redefining hooks and adding control sequences is insufficient to your task, you could modify the core naming macros and hook those modifications back into the \textsf{nameauth} package without needing to continuously track and patch the style file itself.
%
% \DescribeMacro{\NameauthName}
% \DescribeMacro{\NameauthLName}
@@ -1444,47 +1568,31 @@ Running "make install" installs the files in the local TeX tree.
% \end{quote}
% Like\marginpar{\small\raggedleft\cmd{\global}} \cmd{\NamesFormat}, the other hook macros, and many of the state-changing and triggering macros in this package, these naming macros can be redefined or used locally within a scope without making global changes to the document unless you specifically use \cmd{\global}.
%
-% Here we show that the macros \cmd{\NameauthName,} \cmd{\NameauthLName,} and \cmd{\NameauthFName} have reverted back to their original forms. Now \cmd{\Silly} and |\Name[No Particular]{Name}| produce \IndexInactive\Silly\ and \Name[No Particular]{Name}\IndexActive.\medskip
-%
-% \DescribeMacro{\NamesFormat}
-% When formatting is active, \cmd{\NamesFormat} is called at the first instance of a name, and at every instance of a name when the \texttt{alwaysformat} option is used. Originally it was the only formatting ``hook,'' but in version 2.4 and beyond it joins two similar ``hooks'' that are described in Section~\ref{sec:moreC}. One can redefine \cmd{\NamesFormat} to create custom effects like suppressing formatting in footnotes:
+% Here we show that the macros \cmd{\NameauthName,} \cmd{\NameauthLName,} and \cmd{\NameauthFName} have reverted back to their original forms. Now \cmd{\Silly} and |\Name[No Particular]{Name}| produce \IndexInactive\Silly\ and \Name[No Particular]{Name}\IndexActive.
%
-% \begin{quote}\small
-% |\makeatletter|\\
-% |\let\@oldfntext\@makefntext|\\
-% |\long\def\@makefntext#1{%|\\
-% | \renewcommand*\NamesFormat{}\@oldfntext{#1}}|\\
-% |\let\@makefntext\@oldfntext% just in case|\\
-% |\makeatother|
-% \end{quote}
-% \makeatletter\let\@oldfntext\@makefntext\long\def\@makefntext#1{\renewcommand*\NamesFormat{}\@oldfntext{#1}}\makeatother
-% Your footnote would produce an unformatted name.\footnote{This demonstrates no main-matter formatting: \Name[John Maynard]{Keynes}.}
-% We change footnotes back to normal with \makeatletter\let\@makefntext\@oldfntext\makeatother \cmd{\makeatletter}\cmd{\let}\cmd{\@makefntext}\cmd{\@oldfntext}\cmd{\makeatother.} Yet this example also can affect names in the body text, which may not be desirable. Section~\ref{sec:DisableFormat} has an arguably better approach.
+% \subsubsection{Format: Systems}
+% \label{sec:FrontFormat}
%
-% Relying only on scoping to insulate changes to \cmd{\NamesFormat} might create undesired side effects, depending on the sort of modification. We put longer examples of formatting and conditionals in Section~\ref{sec:moreC}.
-%
-% \subsubsection{Disable Formatting}
-% \label{sec:DisableFormat}
-%
% \DescribeMacro{\NamesActive}
% \DescribeMacro{\NamesInactive}
-% Using the \texttt{frontmatter} option deactivates formatting until \cmd{\NamesActive} occurs. Another macro, \cmd{\NamesInactive}, will deactivate formatting again. These two macros toggle two independent systems of formatting and first use.
+% Using the \texttt{frontmatter} option or \cmd{\NamesInactive} causes the naming macros to use the front matter formatting hook until \cmd{\NamesActive} switches the macros to the independent main matter formatting hooks. Additionally, two independent systems of names are created: front-matter names and main-matter names.
%
% Please\marginpar{\small\raggedleft\cmd{\global}} note that these two macros can be used explicitly as a pair. They also can be used singly within an explicit scope, where the effects cease after leaving that scope. Use \cmd{\global} to force a global effect.
%
-% Here we switch to the ``front matter'' mode by placing \cmd{\NamesInactive} at the start of the \texttt{quote} environment:
-% \begin{quote}\small\NamesInactive
-% \begin{tabular}{ll}
+% Similar to the formatting example above, we redefine the formatting hooks to illustrate that indeed, there are two formatting systems at work. Here we switch to the ``front matter'' mode:
+% \begin{quote}\small\cmd{\NamesInactive}\NamesInactive\\[0.4ex]
+% \NamesInactive\renewcommand*{\NamesFormat}{\scshape}\renewcommand*{\FrontNamesFormat}{\bfseries}
+% \begin{tabular}{@{}ll}
% |\Name[Rudolph]{Carnap}| & \Name[Rudolph]{Carnap}\\
% |\Name[Rudolph]{Carnap}| & \Name[Rudolph]{Carnap}\\
% |\Name[Nicolas]{Malebranche}| & \Name[Nicolas]{Malebranche}\\
% |\Name[Nicolas]{Malebranche}| & \Name[Nicolas]{Malebranche}\\
% \end{tabular}
% \end{quote}
-%
-% Then we switch back to ``main matter'' by leaving the scope above instead of calling \cmd{\NamesActive} explicitly. Avoid unwanted effects by using these toggling macros in pairs (perhaps with \cmd{\global}).
-% \begin{quote}\small
-% \begin{tabular}{ll}
+% Then we switch back to ``main matter'' mode:
+% \begin{quote}\small\cmd{\NamesActive}\NamesActive\\[0.4ex]
+% \renewcommand*{\NamesFormat}{\scshape}\renewcommand*{\FrontNamesFormat}{\bfseries}
+% \begin{tabular}{@{}ll}
% |\Name[Rudolph]{Carnap}| & \Name[Rudolph]{Carnap}\\
% |\Name[Rudolph]{Carnap}| & \Name[Rudolph]{Carnap}\\
% |\Name[Nicolas]{Malebranche}| & \Name[Nicolas]{Malebranche}\\
@@ -1492,7 +1600,35 @@ Running "make install" installs the files in the local TeX tree.
% \end{tabular}
% \end{quote}
%
-% Notice that we have two independent cases of ``first use'' above. Consider the two ``species'' of names to be ``non-formatted'' and ``formatted,'' intended for front matter and main matter. Yet one could use this in footnotes to implement a different system of names (see also Section~\ref{sec:Tweaks}):
+% We have two independent cases of ``first use'' above. Thus, we have two ``species'' of names: ``front-matter'' and ``main-matter.'' This is useful if you want to format names one way in the regular body text but another way somewhere else. You see above, however, that using these systems in the same document section can lead to a clash of names.
+%
+% How about we apply some of these formatting ideas to footnotes? Certainly we can redefine \cmd{\NamesFormat} to create custom effects like changing typographic formatting in footnotes:
+% \begin{quote}\small
+% |\makeatletter|\\
+% |\let\@oldfntext\@makefntext|\\
+% |\long\def\@makefntext#1{%|\\
+% | \renewcommand*\NamesFormat{\scshape}\@oldfntext{#1}}|\\
+% |\let\@makefntext\@oldfntext% just in case|\\
+% |\makeatother|
+% \end{quote}
+% \makeatletter\ignorespaces%
+% \let\@oldfntext\@makefntext%
+% \long\def\@makefntext#1{\renewcommand*\NamesFormat{\scshape}\@oldfntext{#1}}%
+% \makeatother%
+% Your footnote would produce names with different formatting than the body text.\footnote{This demonstrates a format change: \Name[John Maynard]{Keynes}.}
+% We change footnotes back to normal with:
+% \makeatletter\ignorespaces%
+% \let\@makefntext\@oldfntext%
+% \makeatother%
+% \begin{quote}\small
+% |\makeatletter%|\\
+% |\let\@makefntext\@oldfntext%|\\
+% |\makeatother|
+% \end{quote}
+%
+% This example has something of a flaw in it. If you are in the main matter of the document, this solution can affect names in the main body text, \emph{e.g.}, ``\Name[John Maynard]{Keynes},'' because the first and subsequent references are global by design. Also, relying only on scoping to insulate any changes to \cmd{\NamesFormat} might create undesired side effects, depending on the sort of modification.
+%
+% By using the front-matter system, we can get around the limitations of the footnotes interfering with the main-matter text:
% \begin{quote}\small
% |\makeatletter|\\
% |\let\@oldfntext\@makefntext|\\
@@ -1500,9 +1636,12 @@ Running "make install" installs the files in the local TeX tree.
% | \NamesInactive\@oldfntext{#1}\NamesActive%|\\
% |}\makeatother|
% \end{quote}
-% \makeatletter\let\@oldfntext\@makefntext\long\def\@makefntext#1{\NamesInactive\@oldfntext{#1}\NamesActive}\makeatother
-% As above, your footnote would produce an unformatted name.\footnote{This demonstrates no front-matter formatting: \Name[John Maynard]{Keynes}.}
-% Here the ``non-formatted'' names would not affect the body text. Again we change footnotes back to normal with \makeatletter\let\@makefntext\@oldfntext\makeatother \cmd{\makeatletter}\cmd{\let}\cmd{\@makefntext}\cmd{\@oldfntext}\cmd{\makeatother.}
+% \makeatletter\ignorespaces%
+% \let\@oldfntext\@makefntext%
+% \long\def\@makefntext#1{\NamesInactive\@oldfntext{#1}\NamesActive}%
+% \makeatother%
+% Your footnote would produce a front-matter name.\footnote{This demonstrates a front-matter name: \Name[John Maynard]{Keynes}.}
+% Notice that the front-matter text has no formatting by default. Not only does front-matter formatting not affect the body text, but also the first/subsequent uses are independent. As above, we can change footnotes back to normal.\makeatletter\let\@makefntext\@oldfntext\makeatother
%
% \subsection{Name Decisions}
% \subsubsection{Testing Decisions}
@@ -1512,6 +1651,18 @@ Running "make install" installs the files in the local TeX tree.
%
% Some examples of conditional text include a ``mini-biography,'' a footnote, or a callout. These macros could be integrated with the ``text tag'' features in Section~\ref{sec:tagtext}. Authors and editors could use these macros with the \textsf{comment}, \textsf{pdfcomment}, and similar packages to make comments based on whether a name has occurred or not. That aids name management and thought development.
%
+% If one passes control sequences to these macros instead of typing the text directly, one can get false results (see \emph{The \TeX book}, 212--15) unless:
+% \begin{itemize}
+% \item The arguments are retrieved from token registers.
+% \item Expansion is regulated via \cmd{\expandafter,} \cmd{\noexpand,} etc.
+% \item Expansion of accented characters in \texttt{pdflatex}/NFSS is regulated.
+% \item Conditional expansion within macro arguments (cf. Section~\ref{sec:Hooksc}) yields consistent results.
+% \end{itemize}
+%
+% The formatting hooks do not employ these testing macros because two are called only for first uses anyway. By default, \cmd{\AKA} calls only the subsequent use hooks unless the \texttt{formatAKA} option is used.
+%
+% Using \cmd{\tracingmacros,} \cmd{\show,} or \cmd{\meaning} can help you ensure that everything is expanding properly to prevent false results.
+%
% \DescribeMacro{\IfMainName}
% If you want to produce output or perform a task based on whether a ``main body'' name exists, use \cmd{\IfMainName}, whose syntax is:
% \begin{quote}
@@ -1519,21 +1670,25 @@ Running "make install" installs the files in the local TeX tree.
% \end{quote}
% This is a long macro via \cmd{\newcommandx}, so you can have paragraph breaks in the \meta{yes} and \meta{no} paths. A ``main body'' name is capable of being formatted by this package, \emph{i.e.}, one created by the naming macros when the \texttt{mainmatter} option is used or after \cmd{\NamesActive}. It is distinguished from those names that occur in the front matter and those that have been used as cross-references.
%
-% For example, we get ``\IfMainName[Bob]{Hope}{I met Bob Hope}{I have not met Bob Hope}'' from the following example because we have yet to invoke |\Name[Bob]{Hope}|:
+% For example, we get ``\IfMainName[Bob]{Hope}{I met Bob}{I have not met Bob}'' from the following example because we have yet to invoke |\Name[Bob]{Hope}|:
% \begin{quote}
-% |\IfMainName[Bob]{Hope}%|\\
-% |{I met Bob Hope}%|\\
-% |{I have not met Bob Hope}|
+% |\IfMainName[Bob]{Hope}{I met Bob}{I have not met Bob}|
% \end{quote}%
%
+% Since we have encountered \Name*[Johann]{Andreä}, we get ``\IfMainName[Johann]{Andreä}{I met Johann}{I have not met Johann}'' with a similar example:
+% \begin{quote}
+% |\IfMainName[Johann]{Andreä}{I met Johann}%|\\| {I have not met Johann}|
+% \end{quote}
+%
% \DescribeMacro{\IfFrontName}
% If you want to produce output or perform a task based on whether a ``front matter'' name exists, use \cmd{\IfFrontName}, whose syntax is:
% \begin{quote}
% \cmd{\IfFrontName}\oarg{FNN}\marg{SNN}\oarg{Alternate names}\marg{yes}\marg{no}
% \end{quote}
% This macro works the same as \cmd{\IfMainName.} A ``front matter'' name is not capable of being formatted by this package, \emph{i.e.}, one created by the naming macros when the \texttt{frontmatter} option is used or after \cmd{\NamesInactive}. It is distinguished from those names that occur in the main matter and those that have been used as cross-references.
+% \clearpage
%
-% \label{page:Carnap}For example, based on Section~\ref{sec:DisableFormat}, we see that ``\ignorespaces
+% \label{page:Carnap}For example, based on Section~\ref{sec:FrontFormat}, we see that ``\ignorespaces
% \IfFrontName[Rudolph]{Carnap}%
% {\IfMainName[Rudolph]{Carnap}%
% {\Name[Rudolph]{Carnap} is both}%
@@ -1605,7 +1760,7 @@ Running "make install" installs the files in the local TeX tree.
% \begin{quote}
% \cmd{\ForgetName}\oarg{FNN}\marg{SNN}\oarg{Alternate names}
% \end{quote}
-% This macro causes \cmd{\Name} and friends globally to ``forget'' prior uses of a name. The next use of that name will print as if it were a ``first use,'' even if it is not. Index entries and cross-references are \emph{never} forgotten.
+% This macro causes \cmd{\Name} and friends globally to ``forget'' prior uses of a name. The next use of that name will print as if it were a ``first use,'' even if it is not. Index entries and cross-references are \emph{never} forgotten.\medskip
%
% \DescribeMacro{\SubvertName}
% This macro is the opposite of the one above. It takes the same arguments. It handles its arguments in the same manner. The syntax is:
@@ -1617,7 +1772,7 @@ Running "make install" installs the files in the local TeX tree.
% The default \marginpar{\small\raggedleft Scope} behavior of these two macros changes whether a name is ``forgotten'' or ``subverted'' simultaneously for front matter and main matter names, Remember the example on page~\pageref{page:Carnap} above that gave us the answer, ``\IfFrontName[Rudolph]{Carnap}{\IfMainName[Rudolph]{Carnap}{\Name[Rudolph]{Carnap} is both}{\Name[Rudolph]{Carnap} is only non-formatted}}{\IfMainName[Rudolph]{Carnap}{\Name[Rudolph]{Carnap} is only formatted}{\Name[Rudolph]{Carnap} is not mentioned}}?'' Now watch closely: After we use \ForgetName[Rudolph]{Carnap}|\ForgetName[Rudolph]{Carnap}| we get the result,
% ``\IfFrontName[Rudolph]{Carnap}{\IfMainName[Rudolph]{Carnap}{\Name[Rudolph]{Carnap} is both}{\Name[Rudolph]{Carnap} is only non-formatted}}{\IfMainName[Rudolph]{Carnap}{\Name[Rudolph]{Carnap} is only formatted}{\Name[Rudolph]{Carnap} is not mentioned}}.'' Both the main matter name and the front matter name were forgotten!
%
-% This default behavior helps synchronize formatted and unformatted types of names. For example, if you wanted to use unformatted names in the footnotes and formatted names in the text (Section~\ref{sec:DisableFormat}), you could use, \emph{e.g.} \cmd{\SubvertName} right after the first use of a name in the body text, ensuring that all references in the text and notes would be short unless otherwise modified.\footnote{This manual takes advantage of that behavior at times in order to synchronize first and subsequent uses of names between formatted and unformatted sections of the body text.}
+% This default behavior helps synchronize formatted and unformatted types of names. For example, if you wanted to use unformatted names in the footnotes and formatted names in the text (Section~\ref{sec:FrontFormat}), you could use, \emph{e.g.} \cmd{\SubvertName} right after the first use of a name in the body text, ensuring that all references in the text and notes would be short unless otherwise modified.\footnote{This manual takes advantage of that behavior at times in order to synchronize first and subsequent uses of names between formatted and unformatted sections of the body text.}
%
% \DescribeMacro{\LocalNames}
% \DescribeMacro{\GlobalNames}
@@ -1628,7 +1783,7 @@ Running "make install" installs the files in the local TeX tree.
% \subsection{``Text Tags''}
% \label{sec:tagtext}
%
-% Sections~\ref{sec:TagName} and~\ref{sec:UntagName} deal with similar tagging features in the index. ``Text tags'' differ from index tags because they are not printed automatically with every name managed by \textsf{nameauth}. Section~\ref{sec:moreC} offers additional solutions that use the macros in this section.
+% Sections~\ref{sec:TagName} and~\ref{sec:UntagName} deal with similar tagging features in the index. ``Text tags'' differ from index tags because they are not printed automatically with every name managed by \textsf{nameauth}. Section~\ref{sec:Hooksb} offers additional solutions that use the macros in this section.
%
% Instead of ``text tags,'' perhaps one should think about ``name information database entries.'' The macros in this section are named accordingly. We retain the ``text tag'' language for simplicity.
%
@@ -1645,7 +1800,7 @@ Running "make install" installs the files in the local TeX tree.
% \begin{quote}
% \cmd{\NameQueryInfo}\oarg{FNN}\marg{SNN}\oarg{Alternate names}
% \end{quote}
-% Thus, |``\NameQueryInfo[George]{Washington}.''| expands to ``\NameQueryInfo[George]{Washington}.'' Notice the space at the beginning of the tag. This is intentional, as with index tags. Sections~\ref{sec:TagName}, \ref{sec:UntagName}, and~\ref{sec:moreC} illustrate how this can permit tags like asterisks, daggers, and footnotes in addition to tags that do need a space or some separation between them and the name.
+% Thus, |``\NameQueryInfo[George]{Washington}.''| expands to ``\NameQueryInfo[George]{Washington}.'' Notice the space at the beginning of the tag. This is intentional, as with index tags. Sections~\ref{sec:TagName}, \ref{sec:UntagName}, and~\ref{sec:Hooksa}ff. illustrate how this can permit tags like asterisks, daggers, and footnotes in addition to tags that do need a space or some separation between them and the name.
%
% By using these text tag macros with the conditional macros, one can display information associated with a name based on whether or the name has occurred. As of version 2.4, this can be done either outside of \cmd{\NamesFormat} and the other general hooks or inside those macros.
%
@@ -1655,7 +1810,8 @@ Running "make install" installs the files in the local TeX tree.
% \cmd{\NameClearInfo}\oarg{FNN}\marg{SNN}\oarg{Alternate names}
% \end{quote}
%
-% For example, |\NameClearInfo[George]{Washington}|\NameClearInfo[George]{Washington} will cause the macro |``\NameQueryInfo[George]{Washington}''| to produce nothing: ``\NameQueryInfo[George]{Washington}''
+% For example, |\NameClearInfo[George]{Washington}|\NameClearInfo[George]{Washington} will cause the macro |``\NameQueryInfo[George]{Washington}''| to produce nothing.
+% \clearpage
%
% \subsection{Name Variant Macros}
% \subsubsection{\texttt{\textbackslash AKA}}
@@ -1668,23 +1824,39 @@ Running "make install" installs the files in the local TeX tree.
% \cmd{\AKA}\oarg{FNN}\marg{SNN}\oarg{Alt. FNN}\marg{Alt. SNN}\oarg{Alt. names}\\
% \cmd{\AKA*}\oarg{FNN}\marg{SNN}\oarg{Alt. FNN}\marg{Alt. SNN}\oarg{Alt. names}
% \end{quote}
-% Only the \meta{FNN} and \meta{SNN} arguments from \cmd{\Name} and friends may be cross-referenced. The new syntax allows \cmd{\AKA} to cross-reference all name types. Both macros create a cross-reference in the index from the \meta{Alt. FNN}, \meta{Alt. SNN}, and \meta{Alt. names} fields to a name defined by \meta{FNN} and \meta{SNN}, regardless of whether that name has been used. Please consult also Section~\ref{sec:AKAtips}, which covers a number of in-depth examples of \cmd{\AKA.}
+% Only the \meta{FNN} and \meta{SNN} arguments from \cmd{\Name} and friends may be cross-referenced. The new syntax allows \cmd{\AKA} to cross-reference all name types. Both macros create a cross-reference in the index from the \meta{Alt. FNN}, \meta{Alt. SNN}, and \meta{Alt. names} fields to a name defined by \meta{FNN} and \meta{SNN}, regardless of whether that name has been used. Please consult also Section~\ref{sec:AKAtips}, which covers a number of in-depth examples of \cmd{\AKA.} The syntactic aspects of name formatting (caps and reversing) work with \cmd{\AKA}.
%
% Both macros print only the \meta{Alt. FNN} and \meta{Alt. SNN} fields in the body text. If the \meta{Alt. names} field is present, \cmd{\AKA} swaps \meta{Alt. names} with \meta{Alt. FNN} in the body text, similar to the naming macros.
%
% \cmd{\AKA*} has two functions. For Western names, where \meta{Alt. FNN} is present, \cmd{\AKA*} prints either just the \meta{Alt. FNN} or just the \meta{Alt. names} when they also are present. However, if \meta{Alt. FNN} is absent, \cmd{\AKA*} prints just \meta{Alt. names} if present, otherwise \meta{Alt. SNN}. See also Section~\ref{sec:TagName}.
%
-% Here is a simple example with the default system of formatting:
+% In this simple example we redefine the the default system of formatting to illustrate what happens with formatting by default:
% \begin{quote}\small
+% \renewcommand*{\NamesFormat}{\scshape}|\renewcommand*{\NamesFormat}{\scshape}|\\
% |\Name{Jean, sans Peur}| |(\AKA{Jean,| |sans| |Peur}{Jean| |the| |Fearless})|\\ {\ttfamily was Duke of Burgundy 1404|--|1419.}
%
% \Name{Jean, sans Peur} (\AKA{Jean, sans Peur}{Jean the Fearless}) was Duke of Burgundy 1404--1419.
% \end{quote}
%
-% ``\AKA{Jean, sans Peur}{Jean the Fearless}'' receives no formatting; this package usually formats only names with main index entries. Section~\ref{sec:moreC} discusses how one might address that beyond the \texttt{alwaysformat} option. The syntactic aspects of name formatting (caps and reversing) always work with \cmd{\AKA}.
+% ``\AKA{Jean, sans Peur}{Jean the Fearless}''\marginpar{\small\raggedleft\texttt{formatAKA}} usually receives no formatting because it is post-processed by \cmd{\MainNamesHook} in the main matter text and \cmd{\FrontNamesHook} otherwise. The \texttt{alwaysformat} option causes the first-use hooks to be used all the time, while the \texttt{formatAKA} option causes the first-use hooks to be used only at the first use:
+% \ForgetName{Elizabeth, I}
+% \begin{quote}\small
+% \renewcommand*{\FrontNamesFormat}{\itshape}|\renewcommand*{\FrontNamesFormat}{\itshape}|\\
+% \renewcommand*{\NamesFormat}{\scshape}|\renewcommand*{\NamesFormat}{\scshape}|\\
+% |\LEliz\ was known as ``\AKA{Elizabeth, I}[Good Queen]{Bess}.''|\\
+% \makeatletter\@nameauth@AKAFormattrue\makeatother
+%
+% \LEliz\ was known as ``\AKA{Elizabeth, I}[Good Queen]{Bess}.''
+%
+% But if you switch to front matter, you will not get what you expect:\NamesInactive
+%
+% \LEliz\ was known as ``\AKA{Elizabeth, I}[Good Queen]{Bess}.''
+% \end{quote}
+% \cmd{\AKA} works with the main/front formatting systems, but its ``first use'' naming system allows only one first use per name, per document.\footnote{This is intentionally a part of the design for \cmd{\AKA}.}
+% Using \texttt{formatAKA} allows that one first-use instance to call the respective first-use formatting hooks. Of course, the \texttt{alwaysformat} option simply uses brute force to make everything call the first-use hooks.
%
-% The following complex example has lines of source literals interleaved with a point-by-point enumerated list, showing the Continental style. The small caps are a syntactic element of the name parameters themselves:
-% \begin{enumerate}\let\oldformat\NamesFormat\renewcommand\NamesFormat{}
+% The following complex example has lines of source text interleaved with a point-by-point enumerated list, showing the Continental style. The small caps are a syntactic element of the name parameters themselves:
+% \begin{enumerate}
% \item I tag the names for proper sorting.\\[4pt]
% |\PretagName[Heinz]{\textsc{Rühmann}}{Ruehmann, Heinz}%|\\
% |\PretagName[Heinrich Wilhelm]{\textsc{Rühmann}}%|\\
@@ -1692,12 +1864,12 @@ Running "make install" installs the files in the local TeX tree.
% \item I want ``\Name*[Heinz]{\textsc{Rühmann}}'' to be the main name of reference, so \cmd{\AKA*} uses his legal name as the cross-reference. \cmd{\AKA*} prints only ``Heinrich Wilhelm'' in the body text. Nevertheless, the index cross-reference will be complete with the surname.\\[4pt]
% |\AKA*[Heinz]{\textsc{Rühmann}}%|\\
% | [Heinrich Wilhelm]{\textsc{Rühmann}} %|
-% \item \cmd{\SubvertName} causes \cmd{\FName} to print the short version. It also bypasses the default name formatting.\\[4pt]
+% \item \cmd{\SubvertName} causes \cmd{\FName} to print the short version via the ``subsequent-use'' \cmd{\MainNameHook.}\\[4pt]
% |\SubvertName[Heinz]{\textsc{Rühmann}}%|
% \item \cmd{\FName} prints ``\FName[Heinz]{\textsc{Rühmann}}.''\\[4pt]
% |``\FName[Heinz]{\textsc{Rühmann}}'' %|
% \item \cmd{\Name} prints ``\Name[Heinz]{\textsc{Rühmann}}.'' The small caps are syntactic, not typographic, because they are part of the argument to \cmd{\Name} itself.\\[4pt]
-% |\Name[Heinz]{\textsc{Rühmann}} %|\let\NamesFormat\oldformat
+% |\Name[Heinz]{\textsc{Rühmann}} %|
% \end{enumerate}
% The resulting text is:
% \begin{quote}
@@ -1705,7 +1877,6 @@ Running "make install" installs the files in the local TeX tree.
% \SubvertName[Heinz]{\textsc{Rühmann}}``\FName[Heinz]{\textsc{Rühmann}}''
% \Name[Heinz]{\textsc{Rühmann}} (7 March 1902--3 October 1994) was a German film actor who appeared in over 100 films between 1926 and 1993.
% \end{quote}
-% \clearpage
%
% Using \Name[Bob]{Hope}, \ForgetName{Louis, XIV}\Name{Louis, XIV}, \Name{Lao-tzu}, and \Name{Gregory, I} as examples, we see how \cmd{\AKA} and \cmd{\AKA*} work:
%
@@ -1761,6 +1932,7 @@ Running "make install" installs the files in the local TeX tree.
% \AKA{Thomas, Aquinas}{\textit{Doctor Angelicus}}.
% \end{quote}
% We use the medieval form: |\Name{Thomas, Aquinas}| because ``Aquinas'' is not a surname, even though many people, including scholars, falsely use it as such. Section~\ref{sec:standards} talks about those unfortunate situations where one must use the Western form |\Name[Thomas]{Aquinas}.|
+% \clearpage
%
% \subsubsection{\texttt{\textbackslash PName}}
%
@@ -1804,7 +1976,7 @@ Running "make install" installs the files in the local TeX tree.
%
% Please\marginpar{\small\raggedleft\cmd{\global}} note that these two macros can be used explicitly as a pair. They also can be used singly within an explicit scope, where the effects cease after leaving that scope. Use \cmd{\global} to force a global effect.\medskip
%
-% \noindent\textbf{You cannot use index tags if the \textsf{nameauth} indexing feature is inactive.}
+% \noindent\begin{tabular}{p{0.97\textwidth}}\toprule\hfil\bfseries Index tags only work when indexing is active.\hfil\\\bottomrule\end{tabular}
%
% \subsubsection{Indexing and \textsf{babel}}
% \label{sec:babel}
@@ -1845,7 +2017,8 @@ Running "make install" installs the files in the local TeX tree.
% \begin{quote}
% \cmd{\PretagName}\oarg{FNN}\marg{SNN}\oarg{Alternate names}\marg{tag}
% \end{quote}
-% The \cmd{\PretagName} macro differs from the other tagging macros:
+%
+% Although the \cmd{\PretagName} macro might look similar to the the other tagging macros, its use and scope is quite a bit different:
% \begin{itemize}\small
% \item You can ``pretag'' any name and any cross-reference.
% \item You can ``tag'' and ``untag'' only names, not cross-references.
@@ -2165,10 +2338,10 @@ Running "make install" installs the files in the local TeX tree.
% \end{quote}
% \clearpage
%
-% \subsubsection{Formatting Hooks}
-% \label{sec:moreC}
+% \subsubsection{Hooks: Intro}
+% \label{sec:Hooksa}
%
-% Before\marginpar{\small\raggedleft Margin Paragraphs} we get to the use of text tags and name conditionals in name formatting, we begin with an intermediate example to illustrate that something more complex can occur in \cmd{\NamesFormat}. Here we put the first mention of a name in boldface, along with a marginal notation if possible:
+% Before\marginpar{\small\raggedleft Margin\break Paragraphs} we get to the use of text tags and name conditionals in name formatting, we begin with an intermediate example to illustrate that something more complex can occur in \cmd{\NamesFormat}. Here we put the first mention of a name in boldface, along with a marginal notation if possible:\footnote{A similar version of this example is in \texttt{examples.tex}, collocated with this manual.}
% \begin{quote}
% |\let\OldFormat\NamesFormat%|\\
% |\renewcommand*\NamesFormat[1]%|\\
@@ -2179,17 +2352,36 @@ Running "make install" installs the files in the local TeX tree.
% \end{quote}
% Changes to \cmd{\NamesFormat} should not rely merely on scoping rules to keep them ``local'' but should be changed and reset explicitly, or else odd side effects can result, especially with more exotic changes to \cmd{\NamesFormat}. We now use the example above in a sample text:
% \begin{quote}
-% \let\OldFormat\NamesFormat%
-% \renewcommand*\NamesFormat[1]{\textbf{#1}\ifinner\else\marginpar{\raggedleft\scriptsize #1}\fi}%
+% \let\OldFormat\NamesFormat\ignorespaces%
+% \renewcommand*\NamesFormat[1]%
+% {\textbf{#1}\ifinner\else
+% \marginpar{\raggedleft\scriptsize #1}\fi}%
% |\PretagName{Vlad, Ţepeş}{Vlad Tepes}% for accented names|\\[2ex]
-% {\small |\Name{Vlad| |III,| |Dracula},| |known| |as| |\AKA{Vlad| |III,| |Dracula}{Vlad,| |Ţepeş},| |``\AKA*{Vlad| |III,| |Dracula}{Vlad}[the| |Impaler]''| |after| |his| |death,| |was| |the| |son| |of| |\Name{Vlad| |II,| |Dracul},| |a| |member| |of| |the| |Order| |of| |the| |Dragon.| |Later| |references| |to| |``\Name{Vlad| |III,| |Dracula}''| |appear| |thus.%|}\\[2ex]
-% \Name{Vlad III, Dracula}, known as \AKA{Vlad III, Dracula}{Vlad, Ţepeş}, ``\AKA*{Vlad III, Dracula}{Vlad}[the Impaler]'' after his death, was the son of \Name{Vlad II, Dracul}, a member of the Order of the Dragon. Later references to ``\Name{Vlad III, Dracula}'' appear thus.%
+% {\small |\Name{Vlad| |III,| |Dracula},| |known| |as| |\AKA{Vlad| |III,| |Dracula}{Vlad,| |Ţepeş},| |``\AKA*{Vlad| |III,| |Dracula}{Vlad}[the| |Impaler]''| |after| |his| |death,| |was| |the| |son| |of| |\Name{Vlad| |II,| |Dracul},| |a| |member| |of| |the| |Order| |of| |the| |Dragon.| |Later| |references| |to| |``\Name{Vlad| |III,| |Dracula}''| |appear| |thus.|}\\[2ex]
+% \Name{Vlad III, Dracula}, known as \AKA{Vlad III, Dracula}{Vlad, Ţepeş}, ``\AKA*{Vlad III, Dracula}{Vlad}[the Impaler]'' after his death, was the son of \Name{Vlad II, Dracul}, a member of the Order of the Dragon. Later references to ``\Name{Vlad III, Dracula}'' appear thus.
% \let\NamesFormat\OldFormat%
% \end{quote}
%
% Now again we have reverted to the original form of \cmd{\NamesFormat} and we get \ForgetName{Vlad III, Dracula}\Name{Vlad III, Dracula} and \Name{Vlad III, Dracula}. For references to ``Vlad'' instead of ``\Name{Vlad III, Dracula}'' one could use |\Name{Vlad, III Dracula}|. Do not mix these forms with each other or with the old syntax, lest errors bite! You would get multiple index entries, unwanted cross-references, and unexpected forms in the text. The simplified interface greatly helps one to avoid this.
%
-% We continue\marginpar{\small\raggedleft Conditionals / Text Tags} onward to using not only name conditionals (Section~\ref{sec:tests}) but also text tags (Section~\ref{sec:tagtext}) to put tags after first references to main-matter names.
+% \let\OldMainHook\MainNameHook%
+% You cannot re-enter \cmd{\Name} or \cmd{\AKA} by calling them from within \cmd{\Namesformat,} \cmd{\FrontNameHook,} or \cmd{\MainNameHook,} as the next example shows:
+% \begin{quote}\small
+% |\renewcommand*\MainNameHook[1]%|\\
+% |{%|\\
+% | {#1}%|\\
+% | \IndexInactive%|\\
+% | \Name{foo}\AKA{bar}{baz}%|\\
+% | \IndexActive%|\\
+% |}|
+% \end{quote}
+% \renewcommand*\MainNameHook[1]{{#1}\IndexInactive\Name{foo}\AKA{bar}{baz}\IndexActive}%
+% Calling, \emph{e.g.}, |\Wash| produces \Wash, without foo, bar, or baz. \cmd{\Name} and \cmd{\AKA} expand to nothing. Version 2.4 of \textsf{nameauth} prevents stack-overflows both in this case and if you called the naming macros as their own arguments. |\Name{foo\Name{bar}}| would produce ``\textsc{foo}'' in the text and ``foo\textsc{bar}'' in the index. As you see, these cases are to be avoided.
+% \let\MainNameHook\OldMainHook%
+%
+% \subsubsection{Hooks: Life Dates}
+% \label{sec:Hooksb}
+% We can use name conditionals (Section~\ref{sec:tests}) and text tags (Section~\ref{sec:tagtext}) to add life information to names when desired.
%
% \DescribeMacro{\if@nameauth@InName}
% \DescribeMacro{\if@nameauth@InAKA}
@@ -2199,8 +2391,8 @@ Running "make install" installs the files in the local TeX tree.
% \DescribeMacro{\@nameauth@toksb}
% \DescribeMacro{\@nameauth@toksc}
% This package makes three token registers available to facilitate using the name conditional macros as we do below. Using these registers allows accented names to be recognized properly. In \cmd{\AKA} the token registers are copies of the \emph{last} three arguments, corresponding to the pseudonym. Nevertheless, they have the same names as the registers in \cmd{\@nameauth@Name} because they work the same way and may be easier to use this way.
-% \clearpage
%
+% We assume that we will not be using the \texttt{alwaysformat} option, meaning that we only call this hook once for a first use:\footnote{A similar version of this example is in \texttt{examples.tex}, collocated with this manual.}
% \begin{quote}\small
% |\newif\ifNoTextTag%|\hfill|allows us to work around \ForgetName|\\
% |\let\OldFormat\NamesFormat%|\hfill|save the format|\\
@@ -2212,36 +2404,20 @@ Running "make install" installs the files in the local TeX tree.
% | \if@nameauth@InName%|\hfill|do only in \@nameauth@Name|\\
% | \ifNoTextTag%|\hfill|true branch disables tags|\\
% | \else%|\hfill|take false branch|\\
-% | \ex\ex\ex\ex\ex\ex\ex\IfMainName\ex\ex\ex\ex\ex\ex\ex[%|\\
+% | \ex\ex\ex\ex\ex\ex\ex\NameQueryInfo%|\\
+% | \ex\ex\ex\ex\ex\ex\ex[%|\\
% | \ex\ex\ex\the\ex\ex\ex\@nameauth@toksa\ex\ex\ex]%|\\
% | \ex\ex\ex{\ex\the\ex\@nameauth@toksb\ex}%|\\
% | \ex[\the\@nameauth@toksc]%|\\
-% | {}%|\hfill|skip true branch to get first use|\\
-% | {%|\\
-% | \ex\ex\ex\ex\ex\ex\ex\NameQueryInfo%|\\
-% | \ex\ex\ex\ex\ex\ex\ex[%|\\
-% | \ex\ex\ex\the\ex\ex\ex\@nameauth@toksa\ex\ex\ex]%|\\
-% | \ex\ex\ex{\ex\the\ex\@nameauth@toksb\ex}%|\\
-% | \ex[\the\@nameauth@toksc]%|\\
-% | }%|\hfill|this form allows accents/control sequences|\\
% | \fi|\\
% | \fi|\\
% | \if@nameauth@InAKA%|\hfill|do only in \AKA|\\
% | \ifNoTextTag\else|\\
-% | \ex\ex\ex\ex\ex\ex\ex\IfAKA%|\\
+% | \ex\ex\ex\ex\ex\ex\ex\NameQueryInfo%|\\
% | \ex\ex\ex\ex\ex\ex\ex[%|\\
% | \ex\ex\ex\the\ex\ex\ex\@nameauth@toksa\ex\ex\ex]%|\\
% | \ex\ex\ex{\ex\the\ex\@nameauth@toksb\ex}%|\\
% | \ex[\the\@nameauth@toksc]%|\\
-% | {}%|\hfill|skip true branch to get first use|\\
-% | {%|\\
-% | \ex\ex\ex\ex\ex\ex\ex\NameQueryInfo%|\\
-% | \ex\ex\ex\ex\ex\ex\ex[%|\\
-% | \ex\ex\ex\the\ex\ex\ex\@nameauth@toksa\ex\ex\ex]%|\\
-% | \ex\ex\ex{\ex\the\ex\@nameauth@toksb\ex}%|\\
-% | \ex[\the\@nameauth@toksc]%|\\
-% | }%|\hfill|this form allows accents/control sequences|\\
-% | {}%|\hfill|skip excluded branch|\\
% | \fi|\\
% | \fi|\\
% | \global\NoTextTagfalse%|\hfill|reset tag suppression|\\
@@ -2249,9 +2425,9 @@ Running "make install" installs the files in the local TeX tree.
% |\makeatother%|
% \end{quote}
%
-% The example above uses \cmd{\NoTextTagtrue} to suppress tags and prints then by default in the false path. A different approach would print the tags only on the true path and still set \cmd{\NoTextTagfalse} at the end, so that the tags would only print when explicitly triggered.
+% The example above prints tags by default in the false path of \cmd{\NoTextTag}, while suppressing them in the true path.
%
-% Before we can refer to any text tags, we must create them. Please pardon the fact that I am going to ``lie'' about the tag used for ``Atatürk'' below in order to illustrate certain points regarding \cmd{\AKA.} I will tell the truth later when this group of examples is complete:
+% Before we can refer to any text tags, we must create them. Please pardon the fact that I am going to ``avoid the truth'' about the tag used for ``Atatürk'' below in order to illustrate certain points regarding \cmd{\AKA.} I will tell the truth later when this group of examples is complete:
% \begin{quote}\small
% |\NameAddInfo[George]{Washington}{ (1732--99)}%|\\
% |\NameAddInfo[Mustafa]{Kemal}{ (1881--1938)}%|\\
@@ -2262,44 +2438,71 @@ Running "make install" installs the files in the local TeX tree.
% \NameAddInfo{Atatürk}{ (a special surname granted 1934)}%
% \NameAddInfo{\kern0pt Atatürk}{ (a special surname granted 1934)}%
% \NameAddInfo{Atatürk\kern0pt}{ (a special surname granted 1934)}%
-% \NameAddInfo{\kern0pt Atatürk\kern0pt}{ (a special surname granted 1934)}%
-%
% We begin using the modified \cmd{\NamesFormat} under normal conditions:
% \newif\ifNoTextTag%
% \let\OldFormat\NamesFormat%
-% \makeatletter\renewcommand*\NamesFormat[1]{\let\ex\expandafter\textbf{#1}\if@nameauth@InName\ifNoTextTag\else\ex\ex\ex\ex\ex\ex\ex\IfMainName\ex\ex\ex\ex\ex\ex\ex[\ex\ex\ex\the\ex\ex\ex\@nameauth@toksa\ex\ex\ex]\ex\ex\ex{\ex\the\ex\@nameauth@toksb\ex}\ex[\the\@nameauth@toksc]{}{\ex\ex\ex\ex\ex\ex\ex\NameQueryInfo\ex\ex\ex\ex\ex\ex\ex[\ex\ex\ex\the\ex\ex\ex\@nameauth@toksa\ex\ex\ex]\ex\ex\ex{\ex\the\ex\@nameauth@toksb\ex}\ex[\the\@nameauth@toksc]}\fi\fi\if@nameauth@InAKA\ifNoTextTag\else\ex\ex\ex\ex\ex\ex\ex\IfAKA\ex\ex\ex\ex\ex\ex\ex[\ex\ex\ex\the\ex\ex\ex\@nameauth@toksa\ex\ex\ex]\ex\ex\ex{\ex\the\ex\@nameauth@toksb\ex}\ex[\the\@nameauth@toksc]{}{\ex\ex\ex\ex\ex\ex\ex\NameQueryInfo\ex\ex\ex\ex\ex\ex\ex[\ex\ex\ex\the\ex\ex\ex\@nameauth@toksa\ex\ex\ex]\ex\ex\ex{\ex\the\ex\@nameauth@toksb\ex}\ex[\the\@nameauth@toksc]}{}\fi\fi\global\NoTextTagfalse}\makeatother
+% \let\OldFrontFormat\FrontNamesFormat%
+% \makeatletter\renewcommand*\NamesFormat[1]{\let\ex\expandafter\textbf{#1}\if@nameauth@InName\ifNoTextTag\else\ex\ex\ex\ex\ex\ex\ex\NameQueryInfo\ex\ex\ex\ex\ex\ex\ex[\ex\ex\ex\the\ex\ex\ex\@nameauth@toksa\ex\ex\ex]\ex\ex\ex{\ex\the\ex\@nameauth@toksb\ex}\ex[\the\@nameauth@toksc]\fi\fi\if@nameauth@InAKA\ifNoTextTag\else\ex\ex\ex\ex\ex\ex\ex\NameQueryInfo\ex\ex\ex\ex\ex\ex\ex[\ex\ex\ex\the\ex\ex\ex\@nameauth@toksa\ex\ex\ex]\ex\ex\ex{\ex\the\ex\@nameauth@toksb\ex}\ex[\the\@nameauth@toksc]\fi\fi\global\NoTextTagfalse}\makeatother
% \ForgetName[George]{Washington}%
% \begin{quote}\small
% |\Wash| |held| |office| |1789--97.| |No| |tags| |appear| |in| |later| |uses| |of| |\Wash.| |We| |now| |suppress| |the| |dates| |and| |trigger| |a| |new| |first| |use:|\\
% |\NoTextTagtrue\ForgetName[George]{Washington}\Wash.|
%
-% |\Name[Mustafa]{Kemal}| |was| |later| |given| |the| |name%|\\ |\AKA[Mustafa]{Kemal}{Atatürk}.|
+% |\Name[Mustafa]{Kemal}| |was| |later| |given| |the| |name%|\\ |\AKA[Mustafa]{Kemal}{Atatürk}. We mention|\\
+% |\AKA[Mustafa]{Kemal}{Atatürk} again.|
%
% \Wash\ held office 1789--97. No tags appear in later uses of \Wash. We now suppress the dates and trigger a new first use: \NoTextTagtrue\ForgetName[George]{Washington}\Wash.
%
-% \Name[Mustafa]{Kemal} was later given the name \IndexInactive\AKA[Mustafa]{Kemal}{\kern0pt Atatürk}\IndexActive.
+% \Name[Mustafa]{Kemal} was later given the name \IndexInactive\AKA[Mustafa]{Kemal}{\kern0pt Atatürk}. We mention \AKA[Mustafa]{Kemal}{\kern0pt Atatürk} again\IndexActive.
% \end{quote}
%
-% Notice that the tag for Atatürk did not print. That is because \cmd{\AKA} only prints a formatted name when \cmd{\NamesActive} is in force and the \texttt{alwaysformat} option is set. We now forget \Wash\ and \Name[Mustafa]{Kemal}, using the same text but now simulating the effects of \texttt{alwaysformat}:\makeatletter\@nameauth@AlwaysFormattrue\makeatother
+% Notice that the text tag for Atatürk did not print. That is because \cmd{\AKA} usually only calls the ``subsequent use'' hooks. Therefore we simulate the \texttt{formatAKA} option and \cmd{\ForgetName} \Wash\ and \Name[Mustafa]{Kemal}:
% \begin{quote}\small
+% \makeatletter\@nameauth@AKAFormattrue\makeatother
% \ForgetName[George]{Washington}%
% \ForgetName[Mustafa]{Kemal}%
% \Wash\ held office 1789--97. No tags appear in later uses of \Wash. We now suppress the dates and trigger a new first use: \NoTextTagtrue\ForgetName[George]{Washington}\Wash.
%
-% \Name[Mustafa]{Kemal} was later given the name \IndexInactive\AKA[Mustafa]{Kemal}{Atatürk\kern0pt}\IndexActive.
-% \end{quote}\makeatletter\@nameauth@AlwaysFormatfalse\makeatother
-% Here we see that the tag is printed because \cmd{\NamesFormat} is called for every use. Still, the tags will not print with \cmd{\NamesInactive.} Before we get to the solution of that issue, perhaps it would help to think about what is happening:
+% \Name[Mustafa]{Kemal} was later given the name \IndexInactive\AKA[Mustafa]{Kemal}{Atatürk\kern0pt}. We mention \AKA[Mustafa]{Kemal}{Atatürk\kern0pt} again\IndexActive.
+% \end{quote}
+% Here we see that the tag is printed because \texttt{formatAKA} allows \cmd{\NamesFormat} to be called for the first use of Ataturk.
+%
+% Now we \cmd{\let} the first-use macro in the front matter be the same as that in the main matter and see what we get in the front matter via \cmd{\NamesInactive.} Again we simulate the \texttt{formatAKA} option and \cmd{\ForgetName} \Wash\ and \Name[Mustafa]{Kemal}:
+% \begin{quote}\small
+% \makeatletter\@nameauth@AKAFormattrue\makeatother\NamesInactive|\NamesInactive|\\
+% |\let\OldFrontFormat\FrontNamesFormat|\\
+% \let\FrontNamesFormat\NamesFormat|\let\FrontNamesFormat\NamesFormat|\\
+% \ForgetName[George]{Washington}%
+% \ForgetName[Mustafa]{Kemal}%
+% \Wash\ held office 1789--97. No tags appear in later uses of \Wash. We now suppress the dates and trigger a new first use: \NoTextTagtrue\ForgetName[George]{Washington}\Wash.
+%
+% \Name[Mustafa]{Kemal} was later given the name \AKA[Mustafa]{Kemal}{Atatürk}. We mention \AKA[Mustafa]{Kemal}{Atatürk} again.
+% \end{quote}
+% Again we see that everything is formatted the way we want, even in the front matter. Nevertheless, I have not been quite honest. Since I wanted to simulate multiple first uses of \cmd{\AKA,} which can print a tag only once unless you use the \texttt{alwaysformat} option, I inserted kerns into the instances of |\AKA[Mustafa]{Kemal}{Atatürk}| in the example paragraphs above:
+% \begin{quote}\footnotesize
+% |\NameAddInfo{\kern0pt| |Atatürk}{| |(a| |special| |surname| |granted| |1934)}|\\
+% |\NameAddInfo{Atatürk\kern0pt}{| |(a| |special| |surname| |granted| |1934)}|\\
+% |\NameAddInfo{Atatürk}{| |(a| |special| |surname| |granted| |1934)}|\\
+% \end{quote}
+% Because the names were different in each paragraph even though they looked the same, I prevented the names with kerns from appearing in the index via \cmd{\IndexInactive} and \cmd{\IndexActive.}\medskip
+%
+% Please remember to reset the formatting, if needed:\medskip
+%
+% \noindent\let\NamesFormat\OldFormat|\let\NamesFormat\OldFormat|\\
+% \let\FrontNamesFormat\OldFrontFormat|\let\FrontNamesFormat\OldFrontFormat|\medskip
+%
+% Here is a summary of what happens:
% \begin{enumerate}
% \item In \cmd{\@nameauth@name} and \cmd{\AKA}:
% \begin{enumerate}
% \item Parse name arguments. Save an unexpanded copy of each relevant name argument in a token register.
% \item Check for a control sequence based on them.
% \item Enter a decision route based on the result. Yes means the name exists. No means it does not. The decision route engages the Boolean values governing formatting.
-% \item Generate the index and print forms of the name. Create the index entry from the former and pass the latter onward to the format switching function, which decides if it is formatted main matter, regular main matter, or front matter as the Boolean values dictate.
+% \item Generate the index and print forms of the name. Create the index entry from the former and pass the latter onward to the format switching macro. Based on the Boolean values governing formatting, that macro calls either the first-use or subsequent-use hooks respectively in the main matter or the front matter.
% \end{enumerate}
-% \item In the hooks and \cmd{\NamesFormat}:
+% \item In the post-processing hooks:
% \begin{enumerate}
-% \item Normally you do nothing and exit, or make a local font change and exit. You could do more complex tasks.\footnote{One could discard the text output of the naming macros, retaining only the indexing functionality, then re-parse the name parameters and create a custom form of text output. One possibility could allow a more flexible Continental approach with macros that expand to \cmd{\textsc} except in the hook macros, where they output format only surnames, but perhaps not always.}
+% \item Normally you do nothing and exit, or make a local font change and exit. You could do more complex tasks like discarding the text output of the naming macros, then parsing and displaying the name parameters differently, based on the token registers.
% \item You also can make more than one independent check for a control sequence based on the name arguments saved in the token registers. This permits some fairly complex actions based on both the Boolean values and the control sequences themselves.
% \item Thus your decision route could turn into a tree or a set of relationships among a number of names.
% \item Print the form of the name as it was passed, or possibly do something else altogether.
@@ -2311,139 +2514,362 @@ Running "make install" installs the files in the local TeX tree.
% \item clean up and exit.
% \end{enumerate}
% \end{enumerate}
-% \DescribeMacro{\MainNameHook}
-% \DescribeMacro{\FrontNameHook}
-% \cmd{\AKA} can print a tag only once because its control sequences cannot be undefined by the \textsf{nameauth} macros. No tags are printed when \cmd{\NamesInactive} turns off formatting\,---\,even with \texttt{alwaysformat.} Two additional hooks address these limitations. \cmd{\MainNameHook} is triggered when \cmd{\NamesActive} is and \cmd{\NamesFormat} is not invoked. \cmd{\FrontNameHook} always is invoked when \cmd{\NamesInactive} is invoked. These hooks compliment \cmd{\NamesFormat.} With the examples below we use tags in the front matter and with the normal first-use case of \cmd{\AKA.}
+% \clearpage
+%
+% \subsubsection{Hooks: Continental}
+% \label{sec:Hooksc}
+%
+% For implementing Continental systems of name formatting, in addition to the basic methods already discussed, here we see how one can have the small caps consistently in the surnames for the first uses and the index, yet have a normal font for subsequent references in the body text.
+%
+% We begin by putting the following in the document preamble:
% \begin{quote}\small
-% |\let\OldFrontHook\FrontNameHook%|\hfill|save the hook|\\
-% |\let\OldMainHook\MainNameHook%|\hfill|save the hook|\\
-% |\makeatletter%|\hfill|access internals|\\
-% |\renewcommand*\MainNameHook[1]%|\\
-% |{%|\\
-% | \let\ex\expandafter%|\hfill|reduce typing|\\
-% | {#1}%|\\
-% | \if@nameauth@InAKA%|\hfill|do only in \AKA|\\
-% | \ifNoTextTag\else|\\
-% | \ex\ex\ex\ex\ex\ex\ex\IfAKA%|\\
-% | \ex\ex\ex\ex\ex\ex\ex[%|\\
-% | \ex\ex\ex\the\ex\ex\ex\@nameauth@toksa\ex\ex\ex]%|\\
-% | \ex\ex\ex{\ex\the\ex\@nameauth@toksb\ex}%|\\
-% | \ex[\the\@nameauth@toksc]%|\\
-% | {}%|\hfill|skip true branch to get first use|\\
-% | {%|\\
-% | \ex\ex\ex\ex\ex\ex\ex\NameQueryInfo%|\\
-% | \ex\ex\ex\ex\ex\ex\ex[%|\\
-% | \ex\ex\ex\the\ex\ex\ex\@nameauth@toksa\ex\ex\ex]%|\\
-% | \ex\ex\ex{\ex\the\ex\@nameauth@toksb\ex}%|\\
-% | \ex[\the\@nameauth@toksc]%|\\
-% | }%|\hfill|this form allows accents/control sequences|\\
-% | {}%|\hfill|skip excluded branch|\\
-% | \fi|\\
+% |\newif\ifSC|\\
+% |\SCtrue%|\hfill |This turns on small caps by default|
+%
+% \noindent|\def\DoFormat#1{%|\\
+% | \ifSC|\\
+% | \textsc{#1}%|\hfill |Format small caps if true|\\
+% | \else|\\
+% | #1%|\hfill |Do nothing if false|\\
% | \fi|\\
-% | \global\NoTextTagfalse%|\hfill|reset tag suppression|\\
-% |}|\\
+% |}|
+%
+% \cmd{\DoFormat} is the key to this whole approach. We want a control sequence that will expand differently under different circumstances.
+%
+% {\noindent\footnotesize|\begin{nameauth}|\\
+% | \< JQA & John Quincy & \noexpand\DoFormat{Adams} & >|\\
+% | \< Aeths & & \noexpand\DoFormat{Æþelstan} & >|\\
+% | \< Chas & & \noexpand\DoFormat{Charles}, I & >|\\
+% | \< Cao & & \noexpand\DoFormat{Cao}, Cao & >|\\
+% | \< JRIII & John David & \noexpand\DoFormat{Rockefeller}, III & >|\\
+% | \< SDJR & Sammy & \noexpand\DoFormat{Davis}, \noexpand\DoFormat{Jr}. & >|\\
+% |\end{nameauth}|}
+%
+% \cmd{\noexpand} is another vital piece of the solution. If one does not use this, all sorts of errors will arise. We also must sort these names properly:
+%
+% {\noindent\footnotesize|\PretagName[John Quincy]{\noexpand\DoFormat{Adams}}{Adams, John Quincy}|\\
+% |\PretagName{\noexpand\DoFormat{Æþelstan}}{Aethelstan}|\\
+% |\PretagName{\noexpand\DoFormat{Charles}, I}{Charles 1}|\\
+% |\PretagName{\noexpand\DoFormat{Cao}, Cao}{Cao Cao}|\\
+% |\PretagName[John David]{\noexpand\DoFormat{Rockefeller}, III}%|\\
+% | {Rockefeller, John David, III}|\\
+% |\PretagName[Sammy]{\noexpand\DoFormat{Davis}, \noexpand\DoFormat{Jr}.}%|\\
+% | {Davis, Sammy, Jr.}|}
+% \end{quote}
+%
+% Above we have our control sequences set up for our names. Next we save the old ``subsequent use'' hook macros:
+% \begin{quote}\small
+% |\let\OldFrontHook\FrontNameHook%|\\
+% |\let\OldMainHook\MainNameHook%|
+% \end{quote}
+%
+% \let\OldFrontHook\FrontNameHook%
+% \let\OldMainHook\MainNameHook%
+% We do not need to redefine either \cmd{\NamesFormat} or \cmd{\FrontNamesFormat} because we want the first uses to display small caps in the text. We redefine \cmd{\MainNameHook} and \cmd{\FrontNameHook} in order to \emph{suppress} formatting in all subsequent uses of names. We also use the \texttt{formatAKA} option.
% \clearpage
-% |\renewcommand*\FrontNameHook[1]%|\\
+%
+% The new implementation of \cmd{\MainNameHook} follows. We incorporate those parts of \cmd{\AKA} and \cmd{\@nameauth@Name} that print name arguments in the text:\footnote{A similar version of this example is in \texttt{examples.tex}, collocated with this manual.}
+% \begin{quote}\small
+% |\makeatletter%|\\
+% |\renewcommand*\MainNameHook[1]%|\\
% |{%|\\
-% | \let\ex\expandafter%|\hfill|reduce typing|\\
-% | {#1}%|\\
-% | \if@nameauth@InName%|\hfill|do only in \@nameauth@Name|\\
-% | \ifNoTextTag\else|\\
-% | \ex\ex\ex\ex\ex\ex\ex\IfFrontName%|\\
-% | \ex\ex\ex\ex\ex\ex\ex[%|\\
-% | \ex\ex\ex\the\ex\ex\ex\@nameauth@toksa\ex\ex\ex]%|\\
-% | \ex\ex\ex{\ex\the\ex\@nameauth@toksb\ex}%|\\
-% | \ex[\the\@nameauth@toksc]%|\\
-% | {}%|\hfill|skip true branch to get first use|\\
-% | {%|\\
-% | \ex\ex\ex\ex\ex\ex\ex\NameQueryInfo%|\\
-% | \ex\ex\ex\ex\ex\ex\ex[%|\\
-% | \ex\ex\ex\the\ex\ex\ex\@nameauth@toksa\ex\ex\ex]%|\\
-% | \ex\ex\ex{\ex\the\ex\@nameauth@toksb\ex}%|\\
-% | \ex[\the\@nameauth@toksc]%|\\
-% | }%|\hfill|this form allows accents/control sequences|\\
-% | {}%|\hfill|skip excluded branch|\\
+% | \let\ex\expandafter%|\\
+% | \SCfalse%|
+%
+% Above we set the small caps Boolean to false. Now we have to ``redo'' name parsing in order to get the different format. We get the unexpanded arguments from the naming macro that called us via the token registers. We must expand the register values for comparisons to work.
+%
+% {\noindent\footnotesize| \protected@edef\arga{\ex\trim@spaces\ex{\the\@nameauth@toksa}}%|\\
+% | \protected@edef\argb{\ex\trim@spaces\ex{\the\@nameauth@toksb}}%|\\
+% | \protected@edef\testb{\ex\@nameauth@Root\ex{\the\@nameauth@toksb}}%|\\
+% | \protected@edef\argc{\ex\trim@spaces\ex{\the\@nameauth@toksc}}%|}
+%
+% \cmd{\Space} is defined by the parent macro. Here we print an appropriate version of the pseudonym in the text. We cannot use the text-only capitalization macros when we use this scheme. This is not much of a problem when using Continental contexts.
+%
+% | \ifx\argb\testb|\\
+% | \protected@edef\Suff{\@empty}%|\\
+% | \let\Reversed\argb%|\\
+% | \let\SNN\argb%|\\
+% | \let\Short\argb%|\\
+% | \else|\\
+% | \protected@edef\Suff{\ex\@nameauth@Suffix\ex{%|\\
+% | \the\@nameauth@toksb}}%|\\
+% | \protected@edef\Reversed{\Suff\Space\testb}%|\\
+% | \protected@edef\SNN{\testb\Space\Suff}%|\\
+% | \if@nameauth@RevThis|\\
+% | \let\Short\Suff%|\\
+% | \else|\\
+% | \let\Short\testb%|\\
+% | \fi|\\
+% | \fi|
+%
+% Only the reversing macros will work with the macros that we generate above as well as in the rest of this hook. The capitalization macros are ignored.
+% \clearpage
+%
+% Print an appropriate version of the pseudonym in the text.
+%
+% | \if@nameauth@InAKA|\\
+% | \ifx\arga\@empty|\\
+% | \ifx\argc\@empty|\\
+% | \if@nameauth@RevThis|\\
+% | \Reversed%|\\
+% | \else|\\
+% | \SNN%|\\
+% | \fi|\\
+% | \else|\\
+% | \if@nameauth@AltAKA|\\
+% | \argc%|\\
+% | \else|\\
+% | \if@nameauth@RevThis|\\
+% | \ex\argc\ex\Space\SNN%|\\
+% | \else|\\
+% | \ex\SNN\ex\space\argc%|\\
+% | \fi|\\
+% | \fi|\\
+% | \fi|\\
+% | \else|\\
+% | \ifx\argc\@empty|\\
+% | \let\FNN\arga%|\\
+% | \else|\\
+% | \let\FNN\argc%|\\
+% | \fi|\\
+% | \if@nameauth@AltAKA|\\
+% | \FNN%|\\
+% | \else|\\
+% | \if@nameauth@RevThis|\\
+% | \ex\SNN\ex\Space\FNN%|\\
+% | \else|\\
+% | \ex\FNN\ex\space\SNN%|\\
+% | \fi|\\
+% | \fi|\\
% | \fi|\\
-% | \fi|\\
-% | \if@nameauth@InAKA%|\hfill|do only in \AKA|\\
-% | \ifNoTextTag\else|\\
-% | \ex\ex\ex\ex\ex\ex\ex\IfAKA%|\\
-% | \ex\ex\ex\ex\ex\ex\ex[%|\\
-% | \ex\ex\ex\the\ex\ex\ex\@nameauth@toksa\ex\ex\ex]%|\\
-% | \ex\ex\ex{\ex\the\ex\@nameauth@toksb\ex}%|\\
-% | \ex[\the\@nameauth@toksc]%|\\
-% | {}%|\hfill|skip true branch to get first use|\\
-% | {%|\\
-% | \ex\ex\ex\ex\ex\ex\ex\NameQueryInfo%|\\
-% | \ex\ex\ex\ex\ex\ex\ex[%|\\
-% | \ex\ex\ex\the\ex\ex\ex\@nameauth@toksa\ex\ex\ex]%|\\
-% | \ex\ex\ex{\ex\the\ex\@nameauth@toksb\ex}%|\\
-% | \ex[\the\@nameauth@toksc]%|\\
-% | }%|\hfill|this form allows accents/control sequences|\\
-% | {}%|\hfill|skip excluded branch|\\
+% | \else|
+% \clearpage
+% Print an appropriate version of the name in the text.
+%
+% | \ifx\arga\@empty|\\
+% | \ifx\argc\@empty|\\
+% | \if@nameauth@FullName|\\
+% | \if@nameauth@RevThis|\\
+% | \Reversed%|\\
+% | \else|\\
+% | \SNN%|\\
+% | \fi|\\
+% | \else|\\
+% | \Short%|\\
+% | \fi|\\
+% | \else|\\
+% | \if@nameauth@FullName|\\
+% | \if@nameauth@RevThis|\\
+% | \ex\argc\ex\space\SNN%|\\
+% | \else|\\
+% | \ex\SNN\ex\space\argc%|\\
+% | \fi|\\
+% | \else|\\
+% | \if@nameauth@RevThis|\\
+% | \argc%|\\
+% | \else|\\
+% | \Short%|\\
+% | \fi|\\
+% | \fi|\\
+% | \fi|\\
+% | \else|\\
+% | \ifx\argc\@empty|\\
+% | \let\FNN\arga%|\\
+% | \else|\\
+% | \let\FNN\argc%|\\
+% | \fi|\\
+% | \let\Short\FNN%|\\
+% | \if@nameauth@FullName|\\
+% | \if@nameauth@RevThis|\\
+% | \ex\SNN\ex\Space\FNN%|\\
+% | \else|\\
+% | \ex\FNN\ex\space\SNN%|\\
+% | \fi|\\
+% | \else|\\
+% | \if@nameauth@FirstName|\\
+% | \Short%|\\
+% | \else|\\
+% | \testb%|\\
+% | \fi|\\
+% | \fi|\\
% | \fi|\\
% | \fi|\\
-% | \global\NoTextTagfalse%|\hfill|reset tag suppression|\\
% |}|
-% |\makeatother%|
% \end{quote}
%
-% \let\OldFrontHook\FrontNameHook%
-% \let\OldMainHook\MainNameHook%
-% \makeatletter
-% \renewcommand*\FrontNameHook[1]{\let\ex\expandafter{#1}\if@nameauth@InName\ifNoTextTag\else\ex\ex\ex\ex\ex\ex\ex\IfFrontName\ex\ex\ex\ex\ex\ex\ex[\ex\ex\ex\the\ex\ex\ex\@nameauth@toksa\ex\ex\ex]\ex\ex\ex{\ex\the\ex\@nameauth@toksb\ex}\ex[\the\@nameauth@toksc]{}{\ex\ex\ex\ex\ex\ex\ex\NameQueryInfo\ex\ex\ex\ex\ex\ex\ex[\ex\ex\ex\the\ex\ex\ex\@nameauth@toksa\ex\ex\ex]\ex\ex\ex{\ex\the\ex\@nameauth@toksb\ex}\ex[\the\@nameauth@toksc]}{}\fi\fi\if@nameauth@InAKA\ifNoTextTag\else\ex\ex\ex\ex\ex\ex\ex\IfAKA\ex\ex\ex\ex\ex\ex\ex[\ex\ex\ex\the\ex\ex\ex\@nameauth@toksa\ex\ex\ex]\ex\ex\ex{\ex\the\ex\@nameauth@toksb\ex}\ex[\the\@nameauth@toksc]{}{\ex\ex\ex\ex\ex\ex\ex\NameQueryInfo\ex\ex\ex\ex\ex\ex\ex[\ex\ex\ex\the\ex\ex\ex\@nameauth@toksa\ex\ex\ex]\ex\ex\ex{\ex\the\ex\@nameauth@toksb\ex}\ex[\the\@nameauth@toksc]}{}\fi\fi\global\NoTextTagfalse}
-% \renewcommand*\MainNameHook[1]{\let\ex\expandafter{#1}\if@nameauth@InAKA\ifNoTextTag\else\ex\ex\ex\ex\ex\ex\ex\IfAKA\ex\ex\ex\ex\ex\ex\ex[\ex\ex\ex\the\ex\ex\ex\@nameauth@toksa\ex\ex\ex]\ex\ex\ex{\ex\the\ex\@nameauth@toksb\ex}\ex[\the\@nameauth@toksc]{}{\ex\ex\ex\ex\ex\ex\ex\NameQueryInfo\ex\ex\ex\ex\ex\ex\ex[\ex\ex\ex\the\ex\ex\ex\@nameauth@toksa\ex\ex\ex]\ex\ex\ex{\ex\the\ex\@nameauth@toksb\ex}\ex[\the\@nameauth@toksc]}{}\fi\fi\global\NoTextTagfalse}
-% \makeatother%
+% This is a really long example! It incorporates much of the parsing that is done in \cmd{\AKA} and \cmd{\@nameauth@Name} in order to implement as much of the standard look and feel as possible.
+% \makeatletter%
+% \renewcommand*\MainNameHook[1]{\ignorespaces%
+% \let\ex\expandafter\ignorespaces%
+% \SCfalse\ignorespaces%
+% \protected@edef\arga{\ex\trim@spaces\ex{\the\@nameauth@toksa}}\ignorespaces%
+% \protected@edef\argb{\ex\trim@spaces\ex{\the\@nameauth@toksb}}\ignorespaces%
+% \protected@edef\testb{\ex\@nameauth@Root\ex{\the\@nameauth@toksb}}\ignorespaces%
+% \protected@edef\argc{\ex\trim@spaces\ex{\the\@nameauth@toksc}}\ignorespaces%
+% \ifx\argb\testb
+% \protected@edef\Suff{\@empty}\ignorespaces%
+% \let\Reversed\argb\ignorespaces%
+% \let\SNN\argb\ignorespaces%
+% \let\Short\argb\ignorespaces%
+% \else
+% \protected@edef\Suff{\ex\@nameauth@Suffix\ex{\the\@nameauth@toksb}}\ignorespaces%
+% \protected@edef\Reversed{\Suff\Space\testb}\ignorespaces%
+% \protected@edef\SNN{\testb\Space\Suff}\ignorespaces%
+% \if@nameauth@RevThis
+% \let\Short\Suff%
+% \else
+% \let\Short\testb%
+% \fi
+% \fi
+% \if@nameauth@InAKA
+% \ifx\arga\@empty
+% \ifx\argc\@empty
+% \if@nameauth@RevThis
+% \Reversed%
+% \else
+% \SNN%
+% \fi
+% \else
+% \if@nameauth@AltAKA
+% \argc%
+% \else
+% \if@nameauth@RevThis
+% \ex\argc\ex\Space\SNN%
+% \else
+% \ex\SNN\ex\space\argc%
+% \fi
+% \fi
+% \fi
+% \else
+% \ifx\argc\@empty
+% \let\FNN\arga%
+% \else
+% \let\FNN\argc%
+% \fi
+% \if@nameauth@AltAKA
+% \FNN%
+% \else
+% \if@nameauth@RevThis
+% \ex\SNN\ex\Space\FNN%
+% \else
+% \ex\FNN\ex\space\SNN%
+% \fi
+% \fi
+% \fi
+% \else
+% \ifx\arga\@empty
+% \ifx\argc\@empty
+% \if@nameauth@FullName
+% \if@nameauth@RevThis
+% \Reversed%
+% \else
+% \SNN%
+% \fi
+% \else
+% \Short%
+% \fi
+% \else
+% \if@nameauth@FullName
+% \if@nameauth@RevThis
+% \ex\argc\ex\space\SNN%
+% \else
+% \ex\SNN\ex\space\argc%
+% \fi
+% \else
+% \if@nameauth@RevThis
+% \argc%
+% \else
+% \Short%
+% \fi
+% \fi
+% \fi
+% \else
+% \ifx\argc\@empty
+% \let\FNN\arga%
+% \else
+% \let\FNN\argc%
+% \fi
+% \let\Short\FNN%
+% \if@nameauth@FullName
+% \if@nameauth@RevThis
+% \ex\SNN\ex\Space\FNN%
+% \else
+% \ex\FNN\ex\space\SNN%
+% \fi
+% \else
+% \if@nameauth@FirstName
+% \Short%
+% \else
+% \testb%
+% \fi
+% \fi
+% \fi
+% \fi
+% }
% \clearpage
-% We forget \Wash\ and \Name[Mustafa]{Kemal}, then see the text as front matter:
-% \begin{quote}\small
-% \NamesInactive%
-% \ForgetName[George]{Washington}%
-% \ForgetName[Mustafa]{Kemal}%
-% \Wash\ held office 1789--97. No tags appear in later uses of \Wash. We now suppress the dates and trigger a new first use: \NoTextTagtrue\ForgetName[George]{Washington}\Wash.
%
-% \Name[Mustafa]{Kemal} was later given the name \IndexInactive\AKA[Mustafa]{Kemal}{\kern0pt Atatürk\kern0pt}\IndexActive.
+% The final hook operates in the front matter. We simply let \cmd{\FrontNameHook} be the same as \cmd{\MainNameHook} in order to suppress all formatting. This is similar to the default behavior of \textsf{nameauth.}
+% \begin{quote}\small
+% |\let\FrontNameHok\MainNameHook|\\
+% |\makeatother|
% \end{quote}
+% \let\FrontNameHook\MainNameHook
+% \makeatother
%
-% Finally we have the same text as main matter:
-% \begin{quote}\small
-% \NamesActive%
-% \ForgetName[George]{Washington}%
-% \ForgetName[Mustafa]{Kemal}%
-% \Wash\ held office 1789--97. No tags appear in later uses of \Wash. We now suppress the dates and trigger a new first use: \NoTextTagtrue\ForgetName[George]{Washington}\Wash.
+% \noindent{\large\bfseries Main Matter}\\
%
-% \Name[Mustafa]{Kemal} was later given the name \AKA[Mustafa]{Kemal}{Atatürk}.
-% \end{quote}
-% \let\MainNameHook\OldMainHook%
-% \let\FrontNameHook\OldFrontHook%
-% \let\NamesFormat\OldFormat%
+% {\footnotesize\noindent\begin{tabular}{llll}\toprule
+% First & Next & Long & Short \\\midrule
+% \JQA & \JQA & \LJQA & \SJQA\\
+% \JRIII & \JRIII & \LJRIII & \SJRIII\\
+% \Aeths & \Aeths & \LAeths & \SAeths\\
+% \Chas & \Chas & \LChas & \SChas\\
+% \Cao & \Cao & \LCao & \SCao\\\bottomrule
+% \end{tabular}}\bigskip
+%
+% \noindent{\large\bfseries Front Matter}\\
+%
+% \NamesInactive
+% {\footnotesize\noindent\begin{tabular}{llll}\toprule
+% First & Next & Long & Short \\\midrule
+% \JQA & \JQA & \LJQA & \SJQA\\
+% \JRIII & \JRIII & \LJRIII & \SJRIII\\
+% \Aeths & \Aeths & \LAeths & \SAeths\\
+% \Chas & \Chas & \LChas & \SChas\\
+% \Cao & \Cao & \LCao & \SCao\\\bottomrule
+% \end{tabular}}\bigskip
+% \NamesActive
%
-% Please be aware that each instance of \AKA[Mustafa]{Kemal}{Atatürk} in the four example paragraphs above actually was a different name, even though they look the same:
+% We can refer to \SDJR. See how the punctuation detection still works? The next reference is \SDJR.
+% We also can use reversing, such as reversing with commas:\\
+%
+% \ReverseCommaActive
+% {\footnotesize\noindent\begin{tabular}{lll}\toprule
+% Long & Normal & Short \\\midrule
+% \LJQA & \JQA & \SJQA\\
+% \LJRIII & \JRIII & \SJRIII\\
+% \LSDJR & \SDJR & \SSDJR \\\bottomrule
+% \end{tabular}}\bigskip
+% \ReverseCommaInactive
+%
+% \makeatletter\@nameauth@AKAFormattrue\makeatother
+% If we use the \texttt{formatAKA} option we can refer to \LCao\ as \AKA{\noexpand\DoFormat{Cao}, Cao}{\noexpand\DoFormat{Mengde}}, and again \AKA{\noexpand\DoFormat{Cao}, Cao}{\noexpand\DoFormat{Mengde}}. We get that with:
% \begin{quote}\small
-% |\NameAddInfo{Atatürk}{| |(a| |special| |surname| |granted| |1934)}|\\
-% |\NameAddInfo{\kern0pt| |Atatürk}{| |(a| |special| |surname| |granted| |1934)}|\\
-% |\NameAddInfo{Atatürk\kern0pt}{| |(a| |special| |surname| |granted| |1934)}|\\
-% |\NameAddInfo{\kern0pt| |Atatürk\kern0pt}{| |(a| |special| |surname| |granted| |1934)}|
+% |\PretagName{\noexpand\DoFormat{Mengde}}{Mengde}|\\
+% |\AKA{\noexpand\DoFormat{Cao}, Cao}{\noexpand\DoFormat{Mengde}}|
% \end{quote}
-% Because the names were different, I suppressed all but one of the variants from appearing in the index by putting the undesired extras between \cmd{\IndexInactive} and \cmd{\IndexActive.}
+% \makeatletter\@nameauth@AKAFormatfalse\makeatother
+% Otherwise \cmd{\AKA} will not format the alternate name.
%
-% Please do remember that \cmd{\IfAKA} will only expand to the false route before the first appearance of a pseudonym. Otherwise it will remain true for the rest of the document. Please do not let these examples mislead you in that regard. They are merely illustrative of hypothetical first uses.
-%
-% \let\OldMainHook\MainNameHook%
-% The next example shows how you cannot re-enter \cmd{\Name} or \cmd{\AKA} from within \cmd{\Namesformat,} \cmd{\FrontNameHook,} or \cmd{\MainNameHook.}
+% When we are done, if the scope is not document-wide, we restore the hooks to their old values:
% \begin{quote}\small
-% |\renewcommand*\MainNameHook[1]%|\\
-% |{%|\\
-% | {#1}%|\\
-% | \IndexInactive%|\\
-% | \Name{foo}\AKA{bar}{baz}%|\\
-% | \IndexActive%|\\
-% |}|
+% |\let\FrontNameHook\OldFrontHook|\\
+% |\let\MainNameHook\OldMainHook|
% \end{quote}
-% \renewcommand*\MainNameHook[1]{{#1}\IndexInactive\Name{foo}\AKA{bar}{baz}\IndexActive}%
-% Calling |\Wash| produces \Wash. \cmd{\Name} and \cmd{\AKA} both exit and do nothing. Version 2.4 of \textsf{nameauth} prevents stack-overflows for the above example and the odd case of calling the naming macros as their own arguments. Nevertheless, |\Name{foo\Name{bar}}| would produce ``\textsc{foo}'' in the text and ``foo\textsc{bar}'' in the index. One might want to avoid such cases.
-% \renewcommand*\MainNameHook{}
-% \renewcommand*\FrontNameHook{}
+% \let\FrontNameHook\OldFrontHook
+% \let\MainNameHook\OldMainHook
+%
+% I am the first to admit that this example is quite involved. I am painfully aware that this package has not crystallized from a great knowledge base or descended on high from any kind of superior design. It has been quite a journey of discovery about naming and \LaTeX, \emph{inter alia}.
% \clearpage
%
% \subsubsection{Variant Spellings}
@@ -2605,14 +3031,14 @@ Running "make install" installs the files in the local TeX tree.
% \indent \Mao, \LMao, \Mao, and \SMao}
% \vfil
%
-% Avoid mixing old and new syntax. In the body text, |\Name{Antiochus, IV}| and |\Name{Antiochus,| |IV}[Epiphanes]| look alike, but their index entries differ.
+% Avoid mixing old and new syntax. |\Name{Antiochus,| |IV| |Epiphanes}| and |\Name{Antiochus}[IV| |Epiphanes]| look similar, but they are quite different. Even if you avoid the old syntax, keep the following in mind:
%
% \begin{itemize}\small
-% \item Use |\Name{Antiochus, IV Epiphanes}| to get \IndexInactive\Name{Antiochus, IV Epiphanes} and \Name{Antiochus, IV Epiphanes} in the text and ``Antiochus IV Epiphanes'' in the index.
+% \item \textbf{Okay:} Use |\Name{Antiochus, IV Epi\-phanes}| to get \IndexInactive\Name{Antiochus, IV Epi\-phanes} and \Name{Antiochus, IV Epi\-phanes} in the body text and ``Antiochus IV Epi\-phanes'' in the index.
%
-% \item Use |\Name{Antiochus~IV, Epiphanes}| to get \Name{Antiochus~IV, Epiphanes} and \Name{Antiochus~IV, Epiphanes} in the text and ``Antiochus IV Epiphanes'' in the index.\IndexActive
+% \item \textbf{Okay:} Use |\Name{Antiochus~IV, Epi\-phanes}| to get \Name{Antiochus~IV, Epi\-phanes} and \Name{Antiochus~IV, Epi\-phanes} in the body text and ``Antiochus IV Epi\-phanes'' in the index.\IndexActive
%
-% \item Use |\Name{Antiochus,| |IV}| to get \Name{Antiochus, IV} and \Name{Antiochus, IV} in the text. Use something like |\TagName{Antiochus,| |IV}{| |Epiphanes}| to get ``Antiochus IV Epiphanes'' in the index and add ``Epiphanes'' in the text.
+% \item \textbf{Best:} Use |\Name{Antiochus,| |IV}| to get \Name{Antiochus, IV} and \Name{Antiochus, IV} in the text. Add a tag like |\TagName{Antiochus,| |IV}{| |Epi\-phanes}| to get ``Antiochus IV Epi\-phanes'' in the index. Manually add ``Epi\-phanes'' in the body text when desired.
% \end{itemize}
% \clearpage
%
@@ -2722,9 +3148,10 @@ Running "make install" installs the files in the local TeX tree.
% \end{macrocode}\medskip
%
% \noindent{\large\bfseries Toggle Formatting}\\[0.5ex]
-% \cmd{\NamesActive} and \cmd{\NamesInactive} or the |mainmatter| and |frontmatter| options set or clear the value below. |\@nameauth@DoFormatfalse| ensures that \cmd{\FrontNameHook} is called for all front-matter names.
+% \cmd{\NamesActive} and \cmd{\NamesInactive} or the |mainmatter| and |frontmatter| options make \cmd{\@nameauth@MainFormat} either true or false, which switches between the main and front matter hooks. \cmd{\@nameauth@AKAFormat} permits \cmd{\AKA} to call the first-use hooks. Otherwise it will call only the subsequent-use hooks.
% \begin{macrocode}
-\newif\if@nameauth@DoFormat
+\newif\if@nameauth@MainFormat
+\newif\if@nameauth@AKAFormat
% \end{macrocode}
% The next value works with \cmd{\LocalNames} and \cmd{\GlobalNames}.
% \begin{macrocode}
@@ -2742,7 +3169,7 @@ Running "make install" installs the files in the local TeX tree.
% \end{macrocode}\medskip
%
% \noindent{\large\bfseries Syntactic Formatting}\\[0.5ex]
-% |\@nameauth@FullName| toggles long or short forms in subsequent name uses. As a corollary, |\@nameauth@FirstName| is used when printing only first names. |\@nameauth@AltAKA| is toggled respectively by \cmd{\AKA} and \cmd{\AKA*} to print a longer or shorter name.
+% \cmd{\@nameauth@FullName} is true in any case where a long name reference is desired. \cmd{\@nameauth@FirstName} disables full-name references and causes only Western forenames to be displayed. |\@nameauth@AltAKA| is toggled respectively by \cmd{\AKA} and \cmd{\AKA*} to print a longer or shorter name.
% \begin{macrocode}
\newif\if@nameauth@FullName
\newif\if@nameauth@FirstName
@@ -2774,64 +3201,71 @@ Running "make install" installs the files in the local TeX tree.
\newif\if@nameauth@Punct
% \end{macrocode}\medskip
%
-% \noindent{\large\bfseries Typographic Formatting}\\[0.5ex]
-% |\@nameauth@FirstFormat| toggles the formatting of main-matter names by triggering whether \cmd{\NamesFormat} is called or whether \cmd{\MainNameHook} is called. Additionally, |\@nameauth@AlwaysFormat| forces name formatting whenever |\@nameauth@DoFormat| is true by setting |\@nameauth@FirstFormattrue.|
+% \noindent{\large\bfseries Hook Triggers}\\[0.5ex]
+% |\@nameauth@FirstFormat| triggers the first-use hooks to be called; otherwise the second-use hooks are called. Additionally, |\@nameauth@AlwaysFormat| forces this true, except when \cmd{\@nameauth@AKAFormat} is false.
% \begin{macrocode}
\newif\if@nameauth@FirstFormat
\newif\if@nameauth@AlwaysFormat
% \end{macrocode}\medskip
%
% \noindent{\large\bfseries Who Called Me?}\\[0.5ex]
-% These values are true within \cmd{\Name} and \cmd{\AKA}, respectively. Otherwise they are false. Normally they have no effect, but they are available for special customizations of \cmd{\NamesFormat,} \cmd{\MainNameHook,} and \cmd{\FrontNameHook.} See Section~\ref{sec:moreC}.
+% These values are true within \cmd{\Name} and \cmd{\AKA}, respectively. Otherwise they are false. They are used when one modifies the hook macros. See Sections~\ref{sec:Hooksb}ff.
% \begin{macrocode}
\newif\if@nameauth@InAKA
\newif\if@nameauth@InName
% \end{macrocode}
-% As a side note, \cmd{\AKA} will invoke \cmd{\NamesFormat} if the \texttt{alwaysformat} option is set and \cmd{\NamesActive}. Otherwise it will invoke \cmd{\MainNameHook} in the main matter and \cmd{\FrontNameHook} in the front matter (\cmd{\NamesInactive}). Thus you need to check both Boolean values above to get the desired outcomes for these hooks.\medskip
+% As a side note, \cmd{\AKA} will invoke \cmd{\NamesFormat} / \cmd{\FrontNamesFormat} if the \texttt{alwaysformat} option is set. Otherwise it will invoke \cmd{\MainNameHook} / \cmd{\FrontNameHook}.\medskip
%
% \noindent{\large\bfseries Stack Overflow Prevention}\\[0.5ex]
-% Here is the locking mechanism that prevents a stack overflow via recursive calls to \cmd{\Name} and \cmd{\AKA}. See Section~\ref{sec:moreC}.
+% Here is the locking mechanism that prevents a stack overflow via recursive calls to \cmd{\Name} and \cmd{\AKA}. See Sections~\ref{sec:Hooksb}ff.
% \begin{macrocode}
\newif\if@nameauth@Lock
% \end{macrocode}
% \subsection{Hooks}
% \begin{macro}{\NamesFormat}
-% Change typographic formatting of final complete name form in text. See Sections~\ref{sec:formatting} and~\ref{sec:moreC}. Called when |\@nameauth@DoFormattrue| and |\@nameauth@FirstFormattrue.|
+% Post-process ``first'' instance of final complete name form in text. See Sections~\ref{sec:CustomHooks} and~\ref{sec:Hooksa}ff. Called when both |\@nameauth@MainFormat| and |\@nameauth@FirstFormat| are true.
% \begin{macrocode}
\newcommand*{\NamesFormat}{}
% \end{macrocode}
% \end{macro}
% \begin{macro}{\MainNameHook}
% \changes{v2.4}{2016/03/15}{Added}
-% Hook for when a non-formatted main-matter name is printed (Section~\ref{sec:moreC}).
+% Post-process subsequent instance of final complete name form in main-matter text. See Sections~\ref{sec:CustomHooks} and~\ref{sec:Hooksa}ff. Called when |\@nameauth@MainFormat| is true and |\@nameauth@FirstFormat| is false.
% \begin{macrocode}
\newcommand*{\MainNameHook}{}
% \end{macrocode}
% \end{macro}
+% \begin{macro}{\FrontNamesFormat}
+% \changes{v2.5}{2016/04/06}{Added}
+% Post-process ``first'' instance of final complete name form in front-matter text. Called when |\@nameauth@MainFormat| is false and |\@nameauth@FirstFormat| is true.
+% \begin{macrocode}
+\newcommand*{\FrontNamesFormat}{}
+% \end{macrocode}
+% \end{macro}
% \begin{macro}{\FrontNameHook}
% \changes{v2.4}{2016/03/15}{Added}
-% Hook for when a non-formatted front-matter name is printed (Section~\ref{sec:moreC}).
+% Post-process subsequent instance of final complete name form in front-matter text. Called when |\@nameauth@MainFormat| is false and |\@nameauth@FirstFormat| is false.
% \begin{macrocode}
\newcommand*{\FrontNameHook}{}
% \end{macrocode}
% \end{macro}
% \begin{macro}{\NameauthName}
% \changes{v2.2}{2015/12/01}{Added}
-% Hook to create custom naming macros. Usually the three macros below have the same control sequence, but they need not do so if you want something different. See Section~\ref{sec:formatting}. Use at your own risk! Changing these macros basically rewrites this package.
+% Hook to create custom naming macros. Usually the three macros below have the same control sequence, but they need not do so if you want something different. See Section~\ref{sec:NewEngine}. Use at your own risk! Changing these macros basically rewrites this package.
% \begin{macrocode}
\newcommand*{\NameauthName}{\@nameauth@Name}
% \end{macrocode}
% \end{macro}
% \begin{macro}{\NameauthLName}
% \changes{v2.3}{2016/01/05}{Added}
-% Customization hook called after \cmd{\@nameauth@FullName} is set true. See Section~\ref{sec:formatting}.
+% Customization hook called after \cmd{\@nameauth@FullName} is set true. See Section~\ref{sec:NewEngine}.
% \begin{macrocode}
\newcommand*{\NameauthLName}{\@nameauth@Name}
% \end{macrocode}
% \end{macro}
% \begin{macro}{\NameauthFName}
% \changes{v2.2}{2015/12/01}{Added}
-% Customization hook called after \cmd{\@nameauth@FirstName} is set true. See Section~\ref{sec:formatting}.
+% Customization hook called after \cmd{\@nameauth@FirstName} is set true. See Section~\ref{sec:NewEngine}.
% \begin{macrocode}
\newcommand*{\NameauthFName}{\@nameauth@Name}
% \end{macrocode}
@@ -2844,7 +3278,7 @@ Running "make install" installs the files in the local TeX tree.
\newtoks\@nameauth@toksb%
\newtoks\@nameauth@toksc%
% \end{macrocode}
-% These three token registers contain the current values of the name arguments in each line od the \texttt{nameauth} environment.
+% These three token registers contain the current values of the name arguments in each line of the \texttt{nameauth} environment.
% \begin{macrocode}
\newtoks\@nameauth@etoksb%
\newtoks\@nameauth@etoksc%
@@ -2855,8 +3289,9 @@ Running "make install" installs the files in the local TeX tree.
% \begin{macrocode}
\DeclareOption{comma}{\@nameauth@AlwaysCommatrue}
\DeclareOption{nocomma}{\@nameauth@AlwaysCommafalse}
-\DeclareOption{mainmatter}{\@nameauth@DoFormattrue}
-\DeclareOption{frontmatter}{\@nameauth@DoFormatfalse}
+\DeclareOption{mainmatter}{\@nameauth@MainFormattrue}
+\DeclareOption{frontmatter}{\@nameauth@MainFormatfalse}
+\DeclareOption{formatAKA}{\@nameauth@AKAFormattrue}
\DeclareOption{index}{\@nameauth@DoIndextrue}
\DeclareOption{noindex}{\@nameauth@DoIndexfalse}
\DeclareOption{pretag}{\@nameauth@Pretagtrue}
@@ -2881,7 +3316,7 @@ Running "make install" installs the files in the local TeX tree.
pretag,%
normalcaps,%
notreversed,%
- smallcaps}
+ noformat}
\ProcessOptions\relax
% \end{macrocode}
% Now we load the required packages. They facilitate the first/subsequent name uses, the parsing of arguments, and the implementation of starred forms.
@@ -3034,26 +3469,50 @@ Running "make install" installs the files in the local TeX tree.
% \changes{v0.95}{2012/02/17}{Works with \textsf{microtype}}
% \changes{v2.0}{2015/11/11}{One macro instead of two}
% \changes{v2.4}{2016/03/15}{Add hooks for non-formatted names}
-% The following macros format the output of \cmd{\Name}, etc. \cmd{\@nameauth@FmtName} prints names in the body text, either formatted or not. Notice how \cmd{\NamesFormat} (Section~\ref{sec:formatting}) sits between a \cmd{\bgroup} and an \cmd{\egroup} to localize the font change. |@nameauth@AlwaysFormat| will force formatting when possible. \cmd{\@nameauth@InHook} prevents one from calling either \cmd{\Name} or \cmd{\AKA} from within the hook macros.
+% \changes{v2.5}{2016/04/06}{Add final formatting hooks and logic}
+% The dispatcher invokes the appropriate formatting hooks, depending on the Boolean values for first use, subsequent use, and name type. The first set of tests enables or disables formatting within \cmd{\AKA}. The second set of tests handle all the other naming macros in the name and front matter. The hooks have a local scope.
% \begin{macrocode}
\newcommand*{\@nameauth@FmtName}[1]%
{%
- \if@nameauth@AlwaysFormat\@nameauth@FirstFormattrue\fi
- \@nameauth@TestDot{#1}%
- \if@nameauth@DoFormat
- \if@nameauth@FirstFormat
- \bgroup\NamesFormat{#1}\egroup%
+ \if@nameauth@InAKA
+ \if@nameauth@AlwaysFormat
+ \@nameauth@FirstFormattrue%
\else
- \bgroup\MainNameHook{#1}\egroup%
+ \if@nameauth@AKAFormat\else\@nameauth@FirstFormatfalse\fi
+ \fi
+ \@nameauth@TestDot{#1}%
+ \if@nameauth@MainFormat
+ \if@nameauth@FirstFormat
+ \bgroup\NamesFormat{#1}\egroup%
+ \else
+ \bgroup\MainNameHook{#1}\egroup%
+ \fi
+ \else
+ \if@nameauth@FirstFormat
+ \bgroup\FrontNamesFormat{#1}\egroup%
+ \else
+ \bgroup\FrontNameHook{#1}\egroup%
+ \fi
\fi
\else
- \bgroup\FrontNameHook{#1}\egroup%
+ \if@nameauth@AlwaysFormat\@nameauth@FirstFormattrue\fi
+ \@nameauth@TestDot{#1}%
+ \if@nameauth@MainFormat
+ \if@nameauth@FirstFormat
+ \bgroup\NamesFormat{#1}\egroup%
+ \else
+ \bgroup\MainNameHook{#1}\egroup%
+ \fi
+ \else
+ \if@nameauth@FirstFormat
+ \bgroup\FrontNamesFormat{#1}\egroup%
+ \else
+ \bgroup\FrontNameHook{#1}\egroup%
+ \fi
+ \fi
\fi
}
% \end{macrocode}
-% This mechanism relies solely on Boolean values that determine which hook macro to call. Those values are set within \cmd{\@nameauth@name} and \cmd{\AKA,} where they also affect branching. However, the name conditional macros act directly, based on the presence or absence of control sequences determined by the interplay of name arguments, the Boolean values checked above, and the control sequences generated by that interaction.
-%
-% Perhaps a metaphor for this sort of ``double interaction'' could be ``double-clutching'' or, alternately, the difference between a manual and an automatic transmission. From the back-end side, you use the Boolean values and the name conditionals to perform a sort of ``torque matching'' between what goes in to the hook macros and what you want to happen when they complete. From the user side, this happens almost automatically, in a seemingly intuitive way with few additional keystrokes.
% \end{macro}
% \clearpage
%
@@ -3101,7 +3560,8 @@ Running "make install" installs the files in the local TeX tree.
% \changes{v2.1}{2015/11/24}{Isolate Unicode issues}
% \changes{v2.3}{2016/01/05}{Rename as internal macro}
% \changes{v2.4}{2016/03/15}{Define name CS after formatting; add token regs for hooks}
-% \changes{v2.41}{2016/03/17}{no local \cmd{\newtoks}}
+% \changes{v2.41}{2016/03/17}{No local \cmd{\newtoks}}
+% \changes{v2.5}{2016/04/06}{Enable hooks better to query internal values}
% Here is the heart of the package. \Name*[Marc van]{Dongen} provided the basic structure. Parsing, indexing, and formatting are in discrete elements.
% \begin{macrocode}
\newcommandx*\@nameauth@Name[3][1=\@empty, 3=\@empty]%
@@ -3238,14 +3698,12 @@ Running "make install" installs the files in the local TeX tree.
% \end{macrocode}
% If formatting is active, we handle first and subsequent formatting of names in the main matter (code !MN for main matter name). First we handle subsequent uses. We need \cmd{\expandafter} to enable the punctuation detection.
% \begin{macrocode}
- \if@nameauth@DoFormat
+ \if@nameauth@MainFormat
\ifcsname\csb!MN\endcsname
\if@nameauth@FirstName
\@nameauth@FullNamefalse%
- \@nameauth@FirstNamefalse%
\fi
\if@nameauth@FullName
- \@nameauth@FullNamefalse%
\if@nameauth@RevThis
\ex\@nameauth@FmtName\ex{\Reversed}%
\else
@@ -3254,12 +3712,14 @@ Running "make install" installs the files in the local TeX tree.
\else
\ex\@nameauth@FmtName\ex{\PrintShort}%
\fi
+ \@nameauth@FullNamefalse%
+ \@nameauth@FirstNamefalse%
\else
% \end{macrocode}
% Handle first uses.
% \begin{macrocode}
\@nameauth@FirstFormattrue%
- \@nameauth@FullNamefalse%
+ \@nameauth@FullNametrue%
\@nameauth@FirstNamefalse%
\if@nameauth@RevThis
\ex\@nameauth@FmtName\ex{\Reversed}%
@@ -3267,6 +3727,7 @@ Running "make install" installs the files in the local TeX tree.
\ex\@nameauth@FmtName\ex{\SNN}%
\fi
\csgdef{\csb!MN}{}%
+ \@nameauth@FullNamefalse%
\fi
\else
% \end{macrocode}
@@ -3276,10 +3737,8 @@ Running "make install" installs the files in the local TeX tree.
\ifcsname\csb!NF\endcsname
\if@nameauth@FirstName
\@nameauth@FullNamefalse%
- \@nameauth@FirstNamefalse%
\fi
\if@nameauth@FullName
- \@nameauth@FullNamefalse%
\if@nameauth@RevThis
\ex\@nameauth@FmtName\ex{\Reversed}%
\else
@@ -3288,11 +3747,14 @@ Running "make install" installs the files in the local TeX tree.
\else
\ex\@nameauth@FmtName\ex{\PrintShort}%
\fi
+ \@nameauth@FullNamefalse%
+ \@nameauth@FirstNamefalse%
\else
% \end{macrocode}
% Handle first uses.
% \begin{macrocode}
- \@nameauth@FullNamefalse%
+ \@nameauth@FirstFormattrue%
+ \@nameauth@FullNametrue%
\@nameauth@FirstNamefalse%
\if@nameauth@RevThis
\ex\@nameauth@FmtName\ex{\Reversed}%
@@ -3300,6 +3762,7 @@ Running "make install" installs the files in the local TeX tree.
\ex\@nameauth@FmtName\ex{\SNN}%
\fi
\csgdef{\csb!NF}{}%
+ \@nameauth@FullNamefalse%
\fi
\fi
\else
@@ -3316,14 +3779,12 @@ Running "make install" installs the files in the local TeX tree.
% \clearpage\noindent
% If formatting is active, we handle first and subsequent formatting of names in the main matter (code !MN for main matter name). First we handle subsequent uses.
% \begin{macrocode}
- \if@nameauth@DoFormat
+ \if@nameauth@MainFormat
\ifcsname\csbc!MN\endcsname
\if@nameauth@FirstName
\@nameauth@FullNamefalse%
- \@nameauth@FirstNamefalse%
\fi
\if@nameauth@FullName
- \@nameauth@FullNamefalse%
\if@nameauth@RevThis
\ex\@nameauth@FmtName\ex{\ex\argc\ex\space\SNN}%
\else
@@ -3336,12 +3797,14 @@ Running "make install" installs the files in the local TeX tree.
\ex\@nameauth@FmtName\ex{\PrintShort}%
\fi
\fi
+ \@nameauth@FullNamefalse%
+ \@nameauth@FirstNamefalse%
\else
% \end{macrocode}
% Handle first uses.
% \begin{macrocode}
\@nameauth@FirstFormattrue%
- \@nameauth@FullNamefalse%
+ \@nameauth@FullNametrue%
\@nameauth@FirstNamefalse%
\if@nameauth@RevThis
\ex\@nameauth@FmtName\ex{\ex\argc\ex\space\SNN}%
@@ -3349,6 +3812,7 @@ Running "make install" installs the files in the local TeX tree.
\ex\@nameauth@FmtName\ex{\ex\SNN\ex\space\argc}%
\fi
\csgdef{\csbc!MN}{}%
+ \@nameauth@FullNamefalse%
\fi
\else
% \end{macrocode}
@@ -3358,10 +3822,8 @@ Running "make install" installs the files in the local TeX tree.
\ifcsname\csbc!NF\endcsname
\if@nameauth@FirstName
\@nameauth@FullNamefalse%
- \@nameauth@FirstNamefalse%
\fi
\if@nameauth@FullName
- \@nameauth@FullNamefalse%
\if@nameauth@RevThis
\ex\@nameauth@FmtName\ex{\ex\argc\ex\space\SNN}%
\else
@@ -3374,11 +3836,14 @@ Running "make install" installs the files in the local TeX tree.
\ex\@nameauth@FmtName\ex{\PrintShort}%
\fi
\fi
+ \@nameauth@FullNamefalse%
+ \@nameauth@FirstNamefalse%
\else
% \end{macrocode}
% Handle first uses.
% \begin{macrocode}
- \@nameauth@FullNamefalse%
+ \@nameauth@FirstFormattrue%
+ \@nameauth@FullNametrue%
\@nameauth@FirstNamefalse%
\if@nameauth@RevThis
\ex\@nameauth@FmtName\ex{\ex\argc\ex\space\SNN}%
@@ -3386,6 +3851,7 @@ Running "make install" installs the files in the local TeX tree.
\ex\@nameauth@FmtName\ex{\ex\SNN\ex\space\argc}%
\fi
\csgdef{\csbc!NF}{}%
+ \@nameauth@FullNamefalse%
\fi
\fi
\fi
@@ -3417,15 +3883,13 @@ Running "make install" installs the files in the local TeX tree.
% \end{macrocode}
% If formatting is active, we handle first and subsequent formatting of names in the main matter (code !MN for main matter name). First we handle subsequent uses.
% \begin{macrocode}
- \if@nameauth@DoFormat
+ \if@nameauth@MainFormat
\ifcsname\csab!MN\endcsname
\if@nameauth@FirstName
\@nameauth@FullNamefalse%
- \@nameauth@FirstNamefalse%
\let\PrintShort\FNN%
\fi
\if@nameauth@FullName
- \@nameauth@FullNamefalse%
\if@nameauth@RevThis
\ex\@nameauth@FmtName\ex{\ex\SNN\ex\Space\FNN}%
\else
@@ -3434,13 +3898,15 @@ Running "make install" installs the files in the local TeX tree.
\else
\ex\@nameauth@FmtName\ex{\PrintShort}%
\fi
+ \@nameauth@FullNamefalse%
+ \@nameauth@FirstNamefalse%
\else
% \end{macrocode}
% \clearpage\noindent
% Handle first uses.
% \begin{macrocode}
\@nameauth@FirstFormattrue%
- \@nameauth@FullNamefalse%
+ \@nameauth@FullNametrue%
\@nameauth@FirstNamefalse%
\if@nameauth@RevThis
\ex\@nameauth@FmtName\ex{\ex\SNN\ex\Space\FNN}%
@@ -3448,6 +3914,7 @@ Running "make install" installs the files in the local TeX tree.
\ex\@nameauth@FmtName\ex{\ex\FNN\ex\space\SNN}%
\fi
\csgdef{\csab!MN}{}%
+ \@nameauth@FullNamefalse%
\fi
\else
% \end{macrocode}
@@ -3456,11 +3923,9 @@ Running "make install" installs the files in the local TeX tree.
\ifcsname\csab!NF\endcsname
\if@nameauth@FirstName
\@nameauth@FullNamefalse%
- \@nameauth@FirstNamefalse%
\let\PrintShort\FNN%
\fi
\if@nameauth@FullName
- \@nameauth@FullNamefalse%
\if@nameauth@RevThis
\ex\@nameauth@FmtName\ex{\ex\SNN\ex\Space\FNN}%
\else
@@ -3469,11 +3934,14 @@ Running "make install" installs the files in the local TeX tree.
\else
\ex\@nameauth@FmtName\ex{\PrintShort}%
\fi
+ \@nameauth@FullNamefalse%
+ \@nameauth@FirstNamefalse%
\else
% \end{macrocode}
% Handle first uses.
% \begin{macrocode}
- \@nameauth@FullNamefalse%
+ \@nameauth@FirstFormattrue%
+ \@nameauth@FullNametrue%
\@nameauth@FirstNamefalse%
\if@nameauth@RevThis
\ex\@nameauth@FmtName\ex{\ex\SNN\ex\Space\FNN}%
@@ -3481,6 +3949,7 @@ Running "make install" installs the files in the local TeX tree.
\ex\@nameauth@FmtName\ex{\ex\FNN\ex\space\SNN}%
\fi
\csgdef{\csab!NF}{}%
+ \@nameauth@FullNamefalse%
\fi
\fi
\fi
@@ -3628,14 +4097,14 @@ Running "make install" installs the files in the local TeX tree.
% \begin{macro}{\NamesInactive}
% Switch to the ``non-formatted'' species of names.
% \begin{macrocode}
-\newcommand*{\NamesInactive}{\@nameauth@DoFormatfalse}
+\newcommand*{\NamesInactive}{\@nameauth@MainFormatfalse}
% \end{macrocode}
% \end{macro}
%
% \begin{macro}{\NamesActive}
% Switch to the ``formatted'' species of names.
% \begin{macrocode}
-\newcommand*{\NamesActive}{\@nameauth@DoFormattrue}
+\newcommand*{\NamesActive}{\@nameauth@MainFormattrue}
% \end{macrocode}
% \end{macro}
%
@@ -3729,7 +4198,7 @@ Running "make install" installs the files in the local TeX tree.
% \changes{v2.1}{2015/11/24}{Isolate Unicode issues}
% \changes{v2.3}{2016/01/05}{Expand starred mode}
% \changes{v2.4}{2016/03/15}{Define name CS after formatting; add token regs for hooks}
-% \changes{v2.41}{2016/03/17}{no local \cmd{\newtoks}}
+% \changes{v2.41}{2016/03/17}{No local \cmd{\newtoks}}
% \cmd{\AKA} prints an alternate name and creates index cross-references. It prevents multiple generation of cross-references and suppresses double periods.
% \begin{macrocode}
\newcommandx*\AKA[5][1=\@empty, 3=\@empty, 5=\@empty]%
@@ -3899,6 +4368,7 @@ Running "make install" installs the files in the local TeX tree.
\protected@edef\Space{,\nobreakspace}%
\fi
\fi
+ \ifcsname\csd!PN\endcsname\else\@nameauth@FirstFormattrue\fi
\if@nameauth@RevThis
\ex\@nameauth@FmtName\ex{\Reversed}%
\else
@@ -3947,6 +4417,7 @@ Running "make install" installs the files in the local TeX tree.
\protected@edef\Space{,\nobreakspace}%
\fi
\fi
+ \ifcsname\csde!PN\endcsname\else\@nameauth@FirstFormattrue\fi
\if@nameauth@AltAKA
\ex\@nameauth@FmtName\ex{\arge}%
\else
@@ -4019,6 +4490,7 @@ Running "make install" installs the files in the local TeX tree.
\else
\let\FNN\arge%
\fi
+ \ifcsname\cscd!PN\endcsname\else\@nameauth@FirstFormattrue\fi
\if@nameauth@AltAKA
\ex\@nameauth@FmtName\ex{\FNN}%
\else
@@ -4672,12 +5144,12 @@ Running "make install" installs the files in the local TeX tree.
\fi
\fi
% \end{macrocode}
-% Now we parse the arguments, undefining the control sequences either locally by section type or globally. |@nameauth@LocalNames| toggles the local or global behavior, while |@nameauth@DoFormat| selects the type of name.
+% Now we parse the arguments, undefining the control sequences either locally by section type or globally. |@nameauth@LocalNames| toggles the local or global behavior, while |@nameauth@MainFormat| selects the type of name.
% \begin{macrocode}
\ifx\testa\@empty
\ifx\testc\@empty
\if@nameauth@LocalNames
- \if@nameauth@DoFormat
+ \if@nameauth@MainFormat
\global\csundef{\csb!MN}%
\else
\global\csundef{\csb!NF}%
@@ -4688,7 +5160,7 @@ Running "make install" installs the files in the local TeX tree.
\fi
\else
\if@nameauth@LocalNames
- \if@nameauth@DoFormat
+ \if@nameauth@MainFormat
\global\csundef{\csbc!MN}%
\else
\global\csundef{\csbc!NF}%
@@ -4700,7 +5172,7 @@ Running "make install" installs the files in the local TeX tree.
\fi
\else
\if@nameauth@LocalNames
- \if@nameauth@DoFormat
+ \if@nameauth@MainFormat
\global\csundef{\csab!MN}%
\else
\global\csundef{\csab!NF}%
@@ -4744,12 +5216,12 @@ Running "make install" installs the files in the local TeX tree.
\fi
\fi
% \end{macrocode}
-% Now we parse the arguments, defining the control sequences either locally by section type or globally. |@nameauth@LocalNames| toggles the local or global behavior, while |@nameauth@DoFormat| selects the type of name.
+% Now we parse the arguments, defining the control sequences either locally by section type or globally. |@nameauth@LocalNames| toggles the local or global behavior, while |@nameauth@MainFormat| selects the type of name.
% \begin{macrocode}
\ifx\testa\@empty
\ifx\testc\@empty
\if@nameauth@LocalNames
- \if@nameauth@DoFormat
+ \if@nameauth@MainFormat
\csgdef{\csb!MN}{}%
\else
\csgdef{\csb!NF}{}%
@@ -4760,7 +5232,7 @@ Running "make install" installs the files in the local TeX tree.
\fi
\else
\if@nameauth@LocalNames
- \if@nameauth@DoFormat
+ \if@nameauth@MainFormat
\csgdef{\csbc!MN}{}%
\else
\csgdef{\csbc!NF}{}%
@@ -4775,7 +5247,7 @@ Running "make install" installs the files in the local TeX tree.
% \begin{macrocode}
\else
\if@nameauth@LocalNames
- \if@nameauth@DoFormat
+ \if@nameauth@MainFormat
\csgdef{\csab!MN}{}%
\else
\csgdef{\csab!NF}{}%
@@ -4793,7 +5265,7 @@ Running "make install" installs the files in the local TeX tree.
% \changes{v1.6}{2013/03/10}{Added}
% \changes{v2.0}{2015/11/11}{Redesigned argument handling}
% \changes{v2.11}{2015/11/29}{Bugfix}
-% \changes{v2.41}{2016/03/17}{no local \cmd{\newtoks}}
+% \changes{v2.41}{2016/03/17}{No local \cmd{\newtoks}}
% The |nameauth| environment provides a means to implement shorthand references to names in a document.
% \begin{macrocode}
\newenvironment{nameauth}{%
diff --git a/Master/texmf-dist/source/latex/nameauth/nameauth.ins b/Master/texmf-dist/source/latex/nameauth/nameauth.ins
index 1937e05f051..c14d2f2cb10 100644
--- a/Master/texmf-dist/source/latex/nameauth/nameauth.ins
+++ b/Master/texmf-dist/source/latex/nameauth/nameauth.ins
@@ -38,7 +38,7 @@ http://www.latex-project.org/lppl.txt
This work is "maintained" (as per LPPL maintenance status) by
Charles P. Schaum.
-This work consists of the file nameauth.dtx and a Makefile.
+This work consists of the files nameauth.dtx, examples.tex, and a Makefile.
Running "make" generates the derived files README, nameauth.pdf and nameauth.sty.
Running "make inst" installs the files in the user's TeX tree.
Running "make install" installs the files in the local TeX tree.
@@ -63,7 +63,7 @@ Running "make install" installs the files in the local TeX tree.
%% This work is "maintained" (as per LPPL maintenance status) by
%% Charles P. Schaum.
%%
-%% This work consists of the file nameauth.dtx and a Makefile.
+%% This work consists of the files nameauth.dtx, examples.tex, and a Makefile.
%% Running "make" generates the derived files README, nameauth.pdf and nameauth.sty.
%% Running "make inst" installs the files in the user's TeX tree.
%% Running "make install" installs the files in the local TeX tree.
diff --git a/Master/texmf-dist/tex/latex/nameauth/nameauth.sty b/Master/texmf-dist/tex/latex/nameauth/nameauth.sty
index d5e44e32cb6..07a991732b0 100644
--- a/Master/texmf-dist/tex/latex/nameauth/nameauth.sty
+++ b/Master/texmf-dist/tex/latex/nameauth/nameauth.sty
@@ -14,10 +14,11 @@
%%
\NeedsTeXFormat{LaTeX2e}[1999/12/01]
\ProvidesPackage{nameauth}
- [2016/03/18 v2.42 Name authority mechanism for consistency in text and index]
+ [2016/04/06 v2.5 Name authority mechanism for consistency in text and index]
\newif\if@nameauth@AlwaysComma
\newif\if@nameauth@ShowComma
-\newif\if@nameauth@DoFormat
+\newif\if@nameauth@MainFormat
+\newif\if@nameauth@AKAFormat
\newif\if@nameauth@LocalNames
\newif\if@nameauth@DoIndex
\newif\if@nameauth@Pretag
@@ -41,6 +42,7 @@
\newif\if@nameauth@Lock
\newcommand*{\NamesFormat}{}
\newcommand*{\MainNameHook}{}
+\newcommand*{\FrontNamesFormat}{}
\newcommand*{\FrontNameHook}{}
\newcommand*{\NameauthName}{\@nameauth@Name}
\newcommand*{\NameauthLName}{\@nameauth@Name}
@@ -53,8 +55,9 @@
\newtoks\@nameauth@etoksd%
\DeclareOption{comma}{\@nameauth@AlwaysCommatrue}
\DeclareOption{nocomma}{\@nameauth@AlwaysCommafalse}
-\DeclareOption{mainmatter}{\@nameauth@DoFormattrue}
-\DeclareOption{frontmatter}{\@nameauth@DoFormatfalse}
+\DeclareOption{mainmatter}{\@nameauth@MainFormattrue}
+\DeclareOption{frontmatter}{\@nameauth@MainFormatfalse}
+\DeclareOption{formatAKA}{\@nameauth@AKAFormattrue}
\DeclareOption{index}{\@nameauth@DoIndextrue}
\DeclareOption{noindex}{\@nameauth@DoIndexfalse}
\DeclareOption{pretag}{\@nameauth@Pretagtrue}
@@ -79,7 +82,7 @@
pretag,%
normalcaps,%
notreversed,%
- smallcaps}
+ noformat}
\ProcessOptions\relax
\RequirePackage{etoolbox}
\RequirePackage{ifluatex}
@@ -129,16 +132,42 @@
{\let\@period=.\ifx\@token\@period\expandafter\@gobble \fi}
\newcommand*{\@nameauth@FmtName}[1]%
{%
- \if@nameauth@AlwaysFormat\@nameauth@FirstFormattrue\fi
- \@nameauth@TestDot{#1}%
- \if@nameauth@DoFormat
- \if@nameauth@FirstFormat
- \bgroup\NamesFormat{#1}\egroup%
+ \if@nameauth@InAKA
+ \if@nameauth@AlwaysFormat
+ \@nameauth@FirstFormattrue%
\else
- \bgroup\MainNameHook{#1}\egroup%
+ \if@nameauth@AKAFormat\else\@nameauth@FirstFormatfalse\fi
+ \fi
+ \@nameauth@TestDot{#1}%
+ \if@nameauth@MainFormat
+ \if@nameauth@FirstFormat
+ \bgroup\NamesFormat{#1}\egroup%
+ \else
+ \bgroup\MainNameHook{#1}\egroup%
+ \fi
+ \else
+ \if@nameauth@FirstFormat
+ \bgroup\FrontNamesFormat{#1}\egroup%
+ \else
+ \bgroup\FrontNameHook{#1}\egroup%
+ \fi
\fi
\else
- \bgroup\FrontNameHook{#1}\egroup%
+ \if@nameauth@AlwaysFormat\@nameauth@FirstFormattrue\fi
+ \@nameauth@TestDot{#1}%
+ \if@nameauth@MainFormat
+ \if@nameauth@FirstFormat
+ \bgroup\NamesFormat{#1}\egroup%
+ \else
+ \bgroup\MainNameHook{#1}\egroup%
+ \fi
+ \else
+ \if@nameauth@FirstFormat
+ \bgroup\FrontNamesFormat{#1}\egroup%
+ \else
+ \bgroup\FrontNameHook{#1}\egroup%
+ \fi
+ \fi
\fi
}
\newcommand*\@nameauth@Actual{@}
@@ -266,14 +295,12 @@
\else
\@nameauth@Index{\csb}{\IndexSNN}%
\fi
- \if@nameauth@DoFormat
+ \if@nameauth@MainFormat
\ifcsname\csb!MN\endcsname
\if@nameauth@FirstName
\@nameauth@FullNamefalse%
- \@nameauth@FirstNamefalse%
\fi
\if@nameauth@FullName
- \@nameauth@FullNamefalse%
\if@nameauth@RevThis
\ex\@nameauth@FmtName\ex{\Reversed}%
\else
@@ -282,9 +309,11 @@
\else
\ex\@nameauth@FmtName\ex{\PrintShort}%
\fi
+ \@nameauth@FullNamefalse%
+ \@nameauth@FirstNamefalse%
\else
\@nameauth@FirstFormattrue%
- \@nameauth@FullNamefalse%
+ \@nameauth@FullNametrue%
\@nameauth@FirstNamefalse%
\if@nameauth@RevThis
\ex\@nameauth@FmtName\ex{\Reversed}%
@@ -292,15 +321,14 @@
\ex\@nameauth@FmtName\ex{\SNN}%
\fi
\csgdef{\csb!MN}{}%
+ \@nameauth@FullNamefalse%
\fi
\else
\ifcsname\csb!NF\endcsname
\if@nameauth@FirstName
\@nameauth@FullNamefalse%
- \@nameauth@FirstNamefalse%
\fi
\if@nameauth@FullName
- \@nameauth@FullNamefalse%
\if@nameauth@RevThis
\ex\@nameauth@FmtName\ex{\Reversed}%
\else
@@ -309,15 +337,19 @@
\else
\ex\@nameauth@FmtName\ex{\PrintShort}%
\fi
- \else
\@nameauth@FullNamefalse%
\@nameauth@FirstNamefalse%
+ \else
+ \@nameauth@FirstFormattrue%
+ \@nameauth@FullNametrue%
+ \@nameauth@FirstNamefalse%
\if@nameauth@RevThis
\ex\@nameauth@FmtName\ex{\Reversed}%
\else
\ex\@nameauth@FmtName\ex{\SNN}%
\fi
\csgdef{\csb!NF}{}%
+ \@nameauth@FullNamefalse%
\fi
\fi
\else
@@ -327,14 +359,12 @@
\else
\@nameauth@Index{\csbc}{\IndexSNN\ISpace\argc}%
\fi
- \if@nameauth@DoFormat
+ \if@nameauth@MainFormat
\ifcsname\csbc!MN\endcsname
\if@nameauth@FirstName
\@nameauth@FullNamefalse%
- \@nameauth@FirstNamefalse%
\fi
\if@nameauth@FullName
- \@nameauth@FullNamefalse%
\if@nameauth@RevThis
\ex\@nameauth@FmtName\ex{\ex\argc\ex\space\SNN}%
\else
@@ -347,9 +377,11 @@
\ex\@nameauth@FmtName\ex{\PrintShort}%
\fi
\fi
+ \@nameauth@FullNamefalse%
+ \@nameauth@FirstNamefalse%
\else
\@nameauth@FirstFormattrue%
- \@nameauth@FullNamefalse%
+ \@nameauth@FullNametrue%
\@nameauth@FirstNamefalse%
\if@nameauth@RevThis
\ex\@nameauth@FmtName\ex{\ex\argc\ex\space\SNN}%
@@ -357,15 +389,14 @@
\ex\@nameauth@FmtName\ex{\ex\SNN\ex\space\argc}%
\fi
\csgdef{\csbc!MN}{}%
+ \@nameauth@FullNamefalse%
\fi
\else
\ifcsname\csbc!NF\endcsname
\if@nameauth@FirstName
\@nameauth@FullNamefalse%
- \@nameauth@FirstNamefalse%
\fi
\if@nameauth@FullName
- \@nameauth@FullNamefalse%
\if@nameauth@RevThis
\ex\@nameauth@FmtName\ex{\ex\argc\ex\space\SNN}%
\else
@@ -378,15 +409,19 @@
\ex\@nameauth@FmtName\ex{\PrintShort}%
\fi
\fi
- \else
\@nameauth@FullNamefalse%
\@nameauth@FirstNamefalse%
+ \else
+ \@nameauth@FirstFormattrue%
+ \@nameauth@FullNametrue%
+ \@nameauth@FirstNamefalse%
\if@nameauth@RevThis
\ex\@nameauth@FmtName\ex{\ex\argc\ex\space\SNN}%
\else
\ex\@nameauth@FmtName\ex{\ex\SNN\ex\space\argc}%
\fi
\csgdef{\csbc!NF}{}%
+ \@nameauth@FullNamefalse%
\fi
\fi
\fi
@@ -411,15 +446,13 @@
\@nameauth@Index{\csab}{\IndexShort,\space\arga,\space\Suff}%
\fi
\fi
- \if@nameauth@DoFormat
+ \if@nameauth@MainFormat
\ifcsname\csab!MN\endcsname
\if@nameauth@FirstName
\@nameauth@FullNamefalse%
- \@nameauth@FirstNamefalse%
\let\PrintShort\FNN%
\fi
\if@nameauth@FullName
- \@nameauth@FullNamefalse%
\if@nameauth@RevThis
\ex\@nameauth@FmtName\ex{\ex\SNN\ex\Space\FNN}%
\else
@@ -428,9 +461,11 @@
\else
\ex\@nameauth@FmtName\ex{\PrintShort}%
\fi
+ \@nameauth@FullNamefalse%
+ \@nameauth@FirstNamefalse%
\else
\@nameauth@FirstFormattrue%
- \@nameauth@FullNamefalse%
+ \@nameauth@FullNametrue%
\@nameauth@FirstNamefalse%
\if@nameauth@RevThis
\ex\@nameauth@FmtName\ex{\ex\SNN\ex\Space\FNN}%
@@ -438,16 +473,15 @@
\ex\@nameauth@FmtName\ex{\ex\FNN\ex\space\SNN}%
\fi
\csgdef{\csab!MN}{}%
+ \@nameauth@FullNamefalse%
\fi
\else
\ifcsname\csab!NF\endcsname
\if@nameauth@FirstName
\@nameauth@FullNamefalse%
- \@nameauth@FirstNamefalse%
\let\PrintShort\FNN%
\fi
\if@nameauth@FullName
- \@nameauth@FullNamefalse%
\if@nameauth@RevThis
\ex\@nameauth@FmtName\ex{\ex\SNN\ex\Space\FNN}%
\else
@@ -456,15 +490,19 @@
\else
\ex\@nameauth@FmtName\ex{\PrintShort}%
\fi
- \else
\@nameauth@FullNamefalse%
\@nameauth@FirstNamefalse%
+ \else
+ \@nameauth@FirstFormattrue%
+ \@nameauth@FullNametrue%
+ \@nameauth@FirstNamefalse%
\if@nameauth@RevThis
\ex\@nameauth@FmtName\ex{\ex\SNN\ex\Space\FNN}%
\else
\ex\@nameauth@FmtName\ex{\ex\FNN\ex\space\SNN}%
\fi
\csgdef{\csab!NF}{}%
+ \@nameauth@FullNamefalse%
\fi
\fi
\fi
@@ -497,8 +535,8 @@
{\@nameauth@RevAlltrue\@nameauth@RevAllCommatrue}
\newcommand*{\ShowComma}{\@nameauth@ShowCommatrue}
\newcommand*{\KeepAffix}{\@nameauth@NBSPtrue}
-\newcommand*{\NamesInactive}{\@nameauth@DoFormatfalse}
-\newcommand*{\NamesActive}{\@nameauth@DoFormattrue}
+\newcommand*{\NamesInactive}{\@nameauth@MainFormatfalse}
+\newcommand*{\NamesActive}{\@nameauth@MainFormattrue}
\newcommand*\LocalNames{\global\@nameauth@LocalNamestrue}
\newcommand*\GlobalNames{\global\@nameauth@LocalNamesfalse}
\newcommand*{\IndexInactive}{\@nameauth@DoIndexfalse}
@@ -645,6 +683,7 @@
\protected@edef\Space{,\nobreakspace}%
\fi
\fi
+ \ifcsname\csd!PN\endcsname\else\@nameauth@FirstFormattrue\fi
\if@nameauth@RevThis
\ex\@nameauth@FmtName\ex{\Reversed}%
\else
@@ -686,6 +725,7 @@
\protected@edef\Space{,\nobreakspace}%
\fi
\fi
+ \ifcsname\csde!PN\endcsname\else\@nameauth@FirstFormattrue\fi
\if@nameauth@AltAKA
\ex\@nameauth@FmtName\ex{\arge}%
\else
@@ -750,6 +790,7 @@
\else
\let\FNN\arge%
\fi
+ \ifcsname\cscd!PN\endcsname\else\@nameauth@FirstFormattrue\fi
\if@nameauth@AltAKA
\ex\@nameauth@FmtName\ex{\FNN}%
\else
@@ -1218,7 +1259,7 @@
\ifx\testa\@empty
\ifx\testc\@empty
\if@nameauth@LocalNames
- \if@nameauth@DoFormat
+ \if@nameauth@MainFormat
\global\csundef{\csb!MN}%
\else
\global\csundef{\csb!NF}%
@@ -1229,7 +1270,7 @@
\fi
\else
\if@nameauth@LocalNames
- \if@nameauth@DoFormat
+ \if@nameauth@MainFormat
\global\csundef{\csbc!MN}%
\else
\global\csundef{\csbc!NF}%
@@ -1241,7 +1282,7 @@
\fi
\else
\if@nameauth@LocalNames
- \if@nameauth@DoFormat
+ \if@nameauth@MainFormat
\global\csundef{\csab!MN}%
\else
\global\csundef{\csab!NF}%
@@ -1272,7 +1313,7 @@
\ifx\testa\@empty
\ifx\testc\@empty
\if@nameauth@LocalNames
- \if@nameauth@DoFormat
+ \if@nameauth@MainFormat
\csgdef{\csb!MN}{}%
\else
\csgdef{\csb!NF}{}%
@@ -1283,7 +1324,7 @@
\fi
\else
\if@nameauth@LocalNames
- \if@nameauth@DoFormat
+ \if@nameauth@MainFormat
\csgdef{\csbc!MN}{}%
\else
\csgdef{\csbc!NF}{}%
@@ -1295,7 +1336,7 @@
\fi
\else
\if@nameauth@LocalNames
- \if@nameauth@DoFormat
+ \if@nameauth@MainFormat
\csgdef{\csab!MN}{}%
\else
\csgdef{\csab!NF}{}%
@@ -1407,7 +1448,7 @@
%% This work is "maintained" (as per LPPL maintenance status) by
%% Charles P. Schaum.
%%
-%% This work consists of the file nameauth.dtx and a Makefile.
+%% This work consists of the files nameauth.dtx, examples.tex, and a Makefile.
%% Running "make" generates the derived files README, nameauth.pdf and nameauth.sty.
%% Running "make inst" installs the files in the user's TeX tree.
%% Running "make install" installs the files in the local TeX tree.
generated by cgit v1.2.3 (git 2.39.1) at 2024-12-27 20:19:15 +0000