texlive[53863] Master/texmf-dist: nameauth (21feb20)
commits+karl at tug.org
commits+karl at tug.org
Fri Feb 21 23:56:15 CET 2020
Revision: 53863
http://tug.org/svn/texlive?view=revision&revision=53863
Author: karl
Date: 2020-02-21 23:56:14 +0100 (Fri, 21 Feb 2020)
Log Message:
-----------
nameauth (21feb20)
Modified Paths:
--------------
trunk/Master/texmf-dist/doc/latex/nameauth/README
trunk/Master/texmf-dist/doc/latex/nameauth/README.txt
trunk/Master/texmf-dist/doc/latex/nameauth/examples.tex
trunk/Master/texmf-dist/doc/latex/nameauth/nameauth.pdf
trunk/Master/texmf-dist/source/latex/nameauth/nameauth.dtx
trunk/Master/texmf-dist/source/latex/nameauth/nameauth.ins
trunk/Master/texmf-dist/tex/latex/nameauth/nameauth.sty
Added Paths:
-----------
trunk/Master/texmf-dist/source/latex/nameauth/Makefile
Removed Paths:
-------------
trunk/Master/texmf-dist/doc/latex/nameauth/Makefile
trunk/Master/texmf-dist/doc/latex/nameauth/nameauth.hd
Deleted: trunk/Master/texmf-dist/doc/latex/nameauth/Makefile
===================================================================
--- trunk/Master/texmf-dist/doc/latex/nameauth/Makefile 2020-02-21 22:55:44 UTC (rev 53862)
+++ trunk/Master/texmf-dist/doc/latex/nameauth/Makefile 2020-02-21 22:56:14 UTC (rev 53863)
@@ -1,42 +0,0 @@
-NAME = nameauth
-ENGINE ?= pdflatex
-# On the command line:
-# make ENGINE=latex
-# make ENGINE=xelatex
-# make ENGINE=lualatex
-SHELL = bash
-PWD = $(shell pwd)
-VERS = $(shell ltxfileinfo -v $(NAME).dtx|sed -e 's/^v//')
-LOCAL = $(shell kpsewhich --var-value TEXMFLOCAL)
-UTREE = $(shell kpsewhich --var-value TEXMFHOME)
-all: $(NAME).pdf
- test -e README.txt && mv README.txt README || exit 0
-$(NAME).pdf: $(NAME).dtx
- $(ENGINE) -shell-escape -recorder -interaction=batchmode $(NAME).dtx >/dev/null
- $(ENGINE) --recorder --interaction=nonstopmode $(NAME).dtx > /dev/null
- if [ -f $(NAME).glo ]; then makeindex -q -s gglo.ist -o $(NAME).gls $(NAME).glo; fi
- if [ -f $(NAME).idx ]; then makeindex -q -s gind.ist -o $(NAME).ind $(NAME).idx; fi
- $(ENGINE) --recorder --interaction=nonstopmode $(NAME).dtx > /dev/null
- $(ENGINE) --recorder --interaction=nonstopmode $(NAME).dtx > /dev/null
-clean:
- rm -f $(NAME).{aux,fls,glo,gls,hd,idx,ilg,ind,ins,log,out,toc} README.txt
-distclean: clean
- rm -f $(NAME).{dvi,pdf,sty,synctex.gz} README
-inst: all
- mkdir -p $(UTREE)/{tex,source,doc}/latex/$(NAME)
- cp $(NAME).dtx $(UTREE)/source/latex/$(NAME)
- 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,examples.tex,Makefile,$(NAME).{pdf,dtx}}
- rm $(NAME)
Modified: trunk/Master/texmf-dist/doc/latex/nameauth/README
===================================================================
--- trunk/Master/texmf-dist/doc/latex/nameauth/README 2020-02-21 22:55:44 UTC (rev 53862)
+++ trunk/Master/texmf-dist/doc/latex/nameauth/README 2020-02-21 22:56:14 UTC (rev 53863)
@@ -2,7 +2,7 @@
--------:| ----------------------------------------------------------------
nameauth:| Name authority mechanism for consistency in text and index
Author:| Charles P. Schaum
- E-mail:| charles dot schaum at comcast dot net
+ E-mail:| charles dot schaum at comcast.net
License:| Released under the LaTeX Project Public License 1.3c or later
See:| http://www.latex-project.org/lppl.txt
@@ -29,15 +29,9 @@
Unpack nameauth.zip in an appropriate directory.
-Note that the instructions below assume that you are using a kind of
-Unix, BSD, Linux, Mac, or Cygwin under Microsoft Windows. If you have
-a different operating environment, you will need to modify these
-instructions to your own needs. Please be aware that this package is
-designed to be stored in a UTF-8 encoded text file and built in a
-Unicode-capable environment.
+If you have a make utility compatible with GNU make, either in
+GNU/Linux, a BSD variant, OSX, or Cygwin in Windows you can type
-If you have a make utility compatible with GNU make you can type
-
make inst
to install the package into your $TEXMFHOME tree or
@@ -45,54 +39,88 @@
make install
to install the package into your $TEXMFLOCAL tree for all users.
+The latter requires sudo privileges.
-Manually, you can generate the package files. First you generate the
-installer driver, README, and style files, with a preliminary PDF:
+Other useful targets include:
+(release process)
+
+make release The default target, same as just ``make''.
+
+make clean Removes all intermediate files. Left are
+the files listed above plus nameauth.sty.
+
+make distclean Leave only nameauth.dtx, examples.tex,
+and Makefile.
+
+make zip Generate a zip file ready for distribution.
+
+(testing process)
+
+make testing Release files, plus compiles examples.tex.
+
+make release ENGINE=<command>
+Here, <command> can be pdflatex (default),
+xelatex, lualatex, dvilualatex, or latex.
+
+make testing ENGINE=<command> See above.
+
+It is not necessary, however, to use GNU make. One can generate
+the package files manually. Since the files nameauth.ins and README.txt
+are contained in the .dtx file itself, the first step is to generate
+the installer driver nameauth.ins, plus the file README.txt, which will
+also trigger the extraction of nameauth.sty and produce the first pass of
+the package documentation nameauth.pdf:
+
pdflatex -shell-escape -recorder -interaction=batchmode nameauth.dtx
-Next you generate the PDF with a table of contents and all cross-references
-validated, so that the index entries will not move:
+Next one adds a table of contents and all cross-references, this also
+should finalize page numbers for glossary and index input files:
pdflatex --recorder --interaction=nonstopmode nameauth.dtx
-The next commands generate the glossary/index and final pdf file
+The next commands generate the glossary/index output files:
makeindex -q -s gglo.ist -o nameauth.gls nameauth.glo
makeindex -q -s gind.ist -o nameauth.ind nameauth.idx
+
+The final two commands integrate the glossary (changes) and index:
+
pdflatex --recorder --interaction=nonstopmode nameauth.dtx
pdflatex --recorder --interaction=nonstopmode nameauth.dtx
-Normally you create the following manual installation directories for user:
+Now one can either keep README.txt or rename it to README, e.g.:
+mv README.txt README
+
+Normally one creates the following directories for a user:
+
$TEXMFHOME/source/latex/nameauth dtx file
$TEXMFHOME/tex/latex/nameauth sty file
$TEXMFHOME/doc/latex/nameauth pdf file, README, examples.tex
-and you create the following manual installation directories for local site:
+and creates the following directories for the local site:
$TEXMFLOCAL/source/latex/nameauth dtx file
$TEXMFLOCAL/tex/latex/nameauth sty file
$TEXMFLOCAL/doc/latex/nameauth pdf file, README, examples.tex
-The above environment variables often are /usr/local/texlive/texmf-local and
-~/texmf.
+The above environment variables often are /usr/local/texlive/texmf-local
+and ~/texmf.
-The make process normally renames the README.txt file created from the dtx file
-to just README by using mv (move/rename utility in the *nix userland). Windows
-distributions of TeX and LaTeX often keep the txt file as well.
+The make process normally renames the README.txt file created from the
+dtx file to just README by using mv (move / rename utility in the *nix
+userland). Windows distributions of TeX and LaTeX often keep the txt file
+because of using file extensions instead of ``magic numbers'' to identify
+files.
-Run mktexlsr with the appropriate level of permissions to complete the install.
+Run mktexlsr with the appropriate level of permissions to complete the
+install.
Testing notes:
-This package and documentation work and build with latex, lualatex, pdflatex,
-and xelatex. It can be used with makeindex/texindy.
+See the nameauth manual.
-For testing, the make file permits one to change the typesetting engine
-on the command line. The default is to build the package and documentation
-with pdflatex. See the make file for details.
-
License
This material is subject to the LaTeX Project Public License:
Modified: trunk/Master/texmf-dist/doc/latex/nameauth/README.txt
===================================================================
--- trunk/Master/texmf-dist/doc/latex/nameauth/README.txt 2020-02-21 22:55:44 UTC (rev 53862)
+++ trunk/Master/texmf-dist/doc/latex/nameauth/README.txt 2020-02-21 22:56:14 UTC (rev 53863)
@@ -2,7 +2,7 @@
--------:| ----------------------------------------------------------------
nameauth:| Name authority mechanism for consistency in text and index
Author:| Charles P. Schaum
- E-mail:| charles dot schaum at comcast dot net
+ E-mail:| charles dot schaum at comcast.net
License:| Released under the LaTeX Project Public License 1.3c or later
See:| http://www.latex-project.org/lppl.txt
@@ -29,15 +29,9 @@
Unpack nameauth.zip in an appropriate directory.
-Note that the instructions below assume that you are using a kind of
-Unix, BSD, Linux, Mac, or Cygwin under Microsoft Windows. If you have
-a different operating environment, you will need to modify these
-instructions to your own needs. Please be aware that this package is
-designed to be stored in a UTF-8 encoded text file and built in a
-Unicode-capable environment.
+If you have a make utility compatible with GNU make, either in
+GNU/Linux, a BSD variant, OSX, or Cygwin in Windows you can type
-If you have a make utility compatible with GNU make you can type
-
make inst
to install the package into your $TEXMFHOME tree or
@@ -45,54 +39,88 @@
make install
to install the package into your $TEXMFLOCAL tree for all users.
+The latter requires sudo privileges.
-Manually, you can generate the package files. First you generate the
-installer driver, README, and style files, with a preliminary PDF:
+Other useful targets include:
+(release process)
+
+make release The default target, same as just ``make''.
+
+make clean Removes all intermediate files. Left are
+the files listed above plus nameauth.sty.
+
+make distclean Leave only nameauth.dtx, examples.tex,
+and Makefile.
+
+make zip Generate a zip file ready for distribution.
+
+(testing process)
+
+make testing Release files, plus compiles examples.tex.
+
+make release ENGINE=<command>
+Here, <command> can be pdflatex (default),
+xelatex, lualatex, dvilualatex, or latex.
+
+make testing ENGINE=<command> See above.
+
+It is not necessary, however, to use GNU make. One can generate
+the package files manually. Since the files nameauth.ins and README.txt
+are contained in the .dtx file itself, the first step is to generate
+the installer driver nameauth.ins, plus the file README.txt, which will
+also trigger the extraction of nameauth.sty and produce the first pass of
+the package documentation nameauth.pdf:
+
pdflatex -shell-escape -recorder -interaction=batchmode nameauth.dtx
-Next you generate the PDF with a table of contents and all cross-references
-validated, so that the index entries will not move:
+Next one adds a table of contents and all cross-references, this also
+should finalize page numbers for glossary and index input files:
pdflatex --recorder --interaction=nonstopmode nameauth.dtx
-The next commands generate the glossary/index and final pdf file
+The next commands generate the glossary/index output files:
makeindex -q -s gglo.ist -o nameauth.gls nameauth.glo
makeindex -q -s gind.ist -o nameauth.ind nameauth.idx
+
+The final two commands integrate the glossary (changes) and index:
+
pdflatex --recorder --interaction=nonstopmode nameauth.dtx
pdflatex --recorder --interaction=nonstopmode nameauth.dtx
-Normally you create the following manual installation directories for user:
+Now one can either keep README.txt or rename it to README, e.g.:
+mv README.txt README
+
+Normally one creates the following directories for a user:
+
$TEXMFHOME/source/latex/nameauth dtx file
$TEXMFHOME/tex/latex/nameauth sty file
$TEXMFHOME/doc/latex/nameauth pdf file, README, examples.tex
-and you create the following manual installation directories for local site:
+and creates the following directories for the local site:
$TEXMFLOCAL/source/latex/nameauth dtx file
$TEXMFLOCAL/tex/latex/nameauth sty file
$TEXMFLOCAL/doc/latex/nameauth pdf file, README, examples.tex
-The above environment variables often are /usr/local/texlive/texmf-local and
-~/texmf.
+The above environment variables often are /usr/local/texlive/texmf-local
+and ~/texmf.
-The make process normally renames the README.txt file created from the dtx file
-to just README by using mv (move/rename utility in the *nix userland). Windows
-distributions of TeX and LaTeX often keep the txt file as well.
+The make process normally renames the README.txt file created from the
+dtx file to just README by using mv (move / rename utility in the *nix
+userland). Windows distributions of TeX and LaTeX often keep the txt file
+because of using file extensions instead of ``magic numbers'' to identify
+files.
-Run mktexlsr with the appropriate level of permissions to complete the install.
+Run mktexlsr with the appropriate level of permissions to complete the
+install.
Testing notes:
-This package and documentation work and build with latex, lualatex, pdflatex,
-and xelatex. It can be used with makeindex/texindy.
+See the nameauth manual.
-For testing, the make file permits one to change the typesetting engine
-on the command line. The default is to build the package and documentation
-with pdflatex. See the make file for details.
-
License
This material is subject to the LaTeX Project Public License:
Modified: trunk/Master/texmf-dist/doc/latex/nameauth/examples.tex
===================================================================
--- trunk/Master/texmf-dist/doc/latex/nameauth/examples.tex 2020-02-21 22:55:44 UTC (rev 53862)
+++ trunk/Master/texmf-dist/doc/latex/nameauth/examples.tex 2020-02-21 22:56:14 UTC (rev 53863)
@@ -1,108 +1,524 @@
-\documentclass{article}
-\usepackage{verbatim}
-\begin{document}
%% This is an example file used with the nameauth package.
%% See README and nameauth.pdf for copyright info.
%%
-
-\section{Test for Latex Engine}
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-%% Test which LaTeX engine you are using
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-\begin{verbatim}
-\ifdefined\Umathchar
+\documentclass[11pt]{article}
+\IfFileExists{iftex.sty}{\usepackage{iftex}}{}
+\unless\ifdefined\RequireTUTeX
+ \usepackage{ifxetex}
+ \usepackage{ifluatex}
+ \usepackage{ifpdf}
+\fi
+% Used to create both dvi and pdf output
+\newif\ifDoTikZ
+\ifxetex
\usepackage{fontspec}
\usepackage{polyglossia}
-\else
- \usepackage[utf8]{inputenc}
- \usepackage[TS1,T1]{fontenc}
- \usepackage{babel}
-\fi
-% Below is optional; use only if your dvi viewer|\\
-% crashes or becomes unresponsive with tikz.|\\
-\usepackage{ifxetex}
-\usepackage{ifluatex}
-\usepackage{ifpdf}
-\ifxetex
+ \setdefaultlanguage{american} % Use own language
\usepackage{tikz}
+ \DoTikZtrue % Perhaps not needed
\else
- \ifpdf
- \usepackage{tikz}
- \fi
-\fi
-\end{verbatim}
-
-\section{Use Different Latex Engines}
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-%% Allow for multiple LaTeX engines
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-Requires \textsf{ifxetex}, \textsf{ifluatex}, and \textsf{ifpdf}.
-\begin{verbatim}
-\ifxetex
- xelatex %
-\else
\ifluatex
\ifpdf
- lualatex in pdf mode %
+ \usepackage{fontspec}
+ \usepackage{polyglossia}
+ \setdefaultlanguage{american} % Use own language
+ \usepackage{tikz}
+ \DoTikZtrue % Perhaps not needed
\else
- lualatex in dvi mode %
+ \IfFileExists{utf8-2018.def}{}
+ {\usepackage[utf8]{inputenc}}
+ \usepackage[TS1,T1]{fontenc}
+ \usepackage[american]{babel} % Use own language
+ \usepackage{lmodern}
+ % Perhaps add \usepackage{tikz}
\fi
\else
- \ifpdf
- pdflatex %
- \else
- latex %
+ \IfFileExists{utf8-2018.def}{}
+ {\usepackage[utf8]{inputenc}}
+ \usepackage[TS1,T1]{fontenc}
+ \usepackage[american]{babel} % Use own language
+ \usepackage{lmodern}
+ \ifpdf % Perhaps not needed
+ \usepackage{tikz}
+ \DoTikZtrue % Perhaps not needed
\fi
\fi
\fi
+\usepackage{booktabs}
+\usepackage[textwidth=137mm,textheight=237mm,right=30mm,marginparwidth=30mm,nohead]{geometry}
+\usepackage{nameauth}
+\usepackage{verbatim}
+\usepackage{makeidx}
+\usepackage{hyperref}
+
+\makeindex
+\reversemarginpar
+\newcounter{VerbLine}
+\newif\ifNoTag
+
+\begin{nameauth}
+ \< Adams & John & \noexpand\textSC{Adams} & >
+ \< SDJR & Sammy & \noexpand\textSC{Davis}, \noexpand\textSC{Jr}. & >
+ \< Dem & & Demetrius, I & >
+ \< deSmet & Pierre-Jean & \noexpand\Fbox{\noexpand\AltCaps{d}e Smet} & >
+ \< HAR & & Harun, \noexpand\textSC{\noexpand\AltCaps{a}l-Rashid} & >
+ \< Harnack & Adolf & Harnack & >
+ \< Jeff & Thomas & \noexpand\JEFF & >
+ \< Mencius & & \noexpand\textSC{Mencius} & >
+ \< Scipio & \noexpand\SCIPi & \noexpand\SCIPii & >
+ \< Shak & \noexpand\WM & \noexpand\SHK & >
+ \< Sutorius & Quintus & \noexpand\SUTOR & >
+ \< Wash & George & Washington & >
+\end{nameauth}
+
+\NameAddInfo{Demetrius, I}{ Soter}
+
+\PretagName[John]{\noexpand\textSC{Adams}}{Adams, John}
+\PretagName[Sammy]{\noexpand\textSC{Davis}, \noexpand\textSC{Jr}.}{Davis, Sammy, Jr.}
+\PretagName{Demetrius, I}{Demetrius 1}
+\PretagName[Pierre-Jean]{\noexpand\Fbox{\noexpand\AltCaps{d}e Smet}}{de Smet, Pierre-Jean}
+\PretagName{Harun, \noexpand\textSC{\noexpand\AltCaps{a}l-Rashid}}{Harun al-Rashid}
+\PretagName[Thomas]{\noexpand\JEFF}{Jefferson, Thomas}
+\PretagName{\noexpand\textSC{Mencius}}{Mencius}
+\PretagName{\noexpand\textSC{Meng}, Ke}{Meng Ke}
+\PretagName[\noexpand\SCIPi]{\noexpand\SCIPii}{Scipio Africanus}
+\PretagName[Quintus]{\noexpand\SUTOR}{Naevius Sutorius}
+\PretagName[\noexpand\WM]{\noexpand\SHK}{Shakespeare, William}
+\PretagName{Vlad, Ţepeş}{Vlad Tepes}
+\TagName[John]{\noexpand\textSC{Adams}}{, president}
+\TagName{Demetrius, I}{ Soter, king}
+\TagName[Thomas]{\noexpand\JEFF}{, president}
+\TagName{Vlad, II}{ Dracul}
+\TagName{Vlad, III}{ Dracula}
+\TagName[Martin]{Van Buren}{, president}
+\TagName[Ulysses S.]{Grant}{, president}
+\TagName[George]{Washington}{, president}
+
+\makeatletter
+\newcommand*\ClearNum{\def\verbatim at processline{\the\verbatim at line\par}}
+\newcommand*\StartNum{\setcounter{VerbLine}{0}\def\verbatim at processline{\stepcounter{VerbLine}\leavevmode\llap{\footnotesize\normalfont\theVerbLine\quad}\the\verbatim at line\par}}
+\newcommand*\ContinueNum{\def\verbatim at processline{\stepcounter{VerbLine}\leavevmode\llap{\footnotesize\normalfont\theVerbLine\quad}\the\verbatim at line\par}}
+\makeatother
+
+\ClearNum
+\title{\bfseries Longer Examples}
+\author{Charles P. Schaum}
+\date{2020/02/20}
+
+\begin{document}
+\maketitle
+
+\section{Particles}
+
+First we use variants with the \(\langle alternate\rangle\) argument:
+\begin{quote}\small
+\StartNum
+\begin{verbatim}
+\NameAddInfo{Demetrius, I}{ Soter}
+\PretagName{Demetrius, I}{Demetrius 1}
+\TagName{Demetrius, I}{ Soter, king}
+\begin{nameauth}
+ \< Dem & & Demetrius, I & >
+\end{nameauth}
\end{verbatim}
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-%% Print the first use of a name in text and margin
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-%%
-%% 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.
-%%
-\section{First Use in Margin: $\epsilon$-\TeX}
+\smallskip
+ \begin{tabular}{@{}ll}
+ \verb+\Dem[I Soter]+ & \Dem[I Soter]\\
+ \verb+\LDem+ & \LDem\\
+ \verb+\Dem+ & \Dem\\
+ \end{tabular}
+\end{quote}
+
+\begingroup%
+\makeatletter\renewcommand*\NamesFormat[1]{\begingroup%
+\protected at edef\temp{\endgroup{#1%
+\noexpand\NameQueryInfo[\unexpanded\expandafter{\the\@nameauth at toksa}]
+{\unexpanded\expandafter{\the\@nameauth at toksb}}
+[\unexpanded\expandafter{\the\@nameauth at toksc}]}}\temp}\makeatother
+\noindent For a more automated approach, we use ``text tags'' in the formatting macros:
+\begin{quote}\small
+\makeatletter\ContinueNum\makeatother
\begin{verbatim}
+\makeatletter
+\renewcommand*\NamesFormat[1]{%
+ \begingroup%
+ \protected at edef\temp{\endgroup%
+ {#1\noexpand\NameQueryInfo
+ [\unexpanded\expandafter{\the\@nameauth at toksa}]
+ {\unexpanded\expandafter{\the\@nameauth at toksb}}
+ [\unexpanded\expandafter{\the\@nameauth at toksc}]%
+ }%
+ }%
+ \temp%
+}
+\makeatother
+\end{verbatim}
+
+\smallskip
+ \begin{tabular}{@{}ll}
+ \verb+\ForgetThis\Dem+ & \ForgetThis\Dem\\
+ \verb+\LDem+ & \LDem\\
+ \verb+\Dem+ & \Dem\\
+ \end{tabular}
+\end{quote}
+\endgroup
+\newpage
+
+\begingroup
+We want all names in the index, so we define macros that expand one or two components: \textit{praenomen} and \textit{nomen}, \textit{cognomen} and \textit{agnomen}. We begin by defining a name with macros using \verb+\noexpand+ to prevent error:
+\newif\ifSkipGens
+\newif\ifNoGens
+\newif\ifSkipAgnomen
+\newif\ifNoAgnomen
+\newcommand*\SCIPi{\ifNoGens Publius\else
+ Publius Cornelius\fi}
+\newcommand*\SCIPii{\ifNoAgnomen Scipio\else
+ Scipio Africanus\fi}
+\newcommand*\ScipioOnly{\SkipAgnomentrue\Scipio}
\renewcommand*\NamesFormat[1]%
-{%
- #1%
- \unless\ifinner
- \marginpar{\raggedleft\scriptsize #1}%
+ {\ifSkipGens\NoGenstrue\fi\ifSkipAgnomen\NoAgnomentrue\fi#1%
+ \global\SkipGensfalse\global\SkipAgnomenfalse}
+\renewcommand*\MainNameHook[1]%
+ {\ifSkipGens\NoGenstrue\fi\ifSkipAgnomen\NoAgnomentrue\fi#1%
+ \global\SkipGensfalse\global\SkipAgnomenfalse}
+ \begin{quote}\small
+ \StartNum
+ \begin{verbatim}
+\begin{nameauth}
+ \< Scipio & \noexpand\SCIPi & \noexpand\SCIPii & >
+\end{nameauth}
+\PretagName[\noexpand\SCIPi]{\noexpand\SCIPii}{Scipio Africanus}
+\end{verbatim}
+ \end{quote}
+
+ We define the flags and macros by which the name will change. The global state of \verb+\NoGens+ and \verb+\NoAgnomen+ determine the index form. The local scope in the formatting hooks allows changes that are reset when exiting that scope.
+ \begin{quote}\small
+ \ContinueNum
+\begin{verbatim}
+\newif\ifSkipGens
+\newif\ifNoGens
+\newif\ifSkipAgnomen
+\newif\ifNoAgnomen
+\newcommand*\SCIPi{\ifNoGens Publius\else
+ Publius Cornelius\fi}
+\newcommand*\SCIPii{\ifNoAgnomen Scipio\else
+ Scipio Africanus\fi}
+\newcommand*\ScipioOnly{\SkipAgnomentrue\Scipio}
+\renewcommand*\NamesFormat[1]%^^A
+ {\ifSkipGens\NoGenstrue\fi\ifSkipAgnomen\NoAgnomentrue\fi#1%
+ \global\SkipGensfalse\global\SkipAgnomenfalse}
+\renewcommand*\MainNameHook[1]%^^A
+ {\ifSkipGens\NoGenstrue\fi\ifSkipAgnomen\NoAgnomentrue\fi#1%
+ \global\SkipGensfalse\global\SkipAgnomenfalse}
+\end{verbatim}
+\smallskip
+\ScipioOnly\ \verb+\ScipioOnly+ was born around 236 \textsc{bc} into the Scipio branch of the Cornelius clan, one of six large patrician clans. \SkipGenstrue\ScipioOnly\ \verb+\SkipGenstrue\ScipioOnly+ rose to fame with his military exploits in Hispania and Africa during the Second Punic War. Thereafter he was known as \SkipGenstrue\Scipio\ \verb+\SkipGenstrue\Scipio+.
+ \end{quote}
+
+ The index entry is fairly lengthy by necessity, governed by the global state of the Boolean flags, and expanding to:
+ \begin{quote}
+ \texttt{\ShowIdxPageref[\noexpand\SCIPi]{\noexpand\SCIPii}}
+ \end{quote}
+
+ \begin{quote}\small
+ \StartNum
+ \begin{verbatim}
+\begin{nameauth}
+ \< Sutorius & Quintus & \noexpand\SUTOR & >
+\end{nameauth}
+\PretagName[Quintus]{\noexpand\SUTOR}{Naevius Sutorius}
+\newcommand*\SUTOR{\ifNoGens
+ \ifNoAgnomen
+ Sutorius\else
+ Sutorius Macro\fi
+ \else\ifNoAgnomen
+ Naevius Sutorius\else
+ Naevius Sutorius Macro\fi\fi}
+\end{verbatim}
+\end{quote}
+\newcommand*\SUTOR{\ifNoGens
+ \ifNoAgnomen
+ Sutorius\else
+ Sutorius Macro\fi
+ \else\ifNoAgnomen
+ Naevius Sutorius\else
+ Naevius Sutorius Macro\fi\fi}
+
+\verb+\Sutorius +\Sutorius
+
+\verb+\SkipGenstrue\Sutorius +\SkipGenstrue\Sutorius
+
+\endgroup
+\newpage
+
+\section{Alternate Formatting: Inflections}
+
+In this section we use a scope to contain \verb+\AltFormatActive+ as we show how to implement a simple grammatical inflection.
+
+\begingroup\AltFormatActive
+\newif\ifGenitive
+\newif\ifDoGen
+\renewcommand*\NamesFormat[1]
+ {\ifGenitive\DoGentrue\fi#1\global\Genitivefalse}
+\renewcommand*\MainNameHook[1]
+ {\ifGenitive\DoGentrue\fi\AltOff#1\global\Genitivefalse}
+\newcommand\JEFF{\ifDoGen\textSC{Jefferson's}\else\textSC{Jefferson}\fi}
+\begin{quote}\small
+\StartNum
+\begin{verbatim}
+\newif\ifGenitive
+\newif\ifDoGen
+\renewcommand*\NamesFormat[1]
+ {\ifGenitive\DoGentrue\fi#1\global\Genitivefalse}
+\renewcommand*\MainNameHook[1]
+ {\ifGenitive\DoGentrue\fi\AltOff#1\global\Genitivefalse}
+\begin{nameauth}
+ \< Jeff & Thomas & \noexpand\JEFF & >
+\end{nameauth}
+\PretagName[Thomas]{\noexpand\JEFF}{Jefferson, Thomas}
+\TagName[Thomas]{\noexpand\JEFF}{, president}
+\newcommand\JEFF{\ifDoGen\textSC{Jefferson's}\else
+ \textSC{Jefferson}\fi}
+
+Consider \Genitivetrue\Jeff\ influence. More on \Jeff\ later.
+\Genitivetrue\Jeff\ reputation has declined in recent decades.
+\end{verbatim}
+
+\smallskip
+Consider \Genitivetrue\Jeff\ legacy. More on \Jeff\ later.
+\Genitivetrue\Jeff\ reputation has declined in recent decades.
+\end{quote}
+\newpage
+
+
+\section{Continental Format Reference Work}
+
+Let us create a macro for entries in a reference work using the basic form of Continental formatting.
+
+\begin{quote}\small
+ \StartNum
+ \begin{verbatim}
+\AltFormatActive
+\PretagName[Greta]{\textSC{Garbo}}{Garbo, Greta}
+\PretagName[Heinz]{\textSC{Rühmann}}{Ruehmann, Heinz}
+\PretagName[Heinrich Wilhelm]{\textSC{Rühmann}}%
+ {Ruehmann, Heinrich Wilhelm}
+
+\newcommand{\RefArticle}[4]{%
+ \def\check{#2}%
+ \ifx\check\empty
+ \noindent\ForgetThis#1\ {#4}
+ \else
+ \noindent\ForceName#1\ ``\ForceName#2''
+ \ForceName#3\ {#4}
\fi
}
\end{verbatim}
+\end{quote}
-\section{First Use in Margin: Historic \TeX}
-\begin{verbatim}
-\renewcommand*\NamesFormat[1]%
-{%
- #1%
- \ifinner\else
- \marginpar{\raggedleft\scriptsize #1}%
+\PretagName[Greta]{\textSC{Garbo}}{Garbo, Greta}
+\PretagName[Heinz]{\textSC{Rühmann}}{Ruehmann, Heinz}
+\PretagName[Heinrich Wilhelm]{\textSC{Rühmann}}%
+ {Ruehmann, Heinrich Wilhelm}
+\newcommand{\RefArticle}[4]{%
+ \def\check{#2}%
+ \ifx\check\empty
+ \noindent\ForgetThis#1\ {#4}
+ \else
+ \noindent\ForceName#1\ ``\ForceName#2''
+ \ForceName#3\ {#4}
\fi
}
+\verb+\RefArticle+ either formats the name from the first argument and appends the fourth argument, ignoring the others if the second is empty, or it formats the first three arguments and appends the fourth. We determine what those arguments mean by including specific naming macros.
+\begin{quote}\small
+ \ContinueNum
+ \begin{verbatim}
+\RefArticle%
+ {\Name[Greta]{\textSC{Garbo}}}%
+ {}{}%
+ {(18 September 1905\,--\,15 April 1990) was a Swedish
+ film actress during the 1920s and 1930s.}
+
+\RefArticle%
+ {%
+ \IndexRef[Heinrich Wilhelm]{\textSC{Rühmann}}%
+ {\textSC{Rühmann}, Heinz}%
+ \SubvertThis\FName[Heinrich Wilhelm]{\textSC{Rühmann}}%
+ }%
+ {\SubvertThis\FName[Heinz]{\textSC{Rühmann}}}%
+ {\Name[Heinz]{\textSC{Rühmann}}}%
+ {(7 March 1902\,--\,3 October 1994) was a German actor
+ in over 100 films.}
+
+\AltFormatInactive
\end{verbatim}
+\end{quote}
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-%% Print a text tag after first name use
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-%%
-%% 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.
-%%
-\section{Text Tag With First Use: $\epsilon$-\TeX}
+\begin{quote}
+\RefArticle%
+ {\Name[Greta]{\textSC{Garbo}}}%
+ {}{}%
+ {(18 September 1905\,--\,15 April 1990) was a Swedish
+ film actress during the 1920s and 1930s.}
+
+\RefArticle%
+ {%
+ \IndexRef[Heinrich Wilhelm]{\textSC{Rühmann}}%
+ {\textSC{Rühmann}, Heinz}%
+ \SubvertThis\FName[Heinrich Wilhelm]{\textSC{Rühmann}}%
+ }%
+ {\SubvertThis\FName[Heinz]{\textSC{Rühmann}}}%
+ {\Name[Heinz]{\textSC{Rühmann}}}%
+ {(7 March 1902\,--\,3 October 1994) was a German actor
+ in over 100 films.}
+\end{quote}
+\endgroup
+\newpage
+
+\section{Beamer MWE}
+One must use the macros that control and detect names, otherwise name forms will change as one advances the slides:
+\begin{quote}\small
+\StartNum
\begin{verbatim}
-\newif\ifNoTag
+\documentclass{beamer}
+\usepackage{nameauth}
+\mode<presentation>
+\beamerdefaultoverlayspecification{<+->}
+
+\begin{document}
+
+\begin{frame}{Move Text Without Retyping Names}
+ \begin{itemize}\footnotesize
+ \item<1-> Original\ForgetName[George]{Washington}%
+ \ForgetName[George]{Washington's}\\
+ \Name[Martin]{Van Buren} changes
+ after the first overlay.
+ \begin{enumerate}
+ \item<2-> \IfMainName[George]{Washington's}{He}%
+ {\Name[George]{Washington}}
+ became the first president
+ of the United States.
+ \item<3-> \IfMainName[George]{Washington}{His}%
+ {\SkipIndex\Name*[George]{Washington's}}
+ military successes during the Seven Years War
+ readied him to command the army
+ of the Continental Congress.
+ \end{enumerate}
+ \item<1-> Reordered\ForgetName[George]{Washington}%
+ \ForgetName[George]{Washington's}\\
+ \ForgetThis\Name[Ulysses S.]{Grant}
+ does not change.
+ \begin{enumerate}
+ \item<3-> \IfMainName[George]{Washington}{His}%
+ {\SkipIndex\Name*[George]{Washington's}}
+ military successes during the Seven Years War
+ readied him to command the army
+ of the Continental Congress.
+ \item<2-> \IfMainName[George]{Washington's}{He}%
+ {\Name[George]{Washington}}
+ became the first president
+ of the United States.
+ \end{enumerate}
+ \end{itemize}
+\end{frame}
+
+\end{document}
+\end{verbatim}
+\IndexName[George]{Washington}
+\IndexName[Martin]{Van Buren}
+\IndexName[Ulysses S.]{Grant}
+\end{quote}
+
+The overlays, numbered progressively from one to three, begin by deleting name control sequence patterns. Uncontrolled names will change. Name conditionals ensure specific, context-dependent forms based on what name has appeared. These conditionals allow the text to be order-independent.
+\newpage
+
+\section{Hooks: Intro}
+\label{sec:Hooksi}
+
+Something more complex than a font switch can occur in \verb+\NamesFormat+. Below we put the first mention of a name in boldface, with a margin note, if possible.
+\begin{quote}\small
+\StartNum
+\begin{verbatim}
+\let\OldFormat\NamesFormat
+\renewcommand*\NamesFormat[1]{\textbf{#1}\unless\ifinner
+ \marginpar{\raggedleft\scriptsize #1}\fi}
+\let\NamesFormat\OldFormat
+\PretagName{Vlad, Ţepeş}{Vlad Tepes} % for accented names
+\TagName{Vlad, II}{ Dracul} % for index information
+\TagName{Vlad, III}{ Dracula}
+\end{verbatim}
+
+Within the document after the preamble:\vspace{-\medskipamount}%
+\let\OldFormat\NamesFormat%
+\renewcommand*\NamesFormat[1]{\textbf{#1}\unless\ifinner
+ \marginpar{\raggedleft\scriptsize #1}\fi}%
+\ContinueNum
+\begin{verbatim}
+\Name{Vlad, III}[III Dracula], known as
+\AKA{Vlad III}{Vlad, Ţepeş} (the Impaler)
+after his death, was the son of \Name{Vlad, II}[II Dracul],
+a member of the Order of the Dragon. Later references to
+``\Name*{Vlad, III}'' and ``\Name{Vlad, III}'' appear thus.\end{verbatim}
+
+\Name{Vlad, III}[III Dracula], known as
+\AKA{Vlad III}{Vlad, Ţepeş} (the Impaler)
+after his death, was the son of \Name{Vlad, II}[II Dracul],
+a member of the Order of the Dragon. Later references to
+``\Name*{Vlad, III}'' and ``\Name{Vlad, III}'' appear thus.
+
+\let\NamesFormat\OldFormat
+\begin{verbatim}\let\NamesFormat\OldFormat
+\end{verbatim}
+\end{quote}
+
+Now we have reverted to the default \verb+\NamesFormat+ and we get:
+\begin{itemize}
+ \item \verb+\ForgetThis\Name{Vlad, III}[III Dracula]+\dotfill \ForgetThis\Name{Vlad, III}[III Dracula]
+ \item \verb+\Name*{Vlad, III}+\dotfill \Name*{Vlad, III}
+ \item \verb+\Name{Vlad, III}+\dotfill \Name{Vlad, III}
+\end{itemize}
+
+We also set up the cross-reference \verb+\IndexRef{Dracula}{Vlad III}+\IndexRef{Dracula}{Vlad III}.
+\newpage
+
+\section{Hooks: Life Dates}
+\label{sec:Hooksii}
+Here we add name conditionals and ``text tags'' to add information to names when desired. The example \verb+\NamesFormat+ below adds a text tag to the first occurrences of main-matter names. It uses internal macros of \verb+\@nameauth at Name+. To prevent errors, the Boolean values \texttt{\textbackslash if at nameauth@InName} and \texttt{\textbackslash if at nameauth@InAKA} are true only within the scope of \verb+\@nameauth at Name+ and \verb+\AKA+ respectively.
+
+Below we use the three token registers available in \textsf{nameauth} to use the name conditional macros. In \verb+\AKA+ these token registers are copies of the \textbf{last} three arguments, corresponding to the pseudonym. We assume that we will not be using the \texttt{alwaysformat} option, meaning that we only call this hook once for a first use of \verb+\AKA+. We also use a different formatting for the naming macros on the one hand and \verb+\AKA+ on the other:
+
+\begin{quote}\small
+\StartNum
+\begin{verbatim}
+\newif\ifNoTag% allows us to work around \ForgetName
+\let\OldFormat\NamesFormat
+\let\OldFrontFormat\FrontNamesFormat
\makeatletter
\renewcommand*\NamesFormat[1]{\begingroup%
- \protected at edef\temp{\endgroup\textbf{#1}%
+ \protected at edef\temp{\endgroup\textsc{#1}%
+ \unless\ifNoTag
+ \if at nameauth@InName
+ {\bfseries\noexpand\NameQueryInfo
+ [\unexpanded\expandafter{\the\@nameauth at toksa}]
+ {\unexpanded\expandafter{\the\@nameauth at toksb}}
+ [\unexpanded\expandafter{\the\@nameauth at toksc}]}\fi
+ \if at nameauth@InAKA
+ {\normalfont\noexpand\NameQueryInfo
+ [\unexpanded\expandafter{\the\@nameauth at toksa}]
+ {\unexpanded\expandafter{\the\@nameauth at toksb}}
+ [\unexpanded\expandafter{\the\@nameauth at toksc}]}\fi
+ \fi}\temp\global\NoTagfalse%
+}
+\makeatother
+\let\FrontNamesFormat\NamesFormat
+\end{verbatim}
+\end{quote}
+\let\OldFormat\NamesFormat%
+\let\OldFrontFormat\FrontNamesFormat%
+\makeatletter%
+\renewcommand*\NamesFormat[1]{\begingroup%
+ \protected at edef\temp{\endgroup\textsc{#1}%
\unless\ifNoTag
\if at nameauth@InName
{\bfseries\noexpand\NameQueryInfo
@@ -110,128 +526,526 @@
{\unexpanded\expandafter{\the\@nameauth at toksb}}
[\unexpanded\expandafter{\the\@nameauth at toksc}]}\fi
\if at nameauth@InAKA
- \noexpand\NameQueryInfo
+ {\normalfont\noexpand\NameQueryInfo
[\unexpanded\expandafter{\the\@nameauth at toksa}]
{\unexpanded\expandafter{\the\@nameauth at toksb}}
- [\unexpanded\expandafter{\the\@nameauth at toksc}]\fi
- \fi}\temp\global\NoTagfalse}
+ [\unexpanded\expandafter{\the\@nameauth at toksc}]}\fi
+ \fi}\temp\global\NoTagfalse}%
\makeatother
+
+We print tags in the first use hooks unless \verb+\NoTag+ is set true. Please note that the conditional path here is placed within the \verb+\edef+. Putting it outside the \verb+\edef+, such as \verb+\unless\ifNoTag\temp\fi+, will cause errors. This method uses the $\epsilon$-\TeX{} primitives \verb+\noexpand+ and \verb+\unexpanded+ to avoid repetition of \verb+\expandafter+.
+
+Before we can refer to any text tags, we must create them. Using the approach above, we must include a leading space in the text tags. The leading space is needed only when a text tag appears. We also set up a cross-reference:
+\begin{quote}\small
+\ContinueNum
+\begin{verbatim}
+\NameAddInfo[George]{Washington}{ (1732--99)}
+\NameAddInfo[Mustafa]{Kemal}{ (1881--1938)}
+\NameAddInfo{Atatürk}{ (in 1934, a special surname)}
+\IndexRef{Atatürk}{Kemal, Mustafa}
\end{verbatim}
-\clearpage
+\end{quote}
+\NameAddInfo[George]{Washington}{ (1732--99)}
+\NameAddInfo[Mustafa]{Kemal}{ (1881--1938)}
+\NameAddInfo{Atatürk}{ (in 1934, a special surname)}
+\IndexRef{Atatürk}{Kemal, Mustafa}
-\section{Text Tag With First Use: Historic \TeX}
+Now we begin with the first example, where the name is in small caps, while the dates are in boldface because we use a naming macro. This formatting is used only to show the different decision paths:
+\newpage
+
+\begin{quote}\small
+\ContinueNum
\begin{verbatim}
+\ForgetThis\Wash held office 1789--97.\\
+No tags: \Wash.\\
+First use, dates suppressed: \NoTagtrue\ForgetThis\Wash.
+\end{verbatim}
+
+\smallskip
+\ForgetThis\Wash\ held office 1789--97.\\
+No tags: \Wash.\\
+First use, dates suppressed: \NoTagtrue\ForgetThis\Wash.
+\end{quote}
+
+Since we already set up a cross-reference with \verb+\IndexRef+, we can use the naming macros with ``Atatürk'' and get the desired formatting without any page references:
+\begin{quote}\small
+\ContinueNum
+\begin{verbatim}
+\Name[Mustafa]{Kemal} was granted the name
+\Name{Atatürk}. We mention \Name[Mustafa]{Kemal}
+and \Name{Atatürk} again.
+
+First use, no tag:
+\NoTagtrue\ForgetThis\Name{Atatürk}.
+\end{verbatim}
+
+\smallskip
+\Name[Mustafa]{Kemal} was granted the name
+\Name{Atatürk}. We mention \Name[Mustafa]{Kemal}
+and \Name{Atatürk} again.
+
+First use, no tag:
+\NoTagtrue\ForgetThis\Name{Atatürk}.
+\end{quote}
+
+Since we set up distinct formatting (\verb+\normalfont+ instead of boldface) for name tags and cross-reference tags, we now simulate the \texttt{formatAKA} package option and use \verb+\ForceName+ with \verb+\AKA+:
+\begin{quote}\small
+\ContinueNum
+\begin{verbatim}
+\makeatletter\@nameauth at AKAFormattrue\makeatother
+\ForgetThis\Name[Mustafa]{Kemal} was granted the name
+\ForceName\AKA[Mustafa]{Kemal}{Atatürk}. We mention
+\Name[Mustafa]{Kemal} and \AKA[Mustafa]{Kemal}{Atatürk} again.
+
+First use, no tag:
+\NoTagtrue\ForceName\AKA[Mustafa]{Kemal}{Atatürk}.
+\end{verbatim}
+
+\smallskip
+\makeatletter\@nameauth at AKAFormattrue\makeatother
+\ForgetThis\Name[Mustafa]{Kemal} was granted the name
+\ForceName\AKA[Mustafa]{Kemal}{Atatürk}. We mention
+\Name[Mustafa]{Kemal} and \AKA[Mustafa]{Kemal}{Atatürk} again.
+
+First use, no tag:
+\NoTagtrue\ForceName\AKA[Mustafa]{Kemal}{Atatürk}.
+\end{quote}
+
+We show an alternate part of this example on the next page that does not appear in the manual, but works identically to that above.
+\newpage
+
+We change the look of the page reference just to see if it works:
+
+\begin{quote}\small
+\ContinueNum
+\begin{verbatim}
+\def\fett#1{\textbf{\sffamily #1}}
+\TagName[Mustafa]{Kemal}{|fett}
+\end{verbatim}
+\end{quote}
+\def\fett#1{\textbf{\sffamily #1}}
+\TagName[Mustafa]{Kemal}{|fett}
+
+This version does not use $\epsilon$-\TeX primitives. We ``forget'' names as needed and replay the text on the previous page with the new version:
+
+\makeatletter
+\renewcommand*\NamesFormat[1]{%
+ \let\ex\expandafter%
+ \textsc{#1}%
+ \if at nameauth@InName
+ \ifNoTag
+ \else
+ \bfseries%
+ \ex\ex\ex\ex\ex\ex\ex\NameQueryInfo\ex\ex\ex\ex\ex\ex\ex[%
+ \ex\ex\ex\the\ex\ex\ex\@nameauth at toksa\ex\ex\ex]%
+ \ex\ex\ex{\ex\the\ex\@nameauth at toksb\ex}%
+ \ex[\the\@nameauth at toksc]%
+ \fi\fi
+ \if at nameauth@InAKA
+ \ifNoTag
+ \else
+ \normalfont%
+ \ex\ex\ex\ex\ex\ex\ex\NameQueryInfo\ex\ex\ex\ex\ex\ex\ex[%
+ \ex\ex\ex\the\ex\ex\ex\@nameauth at toksa\ex\ex\ex]%
+ \ex\ex\ex{\ex\the\ex\@nameauth at toksb\ex}%
+ \ex[\the\@nameauth at toksc]%
+ \fi\fi
+ \global\NoTagfalse}
+\makeatother
+\begin{quote}\small
+\ContinueNum
+\begin{verbatim}
\newif\ifNoTag
\makeatletter
\renewcommand*\NamesFormat[1]{%
\let\ex\expandafter%
- #1%
+ \textsc{#1}%
\if at nameauth@InName
\ifNoTag
\else
+ \bfseries%
\ex\ex\ex\ex\ex\ex\ex\NameQueryInfo\ex\ex\ex\ex\ex\ex\ex[%
- \ex\ex\ex\the\ex\ex\ex\@nameauth at toksa\ex\ex\ex]%
- \ex\ex\ex{\ex\the\ex\@nameauth at toksb\ex}\ex[\the\@nameauth at toksc]%
+ \ex\ex\ex\the\ex\ex\ex\@nameauth at toksa\ex\ex\ex]%
+ \ex\ex\ex{\ex\the\ex\@nameauth at toksb\ex}%
+ \ex[\the\@nameauth at toksc]%
\fi\fi
\if at nameauth@InAKA
\ifNoTag
\else
+ \normalfont%
\ex\ex\ex\ex\ex\ex\ex\NameQueryInfo\ex\ex\ex\ex\ex\ex\ex[%
- \ex\ex\ex\the\ex\ex\ex\@nameauth at toksa\ex\ex\ex]%
- \ex\ex\ex{\ex\the\ex\@nameauth at toksb\ex}\ex[\the\@nameauth at toksc]%
+ \ex\ex\ex\the\ex\ex\ex\@nameauth at toksa\ex\ex\ex]%
+ \ex\ex\ex{\ex\the\ex\@nameauth at toksb\ex}%
+ \ex[\the\@nameauth at toksc]%
\fi\fi
\global\NoTagfalse}
\makeatother
\end{verbatim}
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-%% Surname index entries in an fbox
-%% First surname instances in text are in an fbox
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-%%
-%% We create a macro \Fbox that prints its argument in a framed
-%% box when \@nameauth at DoAlt is true, or it just prints its argument.
-%%
-%%
-\section{Formatting and Capping: New Style}
+\smallskip
+With \verb+\Name+:\\
+\ForgetThis\Name[Mustafa]{Kemal} was granted the name
+\ForgetThis\Name{Atatürk}. We mention \Name[Mustafa]{Kemal}
+and \Name{Atatürk} again.
+
+First use, no tag: \NoTagtrue\ForgetThis\Name{Atatürk}.\bigskip
+
+With \verb+\AKA+:\\
+\makeatletter\@nameauth at AKAFormattrue\makeatother
+\ForgetThis\Name[Mustafa]{Kemal} was granted the name
+\ForceName\AKA[Mustafa]{Kemal}{Atatürk}. We mention
+\Name[Mustafa]{Kemal} and \AKA[Mustafa]{Kemal}{Atatürk} again.
+
+First use, no tag: \NoTagtrue\ForceName\AKA[Mustafa]{Kemal}{Atatürk}.
+\end{quote}
+
+\begin{quote}\small
+\ContinueNum
\begin{verbatim}
+\let\NamesFormat\OldFormat
+\let\FrontNamesFormat\OldFrontFormat
+\end{verbatim}
+\end{quote}
+\let\NamesFormat\OldFormat
+\let\FrontNamesFormat\OldFrontFormat
+\newpage
+
+\section{Hooks: Advanced}
+\label{sec:Hooksiii}
+We start alternate formatting in a new scope with \verb+\AltFormatActive+. The scope ends just before the index is printed.
+\AltFormatActive
+
+\begin{center}\bfseries Continental Format\end{center}
+
+\noindent Here we look in greater detail at how \textsf{nameauth} implements the advanced version of Continental formatting. Font changes in both text and the index occur with the short macros \verb+\textSC+, \verb+\textIT+, \verb+\textBF+, and \verb+\textUC+. Since they all look similar to \verb+\textSC+, we just show this one macro from the package source:
+\begin{quote}\small
+\StartNum
+\begin{verbatim}
+\newcommand*\textSC[1]{%
+ \if at nameauth@DoAlt\textsc{#1}\else#1\fi
+}
+\end{verbatim}
+\end{quote}
+
+We plan to have small caps on by default, then off in subsequent uses. We therefore use \verb+\AltFormatActive+ for the ``always on'' general condition, then redefine \verb+\MainNameHook+ because it is the subsequent use. We use \verb+\AltOff+ to suppress formatting. It works only in the formatting hooks. \verb+\AltOff+ toggles an internal flag that deactivates any changes:
+\begin{quote}\small
+\ContinueNum
+\begin{verbatim}
+\newcommand*\AltOff{%
+ \if at nameauth@InHook\@nameauth at DoAltfalse\fi
+}
+\end{verbatim}
+\end{quote}
+
+Since the normal effects of \verb+\CapThis+ are disabled, \verb+\AltCaps+ does the job by capitalizing its argument in braces \texttt{\{~\}} when it is used in a macro hook and triggered by \verb+\CapThis+. The source looks like:
+\begin{quote}\small
+\ContinueNum
+\begin{verbatim}
+\newcommand*\AltCaps[1]{%
+ \if at nameauth@InHook
+ \if at nameauth@DoCaps\MakeUppercase{#1}\else#1\fi
+ \else#1\fi
+}
+\end{verbatim}
+\end{quote}
+
+It is important that these macros not expand too soon. We therefore must put \verb+\noexpand+ once before \verb+\textSC+, etc., and once before \verb+\AltCaps+. This is because the name arguments in \textsf{nameauth} have to use \verb+\protected at edef+ to work consistently in different document classes.
+
+Before we alter the formatting hooks, we either can \verb+\let+ the hook macros to recall them later or we can use \verb+\begingroup+ and \verb+\endgroup+ to create a new scope that localizes any changes. We use scoping in this section.
+
+The final step \textbf{does not come} from the \textsf{nameauth} source. We must redefine the formatting hooks ourselves. One of the simplest ways to do this when using the \texttt{altformat} option or \verb+\AltFormatActive+ is:
+\begin{quote}\small
+\ContinueNum
+\begin{verbatim}
+\renewcommand*\MainNameHook{\AltOff}
+\let\FrontNameHook\MainNameHook
+\end{verbatim}
+\end{quote}
+
+\renewcommand*\MainNameHook{\AltOff}\let\FrontNameHook\MainNameHook
+Use \verb+\let\FrontNamesFormat\MainNameHook+ to suppress formatting in the front matter.
+Continental formatting usually alters at least one element in the required name argument, as we see below:
+\begin{quote}\small
+\ContinueNum
+\begin{verbatim}
+\begin{nameauth}
+ \< Adams & John & \noexpand\textSC{Adams} & >
+ \< SDJR & Sammy & \noexpand\textSC{Davis},
+ \noexpand\textSC{Jr}. & >
+ \< HAR & & Harun, \noexpand\textSC%
+ {\noexpand\AltCaps{a}l-Rashid} & >
+ \< Mencius & & \noexpand\textSC{Mencius} & >
+\end{nameauth}
+\end{verbatim}
+\end{quote}
+
+Now we must ensure that these names are sorted properly in the index. When sorting names, be sure to use \verb+\noexpand+ before the control sequences in the macro arguments so they expand at the proper time:
+\begin{quote}\small
+\ContinueNum
+\begin{verbatim}
+\PretagName[John]{\noexpand\textSC{Adams}}{Adams, John}
+\PretagName[Sammy]%
+ {\noexpand\textSC{Davis}, \noexpand\textSC{Jr}.}%
+ {Davis, Sammy, Jr.}
+\PretagName{Harun, \noexpand\textSC%
+ {\noexpand\AltCaps{a}l-Rashid}}{Harun al-Rashid}
+\PretagName{\noexpand\textSC{Mencius}}{Mencius}
+\end{verbatim}
+\end{quote}
+
+\begin{center}
+\small\noindent\begin{tabular}{llll}\toprule
+First & Next & Long & Short \\\midrule
+\verb+\Adams+ & \verb+\Adams+ & \verb+\LAdams+ & \verb+\SAdams+\\
+\Adams & \Adams & \LAdams & \SAdams\\\midrule
+\verb+\SDJR+ & \verb+\SDJR+ & \verb+\LSDJR+ & \verb+\SSDJR+\\
+\SDJR & \SDJR & \LSDJR & \SSDJR\\\midrule
+\verb+\HAR+ & \verb+\HAR+ & \verb+\LHAR+ & \verb+\SHAR+\\
+\HAR & \HAR & \LHAR & \SHAR\\\midrule
+\verb+\Mencius+ & \verb+\Mencius+ & \verb+\LMencius+ & \verb+\SMencius+\\
+\Mencius & \Mencius & \LMencius & \SMencius\\\bottomrule
+\end{tabular}
+\end{center}\bigskip
+
+Debugging tests:
+
+\begin{quote}\small
+\StartNum
+\begin{verbatim}
+\ShowPattern[John]{\noexpand\textSC{Adams}}
+\ShowPattern[Sammy]{\noexpand\textSC{Davis}, \noexpand\textSC{Jr}.}
+\ShowPattern{Harun, \noexpand\textSC{\noexpand\AltCaps{a}l-Rashid}}
+\ShowPattern{\noexpand\textSC{Mencius}}
+\ShowIdxPageref[John]{\noexpand\textSC{Adams}}
+\ShowIdxPageref[Sammy]{\noexpand\textSC{Davis}, \noexpand\textSC{Jr}.}
+\ShowIdxPageref{Harun, \noexpand\textSC{\noexpand\AltCaps{a}l-Rashid}}
+\ShowIdxPageref{\noexpand\textSC{Mencius}}
+\end{verbatim}
+\end{quote}
+
+\begin{center}
+\footnotesize\begin{tabular}{ll}\toprule
+First & \verb+\ShowPattern+ \\\midrule
+\ForgetThis\Adams & \ShowPattern[John]{\noexpand\textSC{Adams}}\\
+\ForgetThis\SDJR & \ShowPattern[Sammy]{\noexpand\textSC{Davis}, \noexpand\textSC{Jr}.}\\
+\ForgetThis\HAR & \ShowPattern{Harun, \noexpand\textSC{\noexpand\AltCaps{a}l-Rashid}}\\
+\ForgetThis\Mencius & \ShowPattern{\noexpand\textSC{Mencius}}\\\bottomrule
+\end{tabular}\bigskip
+
+\begin{tabular}{llll}\toprule
+First & \verb+\ShowIdxPageref+ & \verb+\ShowIdxPageref*+\\\midrule
+\ForgetThis\Adams & \ShowIdxPageref[John]{\noexpand\textSC{Adams}} & \ShowIdxPageref*[John]{\noexpand\textSC{Adams}}\\
+\ForgetThis\SDJR & \ShowIdxPageref[Sammy]{\noexpand\textSC{Davis}, \noexpand\textSC{Jr}.} & \ShowIdxPageref*[Sammy]{\noexpand\textSC{Davis}, \noexpand\textSC{Jr}.}\\
+\ForgetThis\HAR & \ShowIdxPageref{Harun, \noexpand\textSC{\noexpand\AltCaps{a}l-Rashid}} & \ShowIdxPageref*{Harun, \noexpand\textSC{\noexpand\AltCaps{a}l-Rashid}} \\
+\ForgetThis\Mencius & \ShowIdxPageref{\noexpand\textSC{Mencius}} & \ShowIdxPageref*{\noexpand\textSC{Mencius}}\\\bottomrule
+\end{tabular}
+\end{center}
+
+\newpage
+
+\begin{center}\bfseries Rolling Your Own: Basic\end{center}
+
+\noindent When redesigning formatting hooks, one often uses \verb+\AltFormatActive+ or the \texttt{altformat} option to enable alternate formatting and prevent \verb+\CapThis+ from breaking custom formatting macros.
+
+We recommend examining the internal package flag \verb+\@nameauth at DoAlt+, which activates alternate formatting, \verb+\@nameauth at DoCaps+, which handles capitalization, and \verb+\@nameauth at InHook+, which is true when the formatting hooks are called. Custom macros tend to look like:
+\begin{quote}\small
+\StartNum
+\begin{verbatim}
\makeatletter
\newcommand*\Fbox[1]{%
- \if at nameauth@DoAlt
- \fbox{#1}\else#1\fi
+ \if at nameauth@DoAlt\protect\fbox{#1}\else#1\fi
}
\makeatother
+\end{verbatim}
+\end{quote}
+\makeatletter
+\newcommand*\Fbox[1]{%
+ \if at nameauth@DoAlt\protect\fbox{#1}\else#1\fi
+}
+\makeatother
-\renewcommand*\MainNameHook[1]{\NameOnly\NameParser}
-
+Since \verb+\AltCaps+ is part of \textsf{nameauth}, you need not reinvent that wheel. Just use it. The final step is redefining the hooks, which can be as simple as:
+\begin{quote}\small
+\ContinueNum
+\begin{verbatim}
+\renewcommand*\MainNameHook{\AltOff}
\let\FrontNameHook\MainNameHook
\end{verbatim}
-\clearpage
+\end{quote}
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-%% Use both the arguments passed to the hooks
-%% and \NameParser under different conditions
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-%%
-%% We redefine the hooks to print a name in the text and in
-%% a margin paragraph. We change some of the internal flags
-%% to make \NameParser print the name differently.
-%%
-%%
-\section{Putting \texttt{\textbackslash NameParser} on Display}
+When sorting names, be sure to use \verb+\noexpand+ before the control sequences in the macro arguments so they expand at the proper time:
+\begin{quote}\small
+\ContinueNum
\begin{verbatim}
+\PretagName[Pierre-Jean]%
+ {\noexpand\Fbox{\noexpand\AltCaps{d}e Smet}}%
+ {de Smet, Pierre-Jean}
+
+\begin{nameauth}
+ \< deSmet & Pierre-Jean &
+ \noexpand\Fbox{\noexpand\AltCaps{d}e Smet} & >
+\end{nameauth}
+\end{verbatim}
+\end{quote}
+
+Now we show how the formatting hooks work in the body text. One can check the index to see that it is formatted properly and consistently.
+
+\begin{center}\footnotesize
+\begin{tabular}{llll}\toprule
+First & Next & Long & Short \\\midrule
+\verb+\deSmet+ & \verb+\deSmet+ & \verb+\LdeSmet+ & \verb+\SdeSmet+\\
+\deSmet & \deSmet & \LdeSmet & \SdeSmet\\
+& \verb+\CapThis+ & \verb+\ForceName+ & \\
+& \CapThis\deSmet & \ForceName\LdeSmet & \\\bottomrule
+\end{tabular}
+\end{center}\smallskip
+\newpage
+
+\begin{center}\bfseries Rolling Your Own: Intermediate\end{center}
+
+\noindent We begin by defining a name composed only of macros:
+\begingroup
+\newif\ifSpecialFN
+\newif\ifSpecialSN
+\newif\ifRevertSN
+\newcommand*\WM{\ifSpecialFN Wm.\else William\fi}
+\newcommand*\SHK{\ifRevertSN \textSC{Shakespeare}\else
+ \ifSpecialSN \noexpand\AltCaps{t}he Bard\else
+ \textSC{Shakespeare}\fi\fi}
+\newcommand*\Revert{\RevertSNtrue}
\makeatletter
\renewcommand*\NamesFormat[1]{%
- #1\unless\ifinner
- \marginpar{\small\raggedleft%
- \@nameauth at FullNametrue%
- \@nameauth at FirstNamefalse%
- \@nameauth at EastFNfalse%
- \NameParser}%
- \fi}
+ \RevertSNfalse\SpecialFNfalse\SpecialSNfalse#1%
+ \unless\ifinner\marginpar{%
+ \footnotesize\raggedleft%
+ \@nameauth at FullNametrue%
+ \@nameauth at FirstNamefalse%
+ \@nameauth at EastFNfalse%
+ \SpecialFNtrue\SpecialSNfalse%
+ \NameParser}%
+ \fi\global\RevertSNfalse}
\renewcommand*\MainNameHook[1]{%
- \AltOff#1\unless\ifinner
- \marginpar{\small\raggedleft%
- \@nameauth at FullNamefalse%
- \@nameauth at FirstNamefalse%
- \@nameauth at EastFNfalse%
- \NameParser}%
- \fi}
+ \AltOff\SpecialFNfalse\SpecialSNtrue#1%
+ \unless\ifinner
+ \unless\ifRevertSN
+ \marginpar{%
+ \footnotesize\raggedleft%
+ \@nameauth at FullNamefalse%
+ \@nameauth at FirstNamefalse%
+ \@nameauth at EastFNfalse%
+ \SpecialFNfalse\SpecialSNfalse%
+ \NameParser}%
+ \fi
+ \fi\global\RevertSNfalse}
\makeatother
+\begin{quote}\small
+\StartNum
+\begin{verbatim}
+\begin{nameauth}
+ \< Shak & \noexpand\WM & \noexpand\SHK & >
+\end{nameauth}
+\PretagName[\noexpand\WM]{\noexpand\SHK}{Shakespeare, William}
+\PretagName[Robert]{\textSC{Burns}}{Burns, Robert}
\end{verbatim}
-\clearpage
+\end{quote}
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-%% Surname index entries in an fbox
-%% First surname instances in text are in an fbox
-%% We can capitalize name within that formatting
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-%%
-%% Below we create a Boolean value \ifFbox and set it true.
-%% This will trigger an fbox
-%%
-%% We then create a macro \Fbox that prints its argument in
-%% an fbox when \ifFbox is true, or makes no change otherwise.
-%%
-%% The \AltCaps macro only capitalizies its argument inside the
-%% formatting hook \NamesFormat below.
-%%
-%% \Namesformat ignores its argument, sets \InHooktrue, then
-%% calls the name parser used specifically in formatting hooks.
-%% \MainNameHook toggles \Fboxfalse to suppress formatting.
-%%
-%%
-\section{Formatting and Capping: Old Style}
+Now we define the flags by which the macros \verb+\WM+ and \verb+\SHK+ can change inside of the formatting macros, and the different values the macros can have:
+\begin{quote}\small
+\ContinueNum
\begin{verbatim}
+\newif\ifSpecialFN
+\newif\ifSpecialSN
+\newif\ifRevertSN
+\newcommand*\WM{\ifSpecialFN Wm.\else William\fi}
+\newcommand*\SHK{\ifRevertSN \textSC{Shakespeare}\else
+ \ifSpecialSN \noexpand\AltCaps{t}he Bard\else
+ \textSC{Shakespeare}\fi\fi}
+\newcommand\Revert{\RevertSNtrue}
+\makeatletter
+\end{verbatim}
+\end{quote}
+
+Finally, we define the formatting hooks that execute these changes:
+\begin{quote}\small
+\ContinueNum
+\begin{verbatim}
+\renewcommand*\NamesFormat[1]{%
+ \RevertSNfalse\SpecialFNfalse\SpecialSNfalse#1%
+ \unless\ifinner\marginpar{%
+ \footnotesize\raggedleft%
+ \@nameauth at FullNametrue%
+ \@nameauth at FirstNamefalse%
+ \@nameauth at EastFNfalse%
+ \SpecialFNtrue\SpecialSNfalse%
+ \NameParser}%
+ \fi\global\RevertSNfalse}
+\end{verbatim}
+
+\begin{verbatim}
+\renewcommand*\MainNameHook[1]{%
+ \AltOff\SpecialFNfalse\SpecialSNtrue#1%
+ \unless\ifinner
+ \unless\ifRevertSN
+ \marginpar{%
+ \footnotesize\raggedleft%
+ \@nameauth at FullNamefalse%
+ \@nameauth at FirstNamefalse%
+ \@nameauth at EastFNfalse%
+ \SpecialFNfalse\SpecialSNfalse%
+ \NameParser}%
+ \fi
+ \fi\global\RevertSNfalse}
+\makeatother
+\end{verbatim}
+
+\smallskip
+\Shak\ (\verb+\Shak+) is the national poet of England in much the same way as \Name[Robert]{\textSC{Burns}} (\verb+\Name[Robert]{\textSC{Burns}}+) is that of Scotland. With the latter's rise of influence in the 1800s, \Revert\Shak\ (\verb+\Revert+\verb+\Shak+) became known as ``\Shak'' (\verb+\Shak+).
+\end{quote}
+\endgroup
+
+First, we establish macros \verb+\WM+ and \verb+\SHK+ in name arguments using \verb+\noexpand+. That will make the index work properly. We use \verb+\PretagName+ to sort the names. Since we need to make some name decisions, we set up three Boolean values. One is for \verb+\WM+ and two are for variations within \verb+\SHK+. The macro \verb+\Revert+ is used to print a canonical last name without a margin note.
+
+In the first-use hook above, we prevent any form except the canonical name via \verb+\RevertSNfalse\SpecialFNfalse\SpecialSNfalse+. The default global state is set by \verb+\AltFormatActive+, so we do not need to modify that. We then print the canonical name in the body text. If not in inner horizontal mode, we print a margin paragraph containing a full name. Yet with \verb+\NameParser+ we print a special form of the personal name with the canonical form of the surname. Both hooks globally set \verb+\RevertSNfalse+ because we want \verb+\Revert+ used on a per-name basis.
+
+The subsequent-use hook uses \verb+\AltOff+ to disable formatting within the hook. Here we do not allow special forenames but we do select special surname forms. Thus, ``the Bard'' will be selected instead of ``Shakespeare''. Yet if we call \verb+\Revert+, we get ``Shakespeare'' in the text, but no margin note.
+\newpage
+
+\begin{center}\bfseries Rolling Your Own: Advanced\end{center}
+
\newif\ifFbox
\newif\ifFirstCap
\newif\ifInHook
\Fboxtrue
+We create three flags. We set \texttt{\textbackslash ifFbox} true; it replaces \texttt{\textbackslash @nameauth at DoAlt}. \texttt{\textbackslash ifFirstCap} replaces \texttt{\textbackslash @nameauth at DoCaps}, which is set by \verb+\CapThis+. The flag \texttt{\textbackslash ifInHook} replaces \texttt{\textbackslash @nameauth at InHook}, which normally is enabled by the internal format hook dispatcher.
+\begin{quote}\small
+\StartNum
+\begin{verbatim}
+\newif\ifFbox
+\newif\ifFirstCap
+\newif\ifInHook
+\Fboxtrue
+\end{verbatim}
+\end{quote}
+\renewcommand*\Fbox[1]{\ifFbox\protect\fbox{#1}\else#1\fi}
+The formatting macro is like what we have seen, except it refers to \texttt{\textbackslash ifFbox}:
+\begin{quote}\small
+\ContinueNum
+\begin{verbatim}
\renewcommand*\Fbox[1]{%
- \ifFbox\fbox{#1}\else#1\fi
+ \ifFbox\protect\fbox{#1}\else#1\fi
}
+\end{verbatim}
+\end{quote}
+\renewcommand*\AltCaps[1]{\ifInHook
+ \ifFirstCap\MakeUppercase{#1}\else#1\fi
+ \else
+ #1\fi}
+Our new \verb+\AltCaps+ works like the built-in version, except it does not use the internal macros and flags:
+\begin{quote}\small
+\ContinueNum
+\begin{verbatim}
\renewcommand*\AltCaps[1]{%
\ifInHook
\ifFirstCap\MakeUppercase{#1}\else#1\fi
@@ -239,49 +1053,113 @@
#1%
\fi
}
+\end{verbatim}
+\end{quote}
-\renewcommand\CapThis{\FirstCaptrue}
+\renewcommand*\CapThis{\FirstCaptrue}
+\renewcommand*\NamesFormat[1]
+{\InHooktrue\NameParser\global\FirstCapfalse}
+\renewcommand*\MainNameHook[1]
+{\Fboxfalse\InHooktrue\NameParser\global\FirstCapfalse}
+\let\FrontNamesFormat\Namesformat
+\let\FrontNameHook\MainNameHook
+Here we redefine \verb+\CapThis+ to use our flag instead of the internal flag:
+\begin{quote}\small
+\ContinueNum
+\begin{verbatim}
+\renewcommand*\CapThis{\FirstCaptrue}
+\end{verbatim}
+\end{quote}
+We have to reproduce the logic and macros that the package would have provided. That means defining everything, including \verb+\NamesFormat+, from scratch:
+\begin{quote}\small
+\ContinueNum
+\begin{verbatim}
\renewcommand*\NamesFormat[1]
{%
- \InHooktrue\NameParser\InHookfalse%
+ \InHooktrue\NameParser%
\global\FirstCapfalse%
}
+\end{verbatim}
+\end{quote}
+Changes to \texttt{\textbackslash ifInHook} (default false) and \texttt{\textbackslash ifFbox} (default true) are local to the scope in which the hook macros are called. \texttt{\textbackslash ifFirstCap} must be \verb+\global+ in order to work correctly. Instead of using just \verb+\AltOff+ before \verb+\NameParser+ below, we have mimic the functions of the internal flags:
+\begin{quote}\small
+\ContinueNum
+\begin{verbatim}
\renewcommand*\MainNameHook[1]
{%
- \Fboxfalse\InHooktrue\NameParser\InHookfalse%
- \global\FirstCapfalse\Fboxtrue%
+ \Fboxfalse\InHooktrue\NameParser%
+ \global\FirstCapfalse%
}
+\end{verbatim}
+\end{quote}
+We avoid spurious index entries in the front matter by using the same hooks.
+\begin{quote}\small
+\ContinueNum
+\begin{verbatim}
\let\FrontNamesFormat\Namesformat
\let\FrontNameHook\MainNameHook
\end{verbatim}
-\clearpage
+\end{quote}
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-%% Migrate new style to old style
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-%%
-%% This is the full example abbreviated in the manual.
-%% Below we create a Boolean value \ifCaps and set it true.
-%% This will trigger small caps.
-%%
-%% We then redefine \textSC to use our flag instead of package internals.
-%% We redefine \AltCaps, \CapThis, and \NamesFormat in the same manner
-%% as above. We change \MainNameHook to use our Caps flag.
-%%
-%%
-\section{Migrating New Style to Old Style}
+Because we use \verb+\noexpand+, our ``old-style'' macros will index the name below under the same entry as the ``new-style'' macros.
+\begin{center}\footnotesize
+\begin{tabular}{llll}\toprule
+First & Next & Long & Short \\\midrule
+\verb+\deSmet+ & \verb+\deSmet+ & \verb+\LdeSmet+ & \verb+\SdeSmet+\\
+\ForgetThis\deSmet & \deSmet & \LdeSmet & \SdeSmet\\
+& \verb+\CapThis+ & \verb+\ForceName+ & \\
+& \CapThis\deSmet & \ForceName\LdeSmet & \\\bottomrule
+\end{tabular}
+\end{center}\smallskip
+
+We can reuse new-style names (above) with old-style macros when needed. We reinstate alternate formatting:
+\AltFormatActive
+
+\newif\ifCaps
+\Capstrue
+\begin{quote}\small
+\StartNum
\begin{verbatim}
-\newif\ifCaps
+\newif\ifFCaps
\newif\ifFirstCap
\newif\ifInHook
\Capstrue
+\end{verbatim}
+\end{quote}
+We redefine the other macros:
\renewcommand*\textSC[1]{%
\ifCaps\textsc{#1}\else#1\fi
}
+\renewcommand*\AltCaps[1]{%
+ \ifInHook
+ \ifFirstCap\MakeUppercase{#1}\else#1\fi
+ \else
+ #1%
+ \fi
+}
+\renewcommand\CapThis{\FirstCaptrue}
+\renewcommand*\NamesFormat[1]
+{%
+ \InHooktrue\NameParser\InHookfalse%
+ \global\FirstCapfalse%
+}
+\renewcommand*\MainNameHook[1]
+{%
+ \Capsfalse\InHooktrue\NameParser\InHookfalse%
+ \global\FirstCapfalse\Capstrue%
+}
+\let\FrontNamesFormat\Namesformat
+\let\FrontNameHook\MainNameHook
+\begin{quote}\small
+\ContinueNum
+\begin{verbatim}
+\renewcommand*\textSC[1]{%
+ \ifCaps\textsc{#1}\else#1\fi
+}
\renewcommand*\AltCaps[1]{%
\ifInHook
@@ -308,4 +1186,192 @@
\let\FrontNamesFormat\Namesformat
\let\FrontNameHook\MainNameHook
\end{verbatim}
-\end{document}
\ No newline at end of file
+\end{quote}
+
+The names below have the same declarations and index entries as they did above. They look and work the same but use different macros.
+\begin{center}
+\small\noindent\begin{tabular}{llll}\toprule
+First & Next & Long & Short \\\midrule
+\ForgetThis\Adams & \Adams & \LAdams & \SAdams\\
+\ForgetThis\SDJR & \SDJR & \LSDJR & \SSDJR\\
+\ForgetThis\HAR & \HAR & \LHAR & \SHAR\\
+\ForgetThis\Mencius & \Mencius & \LMencius & \SMencius\\\bottomrule
+\end{tabular}
+\end{center}
+
+\section{Feature Redesign}
+
+\begin{quote}\small
+\StartNum
+\begin{verbatim}
+\makeatletter
+\newcommandx*\MyName[3][1=\@empty, 3=\@empty]{%
+ \@nameauth at toksa\expandafter{#1}%
+ \@nameauth at toksb\expandafter{#2}%
+ \@nameauth at toksc\expandafter{#3}%
+ \hbox to 4em{Normal: \hfill}%
+ \fbox{\@nameauth at Name[#1]{#2}[#3]}%
+}
+\newcommandx*\MyLName[3][1=\@empty, 3=\@empty]{%
+ \@nameauth at toksa\expandafter{#1}%
+ \@nameauth at toksb\expandafter{#2}%
+ \@nameauth at toksc\expandafter{#3}%
+ \hbox to 4em{Long: \hfill}%
+ \fbox{\@nameauth at Name[#1]{#2}[#3]}%
+}
+\newcommandx*\MyFName[3][1=\@empty, 3=\@empty]{%
+ \@nameauth at toksa\expandafter{#1}%
+ \@nameauth at toksb\expandafter{#2}%
+ \@nameauth at toksc\expandafter{#3}%
+ \hbox to 4em{Short: \hfill}%
+ \fbox{\@nameauth at Name[#1]{#2}[#3]}%
+}
+\makeatother
+\renewcommand*\NamesFormat[1]
+ {\hbox to 9em{\hfil\scshape#1\hfil}}
+\renewcommand*\MainNameHook[1]{\hbox to 9em{\hfil#1\hfil}}
+\renewcommand*\NameauthName{\MyName}
+\renewcommand*\NameauthLName{\MyLName}
+\renewcommand*\NameauthFName{\MyFName}
+\end{verbatim}
+\makeatletter
+\newcommandx*\MyName[3][1=\@empty, 3=\@empty]{%
+ \@nameauth at toksa\expandafter{#1}%
+ \@nameauth at toksb\expandafter{#2}%
+ \@nameauth at toksc\expandafter{#3}%
+ \hbox to 4em{Normal: \hfill}%
+ \fbox{\@nameauth at Name[#1]{#2}[#3]}%
+}
+\newcommandx*\MyLName[3][1=\@empty, 3=\@empty]{%
+ \@nameauth at toksa\expandafter{#1}%
+ \@nameauth at toksb\expandafter{#2}%
+ \@nameauth at toksc\expandafter{#3}%
+ \hbox to 4em{Long: \hfill}%
+ \fbox{\@nameauth at Name[#1]{#2}[#3]}%
+}
+\newcommandx*\MyFName[3][1=\@empty, 3=\@empty]{%
+ \@nameauth at toksa\expandafter{#1}%
+ \@nameauth at toksb\expandafter{#2}%
+ \@nameauth at toksc\expandafter{#3}%
+ \hbox to 4em{Short: \hfill}%
+ \fbox{\@nameauth at Name[#1]{#2}[#3]}%
+}
+\makeatother
+\renewcommand*\NamesFormat[1]
+ {\hbox to 9em{\hfil\scshape#1\hfil}}
+\renewcommand*\MainNameHook[1]{\hbox to 9em{\hfil#1\hfil}}
+\renewcommand*\NameauthName{\MyName}
+\renewcommand*\NameauthLName{\MyLName}
+\renewcommand*\NameauthFName{\MyFName}
+
+\smallskip
+\verb+\ForgetName[Adolf]{Harnack}+\ForgetName[Adolf]{Harnack}\\[1ex]
+\begin{tabular}{@{}rl}
+\verb+\Harnack+ & \Harnack\\
+\verb+\LHarnack[Adolf von]+ & \LHarnack[Adolf von]\\
+\verb+\Harnack+ & \Harnack\\
+\verb+\SHarnack+ & \SHarnack\\
+\end{tabular}
+\end{quote}
+\newpage
+
+\section{\protect\LaTeX\ Engines}
+
+We use \texttt{american} for the language; one should use one's own. We use Latin Modern. We load \textsf{tikz} only in pdf mode to avoid crashing some DVI viewers.
+
+\begin{quote}\small
+\StartNum
+\begin{verbatim}
+\IfFileExists{iftex.sty}{\usepackage{iftex}}{}
+\unless\ifdefined\RequireTUTeX
+ \usepackage{ifxetex}
+ \usepackage{ifluatex}
+ \usepackage{ifpdf}
+\fi
+% Used to create both dvi and pdf output
+\newif\ifDoTikZ % Perhaps not needed
+\ifxetex
+ \usepackage{fontspec}
+ \usepackage{polyglossia}
+ \setdefaultlanguage{american} % Use own language
+ \usepackage{tikz}
+ \DoTikZtrue % Perhaps not needed
+\else
+ \ifluatex
+ \ifpdf
+ \usepackage{fontspec}
+ \usepackage{polyglossia}
+ \setdefaultlanguage{american} % Use own language
+ \usepackage{tikz}
+ \DoTikZtrue % Perhaps not needed
+ \else
+ \IfFileExists{utf8-2018.def}{}
+ {\usepackage[utf8]{inputenc}}
+ \usepackage[TS1,T1]{fontenc}
+ \usepackage[american]{babel} % Use own language
+ \usepackage{lmodern}
+ % Perhaps add \usepackage{tikz}
+ \fi
+ \else
+ \IfFileExists{utf8-2018.def}{}
+ {\usepackage[utf8]{inputenc}}
+ \usepackage[TS1,T1]{fontenc}
+ \usepackage[american]{babel} % Use own language
+ \usepackage{lmodern}
+ \ifpdf % Perhaps not needed
+ \usepackage{tikz}
+ \DoTikZtrue % Perhaps not needed
+ \fi
+ \fi
+\fi
+\end{verbatim}
+\end{quote}
+In the body text we can use something like the test below for \fbox{\ifDoTikZ doing \texttt{pdf} things\else doing \texttt{dvi} things\fi}
+\begin{quote}\small
+\begin{verbatim}
+\ifDoTikZ
+ doing \texttt{pdf} things\else
+ doing \texttt{dvi} things\fi
+\end{verbatim}
+\end{quote}
+\newpage
+
+The following equivalent conditional statements can help a macro or just the body text to work under multiple engines:
+\begin{quote}\small
+\StartNum
+\begin{verbatim}
+\ifxetex xelatex%
+\else
+ \ifluatex
+ \ifpdf lualatex (pdf)%
+ \else lualatex (dvi)%
+ \fi
+ \else
+ \ifpdf pdflatex%
+ \else latex (dvi)%
+ \fi
+ \fi
+\fi
+\end{verbatim}
+
+\StartNum
+\begin{verbatim}
+\unless\ifxetex
+ \unless\ifluatex
+ \ifpdf pdflatex%
+ \else latex (dvi)%
+ \fi
+ \else
+ \ifpdf lualatex (pdf)%
+ \else lualatex (dvi)%
+ \fi
+ \fi
+\else xelatex%
+\fi
+\end{verbatim}
+\end{quote}
+
+\newpage
+\printindex
+
+\end{document}
Deleted: trunk/Master/texmf-dist/doc/latex/nameauth/nameauth.hd
===================================================================
Modified: trunk/Master/texmf-dist/doc/latex/nameauth/nameauth.pdf
===================================================================
(Binary files differ)
Added: trunk/Master/texmf-dist/source/latex/nameauth/Makefile
===================================================================
--- trunk/Master/texmf-dist/source/latex/nameauth/Makefile (rev 0)
+++ trunk/Master/texmf-dist/source/latex/nameauth/Makefile 2020-02-21 22:56:14 UTC (rev 53863)
@@ -0,0 +1,49 @@
+NAME = nameauth
+ENGINE ?= pdflatex
+# or latex, xelatex, lualatex, dvilualatex
+SHELL = bash
+PWD = $(shell pwd)
+VERS = $(shell ltxfileinfo -v $(NAME).dtx|sed -e 's/^v//')
+LOCAL = $(shell kpsewhich --var-value TEXMFLOCAL)
+UTREE = $(shell kpsewhich --var-value TEXMFHOME)
+release: $(NAME).pdf
+testing: $(NAME).pdf examples.pdf
+examples.pdf : examples.tex
+ $(ENGINE) examples >/dev/null
+ if [ -f examples.idx ]; then makeindex -o examples.ind examples.idx; fi
+ $(ENGINE) examples > /dev/null
+$(NAME).pdf : $(NAME).dtx
+ $(ENGINE) -shell-escape -recorder -interaction=batchmode $(NAME).dtx >/dev/null
+ $(ENGINE) --recorder --interaction=nonstopmode $(NAME).dtx > /dev/null
+ if [ -f $(NAME).glo ]; then makeindex -q -s gglo.ist -o $(NAME).gls $(NAME).glo; fi
+ if [ -f $(NAME).idx ]; then makeindex -q -s gind.ist -o $(NAME).ind $(NAME).idx; fi
+ $(ENGINE) --recorder --interaction=nonstopmode $(NAME).dtx > /dev/null
+ $(ENGINE) --recorder --interaction=nonstopmode $(NAME).dtx > /dev/null
+ test -e README.txt && mv README.txt README || exit 0
+clean:
+ rm -f $(NAME).{aux,fls,glo,gls,hd,idx,ilg,ind,ins,log,out,toc} README.txt
+ rm -f examples.{aux,fls,glo,gls,hd,idx,ilg,ind,ins,log,out,toc}
+distclean: clean
+ rm -f $(NAME).{dvi,pdf,sty,synctex.gz} README
+ rm -f examples.{dvi,pdf,sty,synctex.gz}
+inst: release
+ mkdir -p $(UTREE)/{tex,source,doc}/latex/$(NAME)
+ cp $(NAME).dtx $(UTREE)/source/latex/$(NAME)
+ 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)
+ cp README $(UTREE)/doc/latex/$(NAME)
+install: release
+ 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)
+ sudo cp README $(LOCAL)/doc/latex/$(NAME)
+zip: release
+ ln -sf . $(NAME)
+ zip -Drq $(PWD)/$(NAME)-$(VERS).zip $(NAME)/{README,examples.tex,Makefile,$(NAME).{pdf,dtx}}
+ rm $(NAME)
+
Property changes on: trunk/Master/texmf-dist/source/latex/nameauth/Makefile
___________________________________________________________________
Added: svn:eol-style
## -0,0 +1 ##
+native
\ No newline at end of property
Modified: trunk/Master/texmf-dist/source/latex/nameauth/nameauth.dtx
===================================================================
--- trunk/Master/texmf-dist/source/latex/nameauth/nameauth.dtx 2020-02-21 22:55:44 UTC (rev 53862)
+++ trunk/Master/texmf-dist/source/latex/nameauth/nameauth.dtx 2020-02-21 22:56:14 UTC (rev 53863)
@@ -8,7 +8,7 @@
--------:| ----------------------------------------------------------------
nameauth:| Name authority mechanism for consistency in text and index
Author:| Charles P. Schaum
- E-mail:| charles dot schaum at comcast dot net
+ E-mail:| charles dot schaum at comcast.net
License:| Released under the LaTeX Project Public License 1.3c or later
See:| http://www.latex-project.org/lppl.txt
@@ -36,15 +36,9 @@
Unpack nameauth.zip in an appropriate directory.
-Note that the instructions below assume that you are using a kind of
-Unix, BSD, Linux, Mac, or Cygwin under Microsoft Windows. If you have
-a different operating environment, you will need to modify these
-instructions to your own needs. Please be aware that this package is
-designed to be stored in a UTF-8 encoded text file and built in a
-Unicode-capable environment.
+If you have a make utility compatible with GNU make, either in
+GNU/Linux, a BSD variant, OSX, or Cygwin in Windows you can type
-If you have a make utility compatible with GNU make you can type
-
make inst
to install the package into your $TEXMFHOME tree or
@@ -52,54 +46,88 @@
make install
to install the package into your $TEXMFLOCAL tree for all users.
+The latter requires sudo privileges.
-Manually, you can generate the package files. First you generate the
-installer driver, README, and style files, with a preliminary PDF:
+Other useful targets include:
+ (release process)
+
+ make release The default target, same as just ``make''.
+
+ make clean Removes all intermediate files. Left are
+ the files listed above plus nameauth.sty.
+
+ make distclean Leave only nameauth.dtx, examples.tex,
+ and Makefile.
+
+ make zip Generate a zip file ready for distribution.
+
+ (testing process)
+
+ make testing Release files, plus compiles examples.tex.
+
+ make release ENGINE=<command>
+ Here, <command> can be pdflatex (default),
+ xelatex, lualatex, dvilualatex, or latex.
+
+ make testing ENGINE=<command> See above.
+
+It is not necessary, however, to use GNU make. One can generate
+the package files manually. Since the files nameauth.ins and README.txt
+are contained in the .dtx file itself, the first step is to generate
+the installer driver nameauth.ins, plus the file README.txt, which will
+also trigger the extraction of nameauth.sty and produce the first pass of
+the package documentation nameauth.pdf:
+
pdflatex -shell-escape -recorder -interaction=batchmode nameauth.dtx
-Next you generate the PDF with a table of contents and all cross-references
-validated, so that the index entries will not move:
+Next one adds a table of contents and all cross-references, this also
+should finalize page numbers for glossary and index input files:
pdflatex --recorder --interaction=nonstopmode nameauth.dtx
-The next commands generate the glossary/index and final pdf file
+The next commands generate the glossary/index output files:
makeindex -q -s gglo.ist -o nameauth.gls nameauth.glo
makeindex -q -s gind.ist -o nameauth.ind nameauth.idx
+
+The final two commands integrate the glossary (changes) and index:
+
pdflatex --recorder --interaction=nonstopmode nameauth.dtx
pdflatex --recorder --interaction=nonstopmode nameauth.dtx
-Normally you create the following manual installation directories for user:
+Now one can either keep README.txt or rename it to README, e.g.:
+ mv README.txt README
+
+Normally one creates the following directories for a user:
+
$TEXMFHOME/source/latex/nameauth dtx file
$TEXMFHOME/tex/latex/nameauth sty file
$TEXMFHOME/doc/latex/nameauth pdf file, README, examples.tex
-and you create the following manual installation directories for local site:
+and creates the following directories for the local site:
$TEXMFLOCAL/source/latex/nameauth dtx file
$TEXMFLOCAL/tex/latex/nameauth sty file
$TEXMFLOCAL/doc/latex/nameauth pdf file, README, examples.tex
-The above environment variables often are /usr/local/texlive/texmf-local and
-~/texmf.
+The above environment variables often are /usr/local/texlive/texmf-local
+and ~/texmf.
-The make process normally renames the README.txt file created from the dtx file
-to just README by using mv (move/rename utility in the *nix userland). Windows
-distributions of TeX and LaTeX often keep the txt file as well.
+The make process normally renames the README.txt file created from the
+dtx file to just README by using mv (move / rename utility in the *nix
+userland). Windows distributions of TeX and LaTeX often keep the txt file
+because of using file extensions instead of ``magic numbers'' to identify
+files.
-Run mktexlsr with the appropriate level of permissions to complete the install.
+Run mktexlsr with the appropriate level of permissions to complete the
+install.
Testing notes:
-This package and documentation work and build with latex, lualatex, pdflatex,
-and xelatex. It can be used with makeindex/texindy.
+See the nameauth manual.
-For testing, the make file permits one to change the typesetting engine
-on the command line. The default is to build the package and documentation
-with pdflatex. See the make file for details.
-
License
This material is subject to the LaTeX Project Public License:
@@ -123,7 +151,7 @@
--------:| ----------------------------------------------------------------
nameauth:| Name authority mechanism for consistency in text and index
Author:| Charles P. Schaum
- E-mail:| charles dot schaum at comcast dot net
+ E-mail:| charles dot schaum at comcast.net
License:| Released under the LaTeX Project Public License 1.3c or later
See:| http://www.latex-project.org/lppl.txt
@@ -130,12 +158,12 @@
\endpreamble
\postamble
-Copyright (C) 2017 by Charles P. Schaum <charles dot schaum at comcast dot net>
+Copyright (C) 2020 by Charles P. Schaum <charles dot schaum at comcast.net>
-This work may be distributed and/or modified under the
+This work may be distributed and / or modified under the
conditions of the LaTeX Project Public License (LPPL), either
version 1.3c of this license or (at your option) any later
-version. The latest version of this license is in the file:
+version. The latest version of this license is in the file:
http://www.latex-project.org/lppl.txt
@@ -143,10 +171,9 @@
Charles P. Schaum.
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.
-
+These files generate README.txt / README, nameauth.ins, nameauth.sty, and
+nameauth.pdf, with other intermediate files, as a part of this work. See
+the README.txt or README for more information.
\endpostamble
\usedir{tex/latex/nameauth}
@@ -180,247 +207,359 @@
%<package>\NeedsTeXFormat{LaTeX2e}[1999/12/01]
%<package>\ProvidesPackage{nameauth}
%<*package>
- [2017/03/22 3.2 Name authority mechanism for consistency in text and index]
+ [2020/02/20 3.3 Name authority mechanism for consistency in text and index]
%</package>
%<*driver>
\documentclass[11pt]{ltxdoc}
-\usepackage[textwidth=137mm,textheight=237mm,right=25mm,marginparwidth=40mm,nohead]{geometry}
-\usepackage{ifxetex}
-\usepackage{ifluatex}
-\usepackage{ifpdf}
-\ifdefined\Umathchar
+%^^A Below we check if our TL distribution has the iftex package and load it.
+\IfFileExists{iftex.sty}{\usepackage{iftex}}{}
+%^^A Only versions of iftex since 2019 have the macro \RequireTUTeX.
+%^^A If the package is not loaded or if it is not new,
+%^^A we load the older, transitional packages.
+\unless\ifdefined\RequireTUTeX
+ \usepackage{ifxetex}
+ \usepackage{ifluatex}
+ \usepackage{ifpdf}
+\fi
+\ifxetex %^^A \ifpdf will not be true, but a pdf results.
\usepackage{fontspec}
\usepackage{polyglossia}
\setdefaultlanguage{american}
\setotherlanguage{german}
\newcommand\de[1]{\textgerman{#1}}
+ \usepackage{tikz}
+ \usepackage{tcolorbox}
\else
- \usepackage[utf8]{inputenc}
- \usepackage[TS1,T1]{fontenc}
- \usepackage{newunicodechar}
- \usepackage{lmodern}
- \DeclareTextSymbolDefault{\textlongs}{TS1}
- \DeclareTextSymbol{\textlongs}{TS1}{115}
- \newunicodechar{ſ}{\textlongs}
- \usepackage[ngerman,american]{babel}
- \newcommand\de[1]{\foreignlanguage{ngerman}{#1}}
+ \ifluatex
+ \ifpdf %^^A pdf mode
+ \usepackage{fontspec}
+ \usepackage{polyglossia}
+ \setdefaultlanguage{american}
+ \setotherlanguage{german}
+ \newcommand\de[1]{\textgerman{#1}}
+ \usepackage{tikz}
+ \usepackage{tcolorbox}
+ \else %^^A dvi mode
+ \IfFileExists{utf8-2018.def}{}{\usepackage[utf8]{inputenc}}
+ \usepackage[TS1,T1]{fontenc}
+ \usepackage[ngerman,american]{babel}
+ \newcommand\de[1]{\foreignlanguage{ngerman}{#1}}
+ \usepackage{lmodern}
+ \usepackage{newunicodechar}
+ \DeclareTextSymbolDefault{\textlongs}{TS1}
+ \DeclareTextSymbol{\textlongs}{TS1}{115}
+ \newunicodechar{ſ}{\textlongs}
+ \fi
+ \else %^^A These packages work for both pdf and dvi.
+ \IfFileExists{utf8-2018.def}{}{\usepackage[utf8]{inputenc}}
+ \usepackage[TS1,T1]{fontenc}
+ \usepackage[ngerman,american]{babel}
+ \newcommand\de[1]{\foreignlanguage{ngerman}{#1}}
+ \usepackage{lmodern}
+ \usepackage{newunicodechar}
+ \DeclareTextSymbolDefault{\textlongs}{TS1}
+ \DeclareTextSymbol{\textlongs}{TS1}{115}
+ \newunicodechar{ſ}{\textlongs}
+ \ifpdf %^^A These only get included for pdf.
+ \usepackage{tikz}
+ \usepackage{tcolorbox}
+ \fi
+ \fi
\fi
-\usepackage{\jobname}
+%^^A Set up initial page layout to fit both letter and DIN A4.
+\usepackage[textwidth=137mm,textheight=237mm,right=25mm,marginparwidth=40mm,nohead]{geometry}
+%^^A Include only this version of the package.
+\usepackage{\jobname}[2020/02/20]
+%^^A Set up all tabular information.
\usepackage{booktabs}
+\usepackage{colortbl}
+\usepackage{tabularx}
+%^^A Set up lists.
\usepackage{enumitem}
+\setlist{rightmargin=\leftmargin,itemsep=0pt}
+%^^A Create indexes and set up the ``actual'' character in nameauth.
\usepackage{makeidx}
+\IndexActual{=}
+%^^A Dangerous bend ahead...
\usepackage{manfnt}
+%^^A Two-column TOC
\usepackage[toc]{multitoc}
+%^^A Some examples get some stretch to aid clarity and readability.
\usepackage{setspace}
-\ifxetex\usepackage{tikz}\else\ifpdf\usepackage{tikz}\fi\fi
+%^^A Color helps categorize information.
\usepackage{xcolor}
-\colorlet{naviolet}{violet!80!black}
-\colorlet{nagreen}{green!40!black}
-\colorlet{naolive}{olive!90!black}
-\colorlet{naorange}{orange!50!black}
-\colorlet{nared}{red!60!black}
+\colorlet{nared}{red!50!black}
+\colorlet{nagreen}{green!35!black}
+\colorlet{nablue}{blue!50!black}
+\colorlet{nabrown}{brown!55!black}
+\colorlet{naviolet}{violet!90!black}
+\colorlet{nataupe}{yellow!40!black}
+\colorlet{naslate}{cyan!45!black}
+%^^A For example...
+\usepackage{verbatim}
+%^^A Have documentation with hyperlinks
\usepackage[numbered]{hypdoc}
+
+%^^A Let verbatim environments be numbered or unnumbered, and start or resume that.
\makeatletter
-\newcommand\NO{\@ifstar%
-{\textcolor{nared}{\large\strut {\hbox to 2.5em{\hfil\S\textsf{No}\hfil}}}}{\textcolor{nared}{\large\strut {\hbox to 2.5em{\hfil\textsf{No}\hfil}}}}}
-\newcommand\YES{\@ifstar%
-{\textcolor{nagreen}{\large\strut\bfseries \fbox{\hbox to 2.1em{\hfil*\textsf{Yes}\hfil}}}}{\textcolor{nagreen}{\large\strut\bfseries \fbox{\hbox to 2.1em{\hfil\textsf{Yes}\hfil}}}}}
+\newcommand*\ClearNum{%^^A
+ \newcounter{VerbLine}\setcounter{VerbLine}{0}%^^A
+ \def\verbatim at processline{\expandafter\@gobble\the\verbatim at line\par}%^^A
+}
+\newcommand*\StartNum{%^^A
+ \setcounter{VerbLine}{0}
+ \def\verbatim at processline{\stepcounter{VerbLine}\leavevmode%^^A
+ \llap{\footnotesize\normalfont\theVerbLine\quad}%^^A
+ \expandafter\@gobble\the\verbatim at line\par}%^^A
+}
+\newcommand*\ContinueNum{%^^A
+ \def\verbatim at processline{\stepcounter{VerbLine}\leavevmode%^^A
+ \llap{\footnotesize\normalfont\theVerbLine\quad}%^^A
+ \expandafter\@gobble\the\verbatim at line\par}%^^A
+}
\makeatother
-\setlist{rightmargin=\leftmargin,itemsep=0pt}
-\frenchspacing
-\DisableCrossrefs
-\CodelineIndex
-\RecordChanges
+
+%^^A Use color indicators in a couple of tables.
+\newcommand\NO{\bgroup\color{lightgray}\lower 0.075ex\hbox{\rule{1.5ex}{1.5ex}}\egroup}
+\newcommand\YES{\bgroup\color{darkgray}\lower 0.075ex\hbox{\rule{1.5ex}{1.5ex}}\egroup}
+
+%^^A Stretch out some text for clarity.
+\newcommand*\MyStretch{\setstretch{1.1}}
+\newcommand*\MySmallStretch{\setstretch{1.05}}
+
+%^^A Return link to the task dashboard.
+\newcommand*\BigBlank{{\large\itshape\vfil\leavevmode\hfil This space is intentionally left blank.}}
+
+%^^A Macros for marginalia.
+\newcommand*\Version[1]{\unless\ifinner\marginpar{\strut\raggedleft\textsf{\bfseries#1}}\fi}
+\newcommand*\VersionWarn[1]{{\unless\ifinner\marginpar{\strut\raggedleft\textsf{\bfseries#1}\break\small\dbend}\fi}}
+\newcommand*\Warn{{\unless\ifinner\marginpar{\strut\small\raggedleft\dbend}\fi}}
+\newcommand*\Info[1]{{\unless\ifinner\marginpar{\strut\small\raggedleft#1}\fi}}
+
+%^^A Use this example in the body text.
+\newcommand\Orphan[2]{#1(\hyperpage{#2})}
+\TagName[Lost]{Name}{\,\S|Orphan{perdit}}
+\TagName{foo\Name {bar}}{\,\S|hyperpage}
+
+%^^A Redefine emphasis in the body text
+\let\oldemph\emph
+\let\emph\textbf
+
+%^^A Struts for framed boxes
+\newcommand*{\mystrut}{\rule[-0.25\baselineskip]{0pt}{\baselineskip}}
+
+%^^A Set up all the shorthands, but not all the names.
\begin{nameauth}
- \< Cath & Catherine \noexpand\AltCaps{d}e'
- & \noexpand\textSC{Medici} & >
+ \< Adams & John & \noexpand\textSC{Adams} & >
\< Aeth & & Æthelred, II & >
- \< Unraed & & Æthelred, II & Unrædig >
\< Anth & Susan B. & Anthony & >
\< Aris & & Aristotle & >
\< Attil & & Attila, the Hun & >
\< Cicero & M.T. & Cicero & >
\< Confucius & & Confucius & >
- \< Mencius & & \noexpand\textSC{Mencius} & >
\< Dagb & & Dagobert & I >
+ \< SDJR & Sammy & \noexpand\textSC{Davis}, \noexpand\textSC{Jr}. & >
\< Dem & & Demetrius, I & >
- \< deSmet & Pierre-Jean &
- \noexpand\Fbox{\noexpand\AltCaps{d}e Smet} & >
+ \< deSmet & Pierre-Jean & \noexpand\Fbox{\noexpand\AltCaps{d}e Smet} & >
+ \< Soto & Hernando & de Soto & >
+ \< DuBois & W.E.B. & Du~Bois & >
+ \< AltDuBois & W.E.B. & DuBois & >
\< Einstein & Albert & Einstein & >
\< Eliz & & Elizabeth, I & >
\< Fukuyama & & \textUC{Fukuyama}, Takeshi & >
+ \< OFukuyama & & \textUC{Fukuyama} & Takeshi >
+ \< JWG & J.W. von & Goethe & >
+ \< HAR & & Harun, \noexpand\textSC{\noexpand\AltCaps{a}l-Rashid} & >
\< Harnack & Adolf & Harnack & >
\< Henry & & Henry & VIII >
- \< JayR & John David & Rockefeller, IV & Jay >
- \< Adams & John & \noexpand\textSC{Adams} & >
- \< JRIII & John David & \textSC{Rockefeller},\textSC{III} & >
- \< JRIV & John David & Rockefeller, IV & >
- \< JWG & J.W. von & Goethe & >
- \< KempMed & & Thomas, à~Kempis & >
- \< KempAlt & & Thomas & à~Kempis >
- \< KempW & Thomas & à~Kempis & >
- \< Konoe & Fumimaro & Konoe & >
+ \< Jeff & Thomas & \noexpand\JEFF & >
+ \< Lewis & Clive Staples & Lewis & >
\< CSL & Clive Staples & Lewis & C.S. >
- \< Lewis & Clive Staples & Lewis & >
\< Luth & Martin & \noexpand\textSC{Luther} & >
+ \< Cath & Catherine \noexpand\AltCaps{d}e' & \noexpand\textSC{Medici} & >
+ \< Mencius & & \noexpand\textSC{Mencius} & >
\< Miyaz & & Miyazaki, Hayao & >
\< MSens & & Miyazaki, Hayao & Sensei >
- \< OFukuyama & & \textUC{Fukuyama} & Takeshi >
+ \< Noguchi & Hideyo & Noguchi & >
\< Pat & George S. & Patton, Jr. & >
- \< HAR & & Harun, \noexpand\textSC%
- {\noexpand\AltCaps{a}l-Rashid} & >
- \< SDJR & Sammy & \noexpand\textSC{Davis},
- \noexpand\textSC{Jr}. & >
- \< Soto & Hernando & de Soto & >
- \< Striet & John & Strie\-tel\-meier & >
- \< Strieti & John & \de{Strietelmeier} & >
+ \< JRIII & John David & \textSC{Rockefeller},\textSC{III} & >
+ \< JRIV & John David & Rockefeller, IV & >
+ \< JayR & John David & Rockefeller, IV & Jay >
+ \< Scipio & \noexpand\SCIPi & \noexpand\SCIPii & >
+ \< OScipio & Publius & \noexpand\CSA & >
+ \< Shak & \noexpand\WM & \noexpand\SHK & >
+ \< Striet & John & \de{Strietelmeier} & >
+ \< Ches & Chesley B. & Sullenberger, III & >
+ \< Sully & Chesley B. & Sullenberger, III & Sully >
+ \< Sun & & Sun, Yat-sen & >
+ \< KempMed & & Thomas, à~Kempis & >
+ \< KempW & Thomas & à~Kempis & >
+ \< Tyson & Mike & Tyson & >
+ \< Iron & Mike & Tyson & Iron Mike >
\< VBuren & Martin & Van Buren & >
- \< Sun & & Sun, Yat-sen & >
\< Wash & George & Washington & >
- \< Washs & George & Washington's & >
\< White & E.\,B. & White & >
\< Yamt & & Yamamoto, Isoroku & >
\< Yosh & & Yoshida & Shigeru >
\end{nameauth}
-\ExcludeName[George]{Washington's}
+
+%^^A Add sort tags for those needing them.
+\PretagName[John]{\noexpand\textSC{Adams}}{Adams, John}
+\PretagName{Æthelred, II}{Aethelred 2}
+\PretagName{Atatürk}{Ataturk}
+\PretagName{\textit{Doctor mellifluus}}{Doctor mellifluus}
+\PretagName[Charles]{\textBF{Babbage}}{Babbage, Charles}
+\PretagName{Bo\"ethius}{Boethius}
+\PretagName[Robert]{\textSC{Burns}}{Burns, Robert}
+\PretagName[Giovanni]{d'Andrea}{Dandrea, Giovanni}
+\PretagName[Sammy]{\noexpand\textSC{Davis}, \noexpand\textSC{Jr}.}{Davis, Sammy, Jr.}
\PretagName{Demetrius, I}{Demetrius 1}
+\PretagName[Jacques]{De~Pamele}{Depamele, Jacques}
+\PretagName[Pierre-Jean]{\noexpand\Fbox{\noexpand\AltCaps{d}e Smet}}{desmet, Pierre-Jean}
+\PretagName[Hernando]{de Soto}{Desoto, Hernando}
+\PretagName[W.E.B.]{Du~Bois}{Dubois, W.E.B.}
+\PretagName[W.E.B.]{DuBois}{Dubois, W.E.B.}
+\PretagName[Charles]{du Fresne}{Dufresne, Charles}
+\PretagName{du Cange}{Ducange}
\PretagName{Elizabeth, I}{Elizabeth 1}
-\PretagName{Friedrich, I}{Friedrich 1}
-\PretagName[Catherine \noexpand\AltCaps{d}e']
- {\noexpand\textSC{Medici}}{Medici, Catherine de}
-\PretagName[E.\,B.]{White}{White, E. B.}
+\PretagName{\textUC{Fukuyama}, Takeshi}{Fukuyama Takeshi}
+\PretagName[Greta]{\textSC{Garbo}}{Garbo, Greta}
+\PretagName{Ghazāli}{Ghazali}
+\PretagName{Harun, \noexpand\textSC{\noexpand\AltCaps{a}l-Rashid}}{Harun Alrashid}
+\PretagName[Thomas]{\noexpand\JEFF}{Jefferson, Thomas}
+\PretagName[Ada]{\textIT{Lovelace}}{Lovelace, Ada}
+\PretagName[Jan]{Łukasiewicz}{Lukasiewicz, Jan}
\PretagName[Martin]{\noexpand\textSC{Luther}}{Luther, Martin}
-\PretagName[Greta]{\textSC{Garbo}}{Garbo, Greta}
+\PretagName[Catherine \noexpand\AltCaps{d}e']{\noexpand\textSC{Medici}}{Medici, Catherine de}
+\PretagName{\noexpand\textSC{Mencius}}{Mencius}
+\PretagName{\noexpand\textSC{Meng}, Ke}{Meng Ke}
+\PretagName[Frenec]{Molnár}{Molnar, Frenec}
+\PretagName[John David]{\textSC{Rockefeller},\textSC{III}}{Rockefeller, John David 3}
+\PretagName[John David]{Rockefeller, IV}{Rockefeller, John David 4}
\PretagName[Heinrich Wilhelm]{\textSC{Rühmann}}{Ruehmann, Heinrich Wilhelm}
+\PretagName[\noexpand\SCIPi]{\noexpand\SCIPii}{Scipio Africanus}
+\PretagName[Publius]{\noexpand\CSA}{Cornelius Scipio Africanus}
+\PretagName[\noexpand\WM]{\noexpand\SHK}{Shakespeare, William}
\PretagName[Heinz]{\textSC{Rühmann}}{Ruehmann, Heinz}
-\PretagName[Jan]{Łukasiewicz}{Lukasiewicz, Jan}
-\PretagName[John David]{\textSC{Rockefeller},\textSC{III}}
- {Rockefeller, John David 3}
-\PretagName[John David]{Rockefeller, IV}{Rockefeller, John David 4}
-\PretagName[John]{\noexpand\textSC{Adams}}{Adams, John}
-\PretagName[John]{Strie\-tel\-meier}{Strietelmeier, John}
+\PretagName{\textit{Snellius}}{Snellius}
\PretagName[John]{\de{Strietelmeier}}{Strietelmeier, John}
-\PretagName[Pierre-Jean]%
- {\noexpand\Fbox{\noexpand\AltCaps{d}e Smet}}%
- {de Smet, Pierre-Jean}
-\PretagName[Sammy]
- {\noexpand\textSC{Davis}, \noexpand\textSC{Jr}.}
- {Davis, Sammy, Jr.}
+\PretagName{Thomas, à~Kempis}{Thomas Akempis}
+\PretagName[Thomas]{à~Kempis}{Akempis, Thomas}
\PretagName{\textUC{Tokugawa}, Ieyasu}{Tokugawa Ieyasu}
-\PretagName{Bo\"ethius}{Boethius}
-\PretagName[Ada]{\textIT{Lovelace}}{Lovelace, Ada}
-\PretagName[Charles]{\textBF{Babbage}}{Babbage, Charles}
-\PretagName{\noexpand\textSC{Meng}, Ke}{Meng Ke}
-\PretagName{\noexpand\textSC{Mencius}}{Mencius}
-\PretagName{\textUC{Fukuyama}, Takeshi}{Fukuyama, T}
-\PretagName{Harun, \noexpand\textSC%
- {\noexpand\AltCaps{a}l-Rashid}}{Harun al-Rashid}
-\PretagName{Æthelred, II}{Aethelred 2}
-\PretagName{Atatürk}{Ataturk}
-\PretagName{Thomas, à~Kempis}{Thomas a Kempis}
\PretagName{Vlad, Ţepeş}{Vlad Tepes}
-\PretagName[Frenec]{Molnár}{Molnar, Frenec}
-\PretagName[Wm.]{\noexpand\textSC{Shakespeare}}{Shakespeare, William}
-\TagName[e.e.]{cummings}{|hyperpage}
-\TagName[Martin]{Van Buren}{, pres.|hyperpage}
-\TagName[Frenec]{Molnár}{\dag|hyperpage}
-\TagName[Martin]{\noexpand\textSC{Luther}}{|hyperpage}
-\TagName{\textUC{Tokugawa}, Ieyasu}{|hyperpage}
-\TagName[Ada]{\textIT{Lovelace}}{|hyperpage}
-\TagName[Charles]{\textBF{Babbage}}{|hyperpage}
-\TagName{Bo\"ethius}{|hyperpage}
-\TagName[Susan B.]{Anthony}{|hyperpage}
-\TagName[Adolf]{Harnack}{|hyperpage}
-\TagName[Albert]{Einstein}{|hyperpage}
-\TagName[Bob]{Hope}{|hyperpage}
-\TagName[Catherine \noexpand\AltCaps{d}e']{\noexpand\textSC{Medici}}{|hyperpage}
-\TagName[Charles]{du Fresne}{|hyperpage}
-\TagName[Charlie]{Chaplin}{|hyperpage}
-\TagName[Chesley B.]{Sullenberger, III}{|hyperpage}
-\TagName[Clive Staples]{Lewis}{|hyperpage}
-\TagName[Dan]{Luecking}{|hyperpage}
-\TagName[E.\,B.]{White}{|hyperpage}
-\TagName[Enrico]{Gregorio}{|hyperpage}
-\TagName{Friedrich, I}{ Barbarossa, emperor|hyperpage}
-\TagName[Fumimaro]{Konoe}{\dag, PM|hyperpage}
-\TagName[George S.]{Patton, Jr.}{|hyperpage}
-\TagName[George]{Eliot}{|hyperpage}
-\TagName[George]{Washington}{, pres.|hyperpage}
-\TagName[Greta]{\textSC{Garbo}}{|hyperpage}
-\TagName[Heiko]{Oberdiek}{|hyperpage}
-\TagName[Heinz]{\textSC{Rühmann}}{|hyperpage}
-\TagName[Hernando]{de Soto}{|hyperpage}
-\TagName[J.E.]{Carter, Jr.}{, pres.|hyperpage}
-\TagName[J.W. von]{Goethe}{|hyperpage}
-\TagName[Jan]{Łukasiewicz}{|hyperpage}
-\TagName[Jesse]{Ventura}{|hyperpage}
-\TagName[John David]{\textSC{Rockefeller},\textSC{III}}{|hyperpage}
-\TagName[John David]{Rockefeller, IV}{|hyperpage}
-\TagName[John Maynard]{Keynes}{|hyperpage}
+\PretagName[E.\,B.]{White}{White, E.B.}
+
+%^^A Add index tags for all names.
\TagName[John]{\noexpand\textSC{Adams}}{, pres.|hyperpage}
-\TagName[John]{Smith}{*|hyperpage}
-\TagName[John]{Strie\-tel\-meier}{|hyperpage}
-\TagName[John]{\de{Strietelmeier}}{|hyperpage}
-\TagName[Lafcadio]{Hearn}{|hyperpage}
-\TagName[Louis]{Gossett, Jr.}{|hyperpage}
-\TagName[M.T.]{Cicero}{|hyperpage}
-\TagName[Marc van]{Dongen}{|hyperpage}
-\TagName[Mark]{Twain}{|hyperpage}
-\TagName[Martin Luther]{King, Jr.}{|hyperpage}
-\TagName[Mike]{Tyson}{|hyperpage}
-\TagName[Mustafa]{Kemal}{|hyperpage}
-\TagName[Nicolas]{Malebranche}{|hyperpage}
-\TagName[Oskar]{Hammerstein, II}{|hyperpage}
-\TagName[Philipp]{Stephani}{|hyperpage}
-\TagName[Pierre-Jean]{\noexpand\Fbox{\noexpand\AltCaps{d}e Smet}}{|hyperpage}
-\TagName[Robert]{Schlicht}{|hyperpage}
-\TagName[Rudolph]{Carnap}{|hyperpage}
-\TagName[R.]{Snel van Royen}{|hyperpage}
-\TagName[Sammy]{\noexpand\textSC{Davis}, \noexpand\textSC{Jr}.}{|hyperpage}
-\TagName[Schuyler]{Colfax}{, v.p.|hyperpage}
-\TagName[The Amazing]{Kreskin}{|hyperpage}
-\TagName[Ulysses S.]{Grant}{, pres.|hyperpage}
-\TagName[Uwe]{Lueck}{|hyperpage}
-\TagName[W.E.B.]{Du Bois}{|hyperpage}
-\TagName[W.]{Snel van Royen}{|hyperpage}
-\TagName[Yoko]{Kanno}{\dag|hyperpage}
-\TagName{\noexpand\textSC{Mencius}}{|hyperpage}
-\TagName{\textUC{Fukuyama}, Takeshi}{|hyperpage}
\TagName{Æthelred, II}{, king|hyperpage}
+\TagName[Susan B.]{Anthony}{|hyperpage}
\TagName{Arai, Akino}{|hyperpage}
\TagName{Aristotle}{|hyperpage}
\TagName{Attila, the Hun}{|hyperpage}
+\TagName[Charles]{\textBF{Babbage}}{|hyperpage}
\TagName{Bernard, of Clairvaux}{|hyperpage}
-\TagName{Boris, the Animal}{*|hyperpage}
+\TagName{Bo\"ethius}{|hyperpage}
+\TagName[Robert]{\textSC{Burns}}{|hyperpage}
+\TagName[Rudolph]{Carnap}{|hyperpage}
+\TagName[J.E.]{Carter, Jr.}{, pres.|hyperpage}
+\TagName[Charlie]{Chaplin}{|hyperpage}
+\TagName[M.T.]{Cicero}{|hyperpage}
\TagName{Chiang}[Kai-shek]{\ddag, pres.|hyperpage}
+\TagName[Schuyler]{Colfax}{, v.p.|hyperpage}
\TagName{Confucius}{|hyperpage}
+\TagName[e.e.]{cummings}{|hyperpage}
\TagName{Dagobert}[I]{\ddag, king|hyperpage}
+\TagName[Giovanni]{d'Andrea}{|hyperpage}
+\TagName[Sammy]{\noexpand\textSC{Davis}, \noexpand\textSC{Jr}.}{|hyperpage}
\TagName{Demetrius, I}{ Soter, king|hyperpage}
+\TagName[Jacques]{De~Pamele}{|hyperpage}
+\TagName[Pierre-Jean]{\noexpand\Fbox{\noexpand\AltCaps{d}e Smet}}{|hyperpage}
+\TagName[Hernando]{de Soto}{|hyperpage}
+\TagName[Marc van]{Dongen}{|hyperpage}
+\TagName[W.E.B.]{Du~Bois}{|hyperpage}
+\TagName[Charles]{du Fresne}{|hyperpage}
+\TagName[Albert]{Einstein}{|hyperpage}
\TagName{Elizabeth, I}{, queen|hyperpage}
+\TagName{\textUC{Fukuyama}, Takeshi}{|hyperpage}
+\TagName[Greta]{\textSC{Garbo}}{|hyperpage}
+\TagName{Ghazāli}{|hyperpage}
+\TagName{Ghazali}{|hyperpage}
+\TagName[J.W. von]{Goethe}{|hyperpage}
+\TagName[Louis]{Gossett, Jr.}{|hyperpage}
+\TagName[Ulysses S.]{Grant}{, pres.|hyperpage}
+\TagName[Enrico]{Gregorio}{|hyperpage}
\TagName{Gregory, I}{, pope|hyperpage}
+\TagName[Oskar]{Hammerstein, II}{|hyperpage}
+\TagName[Adolf]{Harnack}{|hyperpage}
\TagName{Harun, \noexpand\textSC{\noexpand\AltCaps{a}l-Rashid}}{|hyperpage}
+\TagName[Lafcadio]{Hearn}{|hyperpage}
\TagName{Henry}[VIII]{\ddag, king|hyperpage}
+\TagName[Bob]{Hope}{|hyperpage}
\TagName{Ishida}[Yoko]{\ddag|hyperpage}
-\TagName{John, Eriugena}{|hyperpage}
+\TagName[Thomas]{\noexpand\JEFF}{, pres.|hyperpage}
+\TagName{Jesus, Christ}{|hyperpage}
+\TagName[Yoko]{Kanno}{\dag|hyperpage}
+\TagName[Mustafa]{Kemal}{|hyperpage}
+\TagName[John Maynard]{Keynes}{|hyperpage}
+\TagName[Martin Luther]{King, Jr.}{|hyperpage}
+\TagName[The Amazing]{Kreskin}{|hyperpage}
\TagName{Lao-tzu}{|hyperpage}
\TagName{Leo, I}{, pope|hyperpage}
+\TagName[Clive Staples]{Lewis}{|hyperpage}
\TagName{Louis, XIV}{, king|hyperpage}
+\TagName[Ada]{\textIT{Lovelace}}{|hyperpage}
+\TagName[Uwe]{Lueck}{|hyperpage}
+\TagName[Dan]{Luecking}{|hyperpage}
+\TagName[Jan]{Łukasiewicz}{|hyperpage}
+\TagName[Martin]{\noexpand\textSC{Luther}}{|hyperpage}
\TagName{Maimonides}{|hyperpage}
+\TagName[Nicolas]{Malebranche}{|hyperpage}
+\TagName[Catherine \noexpand\AltCaps{d}e']{\noexpand\textSC{Medici}}{|hyperpage}
+\TagName{\noexpand\textSC{Mencius}}{|hyperpage}
\TagName{Miyazaki, Hayao}{|hyperpage}
+\TagName[Frenec]{Molnár}{\dag|hyperpage}
+\TagName[Hideyo]{Noguchi}{\dag|hyperpage}
+\TagName[Heiko]{Oberdiek}{|hyperpage}
+\TagName[George S.]{Patton, Jr.}{|hyperpage}
+\TagName[Lucius]{Sergius Paulus}{|hyperpage}
\TagName{Rambam}{|hyperpage}
+\TagName[John David]{\textSC{Rockefeller},\textSC{III}}{|hyperpage}
+\TagName[John David]{Rockefeller, IV}{|hyperpage}
+\TagName[Heinz]{\textSC{Rühmann}}{|hyperpage}
+\TagName{Saul, of Tarsus}{|hyperpage}
+\TagName[Robert]{Schlicht}{|hyperpage}
+\TagName[\noexpand\SCIPi]{\noexpand\SCIPii}{|hyperpage}
+\TagName[Publius]{\noexpand\CSA}{|hyperpage}
+\TagName[\noexpand\WM]{\noexpand\SHK}{|hyperpage}
+\TagName[R.]{Snel van Royen}{|hyperpage}
+\TagName[W.]{Snel van Royen}{|hyperpage}
+\TagName[Philipp]{Stephani}{|hyperpage}
+\TagName[John]{\de{Strietelmeier}}{|hyperpage}
+\TagName[Chesley B.]{Sullenberger, III}{|hyperpage}
\TagName{Sun, Yat-sen}{, pres.|hyperpage}
\TagName{Thomas, à~Kempis}{|hyperpage}
\TagName{Thomas, Aquinas}{|hyperpage}
-\TagName{Vlad II, Dracul}{|hyperpage}
-\TagName{Vlad III, Dracula}{|hyperpage}
+\TagName{\textUC{Tokugawa}, Ieyasu}{|hyperpage}
+\TagName[Mark]{Twain}{|hyperpage}
+\TagName[Mike]{Tyson}{|hyperpage}
+\TagName[Martin]{Van Buren}{, pres.|hyperpage}
+\TagName[Jesse]{Ventura}{|hyperpage}
+\TagName{Vlad, II}{ Dracul|hyperpage}
+\TagName{Vlad, III}{ Dracula|hyperpage}
\TagName{Voltaire}{|hyperpage}
+\TagName[George]{Washington}{, pres.|hyperpage}
+\TagName[E.\,B.]{White}{|hyperpage}
\TagName{William, I}{|hyperpage}
\TagName{Yamamoto, Isoroku}{|hyperpage}
\TagName{Yohko}{|hyperpage}
\TagName{Yoshida}[Shigeru]{\ddag, PM|hyperpage}
-\TagName[Wm.]{\noexpand\textSC{Shakespeare}}{|hyperpage}
-\NameAddInfo{Friedrich, I}{Barbarossa}
-\IndexActual{=}
+\TagName[Caspar]{Ziegler}{|hyperpage}
+
+\DisableCrossrefs
+\CodelineIndex
+\RecordChanges
+\frenchspacing
+
\begin{document}
\DocInput{\jobname.dtx}
\end{document}
@@ -427,7 +566,7 @@
%</driver>
% \fi
%
-% \CheckSum{3502}
+% \CheckSum{3799}
%
% \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
@@ -446,818 +585,1121 @@
% Right brace \} Tilde \~}
%
% \changes{0.7}{2011/12/26}{Initial release}
-% \changes{2.0}{2015/11/11}{Use dtxgen template; prevent malformed input}
-% \changes{2.5}{2016/04/06}{No default formatting}
-% \changes{2.6}{2016/09/19}{Fix older syntax}
-% \changes{3.1}{2017/01/13}{Fix logic, arg tests}
-% \changes{3.2}{2017/03/22}{Use \cmd{\MakeUppercase} instead of \cmd{\uppercase}}
+% \changes{1.0}{2012/02/20}{Works with \textsf{microtype}, \textsf{memoir}}
+% \changes{2.0}{2015/11/11}{Use dtxgen; prevent bad args}
+% \changes{2.5}{2016/04/06}{No default format}
+% \changes{3.3}{2020/02/20}{Update manual}
+%
% \GetFileInfo{\jobname.dtx}
-% \DoNotIndex{\@empty, \@gobble, \@period, \@token, \trim at spaces, \zap at 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}
%
+% \DoNotIndex{\@empty, \@gobble, \@period, \@token, \trim at spaces,
+% \zap at 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\ifNoTag
% \newif\ifDoTikZ
-% \newif\ifNoTag
+% \ifxetex
+% \DoTikZtrue
+% \else
+% \ifluatex
+% \ifpdf
+% \DoTikZtrue
+% \fi
+% \else
+% \ifpdf
+% \DoTikZtrue
+% \fi
+% \fi
+% \fi
+%
+% \ClearNum
+% \ifDoTikZ
+% \tcbset{fonttitle=\bfseries\sffamily,box align=top,lower separated=false}
+% \fi
+%
+% \renewcommand*\FrontNamesFormat[1]{\color{nared}\sffamily #1}
+% \renewcommand*\FrontNameHook[1]{\color{nagreen}\sffamily #1}
+% \renewcommand*\NamesFormat[1]{\color{nablue}\sffamily #1}
+% \renewcommand*\MainNameHook[1]{\color{nabrown}\sffamily #1}
+% \newcommand*\ReturnLink{\ifDoTikZ
+% \begin{tcolorbox}\centering Back to Section~\ref{sec:Dashboard}\end{tcolorbox}\else
+% \medskip{\hfil\large Back to Section~\ref{sec:Dashboard}}\fi}
%
-% \ifxetex\DoTikZtrue\else\ifpdf\DoTikZtrue\fi\fi
-% \renewcommand*\FrontNamesFormat[1]{\color{nagreen}\sffamily #1}
-% \renewcommand*\FrontNameHook[1]{\color{naolive}\sffamily #1}
-% \renewcommand*\NamesFormat[1]{\color{naviolet}\sffamily #1}
-% \renewcommand*\MainNameHook[1]{\color{naorange}\sffamily #1}
+% \newif\ifFontDebug
+%^^A \FontDebugtrue
%
+% \makeatletter
+% \@setpar{\ifFontDebug\edef\@FS{ \f at size pt}{\tiny\@FS}\fi\@@par}
+% \makeatother
+%
+% \begingroup\FontDebugfalse
% \title{\textsf{nameauth} --- Name authority mechanism\\ for consistency in text and
% index\thanks{This file describes version \fileversion, last revised \filedate.}}
-% \author{Charles P. Schaum\thanks{E-mail: charles dot schaum at comcast dot net}}
+% \author{Charles P. Schaum\thanks{E-mail: charles dot schaum at comcast.net}}
% \date{Released \filedate}
%
% \maketitle
%
% \begin{abstract}
-% \noindent The \textsf{nameauth} package automates the correct formatting and indexing of names for professional writing. This aids the use of a \textbf{name authority} and the editing process without needing to retype name references.
+% \noindent The \textsf{nameauth} package automates the correct formatting and indexing of names for professional writing. This aids the use of a \emph{name authority} and the editing process without needing to retype name references.
% \end{abstract}
%
-% {\small\tableofcontents}
-% \setlength{\parskip}{0.1\baselineskip plus .05\baselineskip minus .05\baselineskip}
+% \bgroup\small\tableofcontents\egroup
+% \endgroup
%
% \section{Quick Start}
-% \subsection{Introduction}
-% \begin{center}\large\bfseries Disclaimer\end{center}
-% \noindent This manual uses names of living and dead historical figures because users refer to real people. At no time do I intend any disrespect or statement of bias for or against any particular person, culture, or tradition. All names herein (as I know them) are used only for teaching purposes, and I strive to respect those names.
%
-% \begin{center}\large\bfseries Denotative Signs\end{center}
-% \noindent In the index, fictional names have an asterisk (*). In this manual, ``non-native'' Eastern names are shown with a dagger (\dag). Names that use the older non-Western syntax are shown with a double dagger (\ddag). These signs are not added by the package macros and will not appear in users' works unless they add them.
+% \subsection{How to Use the Manual}
%
-% \begin{center}\large\bfseries Design\end{center}
-% \noindent When publications use hundreds of names, it takes time and money to manage and check them. This package handles much of that work in order to save time and money. One can implement a name authority, a master list of related names and variants.
-% \begin{itemize}\small
-% \item \textbf{Automate} name forms to aid professional writing.
+% A \emph{name authority} is a canonical, scholarly list of names to which all variants must refer. The task dashboard (Section~\ref{sec:Dashboard}) guides one to various areas of interest. Start with the basics and add features as needed. To load the defaults, simply type:
+% \begin{quote}
+% \fbox{\mystrut\ \texttt{\textbackslash usepackage\{nameauth\}} }
+% \end{quote}
+%
+% \begin{center}\large\bfseries Package Design and Features\end{center}
+% \noindent With \textsf{nameauth} names become abstractions: verbs that alter state and nouns that have state. That improves accuracy and consistency:
% \begin{itemize}
-% \item Move blocks of text and see the names reformat themselves.
-% \item Default to long name references first, then shorter ones.
-% \item Use name variants only in the body text, not the index.
+% \item \emph{Automate} name forms used in professional writing. First uses of names will have full forms. Later uses have shorter forms. Names vary in the text, but stay constant in the index.
+% \item Permit \emph{complex name formatting}.
+% \item Many \emph{cross-cultural, multilingual naming conventions} are possible. More details appear in Sections~\ref{sec:ErrorProt}, \ref{sec:AltFormat}, \ref{sec:IndexSort}, and~\ref{sec:Hooksiii}.
+% \item \emph{Automatic sort keys and tags} aid indexing.
+% \item One can \emph{associate information with names.}
+% \item The standard used for implementing the \textsf{nameauth} indexing macros is Nancy C. Mulvany, \textit{Indexing Books} (Chicago: University of Chicago Press, 1994). All references [\hypertarget{Mulvany}{Mulvany}] refer to this edition.
+% \item In Section~\ref{sec:ErrorProt} we see how to avoid common errors.
+% \item Section~\ref{sec:TechNotes} contains \emph{thanks} and various technical notes.
% \end{itemize}
-% \item Permit \textbf{complex name formatting}. Default is English typography.
-% \item More\marginpar{\large\raggedleft\textsf{\bfseries 3.1}\strut} \textbf{cross-cultural naming conventions} are possible. A basic form of ``Continental'' formatting has been integrated into the package instead of being a user add-on (Sections~\ref{sec:accents}, \ref{sec:altformat}, \ref{sec:IndexSort}, and~\ref{sec:Hooksc}).
-% \item \textbf{Automatic sort keys and tags} aid indexing.
-% \item One can \textbf{automate information retrieval} about names.
-% \item Indexing generally conforms to the standard in Nancy C. Mulvany, \emph{Indexing Books} (Chicago: University of Chicago Press, 1994). All references [\hypertarget{Mulvany}{Mulvany}] refer to this edition. This was thought suitable for most disciplines.
-% \item Notable\marginpar{\large\raggedleft\textsf{\bfseries 3.0}\strut} changes correspond to package version numbers in the margin.
-% \item The\marginpar{\small\raggedleft\dbend} ``dangerous bend'' is used throughout this manual to show where caution is needed to sort out some technical points.
-% \item Please see Section~\ref{sec:notes} for technical notes regarding general questions about package design, this manual, and the package building and release process.
+%
+% \begin{center}\large\bfseries Special Signs\end{center}
+% \noindent As teaching aids, this manual uses markings that are not part of \textsf{nameauth}, but in some cases are implemented using it:
+% \begin{itemize}
+% \item[\ \ ]We show \fbox{\mystrut\NamesFormat{first uses}} and \fbox{\mystrut\MainNameHook{subsequent uses}} of names (Sections~\ref{sec:Formatting}, \ref{sec:NameControl}).
+% \item[\dag\ ]A dagger indicates ``non-native'' Eastern forms (Section~\ref{sec:Eastern}).
+% \item[\ddag\ ]A double dagger shows usage of the obsolete syntax (Section~\ref{sec:Obsolete}).
+% \item[\S\ ]A section mark denotes index entries of fictional names.
+% \item[\(\leftarrow\)]Major\Version{3.0} changes have package version numbers in the margin.
+% \item[\(\leftarrow\)]The\Warn{} ``dangerous bend'' shows where caution is needed.
% \end{itemize}
%
-% \begin{center}\large\bfseries Thanks\end{center}
-% \noindent 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. Thanks also to users for valuable feedback.
-% \clearpage
+% \ifDoTikZ\begin{tcolorbox}[colback=white,colframe=nared,adjusted title={\hfil Disclaimer}]\else
+% \begin{center}\large\bfseries Disclaimer\end{center}\fi
+% \noindent Names are about real people. This manual mentions notable figures both living and deceased. All names herein are meant to be used respectfully, for teaching purposes only. At no time is any disrespect or bias intended.
+% \ifDoTikZ\end{tcolorbox}\fi
+% \newpage
%
-% \subsection{Basic Concepts}
-% \label{sec:start}
+% \subsection{Task Dashboard}
+% \label{sec:Dashboard}
%
-% Name forms are ambiguous apart from historical and cultural contexts. This package uses that ambiguity to encode names in order to avoid changing the order in which one enters names in one's native culture. In this manual we refer to three general classes of names, shown below. It is helpful to become familiarized with this terminology. Other naming systems can be adapted to these general categories with some caveats, \emph{e.g.}, Icelandic, Hungarian, etc.
+% Here we link to sections by task in order to get things done quickly. Many sections have return links at their end that bring the reader back to this page.
+% \ifDoTikZ
+% \begin{tcolorbox}[colframe=naslate,adjusted title={\hfil Where do you want to go today?}]\centering
+% \tcbox[equal height group=Z,on line,tikznode,colframe=nabrown,colback=white,adjusted title={\bfseries\sffamily\hfil Quick Start}]{Sections~\ref{sec:QuickStart}, \ref{sec:TradStart},\\ \ref{sec:SimpleStart}, \ref{sec:SelectOver}, \ref{sec:Obsolete},\\ \ref{sec:NamePatterns}, \ref{sec:ErrorProt}}\hfill
+% \tcbox[equal height group=Z,on line,tikznode,colframe=nabrown,colback=white,adjusted title={\bfseries\sffamily\hfil Basics}]{Package options:\\ Section~\ref{sec:PkgOptions}}\hfill
+% \tcbox[equal height group=Z,on line,tikznode,colframe=nabrown,colback=white,adjusted title={\bfseries\sffamily\hfil Basics}]{Name macros:\\ Sections~\ref{sec:Naming},\\ \ref{sec:FName}}\bigskip
%
-% For teaching purposes, we highlight names using sans-serif and use color to show first and subsequent uses of names (see also Sections~\ref{sec:formatting} and~\ref{sec:tweaks}).
+% \tcbox[equal height group=Zi,on line,tikznode,colframe=nagreen,colback=white,adjusted title={\bfseries\sffamily\hfil Intermediate}]{Variant forms:\\Sections~\ref{sec:VarNames},\\\ref{sec:NameParticles}, \ref{sec:IndexXref}}\hfill
+% \tcbox[equal height group=Zi,on line,tikznode,colframe=nagreen,colback=white,adjusted title={\bfseries\sffamily\hfil Intermediate}]{Avoid errors: Sec-\\tions~\ref{sec:Obsolete}, \ref{sec:NamePatterns}, \ref{sec:ErrorProt},\\ \ref{sec:NameParticles}, \ref{sec:Unicode}}\hfill
+% \tcbox[equal height group=Zi,on line,tikznode,colframe=naviolet,colback=white,adjusted title={\bfseries\sffamily\hfil Language}]{Western names:\\ Sections~\ref{sec:Affix},\\ \ref{sec:LastFirst}}\bigskip
%
-% Professional writing calls for the full form of a person's name when first used, with shorter forms used thereafter. The name parts that define each class are shown in black, with optional elements in red.\footnote{Compare [\hyperlink{Mulvany}{Mulvany}, 152--82] and the \emph{Chicago Manual of Style}. That approach is adapted to \LaTeX\ and its way of handling optional arguments.}
+% \tcbox[equal height group=Zii,on line,tikznode,colframe=naviolet,colback=white,adjusted title={\bfseries\sffamily\hfil Language}]{Eastern names:\\ Sections~\ref{sec:Affix},\\ \ref{sec:Eastern}}\hfill
+% \tcbox[equal height group=Zii,on line,tikznode,colframe=naviolet,colback=white,adjusted title={\bfseries\sffamily\hfil Language}]{Particles, medieval,\\ ancient names: Sec-\\ tions\,\ref{sec:NameParticles},\,\ref{sec:AltFormat},\,\ref{sec:Hooksiii}}\hfill
+% \tcbox[equal height group=Zii,on line,tikznode,colframe=nataupe,colback=white,adjusted title={\bfseries\sffamily\hfil Index}]{Index entries\\ and control:\\ Section~\ref{sec:IndexControl}}\bigskip
%
-% \begin{enumerate}[noitemsep]\large
-% \item Western name: \Wash\\[1ex]
-% \ifDoTikZ\begin{tikzpicture}[line/.style={draw,thick}]\normalsize
-% \node [matrix] (macro) at (0,1)
-% {
-% \node(space){\qquad\qquad\qquad}; &
-% \node(arg1){\strut\textbf{Forename(s)}}; &
-% \node(arg2){\strut\textbf{Surname(s)}}; &
-% \node(arg3){\strut\color{nared}\textbf{Sobriquet, etc.}};\\
-% };
-% \node [matrix,column sep=1em] (descriptors) at (1,-2)
-% {
-% \node[align=left](a1)
-% {
-% Personal name(s):\\
-% \small\textit{baptismal name}\\
-% \small\textit{Christian name}\\
-% \small\textit{first and middle}\\\quad\textit{names}\\
-% \small\textit{praenomen}
-% }; &
-% \node[align=left](a2)
-% {
-% Family designator:\\
-% \small\textit{father's family}\\
-% \small\textit{mother's family}\\
-% \small\textit{ancestor}\\
-% \small\textit{occupation}\\
-% \small\textit{place of origin}\\
-% \small\textit{territory}\\
-% \small\textit{nomen/cognomen}\\
-% \small\textit{patronym}
-% }; &
-% \node[align=left](a3)
-% {
-% Sobriquet / title:\\
-% \small\textit{Sr., Jr., III\dots}\\
-% \small\textit{notable feature}\\
-% \small\textit{notable attribute}\\
-% \small\textit{place of origin}\\
-% \small\textit{territory}\\
-% \small\textit{agnomen}
-% }; \\
-% };
-% \begin{scope}[every path/.style=line]
-% \path (arg1) -- (a1);
-% \path (arg2) -- (a2);
-% \path (arg3) -- (a3);
-% \end{scope}
-% \end{tikzpicture}\else\vfill\fi
-% \item Eastern name: \Sun\\[1ex]
-% \ifDoTikZ\begin{tikzpicture}[line/.style={draw,thick}]\normalsize
-% \node [matrix] (macro) at (0,1)
-% {
-% \node(spacei){\qquad\qquad\qquad}; &
-% \node(arg1){\strut\textbf{Family name}}; &
-% \node(spaceii){\qquad}; &
-% \node(arg2){\strut\textbf{Given name}};\\
-% };
-% \node [matrix,column sep=1cm] (descriptors) at (2,-0.5)
-% {
-% \node[align=left](a1)
-% {
-% Family\\ designator
-% }; &
-% \node[align=left](a2)
-% {
-% Multiple names are rare, but multi-\\character names do exist.
-% };\\
-% };
-% \begin{scope}[every path/.style=line]
-% \path (arg1) -- (a1);
-% \path (arg2) -- (a2);
-% \end{scope}
-% \end{tikzpicture}\else\vfill\fi
-% \item Ancient name: \Eliz\\[1ex]
-% \ifDoTikZ\begin{tikzpicture}[line/.style={draw,thick}]\normalsize
-% \node [matrix] (macro) at (0,1)
-% {
-% \node(spacei){\qquad\qquad\qquad}; &
-% \node(arg1){\strut\color{black}\textbf{Given name}}; &
-% \node(spaceii){\qquad}; &
-% \node(arg2){\strut\color{nared}\textbf{Sobriquet, etc.}};\\
-% };
-% \node [matrix,column sep=2.2cm] (descriptors) at (1.5,-1.7)
-% {
-% \node[align=left](a1)
-% {
-% Personal\\ name
-% }; &
-% \node[align=left](a2)
-% {
-% Sobriquet / title:\\
-% \small\textit{senior, junior, III\dots}\\
-% \small\textit{notable feature}\\
-% \small\textit{notable attribute}\\
-% \small\textit{place of origin}\\
-% \small\textit{territory}\\
-% \small\textit{patronym}
-% }; \\
-% };
-% \begin{scope}[every path/.style=line]
-% \path (arg1) -- (a1);
-% \path (arg2) -- (a2);
-% \end{scope}
-% \end{tikzpicture}\else\vfill\fi
-% \end{enumerate}
-% \ForgetName[George]{Washington}\ForgetName{Sun, Yat-sen}\ForgetName{Elizabeth, I}
-% \clearpage
+% \tcbox[equal height group=Ziii,on line,tikznode,colframe=nataupe,colback=white,adjusted title={\bfseries\sffamily\hfil Index}]{\hbox to 0.385\textwidth{\ Index cross-refs, automatic\ }\\ sorting, and auto-info: Sec-\\ tions~\ref{sec:IndexXref}, \ref{sec:IndexSort}, \ref{sec:IndexTag}, \ref{sec:AKA}}\hfill
+% \tcbox[equal height group=Ziii,on line,tikznode,colframe=nared,colback=white,adjusted title={\bfseries\sffamily\hfil Advanced}]{\hbox to 0.39\textwidth{Generally manage how names}\\ are typeset: Sections~\ref{sec:Formatting}, \ref{sec:AltFormat},\\ \ref{sec:NameControl}, \ref{sec:NameTests}, \ref{sec:Hooksi}\,--\,\ref{sec:Customize}}\bigskip
%
-% Based on the classes of names, the \textsf{nameauth} macros halt with an error in the following cases:
-% \begin{itemize}\small
-% \item The required name argument \meta{SNN} expands to the empty string.
-% \item The required argument \meta{SNN, Affix} expands to \meta{empty}, \meta{Affix}.
-% \item No shorthand is present for a name in the simplified interface (Section~\ref{sec:simplestart}).
-% \end{itemize}
+% \tcbox[equal height group=Ziv,on line,tikznode,colframe=nared,colback=white,adjusted title={\bfseries\sffamily\hfil Advanced}]{\hbox to 0.385\textwidth{Generally manage names by}\\ using a name authority: Sec-\\ tions~\ref{sec:VarNames}, \ref{sec:Formatting}, \ref{sec:IndexControl}, \ref{sec:NameControl}}\hfill
+% \tcbox[equal height group=Ziv,on line,tikznode,colframe=nared,colback=white,adjusted title={\bfseries\sffamily\hfil Advanced}]{Make complex elements\\\hbox to 0.39\textwidth{determined automatically by}\\ names: Sections \ref{sec:TextTags}, \ref{sec:NameTests}}\bigskip
%
-% \subsection{Traditional Interface}
+% \tcbox[equal height group=Zv,on line,tikznode,colframe=nablue,colback=white,adjusted title={\bfseries\sffamily\hfil Application}]{Use \textsf{nameauth} with \textsf{beamer}\\\hbox to 0.385\textwidth{overlays to get correct name}\\ forms: Sections~\ref{sec:Formatting}, \ref{sec:NameDecisions},\\ \ref{sec:NameControl}, \ref{sec:NameTests}}\hfill
+% \tcbox[equal height group=Zv,on line,tikznode,colframe=nablue,colback=white,adjusted title={\bfseries\sffamily\hfil Application}]{\hbox to 0.39\textwidth{History / game books, other}\\ complex layouts: Sections\\ \ref{sec:Formatting}, \ref{sec:IndexTag}, \ref{sec:TextTags}, \ref{sec:NameControl},\\ \ref{sec:NameTests}, \ref{sec:Hooksi}\,--\,\ref{sec:Hooksiii}}\smallskip
+% \end{tcolorbox}
+% \else
+% \begin{center}
+% \begin{tabularx}{0.9\textwidth}{@{}X|X|X@{}}\toprule
+% &&\\
+% Concept overview: Sections~\ref{sec:QuickStart}, \ref{sec:TradStart}, \ref{sec:SimpleStart}, \ref{sec:SelectOver}, \ref{sec:Obsolete}, \ref{sec:NamePatterns}, \ref{sec:ErrorProt} & Package options: Section~\ref{sec:PkgOptions} & Basic macros: Section \ref{sec:Naming}, \ref{sec:FName}\\
+% &&\\\midrule
+% &&\\
+% Variant forms: Sections~\ref{sec:VarNames}, \ref{sec:NameParticles}, \ref{sec:IndexXref} & Avoid errors: Sections~\ref{sec:Obsolete}, \ref{sec:NamePatterns}, \ref{sec:ErrorProt}, \ref{sec:NameParticles}, \ref{sec:Unicode} & Western names: Sections~\ref{sec:Affix}, \ref{sec:LastFirst}\\
+% &&\\\midrule
+% &&\\
+% Eastern names: Sections~\ref{sec:Affix}, \ref{sec:Eastern} & Particles, medieval, ancient names: Sections~\ref{sec:NameParticles}, \ref{sec:AltFormat}, \ref{sec:Hooksiii} & Index entries and control: Section~\ref{sec:IndexControl}\\
+% &&\\\midrule
+% &&\\
+% Index cross-refs, automatic sorting, and auto-info: Sections~\ref{sec:IndexXref}, \ref{sec:IndexSort}, \ref{sec:IndexTag}, \ref{sec:AKA} & Generally manage how names are typeset: Sections~\ref{sec:Formatting}, \ref{sec:AltFormat}, \ref{sec:NameControl}, \ref{sec:NameTests}, \ref{sec:Hooksi}\,--\,\ref{sec:Customize} & Generally manage names by using a name authority: Sections~\ref{sec:VarNames}, \ref{sec:Formatting}, \ref{sec:IndexControl}, \ref{sec:NameControl}\\
+% &&\\\midrule
+% &&\\
+% Make complex elements determined automatically by names: Sections \ref{sec:TextTags}, \ref{sec:NameTests} & Use \textsf{nameauth} with \textsf{beamer} overlays to get correct name forms: Sections~\ref{sec:Formatting}, \ref{sec:NameDecisions}, \ref{sec:NameControl}, \ref{sec:NameTests} & History\,/\,game books, other complex layouts: Sections~\ref{sec:Formatting}, \ref{sec:IndexTag}, \ref{sec:TextTags}, \ref{sec:NameControl}, \ref{sec:NameTests}, \ref{sec:Hooksi}\,--\,\ref{sec:Hooksiii}\\
+% &&\\\bottomrule
+% \end{tabularx}
+% \end{center}
+% \fi
+% \newpage
%
-% For all categories, the fields that define each category are shown in black, with optional elements in red.\medskip
+% \subsection{Basic Concepts}
+% \label{sec:QuickStart}
%
-% \noindent{\bfseries Western Names}
+% We encode names in macro arguments to address multiple naming systems. Required name elements are shown in \emph{black}; optional parts are in \emph{\color{nared}red}.\footnote{Compare [\hyperlink{Mulvany}{Mulvany}, 152--82] and the \textit{Chicago Manual of Style}.}
+% The arguments appear in the order \meta{FNN} \meta{SNN} \meta{Affix} \meta{Alternate}:
+%
% \ifDoTikZ
-% \begin{center}
-% \begin{tikzpicture}[line/.style={draw,thick}]
-% \node [matrix,column sep=2.5cm] (advice) at (0.5,1.5)
-% {
-% \node[align=center](opt){\small Add to force full name.}; &
-% \node[text width=3.5cm,align=left](grp){\small Add only if text in brackets |[|\,|]| follows.}; \\
-% };
-% \node [matrix] (macro) at (0.2,0)
-% {
-% \node(cmd){\bfseries\cmd{\Name}}; &
-% \node(star){\bfseries\texttt{*}}; &
-% \node(arg1){\bfseries\bfseries\oarg{FNN}}; &
-% \node(arg2){\bfseries\bfseries\marg{SNN\color{nared}, Affix}}; &
-% \node(arg3){\bfseries\oarg{\color{nared}Alternate names}}; &
-% \node(braces){\bfseries|{}|}; \\
-% };
-% \node [matrix,column sep=1em] (descriptors) at (0,-1.5)
-% {
-% \node[align=center](a1)
-% {
-% \small Forename(s)
-% }; & & &
-% \node[align=center](a2)
-% {
-% \small Surname(s)
-% }; & & & & &
-% \node[align=center](a3)
-% {
-% \small Used only in text
-% }; \\
-% };
-% \begin{scope}[every path/.style=line]
-% \path (opt) -- (star);
-% \path (grp) -- (braces);
-% \path (arg1) -- (a1);
-% \path (arg2) -- (a2);
-% \path (arg3) -- (a3);
-% \end{scope}
-% \end{tikzpicture}
-% \end{center}\vspace{-2ex}
-% \else\vfill\fi
-% \textbf{Examples:}\medskip
+% \noindent\begin{tcolorbox}[colframe=naslate,adjusted title={Western Name}]\centering
+% \tcbox[equal height group=A,on line,tikznode,colback=white,adjusted title={\bfseries\sffamily Forename(s):\\ \meta{FNN}}]{%
+% Personal name(s):\\
+% \textit{baptismal name}\\
+% \textit{Christian name}\\
+% \textit{multiple names}\\
+% \textit{praenomen}\footnotemark\\
+% \hphantom{Family\,/\,clan name}}
+% \tcbox[equal height group=A,on line,tikznode,colback=white,adjusted title={\bfseries\sffamily Surname(s):\\ \meta{SNN}}]{%
+% Family name:\\
+% \textit{of father, mother}\\
+% \textit{ancestor, vocation}\\
+% \textit{origin, region}\\
+% \textit{nomen, cognomen}\\
+% \textit{patronym}\\
+% \vspace{-2ex}\hphantom{\textit{ancestor, vocation}}}
+% \tcbox[equal height group=A,on line,tikznode,colback=white,colframe=nared,adjusted title={\bfseries\sffamily Descriptor:\\ \meta{Affix}}]{%
+% Sobriquet\,/\,title:\\
+% \textit{Sr., Jr., III\dots}\\
+% \textit{notable attribute}\\
+% \textit{origin, region}}
+% \tcbox[tikznode,colback=white,colframe=nared,adjusted title={\bfseries\sffamily Alternate Name(s): \meta{Alternate}}]{\hbox to 0.913\textwidth{\hfil In the body text, not the index, \meta{Alternate} swaps with \meta{FNN}\hfil}\\ \hbox to 0.913\textwidth{\hfil for Western names and \meta{Affix} for all other name categories.\hfil}}
+% \end{tcolorbox}\medskip
+% \begin{tcolorbox}[colframe=naslate,adjusted title={Eastern Name}]\centering
+% \tcbox[equal height group=B,on line,tikznode,colback=white,adjusted title={\bfseries\sffamily Family name:\\ \meta{SNN}}]{Family\,/\,clan name}
+% \tcbox[equal height group=B,on line,tikznode,colback=white,adjusted title={\bfseries\sffamily Personal name:\\ \meta{Affix}}]{Seldom multiple\\
+% names; multi-\\
+% character okay.\\
+% \vspace{-2ex}\hphantom{\textit{ancestor, vocation}}}
+% \tcbox[equal height group=B,on line,tikznode,colback=white,colframe=nared,adjusted title={\bfseries\sffamily Descriptor:\\ \meta{Alternate}}]{%
+% Title, etc.\\
+% (old syntax for\\
+% personal names)\\
+% \vspace{-2ex}\hphantom{Sobriquet\,/\,title:}}
+% \end{tcolorbox}\medskip
+% \begin{tcolorbox}[colframe=naslate,adjusted title={Ancient name}]\centering
+% \tcbox[equal height group=C,on line,tikznode,colback=white,adjusted title={\bfseries\sffamily Personal name:\\ \meta{SNN}}]{Given name(s)\\
+% \hphantom{Family\,/\,clan name}}
+% \tcbox[equal height group=C,on line,tikznode,colback=white,colframe=nared,adjusted title={\bfseries\sffamily Descriptor:\\ \meta{Affix}}]{%
+% Sobriquet\,/\,title:\\
+% \textit{Sr., Jr., III\dots}\\
+% \textit{notable attribute}\\
+% \textit{origin, region}\\
+% \textit{patronym}\\
+% \vspace{-2ex}\hphantom{\textit{ancestor, vocation}}}
+% \tcbox[equal height group=C,on line,tikznode,colback=white,colframe=nared,adjusted title={\bfseries\sffamily Descriptor:\\ \meta{Alternate}}]{%
+% Alternate name\\
+% (old syntax for\\
+% titles, etc.)\\
+% \hphantom{Sobriquet\,/\,title:}}
+% \end{tcolorbox}
+% \else
+% \begin{enumerate}[noitemsep]
+% \item Western Name:\medskip\\
+% \begin{tabular}{p{0.28\textwidth}p{0.28\textwidth}p{0.28\textwidth}}
+% \strut\textbf{Forename(s)} &
+% \strut\textbf{Surname(s)} &
+% \strut\textbf{\color{nared}Descriptor}\smallskip\\
+% \strut Personal name(s): &
+% \strut Family name: &
+% \strut Sobriquet\,/\,title:\smallskip\\
+% \textit{baptismal name}\newline
+% \textit{Christian name}\newline
+% \textit{multiple names}\newline
+% \textit{praenomen}\footnotemark &
+% \textit{of father, mother}\newline
+% \textit{ancestor, vocation}\newline
+% \textit{origin, region}\newline
+% \textit{nomen, cognomen}\newline
+% \textit{patronym} &
+% \textit{Sr., Jr., III\dots}\newline
+% \textit{notable attribute}\newline
+% \textit{origin, region}\medskip\\
+% \end{tabular}\\
+%
+% \noindent \textbf{Alternate Name(s):} In the body text, not the index, \meta{Alternate} swaps with \meta{FNN} for Western names and \meta{Affix} for all other name categories.\medskip\\
+% \item Eastern Name:\medskip\\
+% \begin{tabular}{p{0.28\textwidth}p{0.28\textwidth}p{0.28\textwidth}}
+% \textbf{Family name} &
+% \textbf{Given name} &
+% \textbf{\color{nared}Descriptor}\smallskip\\
+% Family\,/\,clan name &
+% \textit{Seldom multiple}\newline
+% \textit{names; multi-}\newline
+% \textit{character okay.} &
+% Title, etc.\newline
+% \textit{(old syntax for}\newline
+% \textit{personal names)}\medskip\\
+% \end{tabular}
+%
+% \item Ancient name:\medskip\\
+% \begin{tabular}{p{0.28\textwidth}p{0.28\textwidth}p{0.28\textwidth}}
+% \textbf{Personal name} &
+% \textbf{\color{nared}Descriptor} &
+% \textbf{\color{nared}Alt. Desc.}\smallskip\\
+% Given name(s): &
+% Sobriquet\,/\,title: &
+% Alternate name:\smallskip\\
+% &
+% \textit{Sr., Jr., III\dots}\newline
+% \textit{notable attribute}\newline
+% \textit{origin, region}\newline
+% \textit{patronym} &
+% \textit{(old syntax for}\newline
+% \textit{titles, etc.)}\\
+% \end{tabular}
+% \end{enumerate}\fi
+%\begingroup
+%\newif\ifSkipGens
+%\newif\ifNoGens
+%\newif\ifSkipAgnomen
+%\newif\ifNoAgnomen
+%\newcommand*\SCIPi{\unless\ifNoGens Publius Cornelius\else Publius\fi}
+%\newcommand*\SCIPii{\unless\ifNoAgnomen Scipio Africanus\else Scipio\fi}
+%\newcommand*\ScipioOnly{\SkipAgnomentrue\Scipio}
+%\renewcommand*\NamesFormat[1]%^^A
+% {\sffamily\color{nablue}\ifSkipGens\NoGenstrue\fi\ifSkipAgnomen\NoAgnomentrue\fi#1%^^A
+% \global\SkipGensfalse\global\SkipAgnomenfalse}
+%\renewcommand*\MainNameHook[1]%^^A
+% {\sffamily\color{nabrown}\ifSkipGens\NoGenstrue\fi\ifSkipAgnomen\NoAgnomentrue\fi#1%^^A
+% \global\SkipGensfalse\global\SkipAgnomenfalse}
+% \footnotetext{How one handles Roman names depends on index entry form; some possible suggestions are given above. Explained on page~\pageref{page:Sobriquets} and following, we have a name \ScipioOnly\ that can be \SkipGenstrue\Scipio\ or just \SkipGenstrue\ScipioOnly, using macro expansion.}
+% \endgroup
+% \newpage
%
-% \noindent One always must include all fields for consistent index entries.\medskip
+% \subsubsection{Traditional Interface}
+% \label{sec:TradStart}
%
-% {\setstretch{1.1}\noindent|\Name [George]{Washington}|\dotfill\Name[George]{Washington}\\
+% Mandatory arguments are shown in \emph{black}, with optional elements in \emph{\color{nared}red}. If the required argument \meta{SNN} expands to the empty string, \textsf{nameauth} will generate a package error. Extra spaces around each argument are stripped (Section~\ref{sec:ErrorProt}). The argument patterns shown here are used in many \textsf{nameauth} macros.
+%
+% \bgroup\ifDoTikZ
+% \begin{tcolorbox}[colframe=naslate,adjusted title={Western Names}]\centering
+% \begin{tabular}{l@{ }c@{ }c@{ }c}
+% & \small Required & \small Required & \small Optional,\\
+% & \small forename(s) & \small surname(s), & \small in text only \\
+% & & \small optional \meta{Affix}\smallskip\\
+% \tcbox[equal height group=D,colback=white,tikznode,left=1mm,right=1mm,valign=center]{\bfseries\strut \hbox{\cmd{\Name}\texttt{\space}}\\ \strut \cmd{\Name*}\\ \strut \cmd{\FName}} &
+% \tcbox[equal height group=D,colback=white,tikznode,left=1mm,right=1mm,valign=center]{\bfseries\oarg{FNN}} &
+% \tcbox[equal height group=D,colback=white,tikznode,left=1mm,right=1mm,valign=center]{\bfseries\marg{SNN\color{nared}, Affix}} &
+% \tcbox[equal height group=D,colback=white,tikznode,left=1mm,right=1mm,valign=center]{\bfseries\oarg{\color{nared}Alternate}}
+% \end{tabular}
+%
+% Add braces \texttt{\bfseries\{\,\}} after {\bfseries\marg{SNN\color{nared}, Affix}} if other text in brackets \texttt{\bfseries[\,]} follows.
+% \end{tcolorbox}
+% \else
+% \bigskip\noindent{\bfseries Western Names}
+%
+% \bigskip\begin{tabular}{lccc}
+% & \small Required & \small Required surname(s), & \small Optional,\\
+% & \small forename(s) & \small optional \meta{Affix} & \small in text only\smallskip\\
+% \cmd{\Name}\\
+% \cmd{\Name*} & \bfseries\oarg{FNN} & \bfseries\marg{SNN\color{nared}, Affix} & \bfseries\oarg{\color{nared}Alternate}\\
+% \cmd{\FName}
+% \end{tabular}\\
+%
+% Add braces \texttt{\bfseries\{\,\}} after {\bfseries\marg{SNN\color{nared}, Affix}} if other text in brackets \texttt{\bfseries[\,]} follows.
+% \fi\egroup
+%
+% \begin{center}\bfseries Examples\end{center}
+%
+% \noindent Western names require the \meta{FNN} argument to be present. One always includes all arguments for consistent index entries. The simplified interface (Section~\ref{sec:SimpleStart}) cuts down the amount of typing in many cases.\medskip
+%
+% \bgroup\MyStretch\noindent%
+% |\Name [George]{Washington}|\dotfill\Name[George]{Washington}\\
% |\Name*[George]{Washington}|\dotfill\Name*[George]{Washington}\\
% |\Name [George]{Washington}|\dotfill\Name[George]{Washington}\\
-% |\FName[George]{Washington}|\dotfill\FName[George]{Washington}\\
+% |\FName[George]{Washington}|\dotfill\FName[George]{Washington}\smallskip\\
% |\Name [George S.]{Patton, Jr.}|\dotfill\Name[George S.]{Patton, Jr.}\\
% |\Name*[George S.]{Patton, Jr.}|\dotfill\Name*[George S.]{Patton, Jr.}\\
% |\Name [George S.]{Patton, Jr.}|\dotfill\Name[George S.]{Patton, Jr.}\\
-% |\FName[George S.]{Patton, Jr.}|\dotfill\FName[George S.]{Patton, Jr.}}\medskip
+% |\FName[George S.]{Patton, Jr.}|\dotfill\FName[George S.]{Patton, Jr.}\egroup\medskip
%
-% \noindent\meta{Alternate names} with Western forms require the \meta{FNN} argument to have a name in it. \meta{Alternate names} print only in the text. \meta{FNN} prints in the text and index. For alternate surnames see Section~\ref{sec:DuBois}.\medskip
+% The \meta{Alternate} argument will swap with \meta{FNN} in the text, not in the index or the name pattern (Section~\ref{sec:NamePatterns}). To see alternate names, one must use a macro that shows forenames (first use, \cmd{\Name*}, and \cmd{\FName}). Western names require a comma to delimit affixes (Section~\ref{sec:Affix}). Below we see alternate names:\medskip
%
-% {\setstretch{1.1}\noindent|\Name [Clive Staples]{Lewis}|\dotfill\Name[Clive Staples]{Lewis}\\
+% \bgroup\MyStretch\noindent%
+% |\DropAffix\Name*[George S.]{Patton, Jr.}[George]|\dotfill\DropAffix\Name*[George S.]{Patton, Jr.}[George]\smallskip\\
+% |\Name [John David]{Rockefeller, IV}|\dotfill\Name[John David]{Rockefeller, IV}\\
+% |\Name*[John David]{Rockefeller, IV}[Jay]|\dotfill\Name*[John David]{Rockefeller, IV}[Jay]\\
+% |\DropAffix\Name*[John David]{Rockefeller, IV}[Jay]|\dotfill\DropAffix\Name*[John David]{Rockefeller, IV}[Jay]\\
+% |\Name [John David]{Rockefeller, IV}[Jay]|\dotfill\Name[John David]{Rockefeller, IV}[Jay]\smallskip\\
+% |\Name [Clive Staples]{Lewis}|\dotfill\Name[Clive Staples]{Lewis}\\
% |\Name*[Clive Staples]{Lewis}[C.S.]|\dotfill\Name*[Clive Staples]{Lewis}[C.S.]\\
-% |\Name [Clive Staples]{Lewis}|\dotfill\Name[Clive Staples]{Lewis}\\
-% |\Name [Clive Staples]{Lewis}[C.S.]|\dotfill\Name[Clive Staples]{Lewis}[C.S.]\\
-% |\Name*[Clive Staples]{Lewis}[Jack]|\dotfill\Name*[Clive Staples]{Lewis}[Jack]\\
-% |\FName[Clive Staples]{Lewis}[Jack]|\dotfill\FName[Clive Staples]{Lewis}[Jack]}\medskip
+% |\FName[Clive Staples]{Lewis}[Jack]|\dotfill\FName[Clive Staples]{Lewis}[Jack]\egroup\medskip
%
-% \noindent Both affixes and alternate names can vary in the text. Western names require a comma to delimit affixes; see Sections~\ref{sec:obsolete} and~\ref{sec:Affix}. Using alternate names does not trigger an explicit first use. That is intentional.\medskip
+% In addition to alternate forenames, one also can display alternate surnames, but that uses several different approaches (Sections~\ref{sec:VarNames}, \ref{sec:NameParticles}, \ref{sec:AltAdvanced}, \ref{sec:Hooksiii}).
+% \newpage
%
-% {\setstretch{1.1}\noindent|\Name [John David]{Rockefeller, IV}|\dotfill\Name[John David]{Rockefeller, IV}\\
-% |\Name*[John David]{Rockefeller, IV}[Jay]|\dotfill\Name*[John David]{Rockefeller, IV}[Jay]\\
-% |\DropAffix\Name*[John David]{Rockefeller, IV}[Jay]|\dotfill\DropAffix\Name*[John David]{Rockefeller, IV}[Jay]}
-% |\Name [John David]{Rockefeller, IV}[Jay]|\dotfill\Name[John David]{Rockefeller, IV}[Jay]\\
-% \clearpage
+% \bgroup\ifDoTikZ
+% \begin{tcolorbox}[colframe=naslate,adjusted title={``Non-native'' Eastern Names, Western Index Entry}]\centering
+% \begin{tabular}{l@{ }c@{ }c@{ }c}
+% & \small Required & \small Required & \small Optional,\\
+% & \small forename(s) & \small surname(s), & \small in text only \\
+% & & \small no \meta{Affix}\smallskip\\
+% \tcbox[equal height group=D,colback=white,tikznode,left=1mm,right=1mm,valign=center]{\bfseries\strut \hbox{\cmd{\Name}\texttt{\space}}\\ \strut \cmd{\Name*}\\ \strut \cmd{\FName}} &
+% \tcbox[equal height group=D,colback=white,tikznode,left=1mm,right=1mm,valign=center]{\bfseries\oarg{FNN}} &
+% \tcbox[equal height group=D,colback=white,tikznode,left=1mm,right=1mm,valign=center]{\bfseries\marg{SNN}} &
+% \tcbox[equal height group=D,colback=white,tikznode,left=1mm,right=1mm,valign=center]{\bfseries\oarg{\color{nared}Alternate}}
+% \end{tabular}
%
-% \noindent{\bfseries ``Non-Native'' Eastern Names in the Text, Western Index Entry}
-% \ifDoTikZ
-% \begin{center}
-% \begin{tikzpicture}[line/.style={draw,thick}]
-% \node [matrix,column sep=1.5cm] (advice) at (0.5,1.5)
-% {
-% \node[align=center](opt){\small Add to force full name.}; &
-% \node[text width=3.5cm,align=left](grp){\small Add only if text in brackets |[|\,|]| follows.}; \\
-% };
-% \node [matrix] (macro) at (0,0)
-% {
-% \node(cmd){\bfseries\cmd{\RevName} \cmd{\Name}}; &
-% \node(star){\bfseries\texttt{*}}; &
-% \node(arg1){\bfseries\oarg{FNN}}; &
-% \node(arg2){\bfseries\marg{SNN}}; &
-% \node(arg3){\bfseries\oarg{\color{nared}Alternate names}}; &
-% \node(braces){\bfseries|{}|}; \\
-% };
-% \node [matrix,column sep=1em] (descriptors) at (0.7,-1.5)
-% {
-% \node[align=center](a1)
-% {
-% \small Given name
-% }; & & &
-% \node[align=center](a2)
-% {
-% \small Family name
-% }; & & &
-% \node[align=center](a3)
-% {
-% \small Used only in text
-% }; \\
-% };
-% \begin{scope}[every path/.style=line]
-% \path (opt) -- (star);
-% \path (grp) -- (braces);
-% \path (arg1) -- (a1);
-% \path (arg2) -- (a2);
-% \path (arg3) -- (a3);
-% \end{scope}
-% \end{tikzpicture}
-% \end{center}\vspace{-2ex}
-% \else\vfill\fi
-% \textbf{Examples:}\medskip
+% Add braces \texttt{\bfseries\{\,\}} after {\bfseries\marg{SNN}} if other text in brackets \texttt{\bfseries[\,]} follows.
+% \end{tcolorbox}
+% \else
+% \bigskip\noindent{\bfseries ``Non-native'' Eastern Names, Western Index Entry}
%
-% \noindent These are encoded using Western name forms without affixes. The reversing macros (Section~\ref{sec:Eastern}) cause them to display in Eastern order in the body text. [\hyperlink{Mulvany}{Mulvany}, 166] shows Hungarian names compatible with this category. Index entries are formatted as: \meta{SNN}, \meta{FNN}. We show these names with a dagger (\dag).\medskip
+% \bigskip\begin{tabular}{lccc}
+% & \small Required & \small Required surname(s), & \small Optional,\\
+% & \small forename(s) & \small no \meta{Affix} & \small in text only\smallskip\\
+% \cmd{\Name}\\
+% \cmd{\Name*} & \bfseries\oarg{FNN} & \bfseries\marg{SNN} & \bfseries\oarg{\color{nared}Alternate}\\
+% \cmd{\FName}
+% \end{tabular}\\
%
-% {\noindent\setstretch{1.1}|\Name[Fumimaro]{Konoe}|\dotfill\Name[Fumimaro]{Konoe}\dag\\
-% |\Name*[Fumimaro]{Konoe}[Prime Minister]|\dotfill\Name*[Fumimaro]{Konoe}[Prime Minister]\dag\\
-% |\RevName\Name*[Fumimaro]{Konoe}|\dotfill\RevName\Name*[Fumimaro]{Konoe}\dag\\
-% |\RevName\Name[Frenec]{Molnár}|\dotfill\RevName\Name[Frenec]{Molnár}\dag}\medskip
+% Add braces \texttt{\bfseries\{\,\}} after {\bfseries\marg{SNN}} if other text in brackets \texttt{\bfseries[\,]} follows.
+% \fi\egroup
%
-% \noindent This ``non-native'' form of Eastern names excludes both comma-delimited suffixes and the older non-Western syntax (Sections~\ref{sec:obsolete}). This form \emph{will not share} control sequences and index entries with the non-Western forms described below.\bigskip
%
-% \noindent{\bfseries ``Native'' Eastern Names in the Text, Eastern Index Entry}
-% \ifDoTikZ
-% \begin{center}
-% \begin{tikzpicture}[line/.style={draw,thick}]
-% \node [matrix,column sep=1cm] (advice) at (0.5,1.3)
-% {
-% \node(opt){\small Add to force full name.}; &
-% \node[text width=3.5cm,align=left](grp){\small Add only if text in brackets |[|\,|]| follows.}; \\
-% };
-% \node [matrix] (macro) at (0,0)
-% {
-% \node(cmd){\bfseries\cmd{\Name}}; &
-% \node(star){\bfseries\texttt{*}}; &
-% \node(arg1){\bfseries\marg{SNN, FNN}}; &
-% \node(arg2){\bfseries\oarg{\color{nared}Alternate names}}; &
-% \node(braces){\bfseries|{}|}; \\
-% };
-% \node [matrix,column sep=1em] (descriptors) at (0.3,-1.3)
-% {
-% \node[align=center](a1)
-% {
-% \small Family name
-% }; &
-% \node[align=center](a2)
-% {
-% \small Given name
-% }; & &
-% \node[align=center](a3)
-% {
-% \small Used only in text
-% }; \\
-% };
-% \begin{scope}[every path/.style=line]
-% \path (opt) -- (star);
-% \path (grp) -- (braces);
-% \path (arg1) -- (a1);
-% \path (arg1) -- (a2);
-% \path (arg2) -- (a3);
-% \end{scope}
-% \end{tikzpicture}
-% \end{center}\vspace{-2ex}
-% \else\vfill\fi
-% \textbf{Examples:}\medskip
+% \begin{center}\bfseries Examples\end{center}
%
-% \noindent The main feature of non-Western forms in \textsf{nameauth} is the comma-delimited suffix. Eastern names have the family name in \meta{SNN} where ancient names have the personal name, but that root name remains the required argument.
+% \noindent Below we start with ``regular'' Western name forms:\medskip
%
-%These names always take the form \meta{SNN FNN} in the index. See Section~\ref{sec:Eastern}. In this manual we refer to the ``native'' Eastern form below:\medskip
+% \bgroup\noindent\MyStretch|\Name[Hideyo]{Noguchi}|\dotfill\Name[Hideyo]{Noguchi}\\
+% |\Name*[Hideyo]{Noguchi}[Doctor]|\dotfill\Name*[Hideyo]{Noguchi}[Doctor]\\
+% |\Name[Frenec]{Molnár}|\dotfill\Name[Frenec]{Molnár}\egroup\medskip
%
-% {\noindent\setstretch{1.1}|\Name{Yamamoto, Isoroku}|\dotfill\Name{Yamamoto, Isoroku}\\
+% To turn them into ``non-native'' Eastern names or proper Hungarian names [\hyperlink{Mulvany}{Mulvany}, 166] we use the reversing macros and leave the \meta{Alternate} argument empty (Section~\ref{sec:Eastern}). Index entries are in Western style: \meta{SNN}, \meta{FNN}:\medskip
+%
+% \bgroup\MyStretch\noindent|\CapName\RevName\Name*[Hideyo]{Noguchi}|\dotfill\CapName\RevName\Name*[Hideyo]{Noguchi}\dag\\
+% |\CapName\RevName\Name*[Hideyo]{Noguchi}[Sensei]|\dotfill\CapName\RevName\Name*[Hideyo]{Noguchi}[Sensei]\dag\\
+% |\RevName\Name*[Frenec]{Molnár}|\dotfill\RevName\Name*[Frenec]{Molnár}\dag\egroup\medskip
+%
+% Reversed Western forms do not work with the older syntax (Section~\ref{sec:Obsolete}) and \emph{they do not share name control sequences and index entries} with ``native'' Eastern names and ancient name forms (Section~\ref{sec:NamePatterns}).
+%
+% \bgroup\ifDoTikZ
+% \begin{tcolorbox}[colframe=naslate,adjusted title={\bfseries ``Native'' Eastern Names in the Text, Eastern Index Entry}]\centering
+% \begin{tabular}{l@{ }c@{ }c}
+% & \small Required surname & \small Optional,\\
+% & \small and forename & \small in text only\smallskip\\
+% \tcbox[equal height group=D,colback=white,tikznode,left=1mm,right=1mm,valign=center]{\bfseries\strut \hbox{\cmd{\Name}\texttt{\space}}\\ \strut \cmd{\Name*}\\ \strut \cmd{\FName}} &
+% \tcbox[equal height group=D,colback=white,tikznode,left=1mm,right=1mm,valign=center]{\bfseries\marg{SNN, Affix}} &
+% \tcbox[equal height group=D,colback=white,tikznode,left=1mm,right=1mm,valign=center]{\bfseries\oarg{\color{nared}Alternate}}
+% \end{tabular}
+%
+% Add braces \texttt{\bfseries\{\,\}} after {\bfseries\marg{SNN, Affix}} if other text in brackets \texttt{\bfseries[\,]} follows.
+% \end{tcolorbox}
+% \else
+% \bigskip\noindent{\bfseries ``Native'' Eastern Names in the Text, Eastern Index Entry}
+%
+% \bigskip\begin{tabular}{lcc}
+% & \small Required Surname & \small Optional,\\
+% & \small and forename & \small in text only\smallskip\\
+% \cmd{\Name}\\
+% \cmd{\Name*} & \bfseries\marg{SNN, Affix} & \bfseries\oarg{\color{nared}Alternate}\\
+% \cmd{\FName}
+% \end{tabular}\\
+%
+% Add braces \texttt{\bfseries\{\,\}} after {\bfseries\marg{SNN, Affix}} if text in brackets \texttt{\bfseries[\,]} follows.
+% \fi\egroup
+%
+% \begin{center}\bfseries Examples\end{center}
+%
+% \noindent The comma-delimited required argument, \meta{SNN, Affix}, is the key to non-Western names, which always take the form \meta{SNN Affix} in the index. See Section~\ref{sec:Eastern}. ``Native'' Eastern names have Eastern name order from the start and \emph{they do not share name control sequences and index entries} with Western names (Section~\ref{sec:NamePatterns}). They can be reversed to have Western name order in the body text.
+% \newpage
+%
+% Except\Version{3.0} for mononyms, non-Western forms also can have alternate names. This is incompatible with the older syntax (see Section~\ref{sec:Obsolete}). Unless the index must have Western-style entries, ``native'' forms are best for Eastern names:\medskip
+%
+% \bgroup\MyStretch\noindent|\Name{Yamamoto, Isoroku}|\dotfill\Name{Yamamoto, Isoroku}\\
% |\Name{Yamamoto, Isoroku}|\dotfill\Name{Yamamoto, Isoroku}\\
-% |\RevName\Name*{Yamamoto, Isoroku}|\dotfill\RevName\Name*{Yamamoto, Isoroku}\\
-% |\RevName\Name*{Yamamoto, Isoroku}[Admiral]|\dotfill\RevName\Name*{Yamamoto, Isoroku}[Admiral]}\medskip
+% |\RevName\Name*{Yamamoto, Isoroku}[Admiral]|\dotfill\RevName\Name*{Yamamoto, Isoroku}[Admiral]\smallskip\\
+% |\Name{Miyazaki, Hayao}|\dotfill\Name{Miyazaki, Hayao}\\
+% |\Name*{Miyazaki, Hayao}[Sensei]|\dotfill\Name*{Miyazaki, Hayao}[Sensei]\\
+% |\RevName\Name*{Miyazaki, Hayao}[Mr.]|\dotfill\RevName\Name*{Miyazaki, Hayao}[Mr.]\egroup\medskip
%
-% \noindent Non-Western\marginpar{\large\raggedleft\textsf{\bfseries 3.0}\strut\break\small\dbend} forms also can have alternate names, except for mononyms (for which alternate names make no sense). Alternate names do not work with the older syntax for non-Western names (see Section~\ref{sec:obsolete}).
-% \clearpage
+% \bgroup\ifDoTikZ
+% \begin{tcolorbox}[colframe=naslate,adjusted title={\bfseries Ancient and Medieval Names}]\centering
+% \begin{tabular}{l@{ }c@{ }c}
+% & \small Required name & \small Optional,\\
+% & \small optional \meta{Affix} & \small in text only\smallskip\\
+% \tcbox[equal height group=D,colback=white,tikznode,left=1mm,right=1mm,valign=center]{\bfseries\strut \hbox{\cmd{\Name}\texttt{\space}}\\ \strut \cmd{\Name*}\\ \strut \cmd{\FName}} &
+% \tcbox[equal height group=D,colback=white,tikznode,left=1mm,right=1mm,valign=center]{\bfseries\marg{SNN\color{nared}, Affix}} &
+% \tcbox[equal height group=D,colback=white,tikznode,left=1mm,right=1mm,valign=center]{\bfseries\oarg{\color{nared}Alternate}}
+% \end{tabular}
%
-% \noindent{\bfseries Ancient Names}
-% \ifDoTikZ
-% \begin{center}
-% \begin{tikzpicture}[line/.style={draw,thick}]
-% \node [matrix,column sep=0.9em] (advice) at (0.6,1.4)
-% {
-% \node[align=center](opt){\small Add to force full name.}; &
-% \node[align=center](a1){\small Name(s)}; &
-% \node[text width=3.3cm,align=left](grp){\small Add only if text in brackets |[|\,|]| follows.}; \\
-% };
-% \node [matrix] (macro) at (0,0)
-% {
-% \node(cmd){\bfseries\cmd{\Name}}; &
-% \node(star){\bfseries\texttt{*}}; &
-% \node(arg1){\bfseries\marg{SNN\color{nared}, Affix}}; &
-% \node(braces){\bfseries|{}|}; \\
-% };
-% \begin{scope}[every path/.style=line]
-% \path (opt) -- (star);
-% \path (grp) -- (braces);
-% \path (arg1) -- (a1);
-% \end{scope}
-% \end{tikzpicture}
-% \end{center}\vspace{-2ex}
-% \else\vspace{20ex}\fi
-% \textbf{Examples:}\medskip
+% Add braces \texttt{\bfseries\{\,\}} after {\bfseries\marg{SNN\color{nared}, Affix}} if other text in brackets \texttt{\bfseries[\,]} follows.
+% \end{tcolorbox}
+% \else
+% \bigskip\noindent{\bfseries Ancient and Medieval Names}
%
-% \noindent These forms are meant for royalty and ancient figures. They have one or more personal names that may or may not have suffixes.\medskip
+% \bigskip\begin{tabular}{lcc}
+% & \small Required name & \small Optional,\\
+% & \small optional \meta{Affix} & \small in text only\smallskip\\
+% \cmd{\Name}\\
+% \cmd{\Name*} & \bfseries\marg{SNN\color{nared}, Affix} & \bfseries\oarg{\color{nared}Alternate}\\
+% \cmd{\FName}
+% \end{tabular}\\
%
-% {\noindent\setstretch{1.1}|\Name{Aristotle}|\dotfill\Name{Aristotle}\\
-% |\Name{Aristotle}|\dotfill\Name{Aristotle}\\
+% Add braces \texttt{\bfseries\{\,\}} after {\bfseries\marg{SNN\color{nared}, Affix}} if other text in brackets \texttt{\bfseries[\,]} follows.
+% \fi\egroup
+%
+% \begin{center}\bfseries Examples\end{center}
+%
+% \noindent These forms are meant for royalty and ancient figures. They can be mononyms or have multiple names, and may have an affix. Note the teaser for Section~\ref{sec:FName}:\medskip
+%
+% \bgroup\MyStretch\noindent|\Name{Aristotle}|\dotfill\Name{Aristotle}\\
+% |\Name{Aristotle}|\dotfill\Name{Aristotle}\smallskip\\
% |\Name{Elizabeth, I}|\dotfill\Name{Elizabeth, I}\\
-% |\Name{Elizabeth, I}|\dotfill\Name{Elizabeth, I}}
+% |\Name{Elizabeth, I}|\dotfill\Name{Elizabeth, I}\\
+% |\ForceFN\FName{Elizabeth, I}[Good Queen Bess]|\dotfill\ForceFN\FName{Elizabeth, I}[Good Queen Bess]\egroup
%
-% \subsection{Simplified Interface}
-% \label{sec:simplestart}%
+% \subsubsection{Simplified Interface}
+% \label{sec:SimpleStart}
%
% \DescribeEnv{nameauth}
-% The |nameauth| environment replaces \cmd{\Name}, \cmd{\Name*}, and \cmd{\FName} with shorthands. Using |nameauth| in the preamble is not required, but it helps prevent undefined control sequences. We set some names up below. Comments (shown in red) are added for explanation; they are not part of the environment itself.
-% \begin{quote}\small\setstretch{1.1}
-% {\color{nared}|% Field 1 Field 2 Field 3 Field 4|}\\
-% |\begin{nameauth}|\\[0.2ex]
-% | \< Wash & George & Washington & > |{\color{nared}|%|\hfill\emph{Western}}\\
-% | \< Soto & Hernando & de Soto & > |{\color{nared}|%|\hfill\emph{Western}}\\
-% | \< Pat & George S. & Patton, Jr. & > |{\color{nared}|%|\hfill\emph{W+affix}}\\
-% | \< JRIV & John David & Rockefeller, IV & > |{\color{nared}|%|\hfill\emph{W+affix}}\\
-% | \< Lewis & Clive Staples & Lewis & > |{\color{nared}|%|\hfill\emph{Western}}\\
-% | \< Aris & & Aristotle & > |{\color{nared}|%|\hfill\emph{Ancient}}\\
-% | \< Aeth & & Æthelred, II & > |{\color{nared}|%|\hfill\emph{Ancient}}\\
-% | \< Eliz & & Elizabeth, I & > |{\color{nared}|%|\hfill\emph{Ancient}}\\
-% | \< Attil & & Attila, the Hun & > |{\color{nared}|%|\hfill\emph{Ancient}}\\
-% | \< Konoe & Fumimaro & Konoe & > |{\color{nared}|%|\hfill\emph{W\,as\,East.}}\\
-% | \< Miyaz & & Miyazaki, Hayao & > |{\color{nared}|%|\hfill\emph{Eastern}}\\
-% | \< Yamt & & Yamamoto, Isoroku & > |{\color{nared}|%|\hfill\emph{Eastern}}\\
-% |\end{nameauth}|
+% Although not required, using the \texttt{nameauth} environment in the preamble guards against undefined macros. This environment defines a tabular-like macro:
+% \begin{quote}
+% \fbox{\vbox{
+% \hbox{\mystrut\ \cmd{\begin\{nameauth\}}}\par
+% \hbox{\hspace{2em}\cmd{\<} \meta{arg1} \texttt{\&} \meta{arg2} \texttt{\&} \meta{arg3} \texttt{\&} \meta{arg4} \texttt{>} }\par
+% \hbox{\mystrut\ \cmd{\end\{nameauth\}}}}}
% \end{quote}
+% It uses \meta{arg1} as a basis to create three macros that are equivalent to:\medskip
%
-% \begin{itemize}\small
-% \item Field 1 contains text that will be turned into three control sequences. For example, \texttt{Wash} generates \cmd{\Wash} (like \cmd{\Name}): \ForgetThis\Wash, \cmd{\LWash} (L for Long; like \cmd{\Name*}): \LWash, and \cmd{\SWash} (S for Short; like \cmd{\FName}): \SWash.
-% \item Fields~2 and~3 hold the name arguments.
-% \item Field 4 usually remains empty. It handles the older non-Western syntax (Section~\ref{sec:obsolete}) and permanent alternate names (next page).
-% \item In this context, ``|\<|'' is an escape character and a control sequence. If you forget it or just use |<| without the backslash, you will get errors.
-% \item There \emph{must} be four argument fields (three ampersands) per line. Leaving out an ampersand will cause an error.
-% \item Extra spaces in each |&|-delimited field are stripped, as is also the case in the traditional interface (Section~\ref{sec:tolerance}).
-% \item Put trailing braces |{|\,|}| or something else after the shorthands to prevent subsequent text in brackets |[|\,|]| from becoming an optional argument.
-% \end{itemize}
+% \begin{tabular}{@{\quad}l@{\ \(\rightarrow\)\ }ll}
+% \texttt{\textbackslash}\meta{arg1} & \cmd{\Name}\oarg{arg2}\marg{arg3}\oarg{arg4} \\
+% \texttt{\textbackslash L}\meta{arg1} & \cmd{\Name*}\oarg{arg2}\marg{arg3}\oarg{arg4} & {\color{nared} |%| L for \textit{long}} \\
+% \texttt{\textbackslash S}\meta{arg1} & \cmd{\FName}\oarg{arg2}\marg{arg3}\oarg{arg4} & {\color{nared} |%| S for \textit{short}} \\
+% \end{tabular}\medskip\\
+% If either \meta{arg1} or \meta{arg3} are empty, or \meta{SNN} is empty, \textsf{nameauth} will generate a package error. Forgetting the backslash, ampersands, or angle brackets will cause errors. For more on \meta{arg4} see page~\pageref{page:ArgIV}.
+% \newpage
%
-% \noindent\textbf{So, why use it?}\medskip
+% Comments below are not part of the environment. Extra spaces in each argument are stripped (Section~\ref{sec:ErrorProt}). Put trailing braces \texttt{\{\,\}} or something else after the shorthand macros if text in brackets \texttt{[\,]} follows, so it does not become an optional argument. Below we introduce name forms with particles.
%
-% \noindent The simplified interface can save work. Instead of the traditional interface macros on the left, one uses the simplified macros on the right:\\[1ex]
-% {\small\setstretch{1.1}
-% |\Name [George]{Washington}|\dotfill\cmd{\Wash}: \ForgetThis\Wash\\
-% |\Name*[George]{Washington}|\dotfill\cmd{\LWash}: \LWash\\
-% |\Name [George]{Washington}|\dotfill\cmd{\Wash}: \Wash\hphantom{ \SWash}\\
-% |\FName[George]{Washington}|\dotfill\cmd{\SWash}: \SWash\hphantom{ \Wash}\\[1ex]
-% |\IndexName[George]{Washington}|\dotfill\cmd{\JustIndex}\cmd{\Wash} \JustIndex\Wash\hphantom{:\LWash}\\[1ex]
-% |\ForgetName[George]{Washington}%|\\
-% |\Name[George]{Washington}|\dotfill\cmd{\ForgetThis}\cmd{\Wash}: \ForgetThis\Wash\\[1ex]
-% |\SubvertName[George]{Washington}%|\\
-% |\Name[George]{Washington}|\dotfill\cmd{\SubvertThis}\cmd{\Wash}: \SubvertThis\Wash\hphantom{ \SWash}}\medskip
+% \begin{center}\bfseries Examples\end{center}
+% \def\startrowa{\ \ \cmd{\< }}
+% \def\startrowb{\color{nared}\% }
+% \def\midrowa{\texttt{ \& }}
+% \def\midrowb{\texttt{\ \ \ }}
+% \def\endrowa{\texttt{ >}}
+% \def\endrowb{}
+% \def\startrow{\startrowb}
+% \def\midrow{\midrowb}
+% \def\endrow{\endrowb}
+% \bgroup\noindent\ttfamily\small| \begin{nameauth}|\\
+% \begin{tabular}{>{\startrow}l@{\midrow}l@{\midrow}l@{\midrow}l@{\endrow}l}
+% {\normalfont\color{nared}\quad\ \ \,\meta{arg1}}\gdef\startrow{\startrowa} & {\normalfont\color{nared}\meta{arg2}} & {\normalfont\color{nared}\meta{arg3}} & {\normalfont\color{nared}\meta{arg4}}\\\gdef\midrow{\midrowa}\gdef\endrow{\endrowa}%^^A
+% Wash & George & Washington & &{\color{nared} \% \normalfont\textit{Western}}\\
+% Harnack & Adolf & Harnack & &{\color{nared} \% \normalfont\textit{Western}}\\
+% Lewis & Clive Staples & Lewis & &{\color{nared} \% \normalfont\textit{Western}}\\
+% Pat & George S. & Patton, Jr. & &{\color{nared} \% \normalfont\textit{W. affix}}\\
+% JRIV & John David & Rockefeller, IV & &{\color{nared} \% \normalfont\textit{W. affix}}\\
+% Ches & Chesley B. & Sullenberger, III & &{\color{nared} \% \normalfont\textit{W. affix}}\\
+% Soto & Hernando & de Soto & &{\color{nared} \% \normalfont\textit{W. part.}}\\
+% JWG & J.W. von & Goethe & &{\color{nared} \% \normalfont\textit{W. part.}}\\
+% VBuren & Martin & Van Buren & &{\color{nared} \% \normalfont\textit{W. part.}}\\
+% Noguchi & Hideyo & Noguchi & &{\color{nared} \% \normalfont\textit{W. as E.}}\\
+% Miyaz & & Miyazaki, Hayao & &{\color{nared} \% \normalfont\textit{Eastern}}\\
+% Yamt & & Yamamoto, Isoroku & &{\color{nared} \% \normalfont\textit{Eastern}}\\
+% Aeth & & Æthelred, II & &{\color{nared} \% \normalfont\textit{Ancient}}\\
+% Attil & & Attila, the Hun & &{\color{nared} \% \normalfont\textit{Ancient}}\\
+% Dem & & Demetrius, I & &{\color{nared} \% \normalfont\textit{Ancient}}\\
+% Eliz & & Elizabeth, I & &{\color{nared} \% \normalfont\textit{Ancient}}\\
+% Aris & & Aristotle & &{\color{nared} \% \normalfont\textit{Mono}}\\
+% CSL & Clive Staples & Lewis & C.S. &{\color{nared} \% \normalfont\textit{W. alt.}}\\
+% MSens & & Miyazaki, Hayao & Sensei &{\color{nared} \% \normalfont\textit{E. alt.}}\\
+% \end{tabular}\\
+% | \end{nameauth}|\egroup\medskip
%
-% \noindent\textbf{Examples:}\medskip
-%
-% \noindent Below, ``non-native'' Eastern name forms are shown with a dagger (\dag). Please see Section~\ref{sec:Eastern} to avoid pitfalls with Eastern names and reversing macros. We reset some ``first uses'' of names from before (Section~\ref{sec:tweaks}).
-%
-% \begin{center}\footnotesize\setstretch{1.1}
-% \begin{tabular}{@{}ll@{}}
-% \textsc{Western:} & \textsc{Ancient\,/\,Mononym} \\
-% |\Wash | \dotfill \ForgetThis\Wash & |\Aris| \dotfill \ForgetThis\Aris \\
-% |\LWash| \dotfill \LWash & |\Aris| \dotfill \Aris \\
-% |\Wash | \dotfill \Wash & \\
-% |\SWash| \dotfill \SWash & \textsc{Medieval/Royal:} \\
-% |\RevComma\LWash| \dotfill \RevComma\LWash & |\Eliz | \dotfill \ForgetThis\Eliz \\
-% & |\Eliz | \dotfill \Eliz \\
-% \textsc{Particles:} \hfill (Section~\ref{sec:standards}) & |\LEliz[the First]| \dotfill \LEliz[the First] \\
-% |\Soto| \dotfill \ForgetThis\Soto & |\Attil| \dotfill \ForgetThis\Attil \\
-% |\Soto| \dotfill \Soto & |\Attil| \dotfill \Attil\\
-% |\CapThis\Soto| \dotfill \CapThis\Soto & \\
-% & \textsc{``Non-native'' Eastern:} \\
-% \textsc{Affixes:} \hfill (Section~\ref{sec:Affix}) & |\Konoe | \dotfill \ForgetThis\Konoe\dag \\
-% |\Pat | \dotfill \ForgetThis\Pat & |\LKonoe| \dotfill \LKonoe\dag \\
-% |\LPat| \dotfill \LPat & |\LKonoe[Minister]| \dotfill \LKonoe[Minister]\dag \\
-% |\DropAffix\LPat| \dotfill \DropAffix\LPat & |\Konoe | \dotfill \Konoe\dag \\
-% |\Pat | \dotfill \Pat & |\SKonoe| \dotfill \SKonoe\dag \\
-% |\SPat| \dotfill \SPat & |\CapName\RevName\LKonoe| \dotfill \CapName\RevName\LKonoe\dag \\
-% & |\CapName\Konoe| \dotfill \CapName\Konoe\dag \\
-% \textsc{Nicknames:} \hfill (Section~\ref{sec:Fname}) & \\
-% |\JRIV | \dotfill \ForgetThis\JRIV & \textsc{``Native'' Eastern:} \\
-% |\DropAffix\LJRIV[Jay]| \dotfill \DropAffix\LJRIV[Jay] & |\CapName\Yamt| \dotfill \ForgetThis\CapName\Yamt \\
-% |\SJRIV[Jay]| \dotfill \SJRIV[Jay] & |\CapName\LYamt| \dotfill \CapName\LYamt \\
-% |\Lewis| \dotfill \ForgetThis\Lewis & |\CapName\Yamt| \dotfill \CapName\Yamt \\
-% |\LLewis[Jack]| \dotfill \LLewis[Jack] & |\RevName\LYamt| \dotfill \RevName\LYamt \\
-% |\SLewis[Jack]| \dotfill \SLewis[Jack] & |\RevName\LYamt[Admiral] | \dotfill \RevName\LYamt[Admiral] \\
-% |\LCSL| \dotfill \LCSL & |\SYamt| \dotfill \SYamt \\
-% |\SCSL | \dotfill \SCSL & |\ForceFN\SYamt| \dotfill \ForceFN\SYamt \\
+% \begin{center}\small\MyStretch
+% \begin{tabular}{rlp{0.41\textwidth}}\toprule
+% Output & Short Form & Long Form\\\midrule
+% \Wash & \cmd{\Wash} & \cmd{\Name}\texttt{[George]\{Washington\}}\\
+% \rowcolor{black!7!white}\LWash & \cmd{\LWash} & \cmd{\Name*}\texttt{[George]\{Washington\}}\\
+% \SWash & \cmd{\SWash} & \cmd{\FName}\texttt{[George]\{Washington\}}\\
+% \rowcolor{black!7!white}\JustIndex\Wash & \cmd{\JustIndex}\cmd{\Wash} & \cmd{\IndexName}\texttt{[George]\{Washington\}}\\
+% \Eliz & \cmd{\SubvertThis}\cmd{\Eliz} & \cmd{\SubvertThis}\cmd{\Name}\texttt{\{Elizabeth,I\}}\\
+% \rowcolor{black!7!white}\ForgetThis\Eliz & \cmd{\ForgetThis}\cmd{\Eliz} & \cmd{\ForgetThis}\cmd{\Name}\texttt{\{Elizabeth,I\}}\\\bottomrule
% \end{tabular}
% \end{center}
-% \ExcludeName{Attila, the Hun}
%
-% \noindent\textbf{Some Devils in the Details:}\medskip
+% English and modern Romance languages keep the particle with the surname. German and other languages do not (cf. Sections~\ref{sec:NameParticles} and~\ref{sec:AltFormat}).\footnote{See also [\hyperlink{Mulvany}{Mulvany}, 152--82], and the \textit{Chicago Manual of Style}.}
%
-% \noindent English keeps the prefix with the surname in the text and the index, while German keeps particles separate:
-% \begin{quote}\small\setstretch{1.1}
-% |\begin{nameauth}|\\[0.2ex]
-% | \< JWG & J.W. von & Goethe & > |{\color{nared}|%|\hfill\emph{Western; German}}\\
-% | \< VBuren & Martin & Van Buren & > |{\color{nared}|%|\hfill\emph{Western; English}}\\
-% |\end{nameauth}|
-% \end{quote}
+% \begin{center}\small\MyStretch
+% \begin{tabular}{rll}\toprule
+% \bfseries Macro & \bfseries Body Text & \bfseries Index \\\midrule
+% \cmd{\VBuren} & \VBuren & \ShowIdxPageref*[Martin]{Van Buren}\\
+% \rowcolor{black!7!white}\cmd{\VBuren} & \VBuren & \ShowIdxPageref*[Martin]{Van Buren}\\
+% \cmd{\Soto} & \Soto & \ShowIdxPageref*[Hernando]{de Soto}\\
+% \rowcolor{black!7!white}\cmd{\CapThis}\cmd{\Soto} & \CapThis\Soto & \ShowIdxPageref*[Hernando]{de Soto}\\
+% \cmd{\JWG} & \JWG & \ShowIdxPageref*[J.W. von]{Goethe}\\
+% \rowcolor{black!7!white}\cmd{\JWG} & \JWG & \ShowIdxPageref*[J.W. von]{Goethe}\\\bottomrule
+% \end{tabular}
+% \end{center}
+% \newpage
%
-% \VBuren\ is ``Van Buren, Martin'' in the index. \cmd{\JWG} prints \JWG\ and \JWG, with ``Goethe, J.W. von'' in the index. You get a quasi-Anglicized \LJWG[von] with |\LJWG[von]|. Either |\CapThis\LJWG[Von]| or |\LJWG[Von]| produce \CapThis\LJWG[von]; see Section~\ref{sec:standards}. Additionally, [\hyperlink{Mulvany}{Mulvany}, 152--82] and the \emph{Chicago Manual of Style} offer helpful guidance.\ForgetName[J.W. von]{Goethe}
+% \begin{center}\bfseries \meta{Alternate} Tips\end{center}
%
-% Normally you would use something like |\LLewis[C.S.]| to get \LLewis[C.S.] instead of \LLewis. You can make that permanent, where \SCSL\ always prints in the text, yet the index always shows ``Lewis, Clive Staples. Some permanent alternate names are shown below:
+% \phantomsection
+% \noindent Above we listed two shorthands that had alternate names in \meta{arg4}: \cmd{\CSL} and \cmd{\MSens}. They have related shorthands whose \meta{arg4} are empty: \cmd{\Lewis} and \cmd{\Miyaz}. Here are how they are related (cf. Section~\ref{sec:FName}):\label{page:ArgIV}
+% \begin{itemize}
+% \item They share the same name patterns (Section~\ref{sec:NamePatterns}): |\ForgetThis\Lewis| \ForgetThis\Lewis; \cmd{\CSL} \CSL. |\ForgetThis\Miyaz| \ForgetThis\Miyaz; and \cmd{\MSens} \MSens.
+% \item More commonly, one produces alternate names with \cmd{\LLewis[C.S.]} \LLewis[C.S.] and \cmd{\LMiyaz[Sensei]} \LMiyaz[Sensei].
+% \item Both\Warn{} \cmd{\LCSL} \LCSL\ and \cmd{\LMSens} \LMSens\ already have \meta{Alternate} built in. They cannot take another optional argument. One must remember which shorthands have used \meta{arg4}.
+% \item If one should forget that, one will get errors: \cmd{\LCSL[C.S.]} \LCSL[C.S.] and \cmd{\LMsens[Sensei]} \LMSens[Sensei].
+% \end{itemize}
%
-% \begin{quote}\small\setstretch{1.1}
-% |\begin{nameauth}|\\[0.2ex]
-% | \< JayR & John David & Rockefeller, IV & Jay > |{\color{nared}|%|\hfill\emph{Western}}\\
-% | \< CSL & Clive Staples & Lewis & C.S. > |{\color{nared}|%|\hfill\emph{Western}}\\
-% | \< Unraed & & Æthelred, II & Unrædig > |{\color{nared}|%|\hfill\emph{Ancient}}\\
-% | \< MSens & & Miyazaki, Hayao & Sensei > |{\color{nared}|%|\hfill\emph{Eastern}}\\
-% |\end{nameauth}|
-% \end{quote}
+% \begin{center}\bfseries Variant Overview\end{center}
%
-% With the names above you get \ForgetThis\JayR, \ForgetThis\CSL, \ForgetThis\Unraed, and \ForgetThis\MSens\ instead of those from the previous page: \LJRIV, \LLewis, \LAeth, and \LMiyaz.\footnote{One could use \cmd{\AKA} to create a cross-reference \AKA[John David]{Rockefeller, IV}[Jay]{Rockefeller}. See Sections~\ref{sec:IndexXref} and~\ref{sec:AKA}.} They all have the same respective index entries and first/subsequent uses, which is why we forced the formatting in the names above. Also |\LLewis[Jack]| prints \LLewis[Jack] while |\LCSL[Jack]| prints \LCSL[Jack]. Section~\ref{sec:Fname} explains why.
+% \begin{center}\footnotesize\MyStretch
+% \begin{tabular}{@{}p{18.4em}p{22.4em}@{}}
+% \textsc{Western:}\par
+% |\Wash|\dotfill \ForgetThis\Wash\par
+% |\LWash|\dotfill \LWash\par
+% |\Wash|\dotfill \Wash\par
+% |\SWash|\dotfill \SWash\par
+% |\RevComma\LWash|\dotfill \RevComma\LWash\par
+% \par\hbox{}\par
+% \textsc{Particles:} \hfill (Section~\ref{sec:NameParticles})\par
+% |\Soto|\dotfill \ForgetThis\Soto\par
+% |\Soto|\dotfill \Soto\par
+% |\CapThis\Soto|\dotfill \CapThis\Soto\par
+% \par\hbox{}\par
+% \textsc{Affixes:} \hfill (Section~\ref{sec:Affix})\par
+% |\Pat|\dotfill \ForgetThis\Pat\par
+% |\LPat|\dotfill \LPat\par
+% |\DropAffix\LPat|\dotfill \DropAffix\LPat\par
+% |\Pat|\dotfill \Pat\par
+% |\SPat|\dotfill \SPat\par
+% \par\hbox{}\par
+% \textsc{Nicknames:} \hfill (Section~\ref{sec:FName})\par
+% |\JRIV|\dotfill \ForgetThis\JRIV\par
+% |\DropAffix\LJRIV[Jay]|\dotfill \DropAffix\LJRIV[Jay]\par
+% |\SJRIV[Jay]|\dotfill \SJRIV[Jay]\par
+% |\Lewis|\dotfill \ForgetThis\Lewis\par
+% |\LLewis[Jack]|\dotfill \LLewis[Jack]\par
+% |\SLewis[Jack]|\dotfill \SLewis[Jack]\par
+% |\LCSL|\dotfill \LCSL\par
+% |\SCSL|\dotfill \SCSL
+% &
+% \textsc{Ancient\,/\,Mononym}\par
+% |\Aris|\dotfill \ForgetThis\Aris\par
+% |\Aris|\dotfill \Aris \par
+% \par\hbox{}\par
+% \textsc{Ancient\,/\,Royal:} \hfill (Sections~\ref{sec:Eastern}, \ref{sec:NameParticles})\par
+% |\Aeth|\dotfill \ForgetThis\Aeth\par
+% |\Aeth|\dotfill \Aeth\par
+% |\LAeth[Unrædig]|\dotfill \LAeth[Unrædig]\par
+% |\Attil|\dotfill \ForgetThis\Attil\par
+% |\Attil|\dotfill \Attil\par
+% \par\hbox{}\par
+% \textsc{``Non-native'' Eastern:} \hfill (Section~\ref{sec:Eastern})\par
+% |\Noguchi|\dotfill \ForgetThis\Noguchi\par
+% |\LNoguchi|\dotfill \LNoguchi\par
+% |\LNoguchi[Doctor]|\dotfill \LNoguchi[Doctor]\par
+% |\SNoguchi|\dotfill \SNoguchi\par
+% |\RevName\LNoguchi|\dotfill \RevName\LNoguchi\dag\par
+% |\CapName\RevName\LNoguchi|\dotfill \CapName\RevName\LNoguchi\dag\par
+% |\CapName\Noguchi|\dotfill \CapName\Noguchi\dag\par
+% \par\hbox{}\par
+% \textsc{``Native'' Eastern:} \hfill (Section~\ref{sec:Eastern})\par
+% |\CapName\Yamt|\dotfill \ForgetThis\CapName\Yamt\par
+% |\CapName\LYamt|\dotfill \CapName\LYamt\par
+% |\CapName\Yamt|\dotfill \CapName\Yamt\par
+% |\RevName\LYamt|\dotfill \RevName\LYamt\par
+% |\RevName\LYamt[Admiral]|\dotfill \RevName\LYamt[Admiral]\par
+% |\SYamt|\dotfill \SYamt\par
+% |\ForceFN\SYamt|\dotfill \ForceFN\SYamt
+% \\
+% \end{tabular}
+% \end{center}
+% Above we used \cmd{\ForgetThis} (Section~\ref{sec:NameControl}) to reset first uses of names. Now we set up examples on page~\pageref{page:ExPage} by invoking \cmd{\ExcludeName\{Attila, the Hun\}}\ExcludeName{Attila, the Hun} and \cmd{\AKA[John David]\{Rockefeller,IV\}[Jay]\{Rockefeller\}} \AKA[John David]{Rockefeller,IV}[Jay]{Rockefeller}. On why that form has a different index entry than |\DropAffix\LJRIV[Jay]| \DropAffix\LJRIV[Jay], see Sections~\ref{sec:IndexXref} and~\ref{sec:AKA}.
+% \newpage
%
-% The simplified\marginpar{\small\raggedleft\dbend} interface can tempt one into completely equating a name with its shortcut. Here we show that to be false. |\ForgetThis\CSL| prints \ForgetThis\CSL. Then |\Lewis| prints \Lewis. Likewise, |\ForgetThis\Lewis| prints \ForgetThis\Lewis. Then |\CSL| prints \CSL. The name itself is the pattern that governs everything. Internally, that detokenized pattern is |CliveStaples!Lewis|. Non-western names have patterns like |Elizabeth,I| and |Yamamoto,Isoroku|. Mononyms are their own pattern: |Aristotle|.
+% \subsubsection[Macro Overview]{Select Macro Overview}
+% \label{sec:SelectOver}
%
-% For the same reasons,\marginpar{\small\raggedleft\dbend} when index tagging or pre-tagging names, the \meta{Alternate names} field has no effect on index tags. \cmd{\JRIV} and \cmd{\JayR} need only one tag, as do \cmd{\Lewis} and \cmd{\CSL}:
-% \begin{quote}\small\setstretch{1.1}
-% |\TagName[John David]{Rockefeller, IV}{|\meta{something}|}|\\
-% |\TagName[Clive Staples]{Lewis}{|\meta{something}|}|
-% \end{quote}
+% \noindent Below we have a partial selection of macros and their arguments in overview:
+% \begin{center}\small\MySmallStretch
+% \begin{tabular}{lrccl}\toprule
+% \meta{prefix macros} & \cmd{\Name} & \meta{optional *} & \meta{name args} & \\
+% \meta{prefix macros} & \cmd{\FName} & \meta{optional *} & \meta{name args} & \\
+% \rowcolor{black!7!white}\meta{prefix macros} & \cmd{\IndexName} & & \meta{name args} & \\
+% \rowcolor{black!7!white}\meta{prefix macros} & \cmd{\IndexRef} & & \meta{xref args} & \meta{target}\\
+% \meta{prefix macros} & \cmd{\AKA} & \meta{optional *} & \meta{target args} & \meta{xref args}\\
+% \rowcolor{black!7!white} & \cmd{\ExcludeName} & & \meta{name args} & \\
+% \rowcolor{black!7!white} & \cmd{\IncludeName} & \meta{optional *} & \meta{name args} & \\
+% & \cmd{\PretagName} & & \meta{name args} & \meta{sort key} \\
+% & \cmd{\TagName} & & \meta{name args} & \meta{tag} \\
+% & \cmd{\UntagName} & & \meta{name args} & \\
+% \rowcolor{black!7!white} & \cmd{\NameAddInfo} & & \meta{name args} & \meta{tag} \\
+% \rowcolor{black!7!white} & \cmd{\NameQueryInfo} & & \meta{name args} & \\
+% \rowcolor{black!7!white} & \cmd{\NameClearInfo} & & \meta{name args} & \\
+% & \cmd{\ForgetName} & & \meta{name args} & \\
+% & \cmd{\SubvertName} & & \meta{name args} & \\
+% \rowcolor{black!7!white} & \cmd{\IfMainName} & & \meta{name args} & \marg{y}\marg{n}\\
+% \rowcolor{black!7!white} & \cmd{\IfFrontName} & & \meta{name args} & \marg{y}\marg{n}\\
+% \rowcolor{black!7!white} & \cmd{\IfAKA} & & \meta{name args} & \marg{y}\marg{n}\marg{x}\\\bottomrule
+% \end{tabular}
+% \end{center}
%
-% Sections~\ref{sec:standards},\marginpar{\small\raggedleft\dbend} \ref{sec:accents}, and~\ref{sec:IndexSort} deal with the pitfalls of accents and capitalization, as well as why you should use \cmd{\PretagName} when dealing with names that contain control sequences or active Unicode characters.
-% \clearpage
+% \noindent The \meta{prefix macros} below have a one-time effect per name and they also stack. For example: |\CapThis\RevName\SkipIndex\Name[bar]{foo}|: \CapThis\RevName\SkipIndex\Name[bar]{foo}.
+% \begin{center}\small\MySmallStretch
+% \begin{tabular}{rp{0.72\textwidth}}\toprule
+% & \bfseries Capitalization in the Text\\
+% \cmd{\CapThis} & Capitalize first letter of all name components in body text.\\
+% \cmd{\AccentCapThis} & Fallback when Unicode detection cannot be done.\\
+% \cmd{\CapName} & Cap entire \meta{SNN} in body text. Overrides \cmd{\CapThis}.\\
+% \rowcolor{black!7!white} & \bfseries Reversing in the Text\\
+% \rowcolor{black!7!white}\cmd{\RevName} & Reverse order of any name in body text. Overrides \cmd{\RevComma}\\
+% \rowcolor{black!7!white}\cmd{\RevComma} & Reverse only Western names to \meta{SNN}, \meta{FNN}.\\
+% & \bfseries Commas in the Text\\
+% \cmd{\ShowComma} & Add comma between \meta{SNN} and \meta{Affix}.\\
+% \cmd{\NoComma} & No comma between \meta{SNN} and \meta{Affix}. Overrides \cmd{\ShowComma}.\\
+% \rowcolor{black!7!white} & \bfseries Name Breaks in the Text\\
+% \rowcolor{black!7!white}\cmd{\DropAffix} & Drop affix only for a long Western name reference.\\
+% \rowcolor{black!7!white}\cmd{\KeepAffix} & Insert non-breaking space (NBSP) between \meta{SNN}, \meta{FNN/Affix}.\\
+% \rowcolor{black!7!white}\cmd{\KeepName} & Insert NBSP between all name elements. Overrides \cmd{\KeepAffix}.\\
+% & \bfseries Forcing Name Forms in the Text\\
+% \cmd{\ForgetThis} & Force a first-time name use. Negates \cmd{\SubvertThis}.\\
+% \cmd{\SubvertThis} & Force a subsequent use.\\
+% \cmd{\ForceName} & Force first-use formatting hooks.\\
+% \cmd{\ForceFN} & Force printing of \meta{Affix} in non-Western short forms.\\
+% \rowcolor{black!7!white} & \bfseries Indexing\\
+% % \rowcolor{black!7!white}\cmd{\SeeAlso} & Make a \textit{see also} reference instead of a page reference. Only for use with \cmd{\IndexRef}, \cmd{\AKA}, \cmd{\PName} and their starred variants.\\
+% \rowcolor{black!7!white}\cmd{\SkipIndex} & Do not create index entries.\\
+% \rowcolor{black!7!white}\cmd{\JustIndex} & Act like \cmd{\IndexName}; negated by \cmd{\AKA}, \cmd{\PName}.\\\bottomrule
+% \end{tabular}
+% \end{center}
+%
+% \ReturnLink
+% \newpage
%
-% \subsection{Older Syntax}
-% \label{sec:obsolete}
+% \subsection{Obsolete Syntax}
+% \label{sec:Obsolete}
%
-% An older syntax for non-Western names remains for backward compatibility with early versions of \textsf{nameauth}. The older syntax prevents the use of alternate names, limits the use of \cmd{\AKA} (Section~\ref{sec:AKA}) and excludes comma-delimited suffixes. Otherwise it works seamlessly with the new syntax.
+% This ``ghost''\Warn{} of \textsf{nameauth} past limits alternate names and cross-references (Section~\ref{sec:AKA}), excludes comma-delimited names, and complicates indexing and tagging (Sections~\ref{sec:IndexTag} and~\ref{sec:TextTags}). When the \meta{FNN} and \meta{Affix} arguments are empty, \meta{Alternate} acts like \meta{Affix} and affects both name and index patterns (Section~\ref{sec:NamePatterns}). In this manual we designate these names with a double dagger (\ddag):
%
-% The big change is, instead of using a comma-delimited affix, this form uses the final optional argument for personal names and affixes. When \textsf{nameauth} was young, this seemed the intuitive approach to take. Now it only remains so that older documents still work today.
-% \begin{quote}\small\setstretch{1.1}
-% |\Name{Henry}[VIII] |{\color{nared}| %|\hfill\emph{royal name}}\\
-% |\Name{Chiang}[Kai-shek] |{\color{nared}| %|\hfill\emph{Eastern name}}\\
+% \begin{quote}\small\MyStretch
+% |\Name{Henry}[VIII] | {\color{nared}|%| \textit{Ancient}}\\
+% |\Name{Chiang}[Kai-shek] | {\color{nared}|%| \textit{Eastern}}\\
% |\begin{nameauth}|\\
-% | \< Dagb & & Dagobert & I > |{\color{nared}| %|\hfill\emph{royal name}}\\
-% | \< Yosh & & Yoshida & Shigeru > |{\color{nared}|%|\hfill\emph{Eastern name}}\\
-% |\end{nameauth}|
+% | \< Dagb & & Dagobert & I > | {\color{nared}|%| \textit{Ancient}}\\
+% | \< Yosh & & Yoshida & Shigeru > | {\color{nared}|%| \textit{Eastern}}\\
+% |\end{nameauth}|\medskip
% \end{quote}
-% Since the \meta{FNN} fields are empty, the final field becomes either \meta{affix} or \meta{FNN} and will appear in the index. We show these names with a double dagger (\ddag):
%
-% \begin{center}\small\setstretch{1.1}
+% \begin{center}\small\MyStretch
% \begin{tabular}{ll}\toprule
-% |\Name{Henry}[VIII]| & \Name{Henry}[VIII]\ddag\\
-% |\Name{Henry}[VIII]| & \Name{Henry}[VIII]\ddag\\
-% |\Name{Chiang}[Kai-shek]| & \Name{Chiang}[Kai-shek]\ddag\\
-% |\Name{Chiang}[Kai-shek]| & \Name{Chiang}[Kai-shek]\ddag\\\midrule
-% |\Dagb| & \Dagb\ddag\\
-% |\Dagb| & \Dagb\ddag\\
-% |\CapName\Yosh| & \CapName\Yosh\ddag\\
-% |\CapName\RevName\LYosh| & \CapName\RevName\LYosh\ddag\\\bottomrule
+% |\Name{Henry}[VIII]| & \Name{Henry}[VIII]\ddag\\
+% |\Name{Henry}[VIII]| & \Name{Henry}[VIII]\ddag\\
+% \rowcolor{black!7!white}|\Name{Chiang}[Kai-shek]| & \Name{Chiang}[Kai-shek]\ddag\\
+% \rowcolor{black!7!white}|\Name{Chiang}[Kai-shek]| & \Name{Chiang}[Kai-shek]\ddag\\
+% |\Dagb| & \Dagb\ddag\\
+% |\Dagb| & \Dagb\ddag\\
+% \rowcolor{black!7!white}|\CapName\Yosh| & \CapName\Yosh\ddag\\
+% \rowcolor{black!7!white}|\CapName\RevName\LYosh| & \CapName\RevName\LYosh\ddag\\\bottomrule
% \end{tabular}
% \end{center}
%
-% \noindent|\Name{Henry}[VIII]|\marginpar{\large\raggedleft\textsf{\bfseries 2.6}\strut\break\small\raggedleft\dbend} (older syntax) will share name occurrences, tags, and index entries with |\Name{Henry, VIII}| (new syntax), as we see below. We recommend using the newer syntax unless otherwise needed.
-% \begin{quote}\small\setstretch{1.1}
-% \NameAddInfo{Henry}[VIII]{ (\emph{Defensor Fidei})}|\NameAddInfo{Henry}[VIII]{ (\emph{Defensor Fidei})} |{\color{nared}|% older|}\\
-% \texttt{\dots} |\Name*{Henry, VIII}\NameQueryInfo{Henry, VIII} |{\,\color{nared}| % new|}\\[0.5ex]
+% |\Name{Henry}[VIII]|\Version{2.6} (older syntax) and |\Name{Henry, VIII}| (new syntax) share name patterns, tags, and index entries, as shown below. We recommend using the newer syntax unless otherwise needed.
+% \begin{quote}\small
+% \NameAddInfo{Henry}[VIII]{ (\textit{Defensor Fidei})}%
+% |\NameAddInfo{Henry}[VIII]{ (\textit{Defensor Fidei})}|{\color{nared}| % old|}\\
+% {.\,.\,.}\\
+% |\Name*{Henry, VIII}\NameQueryInfo{Henry, VIII} |{\color{nared}| % new|}\smallskip\\
% \Name*{Henry, VIII}\NameQueryInfo{Henry, VIII}
% \end{quote}
+%
+% \ReturnLink
%
-% Presently\marginpar{\large\raggedleft\textsf{\bfseries 3.0}\strut\break\small\raggedleft\dbend} |\Name*{Henry, VIII}[Tudor]| prints ``\Name*{Henry, VIII}[Tudor]'' in the body text and ``Henry VIII'' in the index. Before version 3.0 it would have produced ``Henry VIII Tudor'' in the text and in the index. \textbf{The older behavior was discouraged. It is obsolete and not supported.} See also Sections~\ref{sec:indextag} and~\ref{sec:tagtext}.
-% \clearpage
+% \subsection{Name Pattern Overview}
+% \label{sec:NamePatterns}
%
-% \subsection{Reference Tables}
-% \label{sec:RefTables}
+% The table below shows how the macro arguments generate name patterns central to \textsf{nameauth}. The \meta{Alternate} argument only affects patterns when using the obsolete syntax. The naming macro arguments create internal control sequences that affect names in both the text and the index:
%
-% \begin{center}\large\bfseries Getting Things Done\end{center}
-% Here we link from general tasks to relevant sections. The end of each section listed in the table has a return link to this section.
-% \begin{center}
-% \begin{tabular}{p{0.5\textwidth}l@{ }r}
-% \bfseries I want to\dots & \bfseries Topic & \bfseries Section \\\toprule
-% implement standard scholarly names & \cmd{\Name} & \ref{sec:Naming}\\\midrule
-% refer to forenames and affixes & \cmd{\FName} & \ref{sec:Fname}\\
-% & forcing references & \ref{sec:tweaks}\\\midrule
-% use surnames with inflected or alternate & indexing control & \ref{sec:indexctrl}\\
-% forms without creating unwanted index & forcing references & \ref{sec:tweaks}\\
-% entries & alternate spellings & \ref{sec:DuBois}\\\midrule
-% use affixes in names & comma delimiter & \ref{sec:Affix}\\\midrule
-% use ``native'' Eastern name forms & comma delimiter & \ref{sec:Affix}\\
-% & Eastern names & \ref{sec:Eastern}\\\midrule
-% use reversing and all caps for all Eastern name forms in body text only & Eastern names & \ref{sec:Eastern}\\\midrule
-% use discretionary caps in body text only & particles & \ref{sec:standards}\\\midrule
-% use discretionary caps in text and index & advanced hooks & \ref{sec:Hooksc}\\\midrule
-% handle non-English names and & particles & \ref{sec:standards}\\
-% Continental formatting & accents & \ref{sec:accents}\\
-% & non-English format & \ref{sec:altformat}\\
-% & indexing control & \ref{sec:indexctrl}\\
-% & index sorting & \ref{sec:IndexSort}\\
-% & advanced hooks & \ref{sec:Hooksc}\\\midrule
-% not have affixes be present by default & index tags & \ref{sec:indextag}\\
-% in long name forms & text tags & \ref{sec:tagtext}\\\midrule
-% manage index cross-references & cross-references & \ref{sec:IndexXref}\\
-% & alternate names & \ref{sec:AKA}\\\midrule
-% format variant name forms & formatting & \ref{sec:formatting}\\
-% & indexing control & \ref{sec:indexctrl}\\
-% & forcing references & \ref{sec:tweaks}\\
-% & alternate spellings & \ref{sec:DuBois}\\\midrule
-% use \textsf{nameauth} with beamer overlays & formatting & \ref{sec:formatting}\\
-% or design a game book & index tags & \ref{sec:indextag}\\
-% or design a history book & text tags & \ref{sec:tagtext}\\
-% or use many dynamic name elements & name tests & \ref{sec:tests}\\
-% or force name elements to be constant & forcing references & \ref{sec:tweaks}\\
-% & life dates & \ref{sec:Hooksb}\\
-% & advanced hooks & \ref{sec:Hooksc}\\\bottomrule
+% \begin{center}\MyStretch
+% \begin{tabular}{lll}\toprule
+% Macro Arguments & Patterns & Type\\\midrule
+% \rowcolor{black!7!white}\oarg{FNN}\marg{SNN} & \meta{FNN}!\meta{SNN} & \normalfont Western\\
+% \oarg{FNN}\marg{SNN, Affix} & \meta{FNN}!\meta{SNN},\meta{Affix} & \normalfont Western\\
+% \rowcolor{black!7!white}\hphantom{\oarg{FNN}}\marg{SNN, Affix} & \meta{SNN},\meta{Affix} & \normalfont non-Western\\
+% \hphantom{\oarg{FNN}}\marg{SNN}\oarg{Alt} & \meta{SNN},\meta{Alt} & \normalfont (obsolete)\\
+% \rowcolor{black!7!white}\hphantom{\oarg{FNN}}\marg{SNN} & \meta{SNN} & \normalfont mononym\\\bottomrule
% \end{tabular}
% \end{center}
-% \clearpage
+% \newpage
%
-% \begin{center}\large\bfseries Form and Format Overview\end{center}
-% Below we see how the naming macros generate output. First uses of a name are full references and call first-use formatting hooks. Subsequent uses can be longer or shorter, calling their own hooks unless \cmd{\ForceName} changes that (Section~\ref{sec:formatting}). Section~\ref{sec:tweaks} also has more information on how to change things. For changes to \cmd{\AKA} and friends, the \texttt{alwaysformat} option may be needed (Section~\ref{sec:AKA}).\bigskip
+% \noindent We ``forget'' several names below to create first-use cases:
+% \begin{center}\footnotesize\MyStretch
+% \begin{tabular}{rll}\toprule
+% Macro & Body Text & \cmd{\ShowPattern}\\\midrule
+% \cmd{\Harnack[Adolf von]} & \Harnack[Adolf von] & \texttt{\ShowPattern[Adolf]{Harnack}}\\
+% \cmd{\LHarnack} & \LHarnack & \texttt{\ShowPattern[Adolf]{Harnack}}\\
+% \rowcolor{black!7!white}\cmd{\ForgetThis}\cmd{\Pat} & \ForgetThis\Pat & \texttt{\ShowPattern[George S.]{Patton, Jr.}}\\
+% \rowcolor{black!7!white}\cmd{\DropAffix}\cmd{\LPat} & \DropAffix\LPat & \texttt{\ShowPattern[George S.]{Patton, Jr.}}\\
+% \cmd{\ForgetThis}\cmd{\Noguchi} & \ForgetThis\Noguchi & \texttt{\ShowPattern[Hideyo]{Noguchi}}\\
+% \cmd{\RevName}\cmd{\LNoguchi} & \RevName\LNoguchi\dag & \texttt{\ShowPattern[Hideyo]{Noguchi}}\\
+% \rowcolor{black!7!white}\cmd{\ForgetThis}\cmd{\Yamt} & \ForgetThis\Yamt & \texttt{\ShowPattern{Yamamoto,Isoroku}}\\
+% \rowcolor{black!7!white}\cmd{\RevName}\cmd{\LYamt} & \RevName\LYamt & \texttt{\ShowPattern{Yamamoto,Isoroku}}\\
+% \cmd{\ForgetThis}\cmd{\Name\{Henry,VIII\}} & \ForgetThis\Name{Henry,VIII} & \texttt{\ShowPattern{Henry,VIII}}\\
+% \cmd{\Name*\{Henry\}[VIII]} & \Name*{Henry}[VIII]\ddag & \texttt{\ShowPattern{Henry,VIII}}\\
+% \rowcolor{black!7!white}\cmd{\Dem[I Soter]} & \Dem[I Soter] & \texttt{\ShowPattern{Demetrius,I}}\\
+% \rowcolor{black!7!white}\cmd{\LDem} & \LDem & \texttt{\ShowPattern{Demetrius,I}}\\
+% \cmd{\ForgetThis}\cmd{\Aris} & \ForgetThis\Aris & \texttt{\ShowPattern{Aristotle}}\\
+% \cmd{\Aris} & \Aris & \texttt{\ShowPattern{Aristotle}}\\\bottomrule
+% \end{tabular}
+% \ForgetName{Demetrius, I}\ForgetName[Adolf]{Harnack}
+% \end{center}\bigskip
+%
+% \noindent Six suffixes are appended to these patterns to create independent data sets:
+% \begin{center}\small\MyStretch
+% \begin{tabular}{llll}\toprule
+% Description & Pattern & Mnemonic & Example\\\midrule
+% \rowcolor{black!7!white}Front-matter names & \meta{pattern}\texttt{!NF} & ``name front'' & \texttt{\ShowPattern[Adolf]{Harnack}{!NF}}\\
+% Main-matter names & \meta{pattern}\texttt{!MN} & ``main name'' & \texttt{\ShowPattern[Hideyo]{Noguchi}{!MN}}\\
+% \rowcolor{black!7!white}Index cross-refs & \meta{pattern}\texttt{!PN} & ``pseudonym'' & \texttt{\ShowPattern{Yamamoto, Isoroku}{!PN}}\\
+% Index sorting tags & \meta{pattern}\texttt{!PRE} & ``pretag'' & \texttt{\ShowPattern{Henry, VIII}{!PRE}}\\
+% \rowcolor{black!7!white}Index info tags & \meta{pattern}\texttt{!TAG} & ``tag'' & \texttt{\ShowPattern{Demetrius, I}{!TAG}}\\
+% ``Text tag'' database & \meta{pattern}\texttt{!DB} & ``database'' & \texttt{\ShowPattern{Aristotle}{!DB}}\\\bottomrule
+% \end{tabular}
+% \end{center}\bigskip
+%
+% \noindent The following macros \emph{write} to these data sets; others also can read from them:
+% \begin{center}\small\MyStretch
+% \begin{tabular}{lcccccc}\toprule[1pt]
+% Macros & \ttfamily \,!NF\, & \ttfamily \,!MN\, & \ttfamily \,!PN\, & \ttfamily !PRE & \ttfamily !TAG & \ttfamily \,!DB\,\\\midrule
+% \cmd{\Name} \cmd{\Name*} \cmd{\FName} & \YES & \YES & \NO & \NO & \NO & \NO\\
+% \cmd{\ForgetName} \cmd{\SubvertName} & \YES & \YES & \NO & \NO & \NO & \NO\\\midrule
+% \cmd{\PName}\cmd{\PName*} & \YES & \YES & \YES & \NO & \NO & \NO\\\midrule
+% \cmd{\AKA} \cmd{\AKA*} \cmd{\IndexRef} & \NO & \NO & \YES & \NO & \NO & \NO\\
+% \cmd{\ExcludeName} & \NO & \NO & \YES & \NO & \NO & \NO\\
+% \cmd{\IncludeName} \cmd{\IncludeName*} & \NO & \NO & \YES & \NO & \NO & \NO\\\midrule
+% \cmd{\PretagName} & \NO & \NO & \NO & \YES & \NO & \NO\\\midrule
+% \cmd{\TagName} \cmd{\UntagName} & \NO & \NO & \NO & \NO & \YES & \NO\\\midrule
+% \cmd{\NameAddInfo} \cmd{\NameClearInfo} & \NO & \NO & \NO & \NO & \NO & \YES\\\bottomrule
+% \end{tabular}
+% \end{center}\bigskip
+%
+% \ReturnLink
+% \newpage
+%
+% \subsection[Debug and Avoid Errors]{Debugging and Avoiding Errors}
+% \label{sec:ErrorProt}
%
-% \noindent{\large\strut\cmd{\Name} or Unmodified Shorthand}\\
-% {\small%
-%\begin{tabular}{lcccc}\toprule[1pt]
-% \bfseries First Reference & \bfseries Full & \bfseries Short & \parbox{3.1cm}{\footnotesize\ttfamily\textbackslash NamesFormat\\ \textbackslash FrontNamesFormat\smallskip} & \parbox{2.5cm}{\footnotesize\ttfamily\textbackslash MainNameHook\\ \textbackslash FrontNameHook\smallskip}\\
-% & \YES & \NO & \YES & \NO\\\midrule
-% \bfseries Subsequent Ref. & & & \S Cf. \cmd{\ForceName}\\
-% {}*Western Surname & \NO & \YES* & \NO* & \YES\\\midrule
-% {}*Eastern Surname & \NO & \YES* & \NO* & \YES\\\midrule
-% {}*Ancient Name & \NO & \YES* & \NO* & \YES\\\bottomrule[1pt]
-% \end{tabular}}\\\bigskip
+% \begin{center}\bfseries Debugging Macros\end{center}
%
-% \noindent{\large\strut\cmd{\Name*} or L-modifier + Shorthand}\\
-% {\small%
-% \begin{tabular}{lcccc}\toprule[1pt]
-% \hphantom{*Western Forename} & \bfseries Full & \bfseries Short & \parbox{3.1cm}{\footnotesize\ttfamily\textbackslash NamesFormat \textbackslash FrontNamesFormat\smallskip} & \parbox{2.5cm}{\footnotesize\ttfamily\textbackslash MainNameHook \textbackslash FrontNameHook\smallskip}\\
-% \bfseries First Reference & \YES & \NO & \YES & \NO\\\midrule
-% & & & \S Cf. \cmd{\ForceName}\\
-% \bfseries Subsequent Ref.& \YES & \NO & \NO* & \YES\\\bottomrule[1pt]
-% \end{tabular}}\\\bigskip
+% \DescribeMacro{\ShowPattern}
+% \cmd{\ShowPattern} displays how the name arguments create name patterns. One can debug pattern collisions and other issues with this macro:\Version{3.3}
+% \begin{quote}
+% \fbox{\mystrut\ \cmd{\ShowPattern}\oarg{FNN}\marg{SNN|,| Affix}\oarg{Alternate} }
+% \end{quote}
+% We used \cmd{\ShowPattern} in two of the tables on the previous page in order to illustrate name control patterns. We set the macro using a typewriter font, e.g.: |\texttt{\ShowPattern[Hernando]{de Soto}}|:\quad \texttt{\ShowPattern[Hernando]{de Soto}}\medskip
+%
+% \DescribeMacro{\ShowIdxPageref}
+% \cmd{\ShowIdxPageref} displays a full index entry in the text.
+% Its analogue is \cmd{\ShowIdxPageref*},
+% \DescribeMacro{\ShowIdxPageref*}
+% which shows a short index entry. Both only show names as page references, even if they are cross-references\Version{3.3}:
+% \begin{quote}
+% \fbox{\vbox{\hbox{\mystrut\ \cmd{\ShowIdxPageref\ }\oarg{FNN}\marg{SNN|,| Affix}\oarg{Alternate} }\par
+% \hbox{\mystrut\ \cmd{\ShowIdxPageref*}\oarg{FNN}\marg{SNN|,| Affix}\oarg{Alternate} }}}
+% \end{quote}
+% The full entry produced by \cmd{\ShowIdxPageref} can be affected by both index styles and tags produced by \cmd{\PretagName} and \cmd{\TagName}, e.g.:
+% \begin{quote}
+% |\texttt{\ShowIdxPageref[Hernando]{de Soto}}:|\\
+% \ShowIdxPageref[Hernando]{de Soto}
+% \end{quote}
+% \cmd{\ShowIdxPageref*} appears throughout this manual to illustrate basic index entries, e.g.: |\ShowIdxPageref*[Hernando]{de Soto}|:\quad \ShowIdxPageref*[Hernando]{de Soto}
+%
+% \begin{center}\bfseries Avoiding Common Errors\end{center}
%
-% \noindent{\large\strut\cmd{\FName} or S-modifier + Shorthand}\\
-% {\small%
-%\begin{tabular}{lcccc}\toprule[1pt]
-% \bfseries First Reference & \bfseries Full & \bfseries Short & \parbox{3.1cm}{\footnotesize\ttfamily\textbackslash NamesFormat \textbackslash FrontNamesFormat\smallskip} & \parbox{2.5cm}{\footnotesize\ttfamily\textbackslash MainNameHook \textbackslash FrontNameHook\smallskip}\\
-% & \YES & \NO & \YES & \NO\\\midrule
-% \bfseries Subsequent Ref. & & & \S Cf. \cmd{\ForceName}\\
-% {}*Western Forename & \NO & \YES* & \NO* & \YES\\\midrule
-% {}*Eastern Surname & \NO & \YES* & \NO* & \YES\\\midrule
-% {}*Ancient Name & \NO & \YES* & \NO* & \YES\\\bottomrule[1pt]
-% \end{tabular}}\\\bigskip
+% \begin{itemize}
+% \item Keep it simple! Avoid unneeded macros and use the simplified interface.
+% \item Compare index entries with names in the body text.
+% \item Check package warnings. Set the \texttt{verbose} option if needed.
+% \item Check arguments' braces and brackets to avoid errors like ``\texttt{Paragraph ended}'' and ``\texttt{Missing} \meta{grouping token} \texttt{inserted.}''
+% \item Do not format \meta{SNN},\meta{Affix} together as a pair. Format \meta{SNN} and \meta{Affix} separately (Section~\ref{sec:AltFormat}).
+% \item Sort names in the index with \cmd{\PretagName} (Section~\ref{sec:IndexSort}).
+% \item In package docs (\texttt{dtx} files) set up the \texttt{nameauth} environment and tags in the driver section to avoid errors.
+% \end{itemize}
+%
+% \begin{center}\bfseries Obsolete Syntax Caution\end{center}
%
-% \noindent{\large\strut\cmd{\ForceFN}\cmd{\FName} or \cmd{\ForceFN} S-modifier + Shorthand}\\
-% {\small%
-%\begin{tabular}{lcccc}\toprule[1pt]
-% \bfseries First Reference & \bfseries Full & \bfseries Short & \parbox{3.1cm}{\footnotesize\ttfamily\textbackslash NamesFormat \textbackslash FrontNamesFormat\smallskip} & \parbox{2.5cm}{\footnotesize\ttfamily\textbackslash MainNameHook \textbackslash FrontNameHook\smallskip}\\
-% & \YES & \NO & \YES & \NO\\\midrule
-% \bfseries Subsequent Ref. & & & \S Cf. \cmd{\ForceName}\\
-% {}*Western Forename & \NO & \YES* & \NO* & \YES\\\midrule
-% {}*Eastern Forename & \NO & \YES* & \NO* & \YES\\\midrule
-% {}*Ancient Affix & \NO & \YES* & \NO* & \YES\\\bottomrule[1pt]
-% \end{tabular}}\\\bigskip
-% \clearpage
+% \begin{itemize}
+% \item The older syntax has restrictions (Section~\ref{sec:Obsolete}). Only the new syntax permits variant names, e.g.: \cmd{\Name*\{Henry, VIII\}[Tudor]} \Name*{Henry, VIII}[Tudor]. The new syntax is preferred.
+% \item A proper form for the old syntax is \cmd{\Name*\{Henry\}[VIII]}: \Name*{Henry}[VIII].
+% \item \bgroup\IndexInactive\cmd{\Name[Henry]\{VIII\}} is a malformed Western name: ``\Name*[Henry]{VIII}'' and ``\Name[Henry]{VIII}.'' Likewise \cmd{\Name[Henry]\{VIII\}[Tudor]}: ``\Name*[Henry]{VIII}[Tudor]'' and ``\Name[Henry]{VIII}[Tudor].'' Both have the incorrect index entry ``\ShowIdxPageref*[Henry]{VIII}''.\egroup
+% \end{itemize}
%
-% \begin{center}\bfseries Selected Macro Patterns:\end{center}
+% \begin{center}\bfseries Standard Warnings\end{center}
%
-% \begin{center}\small\setstretch{1.05}
-% \begin{tabular}{lrccl}\toprule
-% \meta{prefix macros} & \cmd{\Name} & \meta{optional *} & \meta{arguments} \\
-% \meta{prefix macros} & \cmd{\FName} & \meta{optional *} & \meta{arguments} \\
-% \meta{prefix macros} & \cmd{\AKA} & \meta{optional *} & \meta{target args} & \meta{xref args}\\
-% \cmd{\SeeAlso} & \cmd{\IndexName} & & \meta{arguments} \\
-% \cmd{\SeeAlso} & \cmd{\IndexRef} & & \meta{arguments} & \meta{target}\\\midrule
-% & \cmd{\ExcludeName} & & \meta{arguments} \\
-% & \cmd{\IncludeName} & \meta{optional *} & \meta{arguments} \\
-% & \cmd{\PretagName} & & \meta{arguments} & \meta{sort key} \\
-% & \cmd{\TagName} & & \meta{arguments} & \meta{tag} \\
-% & \cmd{\UntagName} & & \meta{arguments} \\
-% & \cmd{\NameAddInfo} & & \meta{arguments} & \meta{tag} \\
-% & \cmd{\NameQueryInfo} & & \meta{arguments} \\
-% & \cmd{\NameClearInfo} & & \meta{arguments} & \\
-% & \cmd{\IfMainName} & & \meta{arguments} & \marg{y}\marg{n}\\
-% & \cmd{\IfFrontName} & & \meta{arguments} & \marg{y}\marg{n}\\
-% & \cmd{\IfAKA} & & \meta{arguments} & \marg{y}\marg{n}\\
-% & \cmd{\ForgetName} & & \meta{arguments} \\
-% & \cmd{\SubvertName} & & \meta{arguments} \\\bottomrule
+% \begin{itemize}
+% \item If one defines shorthand macros in the \texttt{nameauth} environment whose control sequence already exists, warnings always appear. For example:
+% \begin{quote}\small\StartNum
+% \begin{verbatim}
+%\PretagName[E.\,B.]{White}{White, E.B.}
+%\begin{nameauth}
+% \< White & E.B. & White & > % v.1
+% \< White & E.\,B. & White & > % v.2
+%\end{nameauth}\end{verbatim}
+% \end{quote}
+%\begin{nameauth}
+% \< White & E.B. & White & >
+% \< White & E.\,B. & White & >
+%\end{nameauth}
+% \item \cmd{\White} gives ``\White''. Its pattern is: \texttt{\ShowPattern[E.\,B.]{White}}. We lost the first version. We forget \White\ for later.\ForgetName[E.\,B.]{White} There should be two package warnings in this section for the redefinition of \cmd{\White}, because we defined it in the driver, then again here twice.
+% \item This could be a problem if a name shorthand replaces an actual macro that is used for something else and breaks that macro.
+% \item Then again, if one uses, e.g., a new \texttt{nameauth} environment per chapter, these warnings may be harmless. User discretion is advised.
+% \end{itemize}
+%
+% \begin{center}\bfseries Verbose Warnings\end{center}
+%
+% \noindent Package warnings result from the following \emph{only} when the \texttt{verbose} option is used because we do not want the default to be ``chatty'':
+% \begin{itemize}
+% \item Creating an index page reference after using a name as an xref or excluding it. Not allowed.
+% \item Creating the same cross-reference multiple times. Not allowed.
+% \item Using \cmd{\ExcludeName} on an xref. Not allowed.
+% \item Using\Version{3.3} \cmd{\IncludeName} on an xref. Not allowed.
+% \item Using \cmd{\ExcludeName} to exclude a name that exists is allowed, but a warning still results.
+% \item \cmd{\PretagName} sorts xrefs, but also creates ``informational warnings.''
+% \item Using \cmd{\TagName} and \cmd{\UntagName} on xrefs. No tag allowed.
+% \end{itemize}
+%
+% \begin{center}\bfseries Error Protection Strategies\end{center}
+%
+% \noindent The\Info{extra spaces} \textsf{nameauth} package trims extra spaces \emph{around} name arguments to prevent errors like multiple index entries that appear due to extra spaces. \LaTeX\ usually compacts internal spaces. For example, instead of being two different names, below we have the same name in a first, then subsequent use:
+%
+% \begin{center}\small\MyStretch\ForgetName[Martin Luther]{King, Jr.}
+% \begin{tabular}{ll}
+% \cmd{\Name*[Martin Luther]\{King,Jr.\}} & \Name*[Martin Luther]{King,Jr.}\\
+% \cmd{\Name*}\texttt{[\textvisiblespace\textvisiblespace Martin\textvisiblespace\textvisiblespace Luther\textvisiblespace\textvisiblespace]\{\textvisiblespace\textvisiblespace King\textvisiblespace\textvisiblespace,\textvisiblespace\textvisiblespace Jr.\textvisiblespace\textvisiblespace\}} & \Name*[ Martin Luther ]{ King , Jr. }\\
% \end{tabular}
% \end{center}
+%
+% This does not include explicit spaces from \cmd{\space}, etc. For example, the pattern \texttt{\ShowPattern[Martin Luther]{King, Jr.}} comes from \cmd{\Name[Martin Luther]\{King, Jr.\}} while \texttt{\ShowPattern[Martin~Luther]{King, Jr.}} comes from \cmd{\Name[Martin}|~|\texttt{Luther]\{King, Jr.\}}. The tilde appears as a non-breaking space in the text.
+% \newpage
+%
+% Full\Info{full stop\break detection} stops appear in one's initials and in affixes like ``Jr.'' (junior), ``Sr.'' (senior), ``d.\,J.'' (\textit{der Jüngere}), and ``d.\,Ä.'' (\textit{der Ältere}). The naming macros and some of the alternate name macros (Section~\ref{sec:AKA}) check if the printed name ends with a full stop and is followed by one. They gobble the extra full stop:
+% \begin{quote}\small\ForgetName[Martin Luther]{King, Jr.}
+% |This is Rev. Dr. \Name[Martin Luther]{King, Jr.}.|\\
+% This is Rev. Dr. \Name[Martin Luther]{King, Jr.}. \hfill Full stop is gobbled.\\[2ex]
+% |This is Rev. Dr. \Name[Martin Luther]{King, Jr.}.|\\
+% This is Rev. Dr. \Name[Martin Luther]{King, Jr.}. \hfill Full stop is not gobbled.\\[2ex]
+% |Again we speak fully of \Name*[Martin Luther]{King, Jr.}.|\\
+% Again we speak fully of \Name*[Martin Luther]{King, Jr.}. \hfill Full stop is gobbled.\\[2ex]
+% |We drop the affix: \DropAffix\Name*[Martin Luther]{King, Jr.}.|\\
+% We drop the affix: \DropAffix\Name*[Martin Luther]{King, Jr.}. \hfill Full stop is not gobbled.\\[2ex]
+% |His initials are \FName[Martin Luther]{King, Jr.}[M.L.].|\\
+% His initials are \FName[Martin Luther]{King, Jr.}[M.L.]. \hfill Full stop is gobbled.
+% \end{quote}
%
-% \begin{center}\bfseries Prefix Macros (One-Time Effect):\end{center}
-% \hfil They stack: \cmd{\CapThis}\cmd{\SubvertThis}\cmd{\SkipIndex}\cmd{\Name[foo]\{bar\}}: \CapThis\SubvertThis\SkipIndex\Name[foo]{bar}
-% \begin{center}\small\setstretch{1.05}
-% \begin{tabular}{rp{0.72\textwidth}}\toprule
-% \cmd{\CapThis} & Capitalize first letter of all name components in body text.\footnotemark[3]\\
-% \cmd{\CapName} & Cap entire \meta{SNN} in body text. Works also with \cmd{\CapThis}.\\\midrule
-% \cmd{\RevName} & Reverse name order in body text (e.g., for Eastern names).\\\midrule
-% \cmd{\RevComma} & Reverse Western names to \meta{SNN}, \meta{FNN}.\footnotemark[4]\\
-% \cmd{\ShowComma} & Add comma between \meta{SNN} and \meta{Affix}.\\
-% \cmd{\NoComma} & No comma between \meta{SNN} and \meta{Affix}. Excludes \cmd{\ShowComma}.\\\midrule
-% \cmd{\ForceFN} & \texttt{Force} Eastern \texttt{F}ore\texttt{N}ame or ancient \texttt{F}i\texttt{N}al affix.\footnotemark[5]\\
-% \cmd{\DropAffix} & Drop name affix of Western name (in long name reference).\footnotemark[6]\\
-% \cmd{\KeepAffix} & Insert non-breaking space between \meta{SNN} and \meta{Affix}.\footnotemark[7]\\
-% \cmd{\KeepName} & Insert non-breaking space between all syntactic name elements.\\\midrule
-% \cmd{\ForceName} & Have a subsequent name use call first-use formatting hooks.\\\midrule
-% \cmd{\ForgetThis} & Next naming macro prints a first use. Excludes \cmd{\SubvertThis}.\\
-% \cmd{\SubvertThis} & The next naming macro prints a subsequent use.\\\midrule
-% \cmd{\SeeAlso} & The next cross-reference macro creates a \emph{see also} reference.\footnotemark[8]\\
-% \cmd{\SkipIndex} & The next naming macro does not create index entries.\\
-% \cmd{\JustIndex} & The next \cmd{\Name} or \cmd{\FName} acts just like a call to \cmd{\IndexName}. Ignored and reset by \cmd{\AKA} and \cmd{\PName}.\\\bottomrule
+% Take\Info{grouping\break issues} care when using braces and spaces with a name at the end of a sentence. Braces can change name arguments, even though they look the same. We disable indexing for the three points below:\IndexInactive
+% \begin{itemize}\small
+% \item If one encapsulates a name in braces, the punctuation detection fails:\\
+% |This is Rev. Dr. {\Name*[Martin Luther]{King, Jr.}}.|\\
+% This is Rev. Dr. {\Name*[Martin Luther]{King, Jr.}}. \hfill Full stop is not gobbled.
+% \item[] A solution encapsulates both the name and the full stop:\\
+% |This is Rev. Dr. {\Name*[Martin Luther]{King, Jr.}.}|\\
+% This is Rev. Dr. {\Name*[Martin Luther]{King, Jr.}.} \hfill Full stop is gobbled.
+% \item If one encapsulates \meta{Affix} in braces, the punctuation detection fails:\\
+% |This is Rev. Dr. \Name*[Martin Luther]{King, {Jr.}}.|\\
+% This is Rev. Dr. \Name*[Martin Luther]{King, {Jr.}}. \hfill Full stop is not gobbled.
+% \item[] The solution leaves the full stop in \meta{Affix} outside the braces:\\
+% |This is Rev. Dr. \Name*[Martin Luther]{King, {Jr}.}.|\\
+% This is Rev. Dr. \Name*[Martin Luther]{King, {Jr}.}. \hfill Full stop is gobbled.
+% \item[] The name patterns, however, are different, creating different names:\\
+% \texttt{\ShowPattern[Martin Luther]{King, {Jr.}}}\\
+% \texttt{\ShowPattern[Martin Luther]{King, {Jr}.}}
+% \item If one leaves an extra space after a name, the punctuation detection fails:\\
+% |This is Rev. Dr. \Name*[Martin Luther]{King, Jr.}|\texttt{\textvisiblespace.}\\
+% This is Rev. Dr. \Name*[Martin Luther]{King, Jr.} . \hfill Full stop is not gobbled.
+% \item[] The solution removes the extra space:\\
+% |This is Rev. Dr. \Name*[Martin Luther]{King, Jr.}.|\\
+% This is Rev. Dr. \Name*[Martin Luther]{King, Jr.}. \hfill Full stop is gobbled.
+% \end{itemize}\IndexActive
+%
+% Variations\Info{active chars\break and macros} in the use of active characters and control sequences also change name arguments and index sorting (Section~\ref{sec:IndexSort}; cf.~\ref{sec:Unicode} and~\ref{sec:TeXengines}):
+% \begin{itemize}\small
+% \item |\Name*{Æthelred, II}| \Name*{Æthelred, II};\hfill Pattern: \texttt{\ShowPattern{Æthelred, II}}\footnote{With \texttt{pdflatex} / \texttt{latex}, the glyphs \texttt{ÃĘ} correspond to \cmd{\IeC\{\textbackslash AE\}}.}\newline We have seen this name earlier.
+% \item |\SkipIndex\Name{\AE thelred, II}| \SkipIndex\Name{\AE thelred, II};\hfill Pattern: \texttt{\ShowPattern{\AE thelred, II}}\newline This is a new name that looks the same.\newpage
+% \item |\Name{Bo\"ethius}| \Name{Bo\"ethius};\hfill Pattern: \texttt{\ShowPattern{Bo\"ethius}}\newline We introduce this new name.
+% \item |\SkipIndex\Name{Boëthius}| \SkipIndex\Name{Boëthius} \hfill Pattern: \texttt{\ShowPattern{Boëthius}}\footnote{With \texttt{pdflatex} / \texttt{latex}, the glyphs \texttt{Ãń} correspond to \cmd{\IeC\{\textbackslash"e\}}.}\newline This is a different name that looks the same.
+% \item |\SkipIndex\Name{Bo{\"e}thius}| \SkipIndex\Name{Bo{\"e}thius};\hfill Pattern: \texttt{\ShowPattern{Bo{\"e}thius}}\newline This also is a different name that looks the same.
+% \end{itemize}
+%
+% Omit\Info{formatting\break initials} spaces between initials; see Bringhurst, \textit{Elements of Typographic Style}. If a style guide requires spaces, try thin spaces. Use \cmd{\PretagName} to sort those names (Section~\ref{sec:IndexSort}). Below we use no formatting:\bigskip
+%
+% \leavevmode\quad\begin{minipage}[c]{0.45\textwidth}\small
+% \StartNum
+% \begin{verbatim}
+%\PretagName[E.\,B.]{White}%
+% {White, E.B.}
+%\begin{nameauth}
+% \< White & E.\,B. & White & >
+%\end{nameauth}\end{verbatim}
+% \end{minipage}
+% \begin{minipage}[c]{0.35\textwidth}\normalsize\renewcommand*\NamesFormat{}
+% \def\sep{\vrule width0.5pt\kern-0.5pt}%
+% \begin{tabular}{@{}ll@{}}\hline
+% & \sep\hphantom{E.}\sep\,\sep\hphantom{B.}\sep\hphantom{\ }\sep\hphantom{White}\\
+% \cmd{\White} & \hspace{0.48pt}\White\\
+% & \sep\hphantom{E.}\sep\,\sep\hphantom{B.}\sep\hphantom{\ }\sep\hphantom{White}\\\hline
+% & \sep\hphantom{E.}\sep\ \sep\hphantom{B.}\sep\ \sep\hphantom{White}\\
+% Normal text:\hfill & E. B. White\\
+% & \sep\hphantom{E.}\sep\ \sep\hphantom{B.}\sep\ \sep\hphantom{White}\\\hline
% \end{tabular}
-% \end{center}
-% \footnotetext[3]{\cmd{\AccentCapThis} is a fall-back for when the \textsf{nameauth} package is used where system architecture or file encoding might cause errors with the automatic Unicode detection under NFSS.}
-% \footnotetext[4]{Has no effect on non-Western name forms.}
-% \footnotetext[5]{Only affects non-Western name forms.}
-% \footnotetext[6]{Only affects Western name forms.}
-% \footnotetext[7]{Used best with Western and ancient name forms.}
-% \footnotetext[8]{Works only with \cmd{\IndexRef}, \cmd{\AKA}, \cmd{\PName} and their respective starred variants.}
-% \addtocounter{footnote}{6}
-% \clearpage
+% \end{minipage}\bigskip
%
+% English\Info{hyphenation} contains names from many cultures. The rules for hyphenation go to the heart of how names with non-English origins should be pronounced. With \textsf{nameauth}, one can use either optional hyphens or the \textsf{babel}\,/\,\textsf{polyglossia} packages to handle such names:
+% \NameAddInfo[John]{\de{Strietelmeier}}{late professor at Valparaiso University}
+% \begin{quote}\small
+% \StartNum
+% \begin{verbatim}
+%\newcommand\de[1]{\foreignlanguage{ngerman}{#1}}
+% % or polyglossia: \newcommand\de[1]{\textgerman{#1}}
+%\NameAddInfo[John]{\de{Strietelmeier}}%
+% {late professor at Valparaiso University}
+%\begin{nameauth}
+% \< Striet & John & \de{Strietelmeier} & >
+%\end{nameauth}
+%\PretagName[John]{\de{Strietelmeier}}{Strietelmeier, John}\end{verbatim}
+% \end{quote}
+%
+% \noindent \emph{Not fixed:}\\
+% \noindent In English, some names come from other cultures. These names, like \SkipIndex\Name[John]{Strietelmeier} \cmd{\SkipIndex}\cmd{\Name[John]\{Strietelmeier\}} can break badly.\smallskip
+%
+% \noindent \emph{Fixed with discretionary hyphens:}\\
+% \noindent In English, some names come from other cultures. These names, like \SkipIndex\Name[John]{Strie\-tel\-meier}, \cmd{\SkipIndex}\cmd{\Name[John]\{Strie\textbackslash-tel\textbackslash-meier\}} could break badly.\smallskip
+%
+% \noindent \emph{Fixed with language packages:}\\
+% \noindent In English, some names come from other cultures. These names, like \Striet, \cmd{\Striet} could break badly.\medskip
+%
+% \Striet\ (\NameQueryInfo[John]{\de{Strietelmeier}}) is neither pronounced nor hyphenated as ``Stri-etel-meier''; rather, it is pronounced and hyphenated as ``Strie-tel-meier''. See Sections~\ref{sec:NameParticles} and~\ref{sec:AltFormat} when using macros in name arguments.
+% Using \textsf{babel} or \textsf{polyglossia} likely is best.
+%
+% \ReturnLink
+% \newpage
+%
% \section{Detailed Usage}
+%
% \subsection{Package Options}
-% \label{sec:options}
+% \label{sec:PkgOptions}
%
% One includes the \textsf{nameauth} package thus:
-% \begin{quote}\small
-% |\usepackage[|\meta{$option_1$}|,|\meta{$option_2$}|,|\dots|]{nameauth}|
+% \begin{quote}
+% \fbox{\mystrut\ \cmd{\usepackage[}\meta{\(option_1\)}\texttt{,}\meta{\(option_2\)}\texttt{,}\dots\texttt{,}\meta{\(option_n\)}\texttt{]\{nameauth\} }}
% \end{quote}
% The options have no required order. Still, we discuss them from the general to the specific, as the headings below indicate. In the listings below, {\bfseries implicit default options are boldface and need not be invoked by the user.} {\color{nared}Non-default options are in red and must be invoked explicitly.}
%
-% \begin{center}\large\bfseries Choosing Features\end{center}
+% \begin{center}\bfseries Choosing Features\end{center}
%
-% \noindent{\bfseries Enable Package Warnings}\\[1ex]
-% {\begin{tabular}{p{0.22\textwidth}p{0.6\textwidth}}
-% \leavevmode\color{nared}\quad\texttt{verbose} & \leavevmode\color{nared}Show warnings about index cross-references.\\
-% \end{tabular}}\\[1ex]
-% The default\marginpar{\large\raggedleft\textsf{\bfseries 3.0}\strut} suppresses package warnings from the indexing macros. Warnings from the \texttt{nameauth} environment are not suppressed.\bigskip
+% \noindent{\bfseries Enable Package Warnings}\medskip\\
+% \bgroup\begin{tabular}{p{0.22\textwidth}p{0.6\textwidth}}
+% \leavevmode\color{nared}\quad\texttt{verbose} & \leavevmode\color{nared}Show warnings about index cross-references.\medskip\\
+% \end{tabular}\egroup
+%
+% \noindent The default\Version{3.0} suppresses package warnings from the indexing macros. Warnings from the \texttt{nameauth} environment are not suppressed.\bigskip
%
-% \noindent{\bfseries Choose Formatting}\\[1ex]
-% {\begin{tabular}{p{0.22\textwidth}p{0.6\textwidth}}
-% \bfseries\quad\texttt{mainmatter} & \bfseries Start with ``main-matter names'' and formatting hooks (see also page~\pageref{page:PostProcess}).\\[0.5ex]
-% \leavevmode\color{nared}\quad\texttt{frontmatter} & \leavevmode\color{nared}Start with ``front-matter names'' and hooks.\\[0.5ex]
-% \leavevmode\color{nared}\quad\texttt{alwaysformat} & \leavevmode\color{nared}Use only respective ``first use'' formatting hooks.\\[0.5ex]
-% \leavevmode\color{nared}\quad\texttt{formatAKA} & \leavevmode\color{nared}Format the first use of a name with \cmd{\AKA} like the first use of a name with \cmd{\Name}.\\[0.5ex]
-% \leavevmode\color{nared}\quad\texttt{oldAKA} & \leavevmode\color{nared}Force \cmd{\AKA*} to act like it did before v.3.0.\\
-% \end{tabular}}\\[1ex]
-% The \texttt{mainmatter} option and the \texttt{frontmatter} option enable two different systems of name use and formatting. They are mutually exclusive. \cmd{\NamesActive} starts the main matter system when \texttt{frontmatter} is used. See Section~\ref{sec:formatting}.
+% \noindent{\bfseries Choose Formatting}\medskip\\
+% \bgroup\begin{tabular}{p{0.22\textwidth}p{0.6\textwidth}}
+% \bfseries\quad\texttt{mainmatter} & \bfseries Start with ``main-matter names'' and formatting hooks (see also page~\pageref{page:PostProcess}).\smallskip\\
+% \leavevmode\color{nared}\quad\texttt{frontmatter} & \leavevmode\color{nared}Start with ``front-matter names'' and hooks.\smallskip\\
+% \leavevmode\color{nared}\quad\texttt{alwaysformat} & \leavevmode\color{nared}Use only respective ``first use'' formatting hooks.\smallskip\\
+% \leavevmode\color{nared}\quad\texttt{formatAKA} & \leavevmode\color{nared}Format the first use of a name with \cmd{\AKA} like the first use of a name with \cmd{\Name}.\smallskip\\
+% \leavevmode\color{nared}\quad\texttt{oldAKA} & \leavevmode\color{nared}Force \cmd{\AKA*} to act like it did before version 3.0.\smallskip\\
+% \leavevmode\color{nared}\quad\texttt{oldreset} & \leavevmode\color{nared}Reset per-use name flags locally within the naming macros, as before version 3.3.\smallskip\\
+% \leavevmode\color{nared}\quad\texttt{oldpass} & \leavevmode\color{nared}When \cmd{\Justindex} is called, allow long\,/\,short flags to pass through, as before version 3.3.\medskip\\
+% \end{tabular}\egroup
+%
+% \noindent The \texttt{mainmatter} option and the \texttt{frontmatter} option enable two different systems of name use and formatting. They are mutually exclusive. \cmd{\NamesActive} starts the main matter system when \texttt{frontmatter} is used. See Section~\ref{sec:Formatting}.
%
% The \texttt{alwaysformat} option forces ``first use'' hooks globally in both naming systems. Its use is limited in current versions of \textsf{nameauth}.
%
-% The\marginpar{\large\raggedleft\textsf{\bfseries 3.1}\strut} \texttt{formatAKA} option permits \cmd{\AKA} to use the ``first use'' formatting hooks. This enables \cmd{\ForceName} to trigger those hooks at will (Section~\ref{sec:AKA}). Otherwise \cmd{\AKA} uses ``subsequent use'' hooks.
+% The\Version{3.1} \texttt{formatAKA} option permits \cmd{\AKA} to use the ``first use'' formatting hooks. This enables \cmd{\ForceName} to trigger those hooks at will (Section~\ref{sec:AKA}). Otherwise \cmd{\AKA} uses ``subsequent use'' hooks.
%
-% Using the\marginpar{\large\raggedleft\textsf{\bfseries 3.0}\strut} \texttt{oldAKA} option forces \cmd{\AKA*} always to print a ``forename'' field in the text, as it did in versions 2.6 and older. Otherwise the current behavior of \cmd{\AKA*} prints in the same fashion as \cmd{\FName} (see Sections~\ref{sec:Fname} and~\ref{sec:AKA}).\bigskip
+% Using the\Version{3.0} \texttt{oldAKA} option forces \cmd{\AKA*} always to print a ``forename'' argument in the text, as in versions before 3.0. Otherwise the current behavior of \cmd{\AKA*} prints in the same fashion as \cmd{\FName} (see Sections~\ref{sec:FName} and~\ref{sec:AKA}).
%
-% \noindent{\bfseries Enable/Disable Indexing}\\[1ex]
-% {\begin{tabular}{p{0.22\textwidth}p{0.6\textwidth}}
-% \quad\bfseries\texttt{index} & \bfseries Create index entries in place with names.\\[0.5ex]
-% \leavevmode\color{nared}\quad\texttt{noindex} & \leavevmode\color{nared}Suppress indexing of names.\\
-% \end{tabular}}\\[1ex]
-% These apply only to the \textsf{nameauth} package macros. The default \texttt{index} option enables name indexing right away. The \texttt{noindex} option disables the indexing of names until \cmd{\IndexActive} enables it. \textbf{Caution:}\marginpar{\small\raggedleft\dbend} using \texttt{noindex} and \cmd{\IndexInactive} prevents index tags until you call \cmd{\IndexActive}, as explained also in Section~\ref{sec:indexctrl}.
-% \clearpage
+% Used together,\Version{3.3} the next two options restore pre-version 3.3 handling of flags that could lead to undocumented behavior. The \texttt{oldreset} option causes all Boolean flags related to the prefix macros and long\,/\,short name forms to be reset locally. The new default is to reset them globally (Section~\ref{sec:Customize}). Likewise, the \texttt{oldpass} option allows the long\,/\,short flags to pass through \cmd{\JustIndex} instead of being reset (Section~\ref{sec:IndexControl}).
+% \newpage
%
-% \noindent{\bfseries Enable/Disable Index Sorting}\\[1ex]
-% {\begin{tabular}{p{0.22\textwidth}p{0.6\textwidth}}
-% \quad\bfseries\texttt{pretag} & \bfseries Create sort keys used with \texttt{makeindex}.\\[0.5ex]
-% \leavevmode\color{nared}\quad\texttt{nopretag} & \leavevmode\color{nared}Do not create sort keys. \\
-% \end{tabular}}\\[1ex]
-% The default allows \cmd{\PretagName} to create sort keys used with NFSS or \texttt{makeindex} and its analogues. The \texttt{nopretag} option disables the sorting mechanism, e.g., if a different sorting method is used with \texttt{xindy}. See Section~\ref{sec:IndexSort}.
+% \noindent{\bfseries Enable\,/\,Disable Indexing}\medskip\\
+% \bgroup\begin{tabular}{p{0.22\textwidth}p{0.6\textwidth}}
+% \quad\bfseries\texttt{index} & \bfseries Create index entries in place with names.\smallskip\\
+% \leavevmode\color{nared}\quad\texttt{noindex} & \leavevmode\color{nared}Suppress indexing of names.\medskip\\
+% \end{tabular}\egroup
+%
+% \noindent These options and related macros do not affect the normal use of \cmd{\index}. They apply only to the \textsf{nameauth} package macros. The default \texttt{index} option enables name indexing right away. The \texttt{noindex} option disables the indexing of names until \cmd{\IndexActive} enables it. \emph{Caution:}\Warn{} using \texttt{noindex} and \cmd{\IndexInactive} prevents index tags until you call \cmd{\IndexActive}, as explained also in Section~\ref{sec:IndexControl}.\bigskip
%
-% \begin{center}\large\bfseries Affect the Syntax of Names\end{center}
-% {\bfseries Show/Hide Affix Commas}\\[2ex]
-% {\begin{tabular}{p{0.22\textwidth}p{0.6\textwidth}}
-% \quad\bfseries\texttt{nocomma} & \bfseries Suppress commas between surnames and affixes, following the \emph{Chicago Manual of Style} and other conventions.\\[0.5ex]
-% \leavevmode\color{nared}\quad\texttt{comma} & \leavevmode\color{nared}Retain commas between surnames and affixes.\\
-% \end{tabular}}\\[1ex]
-% If you use \emph{modern standards}, choose the default \texttt{nocomma} option to get, \emph{e.g.}, \Name[J.E.]{Carter, Jr.}[James Earl]. If you need to adopt \emph{older standards} that use commas between surnames and affixes, you have two choices:
+% \noindent{\bfseries Enable\,/\,Disable Index Sorting}\medskip\\
+% \bgroup\begin{tabular}{p{0.22\textwidth}p{0.6\textwidth}}
+% \quad\bfseries\texttt{pretag} & \bfseries Create sort keys used with \texttt{makeindex}.\smallskip\\
+% \leavevmode\color{nared}\quad\texttt{nopretag} & \leavevmode\color{nared}Do not create sort keys.\medskip\\
+% \end{tabular}\egroup
+%
+% \noindent The default allows \cmd{\PretagName} to create sort keys used with \texttt{makeindex}. The \texttt{nopretag} option disables the sorting mechanism, e.g., if a different sorting method is used with \texttt{xindy}. See Section~\ref{sec:IndexSort}.
+%
+% \begin{center}\bfseries Affect the Syntax of Names\end{center}
+%
+% \noindent{\bfseries Show\,/\,Hide Affix Commas}\medskip\\
+% \bgroup\begin{tabular}{p{0.22\textwidth}p{0.6\textwidth}}
+% \quad\bfseries\texttt{nocomma} & \bfseries Suppress commas between surnames and affixes, following the \textit{Chicago Manual of Style} and other conventions.\smallskip\\
+% \leavevmode\color{nared}\quad\texttt{comma} & \leavevmode\color{nared}Retain commas between surnames and affixes.\medskip\\
+% \end{tabular}\egroup
+%
+% \noindent If you use \emph{modern standards}, choose the default \texttt{nocomma} option to get, e.g., \Name[J.E.]{Carter, Jr.}[James Earl]. If you need to adopt \emph{older standards} that use commas between surnames and affixes, you have two choices:
% \begin{enumerate}
-% \item The \texttt{comma} option globally produces, \emph{e.g.}, \ShowComma\Name*[J.E.]{Carter, Jr.}[James Earl].
+% \item The \texttt{comma} option globally produces, e.g., \ShowComma\Name*[J.E.]{Carter, Jr.}[James Earl].
% \item Section~\ref{sec:Affix} shows how one can use \cmd{\ShowComma} with the \texttt{nocomma} option and \cmd{\NoComma} with the \texttt{comma} option to get per-name results.
-% \end{enumerate}\medskip
+% \end{enumerate}
+% In both cases, the display of commas (or the lack thereof) does not affect the appearance or the sorting of index entries.\bigskip
%
-% \noindent{\bfseries Capitalize Entire Surnames}\\[2ex]
-% {\begin{tabular}{p{0.22\textwidth}p{0.6\textwidth}}
-% \quad\bfseries\texttt{normalcaps} & \bfseries Do not perform any special capitalization.\\[0.5ex]
-% \leavevmode\color{nared}\quad\texttt{allcaps} & \leavevmode\color{nared}Capitalize entire surnames, such as romanized Eastern names.\\
-% \end{tabular}}\\[1ex]
-% This only capitalizes names printed in the body text. English standards usually do not propagate typographic changes into the index.
+% \noindent{\bfseries Capitalize Entire Surnames}\medskip\\
+% \bgroup\begin{tabular}{p{0.22\textwidth}p{0.6\textwidth}}
+% \quad\bfseries\texttt{normalcaps} & \bfseries Do not perform any special capitalization.\smallskip\\
+% \leavevmode\color{nared}\quad\texttt{allcaps} & \leavevmode\color{nared}Capitalize entire surnames, e.g., romanized Eastern names.\medskip\\
+% \end{tabular}\egroup
+%
+% \noindent This only capitalizes names printed in the body text. English standards usually do not propagate typographic changes into the index.
%
-% Still,\marginpar{\small\raggedleft\dbend} you can use this package with non-English conventions (just not via these options). You can add, \emph{e.g.}, uppercase or small caps in surnames, formatting them also in the index. See also Sections~\ref{sec:altformat} and~\ref{sec:Hooksc}. The simplified interface aids the embedding of control sequences in names. Section~\ref{sec:Eastern} deals with capitalization on a section-level and per-name basis.\bigskip
+% Still, you can use this package with non-English conventions (just not via these options). You can add, e.g., uppercase or small caps in surnames, formatting them also in the index. See also Sections~\ref{sec:AltFormat} and~\ref{sec:Hooksiii}. The simplified interface aids the embedding of control sequences in names. Section~\ref{sec:Eastern} deals with capitalization on a section-level and per-name basis.
+% \newpage
%
-% \noindent{\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.\\[0.5ex]
-% \leavevmode\color{nared}\quad\texttt{allreversed} & \leavevmode\color{nared}Print all name forms in ``smart'' reverse order.\\[0.5ex]
-% \leavevmode\color{nared}\quad\texttt{allrevcomma} & \leavevmode\color{nared}Print all names in ``Surname, Forenames'' order, meant for Western names.\\
-% \end{tabular}}\\[1ex]
-% These three options are mutually exclusive. Section~\ref{sec:Eastern} speaks more about reversing. The \texttt{allreversed} option, \cmd{\ReverseActive}, and \cmd{\RevName} work with all names and override \texttt{allrevcomma} and its macros.
+% \noindent{\bfseries Reverse Name Order}\medskip\\
+% \bgroup\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.\smallskip\\
+% \leavevmode\color{nared}\quad\texttt{allreversed} & \leavevmode\color{nared}Print all name forms in ``smart'' reverse order.\smallskip\\
+% \leavevmode\color{nared}\quad\texttt{allrevcomma} & \leavevmode\color{nared}Print all names in ``Surname, Forenames'' order, meant for Western names.\medskip\\
+% \end{tabular}\egroup
+%
+% \noindent These three options are mutually exclusive. Section~\ref{sec:Eastern} speaks more about reversing. The \texttt{allreversed} option, \cmd{\ReverseActive}, and \cmd{\RevName} work with all names and override \texttt{allrevcomma} and its macros.
%
% So-called ``last-comma-first'' lists of names via \texttt{allrevcomma} and the reversing macros \cmd{\ReverseCommaActive} and \cmd{\RevComma} (Section~\ref{sec:LastFirst}) are \emph{not} the same as the \texttt{comma} option. They only affect Western names.
-% \clearpage
%
-% \phantomsection\label{page:PostProcess}
-% \begin{center}\large\bfseries Typographic Post-Processing\end{center}
-% \noindent{\bfseries Formatting Attributes}\\[2ex]
-% {\begin{tabular}{p{0.22\textwidth}p{0.6\textwidth}}
-% \quad\bfseries\texttt{noformat} & \bfseries Do not define a default format.\\[0.5ex]
-% \leavevmode\color{nared}\quad\texttt{smallcaps} & \leavevmode\color{nared}First use of a main-matter name in small caps.\\[0.5ex]
-% \leavevmode\color{nared}\quad\texttt{italic} & \leavevmode\color{nared}First use of a main-matter name in italic.\\[0.5ex]
-% \leavevmode\color{nared}\quad\texttt{boldface} & \leavevmode\color{nared}First use of a main-matter name in boldface.\\
-% \end{tabular}}\\
+% \phantomsection
+% \label{page:PostProcess}
%
-% Current\marginpar{\large\raggedleft\textsf{\bfseries 2.5}\strut} versions assign no default formatting to names. Most users have preferred the \texttt{noformat} option as the default and then design their own hooks as needed.\footnote{For those that want the old default option from the early days of this package, one can recover that behavior with the \texttt{smallcaps} option.}
+% \begin{center}\bfseries Typographic Post-Processing\end{center}
+%
+% \noindent{\bfseries Formatting Attributes}\medskip\\
+% \bgroup\begin{tabular}{p{0.22\textwidth}p{0.6\textwidth}}
+% \quad\bfseries\texttt{noformat} & \bfseries Do not define a default format.\smallskip\\
+% \leavevmode\color{nared}\quad\texttt{smallcaps} & \leavevmode\color{nared}First use of a main-matter name in small caps.\smallskip\\
+% \leavevmode\color{nared}\quad\texttt{italic} & \leavevmode\color{nared}First use of a main-matter name in italic.\smallskip\\
+% \leavevmode\color{nared}\quad\texttt{boldface} & \leavevmode\color{nared}First use of a main-matter name in boldface.\medskip\\
+% \end{tabular}\egroup
+%
+% \noindent Current\Version{2.5} versions assign no default formatting to names. Most users have preferred the \texttt{noformat} option as the default and then design their own hooks as needed.\footnote{For those that want the old default option from the early days of this package, one can recover that behavior with the \texttt{smallcaps} option.}
% The options above are ``quick'' solutions based on English typography.
%
-% What\marginpar{\large\raggedleft\textsf{\bfseries 2.4}\strut} was ``typographic formatting'' has become a generalized concept of ``post-processing'' via hook macros.\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. 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.}
-% Post-processing does not affect the index. Sections \ref{sec:formatting}, \ref{sec:Hooksa}, \ref{sec:Hooksb}, and~\ref{sec:Hooksc} explain these hooks in greater detail:
+% What\Version{2.4} was ``typographic formatting'' has become a generalized concept of ``post-processing'' via hook macros.\footnote{This package was designed with type hierarchies and flexibility in mind. See Robert Bringhurst, \textit{The Elements of Typographic Style}, version 3.2 (Point Roberts, Washington: Hartley \& Marks, 2008), 53--60. Typographic inspiration comes from Bernhard Lohse, \textit{Luthers Theologie} (G\"ottingen: Vandenhoeck \& Ruprecht, 1995) and Jaroslav J. Pelikan Jr., \textit{The Christian Tradition: A History of the Development of Doctrine}, 5 vols. (Chicago: Chicago UP, 1971--89).}
+% Post-processing does not affect the index. Sections \ref{sec:Formatting}, \ref{sec:Hooksi}, \ref{sec:Hooksii}, and~\ref{sec:Hooksiii} explain these hooks in greater detail:
% \begin{itemize}
% \item \cmd{\NamesFormat} formats first uses of main-matter names.
% \item \cmd{\MainNameHook} formats subsequent uses of main-matter names.
@@ -1265,55 +1707,95 @@
% \item \cmd{\FrontNameHook} formats subsequent uses of front-matter names.
% \end{itemize}
%
-% Changes\marginpar{\small\raggedleft\cmd{\global}} to the formatting hooks apply within the scope where they are made. Use \cmd{\global} explicitly to alter that. \cmd{\NamesFormat} originally was the only hook, so any oddity in the naming of these hooks results from the need for backward compatibility with old versions.
+% Changes\Info{\cmd{\global}} to the formatting hooks apply within the scope where they are made. Use \cmd{\global} explicitly to alter that. \cmd{\NamesFormat} originally was the only hook, so any oddity in the naming of these hooks results from the need for backward compatibility with old versions.
%
-% \begin{center}\large\bfseries Alternate or Continental Formatting\end{center}
-% \noindent{\bfseries Alternate Syntactic Formatting}\\[2ex]
-% {\begin{tabular}{p{0.22\textwidth}p{0.6\textwidth}}
-% \leavevmode\color{nared}\quad\texttt{altformat} & \leavevmode\color{nared}Make available the alternate formatting framework from the start of the document. Activate formatting by default.\\
-% \end{tabular}}\\
+% Section~\ref{sec:AKA} discusses how \cmd{\AKA} does not respect these formatting systems and uses the hooks differently. To avoid using the \texttt{formatAKA} option and \cmd{\ForceName} with \cmd{\AKA}, Section~\ref{sec:IndexXref} shows how to use \cmd{\IndexRef} and \cmd{\Name} instead.
+% \newpage
%
-% A built-in\marginpar{\large\raggedleft\textsf{\bfseries 3.1}\strut\break\small\dbend} framework provides an alternate formatting mechanism that can be used for ``Continental'' formatting that one sees in German, French, and so on. Continental standards format surnames only, both in the text and in the index. Section~\ref{sec:altformat} introduces the topic, while Section~\ref{sec:Hooksc} goes into greater detail. The previous methods the produced Continental formatting still ought to work. The error protection that prevents \cmd{\CapThis} from breaking alternately formatted names is available by using this option or other macros in Section~\ref{sec:altformat}.
-% \clearpage
+% \begin{center}\bfseries Alternate or Continental Formatting\end{center}
%
+% \noindent{\bfseries Alternate Formatting}\medskip\\
+% \bgroup\begin{tabular}{p{0.22\textwidth}p{0.6\textwidth}}
+% \leavevmode\color{nared}\quad\texttt{altformat} & \leavevmode\color{nared}Make available the alternate formatting framework from the start of the document. Activate formatting by default.\medskip\\
+% \end{tabular}\egroup
+%
+% \noindent A built-in\Version{3.1} framework provides an alternate formatting mechanism that can be used for ``Continental'' formatting that one sees in German, French, and so on. Continental standards often format surnames only, both in the text and in the index. Section~\ref{sec:AltFormat} introduces the topic and should be sufficient for most users, while Section~\ref{sec:Hooksiii} goes into greater detail.
+%
+% The previous methods that produced Continental formatting were rather complex compared to the current, simplified manner of doing so. Yet it is likely that these older solutions still ought to work. The error protection that prevents \cmd{\CapThis} from breaking alternately formatted names remains available to these older solutions by using \texttt{altformat} or the related macros (Section~\ref{sec:AltFormat}).\bigskip
+%
+% \phantomsection
+% \label{page:Priorities}
+% \begin{center}\bfseries Feature Priority\end{center}
+%
+% \noindent The following table shows the relative priority of package options and macros related to indexing, capitalization, and reversing. The darker the row, the lower the priority. Those macros or options in a particular category (column) that have higher priority (row) tend to override similar macros that have lower priority in that same category.
+%
+% Thus, \cmd{\IndexInactive} overrides \cmd{\JustIndex}, which overrides \cmd{\SkipIndex}; using \cmd{\SeeAlso} depends entirely on the interaction of the three others.
+%
+% \begin{center}\small\MyStretch
+% \begin{tabular}{llll}\toprule
+% \bfseries Indexing & \bfseries Capitalization & \bfseries Reversing & \bfseries Name Forms, \\
+% & & & \bfseries Commas, Breaks\\\midrule
+% \texttt{index} & \texttt{normalcaps} & \texttt{notreversed} & \cmd{\ForgetThis}\\
+% \texttt{noindex} & \texttt{allcaps} & \texttt{allreversed} & \cmd{\DropAffix}\\
+% \cmd{\IndexActive} & \cmd{\AllCapsInactive} & \cmd{\ReverseActive} \\
+% \cmd{\IndexInactive} & \cmd{\AllCapsActive} & \cmd{\ReverseInactive} \\
+% \rowcolor{black!7!white}\cmd{\JustIndex} & \cmd{\CapName} & \cmd{\RevName} & \cmd{\SubvertThis}\\
+% \rowcolor{black!7!white} & & & \cmd{\ForceName}\\
+% \rowcolor{black!7!white} & & & \cmd{\NoComma}\\
+% \rowcolor{black!12!white}\cmd{\SkipIndex} & \cmd{\AccentCapThis} & \texttt{allrevcomma} & \cmd{\KeepName}\\
+% \rowcolor{black!12!white} & & \cmd{\RevCommaActive} & \cmd{\ForceFN}\\
+% \rowcolor{black!12!white} & & \cmd{\RevCommaInactive} & \cmd{\ShowComma}\\
+% \rowcolor{black!17!white}\cmd{\SeeAlso} & \cmd{\CapThis} & \cmd{\RevComma} & \cmd{\KeepAffix}\\\bottomrule
+% \end{tabular}
+% \end{center}
+%
+% \ReturnLink
+% \newpage
+%
% \subsection{Naming Macros}
%
-% Although the formatting hooks do nothing by default, we use them here for teaching purposes. We also force first and subsequent uses as needed. See also Sections~\ref{sec:formatting} and~\ref{sec:tweaks}, which explain the concept in detail.
+% In this manual we modify the formatting hooks to show first and later name uses, forcing such uses as needed (Sections~\ref{sec:Formatting} and~\ref{sec:NameControl}). All naming macros create index entries before and after a name for when a name straddles a page break.
%
% \subsubsection{\texttt{\textbackslash Name} and \texttt{\textbackslash Name*}}
% \label{sec:Naming}
%
% \DescribeMacro{\Name}
+% \cmd{\Name} displays and indexes names. It always prints the \meta{SNN} argument. \cmd{\Name} prints the full name at the first occurrence,
% \DescribeMacro{\Name*}
-% \cmd{\Name} displays and indexes names. It always prints the required ``surname'' field. \cmd{\Name} prints the full name at the first occurrence, then a partial form thereafter. \cmd{\Name*} always prints the full name. These macros generate index entries before and after a name in the body text in case of a page break. The general syntax is:
-% \begin{quote}\small\setstretch{1.1}
-% \cmd{\Name}| |\oarg{FNN}\marg{SNN|,| opt. FNN/Affix}\oarg{Alternate names}\\
-% \cmd{\Name}|*|\oarg{FNN}\marg{SNN|,| opt. FNN/Affix}\oarg{Alternate names}
+% then usually just the \meta{SNN} argument thereafter. \cmd{\Name*} always prints the full name:
+% \begin{quote}
+% \fbox{\vbox{\hbox{\mystrut\ \cmd{\Name}| |\oarg{FNN}\marg{SNN|,| Affix}\oarg{Alternate} }\par
+% \hbox{\mystrut\ \cmd{\Name}|*|\oarg{FNN}\marg{SNN|,| Affix}\oarg{Alternate} }}}
% \end{quote}
-% In\marginpar{\large\raggedleft\textsf{\bfseries 3.0}\strut} the body text, not the index, the \meta{Alternate names} field replaces the \meta{FNN} field or the \meta{opt. FNN/Affix} field if they exist. If neither of the latter exist, then the older non-Western syntax is used (Section~\ref{sec:obsolete}).
%
-% \begin{quote}\small\setstretch{1.1}
-% |\begin{nameauth}|\\
-% | \< Einstein & Albert & Einstein & >|\\
-% | \< Cicero & M.T. & Cicero & >|\\
-% | \< Confucius & & Confucius & >|\\
-% | \< Miyaz & & Miyazaki, Hayao & >|\\
-% | \< Eliz & & Elizabeth, I & >|\\
-% |\end{nameauth}|
+% In\Version{3.0} the body text, not the index, the \meta{Alternate} argument replaces either \meta{FNN} or, if \meta{FNN} is absent, \meta{Affix}.\footnote{If \meta{Alternate} is \cmd{\ignorespaces}, the Western long form of \cmd{\Name} looks like the short form. ``Native'' Eastern and ancient forms would have an extra trailing space.}
+% If both \meta{FNN} and \meta{Affix} are absent, then the obsolete syntax is used (Section~\ref{sec:Obsolete}).
+%
+% \begin{quote}\small
+% \StartNum
+% \begin{verbatim}
+%\begin{nameauth}
+% \< Einstein & Albert & Einstein & >
+% \< Cicero & M.T. & Cicero & >
+% \< Confucius & & Confucius & >
+% \< Miyaz & & Miyazaki, Hayao & >
+% \< Eliz & & Elizabeth, I & >
+%\end{nameauth}\end{verbatim}
% \end{quote}
%
-% \begin{center}\small\setstretch{1.1}
+% \begin{center}\small\MyStretch
% \begin{tabular}{ll}\toprule
% |\Name [Albert]{Einstein}| or |\Einstein| & \Name [Albert]{Einstein}\\
% |\Name*[Albert]{Einstein}| or |\LEinstein| & \LEinstein\\
-% |\Name [Albert]{Einstein}| or |\Einstein| & \Einstein\\\midrule
-% |\Name [M.T.]{Cicero}| or |\Cicero| & \Name [M.T.]{Cicero}\\
-% |\Name*[M.T.]{Cicero}[Marcus Tullius]| & \Name*[M.T.]{Cicero}[Marcus Tullius]\\
-% |\Name [M.T.]{Cicero}| or |\Cicero| & \Cicero\\\midrule
-% |\Name {Confucius}| or |\Confucius| & \Confucius\\\midrule
-% |\Name {Miyazaki, Hayao}| or |\Miyaz| & \ForgetThis\Name {Miyazaki, Hayao}\\
-% |\Name*{Miyazaki, Hayao}[Sensei]| & \Name*{Miyazaki, Hayao}[Sensei]\\
-% |\Name {Miyazaki, Hayao}| or |\Miyaz| & \Name {Miyazaki, Hayao}\\\midrule
+% |\Name [Albert]{Einstein}| or |\Einstein| & \Einstein\\
+% \rowcolor{black!7!white}|\Name [M.T.]{Cicero}| or |\Cicero| & \Name [M.T.]{Cicero}\\
+% \rowcolor{black!7!white}|\Name*[M.T.]{Cicero}[Marcus Tullius]| & \Name*[M.T.]{Cicero}[Marcus Tullius]\\
+% \rowcolor{black!7!white}|\Name [M.T.]{Cicero}| or |\Cicero| & \Cicero\\
+% |\Name {Confucius}|, |\Confucius| & \Confucius\\
+% \footnotesize Same for all variants; no \meta{Affix} or \meta{Alternate}. & \Confucius\\
+% \rowcolor{black!7!white}|\Name {Miyazaki, Hayao}| or |\Miyaz| & \ForgetThis\Name {Miyazaki, Hayao}\\
+% \rowcolor{black!7!white}|\Name*{Miyazaki, Hayao}[Sensei]| & \Name*{Miyazaki, Hayao}[Sensei]\\
+% \rowcolor{black!7!white}|\Name {Miyazaki, Hayao}| or |\Miyaz| & \Name {Miyazaki, Hayao}\\
% |\Name {Elizabeth, I}| or |\Eliz| & \ForgetThis\Eliz\\
% |\Name*{Elizabeth, I}| or |\LEliz| & \Name*{Elizabeth, I}\\
% |\Name {Elizabeth, I}| or |\Eliz| & \Name {Elizabeth, I}\\\bottomrule
@@ -1320,514 +1802,824 @@
% \end{tabular}
% \end{center}
%
-% When using the simplified interface, the preferred way to get alternate names is |\LCicero[Marcus Tullius]| and |\LMiyaz[Sensei]|: \LCicero[Marcus Tullius] and \LMiyaz[Sensei]. The next section explains why that is so.
+% When using the simplified interface, the preferred way to get alternate names is |\LCicero[Marcus Tullius]| and |\LMiyaz[Sensei]|: \LCicero[Marcus Tullius] and \LMiyaz[Sensei]. The alternate forename is not shown in subsequent short name references e.g., |\Cicero[Marcus Tullius]| \Cicero[Marcus Tullius].
%
-% Note also that the alternate forename goes away in subsequent short name references. |\Name[M.T.]{Cicero}[Marcus Tullius]| shows up as just \Name [M.T.]{Cicero}[Marcus Tullius] in that case. By default, subsequent name references are surnames only.
+% \newpage
%
-% {\medskip\noindent\hbox{}\hfill\large Back to Section~\ref{sec:RefTables} \hfill\hbox{}}
-% \clearpage
-%
% \subsubsection{Forenames: \texttt{\textbackslash FName}}
-% \label{sec:Fname}
+% \label{sec:FName}
%
% \DescribeMacro{\FName}
+% \cmd{\FName} and its synonym \cmd{\FName*} print personal names only in subsequent name uses. They print full names for first uses.
% \DescribeMacro{\FName*}
-% \cmd{\FName} and its synonym \cmd{\FName*} print personal names only in subsequent name uses. They print full names for first uses. The two macros are the same in case you edit \cmd{\Name*} by adding an \texttt{F} to get a first reference. They print a full name, not a short name, when a name is used for the first time. The syntax is:
-% \begin{quote}\small
-% \cmd{\FName}\oarg{FNN}\marg{SNN|,| opt. FNN/Affix}\oarg{Alternate names}
+% These synonyms let one add an \texttt{F} either to \cmd{\Name} or \cmd{\Name*} to get the same effect:
+% \begin{quote}
+% \fbox{\vbox{\hbox{\mystrut\ \cmd{\FName\ }\oarg{FNN}\marg{SNN|,| Affix}\oarg{Alternate} }\par
+% \hbox{\mystrut\ \cmd{\FName*}\oarg{FNN}\marg{SNN|,| Affix}\oarg{Alternate} }}}
% \end{quote}
+%
% \DescribeMacro{\ForceFN}
-% These\marginpar{\large\raggedleft\textsf{\bfseries 3.0}\strut}
-% macros work with both Eastern and Western names, but to get an Eastern personal name, one must precede these macros with \cmd{\ForceFN}.\footnote{Otherwise you would get poor results with some royal and ancient names.}
-% See also Section~\ref{sec:tweaks} on how to vary some of the forms below. The standard results for subsequent name uses below are:
+% These macros work with both Eastern and Western names, but to get an Eastern personal name, one must precede these macros with \cmd{\ForceFN}.
+% See\Version{3.0} also Sections~\ref{sec:NameParticles} and~\ref{sec:NameControl} on how to vary some of the forms below:
%
-% \begin{center}\small\setstretch{1.1}
+% \begin{center}\small\MyStretch
% \begin{tabular}{ll}\toprule
-% |\FName[Albert]{Einstein}| or |\SEinstein| & \SEinstein\\\midrule
-% |\FName[M.T.]{Cicero}[Marcus Tullius]| \\
-% or |\SCicero[Marcus Tullius]| & \SCicero[Marcus Tullius]\\\midrule
-% |\FName{Confucius}| or |\SConfucius |& \FName{Confucius}\\\midrule
-% |\FName{Miyazaki, Hayao}| or |\SMiyaz| & \FName{Miyazaki, Hayao}\\\midrule
-% |\ForceFN\FName{Miyazaki, Hayao}|\\
-% or |\ForceFN\SMiyaz| & \ForceFN\FName{Miyazaki, Hayao}\\\midrule
-% |\ForceFN\FName{Miyazaki, Hayao}[Sensei]|\\
-% or |\ForceFN\SMiyaz[Sensei]| & \ForceFN\FName{Miyazaki, Hayao}[Sensei]\\\midrule
-% |\FName{Elizabeth, I}| or |\SEliz| & \SEliz\\\midrule
-% |\ForceFN\FName{Elizabeth, I}| & \ForceFN\FName{Elizabeth, I}\\\midrule
-% |\ForceFN\SEliz[the First]| & \ForceFN\SEliz[the First]\\\bottomrule
+% |\FName[Albert]{Einstein}| or |\SEinstein| & \SEinstein\\
+% \rowcolor{black!7!white}|\FName[M.T.]{Cicero}[Marcus Tullius]| & \\
+% \rowcolor{black!7!white}or |\SCicero[Marcus Tullius]| & \SCicero[Marcus Tullius]\\
+% |\FName{Confucius}| or |\SConfucius |& \FName{Confucius}\\
+% \rowcolor{black!7!white}|\FName{Miyazaki, Hayao}| or |\SMiyaz| & \FName{Miyazaki, Hayao}\\
+% |\ForceFN\FName{Miyazaki, Hayao}| & \\
+% or |\ForceFN\SMiyaz| & \ForceFN\FName{Miyazaki, Hayao} \\
+% \rowcolor{black!7!white}|\ForceFN\FName{Miyazaki, Hayao}[Sensei]| & \\
+% \rowcolor{black!7!white}or |\ForceFN\SMiyaz[Sensei]| & \ForceFN\FName{Miyazaki, Hayao}[Sensei]\\
+% |\FName{Elizabeth, I}| or |\SEliz| & \SEliz\\
+% \rowcolor{black!7!white}|\ForceFN\SEliz[Good Queen Bess]| & \ForceFN\SEliz[Good Queen Bess]\\\bottomrule
% \end{tabular}
% \end{center}
%
-% The \meta{Alternate names} argument always replaces the forenames in the text. Sometimes this is a good thing, and sometimes it is not:
-% \begin{nameauth}%
-% \< Ches & Chesley B. & Sullenberger, III & >
-% \< Sully & Chesley B. & Sullenberger, III & Sully >
-% \end{nameauth}%
-% \begin{quote}\small\setstretch{1.1}
-% |\begin{nameauth}|\\
-% | \< Lewis & Clive Staples & Lewis & >|\\
-% | \< CSL & Clive Staples & Lewis & C.S. >|\\
-% | \< Ches & Chesley B. & Sullenberger, III & >|\\
-% | \< Sully & Chesley B. & Sullenberger, III & Sully >|\\
-% |\end{nameauth}|
+% The \meta{Alternate} argument replaces forenames in the text, which strongly shapes the use of \cmd{\FName}.\footnote{If \meta{Alternate} is \cmd{\ignorespaces}, the Western long form of \cmd{\FName} looks like the short form of \cmd{\Name}, while the Western short form of \cmd{\FName} acts like \cmd{\leavevmode} and prints nothing. ``Native'' Eastern and ancient forms would have an extra trailing space.}
+% We recap what we saw on page~\pageref{page:ArgIV}, emphasizing forenames:
+% \begin{quote}\small
+% \StartNum
+% \begin{verbatim}
+%\begin{nameauth}
+% \< Lewis & Clive Staples & Lewis & >
+% \< CSL & Clive Staples & Lewis & C.S. >
+% \< Ches & Chesley B. & Sullenberger, III & >
+% \< Sully & Chesley B. & Sullenberger, III & Sully >
+% \< Miyaz & & Miyazaki, Hayao & >
+% \< MSens & & Miyazaki, Hayao & Sensei >
+%\end{nameauth}\end{verbatim}
% \end{quote}
%
-% For example, if a book section refers always to \LCSL, but another section introduces him as \LLewis, one can use both \cmd{\CSL} and \cmd{\Lewis}. \cmd{\Lewis} and \cmd{\CSL} share common first and subsequent uses because they both point to the same \meta{FNN} (Clive Staples) and \meta{SNN} (Lewis).
+% These share name patterns: \cmd{\SCSL} \SCSL, \cmd{\SLewis} \SLewis; \cmd{\SChes} \SChes, \cmd{\SSully} \SSully; \cmd{\SMiyaz} \SMiyaz, \cmd{\SMSens} \SMSens.
%
-% The drawback lies in remembering that \cmd{\Ches} gives us \Ches, while \cmd{\LSully} produces \LSully. Likewise, \cmd{\SCSL[Jack]} produces \SCSL[Jack]. The final field in the \texttt{nameauth} environment populates the \meta{Alternate Names} argument, making \texttt{[Jack]} normal text.
+% Equivalents: \cmd{\SCSL} \SCSL, \cmd{\SLewis[C.S.]} \SLewis[C.S.]; \cmd{\SSully} \SSully, \cmd{\SChes[Sully]} \SChes[Sully]; |\ForceFN\SMSens| \ForceFN\SMSens, |\ForceFN\SMiyaz[Sensei]|: \ForceFN\SMiyaz[Sensei].
+%
+% These\Warn{} fail: \cmd{\SCSL[Jack]}: \SCSL[Jack]; \cmd{\SSully[Chesley]}: \SSully[Chesley]; and |\ForceFN\SMSens[Hayao]|: \ForceFN\SMSens[Hayao]. Whenever \meta{arg4} of the \texttt{nameauth} environment is used, the respective shorthands cannot take optional arguments.
%
-% {\medskip\noindent\hbox{}\hfill\large Back to Section~\ref{sec:RefTables} \hfill\hbox{}}
-% \clearpage
+% \ReturnLink
+% \newpage
%
-% \subsection{Language Issues}
-% Here we engage topics that relate to specific aspects of grammar and cultural standards. The \textsf{nameauth} package is designed with a keen awareness of cross-cultural use and tries to implement such aspects in a smooth fashion.
+% \subsubsection{Variant Names}
+% \label{sec:VarNames}
%
-% \subsubsection{Affixes Need Commas}
+% This\Version{3.1} section explains how to manage more complicated variants, which gives one the skills needed to implement a name authority. We draw from Sections~\ref{sec:Formatting}, \ref{sec:IndexXref}, \ref{sec:IndexSort}, \ref{sec:NameControl}, and \ref{sec:AKA}. One might want to consult those sections also.
+%
+% We\Info{variant forenames} begin with the easier kind of variant names, namely, variant forenames indexed under a canonical name entry:
+% \begin{quote}\small
+% \StartNum
+% \begin{verbatim}
+%\begin{nameauth}
+% \< Tyson & Mike & Tyson & >
+% \< Iron & Mike & Tyson & Iron Mike >
+%\end{nameauth}\end{verbatim}
+%
+% \begin{tabular}{@{}lrlrl}
+% Same pattern: & \cmd{\Iron} & \Iron & \cmd{\LTyson} & \LTyson\\
+% & \cmd{\SIron} & \SIron & \cmd{\STyson} & \STyson\\
+% \end{tabular}
+% \end{quote}
+% Since \LIron\ is indexed as ``\ShowIdxPageref*[Mike]{Tyson}'' throughout the document, we can use |\IndexRef{Iron Mike}{Tyson, Mike}| with no output in the text or |\AKA[Mike]{Tyson}{Iron Mike}| \AKA[Mike]{Tyson}{Iron Mike} to print a name. Both create the cross-reference ``Iron Mike \textit{see} Tyson, Mike'' in the index.
+%
+% Variant\Info{variant surnames} family names are more complicated than variant personal names. For surname variants, one can use the following method to get fairly good results, depending on the trade-offs that one wishes to accept:
+% \begin{quote}\small
+% \StartNum
+% \begin{verbatim}
+%\begin{nameauth}
+% \< DuBois & W.E.B. & Du~Bois & >
+% \< AltDuBois & W.E.B. & DuBois & >
+%\end{nameauth}
+%\PretagName[W.E.B.]{Du~Bois}{Dubois, W.E.B.}\end{verbatim}
+% \end{quote}
+% \begin{enumerate}
+% \item We decide the canonical name form: \cmd{\DuBois} \ForgetThis\DuBois.
+% \item Both\Warn{} \cmd{\Name[W.E.B.]\{Du Bois\}} and \cmd{\Name[W.E.B.]\{DuBois\}} have the pattern ``\texttt{\ShowPattern[W.E.B.]{Du Bois}}'' (Section~\ref{sec:NamePatterns}). Here we use |Du~Bois| as the argument because we want no breaks, giving us ``\texttt{\ShowPattern[W.E.B.]{Du~Bois}}''.
+% \item We set the sort key for both names to be \texttt{\{Dubois, W.E.B.\}}. If it were of the form \texttt{\{Du Bois, W.E.B.\}}, they would sort differently (Section~\ref{sec:IndexSort}). One must check a style manual for proper sorting.
+% \item Instead of using \cmd{\SkipIndex}\cmd{\AltDuBois} many times, we create a cross-reference in the preamble so that no page entry for the alternate form will occur in the index:\IndexRef[W.E.B.]{DuBois}{Du Bois, W.E.B.}\smallskip\\
+% | \IndexRef[W.E.B.]{DuBois}{Du Bois, W.E.B.}|
+% \item We can use |\JustIndex\DuBois\AltDuBois| \JustIndex\DuBois\AltDuBois, keep full stop detection, and check if the name straddles a page break in order to append |\JustIndex\DuBois| if needed.
+% \item If we create a macro like the one below, we lose full stop detection but then we do not have to check if the name straddles a page break. Normally, the name macros create two index entries each in order to handle this issue automatically:\smallskip\\
+% | \newcommand\NewDuBois%|\\
+% | {\JustIndex\DuBois\AltDubois\JustIndex\DuBois}|
+% \end{enumerate}
+%
+% \newpage
+% \begin{center}\bfseries Example Name Authority\end{center}
+%
+% Below are a couple of names from a name authority created for a translation of \textit{De Diaconis et Diaconissis Veteris Ecclesiae Liber Commentarius} by \Name[Caspar]{Ziegler}, of which the present author was the editor.\footnote{The book, \textit{The Diaconate of the Ancient and Medieval Church}, originally was typeset using \LaTeX, but had to be converted to a different format. Using \LaTeX, the present author has published Charles P. Schaum and Albert B. Collver III, \textit{Breath of God, Yet Work of Man: Scripture, Philosophy, Dialogue, and Conflict} (St. Louis: Concordia Publishing House, 2019).}
+%
+% Constructing that name authority was a challenge. In order to get the names right\,---\,the deceased translator unfortunately had left them in abbreviated Latin, as well as leaving many place names in Latin or translating them incorrectly\,---\,the present author used the following sources, among several others:
+%
+% \begin{itemize}
+% \item CERL Thesaurus: \url{https://data.cerl.org/thesaurus/_search}
+% \item Virtual International Authority File: \url{http://viaf.org/}
+% \item EDIT16: \url{http://edit16.iccu.sbn.it/web_iccu/ehome.htm}
+% \item WorldCat: \url{https://www.worldcat.org/}
+% \item An older version of Graesse, \textit{Orbis Latinus}:\\ \url{http://www.columbia.edu/acis/ets/Graesse/contents.html}
+% \end{itemize}
+%
+% This author followed the scholarly standards for determining the canonical name forms and used the alternate names (which were the ones actually in the original text) to refer to the canonical forms. I just translated all the place-names.
+%
+% Below we have candidates for sorting with \cmd{\PretagName} (Section~\ref{sec:IndexSort}) and potential use of \cmd{\CapThis} (Section~\ref{sec:NameParticles}). After using \cmd{\IndexRef} with a particular name, using \cmd{\Name} with that same name will not create a page reference from that point onward (Section~\ref{sec:IndexXref}).
+%
+% \begin{quote}
+% \StartNum
+% \begin{verbatim}
+%\PretagName[Jacques]{De~Pamele}{Depamele, Jacques}
+%\Name[Jacques]{De~Pamele}[Jacques de~Joigny]
+%\IndexRef[Jacobus]{Pamelius}{De~Pamele, Jacques}
+%\Name[Jacobus]{Pamelius}
+%
+%\PretagName[Giovanni]{d'Andrea}{Dandrea, Giovanni}
+%\Name[Giovanni]{d'Andrea}
+%\IndexRef[Ioannes]{Andreae}{d'Andrea, Giovanni}
+%\Name[Ioannes]{Andreae}\end{verbatim}
+%
+% \medskip \begin{tabular}{ll}\toprule
+% Canonical Name & Alternate Name\\\midrule
+% \Name[Jacques]{De~Pamele}[Jacques de~Joigny] &
+% \leavevmode\IndexRef[Jacobus]{Pamelius}{De~Pamele, Jacques}\Name[Jacobus]{Pamelius}\\
+% \rowcolor{black!7!white}\Name[Giovanni]{d'Andrea} &
+% \leavevmode\IndexRef[Ioannes]{Andreae}{d'Andrea, Giovanni}\Name[Ioannes]{Andreae}\\\bottomrule
+% \end{tabular}
+% \end{quote}
+% \CapThis\Name[Giovanni]{d'Andrea} |\CapThis\Name[Giovanni]{d'Andrea}| can be used at the beginning of a sentence. |\Name[Jacques]{De~Pamele}| gives \Name[Jacques]{De~Pamele}.
+%
+% \ReturnLink
+% \newpage
+%
+% \subsection{Language Topics}
+% \label{sec:Lang}
+% This section looks at how \textsf{nameauth} addresses grammar, usage, and cultural standards. The concept of comma-delimited affixes dominates much of this section.
+%
+% \subsubsection[Affixes]{Affixes Require Commas}
% \label{sec:Affix}
%
-% Comma-delimited affixes are shown below. For Western names, they separate a surname and an affix. For non-Western names, they separate either a surname and a forename or a name and an affix. \emph{Always use a comma as an affix delimiter}, even when commas are not printed. Spaces between the comma and affix are ignored. See also Section~\ref{sec:tolerance}.
+% A comma is required to separate a Western surname and affix, an Eastern family name and personal name, and an ancient name and affix. Yet we must take care because an example like \cmd{\Name\{}\cmd{\textsc\{a Name, Problem\}\}} will halt \LaTeX\ with errors (Section~\ref{sec:AltFormat}). Spaces around the comma are ignored (Section~\ref{sec:ErrorProt}).
%
-% \begin{center}\small\ForgetName{Sun, Yat-sen}\setstretch{1.1}
+% \begin{center}\small\ForgetName{Sun, Yat-sen}\MyStretch
% \begin{tabular}{ll}\toprule
% |\Name[Oskar]{Hammerstein, II}| & \KeepAffix\Name[Oskar]{Hammerstein, II}\\
-% |\Name[Oskar]{Hammerstein, II}| & \Name[Oskar]{Hammerstein, II}\\\midrule
-% |\Name{Louis, XIV}| & \KeepAffix\Name{Louis, XIV}\\
-% |\Name{Louis, XIV}| & \Name{Louis, XIV}\\\midrule
+% |\Name[Oskar]{Hammerstein, II}| & \Name[Oskar]{Hammerstein, II}\\
+% \rowcolor{black!7!white}|\Name{Louis, XIV}| & \KeepAffix\Name{Louis, XIV}\\
+% \rowcolor{black!7!white}|\Name{Louis, XIV}| & \Name{Louis, XIV}\\
% |\Name{Sun, Yat-sen}| & \KeepAffix\Name{Sun, Yat-sen}\\
% |\Name{Sun, Yat-sen}| & \Name{Sun, Yat-sen}\\\bottomrule
% \end{tabular}
% \end{center}
%
-% Western\marginpar{\small\raggedleft\dbend} names with suffixes must use the comma-delimited syntax. Using the older non-Western syntax |\Name[Oskar]{Hammerstein}[II]| produces \SkipIndex\Name[Oskar]{Hammerstein}[II] (index entry skipped). Also, one must use comma-delimited suffixes with the cross-reference target of \cmd{\AKA} (Section~\ref{sec:AKA}).\medskip
+% Western\Warn{} names with affixes must use the comma-delimited syntax. Using the obsolete syntax, |\SkipIndex\Name[Oskar]{Hammerstein}[II]| produces \SkipIndex\Name[Oskar]{Hammerstein}[II] which is an error. See also (Section~\ref{sec:AKA}).\medskip
%
% \DescribeMacro{\KeepAffix}
-% In the text only, \cmd{\KeepAffix} turns the space between \meta{SNN} and \meta{Affix} into a non-breaking space. This holds for a Western surname and affix, an ancient name and affix, and a native Eastern family name and personal name.\medskip
+% In the text only, \cmd{\KeepAffix} turns the space \emph{between} \meta{SNN} and \meta{Affix} into a non-breaking space. This holds for a Western surname and affix, an ancient name and affix, and a ``native'' Eastern family name and personal name.\medskip
%
% \DescribeMacro{\KeepName}
-% In the text only,\marginpar{\large\raggedleft\textsf{\bfseries 3.1}\strut} \cmd{\KeepName} turns all spaces between name components \meta{FNN}, \meta{SNN}, \meta{Affix}, and \meta{Alternate name(s)} into non-breaking spaces. You get no bad breaks with |\KeepName\LJWG[von]| \KeepName\LJWG[von].
+% In the text only, \cmd{\KeepName} turns all spaces \emph{between} name elements \meta{FNN}, \meta{SNN}, and \meta{Affix} into non-breaking spaces;\Version{3.1} |\KeepName\LJWG[von]| \KeepName\LJWG[von] will not break. This macro does not alter spaces \emph{within} name elements like \meta{FNN} (French or German forenames) and \meta{SNN} (Spanish surnames). Both \cmd{\KeepAffix} and \cmd{\KeepName} can affect \textsf{nameauth} macros that print in the text.\medskip
%
-% \cmd{\KeepAffix} and \cmd{\KeepName} affect all \textsf{nameauth} macros that print names in the text. Spaces between multiple names within each name component (think Spanish surnames and French or German forenames) are not affected.\medskip
-%
% \DescribeMacro{\DropAffix}
-% Preceding\marginpar{\large\raggedleft\textsf{\bfseries 3.0}\strut} the naming macros with \cmd{\DropAffix} will suppress an affix in a Western name. |\DropAffix\Name*[Oskar]{Hammerstein, II}| produces ``\DropAffix\Name*[Oskar]{Hammerstein, II}.'' This does not affect non-Western names.\medskip
+% Preceding the naming macros with \cmd{\DropAffix} will suppress an affix in a Western name. |\DropAffix\Name*[Oskar]{Hammerstein, II}| produces\Version{3.0} ``\DropAffix\Name*[Oskar]{Hammerstein, II}.'' This does not affect non-Western names.\medskip
%
% \DescribeMacro{\ShowComma}
+% \cmd{\ShowComma} forces a comma between a Western name and its affix. It works like the \texttt{comma} option on a per-name basis, and only in the body text.
% \DescribeMacro{\NoComma}
-% \cmd{\ShowComma} forces a comma between a Western name and its affix. It works like the \texttt{comma} option on a per-name basis, and only in the body text. \cmd{\NoComma}\marginpar{\large\raggedleft\textsf{\bfseries 2.6}\strut} works like the \texttt{nocomma} option in the body text on a per-name basis.
-% \begin{center}\small\setstretch{1.1}
-% \begin{tabular}{@{}ll@{}}\toprule
+% \cmd{\NoComma} works like the \texttt{nocomma} option in the body text on a per-name basis.
+% Neither\Version{2.6} of these macros affect the use of \cmd{\RevComma}, which always prints a comma.
+% \begin{center}\small\MyStretch
+% \begin{tabular}{ll}\toprule
% |\ShowComma\Name*[Louis]{Gossett, Jr.}| & \ShowComma\Name*[Louis]{Gossett, Jr.}\\
-% |\NoComma\Name*[Louis]{Gossett, Jr.}| & \NoComma\Name*[Louis]{Gossett, Jr.}\\
-% |\RevComma\ShowComma\Name*[Louis]{Gossett, Jr.}| & \RevComma\ShowComma\Name*[Louis]{Gossett, Jr.}\\
-% |\RevComma\NoComma\Name*[Louis]{Gossett, Jr.}| & \RevComma\NoComma\Name*[Louis]{Gossett, Jr.}\\\bottomrule
+% \rowcolor{black!7!white}|\NoComma\Name*[Louis]{Gossett, Jr.}| & \NoComma\Name*[Louis]{Gossett, Jr.}\\\bottomrule
% \end{tabular}
% \end{center}
%
-% {\medskip\noindent\hbox{}\hfill\large Back to Section~\ref{sec:RefTables} \hfill\hbox{}}
-% \clearpage
+% \ReturnLink
+% \newpage
%
+% \subsubsection[Listing by Surname]{Listing Western names by Surname}
+% \label{sec:LastFirst}
+%
+% \DescribeMacro{\ReverseCommaActive}
+% In addition to the options for reversed comma listing (Section~\ref{sec:PkgOptions}), the macros \cmd{\ReverseCommaActive} and \cmd{\ReverseCommaInactive}
+% \DescribeMacro{\ReverseCommaInactive}
+% function the same way with blocks of text. They all override \cmd{\RevComma}.
+% \DescribeMacro{\RevComma}
+% These all reorder long Western name forms (via \cmd{\Name*} and the like). The first two are broad toggles, while the third works on a per-name basis. These\Version{3.0} macros only affect Western and ``non-native'' Eastern name forms.
+% \begin{center}\small\MyStretch
+% \begin{tabular}{lll}\toprule
+% \ForgetThis\VBuren & \RevComma\LVBuren & OK\\
+% \ForgetThis\Name[Oskar]{Hammerstein, II} & \RevComma\Name*[Oskar]{Hammerstein, II} & OK\\
+% \ForgetThis\LNoguchi & \RevComma\LNoguchi\dag & OK\\
+% \rowcolor{black!7!white}\ForgetThis\Aeth & \RevComma\LAeth & no change\\
+% \rowcolor{black!7!white}\ForgetThis\Name{Chiang}[Kai-shek] & \RevComma\Name*{Chiang}[Kai-shek] & no change\\
+% \rowcolor{black!7!white}\ForceName\Name{Confucius} & \RevComma\Name{Confucius} & no change\\\bottomrule
+% \end{tabular}
+% \end{center}
+%
+% Both\Info{\cmd{\global}} \cmd{\ReverseCommaActive} and \cmd{\ReverseCommaInactive} can be used either as a pair or singly within a local scope. Use \cmd{\global} to force a global effect.
+%
+% \ReturnLink
+%
% \subsubsection{Eastern Names}
% \label{sec:Eastern}
%
-% The\marginpar{\small\raggedleft non-native} \textsf{nameauth} package offers ``non-native'' and ``native'' ways to handle romanized Eastern names. The ``non-native'' form is entered as a Western name and it is indexed as such. \cmd{\RevName} reverses its order in the body text:
-% \begin{quote}\small
-% \cmd{\RevName}\cmd{\Name*}\oarg{FNN}\marg{SNN}\oarg{Alternate names}
+% One\Info{``non-native''} produces a ``non-native'' Eastern name in the text by reversing a Western without \meta{Affix} using \cmd{\RevName}:
+% \begin{quote}
+% \fbox{\mystrut\ \cmd{\RevName}\cmd{\Name*}\oarg{FNN}\marg{SNN}\oarg{Alternate} }
% \end{quote}
-% The index entry of this name form looks like \meta{SNN}, \meta{FNN} (including the comma). This type of entry is a Western form. Pick this form also when using Hungarian names. Apologies for needing to enter Hungarian names in reverse, as in |\RevName\Name*[Frenec]{Molnár}| \RevName\Name*[Frenec]{Molnár}\dag.\medskip
%
-% In\marginpar{\small\raggedleft native} contrast, there are two general forms of syntax for ``native'' Eastern name forms, which are indexed as such and appear in Eastern name order in the body text. Apologies for using quasi-Western \meta{SNN} and \meta{FNN} nomenclature for Eastern names. The new syntax permits alternate names; the old does not:
-% \begin{quote}\small\setstretch{1.1}
-% \cmd{\Name}\marg{SNN, FNN}\oarg{Alternate names}\hfill (new syntax)\\
-% \cmd{\Name}\marg{SNN}\oarg{FNN}\hfill (older syntax)
+% The index entry of this name form looks like \meta{SNN}, \meta{FNN} (including the comma). This is a Western index entry. This form is used also for Hungarian names, e.g.: |\RevName\Name[Frenec]{Molnár}| \ForgetThis\RevName\Name[Frenec]{Molnár}\dag, \RevName\Name[Frenec]{Molnár}\dag.\medskip
+%
+% In\Info{``native''} contrast, ``native'' Eastern names use either comma-delimited syntax or the obsolete syntax. They have Eastern-form index entries \meta{SNN} \meta{Affix/Alternate} (no comma). The new syntax permits alternate names; the obsolete does not. These forms work also with ancient and medieval names:
+%
+% \begin{quote}
+% \fbox{\ \parbox{0.45\textwidth}{%
+% \mystrut\cmd{\Name}\marg{SNN, Affix}\oarg{Alternate}\\
+% \mystrut\cmd{\Name}\marg{SNN}\oarg{Alternate}}
+% \parbox{0.225\textwidth}{\color{nared}\mystrut\texttt{\%} \textit{new syntax}\\ \mystrut\texttt{\%} \textit{obsolete syntax}}}
% \end{quote}
-% The index entry of this name form looks like \meta{SNN} \meta{FNN} (no comma). This type of entry bears similarity with ancient and medieval forms. Pick native Eastern names when you want to use Eastern forms in the index.\medskip
%
+% People\Info{avoid error} can make mistakes that these forms help one to avoid. For example, in an otherwise excellent German-language history textbook series, one finds an index entry for ``Yat-sen, Sun''. It should be ``Sun Yat-sen''.\footnote{See Immanuel Geiss, \textit{Personen: Die biographische Dimension der Weltgeschichte}, Geschichte Griffbereit vol. 2 (Munich: Wissen Media Verlag, 2002), 720. Errors arising from cultural differences and basic mistakes give justification for the design of \textsf{nameauth}.}
+% The form |\Name{Sun, Yat-sen}| \Sun\ ensures the correct entry.\medskip
+%
% \DescribeMacro{\ReverseActive}
+% In addition to the options for reversing (Section~\ref{sec:PkgOptions}), \cmd{\ReverseActive} and \cmd{\ReverseInactive} reverse name order for blocks of text.
% \DescribeMacro{\ReverseInactive}
+% These all override the use of \cmd{\RevName}, which reverses once per name.
% \DescribeMacro{\RevName}
-% In addition to the class options for reversing and capitalization (Section~\ref{sec:options}), \cmd{\ReverseActive} and \cmd{\ReverseInactive} reverse name order for blocks of text and \cmd{\RevName} does that once per name. These macros only affect names in the text. They work also with \cmd{\AKA} and its derivatives.
-%
-% The reverse output mechanism affects full names only. Nevertheless, it does not force full names. Results vary, based on the type of Eastern name forms being used. Non-native forms are shown by a dagger (\dag):
-% \begin{center}\small\setstretch{1.1}
+% These macros do not affect the index. They work also with \cmd{\AKA} and its derivatives. The reverse mechanism shows only in full names, but it does not force full names. ``Non-native'' forms are shown by a dagger (\dag) in the next table:
+% \begin{center}\small\MyStretch
% \begin{tabular}{rll}\toprule
-% & \emph{unchanged} & |\RevName|\\\midrule
-% |\LKonoe| & \LKonoe\dag & \RevName\LKonoe\dag\\
-% |\LKonoe[Prime Minister]| & \LKonoe[Prime Minister]\dag & \meta{not appropriate}\\
-% |\Konoe| & \Konoe\dag & \RevName\Konoe\dag\\
-% |\SKonoe| & \SKonoe\dag & \RevName\SKonoe\dag\\\midrule
-% |\LYamt| & \LYamt & \RevName\LYamt\\
-% |\LYamt[Admiral]| & \meta{not appropriate} & \RevName\LYamt[Admiral]\\
-% |\Yamt| & \Yamt & \RevName\Yamt\\
-% |\SYamt| & \SYamt & \RevName\SYamt\\
-% |\ForceFN\SYamt| & \ForceFN\SYamt & \ForceFN\RevName\SYamt\\\bottomrule
-% \end{tabular}
+% & unchanged & |\RevName|\\\midrule
+% |\LNoguchi| & \LNoguchi & \RevName\LNoguchi\dag\\
+% |\LNoguchi[Doctor]| & \LNoguchi[Doctor] & \raise0.5ex\hbox to 5em{\hfil\rule{3em}{0.6pt}} \\
+% |\LNoguchi[Sensei]| & \raise0.5ex\hbox to 5em{\hfil\rule{3em}{0.6pt}} & \RevName\LNoguchi[Sensei]\dag\\
+% |\Noguchi| & \Noguchi & \RevName\Noguchi\dag\\
+% |\SNoguchi| & \SNoguchi & \RevName\SNoguchi\dag\\
+% \rowcolor{black!7!white}|\LYamt| & \LYamt & \RevName\LYamt\\
+% \rowcolor{black!7!white}|\LYamt[Admiral]| & \raise0.5ex\hbox to 5em{\hfil\rule{3em}{0.6pt}} & \RevName\LYamt[Admiral]\\
+% \rowcolor{black!7!white}|\Yamt| & \Yamt & \RevName\Yamt\\
+% \rowcolor{black!7!white}|\SYamt| & \SYamt & \RevName\SYamt\\
+% \rowcolor{black!7!white}|\ForceFN\SYamt| & \ForceFN\SYamt & \ForceFN\RevName\SYamt\\\bottomrule
+% \end{tabular}\medskip\\
% \end{center}
%
-% Creating\marginpar{\large\raggedleft\textsf{\bfseries 3.0}\strut} ``last-comma-first'' listings by surname (Section~\ref{sec:LastFirst}) only makes sense with Western names and maybe non-native Eastern names, but not with native Eastern names or ancient forms. That is why native Eastern forms and ancient forms are unaffected by the comma form of reversing.\medskip
+% Both\Info{\cmd{\global}} \cmd{\ReverseActive} and \cmd{\ReverseInactive} can be used either as a pair or singly within an explicitly local scope. Use \cmd{\global} to force a global effect.\medskip
%
-% 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.
-% \clearpage
-%
% \DescribeMacro{\AllCapsActive}
+% In addition to the options for capitalizing (Section~\ref{sec:PkgOptions}), \cmd{\AllCapsActive} and \cmd{\AllCapsInactive} work for blocks of text.
% \DescribeMacro{\AllCapsInactive}
+% All override \cmd{\CapName}, which works once per name.
% \DescribeMacro{\CapName}
-% Using \cmd{\AllCapsActive} \cmd{\AllCapsInactive} for blocks of text and \cmd{\CapName} for specific names, the \textsf{nameauth} package allows one to capitalize \meta{SNN} in the body text only. These macros also work with \cmd{\AKA} and friends. For caps in the text and index see Sections~\ref{sec:altformat} and~\ref{sec:Hooksc}.
+% These capitalize \meta{SNN} in the body text only. They also work with \cmd{\AKA} and friends. For caps in the text and index see Sections~\ref{sec:AltFormat} and~\ref{sec:Hooksiii}. We show ``non-native'' Eastern forms with a dagger ({\dag}) and the old syntax with a double dagger(\ddag).
%
-% Below, non-native Eastern forms (first Western, then reversed) are marked with a dagger ({\dag}). All other names are in native Eastern, then Western order. Older-syntax forms have a double dagger(\ddag):
-%
-% \begin{center}\small\setstretch{1.1}\AllCapsActive
+% \begin{center}\small\MyStretch\AllCapsActive
% \begin{tabular}{lll}\toprule
% & |\CapName| only & |\CapName\RevName|\\\midrule
-% |\Name*[Yoko]{Kanno}| & \CapName\Name*[Yoko]{Kanno}\dag & \CapName\RevName\Name*[Yoko]{Kanno}\dag\\
-% |\Name*{Arai, Akino}| & \Name*{Arai, Akino} & \RevName\Name*{Arai, Akino}\\
+% |\Name*[Yoko]{Kanno}| & \CapName\Name*[Yoko]{Kanno} & \CapName\RevName\Name*[Yoko]{Kanno}\dag\\
+% \rowcolor{black!7!white}|\Name*{Arai, Akino}| & \Name*{Arai, Akino} & \RevName\Name*{Arai, Akino}\\
% |\Name*{Ishida}[Yoko]| & \CapName\Name*{Ishida}[Yoko]\ddag & \CapName\RevName\Name*{Ishida}[Yoko]\ddag\\
-% |\Name*{Yohko}| & \Name*{Yohko} & \RevName\Name*{Yohko}\\\bottomrule
+% \rowcolor{black!7!white}|\Name*{Yohko}| & \Name*{Yohko} & \RevName\Name*{Yohko}\\\bottomrule
% \end{tabular}\AllCapsInactive
-% \end{center}\smallskip
-%
-%
-% 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.
-%
-%
-% {\medskip\noindent\hbox{}\hfill\large Back to Section~\ref{sec:RefTables} \hfill\hbox{}}
-%
-% \subsubsection{Initials}
-%
-% Omit spaces between initials if possible; see also Bringhurst's \emph{Elements of Typographic Style}. If your publisher wants spaces between initials, try putting thin spaces |\,| between them. Use \cmd{\PretagName} to get the correct index sorting:\bigskip
-%
-% \leavevmode\begin{minipage}[c]{0.55\textwidth}\footnotesize\setstretch{1.1}
-% |\PretagName[E.\,B.]{White}{White, E. B.}|\\
-% |\begin{nameauth}|\\
-% | \< White & E.\,B. & White & >|\\
-% |\end{nameauth}|
-% \end{minipage}
-% \begin{minipage}[c]{0.35\textwidth}\footnotesize
-% \def\sep{\vrule width0.5pt\kern-0.5pt}%
-% \normalsize\begin{tabular}{@{}ll@{}}\hline
-% & \hspace{0.48pt}\hphantom{E.}\sep\,\sep\hphantom{B.}\sep\hphantom{\ }\sep\hphantom{White}\\
-% \cmd{\White} & \hspace{0.48pt}\White\\
-% & \hspace{0.48pt}\hphantom{E.}\sep\,\sep\hphantom{B.}\sep\hphantom{\ }\sep\hphantom{White}\\\hline
-% & \sffamily\hphantom{E.}\sep\ \sep\hphantom{B.}\sep\ \sep\hphantom{White}\\
-% Normal text:\hfill & \sffamily E. B. White\\
-% & \sffamily\hphantom{E.}\sep\ \sep\hphantom{B.}\sep\ \sep\hphantom{White}\\\hline
-% \end{tabular}
-% \end{minipage}
-%
-% \subsubsection{Hyphenation}
-%
-% In English, some names come from other cultures. These names, like \SkipIndex\Name[John]{Strietelmeier} (|\Name[John]{Strietelmeier}|, index entry skipped) can break badly. One solution consistently uses optional hyphens, while another uses either \textsf{babel} or \textsf{polyglossia}. If using both solutions with a name, suppress unwanted index entries.
-% \begin{quote}\small\setstretch{1.1}
-% |\newcommand\de[1]{\foreignlanguage{ngerman}{#1}}|\\
-% |% or polyglossia: \newcommand\de[1]{\textgerman{#1}}|\\
-% |\begin{nameauth}|\\
-% | \< Striet & John & Strie\-tel\-meier & >|\\
-% | \< Strieti & John & \de{Strietelmeier} & >|\\
-% |\end{nameauth}|\\
-% |\PretagName[John]{Strie\-tel\-meier}{Strietelmeier, John}|\\
-% |\PretagName[John]{\de{Strietelmeier}}{Strietelmeier, John}|
-% \end{quote}
-% In English, some names come from other cultures. These names, like \SkipIndex\Striet, (\cmd{\Striet}, index entry skipped) could break badly unless handled correctly. In English, some names come from other cultures. These names, like \Strieti, (\cmd{\Strieti}) could break badly if not handled correctly.
-%
-% \subsubsection{Listing by Surname}
-% \label{sec:LastFirst}
-%
-% \DescribeMacro{\ReverseCommaActive}
-% \DescribeMacro{\ReverseCommaInactive}
-% \DescribeMacro{\RevComma}
-% The macros \cmd{\ReverseCommaActive}, \cmd{\ReverseCommaInactive}, and \cmd{\RevComma}\ let us reorder long Western names (via \cmd{\Name*} and the like). The first two are broad toggles, while the third works on a per-name basis.
-%
-% These macros\marginpar{\large\raggedleft\textsf{\bfseries 3.0}\strut} do not affect ``native'' Eastern and ancient name forms. Also, see below how long uses are not always first uses:
-% \begin{center}\small\setstretch{1.1}
-% \begin{tabular}{lll}\toprule
-% \ForgetThis\VBuren & \RevComma\LVBuren & OK\\
-% \ForgetThis\Name[Oskar]{Hammerstein, II} & \RevComma\Name*[Oskar]{Hammerstein, II} & OK\\
-% \ForgetThis\Aeth & \RevComma\LAeth & no change\\
-% \ForgetThis\Name{Chiang}[Kai-shek] & \RevComma\Name*{Chiang}[Kai-shek] & no change\\
-% \ForceName\Name{Confucius} & \RevComma\Name{Confucius} & no change\\\bottomrule
-% \end{tabular}
% \end{center}
+%
+% Both\Info{\cmd{\global}} \cmd{\AllCapsActive} and \cmd{\AllCapsInactive} can be used either as a pair or singly within an explicitly local scope. Use \cmd{\global} to force a global effect.
%
-% Since\marginpar{\large\raggedleft\textsf{\bfseries 3.0}} reversing with commas does not change ``native'' Eastern and ancient names, we see its effects on ``non-native'' Eastern names:
-% \begin{center}\small\setstretch{1.1}
-% \begin{tabular}{rl}\toprule
-% |\ForgetThis\Konoe| & \ForgetThis\Konoe\dag\\
-% |\RevName\LKonoe| & \RevName\LKonoe\dag\\
-% |\RevComma\LKonoe| & \RevComma\LKonoe\dag\\\bottomrule
-% \end{tabular}
-% \end{center}
+% \ReturnLink
%
-% 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}.
+% \subsubsection[Particles / Ancient]{Particles, Medieval Names, and Ancient Names}
+% \label{sec:NameParticles}
%
-% \subsubsection{Particles}
-% \label{sec:standards}
+% English\Info{cap rules} names with particles \textit{de}, \textit{de\ la}, \textit{d'}, \textit{von}, \textit{van}, and \textit{ten} often keep them with the last name, using varied capitalization.\footnote{According to [\hyperlink{Mulvany}{Mulvany}, 165f.] and the \textit{Chicago Manual of Style}.} \textit{Le}, \textit{La}, and \textit{L'} always are capitalized unless preceded by \textit{de}. See also Sections~\ref{sec:SimpleStart}, \ref{sec:NamePatterns}, \ref{sec:VarNames}, and \ref{sec:AltFormat}.\medskip
%
-% According to [\hyperlink{Mulvany}{Mulvany}, 165f.] and the \emph{Chicago Manual of Style}, English names with the particles \emph{de}, \emph{de\ la}, \emph{d'}, \emph{von}, \emph{van}, and \emph{ten} generally keep them with the last name, using varied capitalization. \emph{Le}, \emph{La}, and \emph{L'} always are capitalized unless preceded by \emph{de}. To Anglicize \JWG[Johann Wolfgang von] in the text as \LJWG[von], but indexed under ``Goethe, J.W. von,'' we use |\LJWG[von]|. |\Name[Catherine de']{Medici}| should be indexed as ``Medici, Catherine de'\,'' instead of modern ``De~Medici.'' See also Sections~\ref{sec:indexctrl} and especially~\ref{sec:DuBois} for name variants.\AltFormatActive\JustIndex\Cath\AltFormatInactive
+% We\Info{non-breaking\break spaces} recommend inserting a tilde (active character for a non-breaking space) or \cmd{\nobreakspace} between some particles and names to prevent bad breaks, sorting them with \cmd{\PretagName} (Section~\ref{sec:IndexSort}).
+% Some particles look similar: \textit{L'} (L+apostrophe) and \textit{d'} (d+apostrophe) are two separate glyphs each. In contrast, \textit{Ľ} (L+caron) and \textit{ď} (d+caron) are one Unicode glyph each (Section~\ref{sec:Unicode}).
+%\newpage
%
-% We\marginpar{\small\raggedleft non-breaking\break spaces} recommend inserting |~| or \cmd{\nobreakspace} between particles and names to prevent bad breaks.\footnote{With v.3.0, \cmd{\CapThis} does not eat the space between a single-letter particle and a name.}
-% Some particles look very similar. For example, \emph{L'} and \emph{d'} are two separate glyphs each. \emph{Ľ} and \emph{ď} are one Unicode glyph each.\medskip
-%
+% \phantomsection
+% \label{page:CapThis}
% \DescribeMacro{\CapThis}
-% In English and modern Romance languages, \emph{e.g.}, \ForgetThis\Soto\ shows that these particles go in the \meta{SNN} field of \cmd{\Name}: \Soto. When the particle appears at the beginning of a sentence, one must capitalize it:
-% \begin{quote}\small\setstretch{1.1}
-% |\CapThis\Soto\ was a famous Spanish explorer in North America.|\\[1ex]
-% \CapThis\Soto\ was a famous Spanish explorer in North America.
+% In English and modern Romance languages, e.g., \ForgetThis\Soto\ shows that these particles go in the \meta{SNN} argument of \cmd{\Name}: \Soto. When the particle appears at the beginning of a sentence, one must capitalize it:
+% \begin{quote}\small
+% |\CapThis\Soto\| \CapThis\Soto\ was a famous Spanish explorer in North America.
% \end{quote}
%
-% \cmd{\CapThis},\marginpar{\large\raggedleft\textsf{\bfseries 3.2}\strut} rather, the capitalizing mechanism that it triggers, has undergone a significant overhaul in recent versions of \textsf{nameauth}. Earlier versions tried to take a few ``shortcuts'' that appeared to work. Problems arose with specific cases where capitalization did not work. We have addressed those problems, most of which involved macro expansion.
+% \cmd{\CapName} overrides the \meta{SNN} created by \cmd{\CapThis}. \cmd{\CapThis}\Version{3.2} should work with all of the Unicode characters available in the T1 encoding (its mechanism is explained in Section~\ref{sec:Unicode} and on page~\pageref{page:CapSystem}). For a broader set of Unicode characters, consider using \texttt{xelatex} and \texttt{lualatex}.\medskip
%
-% Now, \cmd{\CapThis} should work as expected with all of the Unicode characters available in the T1 encoding. Section~\ref{sec:Unicode} has a list, yet see also the table on pages 455--63 in \emph{The Latex Companion}. For a broader set of Unicode characters, consider using \texttt{xelatex} and \texttt{lualatex}.
-%
-% Without going into the gory details, it became clear that:
-% \begin{enumerate}
-% \item There must be one ``regular'' test for a leading active Unicode character and a separate test when that occurs in a comma-delimited suffix.
-% \item We cannot use the suffix designed for printing and for testing if we even have a suffix. The test requires a ``raw'' form of the suffix.
-% \item The token list test for active Unicode characters can be its own component shared by the two test forms above.
-% \item One should do one of the two tests, then pick one of two capitalization methods. Keeping everything separate will help the expansion work properly in every case.
-% \item Every name component is modified. The idea is that you decide to use \cmd{\CapThis} in a short name form when the leading element needs to be capitalized. Chances are, you will not need a full name reference with suffix, etc. By capping every element, you have access to caps on demand using any form of short name reference.
-% \end{enumerate}
-%
-% \cmd{\CapThis} will not cause errors if one uses the \texttt{altformat} option and the provided macros for Continental surname formats because that option entirely bypasses the normal in-text capitalization mechanism. \cmd{\CapThis} still triggers the alternate capping macros, but the mechanism is different and far more manual. Otherwise \cmd{\CapThis} could cause errors in some cases where control sequences in the macro arguments conflict with the capitalization process. See Section~\ref{sec:altformat}.
-%
-% For another example, we suppose that you want to mention poet \Name[e.e.]{cummings}. You might be in a situation where an editor wants: ``\SkipIndex\SubvertThis\CapThis\Name[e.e.]{cummings'} motif of the goat-footed balloon man has underlying sexual motifs that nevertheless have a childish facade.'' We got that form using:
+% For\Info{surname variants} another example, we mention poet \Name[e.e.]{cummings}. One can have formatted name caps and inflections, e.g.: \ExcludeName[e.e.]{cummings's}``\SubvertThis\CapThis\Name[e.e.]{cummings's} motif of the goat-footed balloon man has underlying sexual themes that nevertheless have a childish facade.'' The easiest way to do that is from Section~\ref{sec:IndexXref}:
% \begin{quote}\small
-% |\SkipIndex\SubvertThis\CapThis\Name[e.e.]{cummings'}|
+% |\ExcludeName[e.e.]{cummings's}|\\
+% . . .\\
+% |\SubvertThis\CapThis\Name[e.e.]{cummings's}%|\\
+% |\IndexName[e.e.]{cummings}|\dotfill \SubvertThis\CapThis\Name[e.e.]{cummings's}\IndexName[e.e.]{cummings}
% \end{quote}
%
-% A long-name reference to \CapThis\Name*[e.e.]{cummings} really does not work, nor is it meant to. \cmd{\CapThis} is not meant for general situations. Using \cmd{\CapName} replaces both the original \meta{SNN} and the \meta{SNN} created by \cmd{\CapThis}. Again, this usage is situation-dependent.
+% One\Warn{} must use \cmd{\SubvertThis} only for the first use to avoid ``\ForgetThis\CapThis\Name[e.e.]{cummings's}''; all name elements are capped with \cmd{\CapThis}. Using \cmd{\ExcludeName} keeps one from having to use \cmd{\SkipIndex} every time. With \textsf{nameauth} we can use both simple and complex solutions to name variation. See also Section~\ref{sec:VarNames}.
%
-% Names are beautiful, yet ambiguous creatures whose forms change greatly, depending on one's needs and circumstances. This package allows for such variation, yet it provides consistent in the index. We do try to minimize the amount of typing, allowing for automatic reformatting if one moves blocks of text around. We hope that this approach is useful.\medskip
+% Section~\ref{sec:AltFormat} explains how to use \cmd{\CapThis} with alternate formatting when using macros in name arguments. Page~\pageref{page:Inflections} describes how automation lends itself to Continental (French, German, etc.) formats and grammatical inflections.\medskip
%
% \DescribeMacro{\AccentCapThis}
-% If the source files\marginpar{\large\raggedleft\textsf{\bfseries 3.0}\strut} for the \textsf{nameauth} package have Unicode encoding and run on a Unicode-compliant system, \cmd{\AccentCapThis} is not necessary. See also page~\pageref{page:CapSystem}. If the text encoding of the source files is changed or there are system encoding issues, \cmd{\AccentCapThis} might be needed with NFSS when the first name character is an active Unicode character. See also Section \ref{sec:Unicode}.
-% \clearpage
+% If one uses this package on a system that does not handle Unicode, one can use \cmd{\AccentCapThis} instead of \cmd{\CapThis}\Version{3.0} to handle active initial characters. Otherwise, one should not need to use \cmd{\AccentCapThis}.
%
-% Medieval\marginpar{\small\raggedleft Medieval name\break issues} names present some interesting difficulties, often based on the expected standards of the context in which they are used:
-% \begin{quote}\small\setstretch{1.1}
-% |\PretagName{Thomas, à~Kempis}{Thomas a Kempis}|\hfill\emph{medieval}\\
-% |\PretagName[Thomas]{à~Kempis}{Thomas a Kempis}|\hfill\emph{Western}\\
-% |\begin{nameauth}|\\[0.2ex]
-% | \< KempMed & & Thomas, à~Kempis & >|\hfill\emph{medieval, new syntax}\\
-% | \< KempAlt & & Thomas & à~Kempis >|\hfill\emph{medieval, older syntax}\\
-% | \< KempW & Thomas & à~Kempis & >|\hfill\emph{Western}\\
-% |\end{nameauth}|
+% \begin{center}\bfseries Examples\end{center}
+%
+% Medieval\Info{medieval names} names present some interesting difficulties, often based on the expected standards of the context in which they are used:
+% \begin{quote}\small
+% \StartNum
+% \begin{verbatim}
+%\PretagName{Thomas, à~Kempis}{Thomas Akempis} % medieval
+%\PretagName[Thomas]{à~Kempis}{Akempis, Thomas} % Western
+%\IndexRef[Thomas]{à~Kempis}{Thomas à~Kempis} % xref
+%\ExcludeName{Thomas,\`a~Kempis} % alternate form excluded
+%\begin{nameauth}
+% \< KempMed & & Thomas, à~Kempis & > % medieval
+% \< KempW & Thomas & à~Kempis & > % Western
+%\end{nameauth}\end{verbatim}
+% \IndexRef[Thomas]{à~Kempis}{Thomas à~Kempis}
+% \ExcludeName{Thomas,\`a~Kempis}
% \end{quote}
-% The medieval forms\marginpar{\large\raggedleft\textsf{\bfseries 3.1}\strut} are \KempMed\ and \KempMed, indexed as ``Thomas à~Kempis.'' The suffixed place name ``\ForceFN\SKempMed'' (Latin for \emph{von Kempen}) is used by some as a surname and achieved by using |\ForceFN\SKempMed|. \CapThis\ForceFN\SKempMed\ can start a sentence via |\CapThis\ForceFN\SKempMed|. The old syntax works just as well: \CapThis\ForceFN\SKempAlt\ occurs via |\CapThis\ForceFN\SKempAlt|.
%
-% Western forms\marginpar{\small\raggedleft\dbend} like |\KempW|: \SkipIndex\KempW\ are different from medieval forms and create different index entries. |\CapThis\KempW| gives ``\SkipIndex\CapThis\KempW'' in the text and ``à~Kempis, Thomas'' in the index, which we suppress here.\footnote{Name variants result from work flow constraints, name authorities, and publisher styles. This package works with that, over against this author's plea for cultural sensitivity.}
-% The publisher's way of handling names may differ from the standard way. This package allows for such variations.\footnote{Yet some publishers have problems with some name forms. An example of a true error is the index entry ``Yat-sen, Sun'' (as if Sun were a forename) in Immanuel Geiss, \emph{Personen: Die biographische Dimension der Weltgeschichte}, Geschichte Griffbereit vol. 2 (Munich: Wissen Media Verlag, 2002), 720. Still, the six-volume set is a helpful reference work.}
-% Developing a good rapport with the publisher and the editor will help you apply this package to the company's style.
+% The medieval forms\Version{3.1} \KempMed\ and \KempMed\ are indexed as ``\ShowIdxPageref*{Thomas, à~Kempis}.'' The place name |\ForceFN\SKempMed| ``\ForceFN\SKempMed'' (Latin for \textit{von Kempen}) technically is not a Western surname.
+% \CapThis\ForceFN\SKempMed\ |\CapThis\ForceFN\SKempMed| starts a sentence. \Name{Thomas,\`a~Kempis} |\Name{Thomas,\`a~Kempis}| is different. \CapThis\SubvertThis\ForceFN\FName{Thomas, \`a~Kempis} is |\CapThis\SubvertThis\ForceFN\FName{Thomas,\`a~Kempis}|.
+% One should use \cmd{\PretagName} to sort the index entry (Section~\ref{sec:IndexSort}). We excluded this alternate form (Section~\ref{sec:IndexXref}).
+% \newpage
%
-% Using \cmd{\CapThis} with forms like |\`a~Kempis| will work (\SkipIndex\CapThis\SubvertThis\ForceFN\ForceName\FName{Thomas, \`a~Kempis}) in all situations where one uses the preamble snippet in Section~\ref{sec:engines}.\footnote{This little example is among one of the longest uses of prefix macros in this manual: \cmd{\SkipIndex}\cmd{\CapThis}\cmd{\SubvertThis}\cmd{\ForceFN}\cmd{\ForceName}\cmd{\FName\{Thomas, \textbackslash`a~Kempis\}}.}
+% Western forms\Warn{} like |\KempW|: \KempW\ are very different from medieval forms and create different index entries. |\CapThis\KempW| gives ``\CapThis\KempW'' in the text and ``\ShowIdxPageref*[Thomas]{à~Kempis}'' in the index.
+%
+% Above, we created a cross-reference from the Western form to the medieval form, preventing page entries (Section~\ref{sec:IndexXref}). If we sorted the cross-reference using |\PretagName[Thomas]{à~Kempis}{a Kempis, Thomas}|, it would precede \texttt{aardvark}. We use |\PretagName[Thomas]{à~Kempis}{Akempis, Thomas}|, which sorts the cross-reference between \texttt{ajar} and \texttt{alkaline}. One should check a style manual for correct sorting (Section~\ref{sec:IndexSort}).\medskip
+%
+% \phantomsection
+% \label{page:Sobriquets}
+% \begingroup%^^A
+% \renewcommand*\NamesFormat{}%^^A
+% \renewcommand*\MainNameHook{}%^^A
+% Ancient\Info{ancient names} contexts may or may not bind particles to surnames. The \meta{alternate} argument, \cmd{\PretagName}, and \cmd{\TagName} address this (Sections~\ref{sec:IndexSort}, \ref{sec:IndexTag}).
+%
+% The next examples do not use the formatting conventions of this manual and sometimes hide details that are specific to this manual in order to keep things simple and reflect normal document usage. See the \texttt{dtx} source code for more information. First we use variants with \meta{alternate}:\footnote{Copies of these examples are in \texttt{examples.tex}, collocated with this manual.}
+% \NameAddInfo{Demetrius, I}{ Soter}
+% \begin{quote}\small
+% \StartNum
+% \begin{verbatim}
+%\NameAddInfo{Demetrius, I}{ Soter}
+%\PretagName{Demetrius, I}{Demetrius 1}
+%\TagName{Demetrius, I}{ Soter, king}
+%\begin{nameauth}
+% \< Dem & & Demetrius, I & >
+%\end{nameauth}\end{verbatim}
%
-% \begingroup
-% \makeatletter\renewcommand*\NamesFormat[1]{\begingroup\ignorespaces%
-% \protected at edef\temp{\endgroup{\color{naviolet}\sffamily #1 %\ignorespaces
+% \smallskip
+% \begin{tabular}{ll}\toprule
+% |\Dem[I Soter]| & \Dem[I Soter]\\
+% \rowcolor{black!7!white}|\LDem| & \LDem\\
+% |\Dem| & \Dem\\\bottomrule
+% \end{tabular}
+% \end{quote}
+%
+% \makeatletter\renewcommand*\NamesFormat[1]{\begingroup%^^A
+% \protected at edef\temp{\endgroup{#1%^^A
% \noexpand\NameQueryInfo[\unexpanded\expandafter{\the\@nameauth at toksa}]
% {\unexpanded\expandafter{\the\@nameauth at toksb}}
-% [\unexpanded\expandafter{\the\@nameauth at toksc}]}}\temp}\makeatother%
-% Non-English\marginpar{\small\raggedleft\dbend} contexts do not necessarily bind particles to surnames. One can use the alternate names field or ``text tags'' and ``index tags.'' See also Sections~\ref{sec:indextag}, \ref{sec:tagtext}, and~\ref{sec:Hooksb}. The macros below allow us to show \Name{Friedrich, I}, \Name*{Friedrich, I}, and \Name{Friedrich, I} via |\Name{Friedrich, I}|:
-% \begin{quote}\footnotesize\setstretch{1.1}
-% |\NameAddInfo{Friedrich, I}{Barbarossa}|\\
-% |\PretagName{Friedrich, I}{Friedrich 1}|\\
-% |\TagName{Friedrich, I}{ Barbarossa, emperor|\texttt{\textbar}|hyperpage}|\\[1ex]
-% |\makeatletter\renewcommand*\NamesFormat[1]{\begingroup%|\\
-% |\protected at edef\temp{\endgroup{\color{naviolet}\sffamily #1 %|\\
-% |\noexpand\NameQueryInfo[\unexpanded\expandafter{\the\@nameauth at toksa}]|\\
-% |{\unexpanded\expandafter{\the\@nameauth at toksb}}|\\
-% |[\unexpanded\expandafter{\the\@nameauth at toksc}]}}\temp}\makeatother|
-% \end{quote}
-% \endgroup
+% [\unexpanded\expandafter{\the\@nameauth at toksc}]}}\temp}\makeatother
+% For a more automated approach, we can use ``text tags'' in the formatting macros (see Sections~\ref{sec:TextTags}, \ref{sec:Hooksii}).
%
-% {\noindent\hbox{}\hfill\large Back to Section~\ref{sec:RefTables} \hfill\hbox{}}
-% \clearpage
+% \begin{quote}\small
+% \ContinueNum
+% \begin{verbatim}
+%\makeatletter
+%\renewcommand*\NamesFormat[1]{%
+% \begingroup%
+% \protected at edef\temp{\endgroup%
+% {#1\noexpand\NameQueryInfo
+% [\unexpanded\expandafter{\the\@nameauth at toksa}]
+% {\unexpanded\expandafter{\the\@nameauth at toksb}}
+% [\unexpanded\expandafter{\the\@nameauth at toksc}]%
+% }%
+% }%
+% \temp%
+%}
+%\makeatother\end{verbatim}
%
-% \subsubsection{Accented Names}
-% \label{sec:accents}
+% \smallskip
+% \begin{tabular}{ll}\toprule
+% |\ForgetThis\Dem| & \ForgetThis\Dem\\
+% \rowcolor{black!7!white}|\LDem| & \LDem\\
+% |\Dem| & \Dem\\\bottomrule
+% \end{tabular}
+% \end{quote}
+%
+% The Roman naming\Info{Roman names} system does present some challenges. As long as we do not use \cmd{\CapThis}, we do not need alternate formatting (Section~\ref{sec:AltFormat}). Earlier we treated \LCicero[Marcus Tullius] as a Western name. Now we handle Roman names more properly.
+%
+% We have a \textit{praenomen}, a personal name. Then we have a \textit{nomen}, a clan name. Finally, we would have a \textit{cognomen}, a nickname, except it became hereditary to denote clan branches. Added to that are \textit{agnomina}, affixed names.
+%
+% Popular\Info{popular works} sources tend to treat the \textit{cognomen} as we might a surname, with the indexed form: \ShowIdxPageref*[\meta{praenomen} \meta{nomen}]{\meta{cognomen} \meta{agnomen}}.\footnote{See Geiss, \textit{Geschichte Griffbereit}; Kinder and Hilgemann, \textit{dtv-Atlas zur Weltgeschichte}, 2 vols., 29th printing (1964; Munich: Deutscher Taschenbuch Verlag, 1993). For further resources see: \url{http://books.infotoday.com/books/Indexing-names.shtml}. See also \url{https://en.wikipedia.org/wiki/Roman_naming_conventions}.}
+% We want all names in the index, so we define macros in \meta{FNN} and \meta{SNN} that expand one or two components: \textit{praenomen} and \textit{nomen}, \textit{cognomen} and \textit{agnomen}. We begin by defining a name with macros using \cmd{\noexpand} to prevent error:
+%\newif\ifSkipGens
+%\newif\ifNoGens
+%\newif\ifSkipAgnomen
+%\newif\ifNoAgnomen
+%\newcommand*\SCIPi{\ifNoGens Publius\else
+% Publius Cornelius\fi}
+%\newcommand*\SCIPii{\ifNoAgnomen Scipio\else
+% Scipio Africanus\fi}
+%\newcommand*\ScipioOnly{\SkipAgnomentrue\Scipio}
+%\renewcommand*\NamesFormat[1]%^^A
+% {\ifSkipGens\NoGenstrue\fi\ifSkipAgnomen\NoAgnomentrue\fi#1%^^A
+% \global\SkipGensfalse\global\SkipAgnomenfalse}
+%\renewcommand*\MainNameHook[1]%^^A
+% {\ifSkipGens\NoGenstrue\fi\ifSkipAgnomen\NoAgnomentrue\fi#1%^^A
+% \global\SkipGensfalse\global\SkipAgnomenfalse}
+% \begin{quote}\small
+% \StartNum
+% \begin{verbatim}
+%\begin{nameauth}
+% \< Scipio & \noexpand\SCIPi & \noexpand\SCIPii & >
+%\end{nameauth}
+%\PretagName[\noexpand\SCIPi]{\noexpand\SCIPii}{Scipio Africanus}\end{verbatim}
+% \end{quote}
%
-% For names that contain accented characters, using \texttt{xelatex} or \texttt{lualatex} with \texttt{xindy} (\texttt{texindy}) is recommended. See also Section~\ref{sec:engines}.
+% We define the flags and macros by which the name will change. The global state of \cmd{\NoGens} and\cmd{\NoAgnomen} determine the index form. The local scope in the formatting hooks allows changes that are reset when exiting that scope. The logic is inverted; false prints long, true prints short:
+% \begin{quote}\small
+% \ContinueNum
+% \begin{verbatim}
+%\newif\ifSkipGens
+%\newif\ifNoGens
+%\newif\ifSkipAgnomen
+%\newif\ifNoAgnomen
+%\newcommand*\SCIPi{\ifNoGens Publius\else
+% Publius Cornelius\fi}
+%\newcommand*\SCIPii{\ifNoAgnomen Scipio\else
+% Scipio Africanus\fi}
+%\newcommand*\ScipioOnly{\SkipAgnomentrue\Scipio}
+%\renewcommand*\NamesFormat[1]%^^A
+% {\ifSkipGens\NoGenstrue\fi\ifSkipAgnomen\NoAgnomentrue\fi#1%
+% \global\SkipGensfalse\global\SkipAgnomenfalse}
+%\renewcommand*\MainNameHook[1]%^^A
+% {\ifSkipGens\NoGenstrue\fi\ifSkipAgnomen\NoAgnomentrue\fi#1%
+% \global\SkipGensfalse\global\SkipAgnomenfalse}\end{verbatim}
+%\smallskip
+% \ForgetThis\ScipioOnly\ \cmd{\ScipioOnly} was born around 236 \textsc{bc} into the Scipio branch of the Cornelius clan, one of six large patrician clans. \ScipioOnly\ \cmd{\ScipioOnly} rose to military fame during the Second Punic War. Thereafter he was known as \Scipio\ \cmd{\Scipio}.
+% \end{quote}
+%
+% An advantage of the popular format is that one can drop both \textit{praenomen} and \textit{nomen} automatically in subsequent uses. Yet in any case, one can define helper macros to change Boolean flags. The raw index entry is fairly lengthy by necessity, governed by the global state of the Boolean flags, and expanding to:
+% \begin{quote}\small
+% \ShowIdxPageref[\noexpand\SCIPi]{\noexpand\SCIPii}
+% \end{quote}
+%
+% The\Info{scholarly works} \textit{Oxford Classical Dictionary} and other scholarly sources index under the \textit{nomen}. That requires a similar approach, but it moves the \textit{nomen} from \meta{FNN} to \meta{SNN}. Although we will not index the name, we will show how to set up \SkipGenstrue\Scipio\ to work in that alternate configuration.
+% \newpage
+%
+% We keep the Boolean flags as previously created. We redefine the name in the following manner:
+% \begin{quote}\small
+% \StartNum
+% \begin{verbatim}
+%\begin{nameauth}
+% \< OScipio & Publius & \noexpand\CSA & >
+%\end{nameauth}
+%\PretagName[Publius]{\noexpand\CSA}{Cornelius Scipio Africanus}\end{verbatim}
+% \end{quote}
+%
+%\newcommand*\CSA{\ifNoGens
+% \ifNoAgnomen
+% Scipio\else
+% Scipio Africanus\fi
+% \else\ifNoAgnomen
+% Cornelius Scipio\else
+% Cornelius Scipio Africanus\fi\fi}
+% \ExcludeName[Publius]{\noexpand\CSA}
+% We use a nested conditional in \meta{SNN}. The default still is to show all names so that they can be indexed that way. This time we decided to index under the popular form instead of the scholarly one, so we exclude the scholarly form:
+% \begin{quote}\small
+% \StartNum
+% \begin{verbatim}
+%\newcommand*\CSA{\ifNoGens
+% \ifNoAgnomen
+% Scipio\else
+% Scipio Africanus\fi
+% \else\ifNoAgnomen
+% Cornelius Scipio\else
+% Cornelius Scipio Africanus\fi\fi}
+%\ExcludeName[Publius]{\noexpand\CSA}\end{verbatim}
+% \end{quote}
+%
+% The scholarly form has a different name pattern, so it is not compatible with the popular version. Nevertheless, we show what the raw index entry of the scholarly form would be. We include some of the more meaningful forms of both versions:
+% \begin{quote}\small
+% \cmd{\ShowPattern[Publius]\{}\cmd{\noexpand}\cmd{\CSA\}}:\\
+% \hbox{}\quad \ShowPattern[Publius]{\noexpand\CSA}
+%
+% \cmd{\ShowIdxPageref[Publius]\{}\cmd{\noexpand}\cmd{\CSA\}}:\\
+% \hbox{}\quad \ShowIdxPageref[Publius]{\noexpand\CSA}
+%
+% \textbf{First use:}\\[0.5ex]
+% \cmd{\OScipio}:\quad \OScipio\\
+% \cmd{\Scipio\ }:\quad \ForgetThis\Scipio
+%
+% \textbf{Subsequent use:}\\[0.5ex]
+% \hphantom{\cmd{\SkipGenstrue}}\cmd{\OScipio}:\quad \OScipio\\
+% \cmd{\SkipGenstrue}\cmd{\OScipio}:\quad \SkipGenstrue\OScipio\\
+% \hphantom{\cmd{\SkipGenstrue}}\cmd{\Scipio\ }:\quad \SkipGenstrue\Scipio
+%
+% \textbf{Subsequent use, full, no \textit{agnomen}:}\\[0.5ex]
+% \cmd{\SkipAgnomentrue}\cmd{\LOScipio}:\quad \SkipAgnomentrue\LOScipio\\
+% \cmd{\SkipAgnomentrue}\cmd{\LScipio\ }:\quad \SkipAgnomentrue\LScipio
+%
+% \textbf{Subsequent use, shortest forms:}\\[0.5ex]
+% \hphantom{\cmd{\SkipGenstrue}}\cmd{\SkipAgnomentrue}\cmd{\OScipio}:\quad \SkipAgnomentrue\OScipio\\
+% \cmd{\SkipGenstrue}\cmd{\SkipAgnomentrue}\cmd{\OScipio}:\quad \SkipGenstrue\SkipAgnomentrue\OScipio\\
+% \hphantom{\cmd{\SkipGenstrue}}\cmd{\SkipAgnomentrue}\cmd{\Scipio\ }:\quad \SkipAgnomentrue\Scipio
+%
+% \textbf{Subsequent use, personal name:}\\[0.5ex]
+% \hphantom{\cmd{\SkipGenstrue}}\cmd{\SOScipio}:\quad \SOScipio\\
+% \cmd{\SkipGenstrue}\cmd{\SScipio\ }:\quad \SkipGenstrue\SScipio
+% \end{quote}
+%
+% See Sections~\ref{sec:ErrorProt}, \ref{sec:AltFormat}, and \ref{sec:Hooks} for more guidance on avoiding errors when using name arguments that contain macros.
+% \endgroup
+%
+% \ReturnLink
+% \newpage
%
-% In NFSS,\marginpar{\small\raggedleft\dbend} many Unicode characters are active. Especially with \texttt{makeindex}, use \cmd{\PretagName} to sort all names with active characters (Sections~\ref{sec:IndexSort} and~\ref{sec:Unicode}).
-% \ForgetName{Æthelred, II}
-% These active characters differ from explicit control sequences that one might type. We suppress unwanted index entries below among the names that truly are different, yet look the same.
-% \begin{itemize}\small
-% \item |\Name{Æthelred, II}| creates \Name{Æthelred, II} and \Name{Æthelred, II}. Now we have a different name: |\Name{\AE thelred, II}| \SkipIndex\Name{\AE thelred, II} (a ``first reference'').
-% \item |\Name{Bo\"ethius}| \Name{Bo\"ethius} is not the same as |\Name{Boëthius}| \SkipIndex\Name{Boëthius}. Both differ from |\Name{\textsf{Boëthius}}| \SkipIndex\Name{\textsf{Boëthius}}.
-% \end{itemize}
+% \subsection{Basic Formatting}
+% \label{sec:Formatting}
%
-% See Section~\ref{sec:Unicode} on how to add additional Unicode glyphs to the default set under NFSS, \textsf{inputenc}, and \textsf{fontenc}.
-%
-% {\medskip\noindent\hbox{}\hfill\large Back to Section~\ref{sec:RefTables} \hfill\hbox{}}
-%
-% \subsection{Formatting}
-%
-% \subsubsection{Spaces \& Full Stops}
-% \label{sec:tolerance}
-%
-% The \textsf{nameauth} package is forgiving with spaces; extra spaces usually do not create unique names, as we see below:
-%
-% \begin{center}\small\setstretch{1.1}\ForgetName[Martin Luther]{King, Jr.}
-% \begin{tabular}{ll}\toprule
-% \textit{Macro Example} & \textit{Resulting Text}\\\midrule
-% |\Name*[Martin Luther]{King,Jr.}| & \Name*[Martin Luther]{King,Jr.}\\
-% \cmd{\Name*}\texttt{[\textvisiblespace\textvisiblespace Martin\textvisiblespace\textvisiblespace Luther\textvisiblespace\textvisiblespace]\{\textvisiblespace\textvisiblespace King,\textvisiblespace\textvisiblespace Jr.\textvisiblespace\textvisiblespace\}} & \Name*[ Martin Luther ]{ King, Jr. }\\\bottomrule
-% \end{tabular}
+% Below are many of the forms and formats that names can have:
+%
+% \ifDoTikZ
+% \begin{tcolorbox}[colframe=naslate,sidebyside,lower separated=true,adjusted title={\hfil Full Forms, Front Matter\hspace{5em} Short Forms, Front matter}]\centering
+% {\cmd{\NamesInactive}}\NamesInactive
+% \begin{tcolorbox}[left=2mm,right=2mm,bottom=1mm,colback=white,adjusted title={\sffamily\bfseries\hfil First Use (Default)}]\small
+% \begin{tabular}{@{}ll@{}}
+% \cmd{\Name} & \ForgetThis\Pat\\
+% & \ForgetThis\Eliz\\
+% & \ForgetThis\Yamt\\
+% \cmd{\Name*} & \ForgetThis\LPat\\
+% \cmd{\FName} & \ForgetThis\SPat\\
+% \end{tabular}
+% \end{tcolorbox}
+% \begin{tcolorbox}[left=2mm,right=2mm,bottom=1mm,colback=white,adjusted title={\sffamily\bfseries\hfil Later Use (\texttt{*} or \cmd{\L}\meta{macro})}]\small
+% \begin{tabular}{@{}ll@{}}
+% \cmd{\Name*} & \LPat\\
+% & \LEliz\\
+% & \LYamt\\
+% \end{tabular}
+% \end{tcolorbox}
+% \begin{tcolorbox}[left=2mm,right=2mm,bottom=1mm,colback=white,adjusted title={\sffamily\bfseries\hfil Long, with \cmd{\DropAffix}}]\small
+% \begin{tabular}{@{}ll@{}}
+% \cmd{\DropAffix}\cmd{\LPat}\\ \SubvertThis\DropAffix\LPat\\
+% \end{tabular}
+% \end{tcolorbox}
+% \tcblower\centering
+% {\cmd{\NamesInactive}}\NamesInactive
+% \begin{tcolorbox}[left=2mm,right=2mm,bottom=1mm,colback=white,adjusted title={\sffamily\bfseries\hfil Later Use (Default)}]\small
+% \begin{tabular}{@{}ll@{}}
+% \cmd{\Name} & \SubvertThis\Pat; \SubvertThis\Eliz\\
+% & \SubvertThis\Yamt\\
+% \cmd{\FName}, & \SubvertThis\SPat; \SubvertThis\SEliz\\
+% \cmd{\S}\meta{macro} & \SubvertThis\SYamt\\
+% \end{tabular}
+% \end{tcolorbox}\vspace{1.4ex}
+% \begin{tcolorbox}[left=2mm,right=2mm,bottom=1mm,colback=white,adjusted title={\sffamily\bfseries\hfil Later Use (\cmd{\ForceName})}]\small
+% \begin{tabular}{@{}ll@{}}
+% \cmd{\Name} & \SubvertThis\ForceName\Pat; \SubvertThis\ForceName\Eliz\\
+% & \SubvertThis\ForceName\Yamt\\
+% \cmd{\FName}, & \SubvertThis\ForceName\SPat; \SubvertThis\ForceName\SEliz\\
+% \cmd{\S}\meta{macro} & \SubvertThis\ForceName\SYamt\\
+% \end{tabular}
+% \end{tcolorbox}\vspace{1.4ex}
+% \begin{tcolorbox}[left=2mm,right=2mm,bottom=1mm,colback=white,adjusted title={\sffamily\bfseries\hfil Later Use (\cmd{\ForceFN})}]\small
+% \begin{tabular}{@{}ll@{}}
+% \cmd{\FName}, \cmd{\S}\meta{macro} & \SubvertThis\ForceFN\SYamt\\
+% \end{tabular}
+% \end{tcolorbox}
+% \end{tcolorbox}
+% \vfil
+% \begin{tcolorbox}[colframe=naslate,sidebyside,lower separated=true,adjusted title={\hfil Full Forms, Main Matter\hspace{5em} Short Forms, Main Matter}]\centering
+% {\cmd{\NamesActive}}\NamesActive
+% \begin{tcolorbox}[left=2mm,right=2mm,bottom=1mm,colback=white,adjusted title={\sffamily\bfseries\hfil First Use (Default)}]\small
+% \begin{tabular}{@{}ll@{}}
+% \cmd{\Name} & \ForgetThis\Pat\\
+% & \ForgetThis\Eliz\\
+% & \ForgetThis\Yamt\\
+% \cmd{\Name*} & \ForgetThis\LPat\\
+% \cmd{\FName} & \ForgetThis\SPat\\
+% \end{tabular}
+% \end{tcolorbox}
+% \begin{tcolorbox}[left=2mm,right=2mm,bottom=1mm,colback=white,adjusted title={\sffamily\bfseries\hfil Later Use (\texttt{*} or \cmd{\L}\meta{macro})}]\small
+% \begin{tabular}{@{}ll@{}}
+% \cmd{\Name*} & \LPat\\
+% & \LEliz\\
+% & \LYamt\\
+% \end{tabular}
+% \end{tcolorbox}
+% \begin{tcolorbox}[left=2mm,right=2mm,bottom=1mm,colback=white,adjusted title={\sffamily\bfseries\hfil Long, with \cmd{\DropAffix}}]\small
+% \begin{tabular}{@{}ll@{}}
+% \cmd{\DropAffix}\cmd{\LPat}\\ \SubvertThis\DropAffix\LPat\\
+% \end{tabular}
+% \end{tcolorbox}
+% \tcblower\centering
+% {\cmd{\NamesActive}}\NamesActive
+% \begin{tcolorbox}[left=2mm,right=2mm,bottom=1mm,colback=white,adjusted title={\sffamily\bfseries\hfil Later Use (Default)}]\small
+% \begin{tabular}{@{}ll@{}}
+% \cmd{\Name} & \SubvertThis\Pat; \SubvertThis\Eliz\\
+% & \SubvertThis\Yamt\\
+% \cmd{\FName}, & \SubvertThis\SPat; \SubvertThis\SEliz\\
+% \cmd{\S}\meta{macro} & \SubvertThis\SYamt\\
+% \end{tabular}
+% \end{tcolorbox}\vspace{1.4ex}
+% \begin{tcolorbox}[left=2mm,right=2mm,bottom=1mm,colback=white,adjusted title={\sffamily\bfseries\hfil Later Use (\cmd{\ForceName})}]\small
+% \begin{tabular}{@{}ll@{}}
+% \cmd{\Name} & \SubvertThis\ForceName\Pat; \SubvertThis\ForceName\Eliz\\
+% & \SubvertThis\ForceName\Yamt\\
+% \cmd{\FName}, & \SubvertThis\ForceName\SPat; \SubvertThis\ForceName\SEliz\\
+% \cmd{\S}\meta{macro} & \SubvertThis\ForceName\SYamt\\
+% \end{tabular}
+% \end{tcolorbox}\vspace{1.4ex}
+% \begin{tcolorbox}[left=2mm,right=2mm,bottom=1mm,colback=white,adjusted title={\sffamily\bfseries\hfil Later Use (\cmd{\ForceFN})}]\small
+% \begin{tabular}{@{}ll@{}}
+% \cmd{\FName}, \cmd{\S}\meta{macro} & \SubvertThis\ForceFN\SYamt\\
+% \end{tabular}
+% \end{tcolorbox}
+% \end{tcolorbox}
+% \else\bigskip
+% \begin{center}\small\NamesInactive
+% \begin{tabular}{@{\hspace{4em}}c@{\hspace{6em}}c}
+% Full Forms, Front Matter & Short Forms, Front Matter\\
+% \cmd{\NamesInactive} & \cmd{\NamesInactive}\medskip\\
+% \end{tabular}
+%
+% \begin{tabular}{llll}\toprule
+% \cmd{\Name} & \ForgetThis\Pat & \cmd{\Name} & \SubvertThis\Pat, \SubvertThis\Eliz\\
+% & \ForgetThis\Eliz & & \SubvertThis\Yamt\\
+% & \ForgetThis\Yamt & \cmd{\FName}, & \SubvertThis\SPat; \SubvertThis\SEliz\\
+% \cmd{\Name*} & \ForgetThis\LPat & \cmd{\S}\meta{macro} & \SubvertThis\SYamt\\
+% \cmd{\FName} & \ForgetThis\SPat & \\\midrule
+% & & Using \cmd{\ForceName} \\
+% \cmd{\Name*}, & \LPat & \cmd{\Name} & \SubvertThis\ForceName\Pat; \SubvertThis\ForceName\Eliz\\
+% \cmd{\L}\meta{macro} & \LEliz & & \SubvertThis\ForceName\Yamt\\
+% & \LYamt & \cmd{\FName}, & \SubvertThis\ForceName\SPat; \SubvertThis\ForceName\SEliz\\
+% & & \cmd{\S}\meta{macro} & \SubvertThis\ForceName\SYamt\\\midrule
+% & & Using \cmd{\ForceFN} \\
+% \cmd{\DropAffix}\cmd{\LPat} & \SubvertThis\DropAffix\LPat & \cmd{\FName}, \cmd{\S}\meta{macro} & \SubvertThis\ForceFN\SYamt\\\bottomrule% \end{tabular}
+% \end{center}\bigskip
+% \begin{center}\small\NamesActive
+% \begin{tabular}{@{\hspace{4em}}c@{\hspace{6em}}c}
+% Full Forms, Main Matter & Short Forms, Main Matter\\
+% \cmd{\NamesActive} & \cmd{\NamesActive}\medskip\\
+% \end{tabular}
+%
+% \begin{tabular}{llll}\toprule
+% \cmd{\Name} & \ForgetThis\Pat & \cmd{\Name} & \SubvertThis\Pat; \SubvertThis\Eliz\\
+% & \ForgetThis\Eliz & & \SubvertThis\Yamt\\
+% & \ForgetThis\Yamt & \cmd{\FName}, & \SubvertThis\SPat; \SubvertThis\SEliz\\
+% \cmd{\Name*} & \ForgetThis\LPat & \cmd{\S}\meta{macro} & \SubvertThis\SYamt\\
+% \cmd{\FName} & \ForgetThis\SPat & \\\midrule
+% & & Using \cmd{\ForceName} \\
+% \cmd{\Name*}, & \LPat & \cmd{\Name} & \SubvertThis\ForceName\Pat; \SubvertThis\ForceName\Eliz\\
+% \cmd{\L}\meta{macro} & \LEliz & & \SubvertThis\ForceName\Yamt\\
+% & \LYamt & \cmd{\FName}, & \SubvertThis\ForceName\SPat; \SubvertThis\ForceName\SEliz\\
+% & & \cmd{\S}\meta{macro} & \SubvertThis\ForceName\SYamt\\\midrule
+% & & Using \cmd{\ForceFN} \\
+% \cmd{\DropAffix}\cmd{\LPat} & \SubvertThis\DropAffix\LPat & \cmd{\FName}, \cmd{\S}\meta{macro} & \SubvertThis\ForceFN\SYamt\\\bottomrule
+% \end{tabular}
% \end{center}
+% \fi
+% \newpage
%
-% 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 and produce two of them. \cmd{\Name}, \cmd{\FName}, and \cmd{\AKA} detect this in the printed form of a name and gobble the subsequent full stop as needed:
-%
-% \begin{center}\footnotesize\setstretch{1.1}\ForgetName[Martin Luther]{King, Jr.}
-% \begin{tabular}{rcl}\toprule
-% \textit{Macro Example\hfill} & \textit{Result} & \textit{Resulting Text}\\\midrule
-% |\Name [Martin Luther]{King, Jr.}.| & gobbled & \Name [Martin Luther]{King, Jr.}.\\
-% |\Name [Martin Luther]{King, Jr.}.| & stayed & \Name [Martin Luther]{King, Jr.}.\\
-% |\Name*[Martin Luther]{King, Jr.}.| & gobbled & \Name*[Martin Luther]{King, Jr.}.\\
-% |\DropAffix\Name*[Martin Luther]{King, Jr.}.| & stayed & \DropAffix\Name*[Martin Luther]{King, Jr.}.\\
-% |\FName[Martin Luther]{King, Jr.}[M.L.]|. & gobbled & \FName[Martin Luther]{King, Jr.}[M.L.]\\\bottomrule
-% \end{tabular}
-% \end{center}
-% Grouping tokens inhibit gobbling: |{\Name*[Martin Luther]{King, Jr.}}.|
-% This produces ``{\Name*[Martin Luther]{King, Jr.}}.'' We see two periods. Enclosing |{Jr.}| within braces or making the whole suffix a macro argument also prevents gobbling. Leave the final period outside the macro or group, for example:
-%\begin{quote}
-%\indent{\small|\Name[Martin Luther]{\textSC{King}, \textSC{Jr}.}|}
-% \end{quote}
-% Compare Sections~\ref{sec:altformat} and~\ref{sec:Hooksc}.
-%
-% \subsubsection{Formatting in the Text}
-% \label{sec:formatting}
-%
-% There are two kinds of formatting at work that interact with each other:
+% These formatting features of \textsf{nameauth} can work with name control macros (Section~\ref{sec:NameControl}) in, for example, \textsf{beamer} overlays to define consistently the context and outcome of how names appear. There are two kinds of formatting at work that interact with each other:
% \begin{enumerate}\small
-% \item \textbf{Syntactic Formatting:} Displayed name elements, reversing, and caps normally occur only in the body text, not the index.
-% \item \textbf{Name Post-Processing:} Hook macros apply formatting to the printed form of a name, which normally does not affect the name form.
+% \item \emph{Syntactic Formatting:} Reversing and caps normally occur only in the body text, not the index. Yet macros in name arguments affect both text and index.
+% \item \emph{Name Post-Processing:} Hook macros apply formatting only to the printed form of a name after parsing. See also Section~\ref{sec:Hooksiii}.
% \end{enumerate}
%
% \DescribeMacro{\NamesFormat}
+% Independent ``main-matter'' and ``front-matter'' systems are used to format first and subsequent name uses.
+% \DescribeMacro{\MainNameHook}
+% The main-matter system uses \cmd{\NamesFormat} to post-process first occurrences of names and \cmd{\MainNameHook} for subsequent uses.
% \DescribeMacro{\FrontNamesFormat}
-% \DescribeMacro{\MainNameHook}
+% The front-matter system uses \cmd{\FrontNamesFormat} for first uses and
% \DescribeMacro{\FrontNameHook}
-% Independent\marginpar{\large\raggedleft\textsf{\bfseries 2.5}\strut}
-% ``main-matter'' and ``front-matter'' systems format first and subsequent name uses. The main-matter system uses \cmd{\NamesFormat} to post-process first occurrences of names and \cmd{\MainNameHook} for subsequent uses. The front-matter system uses \cmd{\FrontNamesFormat} for first occurrences and \cmd{\FrontNameHook} for subsequent uses. The \texttt{alwaysformat} option causes only \cmd{\NamesFormat} and \cmd{\FrontNamesFormat} to be used. Section~\ref{sec:tweaks} show how the name reference systems are independent of other data sets in \textsf{nameauth}.\medskip
-%
+% \cmd{\FrontNameHook} for subsequent uses. The \texttt{alwaysformat} option\Version{2.5} causes only \cmd{\NamesFormat} and \cmd{\FrontNamesFormat} to be used (cf. Section~\ref{sec:NamePatterns}).\footnote{The names of these macros may seem poorly conceived. When starting work on this package, this author was ignorant of the breadth of how names might be handled. Designed to meet the needs of a master's thesis, this package has evolved to meet the needs of several published works. At one time, \cmd{\NamesFormat} was the only macro that did any formatting. The rest came later. A certain degree of cargo cult programming arose, to be corrected in the 3.0 series of \textsf{nameauth}.}\medskip
+%
% \DescribeMacro{\NamesActive}
-% \DescribeMacro{\NamesInactive}
-% \cmd{\NamesInactive} and the \texttt{frontmatter} option make names use the front matter system. \cmd{\NamesActive} switches names to the main matter system.\medskip
+% \cmd{\NamesInactive} and the \texttt{frontmatter} option make names use the front matter system. \cmd{\NamesActive} switches names to the main matter system.
+% \DescribeMacro{\NamesInactive}\medskip
%
-% 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
+% These\Info{\cmd{\global}} two macros can be used explicitly as a pair or singly within an explicit local scope. Use \cmd{\global} to force a global effect.\medskip
%
-% These two systems differ only with respect to first and subsequent name uses. We show this here by using different colors. At the start of this manual, we set up the following after defining our custom colors:
-% \begin{quote}\small\setstretch{1.1}
-% |\renewcommand*\FrontNamesFormat[1]{\color{nagreen}\sffamily #1}|\\
-% |\renewcommand*\FrontNameHook[1]{\color{naolive}\sffamily #1}|\\
-% |\renewcommand*\NamesFormat[1]{\color{naviolet}\sffamily #1}|\\
-% |\renewcommand*\MainNameHook[1]{\color{naorange}\sffamily #1}|
+% The two formatting systems are distinct, useful for front matter and main matter, text and footnotes, etc. We show this with different colors:
+% \begin{quote}\small
+% \StartNum
+% \begin{verbatim}
+%\colorlet{nared}{red!50!black}
+%\colorlet{nagreen}{green!35!black}
+%\colorlet{nablue}{blue!50!black}
+%\colorlet{nabrown}{brown!55!black}
+%\renewcommand*\FrontNamesFormat[1]{\color{nared}\sffamily #1}
+%\renewcommand*\FrontNameHook[1]{\color{nagreen}\sffamily #1}
+%\renewcommand*\NamesFormat[1]{\color{nablue}\sffamily #1}
+%\renewcommand*\MainNameHook[1]{\color{nabrown}\sffamily #1}\end{verbatim}
% \end{quote}
-% The two systems are meant to be used in distinct parts of the document, such as front matter and main matter or text and footnotes. The look awkward when used in the same block of text.
%
-% \begin{quote}\small\setstretch{1.1}
-% We switch to the ``front matter'' system:\\
-% \cmd{\NamesInactive}\NamesInactive\\[0.4ex]
-% \begin{tabular}{@{}ll}
+% \begin{center}\small\MyStretch
+% \NamesInactive
+% \begin{tabular}{ll}\toprule
+% Front-matter system: & \cmd{\NamesInactive}\\\midrule
% |\Name[Rudolph]{Carnap}| & \Name[Rudolph]{Carnap}\\
-% |\Name[Rudolph]{Carnap}| & \Name[Rudolph]{Carnap}\\
+% \rowcolor{black!7!white}|\Name[Rudolph]{Carnap}| & \Name[Rudolph]{Carnap}\\
% |\Name[Nicolas]{Malebranche}| & \Name[Nicolas]{Malebranche}\\
-% |\Name[Nicolas]{Malebranche}| & \Name[Nicolas]{Malebranche}\\
-% \end{tabular}\\
+% \rowcolor{black!7!white}|\Name[Nicolas]{Malebranche}| & \Name[Nicolas]{Malebranche}\\\bottomrule
+% \end{tabular}\vfil
%
-% Then we switch back to ``main matter'' system:\\
-% \cmd{\NamesActive}\NamesActive\\[0.4ex]
-% \begin{tabular}{@{}ll}
+% \NamesActive
+% \begin{tabular}{ll}\toprule
+% Main-matter system: & \cmd{\NamesActive}\\\midrule
% |\Name[Rudolph]{Carnap}| & \Name[Rudolph]{Carnap}\\
-% |\Name[Rudolph]{Carnap}| & \Name[Rudolph]{Carnap}\\
+% \rowcolor{black!7!white}|\Name[Rudolph]{Carnap}| & \Name[Rudolph]{Carnap}\\
% |\Name[Nicolas]{Malebranche}| & \Name[Nicolas]{Malebranche}\\
-% |\Name[Nicolas]{Malebranche}| & \Name[Nicolas]{Malebranche}\\
+% \rowcolor{black!7!white}|\Name[Nicolas]{Malebranche}| & \Name[Nicolas]{Malebranche}\\\bottomrule
% \end{tabular}
-% \end{quote}
-%
+% \end{center}
+% \newpage
+%
% \DescribeMacro{\ForceName}
-% Use this prefix macro\marginpar{\large\raggedleft\textsf{\bfseries 3.1}\strut} to force ``first use'' formatting for the next \cmd{\Name}, etc. This will not force a full name reference. One must use the \texttt{formatAKA} option when using this with \cmd{\AKA}, etc. We show this macro in Sections~\ref{sec:tweaks}, \ref{sec:AKA}, and~\ref{sec:Hooksb}.
-% \clearpage
+% Use this prefix macro to force ``first use'' formatting for the next \cmd{\Name}, etc. This will not force a full name reference like \cmd{\ForgetThis}.\Version{3.1} One must use the \texttt{formatAKA} option when using this with \cmd{\AKA}, etc. We show \cmd{\ForceName} in Sections~\ref{sec:NameControl}, \ref{sec:AKA}, and~\ref{sec:Hooksii}.\medskip
%
-% Below\marginpar{\small\raggedleft \texttt{alwaysformat}} we simulate the \texttt{alwaysformat} option by manipulating the package internals. Using first-use hooks will not force full name references.
+% Below\Info{\texttt{alwaysformat}} we simulate the \texttt{alwaysformat} option by manipulating the package internals. Using first-use hooks will not force full name references. This option made more sense when \cmd{\NamesFormat} was the only formatting hook.
% \makeatletter\@nameauth at AlwaysFormattrue\makeatother%
% \ForgetName[M.T.]{Cicero}\ForgetName{Elizabeth, I}%
% \begin{itemize}
-% \item\NamesInactive Using \texttt{alwaysformat} in the front matter will produce: \Name[Albert]{Einstein}, then \Name[Albert]{Einstein}; \Name{Confucius}, then \Name{Confucius}.
+% \item \NamesInactive Using \texttt{alwaysformat} in the front matter will produce: \Name[Albert]{Einstein}, then \Name[Albert]{Einstein}; \Name{Confucius}, then \Name{Confucius}.
% \item \global\NamesActive Using \texttt{alwaysformat} in the main matter will produce: \Name[M.T.]{Cicero}[Marcus Tullius], then \Name[M.T.]{Cicero}[Marcus Tullius]; \Name{Elizabeth, I}, then \Name{Elizabeth, I}.
% \end{itemize}
% \makeatletter\@nameauth at AlwaysFormatfalse\makeatother
%
-% Basic formatting changes can take either the font switch forms or the font command forms. The following are equivalent:
-% \begin{quote}\small\setstretch{1.1}
-% |\renewcommand*\NamesFormat{\bfseries}|\\
-% |\renewcommand*\FrontNamesFormat{\textbf}|
-% \end{quote}
-% The hooks are called in a way that lets them either have one argument or none and keeps changes local via: \cmd{\bgroup}\meta{Hook}|{#1}|\cmd{\egroup}\medskip
+% The internal\Info{hook caveats} hook dispatcher calls the formatting hooks using the pattern \cmd{\bgroup}\meta{Hook}\texttt{\{\#1\}}\cmd{\egroup}. Thus one can use, e.g., \cmd{\itshape} in a local scope. One also can use macros that take one argument (cf. Section~\ref{sec:Hooksiii}), e.g., |\renewcommand*\NamesFormat{\sffamily\color{nablue}\textit}| will create\break the forms \bgroup\renewcommand*\NamesFormat{\sffamily\color{nablue}\textit}\ForgetThis\Einstein\ and \Einstein.\egroup\medskip
%
-% \makeatletter\ignorespaces%
-% \let\@oldfntext\@makefntext\ignorespaces%
-% \long\def\@makefntext#1{\renewcommand*\NamesFormat{\color{naviolet}\scshape}\@oldfntext{#1}}\ignorespaces%
-% \makeatother\ignorespaces%
-% The\marginpar{\small\raggedleft applied to\break footnotes\break\dbend} previous examples illustrate the independent systems or ``species'' of names. Use different ``species'' in different parts of your document. When we do not do this, for example, names in the body text like \Name[John Maynard]{Keynes} affect names in the footnotes.\footnote{You get \Name[John Maynard]{Keynes} from \cmd{\Name}\texttt{[John Maynard]\{Keynes\}} instead of \ForgetThis\Name[John Maynard]{Keynes}.}
-% In this case, \cmd{\MainNameHook} is called instead of \cmd{\NamesFormat} because the name already occurred in the text.
-% \begin{quote}\small\setstretch{1.1}
-% |\makeatletter|{\color{nared}\hfill|% text affects footnotes|}\\
-% |\let\@oldfntext\@makefntext|{\color{nared}\hfill|% restore this later|}\\
-% |\long\def\@makefntext#1{%|{\color{nared}\hfill|% new format; same name system|}\\
-% | \renewcommand*\NamesFormat{\color{naviolet}\scshape}%|\\
-% | \@oldfntext{#1}}|\\
-% |\makeatother|
-% \end{quote}
+% The\Info{applied to\break footnotes} independent systems or ``species'' of names fit independent text elements, like front matter or even footnotes. Names in the body text, such as \Name[John Maynard]{Keynes}, also affect names in the footnotes.\footnote{We have \Name[John Maynard]{Keynes} from \cmd{\Name}\texttt{[John Maynard]\{Keynes\}} instead of \ForgetThis\Name[John Maynard]{Keynes}.}
+% In footnote \arabic{footnote} \cmd{\MainNameHook} is called instead of \cmd{\NamesFormat} because \Name[John Maynard]{Keynes} already had occurred above.
%
-% \makeatletter\ignorespaces%
-% \long\def\@makefntext#1{\renewcommand*\FrontNamesFormat{\color{nagreen}\scshape}\NamesInactive\@oldfntext{#1}\NamesActive}\ignorespaces%
-% \makeatother\ignorespaces%
-% The front-matter system keeps names in the footnotes independent of those in the body text.\footnote{We have the expected \Name[John Maynard]{Keynes}, then \Name[John Maynard]{Keynes}.}
-% You can synchronize the two naming systems if needed; see Section~\ref{sec:tweaks}. Using the front-matter system looks like:
-% \begin{quote}\small\setstretch{1.1}
-% |\makeatletter|{\color{nared}\hfill|% text does not affect footnotes|}\\
-% |\long\def\@makefntext#1{%|{\color{nared}\hfill|% new format; different name system|}\\
-% | \renewcommand*\FrontNamesFormat{\color{nagreen}\scshape}%|\\
-% | \NamesInactive\@oldfntext{#1}\NamesActive%|\\
-% |}\makeatother|
+% If we wanted to format names differently in the footnotes than in the body text, an easy way to do that is to use the front-matter system. For example:
+%
+% \makeatletter
+% \let\@oldfntext\@makefntext
+% \long\def\@makefntext#1{\NamesInactive\@oldfntext{#1}\NamesActive}
+% \makeatother
+% \begin{quote}\small
+% \StartNum
+% \begin{verbatim}
+%\makeatletter
+% \let\@oldfntext\@makefntext
+% \long\def\@makefntext#1{\NamesInactive\@oldfntext{#1}\NamesActive}
+%\makeatother\end{verbatim}
% \end{quote}
-% \makeatletter\let\@makefntext\@oldfntext\makeatother%
-% Now we change footnotes back to normal, for example:
-% \begin{quote}\small\setstretch{1.1}
-% |\makeatletter|\\
-% |\let\@makefntext\@oldfntext|\\
-% |\makeatother|
+%
+% When we create another footnote, we see very different results.\footnote{We have \Name[John Maynard]{Keynes} from \cmd{\Name}\texttt{[John Maynard]\{Keynes\}}, then \Name[John Maynard]{Keynes}.}
+% Footnote \arabic{footnote} shows a completely independent formatting. One also can synchronize the two systems with \cmd{\ForgetThis} and \cmd{\SubvertThis} (Section~\ref{sec:NameDecisions} and its subsections).
+%
+% To finish this example, we change footnotes back to normal:
+% \begin{quote}\small
+% \ContinueNum
+% \begin{verbatim}
+%\makeatletter
+%\let\@makefntext\@oldfntext
+%\makeatother\end{verbatim}
% \end{quote}
-% {\noindent\hbox{}\hfill\large Back to Section~\ref{sec:RefTables} \hfill\hbox{}}
-% \clearpage
+% \makeatletter\let\@makefntext\@oldfntext\makeatother
+%
+% Of cource, one can force long and short forms as needed (Section~\ref{sec:NameControl}). Yet the main point of \textsf{nameauth} is to do the complex work once, then use that in automated fashion for the rest of the document.
+%
+% \ReturnLink
+% \newpage
%
-% \subsubsection{Alternate Format}
-% \label{sec:altformat}
+% \subsection{Alternate Formatting}
+% \label{sec:AltFormat}
% \begingroup\AltFormatActive
%
-% \begin{center}\bfseries Basic Features\end{center}
-% Name post-processing in the formatting hooks (Section~\ref{sec:formatting}) only affects the text. Continental formatting occurs in both the text and in the index. Therefore you need to use control sequences in the naming macro arguments.
+% \noindent The formatting hooks only affect names in the body text. Continental formatting occurs in both the text and in the index. One needs to format those names with macros in the name arguments. The basic way formats names in both text and index. The advanced way allows changes in the text, but keeps the index consistent.
%
-%Section~\ref{sec:accents} showed us that changing a control sequence will change a name, even if one cannot see the difference. Those changes must be consistent in the index to avoid spurious entries. Here is how we address that.
+% \subsubsection{Basic Features}
+% \label{sec:AltBasic}
%
-% We use \cmd{\AltFormatActive}\marginpar{\large\raggedleft\textsf{\bfseries 3.1}\strut} at the start of this section to enable alternate formatting and switch it ``on.'' We begin with basic examples that do not change. We then move to advanced features that allow change in the text.
+%Section~\ref{sec:ErrorProt} showed us that changing a control sequence will change the index entry of a name, even if one cannot see differences on the page. Alternate formatting helps one avert spurious index entries.
%
-% If made the \meta{SNN} argument of a name macro,\marginpar{\small\raggedleft how to break stuff\break\dbend} |\textsc{a Name, Problem}| will cause an error due to using commas as suffix delimiters. We fix that by using: |\textsc{a Name}, \textsc{Problem}|.
+% Using,\Warn{} e.g., \cmd{\Name\{}\cmd{\textsc\{a Name, Problem\}\}} will halt \LaTeX\ because the comma tries to break \cmd{\textsc} and its argument into two elements. We fix that with: \cmd{\Name\{}\cmd{\textsc\{a Name\},} \cmd{\textsc\{Problem\}\}}. Yet \cmd{\CapThis} still needs alternate formatting, given that \cmd{\textsc} is robust (Section~\ref{sec:AltAdvanced}).\footnote{Pre-version 3.1 methods of Continental formatting should work if one uses the \texttt{altformat} option or \cmd{\AltFormatActive} to protect against the default behavior of \cmd{\CapThis}.}\medskip
%
-% \cmd{\CapThis} still can break |\textsc{a Name}, \textsc{Problem}| under the normal formatting regime. Alternate formatting prevents this by suppressing the normal effects of \cmd{\CapThis}.
+% \DescribeMacro{\AltFormatActive}
+% Both the \texttt{altformat} option and \cmd{\AltFormatActive} enable and activate alternate formatting. Both cause \cmd{\CapThis} to work via \cmd{\AltCaps} instead of the normal way. \cmd{\AltFormatActive} countermands \cmd{\AltFormatActive*}.
+% \begin{itemize}
+% \item \emph{Enabled} means that the alternate formatting mechanism inhibits the normal behavior of \cmd{\CapThis}.
+% \item \emph{Activated} means that \cmd{\textSC} and other alternate formatting macros (see below) format their arguments. When deactivated, they do not format their arguments.
+% \end{itemize}
%
-% Previous methods to get Continental formatting still should work. Simply use the \texttt{altformat} option or \cmd{\AltFormatActive} to add protection against \cmd{\CapThis}.\medskip
+% At\Version{3.1} the start of this section we used \cmd{\AltFormatActive} to enable alternate formatting and ``switch on'' the alternate formatting macros. That is the basic set of conditions for the simple use of alternate formatting. \medskip
%
-% \DescribeMacro{\AltFormatActive}
-% Both the \texttt{altformat} option and \cmd{\AltFormatActive} globally enable alternate formatting and switch the formatting macros ``on.'' It will change the effects of \cmd{\AltFormatActive*}. It causes \cmd{\CapThis} only to work via \cmd{\AltCaps}.\medskip
-%
% \DescribeMacro{\AltFormatActive*}
-% When one wants to enable alternate formatting but keep the formatting macros in the ``off'' state, use the starred form \cmd{\AltFormatActive*}. It can change the effects of both the \texttt{altformat} option and \cmd{\AltFormatActive}. It causes \cmd{\CapThis} only to work via \cmd{\AltCaps}.\medskip
+% The starred form \cmd{\AltFormatActive*} enables alternate formatting but deactivates the special formatting macros, preventing them from changing their arguments. It countermands both the \texttt{altformat} option and \cmd{\AltFormatActive}. It causes \cmd{\CapThis} only to work via \cmd{\AltCaps}.\medskip
%
% \DescribeMacro{\AltFormatInactive}
-% When one needs to switch alternate formatting ``off'' and deactivate its mechanism, use \cmd{\AltFormatInactive} to revert globally to standard formatting and the normal function of \cmd{\CapThis}.
-% \begin{center}\small
-% \begin{tabular}{lcc}\toprule
-% & Enabled & Switched ``On''\\\midrule
+% To both disable alternate formatting and deactivate the alternate formatting macros, use \cmd{\AltFormatInactive}. This reverts globally to standard formatting and the normal function of \cmd{\CapThis}.
+%
+% \begin{center}
+% \begin{tabular}{lcc}
+% & Enabled & Activated\\\midrule
% \cmd{\AltFormatActive} & \YES & \YES\\
% \cmd{\AltFormatActive*} & \YES & \NO\\
% \cmd{\AltFormatInactive} & \NO & \NO\\\bottomrule
@@ -1834,19 +2626,25 @@
% \end{tabular}
% \end{center}
%
+% On the next page we describe the formatting macros that are built in to \textsf{nameauth} in order to use the basic features of alternate formatting and provide a foundation for the advanced features. One should use \cmd{\PretagName} (Section~\ref{sec:IndexSort}) to sort the related index entries for these names.
+% \newpage
+%
% \DescribeMacro{\textSC}
+% Continental formatting can be as simple as using the short macro \cmd{\textSC}. Three other macros also implement alternate formatting.
% \DescribeMacro{\textIT}
+% These macros make changes only when alternate formatting is active.
% \DescribeMacro{\textBF}
+% We sort the index entry with \cmd{\PretagName} and demonstrate the formatting.
% \DescribeMacro{\textUC}
-% Continental formatting can be as simple as using the short macro \cmd{\textSC}. Three other macros also implement alternate formatting. These macros make changes only when alternate formatting is active. We sort the index entry and demonstrate the formatting activated by \cmd{\AltFormatActive}.
-% \begin{quote}\small\setstretch{1.1}
-% |\PretagName[Greta]{\textSC{Garbo}}{Garbo, Greta}|\\
-% |\PretagName[Ada]{\textIT{Lovelace}}{Lovelace, Ada}|\\
-% |\PretagName[Charles]{\textBF{Babbage}}{Babbage, Charles}|\\
-% |\PretagName{\textUC{Tokugawa}, Ieyasu}{Tokugawa Ieyasu}|
-% \end{quote}
-% \clearpage
-% \begin{quote}\small\setstretch{1.1}
+% \begin{quote}\small
+% \StartNum
+% \begin{verbatim}
+%\PretagName[Greta]{\textSC{Garbo}}{Garbo, Greta}
+%\PretagName[Ada]{\textIT{Lovelace}}{Lovelace, Ada}
+%\PretagName[Charles]{\textBF{Babbage}}{Babbage, Charles}
+%\PretagName{\textUC{Tokugawa}, Ieyasu}{Tokugawa Ieyasu}\end{verbatim}
+%
+% \smallskip\MyStretch
% |\Name[Greta]{\textSC{Garbo}}|\dotfill \Name[Greta]{\textSC{Garbo}}; \Name[Greta]{\textSC{Garbo}}\\
% |\Name[Ada]{\textIT{Lovelace}}|\dotfill \Name[Ada]{\textIT{Lovelace}}; \Name[Ada]{\textIT{Lovelace}}\\
% |\Name[Charles]{\textBF{Babbage}}|\dotfill \Name[Charles]{\textBF{Babbage}}; \Name[Charles]{\textBF{Babbage}}\\
@@ -1853,1160 +2651,1290 @@
% |\Name{\textUC{Tokugawa}, Ieyasu}|\dotfill \Name{\textUC{Tokugawa}, Ieyasu}; \Name{\textUC{Tokugawa}, Ieyasu}
% \end{quote}
%
-% Formatting\marginpar{\small\raggedleft\dbend} also occurs in the index using this method. Any time that a naming macro writes to the index, the flags that control these formatting macros must be in the same state, or else you will get spurious index entries.
+% Since we switch to Latin Modern Sans in the formatting hooks, the switch to small caps in \Name[Greta]{\textSC{Garbo}} forces a substitution to Latin Modern Roman. This action varies with the font being used.
+%
+% Using basic alternate formatting, these macros \emph{always format their arguments} with the \texttt{altformat} option or \cmd{\AltFormatActive}. Likewise, they \emph{never format their arguments} when \cmd{\AltFormatActive*} is used. To change the formatting of the name arguments, one must use the advanced features. Whenever\Warn{} a naming macro writes to the index, the formatting macros must be in the same Boolean state to avoid spurious index entries. The next section explains more.
%
-% A comma\marginpar{\small\raggedleft comma karma} delimiter splits the mandatory macro argument into a root and an affix. To avoid errors, format the name and suffix separately. The example below gives us \JRIII, then \JRIII.
-% \begin{quote}\footnotesize\setstretch{1.1}
-% |\PretagName[John David]{\textSC{Rockefeller},\textSC{III}}%|\\
-% | {Rockefeller, John David 3}|\\
-% |\begin{nameauth}|\\
-% | \< JRIII & John David & \textSC{Rockefeller},\textSC{III} & >|\\
-% |\end{nameauth}|
+% As with normal formatting, \cmd{\CapName} interacts with alternate formatting only in the text. Thus \CapName\Name*[Greta]{\textSC{Garbo}} instead of \Name[Greta]{\textSC{Garbo}}. \cmd{\RevComma} likewise gives \RevComma\Name*[Ada]{\textIT{Lovelace}}. \cmd{\RevName} produces \RevName\Name*{\textUC{Tokugawa}, Ieyasu}.\medskip
+%
+% A comma\Info{comma karma} delimiter splits the mandatory macro argument into a root and an affix. To avoid errors, format the name and suffix separately.
+% \begin{quote}\small
+% \StartNum
+% \begin{verbatim}
+%\PretagName[John David]{\textSC{Rockefeller},\textSC{III}}
+% {Rockefeller, John David 3}
+%\PretagName{\textUC{Fukuyama}, Takeshi}{Fukuyama Takeshi}
+%\begin{nameauth}
+% \< JRIII & John David & \textSC{Rockefeller},\textSC{III} & >
+% \< Fukuyama & & \textUC{Fukuyama}, Takeshi & >
+% \< OFukuyama & & \textUC{Fukuyama} & Takeshi >
+%\end{nameauth}\end{verbatim}
% \end{quote}
%
-% For non-Western names, the new syntax and the older syntax produce the same control sequence that identifies names. Again we are careful to avoid putting the comma delimiter within a container macro.
-% \begin{quote}\small\setstretch{1.1}
-% |\PretagName{\textUC{Fukuyama}}[Takeshi]{Fukuyama Takeshi}|\\
-% |\begin{nameauth}|\\
-% | \< Fukuyama & & \textUC{Fukuyama}, Takeshi & >|\\
-% | \< OFukuyama & & \textUC{Fukuyama} & Takeshi >|\\
-% |\end{nameauth}|
-% \end{quote}
-% \begin{center}\small\setstretch{1.1}
+% From above we get \JRIII, then \JRIII. For non-Western names, the new syntax and the older syntax produce the same control sequence that identifies names. Again we are careful to avoid putting the comma delimiter within a container macro.
+% \begin{center}\small\MyStretch
% \begin{tabular}{rl}\toprule
% |\Fukuyama| & \Fukuyama\\
-% |\OFukuyama| & \OFukuyama\\
+% \rowcolor{black!7!white}|\OFukuyama| & \OFukuyama\\
% |\LOFukuyama| & \LOFukuyama\\
-% |\Fukuyama| & \Fukuyama\\\bottomrule
+% \rowcolor{black!7!white}|\Fukuyama| & \Fukuyama\\\bottomrule
% \end{tabular}
% \end{center}
%
-% Only the new syntax allows one to use alternate names in the text. For example, |\LFukuyama[Sensei]| \LFukuyama[Sensei] wrote \emph{Nihon Fukuin R\=uteru Ky\=okai Shi} in 1954, after studying in the US in the 1930s. The old syntax |\LOFukuyama[Sensei]|, which we avoid, yields \LOFukuyama[Sensei].
+% Only the new syntax allows one to use alternate names in the text (Section~\ref{sec:FName}). For example, ``|\LFukuyama[Sensei]| \LFukuyama[Sensei] wrote \textit{Nihon Fukuin R\=uteru Ky\=okai Shi} in 1954, after studying in the US in the 1930s.''
+% \newpage
%
-% \begin{center}\bfseries Advanced Features\end{center}
-% A more complex version of alternate formatting allows us to make format changes in the text while keeping format consistent in the index. We use \cmd{\textSC}, \cmd{\textIT}, \cmd{\textBF}, and \cmd{\textUC} with \cmd{\noexpand} and special triggering macros. Using \cmd{\noexpand} is crucial because we do not want to have the macros expand at the wrong time, giving us the wrong results. Thus:
-% \begin{quote}\small\setstretch{1.1}
-% |\Name[Martin]{\textSC{Luther}}|\hfill \emph{basic}\\
-% |\Name[Martin]{\noexpand\textSC{Luther}}|\hfill \emph{advanced}
+% \subsubsection{Advanced Features}
+% \label{sec:AltAdvanced}
+%
+% \noindent A more complex version of alternate formatting allows us to make formatting and other changes in the text while keeping the index consistent. In order to do this, we will be using \cmd{\textSC}, \cmd{\textIT}, \cmd{\textBF}, and \cmd{\textUC} with \cmd{\noexpand} and special triggering macros. Below we briefly see the difference:
+% \begin{center}\small\MyStretch
+% \begin{tabular}{ll}
+% |\Name[Martin]{\textSC{Luther}}| & {\color{nared}|%| \textit{basic alternate formatting}}\\
+% |\Name[Martin]{\noexpand\textSC{Luther}}| & {\color{nared}|%| \textit{advanced version}}\\
+% \end{tabular}
+% \end{center}
+% The reason for this approach is that indexing operations occur outside the formatting hooks, never within the hooks, and \cmd{\noexpand} keeps the two separate.
+%
+% \ifDoTikZ
+% \begin{tcolorbox}[colback=white,colframe=nared]
+% \centering Using \cmd{\noexpand} is key to consistent index entries.
+% \end{tcolorbox}\bigskip
+% \else
+% \begin{center}\bfseries Using \cmd{\noexpand} is key to consistent index entries.\end{center}
+% \fi
+%
+% \cmd{\CapThis}\DescribeMacro{\AltCaps}\ causes \cmd{\AltCaps} to cap its argument only in a formatting hook. It is enabled whenever alternate formatting is enabled. \cmd{\AltCaps} works independently of \cmd{\AltOn} and \cmd{\AltOff}:
+% \begin{quote}
+% \fbox{\mystrut\ \cmd{\noexpand}\cmd{\AltCaps}\marg{Arg} }
% \end{quote}
+% In the example below we redefine \cmd{\MainNameHook} to suppress formatting:
+% \renewcommand*\MainNameHook{\color{nabrown}\sffamily\AltOff}
+% \begin{quote}\small
+% \StartNum
+% \begin{verbatim}
+%\renewcommand*\MainNameHook%
+% {\color{nabrown}\sffamily\AltOff}% we match the manual
%
-% \renewcommand*\MainNameHook{\color{naorange}\sffamily\AltOff}
-% Remember |\textsc{a Name}, \textsc{Problem}|? With a little work adding the alternate formatting macros and \cmd{\noexpand} we get:
-% \begin{quote}\footnotesize\setstretch{1.1}
-% |\noexpand\textSC{\noexpand\AltCaps{a}| |Name},| |\noexpand\textSC{Problem}}|
+%\IndexInactive
+%What's in a \Name{\noexpand\AltCaps{a} Name}?
+%\CapThis\Name{\noexpand\AltCaps{a} Name} smells not,
+%but a rose does. We avoid \Name{
+% \noexpand\textSC{\noexpand\AltCaps{a} Name},
+% \noexpand\textSC{Problem}}.
+%\CapThis\Name*{
+% \noexpand\textSC{\noexpand\AltCaps{a} Name},
+% \noexpand\textSC{Problem}} will not occur,
+% even if it smells like a rose.\end{verbatim}
+%
+% \smallskip\IndexInactive
+% What's in a \Name{\noexpand\AltCaps{a} Name}?
+% \CapThis\Name{\noexpand\AltCaps{a} Name} smells not,
+% but a rose does. We avoid \Name{
+% \noexpand\textSC{\noexpand\AltCaps{a} Name},
+% \noexpand\textSC{Problem}}.
+% \CapThis\Name*{
+% \noexpand\textSC{\noexpand\AltCaps{a} Name},
+% \noexpand\textSC{Problem}} will not occur,
+% even if it smells like a rose.
% \end{quote}
-% With an additional change to the formatting hooks, whenever alternate formatting is active, the naming macros will avoid \SkipIndex\Name{\noexpand\textSC{\noexpand\AltCaps{a} Name}, \noexpand\textSC{Problem}}. \SkipIndex\CapThis\Name*{\noexpand\textSC{\noexpand\AltCaps{a} Name}, \noexpand\textSC{Problem}} will not occur even with \cmd{\CapThis} and \SkipIndex\Name{\noexpand\textSC{\noexpand\AltCaps{a} Name}, \noexpand\textSC{Problem}} will work just fine. We suppressed the index entries that would have been created here.
%
-%The macros below work together for advanced alternate formatting.
-% \begin{enumerate}\small
-% \item The macro\DescribeMacro{\AltOff}\ \cmd{\AltOff} does nothing except when called in a formatting hook, where it ``switches off'' alternate formatting. When that happens, \cmd{\textSC}, \cmd{\textBF}, \cmd{\textIT}, and \cmd{\textUC} do nothing. This macro works with the \texttt{altformat} option and when \cmd{\AltFormatActive} has been called.
+% Like\DescribeMacro{\AltOff}\ a manual automobile clutch and gearbox, \cmd{\AltOff} deactivates \cmd{\textSC}, \cmd{\textBF}, \cmd{\textIT}, and \cmd{\textUC} only in a formatting hook.\medskip
%
-% \item The macro\DescribeMacro{\AltOn}\ \cmd{\AltOon} does nothing except when called in a formatting hook, where it ``switches on'' alternate formatting. When that happens, \cmd{\textSC}, \cmd{\textBF}, \cmd{\textIT}, and \cmd{\textUC} perform their changes. This macro works when \cmd{\AltFormatActive*} has been called.
+% \cmd{\AltOn}\DescribeMacro{\AltOn}\ activates \cmd{\textSC}, \cmd{\textBF}, \cmd{\textIT}, and \cmd{\textUC} only in a formatting hook. To summarize:
+%
+% \begin{itemize}
+% \item \cmd{\AltFormatActive} and \cmd{\AltFormatActive*} set global states.
+% \item \cmd{\AltFormatActive} causes formatting in the text and index, as well as forcing the use of \cmd{\AltCaps}.
+% \item With \cmd{\AltFormatActive*} inhibits formatting, but still requires one to use \cmd{\AltCaps}.
+% \item \cmd{\AltOn} and \cmd{\AltOff} change local state only in the formatting hooks.
+% \item The user adds \cmd{\AltOn} and \cmd{\AltOff} to the hooks as needed.
+% \item The actual formatting happens via macros in the name arguments.
+% \end{itemize}
+% \newpage
+%
+% Keeping the \cmd{\MainNameHook} example above, we have:
+% \begin{quote}\small
+% \StartNum
+% \begin{verbatim}
+%\begin{nameauth}
+% \< Luth & Martin & \noexpand\textSC{Luther} & >
+%\end{nameauth}
+%\PretagName[Martin]{\noexpand\textSC{Luther}}{Luther, Martin}\end{verbatim}
+% \end{quote}
%
-% \item Using \cmd{\noexpand} is the golden key (\emph{clavis aurea}) that lets us expand formatting changes only when desired. It enables this kind of formatting hook, which we must implement:
+% We first mention \cmd{\Luth} \Luth. Then again, \cmd{\Luth} \Luth. Medieval Italian differs from modern Italian with respect to particles. Below the index entry should be ``\ShowIdxPageref*[Catherine \noexpand\AltCaps{d}e']{\noexpand\textSC{Medici}}\,'' instead of ``\ShowIdxPageref*[Catherine]{de~\textSC{Medici}}'':
% \begin{quote}\small
-% |\renewcommand*\MainNameHook{\AltOff}|
+% \StartNum
+% \begin{verbatim}
+%\begin{nameauth}
+% \< Cath & Catherine \noexpand\AltCaps{d}e'
+% & \noexpand\textSC{Medici} & >
+%\end{nameauth}
+%\PretagName[Catherine \noexpand\AltCaps{d}e']
+% {\noexpand\textSC{Medici}}{Medici, Catherine de}\end{verbatim}
% \end{quote}
-% \item Since\DescribeMacro{\AltCaps}\ the normal effects of \cmd{\CapThis} are disabled \cmd{\AltCaps} provides an alternate means to this end. It capitalizes its argument in braces |{| |}| when it is used in a macro hook and triggered by \cmd{\CapThis}.
-% \end{enumerate}
+%This gives us \Cath\ and \Cath. To get \ForceName\CapThis\LCath[\noexpand\AltCaps{d}e'] and \CapThis\LCath[\noexpand\AltCaps{d}e'] in the text, use |\CapThis\LCath[\noexpand\AltCaps{d}e']|.\medskip
%
-% Since we used \cmd{\AltFormatActive} in this section it has triggered formatting by default. We only need to change \cmd{\MainNameHook} and \cmd{\FrontNameHook} because we want to have formatting in first uses but suppress it in subsequent uses. Below we match the style of this manual with the redesign of the formatting hooks and we include a sample text:
-% \begin{quote}\small\setstretch{1.1}
-% |\renewcommand*\MainNameHook[1]%|\\
-% | {\color{naorange}\sffamily\AltOff}|\medskip
+% \phantomsection
+% \label{page:Inflections}
+% We\Info{name inflections\break\dbend} can use alternate formatting for grammatical inflections (cf. Section~\ref{sec:Hooksiii}). We tell the same set of lies that we did on page~\pageref{page:Sobriquets}. \cmd{\DoGentrue} occurs only in the formatting hook, thereby keeping the index entries consistent:\footnote{A copy of this example is in \texttt{examples.tex}, collocated with this manual.}
%
-% With the 500th anniversary of the Reformation in 2017, studies should focus both on the life of \Luth\ and on the social, religious, and political factors of the time that influenced \Luth.
-% \end{quote}
+% \newif\ifGenitive
+% \newif\ifDoGen
+% \renewcommand*\NamesFormat[1]{\ifGenitive\DoGentrue\fi#1\global\Genitivefalse}
+% \renewcommand*\MainNameHook[1]{\ifGenitive\DoGentrue\fi\AltOff#1\global\Genitivefalse}
+% \newcommand\JEFF{\ifDoGen\textSC{Jefferson's}\else\textSC{Jefferson}\fi}
+% \begin{quote}\small
+% \StartNum
+% \begin{verbatim}
+%\newif\ifGenitive
+%\newif\ifDoGen
+%\renewcommand*\NamesFormat[1]
+% {\ifGenitive\DoGentrue\fi#1\global\Genitivefalse}
+%\renewcommand*\MainNameHook[1]
+% {\ifGenitive\DoGentrue\fi\AltOff#1\global\Genitivefalse}
+%\begin{nameauth}
+% \< Jeff & Thomas & \noexpand\JEFF & >
+%\end{nameauth}
+%\PretagName[Thomas]{\noexpand\JEFF}{Jefferson, Thomas}
+%\TagName[Thomas]{\noexpand\JEFF}{, pres.|hyperpage}
+%\newcommand\JEFF{\ifDoGen\textSC{Jefferson's}\else
+% \textSC{Jefferson}\fi}
%
-% We show alternate formatting and capitalization in the text, here being mindful of how medieval Italian differs from modern Italian:
-% \begin{quote}\small\setstretch{1.1}
-% |\begin{nameauth}|\\
-% | \< Cath & Catherine \noexpand\AltCaps{d}e'|\\
-% | & \noexpand\textSC{Medici} & >|\\
-% |\end{nameauth}|\medskip
+%Consider \Genitivetrue\Jeff\ legacy. More on \Jeff\ later.
+%\Genitivetrue\Jeff\ reputation has declined in recent decades.\end{verbatim}
%
-%This gives us \Cath\ and \Cath. To get either \ForceName\CapThis\LCath[\noexpand\AltCaps{d}e'] or \CapThis\LCath[\noexpand\AltCaps{d}e'], use |\CapThis\LCath[\noexpand\AltCaps{d}e']|.
+% \smallskip
+% Consider \Genitivetrue\Jeff\ legacy. More on \Jeff\ later.
+% \Genitivetrue\Jeff\ reputation has declined in recent decades.
% \end{quote}
-%
-% Sections~\ref{sec:formatting} and~\ref{sec:Hooksc} have more on these topics. We resume normal formatting with \cmd{\AltFormatInactive}. We do not use alternately-formatted names in the normal regime in order to prevent spurious index entries.
+%
+% For highly inflected languages, this would require two Boolean flags per case and nested conditional statements. Now we resume normal formatting with \cmd{\AltFormatInactive} and we do not use the names in this section outside of it.\footnote{In a \texttt{dtx} file it is best to put the \texttt{nameauth} environment, \cmd{\PretagName}, and \cmd{\TagName} macros in the driver section, especially when names contain macros.}
% \AltFormatInactive\endgroup
+%
+% \ReturnLink
+% \newpage
%
-% {\medskip\noindent\hbox{}\hfill\large Back to Section~\ref{sec:RefTables} \hfill\hbox{}}
-% \clearpage
-%
% \subsection{Indexing Macros}
%
-% Current\marginpar{\large\raggedleft\textsf{\bfseries 3.0}\strut} versions of \textsf{nameauth} offer greater flexibility with indexing but still implement some error protection. We cover the indexing macros here because the later macros in this manual build on many of their concepts. Some aspects of indexing go beyond the scope of this package.\footnote{For example, search for ``memoir babel index'' at \url{http://tex.stackexchange.com}.}
+% \subsubsection[Entries \& Control]{Index Entries and Control}
+% \label{sec:IndexControl}
%
-% \subsubsection{Indexing Control}
-% \label{sec:indexctrl}
+% \DescribeMacro{\IndexName}
+% Both package users and the naming macros themselves use this macro to create index entries. It prints nothing in the body text:
+% \begin{quote}
+% \fbox{\mystrut\ \cmd{\IndexName}\oarg{FNN}\marg{SNN|,| Affix}\oarg{Alternate} }
+% \end{quote}
%
+% If \meta{FNN} is present, it ignores \meta{Alternate} for Western and ``native'' Eastern name forms. If \meta{FNN} is absent, \cmd{\IndexName} may use the current or obsolete non-Western syntax (Section~\ref{sec:Obsolete}). Indexing follows [\hyperlink{Mulvany}{Mulvany}, 152--82].
+%
+% If \cmd{\IndexInactive} or the \texttt{noindex} option are used, this macro does nothing until \cmd{\IndexActive} appears. Additionally, it will not create index entries for cross-references made by \cmd{\IndexRef} and \cmd{\AKA}. It will not index names excluded by \cmd{\ExcludeName}. This provides some error protection for professional indexing.
+%
+% \cmd{\IndexName} and \cmd{\IndexRef} call \cmd{\@nameauth at Index}, a macro that assembles an index entry from the sort tag (Section~\ref{sec:IndexXref}), name arguments, and index tag (Section~\ref{sec:IndexTag}).
+% Different standards exist for index entries and cross-references. Check with your publisher, style guide, and docs for \textsf{xindy} and \textsf{makeindex}.\medskip
+%
% \DescribeMacro{\IndexActive}
+% The \texttt{noindex} option deactivates the indexing function of this package until \cmd{\IndexActive} enables indexing.
% \DescribeMacro{\IndexInactive}
-% Using the \texttt{noindex} option deactivates the indexing function of this package until \cmd{\IndexActive} occurs. Another macro, \cmd{\IndexInactive}, will deactivate indexing again. These can be used throughout the document. \cmd{\ExcludeName} and \cmd{\IncludeName} do not deactivate indexing, but they leverage the cross-referencing system to prevent page entries.\medskip
+% Another macro, \cmd{\IndexInactive}, will deactivate indexing again. These can be used throughout the document. {\bfseries \cmd{\IndexInactive} suppresses index sorting and tagging macros.} Compare the use of macros \cmd{\ExcludeName} and \cmd{\IncludeName} (Section~\ref{sec:IndexXref}).\medskip
%
-% 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.
+% \DescribeMacro{\IndexProtect}
+% Both the core name engine \cmd{\@nameauth at Name} and \cmd{\AKA} have locks that prevent them from being re-entrant.\VersionWarn{3.3} This protects the text. Usually, one does not put naming macros in the index. Just in case, now one can use \cmd{\IndexProtect} right before \cmd{\printindex} to prevent \textsf{nameauth} macros from producing any output.
%
-% \begin{center}\bfseries \cmd{\IndexInactive} suppresses index sorting and tagging macros.\end{center}
+% This example shows the difference between the effects of the older and newer approaches. We use the tag \S\ in this manual's index, but not below:
+% \begin{center}\small
+% \begin{tabular}{llll}\toprule
+% \bfseries Macro & \bfseries Text & \bfseries \texttt{.ind} file & \bfseries Index\\\midrule
+% no protection\\
+% |\Name{foo\Name{bar}}| & \Name{foo\Name{bar}} & |\item foo\Name {bar}| & foo{\NamesFormat bar}\\
+% (next iteration adds) \(\rightarrow\) & & |\item bar| & bar\\
+% \rowcolor{black!7!white}\cmd{\IndexProtect} & & & \\
+% \rowcolor{black!7!white}|\Name{foo\Name{bar}}| & \Name{foo\Name{bar}} &
+% |\item foo\Name {bar}| & foo\\
+% \rowcolor{black!7!white}(no further output results) & & & \\\bottomrule
+% \end{tabular}
+% \end{center}
%
+% \cmd{\IndexActive}\Info{\cmd{\global}} and \cmd{\IndexInactive} can be used as a pair or singly within a group. These macros override any prefix macros. \cmd{\IndexProtect} also can be used in a local scope. Use \cmd{\global} with these macros to force a global effect.\medskip
+%
% \DescribeMacro{\SkipIndex}
-% The prefix\marginpar{\large\raggedleft\textsf{\bfseries 3.1}\strut} macro \cmd{\SkipIndex} will suppress indexing for just one instance of a naming or cross-referencing macro. It will not alter name forms or formatting. For example, |\SkipIndex\Name[Monty]{Python}| produces \SkipIndex\Name[Monty]{Python} in the text with no index entry. The same thing again yields \SkipIndex\Name[Monty]{Python}. Both \cmd{\IndexName} and \cmd{\IndexRef} ignore \cmd{\SkipIndex} and allow its effect, with other prefix macros, to ``pass through'' to the next naming macro.\medskip
+% The prefix macro \cmd{\SkipIndex} will suppress indexing for just one instance of a naming or cross-referencing macro.\VersionWarn{3.1} It will not alter name forms or formatting. For example, |\SkipIndex\Name[Monty]{Python}| produces \SkipIndex\Name[Monty]{Python} in the text with no index entry. The same thing again yields \SkipIndex\Name[Monty]{Python}. Since prefix macros are meant for macros that print a name, both \cmd{\IndexName} and \cmd{\IndexRef} ignore \cmd{\SkipIndex} and allow the Boolean flags set by the prefix macros, to ``pass through'' to the next naming macro. That may seem counter-intuitive.
+% \newpage
%
% \DescribeMacro{\JustIndex}
-% This prefix macro makes \cmd{\Name} and \cmd{\Fname} act just like a call to \cmd{\IndexName} one time only. That means, like \cmd{\IndexName}, the effects of all the other prefix macros will ``pass through'' to the next naming macro. Both \cmd{\AKA} and \cmd{\PName} ignore and reset the flag controlled by this macro.
+% This prefix macro makes \cmd{\Name}, \cmd{\Name*}, \cmd{\Fname}, and the shorthands act like a one-time call to \cmd{\IndexName}.\VersionWarn{3.3} Flags set by the prefix macros ``pass through'' to the next naming macro except these three: \cmd{\@nameauth at JustIndexfalse} (obviously), but also \cmd{\@nameauth at FullNamefalse} and \cmd{\@nameauth at FirstNamefalse}.
+% \begin{itemize}
+% \item Both \cmd{\AKA} and \cmd{\PName} ignore and reset the flag set by \cmd{\JustIndex}.
+% \item \cmd{\SkipIndex} \cmd{\JustIndex} \cmd{\Name\{A\}} \cmd{\Name\{B\}} is just like \cmd{\JustIndex} \cmd{\Name\{A\}} \cmd{\SkipIndex} \cmd{\Name\{B\}}. See the table on page~\pageref{page:Priorities}.
+% \item Version 3.3 eliminates the undocumented behavior that used to occur when not using, e.g., \cmd{\JustIndex}\cmd{\Wash}. Now any version will do:\smallskip\\
+% \bgroup\small\begin{tabular}{ll@{ }ll@{ }l}
+% |\JustIndex\LWash \Wash| & old: & \makeatletter\@nameauth at OldPasstrue\makeatother\JustIndex\LWash \Wash & new: & \Wash\\
+% |\JustIndex\SWash \Wash| & old: & \makeatletter\@nameauth at OldPasstrue\makeatother\JustIndex\SWash \Wash & new: & \Wash\\
+% \end{tabular}\egroup
+% \item The \texttt{oldpass} option restores the old behavior. Cf. Section~\ref{sec:Customize}.
+% \end{itemize}
%
-% All the changes\marginpar{\small\raggedleft\dbend} made by the prefix macros pass through |\JustIndex\|\meta{$name_1$} to the next instance of \cmd{\Name}, etc., |\|\meta{$name_2$}. This is exactly as if you called \cmd{\IndexName}. This makes |\JustIndex\|\meta{$name_1$}|\SkipIndex\|\meta{$name_2$} equivalent to |\SkipIndex\JustIndex\|\meta{$name_1$}|\|\meta{$name_2$}.\medskip
+% \ReturnLink
%
-% Now we use tricks from Sections~\ref{sec:IndexName}, \ref{sec:IndexXref} and~\ref{sec:tweaks} to modify name forms, formatting, and indexing. Instead of using \cmd{\SkipIndex}, \cmd{\IndexInactive}, and \cmd{\IndexActive}, here we let the name exclusion mechanism protect a name:
-% \begin{quote}\small\setstretch{1.1}
-% |\begin{nameauth}|\\
-% | \< Washs & George & Washington's & >|\\
-% |\end{nameauth}|\\
-% |\ExcludeName[George]{Washington's}|
+% \subsubsection{Cross-References}
+% \label{sec:IndexXref}
+%
+% \DescribeMacro{\IndexRef}
+% This macro emerged from the macros in Section~\ref{sec:AKA}. By default, \cmd{\IndexRef} creates a \textit{see} reference\Version{3.0} from the name defined by its first three arguments to the target in its final argument:
+% \begin{quote}\small
+% \fbox{\mystrut\ \cmd{\IndexRef}\oarg{FNN}\marg{SNN|,| Affix}\oarg{Alternate}\marg{reference target} }
% \end{quote}
-% |\Washs| and |\Washs| produce \Washs\ and \Washs, but no index entries. Use |\JustIndex\Wash|\JustIndex\Wash\ as needed. Remember that one only needs this trick when using something other than default formatting. Otherwise just put an inflected ending after the name macro.
%
-% {\medskip\noindent\hbox{}\hfill\large Back to Section~\ref{sec:RefTables} \hfill\hbox{}}
-% \clearpage
+% The name parsing is like \cmd{\IndexName}, except that the final argument is neither parsed nor checked if a target entry exists. For example, to cross-reference ``Sun King'' with \Name*{Louis, XIV} use: \cmd{\IndexRef}\texttt{\{Sun King\}\{Louis XIV\}}\IndexRef{Sun King}{Louis XIV}.
%
-% \subsubsection{Index Entries}
-% \label{sec:IndexName}
+% When\Warn{} \cmd{\IndexRef} calls \cmd{\@nameauth at Index}, a preexisting tag of the form \meta{some text}\texttt{\textbar}\meta{some macro} is reduced to \meta{some text}. One cannot tag an extant cross-reference, but one can tag a name, then later create a \textit{see also} reference. For related warnings activated by the \texttt{verbose} option, see Section~\ref{sec:ErrorProt}.
%
-% \DescribeMacro{\IndexName}
-% The naming macros (\cmd{\Name}, etc.) use this macro to create index entries. You can use it too. It prints nothing in the body text. The syntax is:
-% \begin{quote}\small
-% \cmd{\IndexName}\oarg{FNN}\marg{SNN}\oarg{Alternate names}
+% Next we look at variant names and cross-references. Some can be handled with the \meta{Alternate} argument. Others require more work to implement (Section~\ref{sec:VarNames}).
+% \begin{itemize}
+% \item Variant names potentially can have page numbers in index entries. Cross-references cannot have page numbers.
+% \item |\DropAffix\ForgetThis\Name[J.E.]{Carter, Jr.}[Jimmy]| gives a variant name: \DropAffix\ForgetThis\Name[J.E.]{Carter, Jr.}[Jimmy] indexed under ``\ShowIdxPageref*[J.E.]{Carter, Jr.}''
+% \item |\IndexRef[Jimmy]{Carter}{Carter, J.E., Jr.}| makes an xref but prints nothing. We need only create this cross-reference once.\IndexRef[Jimmy]{Carter}{Carter, J.E., Jr.}
+% \item By contrast, \cmd{\AKA} automatically formats the cross-reference name in the text and in the index.
+% \item Yet \cmd{\AKA} has limited formatting. Instead, after creating the xref with \cmd{\IndexRef}, one can use |\SubvertThis\Name*[Jimmy]{Carter}| \SubvertThis\Name*[Jimmy]{Carter} with full formatting, but without creating any page entries.
+% \item \cmd{\SubvertThis} syncs the variant with the canonical form \cmd{\DropAffix} \cmd{\Name*[J.E.]\{Carter, Jr.\}[Jimmy]} \DropAffix\Name*[J.E.]{Carter, Jr.}[Jimmy]. Otherwise, they would act as different names. See also Section~\ref{sec:NameTests}.
+% \item If we use |\Name[Jimmy]{Carter}| \Name[Jimmy]{Carter} we have to index this alternate name with the canonical one: |\IndexName[J.E.]{Carter, Jr.}|
+% \end{itemize}
+%
+% \DescribeMacro{\SeeAlso}
+% Put \cmd{\SeeAlso} before \cmd{\IndexRef}, \cmd{\AKA}, and \cmd{\PName} to make a \textit{see also} reference for a name that has appeared already in the index.\Version{3.0}
+% Yet one should mind the caveats:
+% \begin{itemize}
+% \item If |\SeeAlso\IndexRef{Bar}{Foo}| occurs on page 10, \cmd{\Name\{Bar\}} will not create index entries thereafter. A \textit{see also} ref follows all page refs.
+% \item If |\SeeAlso\IndexRef{Bar}{Foo}| occurs on page 10, \cmd{\Name\{Foo\}} will create index entries thereafter because it is the target of ``Bar.''
+% \item If |\Name{Baz}| occurs on page 12 and |\IndexRef{Baz}{Meschugge}| on page 16, no xref will be created. A \textit{see} reference has no page refs.
+% \end{itemize}
+%
+% \DescribeMacro{\ExcludeName}
+% This macro prevents a name from being used as either an index entry or as an index cross-reference.\Version{3.0} It will not exclude extant cross-references:
+% \begin{quote}
+% \fbox{\mystrut\ \cmd{\ExcludeName}\oarg{FNN}\marg{SNN|,| Affix}\oarg{Alternate} }
% \end{quote}
+% \cmd{\IndexRef} works best if one needs a cross-reference from a variant to the canonical name. If no cross-reference is needed, then \cmd{\ExcludeName} is used. Unlike \cmd{\IndexInactive} and \cmd{\IndexActive}, this macro works only on a per-name basis. Below we keep specific names and cross-references out of the index:\ExcludeName[Kris]{Kringle}\ExcludeName[Santa]{Claus}\ExcludeName{Grinch}\vspace{2.5ex}
%
-% \cmd{\IndexName} complies with the new syntax, where a suffixed pair in \meta{SNN} is a name/affix pair that can be ancient or Eastern. If \meta{FNN} are present, it ignores \meta{Alternate names} for Western and native Eastern name forms. If \meta{FNN} are absent, \cmd{\IndexName} sees \meta{Alternate names} as an affix or Eastern forename using the older syntax.
+%\leavevmode\quad\begin{minipage}[b]{0.9\textwidth}\small
+% \StartNum
+% \begin{verbatim}
+%\ExcludeName[Kris]{Kringle}
+%\ExcludeName[Santa]{Claus}
+%\ExcludeName{Grinch}\end{verbatim}
+% \end{minipage}\medskip
%
-% If used after \cmd{\IndexInactive} this macro does nothing until \cmd{\IndexActive} appears. It will not create index entries for cross-references made by \cmd{\IndexRef} and \cmd{\AKA}. It will not index names excluded by \cmd{\ExcludeName}. This provides a basic level of error protection for professional indexing.
+%\leavevmode\quad\begin{minipage}[b]{0.5\textwidth}\small
+% \ContinueNum
+% \begin{verbatim}
+%\Name[Kris]{Kringle}
+%\Name[Kris]{Kringle}
+%\AKA[Kris]{Kringle}[Santa]{Claus}\end{verbatim}
+% \end{minipage}
+% \begin{minipage}[b]{0.3\textwidth}\small
+% \Name[Kris]{Kringle}\\
+% \Name[Kris]{Kringle}\\
+% \AKA[Kris]{Kringle}[Santa]{Claus}
+% \end{minipage}\vspace{2ex}
%
-% The indexing mechanism in the \textsf{nameauth} package follows [\hyperlink{Mulvany}{Mulvany}, 152--82] and the \emph{Chicago Manual of Style} regarding Western name affixes. Thus \LChes\ becomes ``Sullenberger, Chesley B., III'' in the index.
+% For more examples of using \cmd{\ExcludeName} to handle variants, see Sections~\ref{sec:VarNames} and \ref{sec:NameParticles}, among others. We will check on the \Name{Grinch} later.\medskip
%
-% To show what gets into the index entries, consider the following example, much of which gets set up only once in the document.
-% \begin{quote}\small\setstretch{1.1}
-% |\begin{nameauth}|\\
-% | \< Dem & & Demetrius, I & >|\\
-% | \< Harnack & Adolf & Harnack & >|\\
-% | \< JWG & J.W. von & Goethe & >|\\
-% | \< Miyaz & & Miyazaki, Hayao & >|\\
-% |\end{nameauth}|
+% \phantomsection
+% \label{page:ExPage}
+% \DescribeMacro{\IncludeName}
+% For those who might need to break the indexing rules set by \textsf{nameauth}, these two macros get the job done.
+% \DescribeMacro{\IncludeName*}
+% They remove the protections used for exclusion and cross-referencing. These macros have the same syntax as \cmd{\ExcludeName}:\Version{3.0}
+% \begin{quote}
+% \fbox{\vbox{\hbox{\mystrut\ \cmd{\IncludeName\ }\oarg{FNN}\marg{SNN|,| Affix}\oarg{Alternate} }\par
+% \hbox{\mystrut\ \cmd{\IncludeName*}\oarg{FNN}\marg{SNN|,| Affix}\oarg{Alternate} }}}
% \end{quote}
-% \begingroup\NameAddInfo{Demetrius, I}{Soter}
-% \makeatletter\renewcommand*\NamesFormat[1]{\begingroup\ignorespaces%
-% \protected at edef\temp{\endgroup{\color{naviolet}\sffamily #1 %\ignorespaces
-% \noexpand\NameQueryInfo[\unexpanded\expandafter{\the\@nameauth at toksa}]
-% {\unexpanded\expandafter{\the\@nameauth at toksb}}
-% [\unexpanded\expandafter{\the\@nameauth at toksc}]}}\temp}\makeatother%
-% We add a text tag as a sobriquet and use the hook from Section~\ref{sec:standards}:
-% \begin{quote}\footnotesize\setstretch{1.1}
-% |\NameAddInfo{Demetrius, I}{Soter}|\\[1ex]
-% |\makeatletter\renewcommand*\NamesFormat[1]{\begingroup%|\\
-% |\protected at edef\temp{\endgroup{\color{naviolet}\sffamily #1 %|\\
-% |\noexpand\NameQueryInfo[\unexpanded\expandafter{\the\@nameauth at toksa}]|\\
-% |{\unexpanded\expandafter{\the\@nameauth at toksb}}|\\
-% |[\unexpanded\expandafter{\the\@nameauth at toksc}]}}\temp}\makeatother|
-% \end{quote}
-% We also add an index tag: |\TagName{Demetrius, I}{ Soter, king}| and a sort tag: |\PretagName{Demetrius, I}{Demetrius 1}|.
-% \begin{center}\footnotesize\setstretch{1.1}
-% \begin{tabular}{lll}\toprule
-% Text & Source & Index\\\midrule
-% \LDem & \cmd{\LDem} & Demetrius I Soter, king\\
-% \LDem & \cmd{\LDem} & Demetrius I Soter, king\\
-% \LHarnack[Adolf von] & \cmd{\LHarnack[Adolf von]} & Harnack, Adolf\\
-% \LHarnack & \cmd{\LHarnack} & Harnack, Adolf\\
-% \LJWG[Joh. Wolfg. v.] & \cmd{\LJWG[Joh. Wolfg. v.]} & Goethe, J.W. von\\
-% \LJWG & \cmd{\LJWG} & Goethe, J.W. von\\
-% \LMiyaz & \cmd{\LMiyaz} & Miyazaki Hayao\\
-% \LMiyaz[Sensei] & \cmd{\LMiyaz[Sensei]} & Miyazaki Hayao\\
-% \end{tabular}
-% \end{center}
-% Everything in the \meta{FNN} and \meta{SNN} arguments, including the \meta{Affix}, gets in the index. When the final optional argument is interpreted as an alternate name, it does not become part of the index entry. Text tags never get in the index, but index tags always get in the index.
-% \endgroup
-% \clearpage
%
-% \subsubsection{Index Cross-References}
-% \label{sec:IndexXref}
+% \cmd{\IncludeName} only removes an excluded reference created by \cmd{\ExcludeName} while \cmd{\IncludeName*} completely un-protects a cross-reference. Thereafter, one may create page entries for it like a name.
%
-% \DescribeMacro{\IndexRef}
-% The\marginpar{\large\raggedleft\textsf{\bfseries 3.0}\strut} cross-referencing macros (\cmd{\AKA}, etc.) use this macro. Also available to users, \cmd{\IndexRef} creates a \emph{see} reference by default from the name defined by its first three arguments to whatever one puts in the final argument. Section~\ref{sec:tweaks} show how cross-references are independent of other data sets. The syntax is:
-% \begin{quote}\small
-% \cmd{\IndexRef}\oarg{FNN}\marg{SNN}\oarg{Alternate names}\marg{reference target}
-% \end{quote}
+% For example, we used |\ExcludeName{Attila, the Hun}| at the end of Section~\ref{sec:SimpleStart}. Using \cmd{\IfAKA\{Attila, the Hun\}}|{|\meta{an xref}|}{|\meta{no xref}|}{|\meta{excluded}|}| tells us that he is \IfAKA{Attila, the Hun}{\meta{an xref}}{\meta{no xref}}{\meta{excluded}} (cf. Section~\ref{sec:NameTests}).
+%
+% Once we use |\IncludeName{Attila, the Hun}|\IncludeName{Attila, the Hun}, using |\LAttil| \LAttil\ will create a name and an index entry on this page. \cmd{\IfAKA} now tells us that he is \IfAKA{Attila, the Hun}{\meta{an xref}}{\meta{no xref}}{\meta{excluded}}. We again have a name that can be indexed.
%
-% The name used for the cross-reference is parsed like \cmd{\IndexName}. The final argument is neither parsed nor checked to see if a corresponding main entry exists. For example, to cross-reference ``Sun King'' with \Name*{Louis, XIV} use: \cmd{\IndexRef}\texttt{\{Sun King\}\{Louis XIV\}}\IndexRef{Sun King}{Louis XIV}. To format that reference in the text, use \cmd{\AKA} (Section~\ref{sec:AKA}).
+% Cross-references get more protection. \cmd{\IfAKA[Jay]\{Rockefeller\}} (a reference from Section~\ref{sec:SimpleStart}) tells us that he is \IfAKA[Jay]{Rockefeller}{\meta{an xref}}{\meta{no xref}}{}. If we follow the previous example and use |\IncludeName[Jay]{Rockefeller}|\IncludeName[Jay]{Rockefeller} he still is \IfAKA[Jay]{Rockefeller}{\meta{an xref}}{\meta{no xref}}{}. After using |\IncludeName*[Jay]{Rockefeller}|\IncludeName*[Jay]{Rockefeller} he finally becomes \IfAKA[Jay]{Rockefeller}{\meta{an xref}}{\meta{no xref}}{}, removing all protection from that cross-reference.
%
-% \begin{center}\bfseries Please see page~\pageref{page:manualxref} regarding complex cross-references.\end{center}
+% \phantomsection
+% \label{page:ManualXref}
+% \begin{center}\bfseries Advanced Cross-Referencing\end{center}
%
-% \DescribeMacro{\SeeAlso}
-% One\marginpar{\large\raggedleft\textsf{\bfseries 3.0}\strut} can precede \cmd{\IndexRef}, \cmd{\AKA}, or \cmd{\PName} with \cmd{\SeeAlso} to produce a \emph{see also} reference for a name that has appeared already in the index.\footnote{When the \texttt{verbose} option is selected, \cmd{\IndexRef} warns that a name once used as a page number entry is now being used as a cross-reference. It also warns when one attempts to redefine or alter an established cross-reference.}
-% However, this should be used with caution, as the following points indicate:
-% \begin{itemize}\small
-% \item If on page 10 there is |\SeeAlso\IndexRef{Bar}{Foo}|, one \emph{cannot} have index page entries for ``Bar'' thereafter. A \emph{see also} reference comes after page references.
-% \item If on page 10 there is |\SeeAlso\IndexRef{Bar}{Foo}|, one \emph{can} have index page entries for ``Foo'' thereafter because it is the target of ``Bar.''
-% \item If on page 10 there is |\Name{Bar}| and on page 12 |\IndexRef{Bar}{Foo}|, that will not work because \emph{see} references cannot contain page references.
-% \item Suggestion: Group references together: |\IndexRef{Bar}{Baz; Foo}|.\\ Avoid |\IndexRef{Bar}{Baz} \IndexRef{Bar}{Foo}|.\footnote{Professional indexers often use programs like \texttt{Cindex} that enforce a rigorous, standard methodology and syntax. The \textsf{nameauth} package likewise tries to follow suit.}
-% \end{itemize}
+% \noindent \cmd{\IndexRef}\Info{combining xrefs} will not merge multiple cross-references. One must manually merge cross-references: |\IndexRef{Bar}{Baz; Foo}| makes the index entry ``Bar, \textit{see} Baz; Foo.'' The preferred standard (in the humanities) suggests that one avoid something like |\IndexRef{Bar}{Baz} \IndexRef{Bar}{Foo}|.\medskip
%
-% \cmd{\IndexRef} causes an index tag with the format \meta{some text}\verb+|+\meta{some macro} to be reduced to \meta{some text} in the cross-reference. This allows cross-references to work with any index macro, e.g. \texttt{\textbar hyperpage}, used by \cmd{\TagName} (Section~\ref{sec:indextag}).\medskip
+% There\Info{one xref\break many targets} is a special case where one cross-reference can point to multiple targets, such as demonstrated in the example below:
+% \begin{quote}\small
+% \StartNum
+% \begin{verbatim}
+%\PretagName{\textit{Snellius}}{Snellius}
+%\IndexRef{\textit{Snellius}}{Snel van Royen, R.; Snel van Royen, W.}
%
-% \DescribeMacro{\ExcludeName}
-% This\marginpar{\large\raggedleft\textsf{\bfseries 3.0}\strut} macro prevents a name from being used as either an index entry or as an index cross-reference. It ignores extant cross-references. The syntax is:
-% \begin{quote}\small
-% \cmd{\ExcludeName}\oarg{FNN}\marg{SNN}\oarg{Alternate names}
+%Both \Name[W.]{Snel van Royen}[Willebrord] and
+%his son \Name[R.]{Snel van Royen}[Rudolph] were known
+%by the Latin moniker \Name{\textit{Snellius}}.\end{verbatim}
+%
+% \smallskip
+% \IndexRef{\textit{Snellius}}{Snel van Royen, R.; Snel van Royen, W.}
+% Both \Name[W.]{Snel van Royen}[Willebrord] and
+% his son \Name[R.]{Snel van Royen}[Rudolph] were known
+% by the Latin moniker \Name{\textit{Snellius}}.
% \end{quote}
%
-% After |\ExcludeName[Kris]{Kringle}|\ExcludeName[Kris]{Kringle}, you can use |\Name[Kris]{Kringle}| to get \Name[Kris]{Kringle} and \Name[Kris]{Kringle}. After |\ExcludeName[Santa]{Claus}|\ExcludeName[Santa]{Claus} you can use |\AKA[Kris]{Kringle}[Santa]{Claus}| \AKA[Kris]{Kringle}[Santa]{Claus}. No index entries are created.
+% \cmd{\IndexRef}\Info{location matters} prevents page numbers in cross-references, so one must plan how to set up complex cross-references. Above, |\Name{\textit{Snellius}}| produces no index entry because \cmd{\IndexRef} comes first.\medskip
%
-% This can be used to prevent references in the index after you are done with a name. Unlike \cmd{\IndexInactive} and \cmd{\IndexActive} this macro does not suspend the indexing system, but only works on a per-name basis.
-% \clearpage
+% Below,\Info{Multiple\break connections} two names are indexed with page numbers. They have \textit{see also} cross-references to each other. One of those names also has a \textit{see} reference to it:
+% \begin{itemize}
+% \item We use the canonical name to set up page references:\smallskip\\
+% \hbox{}\qquad|\Name{Maimonides}|\dotfill\Name{Maimonides}
+% \item \Name{Maimonides} has two other names, one more used than the other. We set up his least-used name as the \textit{see} reference:\smallskip\\
+% \hbox{}\qquad|\IndexRef{Moses, ben-Maimon}{Maimonides}|\IndexRef{Moses, ben-Maimon}{Maimonides}\\
+% \hbox{}\qquad|\Name{Moses, ben-Maimon}|\dotfill\Name{Moses, ben-Maimon}
+% \item We now have a main name with a page entry and a ``\textit{see} reference'' to that name. \Name*{Moses, ben-Maimon} has no page entries because we made the xref before we started to use the name.
+% \item Before creating \textit{see also} cross-references, we use the other alternate name so that all the page entries precede the cross-references:\smallskip\\
+% \hbox{}\qquad|\Name{Rambam}|\dotfill\Name{Rambam}
+% \item All \textit{see also} references must come after all page references. For example, one could put both of these macros at the end of the document:\smallskip\\
+% \hbox{}\qquad|\SeeAlso\IndexRef{Maimonides}{Rambam}|\SeeAlso\IndexRef{Maimonides}{Rambam}\\
+% \hbox{}\qquad|\SeeAlso\IndexRef{Rambam}{Maimonides}|\SeeAlso\IndexRef{Rambam}{Maimonides}
+% \end{itemize}
+%
+% \BigBlank
+% \newpage
+%
+% \begin{center}\bfseries Continental Format Reference Work\end{center}
%
-% \DescribeMacro{\IncludeName}
-% \DescribeMacro{\IncludeName*}
-% Feel\marginpar{\large\raggedleft\textsf{\bfseries 3.0}\strut} like breaking the indexing rules set by \textsf{nameauth}? Some might want to do things differently. These macros have the same syntax as \cmd{\ExcludeName}:
+% Let us create a macro for entries in a reference work using the basic form of Continental formatting from Section~\ref{sec:AltBasic}. We enable alternate formatting, set up tags, and define an article with head-words:
+% \AltFormatActive
+%\newcommand{\RefArticle}[4]{%^^A
+% \def\check{#2}%^^A
+% \ifx\check\empty
+% \noindent\ForgetThis#1\ {#4}
+% \else
+% \noindent\ForceName#1\ ``\ForceName#2''
+% \ForceName#3\ {#4}
+% \fi
+%}
% \begin{quote}\small
-% \cmd{\IncludeName\ }\oarg{FNN}\marg{SNN}\oarg{Alternate names}\\
-% \cmd{\IncludeName*}\oarg{FNN}\marg{SNN}\oarg{Alternate names}
+% \StartNum
+% \begin{verbatim}
+%\AltFormatActive
+%\PretagName[Greta]{\textSC{Garbo}}{Garbo, Greta}
+%\PretagName[Heinz]{\textSC{Rühmann}}{Ruehmann, Heinz}
+%\PretagName[Heinrich Wilhelm]{\textSC{Rühmann}}%
+% {Ruehmann, Heinrich Wilhelm}
+%
+%\newcommand{\RefArticle}[4]{%
+% \def\check{#2}%
+% \ifx\check\empty
+% \noindent\ForgetThis#1\ {#4}
+% \else
+% \noindent\ForceName#1\ ``\ForceName#2''
+% \ForceName#3\ {#4}
+% \fi
+%}\end{verbatim}
% \end{quote}
-% The unstarred form of \cmd{\IncludeName} only removes an exclusion created by \cmd{\ExcludeName}. The starred form of \cmd{\IncludeName} completely unprotects a cross-reference and allows it to have a page entry like a name.
%
-% For example, we used |\ExcludeName{Attila, the Hun}| after his appearance in Section~\ref{sec:simplestart}. Using \cmd{\IfAKA\{Attila, the Hun\}} (Section~\ref{sec:tests}) tells us that, ``\IfAKA{Attila, the Hun}{Attila is a cross-reference}{Attila is a name}{Attila is excluded}.''
-% Now if we |\IncludeName{Attila, the Hun}|\IncludeName{Attila, the Hun}, a reference to |\LAttil| will create a name and an index entry on this page: \LAttil. \cmd{\IfAKA} now tells us that ``\IfAKA{Attila, the Hun}{Attila is a cross-reference}{Attila is a name}{Attila is excluded}.''
+% \cmd{\RefArticle} either formats the name from the first argument and appends the fourth argument, ignoring the others if the second is empty, or it formats the first three arguments and appends the fourth. We determine what those arguments mean by including specific naming macros.
+% \begin{quote}\small
+% \ContinueNum
+% \begin{verbatim}
+%\RefArticle%
+% {\Name[Greta]{\textSC{Garbo}}}%
+% {}{}%
+% {(18 September 1905\,--\,15 April 1990) was a Swedish
+% film actress during the 1920s and 1930s.}
%
-% Cross-references get more protection. \cmd{\IfAKA[Jay]\{Rockefeller\}} (a reference in a footnote from Section~\ref{sec:simplestart}) tells us that ``\IfAKA[Jay]{Rockefeller}{Jay is a cross-reference}{Jay is a name}{Jay is excluded}.'' Using |\IncludeName[Jay]{Rockefeller}|\IncludeName[Jay]{Rockefeller} changes nothing: we still get ``\IfAKA[Jay]{Rockefeller}{Jay is a cross-reference}{Jay is a name}{Jay is excluded}.'' |\IncludeName*[Jay]{Rockefeller}|\IncludeName*[Jay]{Rockefeller} results in ``\IfAKA[Jay]{Rockefeller}{Jay is a cross-reference}{Jay is a name}{Jay is excluded},'' removing all protection of that cross-reference.
+%\RefArticle%
+% {%
+% \IndexRef[Heinrich Wilhelm]{\textSC{Rühmann}}%
+% {\textSC{Rühmann}, Heinz}%
+% \SubvertThis\FName[Heinrich Wilhelm]{\textSC{Rühmann}}%
+% }%
+% {\SubvertThis\FName[Heinz]{\textSC{Rühmann}}}%
+% {\Name[Heinz]{\textSC{Rühmann}}}%
+% {(7 March 1902\,--\,3 October 1994) was a German actor
+% in over 100 films.}
+%
+%\AltFormatInactive\end{verbatim}
+% \end{quote}
%
-% {\medskip\noindent\hbox{}\hfill\large Back to Section~\ref{sec:RefTables} \hfill\hbox{}}
+% \begin{quote}
+%\RefArticle%^^A
+% {\Name[Greta]{\textSC{Garbo}}}%^^A
+% {}{}%^^A
+% {(18 September 1905\,--\,15 April 1990) was a Swedish
+% film actress during the 1920s and 1930s.}
%
+%\RefArticle%^^A
+% {%^^A
+% \IndexRef[Heinrich Wilhelm]{\textSC{Rühmann}}%^^A
+% {\textSC{Rühmann}, Heinz}%^^A
+% \SubvertThis\FName[Heinrich Wilhelm]{\textSC{Rühmann}}%^^A
+% }%^^A
+% {\SubvertThis\FName[Heinz]{\textSC{Rühmann}}}%^^A
+% {\Name[Heinz]{\textSC{Rühmann}}}%^^A
+% {(7 March 1902\,--\,3 October 1994) was a German actor
+% in over 100 films.}
+% \end{quote}
+%
+% \AltFormatInactive
+% \ReturnLink
+% \newpage
+%
% \subsubsection{Index Sorting}
% \label{sec:IndexSort}
%
-% The general practice for sorting with \texttt{makeindex -s} involves creating your own |.ist| file (pages 659--65 in \emph{The Latex Companion}). Otherwise the following form works with both \texttt{makeindex} and \texttt{texindy}: |\index{|\meta{sort key}|@|\meta{actual}|}|
+% \DescribeMacro{\IndexActual}
+% The general practice for sorting with \texttt{makeindex -s} involves creating your own |.ist| file (pages 659--65 in \textit{The Latex Companion}). The following form works with both \texttt{makeindex} and \texttt{texindy}: |\index{|\meta{sort key}|@|\meta{actual}|}|. By default, the ``actual'' character is |@|. If one needs to change the ``actual'' character, such as when using \texttt{gind.ist} with \texttt{.dtx} files, one would put |\IndexActual{=}| in the preamble (or driver section) before using \cmd{\PretagName}.\medskip
%
-% \begin{center}\bfseries Basic Sorting (for Makeindex and More)\end{center}
+% \noindent \DescribeMacro{\PretagName}
+% The \textsf{nameauth} package enables automatic index sorting using a ``pretag'' (see Section~\ref{sec:NamePatterns}).\Version{2.0} \cmd{\PretagName} creates a sort key terminated with the ``actual'' character. Do not put the ``actual'' character in the ``pretag'':
+% \begin{quote}
+% \fbox{\mystrut\ \cmd{\PretagName}\oarg{FNN}\marg{SNN|,| Affix}\oarg{Alternate}\marg{tag} }
+% \end{quote}
%
-% \DescribeMacro{\PretagName}
-% \noindent The \marginpar{\large\raggedleft\textsf{\bfseries 2.0}\strut}
-% \textsf{nameauth} package integrates this sort of index sorting automatically by using a ``pretag.'' Section~\ref{sec:tweaks} show how sorting tags are independent of other data sets in \textsf{nameauth}. The syntax is:
+% One need only ``pretag'' names once in the preamble. Thereafter, they will be sorted automatically. For example:
% \begin{quote}\small
-% \cmd{\PretagName}\oarg{FNN}\marg{SNN}\oarg{Alternate names}\marg{tag}
+% \StartNum
+% \begin{verbatim}
+%\PretagName[Jan]{Łukasiewicz}{Lukasiewicz, Jan}
+%\PretagName{Æthelred, II}{Aethelred 2}
+%\PretagName[W.E.B.]{Du~Bois}{Dubois, W.E.B.}\end{verbatim}
% \end{quote}
%
-% \cmd{\PretagName} creates a sort key terminated with the ``actual'' character, which is |@| by default. Do not include the ``actual'' character in the ``pretag.''
-% For example:
-% \begin{quote}\small\setstretch{1.1}
-% |\PretagName[Jan]{Łukasiewicz}{Lukasiewicz, Jan}|\\
-% |\PretagName{Æthelred, II}{Aethelred 2}|
-% \end{quote}
+% Every reference to \Name*[Jan]{Łukasiewicz}, \LAeth, and \LDuBois\ is automatically tagged and sorted. One also must ``pretag'' names that contain spaces, macros, active characters, control spaces, non-breaking spaces, and anything that is not basic ASCII. That can differ when using \texttt{xindy} and Unicode-based \LaTeX.\medskip
%
-% One need only ``pretag'' names once in the preamble. Every time that one refers to \Name*[Jan]{Łukasiewicz} or \Name*{Æthelred, II}, the proper index entry will be tagged and sorted automatically.
+% For example, the\Info{particles and\break languages} sort tag \texttt{de Soto} precedes \texttt{deal} due to the space: \texttt{de\textvisiblespace}. The sort tag \texttt{Desoto} falls between \texttt{derp} and \texttt{determinism}. German \textsf{ä ö ü ß} map to English \textsf{ae oe ue ss}. Yet Norwegian \textsf{æ ø å} follow \textsf{z} in that order. Check a style guide regarding collating sequences, spaces, and sorting. This is where using \texttt{xindy} can be very helpful. See also Section~\ref{sec:NameParticles}.\medskip
%
-% Additionally, one can include sub-entry delimiters when sorting, so \meta{Some Name} can be sorted as a sub-entry of ``MyCategory'' by the following:
+% One\Info{sub-entries} can sort names by creating sub-entries, which depends on the index style and formatting files: \cmd{\PretagName[Some]\{Name\}\{}\meta{category}\texttt{!Name, Some\}}. See the documentation for \texttt{xindy} and \texttt{makeindex}.
+%
+% Below we show how \cmd{\PretagName} helps one to avoid manually sorting cross-references (cf. Section~\ref{sec:NameParticles}):
+%
% \begin{quote}\small
-% |\PretagName[Some]{Name}{MyCategory!Name, Some}|
+% \StartNum
+% \begin{verbatim}
+%\PretagName{\textit{Doctor angelicus}}{Doctor angelicus}
+%\IndexRef{\textit{Doctor angelicus}}{Thomas, Aquinas}
+%
+%Perhaps the greatest medieval theologian was
+%\Name{Thomas, Aquinas}, later known as
+%\Name{\textit{Doctor angelicus}}.\end{verbatim}
+%
+% \smallskip
+% \PretagName{\textit{Doctor angelicus}}{Doctor Angelicus}
+% \IndexRef{\textit{Doctor angelicus}}{Thomas, Aquinas}
+% Perhaps the greatest medieval theologian was
+% \Name{Thomas, Aquinas}, later known as
+% \Name{\textit{Doctor angelicus}}.
% \end{quote}
%
-% One also can ``pretag'' a cross-reference created with \cmd{\IndexRef}, \cmd{\AKA}, and so on. See also Sections~\ref{sec:IndexXref} and~\ref{sec:AKA}.
-% \clearpage
-%
-% Although the \cmd{\PretagName} macro might look similar to the the other tagging macros, its use is quite different:
-% \begin{itemize}\small
+% \cmd{\PretagName} differs from the other tagging macros because its function is sorting entries, not appending information to entries:
+% \begin{itemize}
% \item You can ``pretag'' any name and any cross-reference.
-% \item You can ``tag'' and ``untag'' only names, not cross-references.
-% \item There is no command to undo a ``pretag.''
+% \item You can ``tag'' and ``untag'' only page-reference names, not xrefs, but you can turn a page-reference name into a \textit{see also} xref.
+% \item You can undo a ``tag'' but you cannot undo a ``pretag.''
% \end{itemize}
+% \newpage
+%
+% \begin{center}\bfseries Debugging Problems with Sorting\end{center}
%
-% \DescribeMacro{\IndexActual}
-% If you need to change the ``actual'' character, such as with \texttt{gind.ist}, you would put |\IndexActual{=}| in the preamble before any use of \cmd{\PretagName}.
+% \bgroup If an entry is incorrect in the index, check the following:
+% \begin{itemize}
+% \item Are there any active characters, internal spaces, or control sequences in the name arguments? Use \cmd{\PretagName}.
+% \item Is alternate formatting used consistently? Are any names used within sections of alternate formatting ever used outside of them?
+% \item Are macros in the name arguments that can expand differently under different conditions preceded by \cmd{\noexpand}?
+% \end{itemize}
%
-% \begin{center}\bfseries Extra Spaces and Sorting\end{center}
-%
-% \noindent Under\marginpar{\small\raggedleft\dbend} NFSS, active Unicode characters expand to add one or two spaces after control sequences. See \cmd{\indexentry} and \cmd{\item} entries in your \texttt{idx} and \texttt{ind} files. For example, \texttt{ä} becomes \texttt{\cmd{\IeC\textvisiblespace}\{\cmd{\"a}\}} (one added space) and \texttt{Æ} becomes \texttt{\cmd{\IeC\textvisiblespace}\{\cmd{\AE\textvisiblespace}\}} (two added spaces).
-%
-% Section~\ref{sec:Unicode} shows how this is related to the number of times the active character must be expanded. The character \texttt{Æ} must expand twice, through both \cmd{\IeC} and \cmd{\T1}, while \texttt{ä} expands only once through \cmd{\IeC} to a letter. The character \texttt{ß} (\emph{scharfes Ess, Esszett}) below expands twice.
-%
-% Both \texttt{xelatex} and \texttt{lualatex} (using \textsf{fontspec}) avoid these issues by handling the characters natively. Thus we have the following:
-% \begin{center}\small
-% \begin{tabular}{l@{\,}l@{\,}c@{\,}l}
-% NFSS: & |\index{Fußball}| & $\rightarrow$ & \cmd{\indexentry}\ignorespaces%
-% \texttt{\{Fu\cmd{\IeC\textvisiblespace}\{\cmd{\ss\textvisiblespace}\}ball\}\{}\ignorespaces%
-% \meta{page}\texttt{\}}\\
-% fontspec: & |\index{Fußball}| & $\rightarrow$ & \cmd{\indexentry}\texttt{\{Fußball\}\{}\meta{page}\texttt{\}}\\
-% cseq: & |\index{Fu\ss ball}| & $\rightarrow$ & \cmd{\indexentry}\texttt{\{Fu\cmd{\ss\textvisiblespace}ball\}\{}\meta{page}\texttt{\}}\\
+% Since 2018 changes in the way that Unicode characters are handled in \texttt{pdflatex} and \texttt{latex} have made indexing simpler and more intuitive, e.g.\medskip
+%
+% \def\arrow{\ \(\rightarrow\)\ }
+% \def\midrowa{\arrow\quad}
+% \def\midrowb{\hphantom{\arrow}\quad}
+% \def\midrow{\midrowb}
+% \begin{center}\MyStretch
+% \begin{tabular}{ll>{\hspace{-1em}\midrow}lll>{\hspace{-1em}\midrow}l}\toprule
+% pre-2018 & text & index & post-2018 & text & index\gdef\midrow{\midrowa}\\\midrule
+% & ä & \texttt{\cmd{\IeC\textvisiblespace}\{\cmd{\"a}\}} & & ä & \texttt{ä}\\
+% \rowcolor{black!7!white} & æ & \texttt{\cmd{\IeC\textvisiblespace}\{\cmd{\ae\textvisiblespace}\}}
+% & & æ & \texttt{æ}\\\bottomrule
% \end{tabular}
% \end{center}
-%
-% A macro with the general form below, similar to \cmd{\IndexName}, will add two spaces after \emph{other} control sequences that are expanded multiple times. Those spaces only affect index sorting, not appearance. Remember this when using and modifying manual index entries with \textsf{nameauth}:
-% \begin{quote}\small\setstretch{1.1}
-% |\newcommand\IndexExample[1]{%|\\
-% \hbox{}\qquad|\protected at edef\argument{#1}\index{\argument}}|
-%
-% |\IndexExample{\textsc{football}}| $\rightarrow$\\ \hbox{}\qquad\ignorespaces%
-% \cmd{\indexentry}\ignorespaces%
-% \texttt{\{\cmd{\textsc\textvisiblespace\textvisiblespace}\ignorespaces%
-% \{football\}\}\{}\meta{page}\texttt{\}}
-%
-% |\index{\textsc{football}}| $\rightarrow$\\ \hbox{}\qquad\ignorespaces%
-% \cmd{\indexentry}\ignorespaces%
-% \texttt{\{\cmd{\textsc}\ignorespaces%
-% \{football\}\}\{}\meta{page}\texttt{\}}
+% One can test for this change and take different approaches with:
+% \begin{quote}
+% \cmd{\IfFileExists\{utf8-2018.def\}}\marg{yes}\marg{no}
% \end{quote}
+% One also should look at the entries in the \texttt{.idx} or \texttt{.ind} files to see how the name arguments and other index entry components are turned into index entries. If there are entries that do not work, one can find the corresponding page numbers in order to identify the problem.
%
-% These are not the only instances of macros inserting extra spaces. If something is off in the index, the best advice is to look at the \texttt{idx} or \texttt{ind} files. You can use the \textsf{verbatim} package to look at the \texttt{ind} file within your job itself:
+% Extra spaces\Warn{} are significant when sorting index entries, yet usually are not significant in the body text. Hidden spaces, tokens, macros, and control sequences create unique index entries that look similar, yet expand and sort differently. Some macros can add spaces to index entries. For example, index tags in this manual that include \cmd{\dag} show up as \cmd{\dag\textvisiblespace\textvisiblespace} in the index (two trailing spaces). Below we show a general form of macro that adds extra spaces to index entries:
% \begin{quote}\small
-% |\usepackage{verbatim}|\\
-% |\newif\ifdebug|\\[1ex]
-% |\ifdebug|\\
-% | \verbatiminput{\jobname.ind}|\\
-% |\fi|
+% \StartNum
+% \begin{verbatim}
+%\newcommand\Idx[1]{%
+% \protected at edef\arg{#1}%
+% \index{\arg}}\end{verbatim}
% \end{quote}
-% {\noindent\hbox{}\hfill\large Back to Section~\ref{sec:RefTables} \hfill\hbox{}}
%
+% \begin{center}\MyStretch\footnotesize
+% \begin{tabular}{l>{\hspace{-1em}\arrow\ }l}\toprule
+% |\Idx{\textsc{football}}| & \cmd{\indexentry}\texttt{\{\cmd{\textsc\textvisiblespace\textvisiblespace}\{football\}\}\{}\meta{page}\texttt{\}}\\
+% \rowcolor{black!7!white}|\index{\textsc{football}}| & \cmd{\indexentry}\texttt{\{\cmd{\textsc}\{football\}\}\{}\meta{page}\texttt{\}}\\\bottomrule
+% \end{tabular}
+% \end{center}\egroup
+%
+% \ReturnLink
+%
% \subsubsection{Index Tags}
-% \label{sec:indextag}
+% \label{sec:IndexTag}
%
% \DescribeMacro{\TagName}
-% This macro creates an index tag that will be appended to all index entries for a corresponding \cmd{\Name} from when it is invoked until the end of the document or a corresponding \cmd{\UntagName}. Both \cmd{\TagName} and \cmd{\UntagName} handle their arguments like \cmd{\IndexName}. If global tags are desired, tag names in the preamble.
-% \begin{quote}\small
-% \cmd{\TagName}\oarg{FNN}\marg{SNN}\oarg{Alternate names}\marg{tag}
+% This macro creates a tag appended to all index entries for a corresponding \cmd{\Name}.
+% \DescribeMacro{\UntagName}
+% The tag persists until one changes it with \cmd{\TagName} or destroys it with \cmd{\UntagName}.
+% Tags can include life dates, regnal dates, and other information. Both \cmd{\TagName} and \cmd{\UntagName} handle their arguments like \cmd{\IndexName}:
+% \begin{quote}
+% \fbox{\vbox{\hbox{\mystrut\ \cmd{\TagName}\oarg{FNN}\marg{SNN|,| Affix}\oarg{Alternate}\marg{tag} }\par
+% \hbox{\mystrut\ \cmd{\UntagName}\oarg{FNN}\marg{SNN|,| Affix}\oarg{Alternate} }}}
% \end{quote}
+% \newpage
+%
+% All the indexing macros are keyed to the name patterns. \cmd{\PretagName} generates the leading sort key. \cmd{\TagName} and \cmd{\UntagName} affect the trailing content:
%
-% Index tags are not ``pretags.'' Section~\ref{sec:tweaks} show how index tags are independent of other data sets in \textsf{nameauth}. To help sort that out, we look at what parts of the argument of \cmd{\index} get affected by these commands:
-%
-% \begin{center}\small\setstretch{1.1}
+% \begin{center}\small\MyStretch
% \begin{tabular}{r@{\,\vrule width0.5pt\,}c@{\,\vrule width0.5pt\,}c@{\,\vrule width0.5pt\,}l}
-% & \cmd{\PretagName} & \\
-% |\index{| & |Aethelred 2@| & |Æthelred II| & |, king}|\\
-% & & & \cmd{\TagName} and \cmd{\UntagName}\\
+% & \cmd{\PretagName} & \cmd{\IndexName}\\
+% \large\bfseries|\index{| & \large\bfseries|Aethelred 2@| & \large\bfseries|Æthelred II| & \large\bfseries|, king}|\\
+% & & & \quad\cmd{\TagName}\\
+% & & & \quad\cmd{\UntagName}\\
% \end{tabular}
% \end{center}
+% \noindent
%
-% All the tagging commands are keyed to the name arguments. \cmd{\PretagName} generates the leading sort key while \cmd{\TagName} and \cmd{\UntagName} affect the trailing content of the index entry.
+% Tags\Info{scholarly\break helps} created by \cmd{\TagName} can be helpful in the indexes of academic texts by adding dates, titles, etc. \cmd{\TagName} causes the \textsf{nameauth} indexing macros to append ``\texttt{,\textvisiblespace pope}'' to the index entries for the popes below:
+% \begin{quote}\small
+% \StartNum
+% \begin{verbatim}
+%\TagName{Leo, I}{, pope}
+%\TagName{Gregory, I}{, pope}
+%Pope \Name{Leo, I} was known as \AKA{Leo, I}{Leo, the Great}.\\
+%Pope \Name{Gregory, I} was known as \Name{Gregory, I}
+%``\ForceFN\AKA*{Gregory, I}{Gregory, the Great}.''\end{verbatim}
%
-% Tags created by \cmd{\TagName} can be helpful in the indexes of history texts, as can other package features. \cmd{\TagName} causes the \textsf{nameauth} indexing macros to append ``\texttt{,\textvisiblespace pope}'' to the index entries for the popes below:
-% \begin{quote}\small\setstretch{1.1}
-% |\TagName{Leo, I}{, pope}|\\
-% |\TagName{Gregory, I}{, pope}| \\[1ex]
-% |\Name{Leo, I} was known as \AKA{Leo, I}{Leo, the Great}.|\\
-% |\Name{Gregory, I} was known as \Name{Gregory, I}|\\
-% |``\ForceFN\AKA*{Gregory, I}{Gregory}[the Great].''|\\[1ex]
-% \Name{Leo, I} was known as \AKA{Leo, I}{Leo, the Great}.\\
-% \Name{Gregory, I} was known as \Name{Gregory, I}
-% ``\ForceFN\AKA*{Gregory, I}{Gregory}[the Great].''
+% \smallskip
+% Pope \Name{Leo, I} was known as \AKA{Leo, I}{Leo, the Great}.\\
+% Pope \Name{Gregory, I} was known as \Name{Gregory, I}
+% ``\ForceFN\AKA*{Gregory, I}{Gregory, the Great}.''
% \end{quote}
%
-% We see both the old syntax and the new syntax used above. \cmd{\TagName} works with all name types, but not with cross-references from \cmd{\IndexRef}, etc. Tags are literal text that can be daggers, asterisks, and so on. For example, all fictional names in the index of this manual are tagged with an asterisk. One must add any desired spacing to the start of the tag. Tagging aids scholarly indexing and can include life/regnal dates and other information.
+% \cmd{\TagName} works with all names, but not with cross-references from \cmd{\IndexRef}, \cmd{\AKA}, etc. (cf. Sections~\ref{sec:IndexXref}, \ref{sec:AKA}). Tags also can be daggers, asterisks, and so on. For example, all fictional names in the index of this manual are tagged with \S. One must add any desired spaces to the start of the tag.\medskip
%
-% You\marginpar{\small\raggedleft\dbend} can use the \marg{tag} field of \cmd{\TagName} to add specials to index entries for names. Every name in this manual is tagged with at least \texttt{\textbar hyperpage} to allow hyperlinks in the index with \textsf{ltxdoc} and \textsf{hypdoc}. You may have to use \cmd{\string}\texttt{\textbar hyperpage} where a vertical bar is active, as in \textsf{ltxdoc}.
+% We\Info{same name\break game} can format and index one name as two different people with \cmd{\TagName} and \cmd{\ForgetThis} (Section~\ref{sec:NameControl}). The index tags group together their respective entries. In a normal \LaTeX\ document one would write, e.g.:
%
-% For example, |\newcommand\orphan[2]{#1}| allows one to use \texttt{\textbar orphan\{}\meta{text}|}| in an index tag to replace the page number with \meta{text}. The \texttt{idx} file will contain |\indexentry{|\meta{name}\texttt{\textbar}|orphan{|\meta{text}|}}{|\meta{page}|}|. The \texttt{ind} file will have something like |\item |\meta{name}|, \orphan{|\meta{text}|}{|\meta{page}|}|, depending on the index style.
-% \clearpage
+% \begin{quote}\small
+% \StartNum
+% \begin{verbatim}
+%\TagName[E.]{Humperdinck}{ (composer)}
+%This refers to the classical composer:
+%\Name[E.]{Humperdinck}[Engelbert].
%
-% \DescribeMacro{\UntagName}
-% \cmd{\TagName} will replace one tag with another tag, but it does not remove a tag from a name. That is the role of \cmd{\UntagName}. The syntax is:
-% \begin{quote}\small
-% \cmd{\UntagName}\oarg{FNN}\marg{SNN}\oarg{Alternate names}
+%\TagName[E.]{Humperdinck}{ (singer)}
+%This refers to the pop singer from the 60s and 70s:
+%\ForgetThis\Name[E.]{Humperdinck}[Engelbert].\end{verbatim}
+%
+% \smallskip
+% \TagName[E.]{Humperdinck}{ (composer)\string|hyperpage}
+% This refers to the classical composer:
+% \Name[E.]{Humperdinck}[Engelbert].
+%
+% \TagName[E.]{Humperdinck}{ (singer)\string|hyperpage}
+% This refers to the pop singer from the 60s and 70s:
+% \ForgetThis\Name[E.]{Humperdinck}[Engelbert].
% \end{quote}
%
-% By using \cmd{\TagName} and \cmd{\UntagName}, one can disambiguate different people with the same name. For example, using macros from Section~\ref{sec:tweaks}:
+% One\Info{special tags} can use \cmd{\TagName} to create ``special'' index entries for names with the general form \cmd{\TagName\{}\meta{Name}\texttt{\}\{\textbar}\meta{Macro}\texttt{\}}, when \cmd{\def}\texttt{\textbackslash}\meta{Macro}\texttt{\#1\{\#1\}} exists. These\Version{3.3} tags are compatible with \textsf{hyperref}.\footnote{Before version 3.3 these special tags did not work with \textsf{hyperref}. The fix was inspired by the answer of \Name[Heiko]{Oberdiek} in: \url{https://tex.stackexchange.com/questions/201720/index-produces-invalid-idx-entry-with-manual-style-commaparse-hyperref}}
%
-% \begin{quote}\small\setstretch{1.1}
-% {\footnotesize\ttfamily This refers to |\Name[John]{Smith}.\\|\\
-% Now we have a new |\TagName[John]{Smith}{ (second)}%|\\
-% | \ForgetThis\Name[John]{Smith}.\\|\\
-% Now we have a third |\TagName[John]{Smith}{ (third)}%|\\
-% | \ForgetThis\Name[John]{Smith}.\\|\\
-% Then back to the first |\UntagName[John]{Smith}\Name*[John]{Smith}|.}
+% For example, using the \textsf{ltxdoc} class with \textsf{hypdoc} does not create hyperlinked page entries with \textsf{nameauth}. This behavior does not affect normal \LaTeX\ documents that use \textsf{nameauth} and \textsf{hyperref}. When creating this manual, we had to tag every name with: \cmd{\TagName\{}\meta{Name}\}\texttt{\{\textbar hyperpage\}} in the driver section of the \texttt{dtx} file.
+%
+% In the ``commented'' package documentation part of a \texttt{dtx} file, the vertical bar is active. This adds an extra layer of complexity. Index tags in the documentation part must use the form: \cmd{\TagName\{}\meta{Name}\texttt{\}\{}\cmd{\string}\texttt{\textbar hyperpage\}}.
+% \newpage
+%
+% Below we use the conventions of this manual to create a special tag:
+% \begin{quote}\small
+% \StartNum
+% \begin{verbatim}
+%\newcommand\Orphan[2]{#1(\hyperpage{#2})}
+%\TagName[Lost]{Name}{\,\S|Orphan{perdit}}
+%\Name[Lost]{Name}\end{verbatim}
%
-% This refers to \Name[John]{Smith}.\\
-% Now we have a new \TagName[John]{Smith}{* (second)\ignorespaces%
-% \string|hyperpage}\ForgetThis\Name[John]{Smith}.\\
-% Now we have a third \TagName[John]{Smith}{* (third)\ignorespaces%
-% \string|hyperpage}\ForgetThis\Name[John]{Smith}.\\
-% Then back to the first \TagName[John]{Smith}{*\string|hyperpage}\Name*[John]{Smith}.
+% \smallskip
+% \MyStretch\Name[Lost]{Name}\\
+% \texttt{idx} file: |\indexentry{Name, Lost\,\S |\texttt{\textbar}|Orphan{perdit}}{|\meta{page}|}|\\
+% \texttt{ind} file: |\item Name, Lost\,\S \pfill \Orphan{perdit}{|\meta{page}|}|
% \end{quote}
%
-% The tweaking macros (Section~\ref{sec:tweaks}) make it seem like you are dealing with three people who have the same name. The index tags will group together those entries that have the same tag.\footnote{Since this document, unlike the example above, puts an asterisk by all fictional names in the index, it puts an asterisk at the beginning of the tags above and does not \cmd{\UntagName} \Name*[John]{Smith}, but re-tags him with an asterisk again. We also used \cmd{\string}\texttt{\textbar hyperpage} in all the index tags. The information is not shown above for the sake of simplicity and pedagogy.}
+% The \textsf{microtype} package and its \texttt{Spacing} environment may be the best solution to fix index entries and sub-entries that break badly across columns or pages. Suppose, however, that we wanted to insert manual breaks into an index at will, preferably after the final page reference in an entry.
+%
+% We cannot just insert something like \cmd{\newpage}. In order to accomplish our goal, we need a helper macro that can take an argument. Below we use \cmd{\newpage}, but if we instead make use of the \textsf{multicol} or \textsf{idxlayout} packages we can replace that with \cmd{\columnbreak}. Two macros illustrate a similar concept:
+% \begin{quote}\small
+% \StartNum
+% \begin{verbatim}
+%\newcommand*{\EndBreak}[1]{#1\newpage}
+%\makeatletter
+%\newcommand*{\MidBreak}[1]{#1\newpage\@gobble}
+%\makeatother\end{verbatim}
+% \end{quote}
%
-% {\medskip\noindent\hbox{}\hfill\large Back to Section~\ref{sec:RefTables} \hfill\hbox{}}
+% Putting a break into the middle of an index entry is quite sketchy and probably should be avoided, but it can be done by using \cmd{\@gobble} to eat the comma after the break. Instead, breaking after the entry is preferable. That entry is a list of page numbers corresponding to several pages:
+% \begin{quote}
+% (page 10) \cmd{\Name\{Some, Name\}}\\
+% \dots\\
+% (page 15) \cmd{\Name\{Some, Name\}}\\
+% \dots\\
+% (page 18) \cmd{\TagName\{Some, Name\textbar EndBreak\}\%}\\
+% \hphantom{(page 18)} \cmd{\Name\{Some, Name\}}
+% \end{quote}
+%
+% If all instances of \cmd{\Name\{Some, Name\}} on page 18 have the same tag, there will be no duplicate page entries, \textsf{hyperref} will work, and the index will break after:
+% \begin{quote}
+% \texttt{Some Name \dots\ 10, 15, 18}
+% \end{quote}
+%
+% We\Info{manual entries} can use the same macros in manual index entries. We may need to look at the \texttt{idx} or \texttt{ind} files to craft matching entries on the page that corresponds to the placement of the break:\footnote{Results vary, depending on what distribution of \LaTeX\ is being used and how old it is. As we saw in the previous section, any name with active characters needs to be handled differently before 2018 than after 2018.}
+% \begin{quote}
+% (page 18) \cmd{\SkipIndex}\cmd{\Name\{Some, Name\}\%}\\
+% \hphantom{(page 18)} \cmd{\index\{Some Name\textbar EndBreak\}}
+% \end{quote}
+%
+% \ReturnLink
+% \newpage
%
% \subsection{``Text Tags''}
-% \label{sec:tagtext}
+% \label{sec:TextTags}
%
-% Section~\ref{sec:indextag} deals with similar tagging features in the index. ``Text tags'' are not printed automatically with every name managed by \textsf{nameauth}. Section~\ref{sec:tweaks} show how text tags are independent of other data sets. Section~\ref{sec:Hooksb} offers additional examples on using these macros.
-%
-% Several major uses include optional sobriquets, life dates, regnal dates, footnotes, biographical vignettes, margin paragraphs, and so on.\medskip
-%
% \DescribeMacro{\NameAddInfo}
-% Text tags are independent of any other name conditionals, similar to index tags. This \cmd{\long} macro's syntax is:
-% \begin{quote}\small
-% \cmd{\NameAddInfo}\oarg{FNN}\marg{SNN}\oarg{Alternate names}\marg{tag}
+% Unlike index tags, ``text tags'' are not printed automatically with every name managed by \textsf{nameauth}. Sections~\ref{sec:NameTests} and~\ref{sec:Hooksii} have more examples. The macro is \cmd{\long}, allowing for some complexity in the \meta{tag} argument:
+% \begin{quote}
+% \fbox{\mystrut\ \cmd{\NameAddInfo}\oarg{FNN}\marg{SNN|,| Affix}\oarg{Alternate}\marg{tag} }
% \end{quote}
%
-% For example, |\NameAddInfo[George]{Washington}{(1732--99)}|\NameAddInfo[George]{Washington}{(1732--99)} will associate the text ``\NameQueryInfo[George]{Washington}'' with the name ``\LWash.'' Note, however, that the tag does not print automatically with the name. The tag exists as the value to which a control sequence based on \SkipIndex\Washs\ name expands. Such a tag always must expand in the index to have consistent entries. In the text that is not required, so we do that explicitly with \cmd{\NameQueryInfo}.
-% \clearpage
+% For example, |\NameAddInfo[George]{Washington}{(1732--99)}|\NameAddInfo[George]{Washington}{(1732--99)} makes a text tag but does not print whenever \cmd{\Wash} ``\Wash'' is used.\medskip
%
% \DescribeMacro{\NameQueryInfo}
-% To retrieve the information in a text tag, one uses the name as a key to the corresponding information in the data set:
-% \begin{quote}\small
-% \cmd{\NameQueryInfo}\oarg{FNN}\marg{SNN}\oarg{Alternate names}
+% To print the text tag macro associated with a name, we use \cmd{\NameQueryInfo}, which calls the appropriate macro in the name info data set:
+% \begin{quote}
+% \fbox{\mystrut\ \cmd{\NameQueryInfo}\oarg{FNN}\marg{SNN|,| Affix}\oarg{Alternate} }
% \end{quote}
-% \NameAddInfo[Ulysses S.]{Grant}{(president 1869--77)}%
-% \NameAddInfo[Schuyler]{Colfax}{\footnote{Seventeenth vice-president of the US during the first term (1869--73) of \Name[Ulysses S.]{Grant}~\NameQueryInfo[Ulysses S.]{Grant}.}}%
-% Thus, |``\NameQueryInfo[George]{Washington}''| expands to ``\NameQueryInfo[George]{Washington}''. As with index tags, one can put a space at the start of a tag\,---\,or not. In text tags one might use asterisks, daggers, and even footnotes, such as one for \Name[Schuyler]{Colfax}.\NameQueryInfo[Schuyler]{Colfax} We can include a ``text tag'' within another one, thus building complex relations. Keeping this in mind, we look at the source for the footnote:
%
-% \begin{quote}\small\setstretch{1.1}
-% |\NameAddInfo[Ulysses S.]{Grant}{(president 1869--77)}%|\\
-% |\NameAddInfo[Schuyler]{Colfax}%|\\
-% |{\footnote{Seventeenth vice-president of the US during%|\\
-% |the first term (1869--73) of \Name[Ulysses S.]{Grant}~%|\\
-% |\NameQueryInfo[Ulysses S.]{Grant}.}}|\\
-% \texttt{\dots}\\
-% |\Name[Schuyler]{Colfax}.\NameQueryInfo[Schuyler]{Colfax}|
+% \NameAddInfo[Ulysses S.]{Grant}{(president from 1869 to 1877)}
+% \NameAddInfo[Schuyler]{Colfax}{\footnote{He was the seventeenth
+% US vice-president, holding office during the first term (1869--73)
+% of \Name[Ulysses S.]{Grant} \NameQueryInfo[Ulysses S.]{Grant}.}}
+% |\NameQueryInfo[George]{Washington}| expands to \NameQueryInfo[George]{Washington}. One can insert a space at its start or use signs like asterisks, daggers, and even footnotes, such as one for \Name[Schuyler]{Colfax}.\NameQueryInfo[Schuyler]{Colfax} Below is the source for footnote \arabic{footnote}:
+% \begin{quote}\small
+% \StartNum
+% \begin{verbatim}
+%\NameAddInfo[Ulysses S.]{Grant}{(president from 1869 to 1877)}%
+%\NameAddInfo[Schuyler]{Colfax}{\footnote{He was the seventeenth
+%US vice-president, holding office during the first term (1869--73)
+%of \Name[Ulysses S.]{Grant} \NameQueryInfo[Ulysses S.]{Grant}.}}\end{verbatim}
+%
+% \texttt{\dots}|\Name[Schuyler]{Colfax}.\NameQueryInfo[Schuyler]{Colfax}|
% \end{quote}
%
-% Please remember that text tags which query each other or themselves would cause a stack overflow unless you prevented that.\medskip
+% Since\Warn{} one can nest ``text tags'' or have them call each other, one can build complex relations. Yet one must protect against a stack overflow by using Boolean flags to stop the recursion:
+% \begin{quote}\small
+% \newif\ifA
+% \newif\ifB
+% \NameAddInfo{A}{%^^A
+% \Atrue A \ifB Stop \else \NameQueryInfo{B} \fi \Afalse}
+% \NameAddInfo{B}{%^^A
+% \Btrue B \ifA Stop \else \NameQueryInfo{A} \fi \Bfalse}
+% \StartNum
+% \begin{verbatim}
+%\newif\ifA
+%\newif\ifB
+%\NameAddInfo{A}{%
+% \Atrue A \ifB Stop \else \NameQueryInfo{B} \fi \Afalse}
+%\NameAddInfo{B}{%
+% \Btrue B \ifA Stop \else \NameQueryInfo{A} \fi \Bfalse}\end{verbatim}
+% \medskip
%
+% \begin{tabular}{@{}l@{ \(\rightarrow\) }l}
+% \cmd{\NameQueryInfo\{A\}} & \NameQueryInfo{A}\\
+% \cmd{\NameQueryInfo\{B\}} & \NameQueryInfo{B}\\
+% \end{tabular}
+% \end{quote}
+%
% \DescribeMacro{\NameClearInfo}
% \cmd{\NameAddInfo} will replace one text tag with another text tag, but it does not delete a text tag. That is the role of \cmd{\NameClearInfo}. The syntax is:
% \begin{quote}\small
-% \cmd{\NameClearInfo}\oarg{FNN}\marg{SNN}\oarg{Alternate names}
+% \fbox{\mystrut\ \cmd{\NameClearInfo}\oarg{FNN}\marg{SNN|,| Affix}\oarg{Alternate} }
% \end{quote}
%
-% |\NameClearInfo[George]{Washington}|\NameClearInfo[George]{Washington} will cause the next attempt at making a query, |\NameQueryInfo[George]{Washington}|, to produce nothing\NameQueryInfo[George]{Washington}.
+% After using |\NameClearInfo[George]{Washington}|\NameClearInfo[George]{Washington}, the next attempt to query the tag |\NameQueryInfo[George]{Washington}| will produce nothing\NameQueryInfo[George]{Washington}.\footnote{Had any information from a text tag been present, it would have appeared between ``nothing'' and the full stop.}
%
-% {\medskip\noindent\hbox{}\hfill\large Back to Section~\ref{sec:RefTables} \hfill\hbox{}}
+% \ReturnLink
+% \newpage
%
% \subsection{Name Decisions}
-% \subsubsection{Testing Decisions}
-% \label{sec:tests}
+% \label{sec:NameDecisions}
%
-% The macros in this section permit conditional text that depends on the presence or absence of a name. These macros use \cmd{\If}\textbf{\dots} because they differ from regular |\if| expressions. The following macros affect conditional branching: \cmd{\Name}, \cmd{\Name*}, \cmd{\FName}, \cmd{\PName}, \cmd{\AKA}, \cmd{\AKA*}, \cmd{\ForgetName}, \cmd{\SubvertName}, \cmd{\ExcludeName}, \cmd{\IncludeName}, and \cmd{\IncludeName*}.
+% The macros in this section force and detect name states. Below we keep names consistent with \textsf{beamer} overlays using some of the macros explained in this section. Otherwise, name forms will change as one advances the slides:\footnote{A copy of this example is in \texttt{examples.tex}, collocated with this manual.}
+% \begin{quote}\small
+% \StartNum
+% \begin{verbatim}
+%\documentclass{beamer}
+%\usepackage{nameauth}
+%\mode<presentation>
+%\beamerdefaultoverlayspecification{<+->}
%
-% If one uses these macros inside other macros or passes control sequences to them, the expansion of control sequences can create false results (see \emph{The \TeX book}, 212--15). To get around those problems, consider using the following:
-% \begin{itemize}\small
-% \item Use token registers to retrieve the arguments.
-% \item Regulate expansion with \cmd{\expandafter}, \cmd{\noexpand}, etc.
-% \item That affects accented characters in \texttt{pdflatex}/NFSS.
-% \end{itemize}
+%\begin{document}
%
-% See Sections~\ref{sec:Hooksb} and~\ref{sec:Hooksc} for related ideas about tokens and expansion. Using the \textsf{trace} package, \cmd{\show}, or \cmd{\meaning} can help you.
-% \clearpage
+%\begin{frame}{Move Text Without Retyping Names}
+% \begin{itemize}\footnotesize
+% \item<1-> Original\ForgetName[George]{Washington}%
+% \ForgetName[George]{Washington's}\\
+% \Name[Martin]{Van Buren} changes
+% after the first overlay.
+% \begin{enumerate}
+% \item<2-> \IfMainName[George]{Washington's}{He}%
+% {\Name[George]{Washington}}
+% became the first president
+% of the United States.
+% \item<3-> \IfMainName[George]{Washington}{His}%
+% {\SkipIndex\Name*[George]{Washington's}}
+% military successes during the Seven Years War
+% readied him to command the army
+% of the Continental Congress.
+% \end{enumerate}
+% \item<1-> Reordered\ForgetName[George]{Washington}%
+% \ForgetName[George]{Washington's}\\
+% \ForgetThis\Name[Ulysses S.]{Grant}
+% does not change.
+% \begin{enumerate}
+% \item<3-> \IfMainName[George]{Washington}{His}%
+% {\SkipIndex\Name*[George]{Washington's}}
+% military successes during the Seven Years War
+% readied him to command the army
+% of the Continental Congress.
+% \item<2-> \IfMainName[George]{Washington's}{He}%
+% {\Name[George]{Washington}}
+% became the first president
+% of the United States.
+% \end{enumerate}
+% \end{itemize}
+%\end{frame}
%
-% \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}\small
-% \cmd{\IfMainName}\oarg{FNN}\marg{SNN}\oarg{Alternate names}\marg{yes}\marg{no}
+%\end{document}\end{verbatim}
+%\IndexName[George]{Washington}
+%\IndexName[Martin]{Van Buren}
+%\IndexName[Ulysses S.]{Grant}
% \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}{I have not met Bob}'' because we have yet to invoke the name |\Name[Bob]{Hope}|. We will create a manual index entry here.\IndexName[Bob]{Hope}
+% The overlays, numbered progressively from one to three, begin by deleting name control sequence patterns. Uncontrolled names will change. Name conditionals ensure specific, context-dependent forms based on what name has appeared. These conditionals allow the text to be order-independent.
+%
+% \subsubsection{Making Decisions}
+% \label{sec:NameControl}
+%
+% By\Info{Naming system\break behavior} default, the macros below produce global effects. They change both the \texttt{!MN} and \texttt{!NF} data sets (Section~\ref{sec:NamePatterns}). With \cmd{\ForceName} (Section~\ref{sec:Formatting}), they change formatting. Apart from \cmd{\ForceName}, they also change long or short name forms and the outcome of the testing macros in the next section:
+%
+% \begin{center}\small\MyStretch
+% \begin{tabular}{lccc}\toprule
+% \bfseries Defaults & \bfseries Name Length & \bfseries Format Hooks & \bfseries Test Path\\\midrule
+% \bfseries Pre-First Use & Long & First & False\\
+% \rowcolor{black!7!white}\bfseries Subsequent Use\quad\hbox{} & Long or short & Subsequent & True\\\bottomrule
+% \end{tabular}\bigskip\\
+%
+% \begin{tabular}{lll}\toprule
+% \bfseries Modifications & \bfseries Form & \bfseries Function\\\midrule
+% \hfill|\SubvertThis\LAnth| & \SubvertThis\LAnth & force subsequent use \hbox to 3.02em{\hfill}\\
+% & & force long form\\
+% \rowcolor{black!7!white} |\ForceName\SAnth| & \ForceName\SAnth & default subsequent use\\
+% \rowcolor{black!7!white} & & force first-use format\\
+% |\ForgetThis\SAnth| & \ForgetThis\SAnth & force first use; default long\\
+% & & default first-use format\\
+% \rowcolor{black!7!white}|\SAnth| & \SAnth & default subsequent use\\
+% \rowcolor{black!7!white} & & default short form\\\bottomrule
+% \end{tabular}
+% \end{center}
+%
+% \DescribeMacro{\ForgetName}
+% This macro takes the same arguments as \cmd{\Name}. It ``forgets'' a name, forcing a ``pre-first use'' case. The syntax is:
% \begin{quote}\small
-% |\IfMainName[Bob]{Hope}{I met Bob}{I have not met Bob}|
-% \end{quote}%
-% Please note that this test is not affected by the use of \cmd{\IndexName}. Since we have encountered \ForgetThis\Name*{Elizabeth, I}, we get ``\IfMainName{Elizabeth, I}{I met Bess}{I have not met Bess}'' with a similar example:
-% \begin{quote}\small\setstretch{1.1}
-% |\IfMainName{Elizabeth, I}{I met Bess}%|\\
-% | {I have not met Bess}|
+% \cmd{\ForgetName}\oarg{FNN}\marg{SNN|,| Affix}\oarg{Alternate}
% \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:
+% \DescribeMacro{\ForgetThis}
+% This prefix macro causes the next instance of a naming macro or shorthand to ``forget'' a name before printing it.\Version{3.1} After knowing |\Einstein| ``\Einstein'' we forget him and again have a first reference: |\ForgetThis\Einstein| ``\ForgetThis\Einstein.''\medskip
+%
+% \DescribeMacro{\SubvertName}
+% This macro takes the same arguments as \cmd{\Name}. It ``subverts'' a name, forcing a ``subsequent use'' case. The syntax is:
% \begin{quote}\small
-% \cmd{\IfFrontName}\oarg{FNN}\marg{SNN}\oarg{Alternate names}\marg{yes}\marg{no}
+% \cmd{\SubvertName}\oarg{FNN}\marg{SNN|,| Affix}\oarg{Alternate}
% \end{quote}
-% This macro works the same as \cmd{\IfMainName}. A ``front matter'' name is 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.
%
-% \phantomsection\label{page:Carnap}For example, based on Section~\ref{sec:formatting}, we see that ``\ignorespaces
-% \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}}'' a formatted and unformatted name with the following test:
-% \begin{quote}\small\setstretch{1.1}
-% |\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}}|
-% \end{quote}%
-% Please refer to Sections~\ref{sec:tweaks} and~\ref{sec:LocalNames} to understand the scope and operation of main- and front-matter names.
-% \vfil
-% \begin{center}\large \emph{This space intentionally left blank.}\end{center}
-% \clearpage
+% \DescribeMacro{\SubvertThis}
+% This prefix macro causes the next instance of a naming macro or shorthand to ``subvert'' a name before printing it.\Version{3.1} As in the table on page~\pageref{page:Priorities}, \cmd{\ForgetThis} has a higher priority than \cmd{\SubvertThis} and nullifies it when used together.\medskip
%
-% \DescribeMacro{\IfAKA}
-% If you want to produce output or perform a task based on whether a cross-reference name exists, use \cmd{\IfAKA}, whose syntax is:
+% \DescribeMacro{\LocalNames}
+% \cmd{\LocalNames} restricts the effects of the macros above to the current naming system.
+% \DescribeMacro{\GlobalNames}
+% \cmd{\GlobalNames} restores the default behavior. We define a macro that reports whether a name exists in the main matter, front matter, both, or none:
+% \def\CheckChuck{{\bfseries\IfFrontName[Charlie]{Chaplin}%
+% {\IfMainName[Charlie]{Chaplin}{both}{front}}%
+% {\IfMainName[Charlie]{Chaplin}{main}{none}}}}%
% \begin{quote}\small
-% \cmd{\IfAKA}\oarg{FNN}\marg{SNN}\oarg{Alt. names}\marg{y}\marg{n}\marg{excluded}
+% \StartNum
+% \begin{verbatim}
+%\def\CheckChuck{{\bfseries\IfFrontName[Charlie]{Chaplin}%
+% {\IfMainName[Charlie]{Chaplin}{both}{front}}%
+% {\IfMainName[Charlie]{Chaplin}{main}{none}}}}\end{verbatim}
% \end{quote}
-% This macro works similarly to \cmd{\IfMainName}, although it has an additional \meta{excluded} branch in order to detect those names excluded from indexing by \cmd{\ExcludeName} (Section~\ref{sec:IndexXref}).
%
-% A cross-reference name is created by \cmd{\IndexRef}, \cmd{\AKA}, and \cmd{\AKA*}. The following example illustrates how we use this macro:
-% \begin{enumerate}
-% \item In the text we refer to \Name[Jesse]{Ventura}, |\Name[Jesse]{Ventura}|.
-% \item We establish his lesser-known legal name as an alias: ``\AKA[Jesse]{Ventura}[James]{Janos},'' |\AKA[Jesse]{Ventura}[James]{Janos}|.
+% We start with no extant name:
+% \begin{quote}\small\MyStretch
+% |\CheckChuck|\dotfill\CheckChuck\qquad\qquad\qquad\hbox{}
+% \end{quote}
%
-% \item We construct the following test:
-% \begin{quote}\small\setstretch{1.1}
-% |\IfAKA[James]{Janos}%|\\
-% | {\Name[Jesse]{Ventura} has an alias}%|\\
-% | {\Name[Jesse]{Ventura} has no alias}%|\\
-% | {\Name[Jesse]{Ventura} is excluded}|
+% We create a name in the ``main matter'':
+% \begin{quote}\small\MyStretch
+% |\Name*[Charlie]{Chaplin}|\dotfill\Name*[Charlie]{Chaplin}\qquad\qquad\qquad\hbox{}\\
+% |\CheckChuck|\dotfill\CheckChuck\qquad\qquad\qquad\hbox{}
% \end{quote}
-% \item This gives us ``\IfAKA[James]{Janos}{\Name[Jesse]{Ventura} has an alias}{\Name[Jesse]{Ventura} has no alias}{\Name[Jesse]{Ventura} is excluded}.''
-% \end{enumerate}
-% If you are confident that you will not be dealing with names generated by \cmd{\ExcludeName} then you can just leave the \meta{excluded} branch as |{}.|
%
-% A similar use of |\IfAKA{Confucius}| tells us that ``\IfAKA{Confucius}{\Name{Confucius} is an alias}{\Name{Confucius} is not an alias}{}.'' Yet we should test that completely:
-% \begin{quote}\small\setstretch{1.1}
-% |\IfAKA[|\meta{FNN}|]{|\meta{SNN}|}[|\meta{alt. names}|]%|\\
-% |{|\meta{true; it is a pseudonym}|}%|\\
-% |{%|\\
-% | \IfFrontName[|\meta{FNN}|]{|\meta{SNN}|}[|\meta{alt. names}|]%|\\
-% | {\IfMainName[|\meta{FNN}|]{|\meta{SNN}|}[|\meta{alt. names}|]%|\\
-% | {|\meta{both}|}%|\\
-% | {|\meta{front}|}%|\\
-% | }%|\\
-% | {\IfMainName[|\meta{FNN}|]{|\meta{SNN}|}[|\meta{alt. names}|]%|\\
-% | {|\meta{main}|}%|\\
-% | {|\meta{does not exist}|}%|\\
-% | }%|\\
-% |}%|\\
-% |{|\meta{excluded}|}|
+% We switch to the ``front-matter'' and create a name, but since we are using the \texttt{quote} environment, we add \cmd{\global}:
+% \begin{quote}\small\MyStretch
+% |\global\NamesInactive|\global\NamesInactive\\
+% |\Name*[Charlie]{Chaplin}|\dotfill\Name*[Charlie]{Chaplin}\qquad\qquad\qquad\hbox{}\\
+% |\CheckChuck|\dotfill\CheckChuck\qquad\qquad\qquad\hbox{}
% \end{quote}
-% Here we test for a name used with \cmd{\ExcludeName} (Section~\ref{sec:IndexXref}) to get the result, ``\ExcludeName{Grinch}\IfAKA{Grinch}{\Name{Grinch} is an alias}{\Name{Grinch} is not an alias}{\Name{Grinch} is excluded}'':
-% \begin{quote}\small\setstretch{1.1}
-% |\ExcludeName{Grinch}%|\\
-% |\IfAKA{Grinch}%|\\
-% | {\Name{Grinch} is an alias}%|\\
-% | {\Name{Grinch} is not an alias}%|\\
-% | {\Name{Grinch} is excluded}|
+%
+% We now have two names. Their patterns are:
+% \begin{quote}\small\MyStretch
+% \texttt{\ShowPattern[Charlie]{Chaplin}!MN}\\
+% \texttt{\ShowPattern[Charlie]{Chaplin}!NF}
% \end{quote}
+%
+% We use \cmd{\Localnames} to make \cmd{\ForgetName} and \cmd{\SubvertName} work with only the front-matter system. Then we ``forget'' the front-matter name:
+% \begin{quote}\small\MyStretch
+% |\LocalNames|\LocalNames\\
+% |\ForgetName[Charlie]{Chaplin}|\ForgetName[Charlie]{Chaplin}\\
+% |\CheckChuck|\dotfill\CheckChuck\qquad\qquad\qquad\hbox{}
+% \end{quote}
%
-% By using the text tag macros with the conditional macros, one can display information associated with a name based on whether or the name has occurred. Below we disable indexing with \cmd{\IndexInactive}:
-% \begin{quote}\small\IndexInactive
-% \begin{verbatim}
-%\NameAddInfo{Sam}
-%{\IfMainName{Freddy}%
-% {\SkipIndex\Name{Freddy's} sidekick}%
-% {a young gardener helping his granddad}}
+% Next we ``subvert'' the front-matter name to ``remember'' it again and switch to main matter, again using \cmd{\global} to ignore scoping.
+% \begin{quote}\small\MyStretch
+% |\SubvertName[Charlie]{Chaplin}|\SubvertName[Charlie]{Chaplin}\\
+% |\global\NamesActive|\global\NamesActive\\
+% |\CheckChuck|\dotfill\CheckChuck\qquad\qquad\qquad\hbox{}
+% \end{quote}
%
-%There is \Name{Sam}. He is \NameQueryInfo{Sam}.
-%Then \Name{Sam} met \Name{Freddy}, who lives with his uncle.
-%Now he is \NameQueryInfo{Sam} on a quest to save the realm.
-% \end{verbatim}\vspace{-1ex}
-% \NameAddInfo{Sam}{\IfMainName{Freddy}{\SkipIndex\Name{Freddy's} sidekick}{a young gardener helping his granddad}}
-% There is \Name{Sam}. He is \NameQueryInfo{Sam}.\\
-% Then \Name{Sam} met \Name{Freddy}, who lives with his uncle.\\
-% Now he is \NameQueryInfo{Sam} on a quest to save the realm.
+% We forget the main-matter name and additionally reset the default behavior so that \cmd{\ForgetName} and \cmd{\SubvertName} work with both systems:
+% \begin{quote}\small\MyStretch
+% |\ForgetName[Charlie]{Chaplin}|\ForgetName[Charlie]{Chaplin}\\
+% |\GlobalNames|\GlobalNames\\
+% |\CheckChuck|\dotfill\CheckChuck\qquad\qquad\qquad\hbox{}
% \end{quote}
-% We use \cmd{\SkipIndex} to prevent the name ``\SkipIndex\Name{Freddy's}'' from making an index entry of its own. See Section~\ref{sec:indexctrl}. Take care to avoid a stack overflow by not allowing conditional text to call tags recursively ``down the rabbit hole.''
%
-% {\medskip\noindent\hbox{}\hfill\large Back to Section~\ref{sec:RefTables} \hfill\hbox{}}
+% Finally, we forget everything. Even though we are in a main-matter section, the front-matter name also goes away:
+% \begin{quote}\small\MyStretch
+% |\ForgetName[Charlie]{Chaplin}|\ForgetName[Charlie]{Chaplin}\\
+% |\CheckChuck|\dotfill\CheckChuck\qquad\qquad\qquad\hbox{}
+% \end{quote}
%
-% \subsubsection{Changing Decisions}
-% \label{sec:tweaks}
+% \ReturnLink
+%
+% \subsubsection{Testing Decisions}
+% \label{sec:NameTests}
%
-% The following summary of macros that can change (not just read) different data sets will help us put this section into better perspective:
+% The macros in this section test for the presence or absence of a name, then expand based on the result. For example, they can synchronize information between a float and body text by each testing whether a name exists and making decisions about the information accordingly.\medskip
%
-% \begin{center}\small
-% \begin{tabular}{@{}lc@{}c@{}c@{}c@{}c@{}}\toprule[1pt]
-% Macro & \footnotesize Names & \footnotesize Xrefs & \footnotesize Sort & \footnotesize Index & \footnotesize Text\\
-% & & & Tag & Tag & Tag\\\midrule
-% \cmd{\Name} \cmd{\Name*} \cmd{\FName} & \YES & \NO & \NO & \NO & \NO\\\midrule
-% \cmd{\ForgetName} \cmd{\SubvertName} & \YES & \NO & \NO & \NO & \NO\\\midrule
-% \cmd{\PName} \cmd{\PName*} & \YES & \YES & \NO & \NO & \NO\\\midrule
-% \cmd{\AKA} \cmd{\AKA*} \cmd{\IndexRef} & \NO & \YES & \NO & \NO & \NO\\\midrule
-% \cmd{\ExcludeName} & \NO & \YES & \NO & \NO & \NO\\\midrule
-% \cmd{\IncludeName} \cmd{\IncludeName*} & \NO & \YES & \NO & \NO & \NO\\\midrule
-% \cmd{\PretagName} & \NO & \NO & \YES & \NO & \NO\\\midrule
-% \cmd{\TagName} \cmd{\UntagName} & \NO & \NO & \NO & \YES & \NO\\\midrule
-% \cmd{\NameAddInfo} \cmd{\NameClearInfo} & \NO & \NO & \NO & \NO & \YES\\\midrule
-% \end{tabular}
-% \end{center}
+% \DescribeMacro{\IfMainName}
+% In order to test whether or not a ``main matter'' name control sequence exists, use this long macro that can accommodate paragraph breaks:
+% \begin{quote}\small
+% \fbox{\mystrut\ \cmd{\IfMainName}\oarg{FNN}\marg{SNN|,| Affix}\oarg{Alternate}\marg{yes}\marg{no} }
+% \end{quote}
+%
+% For example, because we have not seen the equivalent of |\Name[Bob]{Hope}| or |\SubvertName[Bob]{Hope}|, we try the following test and get:
+% \begin{quote}\small\MyStretch
+% |\IfMainName[Bob]{Hope}{Bob here!}{No Bob.}|\dotfill \IfMainName[Bob]{Hope}{Bob here!}{No Bob.}
+% \end{quote}
%
-% The macros in this section force either a first or subsequent use, helpful especially with overlays in the \textsf{beamer} class. They do not affect \cmd{\AKA} and \cmd{\PName}. They always are global with respect to \LaTeX\ scoping rules.
+% Still, we can create an index entry here with \IndexName[Bob]{Hope}|\IndexName[Bob]{Hope}| and it will not affect the test above. Since, however, we have encountered the equivalent of |\Name{Elizabeth,I}| many times in the document, we get the following result:
+% \begin{quote}\small
+% |\IfMainName{Elizabeth,I}{Bess here!}{No Bess.}|\dotfill\IfMainName{Elizabeth,I}{Bess here!}{No Bess.}
+% \end{quote}
%
-% ``Forgetting'' a name not only changes its format, but also its displayed form and its status with decision macros. Sometimes you want all the changes (\textsf{beamer} overlays) and sometimes not (use \cmd{\Name*}, \cmd{\ForceName}, etc.).
-% \begin{center}\small
-% \begin{tabular}{lccc}\toprule
-% \bfseries & \bfseries Name Length & \bfseries Format Hooks & \bfseries Decision\footnotemark[22]\\\midrule
-% \bfseries First Use & Always long & First & False\\
-% \bfseries Subsequent Use & Long or short & Subsequent & True\\\bottomrule
-% \end{tabular}
-% \end{center}
-% \footnotetext[22]{Decision outcome prior to the name being used.}
-% \addtocounter{footnote}{1}
+% \DescribeMacro{\IfFrontName}
+% In order to test whether or not a ``front matter'' name control sequence exists, use this long macro that can accommodate paragraph breaks. Its syntax is:
+% \begin{quote}\small
+% \fbox{\mystrut\ \cmd{\IfFrontName}\oarg{FNN}\marg{SNN|,| Affix}\oarg{Alternate}\marg{yes}\marg{no} }
+% \end{quote}
+% This macro works like \cmd{\IfMainName}, except using the ``front matter'' name control sequences as the test subject.
%
-% \DescribeMacro{\ForgetName}
-% This macro takes the same arguments as \cmd{\Name}. It ignores alternate names if \meta{FNN} are present. It ``forgets'' a name, forcing a ``first use'' The syntax is:
+% \phantomsection\label{page:Carnap}
+% For example, based on Section~\ref{sec:Formatting}, we see that ``\ignorespaces
+% \IfFrontName[Rudolph]{Carnap}%
+% {\IfMainName[Rudolph]{Carnap}%
+% {\Name[Rudolph]{Carnap} is both}%
+% {\Name[Rudolph]{Carnap} is only front-matter}}%
+% {\IfMainName[Rudolph]{Carnap}%
+% {\Name[Rudolph]{Carnap} is only main-matter}%
+% {\Name[Rudolph]{Carnap} is not mentioned}}'' a main-matter and front-matter name with the following test:
% \begin{quote}\small
-% \cmd{\ForgetName}\oarg{FNN}\marg{SNN}\oarg{Alternate names}
+% \StartNum
+% \begin{verbatim}
+%\IfFrontName[Rudolph]{Carnap}%
+%{%
+% \IfMainName[Rudolph]{Carnap}%
+% {\Name[Rudolph]{Carnap} is both}%
+% {\Name[Rudolph]{Carnap} is only front-matter}%
+%}%
+%{%
+% \IfMainName[Rudolph]{Carnap}%
+% {\Name[Rudolph]{Carnap} is only main-matter}%
+% {\Name[Rudolph]{Carnap} is not mentioned}%
+%}\end{verbatim}
% \end{quote}
%
-% \DescribeMacro{\ForgetThis}
-% This mode switch\marginpar{\large\raggedleft\textsf{\bfseries 3.1}} causes the next instance of a naming macro or shorthand to call \cmd{\ForgetName} internally. After knowing |\Einstein| ``\Einstein'' we forget him and again have a first reference: |\ForgetThis\Einstein| ``\ForgetThis\Einstein.''\medskip
+% \DescribeMacro{\IfAKA}
+% This macro tests whether or not a regular or excluded form of cross-reference control sequence exists. The syntax is:
+% \begin{quote}\small
+% \fbox{\mystrut\ \cmd{\IfAKA}\oarg{FNN}\marg{SNN|,| Affix}\oarg{Alternate}\marg{y}\marg{n}\marg{excluded} }
+% \end{quote}
%
-% \DescribeMacro{\SubvertName}
-% This macro is the opposing analogue of the macros that we saw above. It ``subverts'' a name, forcing a ``subsequent use.'' The syntax is:
+% This macro works like \cmd{\IfMainName}, although it has an additional \meta{excluded} branch in order to detect the activity of \cmd{\ExcludeName} (Section~\ref{sec:IndexXref}).
+%
+% Cross-references are governed by name control sequences ending in \texttt{!PN} (Section~\ref{sec:NamePatterns}). Regular cross-reference control sequences (the \marg{y} path) expand to empty. Excluded control sequences (the \marg{excluded} path) expand to \texttt{!}.
+%
+%\cmd{\ExcludeName} creates excluded xrefs; \cmd{\IncludeName} destroys them. Regular xrefs are created by \cmd{\IndexRef}, \cmd{\AKA}, \cmd{\AKA*}, and \cmd{\PName}; they are destroyed by \cmd{\IncludeName*}. Here is how we use this logic:
+%
+% \begin{enumerate}
+% \item In the text we refer to former pro-wrestler and Minnesota governor \Name[Jesse]{Ventura}, |\Name[Jesse]{Ventura}|.
+% \item We establish his lesser-known legal name as an alias: ``\IndexRef[James]{Janos}{Ventura, Jesse}\Name[James]{Janos},''\\ |\IndexRef[James]{Janos}{Ventura,|\,|Jesse}\Name[James]{Janos}|.
+%
+% \item We get the result: ``\IfAKA[James]{Janos}{\Name*[Jesse]{Ventura} is a stage name}{\Name*[Jesse]{Ventura} is a regular name}{}.'' If we do not use \cmd{\ExcludeName}, we can leave the \marg{excluded} branch empty:
% \begin{quote}\small
-% \cmd{\SubvertName}\oarg{FNN}\marg{SNN}\oarg{Alternate names}
+% \StartNum
+% \begin{verbatim}
+%\IfAKA[James]{Janos}%
+% {\Name*[Jesse]{Ventura} is a stage name}%
+% {\Name*[Jesse]{Ventura} is a regular name}%
+% {}\end{verbatim}
% \end{quote}
+% \end{enumerate}
%
-% \DescribeMacro{\SubvertThis}
-% This mode switch\marginpar{\large\raggedleft\textsf{\bfseries 3.1}} causes the next instance of a naming macro or shorthand to call \cmd{\SubvertName} internally. \cmd{\ForgetThis} takes precedence over \cmd{\SubvertThis}.
-% \begin{quote}\small\setstretch{1.1}
-% \begin{tabular}{@{}lll}
-% |\SubvertThis\LAnth| & \SubvertThis\LAnth & \emph{force subseq. use, force long}\\
-% |\ForceName\SAnth| & \ForceName\SAnth & \emph{subseq. use, force first format}\\
-% |\ForgetThis\SAnth| & \ForgetThis\SAnth & \emph{force first use and format}\\
-% |\SAnth| & \SAnth & \emph{subsequent use, short}\\
-% \end{tabular}
+% Otherwise, based on Section~\ref{sec:IndexXref}, we get: ``\IfAKA{Grinch}{\Name{Grinch} is an alias}{\Name{Grinch} is not an alias}{\Name{Grinch} is excluded}'':
+% \begin{quote}\small
+% \StartNum
+% \begin{verbatim}
+%\IfAKA{Grinch}%
+% {\Name{Grinch} is an alias}%
+% {\Name{Grinch} is not an alias}%
+% {\Name{Grinch} is excluded}\end{verbatim}
% \end{quote}
-% We met \cmd{\ForceName} back in Section~\ref{sec:formatting}. Here we use it with a subsequent name use to format it as a first use. We will meet \cmd{\ForceName} again in Section~\ref{sec:AKA}.\medskip
%
-% By default,\marginpar{\small\raggedleft Naming system\break scope} these macros affect a name form in both front matter and main matter naming systems. The example on page~\pageref{page:Carnap} above 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}}.'' 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 front- and main-matter names were forgotten and now we have a first-use situation.
+% We can combine all these macros create a complete test:
+% \begin{quote}\small
+% \StartNum
+% \begin{verbatim}
+%\IfAKA[FNN]{SNN, Affix}[Alternate]%
+% {true; it is a pseudonym}%
+% {% if not a pseudonym:
+% \IfFrontName[FNN]{SNN, Affix}[Alternate]% yes path
+% {\IfMainName[FNN]{SNN, Affix}[Alternate]%
+% {both}%
+% {front}%
+% }%
+% {\IfMainName[FNN]{SNN, Affix}[Alternate]% no path
+% {main}%
+% {does not exist}%
+% }%
+% }%
+% {excluded path}\end{verbatim}
+% \end{quote}
%
-% This default ``name scope'' behavior helps synchronize formatted and unformatted types of names. For example, one could use \cmd{\ForgetName} and \cmd{\SubvertName} in the footnote examples from Section~\ref{sec:formatting} to synchronize uses of names between formatting systems. This manual uses that approach at need.\medskip
+% We can use the text tag macros with the conditional macros to present information that depends on what names have already occurred. One must avoid unbounded recursion that results in a stack overflow (Section~\ref{sec:TextTags}):
+% \begin{quote}\small
+% \StartNum
+% \begin{verbatim}
+%\IndexRef{Paul}{Saul of Tarsus}
+%\NameAddInfo{Saul, of Tarsus}{\IfMainName{Jesus, Christ}
+% {\IfMainName[Lucius]{Sergius Paulus}
+% {renames himself \Name{Paul}}
+% {a preacher to the Gentiles}}
+% {wrote that he persecuted Christians}}
%
-% \DescribeMacro{\LocalNames}
-% \DescribeMacro{\GlobalNames}
-% If this default behavior is not desired, \cmd{\LocalNames} restricts the macros above to the current naming system. After \cmd{\LocalNames}, if you are in a ``front matter'' section (the \texttt{frontmatter} option or \cmd{\NamesInactive}) the macros above will affect only names in that section. The same is true if you are in a ``main matter'' section via the \texttt{mainmatter} option or \cmd{\NamesActive}. \cmd{\GlobalNames} restores the default behavior. Remember that this is respective to formatting systems, not document scope! Section~\ref{sec:LocalNames} goes into greater detail on system-level scoping.
+%\Name{Saul, of Tarsus} \NameQueryInfo{Saul, of Tarsus}. He
+%saw a vision of \Name{Jesus, Christ} on the road to Damascus
+%and became \NameQueryInfo{Saul, of Tarsus}. After converting
+%\Name[Lucius]{Sergius Paulus}, \Name{Saul, of Tarsus}
+%\NameQueryInfo{Saul, of Tarsus} in honor of that.\end{verbatim}
%
-% {\medskip\noindent\hbox{}\hfill\large Back to Section~\ref{sec:RefTables} \hfill\hbox{}}
-% \clearpage
+% \smallskip
+% \IndexRef{Paul}{Saul of Tarsus}
+% \NameAddInfo{Saul, of Tarsus}{\IfMainName{Jesus, Christ}
+% {\IfMainName[Lucius]{Sergius Paulus}
+% {renamed himself \Name{Paul}}
+% {a preacher to the Gentiles}}
+% {wrote that he persecuted Christians}}
%
-% \subsection{Name Variant Macros}
+% \Name{Saul, of Tarsus} \NameQueryInfo{Saul, of Tarsus}. He
+% saw a vision of \Name{Jesus, Christ} on the road to Damascus
+% and became \NameQueryInfo{Saul, of Tarsus}. After converting
+% \Name[Lucius]{Sergius Paulus}, \Name{Saul, of Tarsus}
+% \NameQueryInfo{Saul, of Tarsus} in honor of that.
+% \end{quote}
+%
+% Using these tests inside other macros or passing control sequences to them may create false results (see \textit{The \TeX book}, 212--15). That is why \textsf{nameauth} uses token registers to save name arguments (Section~\ref{sec:Hooksii}. Consider using \cmd{\noexpand} in macros passed as name arguments and see also Section~\ref{sec:Unicode}. Using the \textsf{trace} package, \cmd{\show}, or \cmd{\meaning} can help one mitigate problems.
+%
+% \ReturnLink
+% \newpage
+%
+% \subsection{Alternate Name Macros}
% \label{sec:AKA}
%
-% The\marginpar{\large\raggedleft\textsf{\bfseries 3.0}} macros in this section are specialized and have a somewhat different syntax than others in this manual. Macros like \cmd{\IndexRef} permit one to avoid the macros here completely. Yet here they are, if needed.\medskip
+% The\Version{3.0} macros in this section predate \cmd{\IndexRef} and have a syntax and behavior recalling early package versions.\footnote{Before version 3.0 the lack of modularity resulted in separate name parsing, name display, and indexing for the naming macros and the alternate name macros. The version 3 series has corrected many early missteps while remaining compatible.}
+% Using \cmd{\IndexRef} with \cmd{\Name} can be more flexible (cf. page~\pageref{page:ManualXref}). To save space, we show the syntax of these macros using \meta{SAFX} as the equivalent of \meta{SNN|,| Affix}. Common properties include:
%
+% \begin{itemize}
+% \item These macros do not create page references.
+% \item The target \oarg{FNN}\marg{SAFX} comes before the xref printed in the text: \oarg{xref FNN}\marg{xref SAFX}\oarg{xref Alternate}.
+% \item The obsolete syntax cannot be used with \oarg{FNN}\marg{SAFX}.
+% \item Only the \meta{SAFX} and \meta{xref SAFX} arguments are able to use comma-delimited suffixes.
+% \item One cannot use \cmd{\TagName} with a cross-reference, but one can sort it with \cmd{\PretagName}\oarg{xref FNN}\marg{xref SAFX}\marg{sort tag}.
+% \end{itemize}
+%
% \DescribeMacro{\AKA}
+% \cmd{\AKA} (\textit{also known as}) and its starred form display an alias in the text and create a cross-reference in the index.
% \DescribeMacro{\AKA*}
-% \cmd{\AKA} (meaning \textit{also known as}) handles the full-name mention of pseudonyms, stage names, \emph{noms de plume}, and so on. The syntax for \cmd{\AKA} is:
-% \begin{quote}\small\setstretch{1.1}
-% \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}
+% They display and format names differently than the name macros:
+% \begin{quote}\small
+% \fbox{\vbox{\hbox{\mystrut\ \cmd{\AKA\ }\oarg{FNN}\marg{SAFX}\oarg{xref FNN}\marg{xref SAFX}\oarg{xref Alternate} }\par
+% \hbox{\mystrut\ \cmd{\AKA*}\oarg{FNN}\marg{SAFX}\oarg{xref FNN}\marg{xref SAFX}\oarg{xref Alternate} }}}
% \end{quote}
-% Both macros create a cross-reference in the index from the \meta{Alt. FNN}, \meta{Alt. SNN}, and \meta{Alt. names} fields to a target defined by \meta{FNN} and \meta{SNN}, regardless of whether that name exists.
-% \textbf{The order of the name and cross-reference in \cmd{\AKA} is opposite that of \cmd{\IndexRef}.}\footnote{That ordering is due to the collision between \textbf{\meta{Alt\textsubscript{1}}} and \textbf{\meta{FNN\textsubscript{2}}} in a hypothetical \cmd{\AKA}\oarg{FNN\textsubscript{1}}\marg{SNN\textsubscript{1}}\ignorespaces%
-% \textbf{\oarg{Alt\textsubscript{1}}\oarg{FNN\textsubscript{2}}}\ignorespaces%
-% \marg{SNN\textsubscript{2}}\oarg{Alt\textsubscript{2}} By only allowing \meta{FNN\textsubscript{1}} and \meta{SNN\textsubscript{1}} for the target name, we can let the other fields permit an unrestricted cross-reference.}
-%See also Section~\ref{sec:indextag}.
%
-% \cmd{\AKA} only prints whatever form of name in the text that you manually specify. It is designed for the occasional mention of alternate names. See page~\pageref{page:manualxref} for alternate solutions. \cmd{\SeeAlso} works with \cmd{\AKA}, \cmd{\AKA*}, and \cmd{\PName}.
+% Both macros create a cross-reference in the index from the \meta{xref FNN}, \meta{xref SAFX}, and \meta{xref Alternate} arguments to a target defined by \meta{FNN} and \meta{SAFX}, regardless of whether that name exists. The order of the name and cross-reference in \cmd{\AKA} is opposite that of \cmd{\IndexRef}. Otherwise the \meta{xref Alternate} argument would be ambiguous with \meta{FNN}. \cmd{\AKA} prints a long form of the cross-reference name in the text. \cmd{\SeeAlso} works with \cmd{\AKA}, \cmd{\AKA*}, and \cmd{\PName}.
%
-% \cmd{\AKA} prints the \meta{Alt. FNN} and \meta{Alt. SNN} fields in the body text. If the \meta{Alt. names} field is present, \cmd{\AKA} swaps it with the \meta{Alt. FNN} field in the text. The caps and reversing macros work with \cmd{\AKA}.
+% \cmd{\AKA} prints the \meta{xref FNN} and \meta{xref SAFX} arguments in the body text. If \meta{xref Alternate} is present with \meta{xref FNN}, \cmd{\AKA} swaps them in the text. If \meta{xref Alternate} is present without \meta{xref FNN}, the old syntax is triggered, which we do not recommend. The caps and reversing macros work with \cmd{\AKA}.
%
-% \cmd{\AKA*}\marginpar{\large\raggedleft\textsf{\bfseries 3.0}} prints short name references like \cmd{\FName}, meaning that \cmd{\ForceFN} works with it in the same manner. For the older behavior of \cmd{\AKA*} use the \texttt{oldAKA} option or always precede \cmd{\AKA*} with \cmd{\ForceFN}.
+% \cmd{\AKA*}\Version{3.0} prints short name references like \cmd{\FName}, meaning that \cmd{\ForceFN} works with it in the same manner. For the older behavior of \cmd{\AKA*} use the \texttt{oldAKA} option or always precede \cmd{\AKA*} with \cmd{\ForceFN}.
%
-% \begin{center}\bfseries General Tips\end{center}
-% \begin{itemize}\small
-% \item \oarg{FNN}\marg{SNN} is the target. \oarg{Alt. FNN}\marg{Alt. SNN}\oarg{Alt. names} is the cross-reference to the target. Neither create page references.
-% \item The older non-Western syntax cannot be used with \oarg{FNN}\marg{SNN}. It can be used with \marg{Alt. SNN}\oarg{Alt. names}, but we discourage that.
-% \item Only the \meta{SNN} and \meta{Alt. SNN} fields use comma-delimited suffixes.
-% \item One cannot create an index tag for a cross-reference, but one can sort that reference with \cmd{\PretagName}.
-% \item \oarg{Alt. FNN}\marg{Alt. SNN}\oarg{Alt. names} in \cmd{\AKA} correspond to the name fields in \cmd{\PretagName}.
-% \item \DropAffix\Name*[J.E.]{Carter, Jr.}[Jimmy] is not a cross-reference when it takes a form like:\\\hbox{}\qquad |\DropAffix\Name*[J.E.]{Carter, Jr.}[Jimmy]|.
-% \item \AKA[J.E.]{Carter, Jr.}[Jimmy]{Carter} is a cross-reference when it takes a form like:\\\hbox{}\qquad |\AKA[J.E.]{Carter, Jr.}[Jimmy]{Carter}|.
-% \item To index stage names:\\\hbox{}\qquad |\Name[The Amazing]{Kreskin}|\dotfill \Name[The Amazing]{Kreskin}\\\hbox{}\qquad|\AKA[The| |Amazing]{Kreskin}| |[Joseph]{Kresge}|\dotfill \AKA[The Amazing]{Kreskin}[Joseph]{Kresge}
-% \item To keep stage names out of the index (index entries suppressed):{\IndexInactive\\\hbox{}\qquad |\Name[J.]{Kreskin}[The| |Amazing]|\dotfill \Name[J.]{Kreskin}[The Amazing]\\\hbox{}\qquad |\AKA[J.]{Kreskin}[Joseph]{Kresge}|\dotfill \AKA[J.]{Kreskin}[Joseph]{Kresge}}
-% \end{itemize}
-%
-% \begin{center}\bfseries Examples\end{center}
-% We make cross-references to \Name[Bob]{Hope}, where all of the forms below create the cross-reference ``Hope, Leslie Townes \emph{see} Hope, Bob'':
-% \begin{center}\small\setstretch{1.1}
+% We make cross-references to \Name[Bob]{Hope}, where all of the forms below create the cross-reference ``\ShowIdxPageref*[Leslie Townes]{Hope} \textit{see} \ShowIdxPageref*[Bob]{Hope}'':
+% \begin{center}\small\MyStretch
% \begin{tabular}{p{0.6\textwidth}l}\toprule
% \footnotesize|\AKA[Bob]{Hope}[Leslie Townes]{Hope}| & \AKA[Bob]{Hope}[Leslie Townes]{Hope}\\
-% \footnotesize|\RevComma\AKA[Bob]{Hope}[Leslie Townes]{Hope}| & \RevComma\AKA[Bob]{Hope}[Leslie Townes]{Hope}\\
-% \footnotesize|\AKA[Bob]{Hope}[Leslie Townes]{Hope}%| | [\ignorespaces]| & \AKA[Bob]{Hope}[Leslie Townes]{Hope}[\ignorespaces]\\
+% \rowcolor{black!7!white}\footnotesize|\RevComma\AKA[Bob]{Hope}[Leslie Townes]{Hope}| & \RevComma\AKA[Bob]{Hope}[Leslie Townes]{Hope}\\
% \footnotesize|\AKA[Bob]{Hope}[Leslie Townes]{Hope}[Lester T.]| & \AKA[Bob]{Hope}[Leslie Townes]{Hope}[Lester T.]\\
-% \footnotesize|\AKA*[Bob]{Hope}[Leslie Townes]{Hope}| & \AKA*[Bob]{Hope}[Leslie Townes]{Hope}\\
+% \rowcolor{black!7!white}\footnotesize|\AKA*[Bob]{Hope}[Leslie Townes]{Hope}| & \AKA*[Bob]{Hope}[Leslie Townes]{Hope}\\
% \footnotesize|\AKA*[Bob]{Hope}[Leslie Townes]{Hope}[Lester]| & \AKA*[Bob]{Hope}[Leslie Townes]{Hope}[Lester]\\\bottomrule
% \end{tabular}
% \end{center}
+% \newpage
%
-% Next we see what happens with references to \KeepAffix\Name*{Louis, XIV}, \Name{Lao-tzu}, and \KeepAffix\Name*{Gregory, I}, as well as \Name[Lafcadio]{Hearn} and \Name[Charles]{du Fresne}:
-% \begin{center}\small\setstretch{1.1}
+% Next we have references to \KeepAffix\Name*{Louis, XIV}, \Name{Lao-tzu}, and \KeepAffix\Name*{Gregory, I}, as well as \Name[Lafcadio]{Hearn} and \Name[Charles]{du Fresne}:
+% \begin{center}\small\MyStretch
% \begin{tabular}{p{0.6\textwidth}l}\toprule
% |\AKA{Louis, XIV}{Sun King}| & \AKA{Louis, XIV}{Sun King}\\
-% |\AKA*{Louis, XIV}{Sun King}| & \AKA{Louis, XIV}{Sun King}\\\midrule
+% \rowcolor{black!7!white}|\AKA*{Louis, XIV}{Sun King}| & \AKA{Louis, XIV}{Sun King}\\
% |\AKA{Lao-tzu}{Li, Er}| & \AKA{Lao-tzu}{Li, Er}\\
-% |\AKA*{Lao-tzu}{Li, Er}| & \AKA*{Lao-tzu}{Li, Er}\\\midrule
+% \rowcolor{black!7!white}|\AKA*{Lao-tzu}{Li, Er}| & \AKA*{Lao-tzu}{Li, Er}\\
% |\AKA[Charles]{du Fresne}{du Cange}| & \AKA[Charles]{du Fresne}{du Cange}\\
-% |\CapThis\AKA[Charles]{du Fresne}{du Cange}| & \CapThis\AKA[Charles]{du Fresne}{du Cange}\\\midrule
+% \rowcolor{black!7!white}|\CapThis\AKA[Charles]{du Fresne}{du Cange}| & \CapThis\AKA[Charles]{du Fresne}{du Cange}\\
% \footnotesize|\CapName\AKA[Lafcadio]{Hearn}{Koizumi, Yakumo}| & \CapName\AKA[Lafcadio]{Hearn}{Koizumi, Yakumo}\\
-% \footnotesize|\RevName\AKA[Lafcadio]{Hearn}{Koizumi, Yakumo}| & \RevName\AKA[Lafcadio]{Hearn}{Koizumi, Yakumo}\\\midrule
+% \rowcolor{black!7!white}\footnotesize|\RevName\AKA[Lafcadio]{Hearn}{Koizumi, Yakumo}| & \RevName\AKA[Lafcadio]{Hearn}{Koizumi, Yakumo}\\
% \footnotesize|\AKA{Gregory, I}{Gregory}[the Great]| & \AKA{Gregory, I}{Gregory}[the Great]\\
-% \footnotesize|\AKA*{Gregory, I}{Gregory}[the Great]| & \AKA*{Gregory, I}{Gregory}[the Great]\\
+% \rowcolor{black!7!white}\footnotesize|\AKA*{Gregory, I}{Gregory}[the Great]| & \AKA*{Gregory, I}{Gregory}[the Great]\\
% \footnotesize|\ForceFN\AKA*{Gregory, I}{Gregory}[the Great]| & \ForceFN\AKA*{Gregory, I}{Gregory}[the Great]\\\bottomrule
% \end{tabular}
-% \end{center}
+% \end{center}\medskip
%
-% \begin{center}\bfseries Formatting Alternate Names: General\end{center}
-% \cmd{\AKA}\marginpar{\small\raggedleft\texttt{formatAKA}\break\dbend} and its derivatives use the subsequent-use formatting hooks \cmd{\MainNamesHook} and \cmd{\FrontNamesHook}. This was designed originally to keep cross-references from looking like main names by accident when they were intriduced in the body text. In order to be freed of those constraints, use the \texttt{formatAKA} package option. Note the caveats that come therewith.
+% \noindent\cmd{\AKA}\Info{\texttt{formatAKA}} and its derivatives use \cmd{\MainNamesHook} and \cmd{\FrontNamesHook} to print the cross-reference because that helped keep cross-references distinct from names in early package versions.
+%
+% The \texttt{formatAKA} package option allows first-use formatting of alternate names, but cross-references use their own system for being ``first'' (Section~\ref{sec:NamePatterns}). We simulate \texttt{formatAKA} and use |\AKA{Elizabeth,I}[Good Queen]{Bess}|. The colors indicate which hooks are used.
+% \begin{quote}\small\MyStretch
+% \makeatletter\@nameauth at AKAFormattrue\makeatother\NamesInactive
+% \emph{Front Matter:} \ForgetThis\LEliz\ was known as ``\AKA{Elizabeth,I}[Good Queen]{Bess}.''\\
+% Again we mention Queen \Eliz, ``\AKA{Elizabeth, I}[Good Queen]{Bess}.''\\
+% \cmd{\ForceName}: \ForceName\AKA{Elizabeth, I}[Good Queen]{Bess}.
%
-% We show \texttt{formatAKA} used with |\AKA{Elizabeth, I}[Good Queen]{Bess}|. The colors indicate which formatting hooks are being used.\ignorespaces%
-% \begin{quote}\small\setstretch{1.1}
-% \makeatletter\@nameauth at AKAFormattrue\makeatother
-% \NamesInactive \textbf{Front Matter:} \ForgetThis\LEliz\ was known as ``\AKA{Elizabeth, I}[Good Queen]{Bess}.''\\
+% \NamesActive
+% \emph{Main Matter:} \ForgetThis\LEliz\ was known as ``\AKA{Elizabeth,I}[Good Queen]{Bess}.''\\
% Again we mention Queen \Eliz, ``\AKA{Elizabeth, I}[Good Queen]{Bess}.''\\
-% \cmd{\ForceName}: \ForceName\AKA{Elizabeth, I}[Good Queen]{Bess}.\\[1ex]
-% \NamesActive \textbf{Main Matter:} \ForgetThis\LEliz\ was known as ``\AKA{Elizabeth, I}[Good Queen]{Bess}.''\\
-% Again we mention Queen \Eliz, ``\AKA{Elizabeth, I}[Good Queen]{Bess}.''\\
% \cmd{\ForceName}: \ForceName\AKA{Elizabeth, I}[Good Queen]{Bess}.
% \end{quote}
-% Section~\ref{sec:tweaks} also shows how cross-references are independent of other data sets in \textsf{nameauth}. Cross-references do not respect the two namng systems. The first time that the cross-reference appears, we see that \texttt{formatAKA} permits the first-use hooks. Thereafter, it uses the subsequent-use hooks. When we switched to the main matter, the cross-reference \AKA{Elizabeth, I}[Good Queen]{Bess} did not switch to a first use until we used \cmd{\ForceName}. Now we compare the \texttt{alwaysformat} option:
%
-% \begin{quote}\small\setstretch{1.1}
-% \makeatletter\@nameauth at AlwaysFormattrue\makeatother
-% \NamesInactive \textbf{Front Matter:} \ForgetThis\LEliz\ was known as ``\AKA{Elizabeth, I}[Good Queen]{Bess}.''\\
+% The first appearance of the cross-reference uses the first-use hooks of whatever naming system is active. Thereafter we only use the subsequent-use hooks of both systems unless we use \cmd{\ForceName}.\medskip
+%
+% Below\Info{\texttt{alwaysformat}} we compare the behavior of the \texttt{alwaysformat} option, where all regular names use only \cmd{\NamesFormat} and \cmd{\FrontNamesFormat}:
+%
+% \begin{quote}\small\MyStretch
+% \makeatletter\@nameauth at AlwaysFormattrue\makeatother\NamesInactive
+% \emph{Front Matter:} \ForgetThis\LEliz\ was known as ``\AKA{Elizabeth, I}[Good Queen]{Bess}.''\\
% Again we mention Queen \Eliz, ``\AKA{Elizabeth, I}[Good Queen]{Bess}.''\\
-% \cmd{\ForceName}: \ForceName\AKA{Elizabeth, I}[Good Queen]{Bess}.\\[1ex]
-% \NamesActive \textbf{Main Matter:} \ForgetThis\LEliz\ was known as ``\AKA{Elizabeth, I}[Good Queen]{Bess}.''\\
+% \cmd{\ForceName}: \ForceName\AKA{Elizabeth, I}[Good Queen]{Bess}.
+%
+% \NamesActive
+% \emph{Main Matter:} \ForgetThis\LEliz\ was known as ``\AKA{Elizabeth, I}[Good Queen]{Bess}.''\\
% Again we mention Queen \Eliz, ``\AKA{Elizabeth, I}[Good Queen]{Bess}.''\\
% \cmd{\ForceName}: \ForceName\AKA{Elizabeth, I}[Good Queen]{Bess}.
% \end{quote}
%
-% With \texttt{alwaysformat}, all the names in the document use only the first-use hooks, never the subsequent-use hooks. This option tends to get little use in the newer versions of \textsf{nameauth}. It was more useful in early versions when \cmd{\NamesFormat} was the only formatting hook.
-%
-% \begin{center}\bfseries Formatting Alternate Names: Continental\end{center}
-% \noindent The following annotated example shows the simple Continental form that we introduced in Section~\ref{sec:altformat}. We initiate the alternate formatting framework with \cmd{\AltFormatActive} and take care not to use the names below outside of it.\AltFormatActive
-% \begin{enumerate}
-% \item Tag the names for proper sorting.\\[4pt]
-% |\PretagName[Heinz]{\textSC{Rühmann}}{Ruehmann, Heinz}%|\\
-% |\PretagName[Heinrich Wilhelm]{\textSC{Rühmann}}%|\\
-% | {Ruehmann, Heinrich Wilhelm}%|
-% \item ``\Name*[Heinz]{\textSC{Rühmann}}'' is the main name, but we do not start with that. We begin with \cmd{\AKA*} in order to use his legal name as an alias for his more popular stage name. \cmd{\AKA*} prints ``\AKA*[Heinz]{\textSC{Rühmann}}[Heinrich Wilhelm]{\textSC{Rühmann}}'' in the body text and sets up the index cross-reference ``\textsc{Rühmann}, Heinrich Wilhelm \emph{see} \textsc{Rühmann}, Heinz.''\\[4pt]
-% |\AKA*[Heinz]{\textSC{Rühmann}}%|\\
-% | [Heinrich Wilhelm]{\textSC{Rühmann}} %|
-% \item \cmd{\SubvertThis} makes \cmd{\FName} print \SubvertThis``\FName[Heinz]{\textSC{Rühmann}}.''\\[4pt]
-% |\SubvertThis``\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}}| |(7| |March| |1902\,--\,3%|\\
-% |October 1994)| |was| |a| |German| |actor| |in| |over| |100| |films.|
-% \end{enumerate}
-% The resulting text is:
-% \begin{quote}\small
-% \AKA*[Heinz]{\textSC{Rühmann}}[Heinrich Wilhelm]{\textSC{Rühmann}} \ignorespaces%
-% \SubvertThis``\FName[Heinz]{\textSC{Rühmann}}'' \ignorespaces%
-% \Name[Heinz]{\textSC{Rühmann}} (7 March 1902\,--\,3 October \ignorespaces%
-% 1994) was a German actor in over 100 films.
-% \end{quote}
-% Of course, this example is but one among a number of solutions. The point is to find a solution that best fits one's needs. We now resume normal formatting with \cmd{\AltFormatInactive}.
-% \AltFormatInactive
-% \clearpage
-%
-% \phantomsection\label{page:manualxref}
-% \begin{center}\bfseries Advanced Cross-Referencing\end{center}
-% \noindent \cmd{\AKA}\marginpar{\large\raggedleft\textsf{\bfseries 3.0}\strut} will not create multiple cross-references. Handle the special case where one moniker applies to multiple people with \cmd{\IndexRef}, \emph{e.g.}, ``Snellius'' for both \Name[W.]{Snel van Royen}[Willebrord] and his son \Name[R.]{Snel van Royen}[Rudolph]:\footnote{We shorten the index entries via \cmd{\Name}\texttt{[W.]\{Snel van Royen\}[Willebrord]}, and for his son, \cmd{\Name}\texttt{[R.]\{Snel van Royen\}[Rudolph]}.}
-% \begin{quote}\small
-% |\IndexRef{Snellius}{Snel| |van| |Royen,| |R.;| |Snel| |van| |Royen,| |W.}|
-% \IndexRef{Snellius}{Snel van Royen, R.; Snel van Royen, W.}
-% \end{quote}
-%
-% \cmd{\AKA} and \cmd{\AKA*} never create never page entries. When the alternate name needs to be indexed with page numbers and \emph{see also} references, do the following:
-% \begin{itemize}\small
-% \item Refer to the person intended, \emph{e.g.}:\\ \hbox{}\qquad\Name{Maimonides} (\AKA{Maimonides}{Moses ben-Maimon}):\\ \hbox{}\qquad|\Name{Maimonides}| |(\AKA{Maimonides}{Moses| |ben-Maimon})|
-% \item We now have a main name with a page entry, as well as a ``\emph{see} reference'' name. If we fail to refer to the main name, we would have a cross-reference to an entry that does not exist.
-% \item Before creating a \emph{see also} cross-reference, one must refer to the alternate name so that all the page entries precede the cross-reference, \emph{e.g.}:\\ \hbox{}\qquad\Name{Rambam}\qquad|\Name{Rambam}|
-% \item For\marginpar{\large\raggedleft\textsf{\bfseries 3.0}\strut} whatever name you use for the \emph{see also} reference, put the cross-reference after all of the page references. For example, you could put both of these macros at the end of the document:\footnote{Different standards exist for punctuating index entries and cross-references. Check with your publisher, style guide, docs for \textsf{xindy} and \textsf{makeindex}, and \url{http://tex.stackexchange.com}.}\\\hbox{}\qquad|\SeeAlso\IndexRef{Maimonides}{Rambam}|\\\hbox{}\qquad|\SeeAlso\IndexRef{Rambam}{Maimonides}|
-% \item You could let the last reference to either name be handled by \cmd{\SeeAlso}\cmd{\AKA}, but that could be more confusing and prone to error.
-% \end{itemize}
-% \SeeAlso\IndexRef{Maimonides}{Rambam}%
-% \SeeAlso\IndexRef{Rambam}{Maimonides}%
-%
-% Using \cmd{\PretagName} (Section~\ref{sec:IndexSort}) helps to avoid the need for manual index entries, as the following example shows:
-%
-% \begin{quote}\small\setstretch{1.1}
-% {\ttfamily%
-% |\PretagName{\textit{Doctor| |angelicus}}{Doctor| |angelicus}|\\
-% |Perhaps| |the| |greatest| |medieval| |theologian was %|\\
-% |\Name{Thomas,| |Aquinas}, also known as %|\\
-% |\AKA{Thomas, Aquinas}{\textit{Doctor angelicus}}|.}
-%
-% \PretagName{\textit{Doctor angelicus}}{Doctor Angelicus}
-% Perhaps the greatest medieval theologian was
-% \Name{Thomas, Aquinas}, also known as %
-% \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, use it as such. Section~\ref{sec:standards} talks about how one can use |\ForceFN\FName{Thomas, Aquinas}| to refer to \ForceFN\FName{Thomas, Aquinas}. Using |\ForceFN\Name{Thomas, Aquinas}| will produce \ForceFN\Name{Thomas, Aquinas}. That helps prevent unwanted side effects with Eastern names.
-% \clearpage
-%
% \DescribeMacro{\PName}
+% These convenience macros (an early feature) print a main name and a cross-reference in parentheses:
% \DescribeMacro{\PName*}
-% These macros were meant for Western names and developed in the early versions of \textsf{nameauth}. They no longer fit well with the package. They print a main name followed by a cross-reference in parentheses, the syntax being:
% \begin{quote}\small
-% \cmd{\PName}\oarg{FNN}\marg{SNN}\oarg{other FNN}\marg{other SNN}\oarg{other alt.}
+% \fbox{\vbox{\hbox{\mystrut\cmd{\PName\ }\oarg{FNN}\marg{SAFX}\oarg{xref\,FNN}\marg{xref\,SAFX}\oarg{xref\,Alternate}}\par
+% \hbox{\mystrut\cmd{\PName*}\oarg{FNN}\marg{SAFX}\oarg{xref\,FNN}\marg{xref\,SAFX}\oarg{xref\,Alternate}}}}
% \end{quote}
-%
-% Apart from \cmd{\SkipIndex}, prefix macros only work on the name given by \meta{FNN} and \meta{SNN}, not on the latter cross-reference. \cmd{\SkipIndex} keeps both names out of the index. Below we see the only name types that this macro can handle:
-% \begin{quote}\footnotesize\setstretch{1.1}
-% |\PName[Mark]{Twain}[Samuel L.]{Clemens}|\hfill \PName[Mark]{Twain}[Samuel L.]{Clemens}\\
-% \hbox{}\hfill \PName[Mark]{Twain}[Samuel L.]{Clemens}\\
-% |\PName*[Mark]{Twain}[Samuel L.]{Clemens}[Sam]|\hfill \PName*[Mark]{Twain}[Samuel L.]{Clemens}[Sam]\\[1ex]
-% |\PName{Voltaire}[François-Marie]{Arouet}|\hfill \PName{Voltaire}[François-Marie]{Arouet}\\
-% \hbox{}\hfill \PName{Voltaire}[François-Marie]{Arouet}\\[1ex]
-% |\PretagName{\textit{Doctor mellifluus}}{Doctor mellifluus}|\\
-% |\PName{Bernard, of Clairvaux}{\textit{Doctor mellifluus}}|\\
-% \PretagName{\textit{Doctor mellifluus}}{Doctor mellifluus}
-% \hbox{}\hfill \PName{Bernard, of Clairvaux}{\textit{Doctor mellifluus}}\\
-% \hbox{}\hfill \PName{Bernard, of Clairvaux}{\textit{Doctor mellifluus}}
-% \end{quote}
-%
-% Like \cmd{\AKA}, \cmd{\PName} cannot use the older syntax \marg{SNN}\oarg{FNN} for the main name, but it can do so for the alternate name.
-%
-% |\PName{William,| |I}{William,| |the Conqueror}| gives \PName{William, I}{William, the Conqueror} and \PName{William, I}{William, the Conqueror}.\footnote{The form \texttt{\textbackslash PName\{William, I\}\{William\}[the Conqueror]} works, but we discourage it. Also choose forms like \texttt{\textbackslash PName\{Lao-tzu\}\{Li, Er\}} instead of \texttt{\textbackslash PName\{Lao-tzu\}\{Li\}[Er]}. Avoiding the older syntax with \cmd{\AKA} and \cmd{\PName} avoids error.}
-% If you use \cmd{\PName*}, again you will get the long reference \PName*{William, I}{William}[the Conqueror].
-%
-% |\PName*{William, I}[William]{the Conqueror}| puts \SkipIndex``\PName*{William, I}[William]{the Conqueror}'' in the body text, but its index entry will be ``the Conqueror, William \emph{see} William I.'' This is a result of mixing medieval and Western forms. We suppressed the index entry with \cmd{\SkipIndex}.
-%
-% {\medskip\noindent\hbox{}\hfill\large Back to Section~\ref{sec:RefTables} \hfill\hbox{}}
-%
-% \subsection{Longer Examples}
-%
-% \subsubsection{Variant Names}
-% \label{sec:DuBois}
-% This section\marginpar{\large\raggedleft\textsf{\bfseries 3.1}\strut} demonstrates how \textsf{nameauth} helps one manage a name authority. Handling name variants has become easier than before. We start with some simple cases and move on to complex ones:
-%
-% \newcommand*\Iron{\SubvertThis\Name*[Mike]{Tyson}[Iron Mike]}
-% \begin{itemize}\small
-% \item Where |Iron Mike| occurs in the text, include |\IndexName[Mike]{Tyson}|.
-% \item |\SubvertThis\FName[Mike]{Tyson}[Iron Mike]| always prints \SubvertThis\FName[Mike]{Tyson}[Iron Mike] indexed as ``Tyson, Mike''. That form uses the subsequent-use formatting hooks. |\ForceName\SubvertThis\FName[Mike]{Tyson}[Iron Mike]| prints \ForceName\SubvertThis\FName[Mike]{Tyson}[Iron Mike] with the first-use hooks.
-% \item The form \cmd{\Iron} \SubvertThis\Name*[Mike]{Tyson}[Iron Mike] can be set up with:\\[1ex]
-% |\newcommand*\Iron{\SubvertThis\Name*[Mike]{Tyson}[Iron Mike]}|\\[1ex]
-% In \textsf{nameauth} it makes little sense to ``force'' the subsequent use because it is the common use. First uses are rare. That is why we set up the subsequent use with \cmd{\SubvertThis} and create a first use when needed with \cmd{\ForceName}. |\ForceName\Iron| prints \ForceName\Iron, again indexed as ``Tyson, Mike''.
-% \item Use |\IndexRef{Iron Mike}{Tyson, Mike}| to create a \emph{see} cross-reference from ``Iron Mike'' to ``Tyson, Mike'' in the index. Be sure to have an occurrence of |\Name[Mike]{Tyson}| in the text.
-% \item Use |``\AKA[Mike]{Tyson}{Iron Mike}''| to create ``\AKA[Mike]{Tyson}{Iron Mike}'' in the text and a cross-reference to ``Tyson, Mike'' in the index. Be sure to have an occurrence of |\Name[Mike]{Tyson}| in the text.
-% \end{itemize}
-%
-% When you want alternate names that can change form and format independently, do the following:
-% \begin{nameauth}
-% \< DuBois & W.E.B. & Du Bois & >
-% \< AltDuBois & W.E.B. & Du\empty Bois & >
-% \end{nameauth}
-% \begin{enumerate}\small
-% \item We start by deciding that the canonical name form we wish to use is ``W.E.B. Du Bois.'' We want to manage the alternate form ``W.E.B. DuBois'' as if it were an occurrence of the canonical name. We set up the name authority:\\
-% |\begin{nameauth}|\\
-% | \< DuBois & W.E.B. & Du Bois & >|\\
-% | \< AltDuBois & W.E.B. & Du\empty Bois & >|\\
-% |\end{nameauth}|
-%
-% \item This name gives us an extra level of difficulty because the two variants differ only in terms of spaces. They share the same internal representation in the \textsf{nameauth} macros: |W.E.B.!DuBois|. We fix this ambiguity by inserting a non-printing control sequence in the alternate form, such as |{Du\empty Bois}|. That prevents ``{Du\empty Bois}'' from breaking at the end of a line or page. A discretionary hyphen would allow the name to break.\footnote{Ignoring spaces in names is good because it aids fault tolerance, thereby decreasing spurious index entries. Here we have a special case where this behavior is not useful.}
-%
-% \item Instead of using \cmd{\SkipIndex}\cmd{\AltDuBois} every time we wanted to avoid making an index entry, we create a cross-reference in the index from the alternate name to the canonical name:\\
-% | \IndexRef[W.E.B.]{Du\empty Bois}{Du Bois, W.E.B.}|
-%
-% \IndexRef[W.E.B.]{Du\empty Bois}{Du Bois, W.E.B.}From this point onward, no page entry for \AltDuBois\ will occur in the index unless manipulated by \cmd{\IncludeName*}. The canonical \DuBois\ functions as a different name and is not affected.
-% \end{enumerate}
-%
-% Indexing\marginpar{\large\raggedleft\textsf{\bfseries 3.0}\strut} both name forms would be trivial. One can use both forms at need to generate page references in the index. After all of the page references are done, one can create cross-references with \cmd{\SeeAlso}\cmd{\IndexRef}.
-%
-% Indexing\marginpar{\large\raggedleft\textsf{\bfseries 3.1}\strut} with the canonical name form \DuBois\ whenever we see \AltDuBois\ is slightly more complicated:
-%
-% \begin{itemize}\small
-% \item We no longer wrap each name automatically with two index entries, so we would need to keep track of page breaks and this alternate name.
-% \item We could use |\JustIndex\DuBois\AltDuBois| to get \JustIndex\DuBois\AltDuBois.
-% \item We could create macros based on that:\\
-% |\global\newcommand*\OtherDuBois{\JustIndex\DuBois\AltDuBois}|\\
-% |\global\newcommand*\LOtherDuBois{\JustIndex\DuBois\LAltDuBois}|\\
-% |\global\newcommand*\SOtherDuBois{\JustIndex\DuBois\SAltDuBois}|
-% \end{itemize}
-% \global\newcommand*\OtherDuBois{\JustIndex\DuBois\AltDuBois\JustIndex\DuBois}
-% \global\newcommand*\LOtherDuBois{\JustIndex\DuBois\LAltDuBois\JustIndex\DuBois}
-% \global\newcommand*\SOtherDuBois{\JustIndex\DuBois\SAltDuBois}
-%
-% With |\ForgetThis\OtherDuBois| we get \ForgetThis\OtherDuBois\ and \OtherDuBois\ thereafter. |\LOtherDuBois| gives us \LOtherDuBois, while with |\SOtherDuBois| we get \SOtherDuBois. The extra full stop at the end of the sentence was gobbled. We used \cmd{\global} to ensure that, regardless of scope, our macros work.
-%
-% {\medskip\noindent\hbox{}\hfill\large Back to Section~\ref{sec:RefTables} \hfill\hbox{}}
-%
-% \subsubsection{\texttt{\textbackslash LocalNames}}
-% \label{sec:LocalNames}
-%
-% As mentioned previously in Section~\ref{sec:tweaks}, both \cmd{\ForgetName} and \cmd{\SubvertName} usually affect both main-matter and front-matter names. This default behavior can be quite helpful. Nevertheless, there are cases where it is undesirable. This section shows \cmd{\Localnames} and \cmd{\Globalnames} in action, limiting the behavior of the ``tweaking macros'' to either the main or front matter.
-%
-% We begin by defining a macro that will report to us whether a name exists in the main matter, front matter, both, or none:
-% \def\CheckChuck{\IfFrontName[Charlie]{Chaplin}%
-% {\IfMainName[Charlie]{Chaplin}{both}{front}}%
-% {\IfMainName[Charlie]{Chaplin}{main}{none}}}%
-% \begin{quote}\small\setstretch{1.1}
-% |\def\CheckChuck{%\IfFrontName[Charlie]{Chaplin}%|\\
-% | {\IfMainName[Charlie]{Chaplin}{both}{front}}%|\\
-% | {\IfMainName[Charlie]{Chaplin}{main}{none}}}%|
-% \end{quote}
-% Next we create a formatted name in the ``main matter'':
-% \begin{quote}\small\setstretch{1.1}
-% |\Name*[Charlie]{Chaplin}|\hfill\Name*[Charlie]{Chaplin}\qquad\qquad\qquad\hbox{}\\
-% |\CheckChuck|\hfill\CheckChuck\qquad\qquad\qquad\hbox{}
-% \end{quote}
-% Now we switch to ``front-matter'' text and create a name. To ignore any local scoping we use \cmd{\global}\cmd{\NamesInactive}:
-% \begin{quote}\small\setstretch{1.1}
-% |\global\NamesInactive|\global\NamesInactive\\
-% |\Name*[Charlie]{Chaplin}|\hfill\Name*[Charlie]{Chaplin}\qquad\qquad\qquad\hbox{}\\
-% |\CheckChuck|\hfill\CheckChuck\qquad\qquad\qquad\hbox{}
-% \end{quote}
-% We now have two names. They look and behave the same, but are two different ``species'' with independent first and subsequent uses. We use \cmd{\Localnames} to make \cmd{\ForgetName} and \cmd{\SubvertName} work with only the front-matter species. Then we ``forget'' the front-matter name:
-% \begin{quote}\small\setstretch{1.1}
-% |\LocalNames|\LocalNames\\
-% |\ForgetName[Charlie]{Chaplin}|\ForgetName[Charlie]{Chaplin}\\
-% |\CheckChuck|\hfill\CheckChuck\qquad\qquad\qquad\hbox{}
-% \end{quote}
-% Next we ``subvert'' the front-matter name to ``remember'' it again and switch to the main section, again using \cmd{\global} to ignore scoping. Now \cmd{\ForgetName} and \cmd{\SubvertName} are working with the main-matter species.
-% \begin{quote}\small\setstretch{1.1}
-% |\SubvertName[Charlie]{Chaplin}|\SubvertName[Charlie]{Chaplin}\\
-% |\global\NamesActive|\global\NamesActive\\
-% |\CheckChuck|\hfill\CheckChuck\qquad\qquad\qquad\hbox{}
-% \end{quote}
-% We forget the main-matter name and additionally reset the default behavior so that \cmd{\ForgetName} and \cmd{\SubvertName} work with both species:
-% \begin{quote}\small\setstretch{1.1}
-% |\ForgetName[Charlie]{Chaplin}|\ForgetName[Charlie]{Chaplin}\\
-% |\GlobalNames|\GlobalNames\\
-% |\CheckChuck|\hfill\CheckChuck\qquad\qquad\qquad\hbox{}
-% \end{quote}
-% Finally, we forget everything. Even though we are in a main-matter section, the front-matter control sequence goes away:
-% \begin{quote}\small\setstretch{1.1}
-% |\ForgetName[Charlie]{Chaplin}|\ForgetName[Charlie]{Chaplin}\\
-% |\CheckChuck|\hfill\CheckChuck\qquad\qquad\qquad\hbox{}
-% \end{quote}
-% \clearpage
-%
-% \subsubsection{Unicode + \textsf{inputenc}}
-% \label{sec:Unicode}
-%
-% The following subset of active Unicode characters are available ``out of the box'' using NFSS, \textsf{inputenc}, and \textsf{fontenc}:
-%
-% \begin{center}\setstretch{1.1}
-% \begin{tabular}{lll}\toprule
-% À Á Â Ã Ä Å Æ & Ç È É Ê Ë & Ì Í Î Ï Ð Ñ \\
-% Ò Ó Ô Õ Ö Ø & Ù Ú Û Ü Ý & Þ ß \\
-% à á â ã ä å æ & ç è é ê ë & ì í î ï ð ñ \\
-% ò ó ô õ ö ø & ù ú û ü ý & þ ÿ \\
-% Ă ă Ą ą Ć ć Č č & Ď ď Đ đ Ę ę Ě ě & Ğ ğ İ ı \\
-% IJ ij Ľ ľ Ł ł & Ń ń Ň ň Œ œ & Ŕ ŕ Ř ř \\
-% Ś Ş ş Š š Ţ ţ Ť ť & Ů ů Ű ű & Ź ź Ż ż Ž ž \\\bottomrule
+% The starred form \cmd{\PName*} is like the starred form \cmd{\Name*} to the extent that it prints a long form of \meta{FNN}\meta{SAFX}. It does not affect the cross-reference arguments \meta{xref FNN}\meta{xref SAFX}\meta{xref Alternate}.
+%
+% Except \cmd{\SkipIndex}, prefix macros only affect \meta{FNN}\meta{SAFX}, not the cross-reference, which always takes a long form. \cmd{\SkipIndex} keeps both names out of the index. \cmd{\PName} cannot use the obsolete syntax for the main name, but it can do so for the alternate name.
+%
+% \begin{center}\footnotesize\MyStretch
+% \begin{tabular}{p{0.45\textwidth}l}\toprule
+% \bfseries\small Recommended Macro\,/\,Output & \bfseries\small Index\\\midrule
+% |\PName[Mark]{Twain}%|\newline| [Samuel L.]{Clemens}| & \\
+% \PName[Mark]{Twain}[Samuel L.]{Clemens} & \ShowIdxPageref*[Samuel L.]{Clemens} \textit{see} \ShowIdxPageref*[Mark]{Twain}\\
+% \PName[Mark]{Twain}[Samuel L.]{Clemens} & \ShowIdxPageref*[Samuel L.]{Clemens} \textit{see} \ShowIdxPageref*[Mark]{Twain}\\
+% \rowcolor{black!7!white}|\PName*[Mark]{Twain}%|\newline| [Samuel L.]{Clemens}[Sam]| & \\
+% \rowcolor{black!7!white}\PName*[Mark]{Twain}[Samuel L.]{Clemens}[Sam] & \ShowIdxPageref*[Samuel L.]{Clemens} \textit{see} \ShowIdxPageref*[Mark]{Twain}\\
+% |\PName{Voltaire}%|\newline| [François-Marie]{Arouet}| & \\
+% \PName{Voltaire}[François-Marie]{Arouet} & \ShowIdxPageref*[François-Marie]{Arouet} \textit{see} \ShowIdxPageref*{Voltaire}\\
+% \PName{Voltaire}[François-Marie]{Arouet} & \ShowIdxPageref*[François-Marie]{Arouet} \textit{see} \ShowIdxPageref*{Voltaire}\\
+% \rowcolor{black!7!white}|\PName{William, I}%|\newline| {William, the Conqueror}| & \\
+% \rowcolor{black!7!white}\PName{William, I}{William, the Conqueror} & \ShowIdxPageref*{William, the Conqueror} \textit{see} \ShowIdxPageref*{William, I}\\
+% \rowcolor{black!7!white}\PName{William, I}{William, the Conqueror} & \ShowIdxPageref*{William, the Conqueror} \textit{see} \ShowIdxPageref*{William, I}\\
+% |\PName*{William, I}%|\newline| {William, the Conqueror}| & \\
+% \PName*{William, I}{William, the Conqueror} & \ShowIdxPageref*{William, the Conqueror} \textit{see} \ShowIdxPageref*{William, I}\\
+% \rowcolor{black!7!white}|\PretagName%|\newline| {\textit{Doctor mellifluus}}%|\newline| {Doctor mellifluus}| & \\
+% \rowcolor{black!7!white}|\PName{Bernard, of Clairvaux}%|\newline| {\textit{Doctor mellifluus}}| & \\
+% \rowcolor{black!7!white}\PName{Bernard, of Clairvaux}{\textit{Doctor mellifluus}} & \ShowIdxPageref*{\textit{Doctor mellifluus}} \textit{see} \ShowIdxPageref*{Bernard, of Clairvaux}\\
+% \rowcolor{black!7!white}\PName{Bernard, of Clairvaux}{\textit{Doctor mellifluus}} & \ShowIdxPageref*{\textit{Doctor mellifluus}} \textit{see} \ShowIdxPageref*{Bernard, of Clairvaux}\\
+% |\ForgetThis\PName{Lao-tzu}{Li, Er}| & \\
+% \ForgetThis\PName{Lao-tzu}{Li, Er} & \ShowIdxPageref*{Li, Er} \textit{see} \ShowIdxPageref*{Lao-tzu}\\
+% \PName{Lao-tzu}{Li, Er} & \ShowIdxPageref*{Li, Er} \textit{see} \ShowIdxPageref*{Lao-tzu}\\\midrule
+% \bfseries\small Discouraged Macro\,/\,Output & \bfseries\small Index\\\midrule
+% |\PName{William, I}{William}%|\newline| [the Conqueror]| & \\
+% \PName{William, I}{William}[the Conqueror] & \ShowIdxPageref*{William}[the Conqueror] \textit{see} \ShowIdxPageref*{William, I}\\
+% \rowcolor{black!7!white}|\PName{Lao-tzu}{Li}[Er]| & \\
+% \rowcolor{black!7!white}\PName{Lao-tzu}{Li}[Er] & \ShowIdxPageref*{Li}[Er] \textit{see} \ShowIdxPageref*{Lao-tzu}\\\bottomrule
% \end{tabular}
% \end{center}
%
-% Some\marginpar{\small\raggedleft\dbend} of these characters expand differently, which can affect index sorting. For example, \texttt{ä} becomes \texttt{\cmd{\IeC\textvisiblespace}\{\cmd{\"a}\}} and \texttt{Æ} becomes \texttt{\cmd{\IeC\textvisiblespace}\{\cmd{\AE\textvisiblespace}\}}. Additional accents and glyphs can be used with Unicode input, NFSS, \textsf{inputenc}, and \textsf{fontenc} when using fonts with TS1 glyphs, \emph{e.g.}, |\usepackage{lmodern}| (per the table on pages 455--63 in \emph{The Latex Companion}). The following example lets you type, ``In Congreſs, July 4, 1776.''
-% \begin{quote}\small\setstretch{1.1}
-% |\usepackage{newunicodechar}|\\
-% |\DeclareTextSymbolDefault{\textlongs}{TS1}|\\
-% |\DeclareTextSymbol{\textlongs}{TS1}{115}|\\
-% |\newunicodechar{ſ}{\textlongs}|
-% \end{quote}
+% The newer non-Western syntax does not work with \cmd{\PName}. If we attempted to use |\SkipIndex\PName*{William, I}[William]{the Conqueror}|, this macro would put ``\SkipIndex\PName*{William, I}[William]{the Conqueror}'' in the body text, but its index entry would be incorrect: ``\ShowIdxPageref*[William]{the Conqueror} \textit{see} \ShowIdxPageref*{William, I}''.
+%
+% \ReturnLink
+% \newpage
%
-% Using\marginpar{\small\raggedleft\dbend} |\newunicodechar{ā}{\=a}| allows |\Name{Ghazāli}| to show \SkipIndex\Name{Ghaz\=ali}, but control sequences like |\=a| fail when using \texttt{makeindex} and \texttt{gind.ist}. For example, the \textsf{ltxdoc} class, with \texttt{gind.ist}, turns the default ``actual'' character |@| into |=|. Using |\index{Gh{\=a}zali}| halts execution. Understandably, using |\index{Gh\=azali}| gives an ``azali'' entry sorted under ``Gh'' (thanks \Name[Dan]{Luecking}). This issue is not specific to \textsf{nameauth}.
+% \subsection{Longer Examples}
+% \label{sec:Hooks}
%
-% Such\marginpar{\small\raggedleft\dbend} issues with \texttt{gind.ist} are not the only concerns one must have about NFSS, \textsf{inputenc}, and \textsf{fontenc} when using Unicode. Although the manner in which glyphs are handled is quite powerful, it also is fragile. Any \TeX\ macro that partitions its argument without using delimiters can break Unicode under NFSS. Consider the following examples with |\def\foo#1#2#3\relax{<#1#2><#3>}|:
-% \begin{center}\setstretch{1.1}
-% \def\foo#1#2#3\relax{<#1#2><#3>}
-% \begin{tabular}{lll}\toprule
-% Argument & Macro & Result\\\midrule
-% |abc| & |\foo abc\relax| & \foo abc\relax\\
-% |{æ}bc| & |\foo {æ}bc\relax| & \foo {æ}bc\relax\\
-% |\ae bc| & |\foo \ae bc\relax| & \foo \ae bc\relax\\\bottomrule
-% \end{tabular}
-% \end{center}
+% Examples from the remainder of this manual are in \texttt{examples.tex}, included with the \textsf{nameauth} documentation.
%
-% The arguments in the last example always put |c| in |#3|, with the first two glyphs in |#1#2.| Now here is where things get tricky:
-% \begin{center}\setstretch{1.1}
-% \begin{tabular}{llll}\toprule
-% Argument & Macro & Engine & Result\\\midrule
-% |æbc| & |\foo æbc\relax| & \texttt{xelatex} & <æb><c>\\
-% |æbc| & |\foo æbc\relax| & \texttt{lualatex} & <æb><c>\\
-% |æbc| & |\foo æbc\relax| & \texttt{pdflatex} & <æ><bc>\\\bottomrule
-% \end{tabular}
-% \end{center}
+% When\Info{\texttt{dtx} files} creating package documentation, any name that has a macro in its argument should be set up in the driver section (the \texttt{nameauth} environment and tags from \cmd{\PretagName} and \cmd{\TagName}). Otherwise, errors can result.
%
-% In both \texttt{xelatex} and \texttt{lualatex} you get the same results as the previous table, where |c| is in |#3| and the first two glyphs are in |#1#2.| However, using \texttt{latex} or \texttt{pdflatex} with \textsf{inputenc} and \textsf{fontenc} causes |æ| by itself to use |#1#2|.
-%
-% Without digging into the details of font encoding and NFSS, we can say in simple terms that |æ| is ``two arguments wide.'' Any macro where this |#1#2| pair gets split into |#1| and |#2| will produce either \texttt{Unicode char \dots not set up for LaTeX} or \texttt{Argument of \textbackslash UTFviii at two@octets has an extra \}}. Again, this is not just specific to \textsf{nameauth}.
-%
-% \cmd{\CapThis}\marginpar{\large\raggedleft\textsf{\bfseries 3.0}\strut\break\small\dbend} avoids these pitfalls by checking if the leading token of the argument to be capitalized is equivalent to the leading token of an active Unicode character. We chose \texttt{ß} as the test character somewhat at random. Page~\pageref{page:CapSystem} shows the test. Essentially, the following two expressions are equal under NFSS:
-% \begin{quote}\small\setstretch{1.1}
-% \cmd{\@car}\meta{$test_1$}\cmd{\@nil}, where \meta{$test_1$} expands to \cmd{\IeC} \marg{$test_1$}\\
-% \cmd{\@car}\meta{$test_2$}\cmd{\@nil}, where \meta{$test_2$} expands to \cmd{\IeC} \marg{$test_2$}
-% \end{quote}
-%
-% If \meta{$test_2$} expands to the letter \meta{$test_2$}, then it will fail the test for equality. ``Active'' characters expand to ``two-argument wide'' values under NFSS, as the table below shows via defining a macro to be a character, then printing its \cmd{\meaning} in the cell:
-% \begin{center}\footnotesize\setstretch{1.1}\makeatletter
-% \begin{tabular}{lll}\toprule
-% |\def\a|\marg{L} & |\protected at edef\a|\marg{L} & |\protected\edef\a|\marg{L}\\
-% A \def\a{A}\meaning\a & A \protected at edef\a{A}\meaning\a & A \protected\edef\a{A}\meaning\a\\
-% À \def\a{À}\meaning\a & À \protected at edef\a{À}\meaning\a & À \protected\edef\a{À}\meaning\a\\
-% ß \def\a{ß}\meaning\a & ß \protected at edef\a{ß}\meaning\a & ß \protected\edef\a{ß}\meaning\a\\\bottomrule
-% \end{tabular}
-% \end{center}
-% The number of spaces inserted in the index file depends on the number of expansions that occur for a given active character.
-%
-% This\marginpar{\small\raggedleft\dbend} method of testing for active characters and resolving the related issues can interfere with some situations of expansion, generating errors. Be mindful of names within an \cmd{\edef}, for example, unless you control expansion explicitly.
-%
-% \LaTeX\marginpar{\small\raggedleft\dbend} also removes spaces between undelimited macro arguments, but not from the trailing undelimited argument. This is no longer an issue for name arguments in \textsf{nameauth}, but we include the information anyway:
-% \begin{center}\setstretch{1.1}
-% \def\foo#1#2#3\relax{<#1#2><#3>}
-% \begin{tabular}{lll}\toprule
-% Argument & Macro & Result\\\midrule
-% |a b c| & |\foo a b c\relax| & \foo a b c\relax\\
-% |ab c| & |\foo ab c\relax| & \foo ab c\relax\\
-% |a bc| & |\foo a bc\relax| & \foo a bc\relax\\
-% |abc| & |\foo abc\relax| & \foo abc\relax\\\bottomrule
-% \end{tabular}
-% \end{center}
-% Using explicit spacing macros prevents gobbled spaces:
-% \begin{center}\small\setstretch{1.1}
-% \def\foo#1#2#3\relax{<#1#2><#3>}
-% \begin{tabular}{lll}\toprule
-% Argument & Macro & Result\\\midrule
-% |a~bc| & |\foo a~bc\relax| & \foo a~bc\relax\\
-% |a\nobreakspace bc| & |\foo a\nobreakspace bc\relax| & \foo a\nobreakspace bc\relax\\
-% |a\space bc| & |\foo a\space bc\relax| & \foo a\space bc\relax\\\bottomrule
-% \end{tabular}
-% \end{center}
-% See also Sections~\ref{sec:standards} and~\ref{sec:accents}, as well as Section~\ref{sec:IndexSort}.
-% \clearpage
-%
-% \subsubsection{\LaTeX\ Engines}
-% \label{sec:engines}
-%
-% The\marginpar{\small\raggedleft\dbend} \textsf{nameauth} package tries to work with multiple languages and typesetting engines. The following preamble snippet illustrates how that can be done:\footnote{A similar version of this example is in \texttt{examples.tex}, collocated with this manual.}
-% This example reflects changes to several packages since 2014 and may not address older documents and systems or all possible cases. Of course, the user must specify the main and alternate languages and any package options as the respective package documentation files indicate.
-% \begin{quote}\small\setstretch{1.1}
-% |\ifdefined\Umathchar|\\
-% | \usepackage{fontspec}|\\
-% | \usepackage{polyglossia}|\\
-% |\else|\\
-% | \usepackage[utf8]{inputenc}|\\
-% | \usepackage[TS1,T1]{fontenc}|\\
-% | \usepackage{babel}|\\
-% |\fi|\\
-% |% Below is optional; use only if your dvi viewer|\\
-% |% crashes or becomes unresponsive with tikz.|\\
-% |\usepackage{ifxetex}|\\
-% |\usepackage{ifluatex}|\\
-% |\usepackage{ifpdf}|\\
-% |\ifxetex|\\
-% | \usepackage{tikz}|\\
-% |\else|\\
-% | \ifpdf|\\
-% | \usepackage{tikz}|\\
-% | \fi|\\
-% |\fi|
-% \end{quote}
-%
-% This general arrangement works for this manual, which is tested with all of the \LaTeX\ engines above. This example is not meant to be the only possible way to check which engine you are using and how to set things up.
-%
-% The following can be used in the text itself to allow for conditional processing that helps one to document work under multiple engines. One must include the \textsf{ifxetex}, \textsf{ifluatex}, and \textsf{ifpdf} packages for it to work.
-%
-% \begin{quote}\small\setstretch{1.1}
-% |\ifxetex| \meta{xelatex text}|%|\\
-% |\else|\\
-% \hbox{\quad}|\ifluatex|\\
-% \hbox{\qquad}|\ifpdf |\meta{lualatex in pdf mode text}|%|\\
-% \hbox{\qquad}|\else |\meta{lualatex in dvi mode text}|%|\\
-% \hbox{\qquad}|\fi|\\
-% \hbox{\quad}|\else|\\
-% \hbox{\qquad}|\ifpdf |\meta{pdflatex text}|%|\\
-% \hbox{\qquad}|\else |\meta{latex text}|%|\\
-% \hbox{\qquad}|\fi|\\
-% \hbox{\quad}|\fi|\\
-% |\fi|
-% \end{quote}
-% \clearpage
-%
+% \begingroup^^A Start of hook macro redefinition.
% \subsubsection{Hooks: Intro}
-% \label{sec:Hooksa}
+% \label{sec:Hooksi}
%
-% Starting with this section we reset all formatting hooks to do nothing. This helps us focus on the modifications made hereafter.
+% In these sections on advanced topics we reset all formatting hooks to do nothing. This helps us focus on the modifications made hereafter.
% \renewcommand*\NamesFormat{}
% \renewcommand*\FrontNamesFormat{}
% \renewcommand*\MainNameHook{}
% \renewcommand*\FrontNameHook{}
%
-% 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}.\marginpar{\small\raggedleft\dbend} 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}\small\setstretch{1.1}
-% |\let\OldFormat\NamesFormat%|\\
-% |\renewcommand*\NamesFormat[1]|\\
-% | {\textbf{#1}\unless\ifinner|\\
-% | \marginpar{\raggedleft\scriptsize #1}\fi}|\\
-% \dots\\
-% |\let\NamesFormat\OldFormat%|
-% \end{quote}
-% Changes to \cmd{\NamesFormat} are not relying just on scoping rules to keep them ``local.'' We use \cmd{\let} to make explicit changes in order to avoid some possible side effects. We now use the example above in a sample text:
-% \begin{quote}\small\setstretch{1.1}
-% \let\OldFormat\NamesFormat\ignorespaces%
+% Before we get to the use of text tags and name conditionals in name formatting, we seek to illustrate that something more complex than a font switch can occur in \cmd{\NamesFormat}. Below we put the first mention of a name in boldface, along with a marginal notation if possible.
+% \begin{quote}\small
+% \StartNum
+% \begin{verbatim}
+%\let\OldFormat\NamesFormat
+%\renewcommand*\NamesFormat[1]{\textbf{#1}\unless\ifinner
+% \marginpar{\raggedleft\scriptsize #1}\fi}
+%\let\NamesFormat\OldFormat
+%\PretagName{Vlad, Ţepeş}{Vlad Tepes} % for accented names
+%\TagName{Vlad, II}{ Dracul} % for index information
+%\TagName{Vlad, III}{ Dracula}\end{verbatim}
+%
+% \medskip Within the document after the preamble:
+% \let\OldFormat\NamesFormat
% \renewcommand*\NamesFormat[1]{\textbf{#1}\unless\ifinner
-% \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ş}| |(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ş} (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}
+% \marginpar{\raggedleft\scriptsize #1}\fi}
+% \ContinueNum
+% \begin{verbatim}\Name{Vlad, III}[III Dracula], known as
+%\AKA{Vlad III}{Vlad, Ţepeş} (the Impaler)
+%after his death, was the son of \Name{Vlad, II}[II Dracul],
+%a member of the Order of the Dragon. Later references to
+%``\Name*{Vlad, III}'' and ``\Name{Vlad, III}'' appear thus.\end{verbatim}
%
-% Now again we have reverted to the default \cmd{\NamesFormat} and we get \ForgetName{Vlad III, Dracula}\Name{Vlad III, Dracula} and \Name{Vlad III, Dracula}. For references to ``Vlad'' consider using |\Name{Vlad, III}| and use \cmd{\NameAddInfo} and \cmd{\NameQueryInfo} to handle ``\texttt{Dracula}.'' The simplified interface greatly helps one to avoid confusion and settle on specific name forms.
+% \Name{Vlad, III}[III Dracula], known as
+% \AKA{Vlad III}{Vlad, Ţepeş} (the Impaler)
+% after his death, was the son of \Name{Vlad, II}[II Dracul],
+% a member of the Order of the Dragon. Later references to
+% ``\Name*{Vlad, III}'' and ``\Name{Vlad, III}'' appear thus.
%
-% \let\OldMainHook\MainNameHook%
-% You\marginpar{\small\raggedleft\dbend} cannot re-enter \cmd{\Name} or \cmd{\AKA} by calling them within any of the formatting hooks, as the next example shows:
-% \begin{quote}\small\setstretch{1.1}
-% |\renewcommand*\MainNameHook[1]|\\
-% |{%|\\
-% | {#1}%|\\
-% | \IndexInactive%|\\
-% | \Name{foo}\AKA{bar}{baz}%|\\
-% | \IndexActive%|\\
-% |}|
+% \let\NamesFormat\OldFormat
+% \begin{verbatim}\let\NamesFormat\OldFormat\end{verbatim}
% \end{quote}
-% \renewcommand*\MainNameHook[1]{{#1}\IndexInactive\Name{foo}\AKA{bar}{baz}\IndexActive}%
-% Calling,\marginpar{\large\raggedleft\textsf{\bfseries 2.4}\strut} \emph{e.g.}, |\Wash| produces \Wash, without foo, bar, or baz. \cmd{\Name} and \cmd{\AKA} expand to nothing. This prevents stack overflows both in this case and if you called the naming macros as their own arguments. |\Name{foo\Name{bar}}| would produce ``foo'' in the text and ``foobar'' in the index. As you see, these cases are to be avoided.
-% \let\MainNameHook\OldMainHook
-% \clearpage
-%
+% Now we have reverted to the default \cmd{\NamesFormat} and we get:
+% \begin{itemize}
+% \item |\ForgetThis\Name{Vlad, III}[III Dracula]|\dotfill \ForgetThis\Name{Vlad, III}[III Dracula]
+% \item |\Name*{Vlad, III}|\dotfill \Name*{Vlad, III}
+% \item |\Name{Vlad, III}|\dotfill \Name{Vlad, III}
+% \end{itemize}
+% We also set up the cross-reference |\IndexRef{Dracula}{Vlad III}|\IndexRef{Dracula}{Vlad III}. Compare the examples for \LDem\ in Section~\ref{sec:NameParticles}.
+%
+% \ReturnLink
+% \newpage
+%
% \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.
+% \label{sec:Hooksii}
+% We can use name conditionals (Section~\ref{sec:NameTests}) and text tags (Section~\ref{sec:TextTags}) to add life information to names when desired.
%
% \DescribeMacro{\if at nameauth@InName}
+% The example \cmd{\NamesFormat} below adds a text tag to the first occurrences of main-matter names.
% \DescribeMacro{\if at nameauth@InAKA}
-% The example \cmd{\NamesFormat} below adds a text tag to the first occurrences of main-matter names. It uses internal macros of \cmd{\@nameauth at Name}. To prevent errors, the Boolean values \texttt{\textbackslash if at nameauth@InName} and \texttt{\textbackslash if at nameauth@InAKA} are true only within the scope of \cmd{\@nameauth at Name} and \cmd{\AKA} respectively.
+% It uses internal macros of \cmd{\@nameauth at Name}. To prevent errors, the Boolean values \texttt{\textbackslash if at nameauth@InName} and \texttt{\textbackslash if at nameauth@InAKA} are true only within the scope of \cmd{\@nameauth at Name} and \cmd{\AKA} respectively.
%
% \DescribeMacro{\@nameauth at toksa}
+% This package makes three token registers available to facilitate using the name conditional macros as we do below.
% \DescribeMacro{\@nameauth at toksb}
+% These registers are necessary for names that contain accents and diacritics.\footnote{In \cmd{\AKA} these registers correspond to the \emph{last} three arguments, the xref.}
% \DescribeMacro{\@nameauth at 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.\marginpar{\small\raggedleft\dbend} Nevertheless, they have the same names as the registers in \cmd{\@nameauth at Name} because they work the same way and may be easier to use this way.
+%
%
-% We assume that we will not be using the \texttt{alwaysformat} option, meaning that we only call this hook once for a first use of \cmd{\AKA}. We also use a different formatting for the naming macros on the one hand and \cmd{\AKA} on the other:\footnote{A similar version of this example is in \texttt{examples.tex}, collocated with this manual.}
-% \begin{quote}\small\setstretch{1.1}
-% |\newif\ifNoTag|{\color{nared}|%|\hfill|allows us to work around \ForgetName|}\\
-% |\let\OldFormat\NamesFormat|{\color{nared}|%|\hfill|save the format|}\\
-% |\let\OldFrontFormat\FrontNamesFormat|\\
-% |\makeatletter|{\color{nared}|%|\hfill|access internals|}\\
-% |\renewcommand*\NamesFormat[1]{\begingroup%|\\
-% | \protected at edef\temp{\endgroup\textbf{#1}%|\\
-% | \unless\ifNoTag|\\
-% | \if at nameauth@InName|\\
-% | {\bfseries\noexpand\NameQueryInfo|\\
-% | [\unexpanded\expandafter{\the\@nameauth at toksa}]|\\
-% | {\unexpanded\expandafter{\the\@nameauth at toksb}}|\\
-% | [\unexpanded\expandafter{\the\@nameauth at toksc}]}\fi|\\
-% | \if at nameauth@InAKA\noexpand\NameQueryInfo|\\
-% | [\unexpanded\expandafter{\the\@nameauth at toksa}]|\\
-% | {\unexpanded\expandafter{\the\@nameauth at toksb}}|\\
-% | [\unexpanded\expandafter{\the\@nameauth at toksc}]\fi|\\
-% | \fi}\temp\global\NoTagfalse%|\\
-% |}|\\
-% |\makeatother|\\
-% |\let\FrontNamesFormat\NamesFormat|
+% Below the first use of a name is in small caps. Text tags are in boldface with naming macros, and roman with \cmd{\AKA}. Just because we set up a cross-reference does not mean that we use \cmd{\AKA} by default, as was the case in early versions of \textsf{nameauth}. We use \cmd{\ForceName} to use it more than once with \cmd{\AKA}:
+% \begin{quote}\small
+% \StartNum
+% \begin{verbatim}
+%\newif\ifNoTag% allows us to work around \ForgetName
+%\let\OldFormat\NamesFormat
+%\let\OldFrontFormat\FrontNamesFormat
+%\makeatletter
+%\renewcommand*\NamesFormat[1]{\begingroup%
+% \protected at edef\temp{\endgroup\textsc{#1}%
+% \unless\ifNoTag
+% \if at nameauth@InName
+% {\bfseries\noexpand\NameQueryInfo
+% [\unexpanded\expandafter{\the\@nameauth at toksa}]
+% {\unexpanded\expandafter{\the\@nameauth at toksb}}
+% [\unexpanded\expandafter{\the\@nameauth at toksc}]}\fi
+% \if at nameauth@InAKA
+% {\normalfont\noexpand\NameQueryInfo
+% [\unexpanded\expandafter{\the\@nameauth at toksa}]
+% {\unexpanded\expandafter{\the\@nameauth at toksb}}
+% [\unexpanded\expandafter{\the\@nameauth at toksc}]}\fi
+% \fi}\temp\global\NoTagfalse%
+%}
+%\makeatother
+%\let\FrontNamesFormat\NamesFormat\end{verbatim}
% \end{quote}
-% \let\OldFormat\NamesFormat\ignorespaces%
-% \let\OldFrontFormat\FrontNamesFormat\ignorespaces%
-% \makeatletter\ignorespaces%
-% \renewcommand*\NamesFormat[1]{\begingroup\ignorespaces%
-% \protected at edef\temp{\endgroup\textbf{#1}\ignorespaces%
+% \let\OldFormat\NamesFormat
+% \let\OldFrontFormat\FrontNamesFormat
+% \makeatletter
+% \renewcommand*\NamesFormat[1]{\begingroup%^^A
+% \protected at edef\temp{\endgroup\textsc{#1}%^^A
% \unless\ifNoTag
% \if at nameauth@InName
% {\bfseries\noexpand\NameQueryInfo
@@ -3013,207 +3941,259 @@
% [\unexpanded\expandafter{\the\@nameauth at toksa}]
% {\unexpanded\expandafter{\the\@nameauth at toksb}}
% [\unexpanded\expandafter{\the\@nameauth at toksc}]}\fi
-% \if at nameauth@InAKA\noexpand\NameQueryInfo
+% \if at nameauth@InAKA
+% {\normalfont\noexpand\NameQueryInfo
% [\unexpanded\expandafter{\the\@nameauth at toksa}]
% {\unexpanded\expandafter{\the\@nameauth at toksb}}
-% [\unexpanded\expandafter{\the\@nameauth at toksc}]\fi
-% \fi}\temp\global\NoTagfalse}\ignorespaces%
-% \makeatother%
-% This change prints tags in the first use hooks unless \cmd{\NoTag} is set true. Please note that the conditional path here is placed within the \cmd{\edef}. Putting it outside the \cmd{\edef}, such as |\unless\ifNoTag\temp\fi|, will cause errors.
+% [\unexpanded\expandafter{\the\@nameauth at toksc}]}\fi
+% \fi}\temp\global\NoTagfalse}%^^A
+% \makeatother
%
-% This method uses the $\epsilon$-\TeX{} primitives \cmd{\noexpand} and \cmd{\unexpanded} to avoid the extensive repetition of \cmd{\expandafter}. Since the \textsf{nameauth} package depends on \textsf{etoolbox}, we assume that we are using $\epsilon$-\TeX.
-%
-% Before we can refer to any text tags, we must create them. Using the approach above, we must include a leading space in the text tags:
-% \begin{quote}\small\setstretch{1.1}
-% |\NameAddInfo[George]{Washington}{ (1732--99)}%|\\
-% |\NameAddInfo[Mustafa]{Kemal}{ (1881--1938)}%|\\
-% |\NameAddInfo{Atatürk}{ (in 1934, a special surname)}%|
-% \NameAddInfo[George]{Washington}{ (1732--99)}%
-% \NameAddInfo[Mustafa]{Kemal}{ (1881--1938)}%
-% \NameAddInfo{Atatürk}{ (in 1934, a special surname)}%
+% We print tags in the first use hooks unless \cmd{\NoTag} is set true. This method uses the two \(\epsilon\)-\TeX{} primitives \cmd{\noexpand} and \cmd{\unexpanded} to avoid repetition of \cmd{\expandafter}. Since \textsf{nameauth} depends on \textsf{etoolbox}, we assume \(\epsilon\)-\TeX.
+%
+% Before we can refer to any text tags, we must create them. Using the approach above, we include a leading space in the text tags. The leading space is needed only when a text tag appears.\footnote{Another way to add that space is to put it in the conditional path of the formatting hook and leave it out of the text tags entirely: \dots\texttt{\{ \}}\cmd{\noexpand}\cmd{\NameQueryInfo}\dots}
+% We also set up a cross-reference, which we will use regardless of whether we also use \cmd{\AKA}. The cross-reference will be created only once and skipped thereafter:
+% \begin{quote}\small
+% \ContinueNum
+% \begin{verbatim}
+%\NameAddInfo[George]{Washington}{ (1732--99)}
+%\NameAddInfo[Mustafa]{Kemal}{ (1881--1938)}
+%\NameAddInfo{Atatürk}{ (in 1934, a special surname)}
+%\IndexRef{Atatürk}{Kemal, Mustafa}\end{verbatim}
% \end{quote}
-%
-% The leading space is needed only when a text tag appears. Another way to add that space is to put it in the conditional path of the formatting hook and leave it out of the text tags entirely:
+% \NameAddInfo[George]{Washington}{ (1732--99)}
+% \NameAddInfo[Mustafa]{Kemal}{ (1881--1938)}
+% \NameAddInfo{Atatürk}{ (in 1934, a special surname)}
+% \IndexRef{Atatürk}{Kemal, Mustafa}
+% \newpage
+%
+% Now we begin with the first example, which, after all the setup, looks deceptively simple, but highly reusable without extra work:
% \begin{quote}\small
-% \dots|\unless\ifNoTag|\dots|{ }\noexpand\NameQueryInfo|\dots|\fi}\temp|
-% \end{quote}
+% \ContinueNum
+% \begin{verbatim}
+%\ForgetThis\Wash held office 1789--97.
+%No tags: \Wash.\\
+%First use, dates suppressed: \NoTagtrue\ForgetThis\Wash.\end{verbatim}
%
-% Now we begin with the first example, where both the name and the dates are in boldface because we use a naming macro:
-% \begin{quote}\small\setstretch{1.1}
-% |\ForgetThis\Wash held office 1789--97. No tags: \Wash.|\\
-% |First use, dates suppressed: \NoTagtrue\ForgetThis\Wash.|\\[1ex]
-% \ForgetThis\Wash\ held office 1789--97. No tags: \Wash.
+% \smallskip
+% \ForgetThis\Wash\ held office 1789--97.\\
+% No tags: \Wash.\\
% First use, dates suppressed: \NoTagtrue\ForgetThis\Wash.
% \end{quote}
%
-% Since \cmd{\AKA} usually calls the ``subsequent use'' formatting hooks, we can create a scope to ``fool'' it into calling the first-use hook via \cmd{\let}:
-% \begin{quote}\small\setstretch{1.1}
-% |\Name[Mustafa]{Kemal} was granted the name%|\\
-% |\begingroup\let\MainNameHook\NamesFormat%|\\
-% |\AKA[Mustafa]{Kemal}{Atatürk}\endgroup. We mention%|\\
-% |\AKA[Mustafa]{Kemal}{Atatürk} again.|
+% Since we already set up a cross-reference with \cmd{\IndexRef}, we can use just the the naming macros with ``Atatürk'' and get the desired formatting without any page references in the index:
+% \begin{quote}\small
+% \ContinueNum
+% \begin{verbatim}
+%\Name[Mustafa]{Kemal} was granted the name
+%\Name{Atatürk}. We mention \Name[Mustafa]{Kemal}
+%and \Name{Atatürk} again.
%
-% \Name[Mustafa]{Kemal} was granted the name \begingroup\let\MainNameHook\NamesFormat \AKA[Mustafa]{Kemal}{Atatürk}\endgroup. We mention \AKA[Mustafa]{Kemal}{Atatürk} again.
-% \end{quote}
+%First use, no tag:
+%\NoTagtrue\ForgetThis\Name{Atatürk}.\end{verbatim}
%
-% Another\marginpar{\small\raggedleft\dbend} solution uses the \texttt{formatAKA} package option. In the example below, we simulate a first occurrence of \Name[Mustafa]{Kemal}. Then we simulate \texttt{formatAKA}. Finally, we use \cmd{\ForceName} with \cmd{\AKA}:
-% \begin{quote}\small\setstretch{1.1}
-% |\ForgetName[Mustafa]{Kemal}%|\hfill|first use|\\
-% |\makeatletter\@nameauth at AKAFormattrue\makeatother%|\hfill|formatAKA|\\
-% |\Name[Mustafa]{Kemal} was granted the name%|\\
-% |\AKA[Mustafa]{Kemal}{Atatürk}. We mention%|\\
-% |\AKA[Mustafa]{Kemal}{Atatürk} again.|\\[1ex]
-% \ForgetName[Mustafa]{Kemal}\makeatletter\@nameauth at AKAFormattrue\makeatother\Name[Mustafa]{Kemal} was granted the name \ForceName\AKA[Mustafa]{Kemal}{Atatürk}. We mention \AKA[Mustafa]{Kemal}{Atatürk} again.
+% \smallskip
+% \Name[Mustafa]{Kemal} was granted the name
+% \Name{Atatürk}. We mention \Name[Mustafa]{Kemal}
+% and \Name{Atatürk} again.
+%
+% First use, no tag:
+% \NoTagtrue\ForgetThis\Name{Atatürk}.
% \end{quote}
%
-% There are other solutions for getting this result, such as using \cmd{\IncludeName*} or non-printing control sequences. One must decide the best approach for oneself. Please remember to reset the formatting, if needed:
-% \begin{quote}\small\setstretch{1.1}
-% |\let\NamesFormat\OldFormat|\\
-% |\let\FrontNamesFormat\OldFrontFormat|
+% Since we set up distinct formatting for \cmd{\AKA} (\cmd{\normalfont} instead of boldface for text tags associated with cross-references), we now simulate the \texttt{formatAKA} package option and use \cmd{\ForceName} with \cmd{\AKA}:
+% \begin{quote}\small
+% \ContinueNum
+% \begin{verbatim}
+%\makeatletter\@nameauth at AKAFormattrue\makeatother
+%\ForgetThis\Name[Mustafa]{Kemal} was granted the name
+%\ForceName\AKA[Mustafa]{Kemal}{Atatürk}. We mention
+%\Name[Mustafa]{Kemal} and \AKA[Mustafa]{Kemal}{Atatürk} again.
+%
+%First use, no tag:
+%\NoTagtrue\ForceName\AKA[Mustafa]{Kemal}{Atatürk}.\end{verbatim}
+%
+% \smallskip
+% \makeatletter\@nameauth at AKAFormattrue\makeatother
+% \ForgetThis\Name[Mustafa]{Kemal} was granted the name
+% \ForceName\AKA[Mustafa]{Kemal}{Atatürk}. We mention
+% \Name[Mustafa]{Kemal} and \AKA[Mustafa]{Kemal}{Atatürk} again.
+%
+% First use, no tag:
+% \NoTagtrue\ForceName\AKA[Mustafa]{Kemal}{Atatürk}.
+% \end{quote}%
+% Please remember to reset the formatting:
+% \begin{quote}\small
+% \ContinueNum
+% \begin{verbatim}
+%\let\NamesFormat\OldFormat
+%\let\FrontNamesFormat\OldFrontFormat\end{verbatim}
% \end{quote}
% \let\NamesFormat\OldFormat
% \let\FrontNamesFormat\OldFrontFormat
%
-% See Section~\ref{sec:internal} and page~\pageref{page:parser} for the decision paths and the logic used by the package. Presently, writing hook macros should be much simpler than in earlier versions of this package.
-%
-% {\medskip\noindent\hbox{}\hfill\large Back to Section~\ref{sec:RefTables} \hfill\hbox{}}
-% \clearpage
-%
+% \ReturnLink
+% \newpage
+%
% \subsubsection{Hooks: Advanced}
-% \label{sec:Hooksc}
+% \label{sec:Hooksiii}
% \AltFormatActive\begingroup
%
% \begin{center}\bfseries Alternate Formatting\end{center}
-% The\marginpar{\large\raggedleft\textsf{\bfseries 3.1}} alternate formatting framework now makes designing hooks much easier by providing some built-in features that add not only error protection but also ease of use. We enabled that framework at the beginning of this section with \cmd{\AltFormatActive} and take care not to use the names in this section elsewhere.
%
-% Both \cmd{\AltFormatActive} and \cmd{\AltFormatActive*} set the internal Boolean flag \cmd{\@nameauth at AltFormattrue}, which enables alternate formatting. Additionally, \cmd{\AltFormatActive} sets \cmd{\@nameauth at DoAlttrue}, which ``switches on'' alternate formatting. \cmd{\AltFormatInactive} sets both flags false.
+% \noindent The\Version{3.1} alternate formatting framework provides features that aid both error protection and ease of use. This section uses \cmd{\AltFormatActive}. We do not use the names in this section elsewhere. A name designed for the alternate formatting regime may cause spurious index entries when used in the default formatting regime.
%
-% The main feature\marginpar{\small\raggedleft\cmd{\CapThis}\break protection} of this framework is protecting against errors created when \cmd{\@nameauth at Cap} gets a misleading result from \cmd{\@nameauthUTFtest} and splits a token list in a way that causes an error. The alternate capping macro \cmd{\AltCaps} and \cmd{\CapThis} work mutually in \cmd{\@nameauth at Parse} to ensure that they do not interfere with each other, as we saw demonstrated in Section~\ref{sec:altformat}.
+% Both \cmd{\AltFormatActive} and \cmd{\AltFormatActive*} set the internal Boolean flag \cmd{\@nameauth at AltFormattrue}, enabling alternate formatting. \cmd{\AltFormatActive} sets \cmd{\@nameauth at DoAlttrue}, which activates formatting. \cmd{\AltFormatInactive} sets both flags false.
%
+% \cmd{\AltFormatActive*} normally suppresses formatting changes but it still forces \cmd{\CapThis} to work through \cmd{\AltCaps}. This produces the default look of \textsf{nameauth} and prevents Continental formatting, but it also reduces spurious index entries and errors if many names use macros in their arguments.
+%
+% Alternate formatting protects against errors created when \cmd{\@nameauth at Cap} (used by \cmd{\CapThis}) gets a failure result from \cmd{\@nameauthUTFtest}, but that result is neither a letter nor a macro that expands to a sequence of letters. Protected macros and other cases may create errors if \cmd{\MakeUppercase} is applied to them. \cmd{\AltCaps} and \cmd{\CapThis} work together to avoid this problem (Section~\ref{sec:AltFormat}).
+%
% \begin{center}\bfseries Continental Format\end{center}
-% Here we look in greater detail at the more complex version of Continental formatting from Section~\ref{sec:altformat}.
%
-% Font changes \marginpar{\small\raggedleft changes\break in text} in the text occur with the short macros \cmd{\textSC}, \cmd{\textIT}, \cmd{\textBF}, and \cmd{\textUC}. They all look similar to \cmd{\textSC}. We therefore show just this one macro as an example from the package source.
-% \begin{quote}\small\setstretch{1.1}
-% |\newcommand*\textSC[1]{%|\\
-% | \if at nameauth@DoAlt\textsc{#1}\else#1\fi|\\
-% |}|
+% \noindent Here we look in greater detail at how \textsf{nameauth} implements the advanced version of Continental formatting. Font changes occur in the short macros \cmd{\textSC}, \cmd{\textIT}, \cmd{\textBF}, and \cmd{\textUC}. They all look similar to \cmd{\textSC}:
+% \begin{quote}\small
+% \StartNum
+% \begin{verbatim}
+%\newcommand*\textSC[1]{%
+% \if at nameauth@DoAlt\textsc{#1}\else#1\fi
+%}\end{verbatim}
% \end{quote}
-%
-% Using this method, formatting occurs in both the text and in the index if the \texttt{altformat} option or \cmd{\AltFormatActive} was used. If you use a name that uses these macros both within and outside of the alternate formatting regime, you will get spurious index entries.\footnote{Using \cmd{\AltFormatActive*} is interesting because it looks like the normal \textsf{nameauth} regime but prevents \cmd{\CapThis} from having its normal effect unless you use \cmd{\AltCaps}. With \cmd{\AltFormatActive*} if you use a name that has alternate formatting both within and outside of the alternate formatting regime, you may not get spurious index entries as long as control sequences are consistent.}
-%
-% We plan to have small caps on by default, then off in subsequent uses. We thus use \cmd{\AltFormatActive} for the ``always on'' general condition, then redefine \cmd{\MainNameHook} because it is the subsequent use. We use \cmd{\AltOff} to suppress formatting. It works only in the formatting hooks. \cmd{\AltOff} toggles an internal flag that deactivates any changes. From the source, it looks like:
-% \begin{quote}\small\setstretch{1.1}
-% |\newcommand*\AltOff{%|\\
-% | \if at nameauth@InHook\@nameauth at DoAltfalse\fi|\\
-% |}|
+%
+% If the \texttt{altformat} option or \cmd{\AltFormatActive} is used, formatting occurs in both the text and in the index. We want small caps on by default in the text and index, then off in subsequent uses. Thus, we use \cmd{\AltFormatActive}, then redefine \cmd{\MainNameHook} because it is the subsequent use hook. \cmd{\AltOff} deactivates formatting only in the formatting hooks:
+% \begin{quote}\small
+% \ContinueNum
+% \begin{verbatim}
+%\newcommand*\AltOff{%
+% \if at nameauth@InHook\@nameauth at DoAltfalse\fi
+%}\end{verbatim}
% \end{quote}
%
-% Since the normal effects of \cmd{\CapThis} are disabled, \cmd{\AltCaps} does the job by capitalizing its argument in braces |{| |}| when it is used in a macro hook and triggered by \cmd{\CapThis}. The source looks like:
-% \begin{quote}\small\setstretch{1.1}
-% |\newcommand*\AltCaps[1]{%|\\
-% | \if at nameauth@InHook|\\
-% | \if at nameauth@DoCaps\MakeUppercase{#1}\else#1\fi|\\
-% | \else#1\fi|\\
-% |}|
+% \cmd{\CapThis} now triggers \cmd{\AltCaps} to capitalize its argument:
+% \begin{quote}\small
+% \ContinueNum
+% \begin{verbatim}
+%\newcommand*\AltCaps[1]{%
+% \if at nameauth@InHook
+% \if at nameauth@DoCaps\MakeUppercase{#1}\else#1\fi
+% \else#1\fi
+%}\end{verbatim}
% \end{quote}
%
-% It is important that these macros not expand too soon. We therefore must put \cmd{\noexpand} once before \cmd{\textSC}, etc., and once before \cmd{\AltCaps}. This is because the name arguments in \textsf{nameauth} have to use \cmd{\protected at edef} to work right. We will get to that when we set up the names and any applicable tags.
+% We must put \cmd{\noexpand} before \cmd{\textSC}, \cmd{\AltCaps}, and so on to prevent them from expanding outside of the formatting hooks.
%
-% Before we alter the formatting hooks, we can save the hook macros if we want to recall them (below) or we can use \cmd{\begingroup} and \cmd{\endgroup} to create a new scope and let that handle any changes. We use scoping in this section.
+% Before we alter the formatting hooks, we either can \cmd{\let} the hook macros to recall them later or we can use \cmd{\begingroup} and \cmd{\endgroup} to create a new scope that localizes any changes. We use scoping in this section.
%
-% The final step \emph{does not come} from the \textsf{nameauth} source. We must redefine the formatting hooks ourselves. One of the simplest ways to do this when using the \texttt{altformat} option or \cmd{\AltFormatActive} is:
-% \begin{quote}\small\setstretch{1.1}
-% |\renewcommand*\MainNameHook{\AltOff}|
+% This final step \emph{does not come} from the \textsf{nameauth} source. We must redefine the formatting hooks ourselves. One of the simplest ways to do this when using the \texttt{altformat} option or \cmd{\AltFormatActive} is:
+% \begin{quote}\small
+% \ContinueNum
+% \begin{verbatim}
+%\renewcommand*\MainNameHook{\AltOff}
+%\let\FrontNameHook\MainNameHook\end{verbatim}
% \end{quote}
-% Simple, \emph{oder}? If needed, we can \cmd{\let}\cmd{\FrontNameHook}\cmd{\MainNameHook}.
+%
% \renewcommand*\MainNameHook{\AltOff}\let\FrontNameHook\MainNameHook
-% If you want to suppress formatting altogether in the front matter, make the following change: |\let\FrontNamesFormat\MainNameHook|.
-%
-% Continental formatting usually alters at least one element in the required name field, as we see below:
-% \begin{quote}\small\setstretch{1.1}
-% |\begin{nameauth}|\\
-% | \< Adams & John & \noexpand\textSC{Adams} & >|\\
-% | \< SDJR & Sammy & \noexpand\textSC{Davis},|\\
-% | \noexpand\textSC{Jr}. & >|\\
-% | \< HAR & & Harun, \noexpand\textSC%|\\
-% | {\noexpand\AltCaps{a}l-Rashid} & >|\\
-% | \< Mencius & & \noexpand\textSC{Mencius} & >|\\
-% |\end{nameauth}|
+% To suppress all formatting in the front-matter text, one need simply to use |\let\FrontNamesFormat\MainNameHook|. Continental formatting usually alters at least one element in the required name argument, as we see below:
+% \begin{quote}\small
+% \ContinueNum
+% \begin{verbatim}
+%\begin{nameauth}
+% \< Adams & John & \noexpand\textSC{Adams} & >
+% \< SDJR & Sammy & \noexpand\textSC{Davis},
+% \noexpand\textSC{Jr}. & >
+% \< HAR & & Harun, \noexpand\textSC%
+% {\noexpand\AltCaps{a}l-Rashid} & >
+% \< Mencius & & \noexpand\textSC{Mencius} & >
+%\end{nameauth}\end{verbatim}
% \end{quote}
%
-% Now we must ensure that these names are sorted properly in the index. See again how the formatting must be present:
-% \begin{quote}\small\setstretch{1.1}
-% |\PretagName[John]{\noexpand\textSC{Adams}}{Adams, John}|\\
-% |\PretagName[Sammy]%|\\
-% | {\noexpand\textSC{Davis}, \noexpand\textSC{Jr}.}%|\\
-% | {Davis, Sammy, Jr.}|\\
-% |\PretagName{Harun, \noexpand\textSC%|\\
-% | {\noexpand\AltCaps{a}l-Rashid}}{Harun al-Rashid}|\\
-% |\PretagName{\noexpand\textSC{Mencius}}{Mencius}|
+% Now we must ensure that these names are sorted properly in the index. When sorting names, be sure to use \cmd{\noexpand} before the macros:
+% \begin{quote}\small
+% \ContinueNum
+% \begin{verbatim}
+%\PretagName[John]{\noexpand\textSC{Adams}}{Adams, John}
+%\PretagName[Sammy]%
+% {\noexpand\textSC{Davis}, \noexpand\textSC{Jr}.}%
+% {Davis, Sammy, Jr.}
+%\PretagName{Harun, \noexpand\textSC%
+% {\noexpand\AltCaps{a}l-Rashid}}{Harun al-Rashid}
+%\PretagName{\noexpand\textSC{Mencius}}{Mencius}\end{verbatim}
% \end{quote}
%
-% The use in the body text is not much different than normal, but only if we use the simplified interface.
% \begin{center}
% \small\noindent\begin{tabular}{llll}\toprule
% First & Next & Long & Short \\\midrule
+% |\Adams| & |\Adams| & |\LAdams| & |\SAdams|\\
% \Adams & \Adams & \LAdams & \SAdams\\
-% \SDJR & \SDJR & \LSDJR & \SSDJR\\
+% \rowcolor{black!7!white}|\SDJR| & |\SDJR| & |\LSDJR| & |\SSDJR|\\
+% \rowcolor{black!7!white}\SDJR & \SDJR & \LSDJR & \SSDJR\\
+% |\HAR| & |\HAR| & |\LHAR| & |\SHAR|\\
% \HAR & \HAR & \LHAR & \SHAR\\
-% \Mencius & \Mencius & \LMencius & \SMencius\\\bottomrule
+% \rowcolor{black!7!white}|\Mencius| & |\Mencius| & |\LMencius| & |\SMencius|\\
+% \rowcolor{black!7!white}\Mencius & \Mencius & \LMencius & \SMencius\\\bottomrule
% \end{tabular}
% \end{center}
%
% \begin{itemize}\small
% \item Punctuation detection works: \ForceName\LSDJR. Also \LSDJR. Then \ForceName\SDJR. Now \SDJR. (We used \cmd{\ForceName} for formatting.)
-% \item \cmd{\ForceName}\cmd{\DropAffix}\cmd{\LSDJR} gives \ForceName\DropAffix\LSDJR. Otherwise, using just \cmd{\DropAffix}\cmd{\LSDJR} gives \DropAffix\LSDJR.
+% \item \cmd{\ForceName}\cmd{\DropAffix}\cmd{\LSDJR} gives \ForceName\DropAffix\LSDJR. Otherwise, only using the macro \cmd{\DropAffix}\cmd{\LSDJR} gives \DropAffix\LSDJR.
% \item \cmd{\RevComma}\cmd{\LAdams} yields \RevComma\LAdams. All the reversing macros work.
-% \item \cmd{\ForceName}\cmd{\ForceFN}\cmd{\SHAR} produces \ForceName\ForceFN\SHAR. \cmd{\ForceFN}\cmd{\SHAR} produces \ForceFN\SHAR. If we add \cmd{\CapThis} we get \CapThis\ForceName\ForceFN\SHAR\ and \CapThis\ForceFN\SHAR. The way that Continental resources treat certain affixes relates to similar issues in [\hyperlink{Mulvany}{Mulvany}, 168--73].\footnote{Handling non-Western names in Western sources can be a gray area. One ought take care to be culturally sensitive in these matters.}
-% \item One must include the extra control sequences in all the macro arguments that use these names.
+% \item \cmd{\ForceName}\cmd{\ForceFN}\cmd{\SHAR} produces \ForceName\ForceFN\SHAR. \cmd{\ForceFN}\cmd{\SHAR} produces \ForceFN\SHAR. If we add \cmd{\CapThis} we get \CapThis\ForceName\ForceFN\SHAR\ and \CapThis\ForceFN\SHAR.\footnote{The way that Continental resources treat certain affixes relates to similar issues in [\hyperlink{Mulvany}{Mulvany}, 168--73]. Handling non-Western names in Western sources can be a gray area. One ought take care to be culturally sensitive in these matters.}
+% \item One must include all the macros in the name arguments.
% \end{itemize}
%
% \makeatletter\@nameauth at AKAFormattrue\makeatother
% If we use the \texttt{formatAKA} option we can refer to \Mencius\ as \AKA{\noexpand\textSC{Mencius}}{\noexpand\textSC{Meng}, Ke}, and again \AKA{\noexpand\textSC{Mencius}}{\noexpand\textSC{Meng}, Ke}. We get that with:
-% \begin{quote}\small\setstretch{1.1}
-% |\PretagName{\noexpand\textSC{Meng}, Ke}{Meng Ke}|\\
-% |\AKA{\noexpand\textSC{Mencius}}{\noexpand\textSC{Meng}, Ke}|
+% \begin{quote}\small
+% \ContinueNum
+% \begin{verbatim}
+%\PretagName{\noexpand\textSC{Meng}, Ke}{Meng Ke}
+%\AKA{\noexpand\textSC{Mencius}}{\noexpand\textSC{Meng}, Ke}\end{verbatim}
% \end{quote}
% \makeatletter\@nameauth at AKAFormatfalse\makeatother
%
-% \begin{center}\bfseries Rolling Your Own: New Style\end{center}
-% \noindent ``New style'' means that we are sticking closely with various package features that have been implemented already and look similar to the solutions in Section~\ref{sec:altformat}. Here we set out on the path to custom formatting.
+% \begin{center}\bfseries Rolling Your Own: Basic\end{center}
%
-% When\marginpar{\small\raggedleft\dbend} redesigning formatting hooks, you should use \cmd{\AltFormatActive} or the \texttt{altformat} option to enable alternate formatting and prevent \cmd{\CapThis} from breaking your formatting macros.
+% \noindent Here we set out on the path to custom formatting by using package features that have been implemented already and look similar to the solutions in Section~\ref{sec:AltFormat}.
%
-% We recommend using the internal package flag \cmd{\@nameauth at DoAlt}, which activates alternate formatting, \cmd{\@nameauth at DoCaps}, which handles capitalization, and \cmd{\@nameauth at InHook}, which is true when the formatting hooks are called. See page~\pageref{page:hooks} and following. If you create your own macros, they will look similar:\footnote{A similar version of this example is in \texttt{examples.tex}, collocated with this manual.}
-% \begin{quote}\small\setstretch{1.1}
-% |\makeatletter%|\\
-% |\newcommand*\Fbox[1]{%|\\
-% | \if at nameauth@DoAlt\fbox{#1}\else#1\fi|\\
-% |}|\\
-% |\makeatother|
+% When\Warn{} redesigning formatting hooks, one should use \cmd{\AltFormatActive} or the \texttt{altformat} option to enable alternate formatting and prevent \cmd{\CapThis} from breaking custom formatting macros.
+%
+% We recommend examining the internal package flag \cmd{\@nameauth at DoAlt}, which activates alternate formatting, \cmd{\@nameauth at DoCaps}, which handles capitalization, and \cmd{\@nameauth at InHook}, which is true when the formatting hooks are called. See page~\pageref{page:Hooks} and following. If you create your own macros, they will look similar:
+% \begin{quote}\small
+% \StartNum
+% \begin{verbatim}
+%\makeatletter
+%\newcommand*\Fbox[1]{%
+% \if at nameauth@DoAlt\protect\fbox{#1}\else#1\fi
+%}
+%\makeatother\end{verbatim}
% \end{quote}
-% \makeatletter\newcommand*\Fbox[1]{\if at nameauth@DoAlt\fbox{#1}\else#1\fi}\makeatother
+% \makeatletter\newcommand*\Fbox[1]{\if at nameauth@DoAlt\protect\fbox{#1}\else#1\fi}\makeatother
%
-% Since \cmd{\AltCaps} is part of \textsf{nameauth}, you need not reinvent that particular wheel. As was the case previously, the final step is redefining the formatting hooks. One of the simplest ways to do this is:
-% \begin{quote}\small\setstretch{1.1}
-% |\renewcommand*\MainNameHook{\AltOff}|\\
-% |\let\FrontNameHook\MainNameHook|
+% Since \cmd{\AltCaps} is part of \textsf{nameauth}, you need not reinvent that wheel. Just use it. The final step is redefining the hooks, which can be as simple as:
+% \begin{quote}\small
+% \ContinueNum
+% \begin{verbatim}
+%\renewcommand*\MainNameHook{\AltOff}
+%\let\FrontNameHook\MainNameHook\end{verbatim}
% \end{quote}
%
-% When defining names, be sure to use \cmd{\noexpand} before the control sequences in the macro arguments so they expand at the proper time:
-% \begin{quote}\small\setstretch{1.1}
-% |\PretagName[Pierre-Jean]%|\\
-% | {\noexpand\Fbox{\noexpand\AltCaps{d}e Smet}}%|\\
-% | {de Smet, Pierre-Jean}|\medskip
+% When sorting names, be sure to use \cmd{\noexpand} as shown previously:
+% \begin{quote}\small
+% \ContinueNum
+% \begin{verbatim}
+%\PretagName[Pierre-Jean]%
+% {\noexpand\Fbox{\noexpand\AltCaps{d}e Smet}}%
+% {de Smet, Pierre-Jean}
%
-% |\begin{nameauth}|\\
-% | \< deSmet & Pierre-Jean &|\\
-% | \noexpand\Fbox{\noexpand\AltCaps{d}e Smet}} & >|\\
-% |\end{nameauth}|
+%\begin{nameauth}
+% \< deSmet & Pierre-Jean &
+% \noexpand\Fbox{\noexpand\AltCaps{d}e Smet} & >
+%\end{nameauth}\end{verbatim}
% \end{quote}
%
% Now we show how the formatting hooks work in the body text. One can check the index to see that it is formatted properly and consistently.
+%
% \begin{center}\footnotesize
% \begin{tabular}{llll}\toprule
% First & Next & Long & Short \\\midrule
@@ -3222,151 +4202,261 @@
% \end{tabular}
% \end{center}
%
-% The capitalized version |\CapThis\deSmet| is \CapThis\deSmet. This also works for a formatted use via \cmd{\ForceName}: \ForceName\CapThis\deSmet. The index entries will be consistent for all the variations in the text.
+% The capitalized version |\CapThis\deSmet| is \CapThis\deSmet. This also works for a formatted use via \cmd{\ForceName}: \ForceName\CapThis\deSmet.
%
-% Also, remember to restore the macro hooks if they should not persist for the entire document, or else you will get unwanted results.
+% Some formatting, such as the use of \cmd{\textSC}, is fairly standard. Other formatting, such as \cmd{\Fbox} above, is ornamental and may be handled better with custom features (Section~\ref{sec:Customize}), but those features appear only in the text.
+% \newpage
%
-% \begin{center}\bfseries Rolling Your Own: Old Style\end{center}
-% ``Old style'' refers to the way hooks were designed before recent package changes. Sometimes one might want to achieve more customized results. We begin that journey by looking at \cmd{\NameParser}.
+% \begin{center}\bfseries Rolling Your Own: Intermediate\end{center}
%
+% \noindent \hspace{-0.47em}``Intermediate'' and ``advanced'' refer to the way hooks were designed before version 3.1. We begin the journey to more customized formatting by looking at \cmd{\NameParser}, whose logic Sections~\ref{sec:InternalMacros} and~\ref{sec:UserInterface} show in detail.\medskip
+%
% \DescribeMacro{\NameParser}
-% This user-accessible parser\marginpar{\large\raggedleft\textsf{\bfseries 3.1}} (page~\pageref{page:parser}) builds a name from the internal macros \cmd{\FNN}, \cmd{\SNN}, \cmd{\rootb} and \cmd{\suffb}. Reversing and commas are still usable; capitalization depends on the context. The general form is:
-% \begin{quote}\small\setstretch{1.1}
-% |\renewcommand*|\meta{Hook}|[1]{|\texttt{\dots}\cmd{\NameParser}\texttt{\dots}|}|
+% This user-accessible parser (Section~\ref{sec:UserInterface}) builds a printed name from the internal macros \cmd{\FNN}, \cmd{\SNN}, \cmd{\rootb} and \cmd{\suffb}.\Version{3.1} It uses the following Boolean flags:\footnote{These exclude all capitalization macros.}
+% \begin{quote}\small\MyStretch
+% Only one or the other of these can be true to avoid undocumented behavior.\smallskip\\
+% |\if at nameauth@FullName|\hfill Print a full name if true.\\
+% |\if at nameauth@FirstName|\hfill Print a first name if true.\smallskip\\
+% Reversing without commas overrides reversing with commas.\smallskip\\
+% |\if at nameauth@RevThis|\hfill Reverse name order if true.\\
+% |\if at nameauth@EastFN|\hfill toggled by \cmd{\ForceFN}.\\
+% |\if at nameauth@RevThisComma|\hfill Reverse Western name, add comma.
% \end{quote}
-% In order to use this hook-level parser, we want the option of ignoring the text that is sent to the formatting hooks from \cmd{\@nameauth at Parse}. We do that by redefining the hooks to take an argument.
%
-% If we use the \texttt{altformat} option or \cmd{\AltFormatActive}, then alternate formatting is both enabled and ``switched on''; whatever formatting macros that we are using should be in the ``on'' state. If we want subsequent uses of names to be in the ``off'' state, we can design a hook like:
-% \begin{quote}\small\setstretch{1.1}
-% |\renewcommand*|\meta{Hook}|[1]{|\texttt{\dots}\cmd{\AltOff}\cmd{\NameParser}\texttt{\dots}|}|
+% We create a hook that can ignore ignore the output of \cmd{\@nameauth at Name}, which is the \texttt{\#1} in the hook dispatcher's code \cmd{\bgroup}\meta{Hook}\texttt{\{\#1\}}\cmd{\egroup}:
+% \begin{quote}\small\MyStretch
+% |\renewcommand*|\meta{FirstHook}|[1]{|\texttt{\dots}\cmd{\NameParser}\texttt{\dots}|}|
% \end{quote}
%
-% If we used \cmd{\AltFormatActive*}, where the formatting macros are ``switched off'' but enabled nonetheless, then we might want a hook that turns the macros ``on'' instead:
-% \begin{quote}\small\setstretch{1.1}
+% With the \texttt{altformat} option or \cmd{\AltFormatActive} we can design a subsequent-use hook that deactivates formatting inside of it:
+% \begin{quote}\small\MyStretch
+% |\renewcommand*|\meta{SubsequentHook}|[1]{|\texttt{\dots}\cmd{\AltOff}\cmd{\NameParser}\texttt{\dots}|}|
+% \end{quote}
+%
+% If we used \cmd{\AltFormatActive*}, where the formatting macros are enabled, but deactivated, then we might want a hook that activates the macros:
+% \begin{quote}\small\MyStretch
% |\renewcommand*|\meta{Hook}|[1]{|\texttt{\dots}\cmd{\AltOn}\cmd{\NameParser}\texttt{\dots}|}|
% \end{quote}
+%
+% Within the hooks we can use the user-level parser as often as we want. We also can change internal Boolean flags, for example:
+% \begingroup
+% \begin{quote}\small
+% \StartNum
+% \begin{verbatim}
+%\makeatletter
+%\renewcommand*\NamesFormat[1]{\small%
+% \hbox to 3.5em{[now]\hfill}\space\NameParser\\%
+% \@nameauth at FullNametrue%
+% \hbox to 3.5em{[long]\hfill}\space\NameParser\\%
+% \@nameauth at FullNamefalse%
+% \@nameauth at FirstNametrue%
+% \hbox to 3.5em{[short]\hfill}\space\NameParser}
+%\makeatother
+%\let\MainNameHook\NamesFormat\end{verbatim}
%
-% We have shown\marginpar{\small\raggedleft\dbend} already that you do not really need \cmd{\NameParser} to use these switching macros in the hooks. Yet the user-level parser does have some handy uses, especially as we go further toward designing custom macros. For example, we demonstrate an extreme case based on Section~\ref{sec:Hooksa} where we modify some internal flags to have \cmd{\NameParser} to produce different syntactic forms than the normal output:\footnote{A similar version of this example is in \texttt{examples.tex}, collocated with this manual.}
-% \begin{quote}\small\setstretch{1.1}\makeatletter
-% \renewcommand*\NamesFormat[1]{#1\unless\ifinner\marginpar{\small\raggedleft\@nameauth at FullNametrue\@nameauth at FirstNamefalse\@nameauth at EastFNfalse\NameParser}\fi}
-% \renewcommand*\MainNameHook[1]{\AltOff#1\unless\ifinner\marginpar{\small\raggedleft\@nameauth at FullNamefalse\@nameauth at FirstNamefalse\@nameauth at EastFNfalse\NameParser}\fi}
-% |\makeatletter|\\
-% |\renewcommand*\NamesFormat[1]{#1\unless\ifinner|\\
-% | \marginpar{\small\raggedleft%|\\
-% | \@nameauth at FullNametrue\@nameauth at FirstNamefalse%|\\
-% | \@nameauth at EastFNfalse\NameParser}\fi}|\\
-% |\renewcommand*\MainNameHook[1]{\AltOff#1\unless\ifinner|\\
-% | \marginpar{\small\raggedleft%|\\
-% | \@nameauth at FullNamefalse\@nameauth at FirstNamefalse%|\\
-% | \@nameauth at EastFNfalse\NameParser}\fi}|\\
-% |\makeatother|\makeatother
+% \smallskip
+% \makeatletter
+% \renewcommand*\NamesFormat[1]{\small%^^A
+% \hbox to 3.5em{[now]\hfill}\space\NameParser\\%^^A
+% \@nameauth at FullNametrue%^^A
+% \hbox to 3.5em{[long]\hfill}\space\NameParser\\%^^A
+% \@nameauth at FullNamefalse%^^A
+% \@nameauth at FirstNametrue%^^A
+% \hbox to 3.5em{[short]\hfill}\space\NameParser}
+% \makeatother
+% \let\MainNameHook\NamesFormat
%
-% \Name[Wm.]{\noexpand\textSC{Shakespeare}}\hfill |\Name[Wm.]{\noexpand\textSC{Shakespeare}}|
+% |\JRIV| displays:
+%
+% \JRIV
+% \end{quote}
+% \endgroup
%
-% \Name[Wm.]{\noexpand\textSC{Shakespeare}}\hfill |\Name[Wm.]{\noexpand\textSC{Shakespeare}}|
+% The proof of concept above is interesting, but not very useful. Now we move on toward more useful designs, based on Sections~\ref{sec:Hooksi} and~\ref{sec:Hooksii}.
+% \newpage
+%
+% We begin by defining a name that is composed only of macros:
+% \begingroup
+% \newif\ifSpecialFN
+% \newif\ifSpecialSN
+% \newif\ifRevertSN
+% \newcommand*\WM{\ifSpecialFN Wm.\else William\fi}
+% \newcommand*\SHK{\ifRevertSN \textSC{Shakespeare}\else
+% \ifSpecialSN \noexpand\AltCaps{t}he Bard\else
+% \textSC{Shakespeare}\fi\fi}
+% \newcommand*\Revert{\RevertSNtrue}
+% \makeatletter
+% \renewcommand*\NamesFormat[1]{%^^A
+% \RevertSNfalse\SpecialFNfalse\SpecialSNfalse#1%^^A
+% \unless\ifinner\marginpar{%^^A
+% \footnotesize\raggedleft%^^A
+% \@nameauth at FullNametrue%^^A
+% \@nameauth at FirstNamefalse%^^A
+% \@nameauth at EastFNfalse%^^A
+% \SpecialFNtrue\SpecialSNfalse%^^A
+% \NameParser}%^^A
+% \fi\global\RevertSNfalse}
+% \renewcommand*\MainNameHook[1]{%^^A
+% \AltOff\SpecialFNfalse\SpecialSNtrue#1%^^A
+% \unless\ifinner
+% \unless\ifRevertSN
+% \marginpar{%^^A
+% \footnotesize\raggedleft%^^A
+% \@nameauth at FullNamefalse%^^A
+% \@nameauth at FirstNamefalse%^^A
+% \@nameauth at EastFNfalse%^^A
+% \SpecialFNfalse\SpecialSNfalse%^^A
+% \NameParser}%^^A
+% \fi
+% \fi\global\RevertSNfalse}
+% \makeatother
+% \begin{quote}\small
+% \StartNum
+% \begin{verbatim}
+%\begin{nameauth}
+% \< Shak & \noexpand\WM & \noexpand\SHK & >
+%\end{nameauth}
+%\PretagName[\noexpand\WM]{\noexpand\SHK}{Shakespeare, William}
+%\PretagName[Robert]{\textSC{Burns}}{Burns, Robert}\end{verbatim}
+% \end{quote}
%
-% \Name*[Wm.]{\noexpand\textSC{Shakespeare}}\hfill |\Name*[Wm.]{\noexpand\textSC{Shakespeare}}|
+% Now we define the flags by which the macros \cmd{\WM} and \cmd{\SHK} expand differently in the formatting hooks than in the index:
+% \begin{quote}\small
+% \ContinueNum
+% \begin{verbatim}
+%\newif\ifSpecialFN
+%\newif\ifSpecialSN
+%\newif\ifRevertSN
+%\newcommand*\WM{\ifSpecialFN Wm.\else William\fi}
+%\newcommand*\SHK{\ifRevertSN \textSC{Shakespeare}\else
+% \ifSpecialSN \noexpand\AltCaps{t}he Bard\else
+% \textSC{Shakespeare}\fi\fi}
+%\newcommand*\Revert{\RevertSNtrue}
+%\makeatletter\end{verbatim}
+% \end{quote}
%
-% \FName[Wm.]{\noexpand\textSC{Shakespeare}}[William]\hfill |\FName[Wm.]{\noexpand\textSC{Shakespeare}}[William]|
+% Finally, we define the two formatting hooks that trigger these changes:
+% \begin{quote}\small
+% \ContinueNum
+% \begin{verbatim}
+%\renewcommand*\NamesFormat[1]{%
+% \RevertSNfalse\SpecialFNfalse\SpecialSNfalse#1%
+% \unless\ifinner\marginpar{%
+% \footnotesize\raggedleft%
+% \@nameauth at FullNametrue%
+% \@nameauth at FirstNamefalse%
+% \@nameauth at EastFNfalse%
+% \SpecialFNtrue\SpecialSNfalse%
+% \NameParser}%
+% \fi\global\RevertSNfalse}
+%\renewcommand*\MainNameHook[1]{%
+% \AltOff\SpecialFNfalse\SpecialSNtrue#1%
+% \unless\ifinner
+% \unless\ifRevertSN
+% \marginpar{%
+% \footnotesize\raggedleft%
+% \@nameauth at FullNamefalse%
+% \@nameauth at FirstNamefalse%
+% \@nameauth at EastFNfalse%
+% \SpecialFNfalse\SpecialSNfalse%
+% \NameParser}%
+% \fi
+% \fi\global\RevertSNfalse}
+%\makeatother\end{verbatim}
%
-% \ForceName\Name[Wm.]{\noexpand\textSC{Shakespeare}}\\\hbox{}\hfill |\ForceName\Name[Wm.]{\noexpand\textSC{Shakespeare}}|
+% \smallskip
+% \Shak\ \cmd{\Shak} is the national poet of England in much the same way as \Name[Robert]{\textSC{Burns}} |\Name[Robert]{\textSC{Burns}}| is that of Scotland. With the latter's rise of influence in the 1800s, \Revert\Shak\ \cmd{\Revert}\cmd{\Shak} became known as ``\Shak'' \cmd{\Shak}.
% \end{quote}
+% \endgroup
%
-% In a first-use hook, the person's full name always is displayed in the margin. In a subsequent-use formatting hook, only a surname, ancient personal name, or mononym can be displayed in the margin.
+% First, we put macros \cmd{\WM} and \cmd{\SHK} in name arguments using \cmd{\noexpand}. That will make the index work properly. We use \cmd{\PretagName} to sort the names. We set up three flags. One is for \cmd{\WM} and two are for \cmd{\SHK}. \cmd{\Revert} is used to print a last name without a margin note.
%
-% We use the \cmd{\NameParser} macro to re-create the name, but using different rules via the internal Boolean flags. The macros that toggle these flags are discussed elsewhere. These include:
-% \begin{quote}\small\setstretch{1.1}
-% |\if at nameauth@FullName|\hfill Print a full name if true.\\
-% |\if at nameauth@FirstName|\hfill Print a first name if true.\\
-% Only one or the other of these can be true to avoid undocumented behavior.\\[1ex]
-% |\if at nameauth@RevThis|\hfill Reverse name order if true.\\
-% |\if at nameauth@EastFN|\hfill toggled by \cmd{\ForceFN}.\\
-% |\if at nameauth@RevThisComma|\hfill Reverse Western name, add comma.\\
-% Reversing without commas overrides reversing with commas.
-% \end{quote}
+%In the first-use hook we allow only the canonical name via \cmd{\RevertSNfalse}, \cmd{\SpecialFNfalse}, and \cmd{\SpecialSNfalse}. The default global formatting state is set by \cmd{\AltFormatActive}. We print the canonical name in the body text. If not in inner horizontal mode, we print a margin paragraph with an alternate full name using \cmd{\NameParser} and two flags. Both hooks set \cmd{\RevertSNfalse} so that \cmd{\Revert} works on a per-name basis. The subsequent-use hook disables formatting with \cmd{\AltOff}, but it allows variant forms.
%
-% Please\marginpar{\small\raggedleft\dbend} be aware that if you designed your own hooks for versions of \textsf{nameauth} before 3.0, it remains likely that they still work, but without the newer features. Updating your custom hooks is advised.
+% \begin{center}\bfseries Rolling Your Own: Advanced\end{center}
%
-% The older version of ``rolling your own'' is reminiscent of the newer way, but it has significant differences:
-% \begin{itemize}\small
-% \item We do not use the internal package macros.
-% \item We best use \cmd{\NameParser} to generate the name in the hooks. It may be possible not to do so, but as we get more customized the user-level parser is a handy way to get reasonably predictable results.
-% \item We still recommend using \cmd{\AltFormatActive} if you want to disable the normal effects of \cmd{\CapThis}. Otherwise redefine \cmd{\CapThis} (which is what we do below).
-% \end{itemize}
+% Here\Warn{} is how formatting hooks were designed before version 3.0. Updating these older hooks is helpful, but may not be necessary. Here we do not use the internal package macros. We only use \cmd{\NameParser} in the hooks to produce output. We still recommend using \cmd{\AltFormatActive} to prevent problems with \cmd{\CapThis}.
%
-%\newif\ifFbox
-%\newif\ifFirstCap
-%\newif\ifInHook
-%\Fboxtrue
-% We define three Boolean flags and set one of them true by default. The \texttt{\textbackslash ifFbox} flag takes over the internal function of \texttt{\textbackslash @nameauth at DoAlt}, which is enabled by \cmd{\AltFormatActive}. The \texttt{\textbackslash ifFirstCap} flag takes over the internal function of \texttt{\textbackslash @nameauth at DoCaps}, which is enabled by \cmd{\CapThis}. The \texttt{\textbackslash ifInHook} flag replaces the internal function of \texttt{\textbackslash @nameauth at InHook}, which is enabled by the internal format hook dispatcher.\footnote{A similar version of this example is in \texttt{examples.tex}, collocated with this manual.}
-%\begin{quote}\small\setstretch{1.1}
-% |\newif\ifFbox|\\
-% |\newif\ifFirstCap|\\
-% |\newif\ifInHook|\\
-% |\Fboxtrue|
-%\end{quote}
+% \newif\ifFbox
+% \newif\ifFirstCap
+% \newif\ifInHook
+% \Fboxtrue
+% Three flags replace package internals. \texttt{\textbackslash @nameauth at DoAlt} activates formatting; \texttt{\textbackslash @nameauth at DoCaps} is set by \cmd{\CapThis}; and \texttt{\textbackslash @nameauth at InHook} is set by the hook dispatcher. Setting \texttt{\textbackslash Fboxtrue} is equivalent to using \cmd{\AltFormatActive}:
+% \begin{quote}\small
+% \StartNum
+% \begin{verbatim}
+%\newif\ifFbox% Replaces \@nameauth at DoAlt
+%\newif\ifFirstCap% Replaces \@nameauth at DoCaps
+%\newif\ifInHook% Replaces \@nameauth at InHook
+%\Fboxtrue\end{verbatim}
+% \end{quote}
%
-%\renewcommand*\Fbox[1]{\ifFbox\fbox{#1}\else#1\fi}
-% The formatting macro is like the new style, except it refers to \texttt{\textbackslash ifFbox}:
-%\begin{quote}\small\setstretch{1.1}
-% |\renewcommand*\Fbox[1]{%|\\
-% | \ifFbox\fbox{#1}\else#1\fi|\\
-% |}|
-%\end{quote}
+% \renewcommand*\Fbox[1]{\ifFbox\protect\fbox{#1}\else#1\fi}
+% The formatting macro is like what we have seen, except it refers to \texttt{\textbackslash ifFbox}:
+% \begin{quote}\small
+% \ContinueNum
+% \begin{verbatim}
+%\renewcommand*\Fbox[1]{%
+% \ifFbox\protect\fbox{#1}\else#1\fi
+%}\end{verbatim}
+% \end{quote}
%
-%\renewcommand*\AltCaps[1]{\ifInHook
+% \renewcommand*\AltCaps[1]{\ifInHook
+% \ifFirstCap\MakeUppercase{#1}\else#1\fi
+% \else
+% #1\fi}
+% Our new \cmd{\AltCaps} works like the built-in version, except it does not use the internal macros and flags:
+% \begin{quote}\small
+% \ContinueNum
+% \begin{verbatim}
+%\renewcommand*\AltCaps[1]{%
+% \ifInHook
% \ifFirstCap\MakeUppercase{#1}\else#1\fi
% \else
-% #1\fi}
-% Our new \cmd{\AltCaps} works like the built-in version, except it does not use the internal macros and flags:
-%\begin{quote}\small\setstretch{1.1}
-% |\renewcommand*\AltCaps[1]{%|\\
-% | \ifInHook|\\
-% | \ifFirstCap\MakeUppercase{#1}\else#1\fi|\\
-% | \else|\\
-% | #1%|\\
-% | \fi|\\
-% |}|
-%\end{quote}
+% #1%
+% \fi
+%}\end{verbatim}
+% \end{quote}
%
-%\renewcommand*\CapThis{\FirstCaptrue}
-%\renewcommand*\NamesFormat[1]
-%{\InHooktrue\NameParser\InHookfalse\global\FirstCapfalse}
-%\renewcommand*\MainNameHook[1]
-%{\Fboxfalse\InHooktrue\NameParser\InHookfalse\global\FirstCapfalse\Fboxtrue}
-%\let\FrontNamesFormat\Namesformat
-%\let\FrontNameHook\MainNameHook
+% \renewcommand*\CapThis{\FirstCaptrue}
+% \renewcommand*\NamesFormat[1]
+% {\InHooktrue\NameParser\global\FirstCapfalse}
+% \renewcommand*\MainNameHook[1]
+% {\Fboxfalse\InHooktrue\NameParser\global\FirstCapfalse}
+% \let\FrontNamesFormat\Namesformat
+% \let\FrontNameHook\MainNameHook
% Here we redefine \cmd{\CapThis} to use our flag instead of the internal flag:
-%\begin{quote}\small\setstretch{1.1}
-% |\renewcommand*\CapThis{\FirstCaptrue}|
-%\end{quote}
+% \begin{quote}\small
+% \ContinueNum
+% \begin{verbatim}
+%\renewcommand*\CapThis{\FirstCaptrue}\end{verbatim}
+% \end{quote}
%
-% We have to do in our own hooks what the naming macros do internally in order to get the same exit conditions. In the new style, we do not have to define \cmd{\NamesFormat}. Here we have to define everything:
-%\begin{quote}\small\setstretch{1.1}
-% |\renewcommand*\NamesFormat[1]|\\
-% |{%|\\
-% | \InHooktrue\NameParser\InHookfalse%|\\
-% | \global\FirstCapfalse%|\\
-% |}|
-%\end{quote}
+% We have to reproduce the logic and macros that the package would have provided. That means defining everything, including \cmd{\NamesFormat}, from scratch:
+% \begin{quote}\small
+% \ContinueNum
+% \begin{verbatim}
+%\renewcommand*\NamesFormat[1]
+% {\InHooktrue\NameParser\global\FirstCapfalse}\end{verbatim}
+% \end{quote}
%
-% Instead of using just \cmd{\AltOff} before \cmd{\NameParser} below, we have to add a few extras in order to mimic the functions of the internal flags:
-%\begin{quote}\small\setstretch{1.1}
-% |\renewcommand*\MainNameHook[1]|\\
-% |{%|\\
-% | \Fboxfalse\InHooktrue\NameParser\InHookfalse%|\\
-% | \global\FirstCapfalse\Fboxtrue%|\\
-% |}|
-%\end{quote}
-%\clearpage
+% Changes to \texttt{\textbackslash ifInHook} (default false) and \texttt{\textbackslash ifFbox} (default true) are local to the scope in which the hook macros are called. \texttt{\textbackslash ifFirstCap} must be set globally. Below we reproduce the logic of \cmd{\AltOff} before \cmd{\NameParser}:
+% \begin{quote}\small
+% \ContinueNum
+% \begin{verbatim}
+%\renewcommand*\MainNameHook[1]
+%{\Fboxfalse\InHooktrue\NameParser\global\FirstCapfalse}\end{verbatim}
+% \end{quote}
%
% We avoid spurious index entries in the front matter by using the same hooks.
-%\begin{quote}\small\setstretch{1.1}
-% |\let\FrontNamesFormat\Namesformat|\\
-% |\let\FrontNameHook\MainNameHook|
-%\end{quote}
+% \begin{quote}\small
+% \ContinueNum
+% \begin{verbatim}
+%\let\FrontNamesFormat\Namesformat
+%\let\FrontNameHook\MainNameHook\end{verbatim}
+% \end{quote}
%
-% Because we use \cmd{\noexpand}, our ``old-style'' macros will index the name below under the same entry as the ``new-style'' macros.
+% Because we use \cmd{\noexpand}, our ``old-style'' macros will index the following names under the same entry as the ``new-style'' macros.
% \begin{center}\footnotesize
% \begin{tabular}{llll}\toprule
% First & Next & Long & Short \\\midrule
@@ -3375,170 +4465,467 @@
% \end{tabular}
% \end{center}
%
-% The capitalized version |\CapThis\deSmet| is \CapThis\deSmet. This also works for a formatted use via \cmd{\ForceName}: \ForceName\CapThis\deSmet.\medskip
+% The capitalized version |\CapThis\deSmet| is \CapThis\deSmet. This also works for a formatted use via \cmd{\ForceName}: \ForceName\CapThis\deSmet.
%
-% We can reuse\marginpar{\raggedleft\dbend} new-style names with old-style macros when needed. We show this here in abbreviated fashion. We keep the Boolean flags \texttt{\textbackslash ifFirstCap} and \texttt{\textbackslash ifInHook} from earlier. We also keep the redefined \cmd{\AltCaps}, \cmd{\CapThis}, and \cmd{\NamesFormat}. One might have to make modifications as needed.\footnote{A fuller version of this example is in \texttt{examples.tex}, collocated with this manual.}
+% We can reuse\Warn{} new-style names with old-style macros, shown below in abbreviated fashion. We keep the flags \texttt{\textbackslash ifFirstCap} and \texttt{\textbackslash ifInHook}. We also keep the redefined \cmd{\AltCaps}, \cmd{\CapThis}, and \cmd{\NamesFormat}. We then add:
+% \newif\ifCaps
+% \Capstrue
+% \renewcommand*\textSC[1]{\ifCaps\textsc{#1}\else#1\fi}
+% \renewcommand*\MainNameHook[1]
+% {\Capsfalse\InHooktrue\NameParser\global\FirstCapfalse}
+% \let\FrontNameHook\MainNameHook
+% \begin{quote}\small
+% \StartNum
+% \begin{verbatim}
%\newif\ifCaps
%\Capstrue
-%\renewcommand*\textSC[1]{\ifCaps\textsc{#1}\else#1\fi}
+%\renewcommand*\textSC[1]{%
+% \ifCaps\textsc{#1}\else#1\fi
+%}
%\renewcommand*\MainNameHook[1]
-%{\Capsfalse\InHooktrue\NameParser\InHookfalse\global\FirstCapfalse\Capstrue}
-%\let\FrontNameHook\MainNameHook
-%\begin{quote}\small\setstretch{1.1}
-% |\newif\ifCaps|\\
-% |\Capstrue|\\
-% |\renewcommand*\textSC[1]{%|\\
-% | \ifCaps\textsc{#1}\else#1\fi|\\
-% |}|\\
-% |\renewcommand*\MainNameHook[1]|\\
-% |{%|\\
-% | \Capsfalse\InHooktrue\NameParser\InHookfalse%|\\
-% | \global\FirstCapfalse\Capstrue%|\\
-% |}|\\
-% |\let\FrontNameHook\MainNameHook|
-%\end{quote}
+%{%
+% \Capsfalse\InHooktrue\NameParser%
+% \global\FirstCapfalse%
+%}
+%\let\FrontNameHook\MainNameHook\end{verbatim}
+% \end{quote}
%
-% The names below have the same declarations and index entries as they did above. They look and work the same but use different macros.
+% The names below have the same declarations and index entries as they did above. They look and work the same but use different back-end macros:
% \begin{center}
% \small\noindent\begin{tabular}{llll}\toprule
% First & Next & Long & Short \\\midrule
% \ForgetThis\Adams & \Adams & \LAdams & \SAdams\\
-% \ForgetThis\SDJR & \SDJR & \LSDJR & \SSDJR\\
+% \rowcolor{black!7!white}\ForgetThis\SDJR & \SDJR & \LSDJR & \SSDJR\\
% \ForgetThis\HAR & \HAR & \LHAR & \SHAR\\
-% \ForgetThis\Mencius & \Mencius & \LMencius & \SMencius\\\bottomrule
+% \rowcolor{black!7!white}\ForgetThis\Mencius & \Mencius & \LMencius & \SMencius\\\bottomrule
% \end{tabular}
% \end{center}
%
-% As earlier, punctuation detection works: \ForceName\LSDJR. Also \LSDJR. Then \ForceName\SDJR. Now \SDJR. \cmd{\ForceName}\cmd{\DropAffix}\cmd{\LSDJR} gives \ForceName\DropAffix\LSDJR. \cmd{\DropAffix}\cmd{\LSDJR} gives \DropAffix\LSDJR. \cmd{\RevComma}\cmd{\LAdams} yields \RevComma\LAdams. \cmd{\ForceName}\cmd{\ForceFN}\cmd{\SHAR} produces \ForceName\ForceFN\SHAR. \cmd{\ForceFN}\cmd{\SHAR} produces \ForceFN\SHAR. If we add \cmd{\CapThis} we get \CapThis\ForceName\ForceFN\SHAR\ and \CapThis\ForceFN\SHAR.
+% \begin{itemize}\small
+% \item Punctuation detection works: \ForceName\LSDJR. Also \LSDJR. Then \ForceName\SDJR. Now \SDJR. (We used \cmd{\ForceName} for formatting.)
+% \item \cmd{\ForceName}\cmd{\DropAffix}\cmd{\LSDJR} gives \ForceName\DropAffix\LSDJR. Otherwise, only using the macro \cmd{\DropAffix}\cmd{\LSDJR} gives \DropAffix\LSDJR.
+% \item \cmd{\RevComma}\cmd{\LAdams} yields \RevComma\LAdams. All the reversing macros work.
+% \item \cmd{\ForceName}\cmd{\ForceFN}\cmd{\SHAR} produces \ForceName\ForceFN\SHAR. \cmd{\ForceFN}\cmd{\SHAR} produces \ForceFN\SHAR. If we add \cmd{\CapThis} we get \CapThis\ForceName\ForceFN\SHAR\ and \CapThis\ForceFN\SHAR.
+% \end{itemize}
%
-% Use names with alternate formatting only when it is active to avoid spurious index entries. We resume normal formatting with \cmd{\AltFormatInactive}.
+% We now resume normal formatting with \cmd{\AltFormatInactive} and close the scope that we began at the start of Section~\ref{sec:Hooksi}.
% \AltFormatInactive\endgroup
%
-% {\medskip\noindent\hbox{}\hfill\large Back to Section~\ref{sec:RefTables} \hfill\hbox{}}
-% \clearpage
+% \ReturnLink
+% \newpage
%
-% \subsubsection{Full Redesign}
-% \label{sec:NewEngine}
+% \subsubsection{Customization}
+% \label{sec:Customize}
%
-% Assuming\marginpar{\small\raggedleft\dbend\dbend} 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.
+% Assuming\Warn{} that redefining hooks and adding control sequences is insufficient, one could redesign the core name macros partially or wholly, then hook those modifications into the \textsf{nameauth} package without needing to patch the style file itself.
%
% \DescribeMacro{\NameauthName}
+% All these macros are set by default to \cmd{\@nameauth at Name}, the internal name parser.
% \DescribeMacro{\NameauthLName}
+% \cmd{\Name}, or an unmodified shorthand, calls \cmd{\NameauthName}. \cmd{\Name*}, or an L-shorthand, sets \cmd{\@nameauth at FullNametrue}, then calls \cmd{\NameauthLName}.
% \DescribeMacro{\NameauthFName}
-% These macros are set by default to \cmd{\@nameauth at Name}, the internal name parser. The main and simplified interfaces call them as respective synonyms for \cmd{\Name}, \cmd{\Name*}, and \cmd{\FName}. Should you desire to create your own naming macros, you can redefine them. Here is the minimal working example:
-% \begin{quote}\small\setstretch{1.1}
-% |\makeatletter|\\
-% |\newcommandx*\MyName[3][1=\@empty, 3=\@empty]{|\meta{Name}|}|\\
-% |\newcommandx*\MyLName[3][1=\@empty, 3=\@empty]|\\
-% | {|\meta{Long name}|\@nameauth at FullNamefalse}|\\
-% |\newcommandx*\MyFName[3][1=\@empty, 3=\@empty]|\\
-% | {|\meta{Short name}|\@nameauth at FirstNamefalse}|\\
-% |\makeatother|
+% \cmd{\FName}, or an S-shorthand, sets \cmd{\@nameauth at FirstNametrue}, then calls \cmd{\NameauthFName}. One should not modify \cmd{\Name} and \cmd{\FName} directly.
+%
+% Next we see a minimal working example that implements the obsolete syntax. We use few internal Boolean values, save those governing name forms. We do not implement short forms or any other features in \textsf{nameauth}. We must index the names with \cmd{\IndexName}. This example shows how to hook these redefined macros into the user interface:
+%
+% \begin{quote}\small
+% \StartNum
+% \begin{verbatim}
+%\makeatletter
+%\newcommandx*\MyName[3][1=\@empty, 3=\@empty]{%
+% \protected at edef\a{\trim at spaces{#1}}%
+% \protected at edef\b{\trim at spaces{#2}}%
+% \protected at edef\c{\trim at spaces{#3}}%
+% \ifx\b\empty fail \else
+% \ifx\a\empty
+% \ifx\c\empty \hbox to 5em{Mononym:\hfill} {\b}\else
+% \hbox to 5em{Eastern:\hfill} {\b\ \c}\fi
+% \else
+% \ifx\c\empty \hbox to 5em{Western:\hfill} {\a\ \b}\else
+% \hbox to 5em{Alternate:\hfill} {\c\ \b}\fi
+% \fi
+% \fi
+% \global\@nameauth at FullNamefalse%
+% \global\@nameauth at FirstNamefalse%
+%}
+%\makeatother
+%\let\MyLName\MyName
+%\let\MyFName\MyName
+%\renewcommand*\NameauthName{\MyName}
+%\renewcommand*\NameauthLName{\MyLName}
+%\renewcommand*\NameauthFName{\MyFName}
+%\IndexName[George]{Washington}
+%\IndexName[M.T.]{Cicero}
+%\IndexName{Dagobert}[I]
+%\IndexName{Aristotle}\end{verbatim}
+% \makeatletter
+% \newcommandx*\MyName[3][1=\@empty, 3=\@empty]{%^^A
+% \protected at edef\a{\trim at spaces{#1}}%^^A
+% \protected at edef\b{\trim at spaces{#2}}%^^A
+% \protected at edef\c{\trim at spaces{#3}}%^^A
+% \ifx\b\empty fail \else
+% \ifx\a\empty
+% \ifx\c\empty \hbox to 5em{Mononym:\hfill} {\b}\else
+% \hbox to 5em{Eastern:\hfill} {\b\ \c}\fi
+% \else
+% \ifx\c\empty \hbox to 5em{Western:\hfill} {\a\ \b}\else
+% \hbox to 5em{Alternate:\hfill} {\c\ \b}\fi
+% \fi
+% \fi
+% \global\@nameauth at FullNamefalse%^^A
+% \global\@nameauth at FirstNamefalse%^^A
+% }
+% \makeatother
+% \let\MyLName\MyName
+% \let\MyFName\MyName
+% \renewcommand*\NameauthName{\MyName}
+% \renewcommand*\NameauthLName{\MyLName}
+% \renewcommand*\NameauthFName{\MyFName}
+% \IndexName[George]{Washington}
+% \IndexName[M.T.]{Cicero}
+% \IndexName{Dagobert}[I]
+% \IndexName{Aristotle}\bigskip
+%
+% \begin{tabular}{rl}
+% \cmd{\Wash} & \Wash \\
+% \cmd{\Cicero[Marcus Tullius]} & \Cicero[Marcus Tullius] \\
+% \cmd{\Dagb} & \Dagb \\
+% \cmd{\Aris} & \Aris \\
+% \end{tabular}
% \end{quote}
%
-% The macros above do not really work together with the rest of \textsf{nameauth} package, so be careful! You can hook these macros into the user interface thus:
-% \begin{quote}\small\setstretch{1.1}
-% \makeatletter%
-% \newcommandx*\MyName[3][1=\@empty, 3=\@empty]{\meta{Name}}%
-% \newcommandx*\MyLName[3][1=\@empty, 3=\@empty]{\meta{Long name}\@nameauth at FullNamefalse}%
-% \newcommandx*\MyFName[3][1=\@empty, 3=\@empty]{\meta{Short name}\@nameauth at FirstNamefalse}%
-% \makeatother%
-% |\renewcommand*\NameauthName{\MyName}|\\
-% |\renewcommand*\NameauthLName{\MyLName}|\\
-% |\renewcommand*\NameauthFName{\MyFName}|\\
-% |\begin{nameauth}|\\
-% | \< Silly & No Particular & Name & >|\\
-% |\end{nameauth}|\\
-% |This is \Silly, \LSilly, and \SSilly.|\\
+% The previous example is not particularly useful. There is, however, a more practical use for these macros. One could choose to implement additional features, then pass the information in the name argument token registers to the extant parsing macros of \textsf{nameauth} (cf. Section~\ref{sec:Hooksii}).
+% \newpage
+%
+% Below we introduce formatting that is additional to, inter-operative with, yet distinct from the formatting hooks:
+% \begin{quote}\small
+% \StartNum
+% \begin{verbatim}
+%\makeatletter
+%\newcommandx*\MyName[3][1=\@empty, 3=\@empty]{%
+% \@nameauth at toksa\expandafter{#1}%
+% \@nameauth at toksb\expandafter{#2}%
+% \@nameauth at toksc\expandafter{#3}%
+% \hbox to 4em{Normal: \hfill}%
+% \fcolorbox{black}{gray!25!white}{\@nameauth at Name[#1]{#2}[#3]}%
+%}
+%\newcommandx*\MyLName[3][1=\@empty, 3=\@empty]{%
+% \@nameauth at toksa\expandafter{#1}%
+% \@nameauth at toksb\expandafter{#2}%
+% \@nameauth at toksc\expandafter{#3}%
+% \hbox to 4em{Long: \hfill}%
+% \fcolorbox{black}{green!25!white}{\@nameauth at Name[#1]{#2}[#3]}%
+%}
+%\newcommandx*\MyFName[3][1=\@empty, 3=\@empty]{%
+% \@nameauth at toksa\expandafter{#1}%
+% \@nameauth at toksb\expandafter{#2}%
+% \@nameauth at toksc\expandafter{#3}%
+% \hbox to 4em{Short: \hfill}%
+% \fcolorbox{black}{yellow!25!white}{\@nameauth at Name[#1]{#2}[#3]}%
+%}
+%\makeatother
+%\renewcommand*\NamesFormat[1]
+% {\hbox to 9em{\hfil\scshape#1\hfil}}
+%\renewcommand*\MainNameHook[1]{\hbox to 9em{\hfil#1\hfil}}
+%\renewcommand*\NameauthName{\MyName}
+%\renewcommand*\NameauthLName{\MyLName}
+%\renewcommand*\NameauthFName{\MyFName}\end{verbatim}
+%
+% \makeatletter
+% \newcommandx*\MyName[3][1=\@empty, 3=\@empty]{%^^A
+% \@nameauth at toksa\expandafter{#1}%^^A
+% \@nameauth at toksb\expandafter{#2}%^^A
+% \@nameauth at toksc\expandafter{#3}%^^A
+% \hbox to 4em{Normal: \hfill}%^^A
+% \fcolorbox{black}{gray!25!white}{\@nameauth at Name[#1]{#2}[#3]}%^^A
+% }
+% \newcommandx*\MyLName[3][1=\@empty, 3=\@empty]{%^^A
+% \@nameauth at toksa\expandafter{#1}%^^A
+% \@nameauth at toksb\expandafter{#2}%^^A
+% \@nameauth at toksc\expandafter{#3}%^^A
+% \hbox to 4em{Long: \hfill}%^^A
+% \fcolorbox{black}{green!25!white}{\@nameauth at Name[#1]{#2}[#3]}%^^A
+% }
+% \newcommandx*\MyFName[3][1=\@empty, 3=\@empty]{%^^A
+% \@nameauth at toksa\expandafter{#1}%^^A
+% \@nameauth at toksb\expandafter{#2}%^^A
+% \@nameauth at toksc\expandafter{#3}%^^A
+% \hbox to 4em{Short: \hfill}%^^A
+% \fcolorbox{black}{yellow!25!white}{\@nameauth at Name[#1]{#2}[#3]}%^^A
+% }
+% \makeatother
+% \renewcommand*\NamesFormat[1]{\hbox to 9em{\hfil\scshape#1\hfil}}
+% \renewcommand*\MainNameHook[1]{\hbox to 9em{\hfil#1\hfil}}
% \renewcommand*\NameauthName{\MyName}%
% \renewcommand*\NameauthLName{\MyLName}%
-% \renewcommand*\NameauthFName{\MyFName}%
-% \begin{nameauth}
-% \< Silly & No Particular & Name & >
-% \end{nameauth}
-% This is \Silly, \LSilly, and \SSilly.
+% \renewcommand*\NameauthFName{\MyFName}
+%
+% \smallskip
+% |\ForgetName[Adolf]{Harnack}|\ForgetName[Adolf]{Harnack}\\[1ex]
+% \begin{tabular}{@{}rl}
+% |\Harnack| & \Harnack\\
+% |\LHarnack[Adolf von]| & \LHarnack[Adolf von]\\
+% |\Harnack| & \Harnack\\
+% |\SHarnack| & \SHarnack\\
+% \end{tabular}
% \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 \cmd{\NameauthName}, \cmd{\NameauthLName}, and \cmd{\NameauthFName} have reverted back to their original forms. Now |\Name[No Particular]{Name}| and \cmd{\Silly} produce {\IndexInactive\Name[No Particular]{Name} and \Silly.}
-% \vfil
-% \begin{center}\large \emph{This space intentionally left blank.}\end{center}
-% \clearpage
+% After\Version{3.3} the name is printed in the body text, the internal macros \emph{globally} set \cmd{\@nameauth at FullNamefalse} and \cmd{\@nameauth at FirstNamefalse}, as well as other flags related to the prefix macros. This prevents certain cases of undocumented behavior in versions of \textsf{nameauth} before 3.3, where resetting flags locally could cause unexpected name forms. If an existing document leverages the local resetting of flags, one can use the \texttt{oldreset} option. Compare Section~\ref{sec:IndexControl}.\medskip
%
+% Like\Info{\cmd{\global}} many of the 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}.
+%
+% \ReturnLink
+% \newpage
+% \endgroup^^A End of hook macro redefinition.
+%
% \subsection{Technical Notes}
-% \label{sec:notes}
+% \label{sec:TechNotes}
+%
+% \hfil This manual was created with
+% \fbox{\mystrut\ \bfseries\ifxetex xelatex (pdf)%^^A
+% \else
+% \ifluatex
+% \ifpdf lualatex (pdf)%^^A
+% \else lualatex (dvi)%^^A
+% \fi
+% \else
+% \ifpdf pdflatex%^^A
+% \else latex (dvi)%^^A
+% \fi
+% \fi
+% \fi\ }
+%
+% \ifDoTikZ\begin{tcolorbox}[colback=white,colframe=nared,adjusted title={\hfil Thanks}]\else
+% \begin{center}\large\bfseries Thanks\end{center}\fi
+% \noindent Thanks to \Name[Marc van]{Dongen}, \Name[Enrico]{Gregorio}, \Name[Philipp]{Stephani}, \Name*[Heiko]{Oberdiek}, \Name[Uwe]{Lueck}, \Name[Dan]{Luecking} and \Name[Robert]{Schlicht} for assistance in early versions of this package. Thanks also to users for valuable feedback.\vfil
+% \ifDoTikZ\end{tcolorbox}\fi
+%
+% \subsubsection{General}
+% \label{sec:GenNotes}
+%
% About the package itself:
-% \begin{itemize}\small
-% \item We put great weight on being backward-compatible with older versions.
-% \item Recent changes aim for simpler work flow, not more features.
-% \item The package works with both \texttt{xindy} and \texttt{makeindex}. We recommend \texttt{xindy} for languages whose collating sequences do not map to English.\footnote{\cmd{\PretagName} may not be useful in that case. German \emph{does} map to English: ä, ö, ü, and ß are ae, oe, ue, and ss. Norwegian \emph{does not} map to English: æ, ø, and å come after z.}
-% \item We\marginpar{\large\raggedleft\textsf{\bfseries 3.0}\strut} support alternate names in both Western and ``native'' Eastern forms. Mononyms and the older syntax for non-Western names do not support alternate names.
-% \item Name\marginpar{\large\raggedleft\textsf{\bfseries 3.0}\strut} output, index entries, and index cross-references are independent modules.
-% \item Warnings\marginpar{\large\raggedleft\textsf{\bfseries 3.0}\strut} for the indexing macros are suppressed unless one uses the \texttt{verbose} option. The \texttt{nameauth} environment will continue to emit warnings as needed.
-% \item The\marginpar{\large\raggedleft\textsf{\bfseries 2.6}\strut} \texttt{comma} option and the older syntax are no longer restrictive, save with \cmd{\AKA} and its derivatives. See Sections~\ref{sec:obsolete}, \ref{sec:Affix}, and~\ref{sec:AKA}.
-% \item No\marginpar{\large\raggedleft\textsf{\bfseries 2.5\strut}} formatting is selected by default. Cf. Sections~\ref{sec:formatting}, \ref{sec:Hooksa}, \ref{sec:Hooksb}, and~\ref{sec:Hooksc}.
+% \begin{itemize}
+% \item For version 3.2 behavior, use both the \texttt{oldpass} and \texttt{oldreset} options.
+% \item For version 2.6 behavior, use \texttt{oldpass}, \texttt{oldreset}, and \texttt{oldAKA}.
+% \item The package works with both \texttt{xindy} and \texttt{makeindex}.
+% \item Name\Version{3.0} output, index entry creation, and index cross-reference creation occur in independent modules.
+% \item Use\Version{3.0} the \texttt{verbose} option for warnings about indexing.
+% \item The \texttt{nameauth} environment always will emit warnings as needed.
+% \item The\Version{2.6} \texttt{comma} option and the older syntax are no longer restrictive, save with \cmd{\AKA} and its derivatives. See Sections~\ref{sec:Obsolete}, \ref{sec:Affix}, and~\ref{sec:AKA}.
+% \item No\Version{2.5} formatting is selected by default.
% \end{itemize}
% \noindent About the manual:
-% \begin{itemize}\small
-% \item This manual is compatible with both A4 and US letter formats.
-% \item For an index that focuses on using the names, we minimize macro references.
-% \item We mention when this manual changes package internals for an example.
-% \item The name pattern reference was removed for redundancy and obsolescence.
+% \begin{itemize}
+% \item This manual is the test suite.
+% \item This manual is designed for both current and older \LaTeX\ distributions.
+% \item This\Version{3.3} manual has been redesigned.
+% \item It is compatible with both A4 and US letter formats.
+% \item We mention when this manual changes package internals.
% \end{itemize}
% About package building:
-% \begin{itemize}\small
-% \item The \textsf{nameauth} package requires \textsf{etoolbox}, \textsf{suffix}, \textsf{trimspaces}, and \textsf{xargs}. The \texttt{dtx} file encoding is UTF-8; we cannot guarantee building and using this package on systems that are not Unicode-compliant.
-% \item With each release, we test \textsf{nameauth} with dvi-mode \texttt{latex} and with pdf-mode engines \texttt{pdflatex}, \texttt{lualatex}, and \texttt{xelatex} using \texttt{makeindex}. We run the GNU Makefile with the ENGINE=\meta{engine} option.\footnote{The manual is used as the test suite. In dvi mode the manual omits all references to \emph{TikZ} because some dvi display programs (\emph{e.g.} \texttt{dviout}, but not \texttt{xdvi}) will emit errors about bad specials even if one just includes the \textsf{tikz} package. The \emph{TikZ} diagrams herein will appear as blank space in that case. This does not affect \textsf{nameauth} proper.}
-% \item This package was built 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. This item changes per \LaTeX\ engine.
-% \item This package is tested on Ubuntu Linux and Windows 7 (both vanilla \TeX\ Live). Cygwin provides \texttt{make} on Windows. The \texttt{pdflatex} version of this package is released from the Ubuntu platform to CTAN.
+% \begin{itemize}
+% \item The \textsf{nameauth} package requires \textsf{etoolbox}, \textsf{suffix}, \textsf{trimspaces}, and \textsf{xargs}. The \texttt{dtx} file encoding is UTF-8; we assume Unicode support.
+% \item We tested this release in \texttt{dvi} mode (\texttt{latex} and \texttt{dvilualatex}), and in \texttt{pdf} mode (\texttt{pdflatex}, \texttt{lualatex}, and \texttt{xelatex}). We used \texttt{makeindex}.
+% \item This release has been tested on GNU/Linux (distro TL 2017 and vanilla TL 2019), and Windows (Mik\TeX, using GNU make via Cygwin.)
+% \item The release uploaded to CTAN is generated using \texttt{pdflatex} in GNU/Linux.
% \end{itemize}
-% \clearpage
+% \newpage
+%
+% \subsubsection{Active Unicode}
+% \label{sec:Unicode}
%
-% \subsection{Errors and Warnings}
-% \label{sec:error}
+% With |\usepackage[T1]{fontenc}| we can use many active Unicode characters automatically.\footnote{As of release, most documents typeset with \texttt{latex} and \texttt{pdflatex} do not require explicit loading of either \textsf{inputenc} or \textsf{inputenx}.}
+% We already covered using \cmd{\PretagName} to sort names with these characters (Section~\ref{sec:IndexSort}).
+% Below we group by accents and diacritical marks:
%
-% Here are some ways to avoid common errors:
+% \begin{center}\small\setstretch{1.4}
+% \def\Bullet#1{\setbox0\hbox{#1}\raise 0.4ex\hbox to\wd0{\hfil\tiny\textbullet\hfil}}
+% \def\bullet#1{\setbox0\hbox{#1}\raise 0.2ex\hbox to\wd0{\hfil\tiny\textbullet\hfil}}
+% \begin{tabular}{lll}\toprule
+% acute & Á Ć É Ǵ \Bullet{H} Í Ĺ Ń Ó Ŕ Ś Ú Ý Ź & á ć é ǵ \bullet{h} í ĺ ń ó ŕ ś ú ý ź \strut\\
+% \rowcolor{black!7!white}grave & À \Bullet{C} È \Bullet{G} \Bullet{H} Ì Ò Ù & à \bullet{c} è \bullet{g} \bullet{h} ì ò ù \strut\\
+% circumflex & Â Ĉ Ê Ĝ Ĥ Î Ĵ Ô Ŝ Û Ŵ Ŷ & â ĉ ê ĝ ĥ î ĵ ô ŝ û ŵ ŷ \strut\\
+% \rowcolor{black!7!white}tilde & Ã \Bullet{C} \Bullet{E} \Bullet{G} \Bullet{H} Ĩ Ñ Õ Ũ & ã \bullet{c} \bullet{e} \bullet{g} \Bullet{h} ĩ ñ õ ũ \strut\\
+% diaresis\footnotemark & Ä \Bullet{C} Ë \Bullet{G} \Bullet{H} Ï Ö Ü Ÿ & ä \bullet{c} ë \bullet{g} \bullet{h} ï ö ü ÿ \strut\\
+% \rowcolor{black!7!white}cedilla & \Bullet{A} Ç \Bullet{E} Ģ Ķ Ļ Ņ Ŗ Ş Ţ & \bullet{a} ç \bullet{e} ģ ķ ļ ņ ŗ ş ţ \strut\\
+% macron & Ā \Bullet{C} Ē Ḡ \Bullet{H} Ī Ō Ū Ǣ Ȳ & ā \bullet{c} ē ḡ \bullet{h} ī ō ū ǣ ȳ \strut\\
+% \rowcolor{black!7!white}breve & Ă \Bullet{C} \Bullet{E} Ğ \Bullet{H} Ĭ Ŏ Ŭ & ă \bullet{c} \bullet{e} ğ \bullet {h} ĭ ŏ ŭ \strut\\
+% dot\,/\,dotless & Ḃ Ċ Ė Ġ \Bullet{H} İ Ż & ḃ ċ ė ġ \bullet{h} ı ż \strut\\
+% \rowcolor{black!7!white}ogonek & Ą \Bullet{C} Ę \Bullet{G} \Bullet{H} Į Ǫ Ų & ą \bullet{c} ę \bullet{g} \bullet{h} į ǫ ų \strut\\
+% caron & Ǎ Č Ď Ě Ǧ Ǐ Ǩ Ľ Ň Ǒ Ř Š Ť Ǔ Ž & ǎ č ď ě ǧ ǐ ǰ ǩ ľ ň ǒ ř š ť ǔ ž \strut\\
+% \rowcolor{black!7!white}various & Å Æ Ð (eth) Đ (stroke) IJ\ Ł Ŋ & å æ ð đ ij\ ł ŋ \strut\\
+% \rowcolor{black!7!white} & Ø Œ Ő Ů Ű Ș Ț Þ & ø œ ő ů ű ș ß ț þ \strut\\\bottomrule
+% \end{tabular}
+% \footnotetext{A diaresis mark is one way to indicate an umlaut, a sound change. German originally used a superscript \textsf{e} over \textsf{a}, \textsf{o}, and \textsf{u}. The cursive form of \textsf{e} simplified to a diaresis mark in the 1800s. A diaresis mark also signals a diaresis: reading a diphthong as two monophthongs.}
+% \end{center}
+%
+% Additional Unicode characters can be made available when using fonts with TS1 glyphs (pages 455--463 in \textit{The Latex Companion}). Compare the list: \url{http://tug.ctan.org/info/symbols/comprehensive/} or \texttt{texdoc comprehensive}.
%
-% \begin{itemize}\small
-% \item Keep it simple! Avoid unneeded macros and use the simplified interface.
-% \item Check braces and brackets with naming macros to avoid errors like ``Paragraph ended\dots'' and ``Missing \meta{grouping token} inserted.''
-% \item Do not apply a formatting macro to an entire comma-delimited \meta{SNN, affix} pair. Format each part separately.
-% \item Consider using \cmd{\PretagName} with all names containing control sequences or active Unicode; see Section~\ref{sec:IndexSort}.
-% \item One way to spot errors is to compare index entries with names in the body text. All macros that produce output also emit meaningful warnings.
-% \end{itemize}
-% The older syntax presents its own group of potential errors:
-% \begin{itemize}\small{\IndexInactive
-% \item Erroneously typing |\Name[Henry]{VIII}| prints ``\Name*[Henry]{VIII}'' and ``\Name[Henry]{VIII},'' as well as producing a malformed index entry.
-% \item Avoid forms like |\Name[Henry]{VIII}[Tudor]| which gives ``\Name*[Henry]{VIII}[Tudor]'' and ``\Name[Henry]{VIII}[Tudor].'' That is a Western alternate name form, which is incorrect.}
-% \item The older syntax will not work with some macros. The comma-suffixed form does work with those macros. See Section~\ref{sec:AKA}.
-% \end{itemize}
-% Warnings result from the following:
-% \begin{itemize}\small
-% \item Using the \texttt{nameauth} environment to redefine shorthands or define shorthands that collide with extant macros generates warning because that could result in unwanted behavior like unexpected name forms and index entries. The following will create a warning for such reasons:\\[1ex]
-% |\PretagName[E.\,B.]{White}{White, E. B.}|\dots\\[1ex]
-% |\begin{nameauth}|\\\IndexName[E.\,B.]{White}\ignorespaces
-% | \< White & E.\,B. & White & >|\\
-% | \< White & E. B. & White & >|\\
-% |\end{nameauth}|\\[1ex]
-% Sometimes dedefinition is harmless because it produces no unwanted results. It is up to the user to consider these warnings.
-% \item Use the \texttt{verbose} option for warnings from the indexing macros.
-% \item Using an index cross-reference name as a page entry. Nothing will happen.
-% \item Creating the same cross-reference multiple times. Nothing will happen.
-% \item Creating a page reference after a cross-reference has been created or after you have used \cmd{\ExcludeName}. Nothing happens until you use a variant of \cmd{\Includename}.
-% \item Using \cmd{\TagName} and \cmd{\UntagName} on cross-references. Nothing will happen.
-% \item Using \cmd{\PretagName} with cross-references will create sorting tags for them, but also will generate ``informational warnings'' only if the \texttt{verbose} option is selected.
-% \item Using \cmd{\ExcludeName} with cross-references. Nothing will happen.
-% \item Using \cmd{\ExcludeName} to exclude a name that has already been excluded. Likewise, it will do nothing.
-% \end{itemize}
+% When using a font with TS1 glyphs and slots, the following preamble snippet lets one add more Unicode characters. That enables one to write, ``In Congreſs, July 4, 1776'' as |``In Congreſs, July 4, 1776''|:
+% \begin{quote}\small
+% \StartNum
+% \begin{verbatim}
+%\usepackage[utf8]{inputenc} % For older TL releases
+%\usepackage[TS1,T1]{fontenc}
+%\usepackage{lmodern}% Contains TS1 glyph 115
+%\usepackage{newunicodechar}
+%\DeclareTextSymbolDefault{\textlongs}{TS1}
+%\DeclareTextSymbol{\textlongs}{TS1}{115}
+%\newunicodechar{ſ}{\textlongs}\end{verbatim}
+% \end{quote}
+%
+% Many\Warn{} Unicode characters have native support in \texttt{xelatex} and \texttt{lualatex}, but not in \texttt{pdflatex}. Yet the latter has certain features (e.g., with respect to \textsf{microtype}) that others lack. The features of \texttt{makeindex} do not always equate to those in \texttt{xindy}. Those differences impact design choices.
%
+% Before\Warn{} 2018, some index styles excluded characters with macrons, e.g., \textsf{ā}. Even now, control sequences like \cmd{\=a} in the index create undocumented behavior when using \texttt{makeindex} and \texttt{gind.ist}, which changes the ``actual'' character from~\texttt{@} to~\texttt{=}. Since 2018, names like \ifPDFTeX\IfFileExists{utf8-2018.def}{\Name{Ghazāli}}{\Name{Ghazali}}\else\Name{Ghazāli}\fi\ work properly due to new Unicode conventions. We allow for backward compatibility using the \textsf{iftex} package thus:
+% \begin{quote}\small
+% \StartNum
+% \begin{verbatim}
+%\ifPDFTeX
+% \IfFileExists{utf8-2018.def}%
+% {\Name{Ghazāli}}{\Name{Ghazali}}%
+% \else\Name{Ghazāli}%
+%\fi\end{verbatim}
+% \end{quote}
+%
+% \TeX\Warn{} macros that partition their arguments can break active Unicode characters. Consider the simple macro |\def\foo#1#2#3!{<#1#2><#3>}|. It takes three undelimited arguments and groups the first two, then the third:
+%
+% \begin{center}\MyStretch
+% \def\foo#1#2#3!{<#1#2><#3>}
+% \begin{tabular}{llll}\toprule
+% Argument & Macro & Engine & Result\\\midrule
+% |abc| & |\foo abc!| & (any) & \foo abc!\\
+% |{æ}bc| & |\foo {æ}bc!| & (any) & \foo {æ}bc!\\
+% |\ae bc| & |\foo \ae bc!| & (any) & \foo \ae bc!\\
+% \rowcolor{black!7!white}|æbc| & |\foo æbc!| & \texttt{xelatex} & \ifxetex\foo æbc!\else<æb><c>\fi\\
+% \rowcolor{black!7!white}|æbc| & |\foo æbc!| & \texttt{lualatex} & \ifluatex\foo æbc!\else<æb><c>\fi\\
+% |æbc| & |\foo æbc!| & \texttt{pdflatex} & \unless\ifxetex\unless\ifluatex\foo æbc!\else<æ><bc>\fi\else<æ><bc>\fi\\
+% |æbc| & |\foo æbc!| & \texttt{latex} & \unless\ifxetex\unless\ifluatex\foo æbc!\else<æ><bc>\fi\else<æ><bc>\fi\\\bottomrule
+% \end{tabular}
+% \end{center}
+%
+% The letter \texttt{a} is one argument. Since \texttt{\{æ\}} is in a group, it is one argument. The macro \cmd{\ae} also is one argument. Thus, the first two glyphs are grouped together in |#1#2| and \texttt{c} is left by itself in |#3|. Both \texttt{xelatex} and \texttt{lualatex} likewise treat the Unicode letter \texttt{æ} as one argument.
+%
+% In \texttt{latex} and \texttt{pdflatex}, however, \texttt{æ} is an active Unicode control sequence that uses two arguments: |#1#2|. The tail of the input, \texttt{bc}, is crowded into |#3|. Any macro where this |#1#2| pair is divided into |#1| and |#2| will produce one of two errors: \texttt{Unicode char \dots not set up for LaTeX} or \texttt{Argument of \textbackslash UTFviii at two@octets has an extra \}}.
+%
+% We\Version{3.0} test if \cmd{\Umathchar} is not defined. If so, we check if the leading token of the argument matches the start of an active Unicode control sequence: If \cmd{\@car}\meta{test}\cmd{\@nil} is equal to \cmd{\@car ß}\cmd{\@nil} (page~\pageref{page:CapSystem}) we capitalize |#1#2|, otherwise just |#1|. Should |#1| be a protected macro or something that does not expand to a sequence of letters, we use alternate formatting and \cmd{\AltCaps} (Section~\ref{sec:AltAdvanced}).
+%
+% A\Warn{} macro defined like |\edef\foo{\CapThis\Name{bar}}| will fail. However, |\CapThis\Name{bar}| can be an argument to a macro defined with \cmd{\edef} or \cmd{\xdef}.
+%
+% \LaTeX\Warn{} removes spaces between undelimited macro arguments, except the trailing argument. We use \cmd{\trim at spaces} to address this in \textsf{nameauth}. Explicit spacing macros change the results, but also require sorting with \cmd{\PretagName}. See also Sections~\ref{sec:ErrorProt} and~\ref{sec:NameParticles}, as well as Section~\ref{sec:IndexSort}.
+%
+% \ReturnLink
+% \newpage
+%
+% \subsubsection{\LaTeX\ Engines}
+% \label{sec:TeXengines}
+%
+% The following preamble snippet lets one build \textsf{nameauth} also with older TL versions. We do not load \texttt{iftex.sty} if it does not exist. We load the transitional packages when \textsf{iftex} is absent or older than 2019:\footnote{A copy of this example is in \texttt{examples.tex}, collocated with this manual.}
+% \begin{quote}\small
+% \StartNum
+% \begin{verbatim}
+%\IfFileExists{iftex.sty}{\usepackage{iftex}}{}
+%\unless\ifdefined\RequireTUTeX
+% \usepackage{ifxetex}
+% \usepackage{ifluatex}
+% \usepackage{ifpdf}
+%\fi\end{verbatim}
+% \end{quote}
+%
+% Next we test for the \LaTeX\ engine and include packages accordingly. We could just include \textsf{inputenc} either way, but we are illustrating a point about testing. Some statements below should be modified, depending on one's workflow.
+% \begin{quote}\small
+% \ContinueNum
+% \begin{verbatim}
+%\newif\ifDoTikZ % Perhaps not needed
+%\ifxetex
+% \usepackage{fontspec}
+% \usepackage{polyglossia}
+% \setdefaultlanguage{american} % Use own language
+% \usepackage{tikz}
+% \DoTikZtrue % Perhaps not needed
+%\else
+% \ifluatex
+% \ifpdf
+% \usepackage{fontspec}
+% \usepackage{polyglossia}
+% \setdefaultlanguage{american} % Use own language
+% \usepackage{tikz}
+% \DoTikZtrue % Perhaps not needed
+% \else
+% \IfFileExists{utf8-2018.def}{}
+% {\usepackage[utf8]{inputenc}}
+% \usepackage[TS1,T1]{fontenc}
+% \usepackage[american]{babel} % Use own language
+% \usepackage{lmodern}
+% % Perhaps add \usepackage{tikz}
+% \fi
+% \else
+% \IfFileExists{utf8-2018.def}{}
+% {\usepackage[utf8]{inputenc}}
+% \usepackage[TS1,T1]{fontenc}
+% \usepackage[american]{babel} % Use own language
+% \usepackage{lmodern}
+% \ifpdf % Perhaps not needed
+% \usepackage{tikz}
+% \DoTikZtrue % Perhaps not needed
+% \fi
+% \fi
+%\fi\end{verbatim}
+% \end{quote}
+% \newpage
+%
+% For the sake of comparing \texttt{dvi} viewers \texttt{xdvi}, \texttt{yap}, and others, we load \textsf{tikz} only when making a \texttt{pdf} because some \texttt{dvi} viewers crash otherwise. This may be wholly unnecessary in a \texttt{dvips} workflow or the like. With \textsf{fontspec}, Latin Modern is the default. If we only make \texttt{pdf} documents, the test simplifies to testing for \cmd{\Umathchar}, then loading either \textsf{fontspec} (success) or \textsf{fontenc} (failure).
+%
+%In the body text we can use something like the test below for \fbox{\ifDoTikZ doing \texttt{pdf} things\else doing \texttt{dvi} things\fi}
+% \begin{quote}\small
+% \begin{verbatim}
+%\ifDoTikZ
+% doing \texttt{pdf} things\else
+% doing \texttt{dvi} things\fi\end{verbatim}
+% \end{quote}
+%
+% The following equivalent conditional statements can help a macro or just the body text to work under multiple engines:
+% \begin{quote}\small
+% \StartNum
+% \begin{verbatim}
+%\ifxetex xelatex%
+%\else
+% \ifluatex
+% \ifpdf lualatex (pdf)%
+% \else lualatex (dvi)%
+% \fi
+% \else
+% \ifpdf pdflatex%
+% \else latex (dvi)%
+% \fi
+% \fi
+%\fi\end{verbatim}
+% \end{quote}
+%
+% \begin{quote}\small
+% \StartNum
+% \begin{verbatim}
+%\unless\ifxetex
+% \unless\ifluatex
+% \ifpdf pdflatex%
+% \else latex (dvi)%
+% \fi
+% \else
+% \ifpdf lualatex (pdf)%
+% \else lualatex (dvi)%
+% \fi
+% \fi
+%\else xelatex%
+%\fi\end{verbatim}
+% \end{quote}
+%
+% \ReturnLink
+% \BigBlank
+% \newpage
+%
% \StopEventually{^^A
-% \clearpage
-% \newgeometry{textwidth=147mm,textheight=237mm,right=25mm}
-% \PrintChanges\clearpage\PrintIndex
+% \let\emph\oldemph
+% \newgeometry{textwidth=160mm,textheight=237mm,right=25mm}
+% \IndexProtect\PrintChanges\newpage\PrintIndex
% }
%
% \section{Implementation}
@@ -3549,50 +4936,55 @@
% \small
% \subsection{Flags and Registers}
%
-% The flags below are grouped according to general function. We begin with flow control\medskip
+% The flags below are grouped according to function. We begin with flow control\medskip
%
-% \noindent{\large\bfseries Who Called Me?}\\[0.5ex]
-% These values are used by the format hook dispatcher \cmd{\@nameauth at Hook} and the hook macros to determine if they have been called by either \cmd{\@nameauth at Name}, \cmd{\AKA}, or \cmd{\IndexRef}, respectively. Those macros set these flags. On their use, see also Sections~\ref{sec:Hooksb} and ~\ref{sec:Hooksc}.
+% \noindent{\large\bfseries Who Called Me?}\medskip\\
+% Various macros use these flags to protect against stack overflows or choose the right output.
% \begin{macrocode}
\newif\if at nameauth@InAKA
\newif\if at nameauth@InName
\newif\if at nameauth@Xref
-% \end{macrocode}
-% As an aside, \cmd{\AKA} will invoke \cmd{\NamesFormat} or \cmd{\FrontNamesFormat} if the \texttt{alwaysformat} option is set. Otherwise it will invoke \cmd{\MainNameHook} or \cmd{\FrontNameHook}.\medskip
+% \end{macrocode}\smallskip
%
-% \noindent{\large\bfseries Core Macro Lock}\\[0.5ex]
-% The macros \cmd{\@nameauth at Name} and \cmd{\AKA}, with some auxiliary macros, process names in a ``locked'' state. These flags prevent a stack overflow. See also Sections~\ref{sec:Hooksb} and ~\ref{sec:Hooksc}.
+% \noindent{\large\bfseries Core Macro Locks}\medskip\\
+% The macros \cmd{\@nameauth at Name} and \cmd{\AKA}, with some auxiliary macros, process names in a ``locked'' state to avoid a stack overflow. The \texttt{BigLock} always locks the macros, preventing execution. See also Sections~\ref{sec:Hooksii} and~\ref{sec:Hooksiii}.
% \begin{macrocode}
\newif\if at nameauth@Lock
+\newif\if at nameauth@BigLock
\newif\if at nameauth@InHook
% \end{macrocode}\smallskip
%
-% \noindent{\large\bfseries Indexing}\\[0.5ex]
-% As the naming macros have locks, so do the indexing macros. These locks permit or prevent both indexing and tags. \cmd{\IndexActive} and \cmd{\IndexInctive} or the \texttt{index} and \texttt{noindex} options toggle the first flag; \cmd{\SkipIndex} toggles the second. \cmd{\JustIndex} toggles the third, which makes the core naming engine act like a call to \cmd{\IndexName}:
+% \noindent{\large\bfseries Indexing}\medskip\\
+% The indexing flags permit or prevent indexing and tags. \cmd{\IndexActive} and \cmd{\IndexInctive} or the \texttt{index} and \texttt{noindex} options toggle the first flag; \cmd{\SkipIndex} toggles the second. \cmd{\JustIndex} toggles the third, which makes the core naming engine act like a call to \cmd{\IndexName}:
% \begin{macrocode}
\newif\if at nameauth@DoIndex
\newif\if at nameauth@SkipIndex
\newif\if at nameauth@JustIndex
% \end{macrocode}
-% The \texttt{pretag} and \texttt{nopretag} options toggle the value below, which allows or prevents the insertion of sort keys.
+% The \texttt{pretag} and \texttt{nopretag} options toggle the flag below, which allows or prevents the insertion of index sort keys.
% \begin{macrocode}
\newif\if at nameauth@Pretag
% \end{macrocode}
-% Theis flag determines whether \cmd{\IndexRef} creates a \emph{see} reference or a \emph{see also} reference.
+% This flag determines whether \cmd{\IndexRef} creates a \textit{see} reference or a \textit{see also} reference.
% \begin{macrocode}
\newif\if at nameauth@SeeAlso
% \end{macrocode}\smallskip
%
-% \noindent{\large\bfseries Formatting}\\[0.5ex]
-% \cmd{\NamesActive} and \cmd{\NamesInactive}, with the \texttt{mainmatter} and \texttt{frontmatter}, options toggle formatting hooks via \texttt{\textbackslash if at nameauth@MainFormat}. \texttt{\textbackslash if at nameauth@AKAFormat} permits \cmd{\AKA} to call the first-use hooks once.
+% \noindent{\large\bfseries Formatting}\medskip\\
+% \cmd{\NamesActive} and \cmd{\NamesInactive}, with the \texttt{mainmatter} and \texttt{frontmatter} options, toggle formatting hooks via \texttt{\textbackslash if at nameauth@MainFormat}. \texttt{\textbackslash if at nameauth@AKAFormat} permits \cmd{\AKA} to call the first-use hooks once.
% \begin{macrocode}
\newif\if at nameauth@MainFormat
\newif\if at nameauth@AKAFormat
-% \end{macrocode}
+% \end{macrocode}\medskip
% The next flag works with \cmd{\LocalNames} and \cmd{\GlobalNames}.
% \begin{macrocode}
\newif\if at nameauth@LocalNames
% \end{macrocode}\medskip
+% These two flags are used only for backward compatibility. The first broadly determines how per-name flags are reset, while the second affects the behavior of \cmd{\JustIndex}.
+% \begin{macrocode}
+\newif\if at nameauth@OldReset
+\newif\if at nameauth@OldPass
+% \end{macrocode}\medskip
% These two flags trigger \cmd{\ForgetName} and \cmd{\SubvertName} within \cmd{\@nameauth at Name}.
% \begin{macrocode}
\newif\if at nameauth@Forget
@@ -3602,12 +4994,12 @@
% \begin{macrocode}
\newif\if at nameauth@FirstFormat
\newif\if at nameauth@AlwaysFormat
-% \end{macrocode}\clearpage
+% \end{macrocode}\medskip
%
% \noindent Next we move from general flow control to specific modification of name forms.\medskip
%
-% \noindent{\large\bfseries Affix Commas}\\[0.5ex]
-% The \texttt{comma} and \texttt{nocomma} options toggle the flag value below. \cmd{\ShowComma} and \cmd{\NoComma} respectively toggle the second and third.
+% \noindent{\large\bfseries Affix Commas}\medskip\\
+% The \texttt{comma} and \texttt{nocomma} options toggle the first flag value below. \cmd{\ShowComma} and \cmd{\NoComma} respectively toggle the second and third.
% \begin{macrocode}
\newif\if at nameauth@AlwaysComma
\newif\if at nameauth@ShowComma
@@ -3614,7 +5006,7 @@
\newif\if at nameauth@NoComma
% \end{macrocode}\medskip
%
-% \noindent{\large\bfseries Name Breaking}\\[0.5ex]
+% \noindent{\large\bfseries Name Breaking}\medskip\\
% \cmd{\KeepAffix} toggles the first flag below, while \cmd{\KeepName} toggles the second. Both affect the use of non-breaking spaces in the text.
% \begin{macrocode}
\newif\if at nameauth@NBSP
@@ -3621,14 +5013,14 @@
\newif\if at nameauth@NBSPX
% \end{macrocode}\medskip
%
-% \noindent{\large\bfseries Detect Punctuation}\\[0.5ex]
+% \noindent{\large\bfseries Detect Punctuation}\medskip\\
% This Boolean value is used to prevent double full stops at the end of a name in the text.
% \begin{macrocode}
\newif\if at nameauth@Punct
% \end{macrocode}\medskip
%
-% \noindent{\large\bfseries Long and Short Names}\\[0.5ex]
-% \texttt{\textbackslash if at nameauth@FullName} is true for a long name reference. \texttt{\textbackslash if at nameauth@FirstName} disables full-name references and causes only Western forenames to be displayed.
+% \noindent{\large\bfseries Long and Short Names}\medskip\\
+% \texttt{\textbackslash if at nameauth@FullName} is true for a long name reference. \texttt{\textbackslash if at nameauth@FirstName} disables full-name references and causes only Western forenames to be displayed. The default is to reset both globally on a per-name basis.
%
% \texttt{\textbackslash if at nameauth@AltAKA} is toggled respectively by \cmd{\AKA} and \cmd{\AKA*} to print a longer or shorter name. \texttt{\textbackslash if at nameauth@OldAKA} forces the pre-3.0 behavior of \cmd{\AKA*}.
%
@@ -3642,7 +5034,7 @@
\newif\if at nameauth@EastFN
% \end{macrocode}\medskip
%
-% \noindent{\large\bfseries Eastern Names}\\[0.5ex]
+% \noindent{\large\bfseries Eastern Names}\medskip\\
% The next flags values govern name reversing and full surname capitalization. The first of each pair is a global state. The second of each pair is an individual state.
% \begin{macrocode}
\newif\if at nameauth@RevAll
@@ -3651,7 +5043,7 @@
\newif\if at nameauth@AllThis
% \end{macrocode}\medskip
%
-% \noindent{\large\bfseries Last-Comma-First}\\[0.5ex]
+% \noindent{\large\bfseries Last-Comma-First}\medskip\\
% This pair of flags deals with Western names reordered in a list according to surname.
% \begin{macrocode}
\newif\if at nameauth@RevAllComma
@@ -3658,8 +5050,8 @@
\newif\if at nameauth@RevThisComma
% \end{macrocode}\medskip
%
-% \noindent{\large\bfseries Capitalize First Letter}\\[0.5ex]
-% The next flags deal with first-letter capitalization. The first Boolean value is triggered by \cmd{\CapThis} and reset by \cmd{\Name} and \cmd{\AKA}. The second is triggered by \cmd{\@nameauth at UTFtest} when it encounters a Unicode character under NFSS. The third is an ``override switch'' triggered by \cmd{\AccentCapThis} as a fall-back. The fourth prevents the first-letter capping mechanism from interacting with Continental formatting and the fifth toggles it.
+% \noindent{\large\bfseries Cap First Letter and Format}\medskip\\
+% The next flags deal with first-letter capitalization. \cmd{\CapThis} sets the first Boolean value. The second is triggered by \cmd{\@nameauth at UTFtest} when it encounters an active Unicode character. The third is a fallback triggered by \cmd{\AccentCapThis}. The fourth disables \cmd{\CapThis} for alternate formatting. The fifth toggles alternate formatting.
% \begin{macrocode}
\newif\if at nameauth@DoCaps
\newif\if at nameauth@UTF
@@ -3668,19 +5060,25 @@
\newif\if at nameauth@DoAlt
% \end{macrocode}\medskip
%
-% \noindent{\large\bfseries Warning Levels}\\[0.5ex]
+% \noindent{\large\bfseries Warning Levels}\medskip\\
% This flag controls how many warnings you get. Defaults to few warnings. Verbose gives you plenty of warnings about cross-references in the index.
% \begin{macrocode}
\newif\if at nameauth@Verbose
% \end{macrocode}\medskip
%
-% \noindent{\large\bfseries Name Argument Token Registers}\\[0.5ex]
-% These three token registers contain the current values of the name arguments passed to \cmd{\Name}, its variants, and the cross-reference fields of \cmd{\AKA}.
+% \noindent{\large\bfseries Name Argument Token Registers}\vspace{-1.5ex}
+% \begin{macro}{\@nameauth at toksa}
+% \begin{macro}{\@nameauth at toksb}
+% \begin{macro}{\@nameauth at toksc}
+% These three token registers contain the current values of the name arguments passed to \cmd{\Name}, its variants, and the cross-reference arguments of \cmd{\AKA}. Users can access them especially in formatting hooks.
% \begin{macrocode}
\newtoks\@nameauth at toksa%
\newtoks\@nameauth at toksb%
\newtoks\@nameauth at toksc%
% \end{macrocode}
+% \end{macro}
+% \end{macro}
+% \end{macro}
% These three token registers contain the current values of the name arguments in each line of the \texttt{nameauth} environment.
% \begin{macrocode}
\newtoks\@nameauth at etoksb%
@@ -3690,7 +5088,7 @@
%
% \subsection{Hooks}
% \begin{macro}{\NamesFormat}
-% Post-process ``first'' instance of final complete name form in text. See Sections~\ref{sec:formatting} and~\ref{sec:Hooksa}f. Called when both |\@nameauth at MainFormat| and |\@nameauth at FirstFormat| are true.
+% Post-process ``first'' instance of final complete name form in text. See Sections~\ref{sec:Formatting} and~\ref{sec:Hooksi}f. Called when both |\@nameauth at MainFormat| and |\@nameauth at FirstFormat| are true.
% \begin{macrocode}
\newcommand*\NamesFormat{}
% \end{macrocode}
@@ -3697,7 +5095,7 @@
% \end{macro}
% \begin{macro}{\MainNameHook}
% \changes{2.4}{2016/03/15}{Added}
-% Post-process subsequent instance of final complete name form in main-matter text. See Sections~\ref{sec:formatting} and~\ref{sec:Hooksa}f. Called when |\@nameauth at MainFormat| is true and the Boolean flag |\@nameauth at FirstFormat| is false.
+% Post-process subsequent instance of final complete name form in main-matter text. See Sections~\ref{sec:Formatting} and~\ref{sec:Hooksi}f. Called when |\@nameauth at MainFormat| is true and the Boolean flag |\@nameauth at FirstFormat| is false.
% \begin{macrocode}
\newcommand*\MainNameHook{}
% \end{macrocode}
@@ -3718,7 +5116,7 @@
% \end{macro}
% \begin{macro}{\NameauthName}
% \changes{2.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:NewEngine}. Use at your own risk! Changing these macros basically rewrites this package.
+% The last three hooks usually point to \cmd{\@nameauth at Name}. See Section~\ref{sec:Customize}.
% \begin{macrocode}
\newcommand*\NameauthName{\@nameauth at Name}
% \end{macrocode}
@@ -3725,7 +5123,7 @@
% \end{macro}
% \begin{macro}{\NameauthLName}
% \changes{2.3}{2016/01/05}{Added}
-% Customization hook called after \cmd{\@nameauth at FullName} is set true. See Section~\ref{sec:NewEngine}.
+% Customization hook called after \cmd{\@nameauth at FullName} is set true. See Section~\ref{sec:Customize}.
% \begin{macrocode}
\newcommand*\NameauthLName{\@nameauth at Name}
% \end{macrocode}
@@ -3732,7 +5130,7 @@
% \end{macro}
% \begin{macro}{\NameauthFName}
% \changes{2.2}{2015/12/01}{Added}
-% Customization hook called after \cmd{\@nameauth at FirstName} is set true. See Section~\ref{sec:NewEngine}.
+% Customization hook called after \cmd{\@nameauth at FirstName} is set true. See Section~\ref{sec:Customize}.
% \begin{macrocode}
\newcommand*\NameauthFName{\@nameauth at Name}
% \end{macrocode}
@@ -3747,6 +5145,8 @@
\DeclareOption{frontmatter}{\@nameauth at MainFormatfalse}
\DeclareOption{formatAKA}{\@nameauth at AKAFormattrue}
\DeclareOption{oldAKA}{\@nameauth at OldAKAtrue}
+\DeclareOption{oldreset}{\@nameauth at OldResettrue}
+\DeclareOption{oldpass}{\@nameauth at OldPasstrue}
\DeclareOption{index}{\@nameauth at DoIndextrue}
\DeclareOption{noindex}{\@nameauth at DoIndexfalse}
\DeclareOption{pretag}{\@nameauth at Pretagtrue}
@@ -3773,7 +5173,7 @@
\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.
+% Now we load the required packages. They facilitate the first\,/\,subsequent name uses, the parsing of arguments, and the implementation of starred forms.
% \begin{macrocode}
\RequirePackage{etoolbox}
\RequirePackage{suffix}
@@ -3782,9 +5182,11 @@
% \end{macrocode}
%
% The \textsf{etoolbox} package is essential for processing name control sequences. Using \textsf{xargs} allows the optional arguments to work. Using \textsf{suffix} facilitated the starred form of macros. Finally, \textsf{trimspaces} helps the fault tolerance of name arguments.
+% \BigBlank
+% \newpage
%
% \subsection{Internal Macros}
-% \label{sec:internal}
+% \label{sec:InternalMacros}
%
% \noindent{\large\bfseries Name Control Sequence: Who Am I?}
% \begin{macro}{\@nameauth at Clean}
@@ -3794,11 +5196,9 @@
{\expandafter\zap at space\detokenize{#1} \@empty}
% \end{macrocode}
% \end{macro}\medskip
-% \clearpage
%
% \noindent{\large\bfseries Parsing: Root and Suffix}
% \begin{macro}{\@nameauth at Root}
-% \changes{1.4}{2012/07/24}{More robust}
% The following two macros return everything before a comma in \meta{SNN}.
% \begin{macrocode}
\newcommand*\@nameauth at Root[1]{\@nameauth@@Root#1,\\}
@@ -3806,7 +5206,6 @@
% \end{macro}
%
% \begin{macro}{\@nameauth@@Root}
-% \changes{0.9}{2012/02/10}{Expands}
% \changes{2.0}{2015/11/11}{Trim spaces}
% \changes{3.0}{2016/10/26}{Redesigned}
% \changes{3.2}{2017/03/22}{Renamed}
@@ -3871,9 +5270,10 @@
%
% \noindent{\large\bfseries Parsing: Capitalization}
% \begin{macro}{\@nameauth at TestToks}
-% \phantomsection\label{page:CapSystem}
+% \phantomsection
+% \label{page:CapSystem}
% \changes{3.2}{2017/03/22}{Added}
-% Test if the leading token is the same as the leading token of an active Unicode character, using an \emph{Esszett} (\texttt{ß}) as the control. We only run this macro if we are in the \textsf{inputenc} regime.
+% Test if the leading token is the same as the leading token of an active Unicode character, using an \textit{Esszett} (\texttt{ß}) as the control. We only run this macro if we are in the \textsf{inputenc} regime.
% \begin{macrocode}
\newcommand*\@nameauth at TestToks[1]
{%
@@ -3887,11 +5287,10 @@
% \end{macro}
%
% \begin{macro}{\@nameauth at UTFtest}
-% \phantomsection\label{page:CapSystem}
% \changes{3.0}{2016/10/26}{Added}
% \changes{3.1}{2017/01/13}{Override bypasses test}
% \changes{3.2}{2017/03/22}{Non-suffix only}
-% Before we attempt at capitalizing anything, we need to determine if we are running under \texttt{xelatex} or \texttt{lualatex} by testing for \cmd{\Umathchar}. Then we see if \textsf{inputenc} is loaded. We set up the comparison and pass off to \cmd{@nameauth at TestToks}.
+% Before we attempt at capitalizing anything, we need to determine if we are running under \texttt{xelatex} or \texttt{lualatex} by testing for \cmd{\Umathchar}. Then we see if \textsf{inputenc} is loaded. We set up the comparison and pass off to \cmd{\@nameauth at TestToks}.
% \begin{macrocode}
\newcommand*\@nameauth at UTFtest[1]
{%
@@ -3941,7 +5340,7 @@
% \end{macro}
%
% \begin{macro}{\@nameauth at Cap}
-% \changes{3.1}{2017/01/13}{Added; old caps gone}
+% \changes{3.1}{2017/01/13}{Redesigned}
% \changes{3.2}{2017/03/22}{Non-UTF}
% The following two macros cap the first letter of the argument.
% \begin{macrocode}
@@ -3951,7 +5350,7 @@
%
% \begin{macro}{\@nameauth at C@p}
% \changes{3.1}{2017/01/13}{Added}
-% \changes{3.2}{2017/03/22}{Renamed}
+% \changes{3.2}{2017/03/22}{Renamed, use \cmd{\MakeUppercase}}
% Helper macro for the one above.
% \begin{macrocode}
\def\@nameauth at C@p#1#2\\%
@@ -3969,6 +5368,7 @@
%
% \begin{macro}{\@nameauth at C@pUTF}
% \changes{3.1}{2017/01/13}{Added}
+% \changes{3.2}{2017/03/22}{Use \cmd{\MakeUppercase}}
% Helper macro for the one above.
% \begin{macrocode}
\def\@nameauth at C@pUTF#1#2#3\\%
@@ -3975,7 +5375,6 @@
{\expandafter\trim at spaces\expandafter{\MakeUppercase{#1#2}#3}}
% \end{macrocode}
% \end{macro}
-% \clearpage
%
% \noindent{\large\bfseries Parsing: Punctuation Detection}
% \begin{macro}{\@nameauth at TestDot}
@@ -4019,12 +5418,12 @@
% \begin{macro}{\@nameauth at Error}
% \changes{3.0}{2016/10/26}{Added}
% \changes{3.01}{2016/10/27}{Fixed}
-% One can cause \textsf{nameauth} to halt with an error by leaving a required name argument empty, providing an argument that expands to empty, or creating an empty root within a root/suffix pair.
+% One can cause \textsf{nameauth} to halt with an error by leaving a required name argument empty, providing an argument that expands to empty, or creating an empty root within a root\,/\,suffix pair.
% \begin{macrocode}
\newcommand*\@nameauth at Error[2]
{%
- \edef\msga{#2 SNN field empty}%
- \edef\msgb{#2 SNN field malformed}%
+ \edef\msga{#2 SNN arg empty}%
+ \edef\msgb{#2 SNN arg malformed}%
\protected at edef\testname{\trim at spaces{#1}}%
\protected at edef\testroot{\@nameauth at Root{#1}}%
\ifx\testname\@empty
@@ -4036,46 +5435,59 @@
}
% \end{macrocode}
% \end{macro}
+% \newpage
%
% \noindent{\large\bfseries Core Name Engine}
%
% \begin{macro}{\@nameauth at Name}
% \changes{0.85}{2012/02/05}{Hide commas}
-% \changes{1.5}{2013/02/22}{Reversing/caps}
-% \changes{2.0}{2015/11/11}{Trim spaces; redesign tagging}
+% \changes{1.5}{2013/02/22}{Reversing\,/\,caps}
+% \changes{2.0}{2015/11/11}{Trim spaces; fix tags}
% \changes{2.1}{2015/11/24}{Fix Unicode}
-% \changes{2.3}{2016/01/05}{Now internal}
+% \changes{2.3}{2016/01/05}{Internal}
% \changes{2.4}{2016/03/15}{Set token regs}
% \changes{2.41}{2016/03/17}{Fix token regs}
-% \changes{2.5}{2016/04/06}{Current parsing approach}
+% \changes{2.5}{2016/04/06}{Fix old syntax}
% \changes{2.6}{2016/09/19}{Better indexing}
% \changes{3.0}{2016/10/26}{Redesigned}
-% \changes{3.1}{2017/01/13}{Enhanced workflow control}
+% \changes{3.1}{2017/01/13}{New workflow}
+% \changes{3.3}{2020/02/20}{global flag reset}
% Here is the heart of the package. \Name*[Marc van]{Dongen} provided the original basic structure. Parsing, indexing, and formatting are more discrete than in earlier versions.
% \begin{macrocode}
\newcommandx*\@nameauth at Name[3][1=\@empty, 3=\@empty]
{%
% \end{macrocode}
-% Both \cmd{\@nameauth at Name} and \cmd{\AKA} engage the lock below, preventing a stack overflow.
+% Both \cmd{\@nameauth at Name} and \cmd{\AKA} engage the lock below, preventing a stack overflow. Tell the formatting mechanism that it is being called from \cmd{\@nameauth at Name}.
% \begin{macrocode}
+ \if at nameauth@BigLock\@nameauth at Locktrue\fi
\unless\if at nameauth@Lock
\@nameauth at Locktrue%
+ \@nameauth at InNametrue%
% \end{macrocode}
-% Tell the formatting mechanism that it is being called from \cmd{\@nameauth at Name}. Then test for malformed input.
+% Test for malformed input.
% \begin{macrocode}
- \@nameauth at InNametrue%
\@nameauth at Error{#2}{macro \string\@nameauth at name}%
% \end{macrocode}
-% If we use \cmd{\JustIndex} then skip everything else..
+% If we use \cmd{\JustIndex} then skip everything else. The \texttt{oldpass} option restores what we did before version 3.3, where we locally reset \cmd{\@nameauth at JustIndexfalse} and were done. Now, however, the default is a global reset to avoid undocumented behavior.
% \begin{macrocode}
\if at nameauth@JustIndex
\IndexName[#1]{#2}[#3]%
- \@nameauth at InNamefalse%
- \@nameauth at Lockfalse%
- \@nameauth at JustIndexfalse%
+ \if at nameauth@OldPass
+ \@nameauth at JustIndexfalse%
+ \else
+ \if at nameauth@OldReset
+ \@nameauth at FullNamefalse%
+ \@nameauth at FirstNamefalse%
+ \@nameauth at JustIndexfalse%
+ \else
+ \global\@nameauth at FullNamefalse%
+ \global\@nameauth at FirstNamefalse%
+ \global\@nameauth at JustIndexfalse%
+ \fi
+ \fi
\else
% \end{macrocode}
-% Delete/create name cseq if directed. If the delete flag is set, the create flag is ignored. Ensure that names are printed in horizontal mode. Print the name between two index entries, if allowed.
+% Delete\,/\,create name cseq if directed. If the delete flag is set, the create flag is ignored. Ensure that names are printed in horizontal mode. Wrap the name with two index entries in case a page break occurs between name elements.
% \begin{macrocode}
\if at nameauth@Forget
\ForgetName[#1]{#2}[#3]%
@@ -4093,25 +5505,42 @@
\fi
\unless\if at nameauth@SkipIndex\IndexName[#1]{#2}[#3]\fi
% \end{macrocode}
-% Reset all the ``per name'' Boolean values.
+% Reset all the ``per name'' Boolean values. The default is global.
% \begin{macrocode}
- \@nameauth at SkipIndexfalse%
- \@nameauth at Forgetfalse%
- \@nameauth at Subvertfalse%
- \@nameauth at Lockfalse%
- \@nameauth at InNamefalse%
- \@nameauth at NBSPfalse%
- \@nameauth at NBSPXfalse%
- \@nameauth at DoCapsfalse%
- \@nameauth at Accentfalse%
- \@nameauth at AllThisfalse%
- \@nameauth at ShowCommafalse%
- \@nameauth at NoCommafalse%
- \@nameauth at RevThisfalse%
- \@nameauth at RevThisCommafalse%
- \@nameauth at ShortSNNfalse%
- \@nameauth at EastFNfalse%
+ \if at nameauth@OldReset
+ \@nameauth at SkipIndexfalse%
+ \@nameauth at Forgetfalse%
+ \@nameauth at Subvertfalse%
+ \@nameauth at NBSPfalse%
+ \@nameauth at NBSPXfalse%
+ \@nameauth at DoCapsfalse%
+ \@nameauth at Accentfalse%
+ \@nameauth at AllThisfalse%
+ \@nameauth at ShowCommafalse%
+ \@nameauth at NoCommafalse%
+ \@nameauth at RevThisfalse%
+ \@nameauth at RevThisCommafalse%
+ \@nameauth at ShortSNNfalse%
+ \@nameauth at EastFNfalse%
+ \else
+ \global\@nameauth at SkipIndexfalse%
+ \global\@nameauth at Forgetfalse%
+ \global\@nameauth at Subvertfalse%
+ \global\@nameauth at NBSPfalse%
+ \global\@nameauth at NBSPXfalse%
+ \global\@nameauth at DoCapsfalse%
+ \global\@nameauth at Accentfalse%
+ \global\@nameauth at AllThisfalse%
+ \global\@nameauth at ShowCommafalse%
+ \global\@nameauth at NoCommafalse%
+ \global\@nameauth at RevThisfalse%
+ \global\@nameauth at RevThisCommafalse%
+ \global\@nameauth at ShortSNNfalse%
+ \global\@nameauth at EastFNfalse%
+ \fi
\fi
+ \@nameauth at Lockfalse%
+ \@nameauth at InNamefalse%
% \end{macrocode}
% Close the ``locked'' branch.
% \begin{macrocode}
@@ -4126,12 +5555,13 @@
%
% \begin{macro}{\@nameauth at Parse}
% \changes{3.0}{2016/10/26}{Added}
-% \changes{3.1}{2017/01/13}{Enhanced, integrated caps}
-% \changes{3.2}{2017/03/22}{Fix alt. format and Western affixes}
-% Parse and print a name in the text. The final required argument is a ``mode designator'' that can be ``!MN'' (main name); ``!NF'' (was ``non-formatted,'' now ``name in front matter''); and ``!PN'' (pseudonym/cross-reference). Both \cmd{\@nameauth at Name} and \cmd{\AKA} call this parser.
+% \changes{3.1}{2017/01/13}{New workflow, caps}
+% \changes{3.2}{2017/03/22}{Fix alt. format, affixes, use \cmd{\MakeUppercase}}
+% Parse and print a name in the text. The final required argument tells us which naming system we are in (Section~\ref{sec:NamePatterns}). Both \cmd{\@nameauth at Name} and \cmd{\AKA} call this parser.
% \begin{macrocode}
\newcommandx*\@nameauth at Parse[4][1=\@empty, 3=\@empty]
{%
+ \if at nameauth@BigLock\@nameauth at Lockfalse\fi
\if at nameauth@Lock
\let\ex\expandafter%
% \end{macrocode}
@@ -4142,7 +5572,8 @@
\protected at edef\suffb{\@nameauth at Suffix{#2}}%
\protected at edef\argc{\trim at spaces{#3}}%
% \end{macrocode}
-% If global caps. reversing, and commas are true, set the local flags true.
+% \newpage
+% \noindent If global caps. reversing, and commas are true, set the local flags true.
% \begin{macrocode}
\if at nameauth@AllCaps\@nameauth at AllThistrue\fi
\if at nameauth@RevAll\@nameauth at RevThistrue\fi
@@ -4251,13 +5682,13 @@
\fi
\fi
% \end{macrocode}
-% We parses names by attaching ``meaning'' to patterns of macro arguments primarily via \cmd{\FNN} and \cmd{\SNN}. Then we call the name printing macros, based on the optional arguments.
+% We parse names by attaching ``meaning'' to patterns of macro arguments primarily via \cmd{\FNN} and \cmd{\SNN}. Then we call the name printing macros, based on the optional arguments.
% \begin{macrocode}
\let\SNN\rootb%
\ifx\arga\@empty
\ifx\argc\@empty
% \end{macrocode}
-% When \cmd{\arga}, \cmd{\argc}, and \cmd{\suffb} are empty, we have a mononym. When \cmd{\suffb} is not empty, we have a native Eastern name or non-Western name.
+% When \cmd{\arga}, \cmd{\argc}, and \cmd{\suffb} are empty, we have a mononym. When \cmd{\suffb} is not empty, we have a ``native'' Eastern name or non-Western name.
% \begin{macrocode}
\let\FNN\suffb%
\let\SNN\rootb%
@@ -4278,7 +5709,7 @@
\fi
\else
% \end{macrocode}
-% When \cmd{\arga} is not empty, we have either a Western name or a non-native Eastern name. When \cmd{\argc} is not empty, we use alternate names. When \cmd{\suffb} is not empty we use suffixed forms.
+% When \cmd{\arga} is not empty, we have either a Western name or a ``non-native'' Eastern name. When \cmd{\argc} is not empty, we use alternate names. When \cmd{\suffb} is not empty we use suffixed forms.
% \begin{macrocode}
\ifx\argc\@empty
\let\FNN\arga%
@@ -4299,10 +5730,12 @@
% \begin{macro}{\@nameauth at NonWest}
% \changes{3.0}{2016/10/26}{Added}
% \changes{3.02}{2016/11/01}{Restrict \cmd{\ForceFN}}
-% Print non-Western names from \cmd{\@nameauth at name} and \cmd{\AKA}. We inherit internal control sequences from the naming macros and do nothing if called outside them.
+% \changes{3.3}{2020/02/20}{global flag reset}
+% Print non-Western names from \cmd{\@nameauth at name} and \cmd{\AKA}. We inherit internal macros from the parser and do nothing apart from the locked state.
% \begin{macrocode}
\newcommand*\@nameauth at NonWest[1]
{%
+ \if at nameauth@BigLock\@nameauth at Lockfalse\fi
\if at nameauth@Lock
\unless\ifcsname#1\endcsname
\@nameauth at FirstFormattrue%
@@ -4349,8 +5782,16 @@
\unless\ifcsname#1\endcsname
\unless\if at nameauth@InAKA\csgdef{#1}{}\fi
\fi
- \@nameauth at FullNamefalse%
- \@nameauth at FirstNamefalse%
+% \end{macrocode}
+% We have to reset these flags here because both the naming and cross-referencing macros use the parser.
+% \begin{macrocode}
+ \if at nameauth@OldReset
+ \@nameauth at FullNamefalse%
+ \@nameauth at FirstNamefalse%
+ \else
+ \global\@nameauth at FullNamefalse%
+ \global\@nameauth at FirstNamefalse%
+ \fi
\fi
}
% \end{macrocode}
@@ -4358,10 +5799,12 @@
%
% \begin{macro}{\@nameauth at West}
% \changes{3.0}{2016/10/26}{Added}
-% Print Western names and ``non-native'' Eastern names from \cmd{\@nameauth at name} and \cmd{\AKA}. We inherit internal control sequences from the naming macros and do nothing if called outside them.
+% \changes{3.3}{2020/02/20}{global flag reset}
+% Print Western names and ``non-native'' Eastern names from \cmd{\@nameauth at name} and \cmd{\AKA}. We inherit internal macros from the parser and do nothing apart from the locked state.
% \begin{macrocode}
\newcommand*\@nameauth at West[1]
{%
+ \if at nameauth@BigLock\@nameauth at Lockfalse\fi
\if at nameauth@Lock
\unless\ifcsname#1\endcsname
\@nameauth at FirstFormattrue%
@@ -4404,8 +5847,16 @@
\unless\ifcsname#1\endcsname
\unless\if at nameauth@InAKA\csgdef{#1}{}\fi
\fi
- \@nameauth at FullNamefalse%
- \@nameauth at FirstNamefalse%
+% \end{macrocode}
+% We have to reset these flags here because both the naming and cross-referencing macros use the parser.
+% \begin{macrocode}
+ \if at nameauth@OldReset
+ \@nameauth at FullNamefalse%
+ \@nameauth at FirstNamefalse%
+ \else
+ \global\@nameauth at FullNamefalse%
+ \global\@nameauth at FirstNamefalse%
+ \fi
\fi
}
% \end{macrocode}
@@ -4416,10 +5867,11 @@
% \changes{2.4}{2016/03/15}{Current form}
% \changes{2.5}{2016/04/06}{Improve hooks}
% \changes{3.0}{2016/10/26}{Fix punct. detection}
-% Flags help the dispatcher invoke the correct formatting hooks. The flags control which hook is called (first/subsequent use, name type). The first set of tests handles formatting within \cmd{\AKA}. The second set of tests handles regular name formatting.
+% Flags help the dispatcher invoke the correct formatting hooks. The flags control which hook is called (first\,/\,subsequent use, name type). The first set of tests handles formatting within \cmd{\AKA}. The second set of tests handles regular name formatting.
% \begin{macrocode}
\newcommand*\@nameauth at Hook[1]
{%
+ \if at nameauth@BigLock\@nameauth at Lockfalse\fi
\if at nameauth@Lock
\@nameauth at InHooktrue%
\protected at edef\test{#1}%
@@ -4462,7 +5914,14 @@
\fi
\fi
\fi
- \@nameauth at FirstFormatfalse%
+% \end{macrocode}
+% We have to reset this flag here because both the naming and cross-referencing macros use the parser.
+% \begin{macrocode}
+ \if at nameauth@OldReset
+ \@nameauth at FirstFormatfalse%
+ \else
+ \global\@nameauth at FirstFormatfalse%
+ \fi
\@nameauth at InHookfalse%
\fi
}
@@ -4473,40 +5932,39 @@
% \begin{macro}{\@nameauth at Index}
% \changes{0.94}{2012/02/15}{Added}
% \changes{2.0}{2015/11/11}{New tagging}
+% \changes{3.3}{2020/02/20}{Tags support hyperref}
% If the indexing flag is true, create an index entry, otherwise do nothing. Add tags automatically if they exist.
% \begin{macrocode}
\newcommand*\@nameauth at Index[2]
{%
- \def\cseq{#1}%
\let\ex\expandafter%
- \ifcsname\cseq!TAG\endcsname
- \protected at edef\Tag{\csname#1!TAG\endcsname}%
- \ex\def\ex\ShortTag\ex{\ex\@nameauth at TrimTag\ex{\Tag}}%
- \fi
\if at nameauth@DoIndex
- \ifcsname\cseq!TAG\endcsname
- \ifcsname\cseq!PRE\endcsname
- \if at nameauth@Xref%
- \index%
- {\csname\cseq!PRE\endcsname#2\ShortTag}%
+ \ifcsname#1!TAG\endcsname
+ \protected at edef\Tag{\csname#1!TAG\endcsname}%
+ \ex\def\ex\ShortTag\ex{\ex\@nameauth at TrimTag\ex{\Tag}}%
+ \ifcsname#1!PRE\endcsname
+ \protected at edef\Pre{\csname#1!PRE\endcsname}%
+ \if at nameauth@Xref
+ \protected at edef\Entry{\Pre#2\ShortTag}%
\else
- \index%
- {\csname\cseq!PRE\endcsname#2\csname\cseq!TAG\endcsname}%
+ \protected at edef\Entry{\Pre#2\Tag}%
\fi
\else
\if at nameauth@Xref
- \index{#2\ShortTag}%
+ \protected at edef\Entry{#2\ShortTag}%
\else
- \index{#2\csname\cseq!TAG\endcsname}%
+ \protected at edef\Entry{#2\Tag}%
\fi
\fi
\else
- \ifcsname\cseq!PRE\endcsname
- \index{\csname\cseq!PRE\endcsname#2}%
+ \ifcsname#1!PRE\endcsname
+ \protected at edef\Pre{\csname#1!PRE\endcsname}%
+ \protected at edef\Entry{\Pre#2}%
\else
- \index{#2}%
+ \protected at edef\Entry{#2}%
\fi
\fi
+ \ex\index\ex{\Entry}%
\fi
}
% \end{macrocode}
@@ -4520,11 +5978,99 @@
% \end{macrocode}
% \end{macro}
%
-% \subsection{User Interface Macros}
+% \noindent{\large\bfseries Debugging Help}
+% \begin{macro}{\@nameauth at Debug}
+% \changes{3.3}{2020/02/20}{added}
+% This Swiss-army knife for debugging shows name control sequence patterns, full index entries with tags, and short index entries with just the name. Other macros call it to get the desired info. We set up a local scope, redefine \cmd{\index} to print an argument in the text, force indexing to occur, and ignore whether we are working with xrefs.
+% \begin{macrocode}
+\newcommandx*\@nameauth at Debug[3][1=\@empty, 3=\@empty]
+{%
+ \bgroup%
+ \def\index##1{##1}%
+ \@nameauth at DoIndextrue%
+ \protected at edef\arga{\trim at spaces{#1}}%
+ \protected at edef\argc{\trim at spaces{#3}}%
+ \protected at edef\suffb{\@nameauth at Suffix{#2}}%
+ \def\csb{\@nameauth at Clean{#2}}%
+ \def\csbc{\@nameauth at Clean{#2,#3}}%
+ \def\csab{\@nameauth at Clean{#1!#2}}%
+ \@nameauth at Error{#2}{macro \string\@nameauth at Debug}%
+% \end{macrocode}
+% We interleave printing name patterns (\cmd{\ShowPattern}), printing full index entries as if they were page refs (\cmd{\ShowIdxPageref*}), and printing short index entries (\cmd{\ShowIdxPageref}). Since we are in a local scope we delete the tag and xref control sequences as needed. They will be restored when the scope ends. We do not care about xrefs because we just want to see what happens with the name. We can always go to the \texttt{idx} and \texttt{ind} files if needed.
+% \begin{macrocode}
+ \ifx\arga\@empty
+ \ifx\argc\@empty
+ \ifdefined\ShortIdxEntry
+ \csundef{\csb!PRE}%
+ \csundef{\csb!TAG}%
+ \csundef{\csb!PN}%
+ \IndexName[#1]{#2}[#3]%
+ \else
+ \ifdefined\LongIdxEntry
+ \csundef{\csb!PN}%
+ \IndexName[#1]{#2}[#3]%
+ \else
+ \csb%
+ \fi
+ \fi
+ \else
+ \ifx\suffb\@empty
+ \ifdefined\ShortIdxEntry
+ \csundef{\csbc!PRE}%
+ \csundef{\csbc!TAG}%
+ \csundef{\csbc!PN}%
+ \IndexName[#1]{#2}[#3]%
+ \else
+ \ifdefined\LongIdxEntry
+ \csundef{\csbc!PN}%
+ \IndexName[#1]{#2}[#3]%
+ \else
+ \csbc%
+ \fi
+ \fi
+ \else
+ \ifdefined\ShortIdxEntry
+ \csundef{\csb!PRE}%
+ \csundef{\csb!TAG}%
+ \csundef{\csb!PN}%
+ \IndexName[#1]{#2}[#3]%
+ \else
+ \ifdefined\LongIdxEntry
+ \csundef{\csb!PN}%
+ \IndexName[#1]{#2}[#3]%
+ \else
+ \csb%
+ \fi
+ \fi
+ \fi
+ \fi
+ \else
+ \ifdefined\ShortIdxEntry
+ \csundef{\csab!PRE}%
+ \csundef{\csab!TAG}%
+ \csundef{\csab!PN}%
+ \IndexName[#1]{#2}[#3]%
+ \else
+ \ifdefined\LongIdxEntry
+ \csundef{\csab!PN}%
+ \IndexName[#1]{#2}[#3]%
+ \else
+ \csab%
+ \fi
+ \fi
+ \fi
+ \global\undef{\LongIdxEntry}%
+ \global\undef{\ShortIdxEntry}%
+ \egroup%
+}
+% \end{macrocode}
+% \end{macro}
+%
+% \subsection[Prefix Macros]{User Interface Macros: Prefix Macros}
% \noindent{\large\bfseries Syntactic Formatting\,---\,Capitalization}
% \begin{macro}{\CapThis}
% \changes{0.94}{2012/02/15}{Added}
-% Tells the root capping macro to cap the first character. This excludes \cmd{\CapName}.
+% Tells the root capping macro to cap the first character of all name elements.
% \begin{macrocode}
\newcommand*\CapThis{\@nameauth at DoCapstrue}
% \end{macrocode}
@@ -4541,7 +6087,7 @@
%
% \begin{macro}{\CapName}
% \changes{1.5}{2013/02/22}{Added}
-% Capitalize entire required name. \cmd{\CapThis} overrides this.
+% Capitalize entire required name. Overrides \cmd{\CapThis} for surnames.
% \begin{macrocode}
\newcommand*\CapName{\@nameauth at AllThistrue}
% \end{macrocode}
@@ -4548,7 +6094,7 @@
% \end{macro}
%
% \begin{macro}{\AllCapsInactive}
-% Turn off global surname capitalization. \cmd{\CapThis} overrides this.
+% Turn off global surname capitalization.
% \changes{1.5}{2013/02/22}{Added}
% \begin{macrocode}
\newcommand*\AllCapsInactive{\@nameauth at AllCapsfalse}
@@ -4557,7 +6103,7 @@
%
% \begin{macro}{\AllCapsActive}
% \changes{1.5}{2013/02/22}{Added}
-% Turn on global surname capitalization. \cmd{\CapThis} overrides this.
+% Turn on global surname capitalization. Activates \cmd{\CapName} for every name.
% \begin{macrocode}
\newcommand*\AllCapsActive{\@nameauth at AllCapstrue}
% \end{macrocode}
@@ -4581,7 +6127,7 @@
% \end{macro}
%
% \begin{macro}{\ReverseActive}
-% Turn on global name reversing.
+% Turn on global name reversing. Activates \cmd{\RevName} for every name.
% \changes{1.5}{2013/02/22}{Added}
% \begin{macrocode}
\newcommand*\ReverseActive{\@nameauth at RevAlltrue}
@@ -4589,7 +6135,7 @@
% \end{macro}
%
% \begin{macro}{\ForceFN}
-% Force the printing of an Eastern forename in the text, but only when using the ``short name'' macro \cmd{\FName} and the S-modifier.
+% Force the printing of an Eastern forename or ancient affix in the text, but only when using the ``short name'' macro \cmd{\FName} and the \cmd{\S}\meta{macro}.
% \changes{3.0}{2016/10/26}{Added}
% \begin{macrocode}
\newcommand*\ForceFN{\@nameauth at EastFNtrue}
@@ -4616,7 +6162,7 @@
% \end{macro}
%
% \begin{macro}{\ReverseCommaActive}
-% Turn on global ``last-name-comma-first.''
+% Turn on global ``last-name-comma-first.'' Activates \cmd{\RevComma} for every name.
% \changes{1.5}{2013/02/22}{Added}
% \begin{macrocode}
\newcommand*\ReverseCommaActive%
@@ -4624,11 +6170,11 @@
% \end{macrocode}
% \end{macro}
%
-% \noindent{\large\bfseries Alternate Syntactic Formatting}
-% \phantomsection\label{page:hooks}
+% \noindent{\large\bfseries Alternate Formatting}
+% \phantomsection\label{page:Hooks}
% \begin{macro}{\AltFormatActive}
% \changes{3.1}{2017/01/13}{Added}
-% Turn on alternate formatting.
+% Turn on alternate formatting, engage the formatting macros.
% \begin{macrocode}
\newcommand*\AltFormatActive{%
\global\@nameauth at AltFormattrue%
@@ -4639,7 +6185,7 @@
%
% \begin{macro}{\AltFormatActive*}
% \changes{3.1}{2017/01/13}{Added}
-% Turn on alternate formatting.
+% Turn on alternate formatting, disengage the formatting macros.
% \begin{macrocode}
\WithSuffix{\newcommand*}\AltFormatActive*{%
\global\@nameauth at AltFormattrue%
@@ -4649,7 +6195,7 @@
% \end{macro}
%
% \begin{macro}{\AltFormatInactive}
-% Turn off alternate formatting.
+% Turn off alternate formatting altogether.
% \changes{3.1}{2017/01/13}{Added}
% \begin{macrocode}
\newcommand*\AltFormatInactive{%
@@ -4685,6 +6231,7 @@
%
% \begin{macro}{\AltCaps}
% \changes{3.1}{2017/01/13}{Added}
+% \changes{3.2}{2017/03/22}{Use \cmd{\MakeUppercase}}
% Alternate discretionary capping macro triggered by \cmd{\CapThis}.
% \begin{macrocode}
\newcommand*\AltCaps[1]{%
@@ -4707,6 +6254,7 @@
%
% \begin{macro}{\textUC}
% \changes{3.1}{2017/01/13}{Added}
+% \changes{3.2}{2017/03/22}{Use \cmd{\MakeUppercase}}
% Alternate formatting macro: uppercase when active.
% \begin{macrocode}
\newcommand*\textUC[1]{%
@@ -4773,7 +6321,7 @@
% \end{macrocode}
% \end{macro}
%
-% \noindent{\large\bfseries Typographic Formatting\,---\,Main Versus Front Matter}
+% \noindent{\large\bfseries Post-Processing\,---\,Main Versus Front Matter}
% \begin{macro}{\NamesInactive}
% Switch to the ``non-formatted'' species of names.
% \begin{macrocode}
@@ -4788,7 +6336,7 @@
% \end{macrocode}
% \end{macro}
%
-% \noindent{\large\bfseries Typographic Formatting\,---\,First / Subsequent Reference}
+% \noindent{\large\bfseries Name Decisions\,---\,First\,/\,Subsequent Reference}
% \begin{macro}{\ForgetThis}
% \changes{3.1}{2017/01/13}{Added}
% Have the naming engine \cmd{\@nameauth at Name} call \cmd{\ForgetName} internally.
@@ -4817,7 +6365,7 @@
% \begin{macro}{\LocalNames}
% \changes{2.3}{2016/01/05}{Added}
% \changes{2.4}{2016/03/15}{Ensure global}
-% \cmd{\LocalNames} sets |@nameauth at LocalNames| true so \cmd{\ForgetName} and \cmd{\SubvertName} do not affect both formatted and unformatted naming systems.
+% \cmd{\LocalNames} sets |@nameauth at LocalNames| true so \cmd{\ForgetName} and \cmd{\SubvertName} do not affect both main and front matter naming systems.
% \begin{macrocode}
\newcommand*\LocalNames{\global\@nameauth at LocalNamestrue}
% \end{macrocode}
@@ -4876,19 +6424,46 @@
%
% \begin{macro}{\SeeAlso}
% \changes{3.0}{2016/10/26}{Added}
-% Change the type of cross-reference from a \emph{see} reference to a \emph{see also} reference. Works once per xref, unless one uses \cmd{\Include*}, in which case, take care!
+% Change the type of cross-reference from a \textit{see} reference to a \textit{see also} reference. Works once per xref, unless one uses \cmd{\Include*}, in which case, take care!
% \begin{macrocode}
\newcommand*\SeeAlso{\@nameauth at SeeAlsotrue}
% \end{macrocode}
% \end{macro}
%
-% \noindent{\large\bfseries Hook Macro Name Parser}
-% \phantomsection\label{page:parser}
+% \subsection[General User Interface]{User Interface Macros: General}
+% \label{sec:UserInterface}
+%
+% \begin{macro}{\ShowPattern}
+% \changes{3.3}{2020/02/20}{added}
+% This displays the pattern that the name arguments generate; maybe useful for debugging.
+% \begin{macrocode}
+\newcommand*\ShowPattern{\@nameauth at Debug}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\ShowIdxPageref}
+% \changes{3.3}{2020/02/20}{added}
+% This displays the index entry that will be generated. This may be useful for debugging.
+% \begin{macrocode}
+\newcommand*\ShowIdxPageref%
+ {\def\LongIdxEntry{}\ShowPattern}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\ShowIdxPageref*}
+% \changes{3.3}{2020/02/20}{added}
+% This displays an index entry with no tag. This may be useful for debugging.
+% \begin{macrocode}
+\WithSuffix{\newcommand*}\ShowIdxPageref*%
+ {\def\ShortIdxEntry{}\ShowPattern}
+% \end{macrocode}
+% \end{macro}
+%
% \begin{macro}{\NameParser}
% \changes{3.0}{2016/10/26}{Added}
-% \changes{3.03}{2016/11/01}{First name only with ``short'' macros}
-% \changes{3.1}{2017/01/13}{Older syntax fixed; NBSP added}
-% \changes{3.2}{2017/03/22}{Fix alt. format and Western affixes}
+% \changes{3.03}{2016/11/01}{First name only for short forms}
+% \changes{3.1}{2017/01/13}{Fix old syntax; add NBSP}
+% \changes{3.2}{2017/03/22}{Fix alt. format, affixes}
% Generate a name form based on the current state of the \textsf{nameauth} macros in the locked path. Available for use only in the hook macros.
% \begin{macrocode}
\newcommand*\NameParser
@@ -5026,12 +6601,24 @@
{\@nameauth at FirstNametrue\NameauthFName}
% \end{macrocode}
% \end{macro}
+%
+% \noindent{\large\bfseries Index Operations}
+% \begin{macro}{\IndexProtect}
+% \changes{3.3}{2020/02/20}{added}
+% We shut down all output from the naming and indexing macros to protect against problems in the index in case a macro in an index entry should expand into one of the naming macros.
+% \begin{macrocode}
+\newcommand*\IndexProtect
+{%
+ \@nameauth at DoIndexfalse%
+ \@nameauth at BigLocktrue%
+}
+% \end{macrocode}
+% \end{macro}
%
-% \noindent{\large\bfseries Index Operations}
% \begin{macro}{\IndexName}
-% \changes{0.75}{2012/01/19}{Has current args}
+% \changes{0.75}{2012/01/19}{Current args}
% \changes{0.85}{2012/02/05}{Hide commas}
-% \changes{1.26}{2012/04/24}{Affixes now correct}
+% \changes{1.26}{2012/04/24}{Fix affixes}
% \changes{2.0}{2015/11/11}{Fix spaces, tagging}
% \changes{2.6}{2016/09/19}{Fix commas}
% \changes{3.0}{2016/10/26}{Redesigned}
@@ -5064,7 +6651,7 @@
\else
\ifx\suffb\@empty
% \end{macrocode}
-% mononym or Eastern / ancient name, new syntax
+% mononym or Eastern\,/\,ancient name, new syntax
% \begin{macrocode}
\@nameauth at Index{\csb}{\rootb}%
\else
@@ -5124,6 +6711,7 @@
% \begin{macro}{\IndexRef}
% \changes{3.0}{2016/10/26}{Added}
% \changes{3.1}{2017/01/13}{Better tests}
+% \changes{3.3}{2020/02/20}{global flag reset}
% This creates an index cross-reference that is not already a pseudonym. It prints nothing. First we make copies of the arguments to test them and make parsing decisions.
% \begin{macrocode}
\newcommandx*\IndexRef[4][1=\@empty, 3=\@empty]
@@ -5143,7 +6731,7 @@
\@nameauth at Error{#2}{macro \string\IndexRef}%
\@nameauth at Xreftrue%
% \end{macrocode}
-% We create either \emph{see also} entries or \emph{see} entries. The former are unrestricted. The latter are only created if they do not already exist as main entries.
+% We create either \textit{see also} entries or \textit{see} entries. The former are unrestricted. The latter are only created if they do not already exist as main entries.
% \begin{macrocode}
\ifx\arga\@empty
\ifx\argc\@empty
@@ -5155,7 +6743,7 @@
\else
\ifx\suffb\@empty
% \end{macrocode}
-% mononym or Eastern / ancient name, new syntax
+% mononym or Eastern\,/\,ancient name, new syntax
% \begin{macrocode}
\if at nameauth@SeeAlso
\@nameauth at Index{\csb}{\rootb|seealso{\target}}%
@@ -5164,9 +6752,11 @@
\fi
\else
\if at nameauth@SeeAlso
- \@nameauth at Index{\csb}{\rootb\space\suffb|seealso{\target}}%
+ \@nameauth at Index{\csb}%
+ {\rootb\space\suffb|seealso{\target}}%
\else
- \@nameauth at Index{\csb}{\rootb\space\suffb|see{\target}}%
+ \@nameauth at Index{\csb}%
+ {\rootb\space\suffb|see{\target}}%
\fi
\fi
\csgdef{\csb!PN}{}%
@@ -5242,8 +6832,15 @@
\csgdef{\csab!PN}{}%
\fi
\fi
- \@nameauth at SeeAlsofalse%
\@nameauth at Xreffalse%
+% \end{macrocode}
+% This may not be necessary, but we do it for consistency.
+% \begin{macrocode}
+ \if at nameauth@OldReset
+ \@nameauth at SeeAlsofalse%
+ \else
+ \global\@nameauth at SeeAlsofalse%
+ \fi
}
% \end{macrocode}
% \end{macro}
@@ -5252,6 +6849,7 @@
% \changes{0.94}{2012/02/15}{Added}
% \changes{2.3}{2016/01/05}{New xref test}
% \changes{3.0}{2016/10/26}{Redesigned}
+% \changes{3.3}{2020/02/20}{More accurate warnings}
% This macro prevents a name from being indexed.
% \begin{macrocode}
\newcommandx*\ExcludeName[3][1=\@empty, 3=\@empty]
@@ -5302,7 +6900,7 @@
\ifcsname\csbc!PN\endcsname
\if at nameauth@Verbose
\PackageWarning{nameauth}%
- {macro \ExcludeName: Xref: #2 exists}%
+ {macro \ExcludeName: Xref: #2 #3 exists}%
\fi
\else
\csgdef{\csbc!PN}{!}%
@@ -5342,7 +6940,7 @@
\ifcsname\csab!PN\endcsname
\if at nameauth@Verbose
\PackageWarning{nameauth}%
- {macro \ExcludeName: Xref: #2 exists}%
+ {macro \ExcludeName: Xref: #1 #2 exists}%
\fi
\else
\csgdef{\csab!PN}{!}%
@@ -5354,6 +6952,7 @@
%
% \begin{macro}{\IncludeName}
% \changes{3.0}{2016/10/26}{Added}
+% \changes{3.3}{2020/02/20}{Added warnings}
% This macro allows a name to be indexed if it is not a cross-reference.
% \begin{macrocode}
\newcommandx*\IncludeName[3][1=\@empty, 3=\@empty]
@@ -5365,7 +6964,7 @@
\def\csbc{\@nameauth at Clean{#2,#3}}%
\def\csab{\@nameauth at Clean{#1!#2}}%
% \end{macrocode}
-% Below we parse the name arguments and undefine an ``excluded'' name.
+% Below we parse the name arguments and undefine only an ``excluded'' name.
% \begin{macrocode}
\@nameauth at Error{#2}{macro \string\IncludeName}%
\ifx\arga\@empty
@@ -5372,18 +6971,36 @@
\ifx\argc\@empty
\ifcsname\csb!PN\endcsname
\edef\testex{\csname\csb!PN\endcsname}%
- \unless\ifx\testex\@empty\global\csundef{\csb!PN}\fi
+ \unless\ifx\testex\@empty\global\csundef{\csb!PN}%
+ \else
+ \if at nameauth@Verbose
+ \PackageWarning{nameauth}%
+ {macro \IncludeName: Xref: #2 exists}%
+ \fi
+ \fi
\fi
\else
\ifx\suffb\@empty
\ifcsname\csbc!PN\endcsname
\edef\testex{\csname\csbc!PN\endcsname}%
- \unless\ifx\testex\@empty\global\csundef{\csbc!PN}\fi
+ \unless\ifx\testex\@empty\global\csundef{\csbc!PN}%
+ \else
+ \if at nameauth@Verbose
+ \PackageWarning{nameauth}%
+ {macro \IncludeName: Xref: #2 #3 exists}%
+ \fi
+ \fi
\fi
\else
\ifcsname\csb!PN\endcsname
\edef\testex{\csname\csb!PN\endcsname}%
- \unless\ifx\testex\@empty\global\csundef{\csb!PN}\fi
+ \unless\ifx\testex\@empty\global\csundef{\csb!PN}%
+ \else
+ \if at nameauth@Verbose
+ \PackageWarning{nameauth}%
+ {macro \IncludeName: Xref: #2 exists}%
+ \fi
+ \fi
\fi
\fi
\fi
@@ -5390,7 +7007,13 @@
\else
\ifcsname\csab!PN\endcsname
\edef\testex{\csname\csab!PN\endcsname}%
- \unless\ifx\testex\@empty\global\csundef{\csab!PN}\fi
+ \unless\ifx\testex\@empty\global\csundef{\csab!PN}%
+ \else
+ \if at nameauth@Verbose
+ \PackageWarning{nameauth}%
+ {macro \IncludeName: Xref: #1 #2 exists}%
+ \fi
+ \fi
\fi
\fi
}
@@ -5487,7 +7110,7 @@
}
% \end{macrocode}
% \end{macro}
-%
+%
% \begin{macro}{\TagName}
% \changes{1.2}{2012/02/25}{Added}
% \changes{1.9}{2015/07/09}{Fix cs collisions}
@@ -5503,7 +7126,7 @@
\def\csbc{\@nameauth at Clean{#2,#3}}%
\def\csab{\@nameauth at Clean{#1!#2}}%
% \end{macrocode}
-% We parse the arguments, defining the index tag control sequences used by\newline \cmd{\@nameauth at Index}.
+% We parse the arguments, defining the macros used by \cmd{\@nameauth at Index}.
% \begin{macrocode}
\@nameauth at Error{#2}{macro \string\TagName}%
\ifx\arga\@empty
@@ -5550,10 +7173,10 @@
}
% \end{macrocode}
% \end{macro}
-%
+%
% \begin{macro}{\UntagName}
% \changes{1.2}{2012/02/25}{Added}
-% \changes{1.9}{2015/07/09}{Ensure global undef, fix cs collisions}
+% \changes{1.9}{2015/07/09}{Global undef, no cs collisions}
% \changes{2.0}{2015/11/11}{Redesign tagging}
% This deletes an index tag.
% \begin{macrocode}
@@ -5566,7 +7189,7 @@
\def\csbc{\@nameauth at Clean{#2,#3}}%
\def\csab{\@nameauth at Clean{#1!#2}}%
% \end{macrocode}
-% We parse the arguments, undefining the index tag control sequences.
+% We parse the arguments, undefining the index tag macros.
% \begin{macrocode}
\@nameauth at Error{#2}{macro \string\UntagName}%
\ifx\arga\@empty
@@ -5585,11 +7208,11 @@
}
% \end{macrocode}
% \end{macro}
-%
+%
% \noindent{\large\bfseries Name Info Data Set: ``Text Tags''}
% \begin{macro}{\NameAddInfo}
% \changes{2.4}{2016/03/15}{Added}
-% This creates a control sequence and information associated with a given name, similar to an index tag, but usable in the body text.
+% This creates a macro that expands to information associated with a given name, similar to an index tag, but usable in the body text.
% \begin{macrocode}
\newcommandx\NameAddInfo[4][1=\@empty, 3=\@empty]
{%
@@ -5623,6 +7246,7 @@
% \begin{macro}{\NameQueryInfo}
% \changes{2.4}{2016/03/15}{Added}
% \changes{3.1}{2017/01/13}{Short macro}
+% \changes{3.3}{2020/02/20}{lock added}
% This prints the information created by \cmd{\NameAddInfo} if it exists.
% \begin{macrocode}
\newcommandx*\NameQueryInfo[3][1=\@empty, 3=\@empty]
@@ -5633,22 +7257,24 @@
\def\csb{\@nameauth at Clean{#2}}%
\def\csbc{\@nameauth at Clean{#2,#3}}%
\def\csab{\@nameauth at Clean{#1!#2}}%
+ \unless\if at nameauth@BigLock
% \end{macrocode}
-% We parse the arguments, invoking the tag control sequences to expand to their contents.
+% We parse the arguments, invoking the tag macros to expand to their contents.
% \begin{macrocode}
- \@nameauth at Error{#2}{macro \string\NameQueryInfo}%
- \ifx\arga\@empty
- \ifx\argc\@empty
- \ifcsname\csb!DB\endcsname\csname\csb!DB\endcsname\fi
- \else
- \ifx\Suff\@empty
- \ifcsname\csbc!DB\endcsname\csname\csbc!DB\endcsname\fi
+ \@nameauth at Error{#2}{macro \string\NameQueryInfo}%
+ \ifx\arga\@empty
+ \ifx\argc\@empty
+ \ifcsname\csb!DB\endcsname\csname\csb!DB\endcsname\fi
\else
- \ifcsname\csb!DB\endcsname\csname\csb!DB\endcsname\fi
+ \ifx\Suff\@empty
+ \ifcsname\csbc!DB\endcsname\csname\csbc!DB\endcsname\fi
+ \else
+ \ifcsname\csb!DB\endcsname\csname\csb!DB\endcsname\fi
+ \fi
\fi
+ \else
+ \ifcsname\csab!DB\endcsname\csname\csab!DB\endcsname\fi
\fi
- \else
- \ifcsname\csab!DB\endcsname\csname\csab!DB\endcsname\fi
\fi
}
% \end{macrocode}
@@ -5686,8 +7312,7 @@
}
% \end{macrocode}
% \end{macro}
-% \clearpage
-%
+%
% \noindent{\large\bfseries Name Decisions}
% \begin{macro}{\IfMainName}
% \changes{2.3}{2016/01/05}{Added}
@@ -5721,7 +7346,7 @@
}
% \end{macrocode}
% \end{macro}
-%
+%
% \begin{macro}{\IfFrontName}
% \changes{2.3}{2016/01/05}{Added}
% This macro expands one path if a front matter name exists, or else the other.
@@ -5754,7 +7379,7 @@
}
% \end{macrocode}
% \end{macro}
-%
+%
% \begin{macro}{\IfAKA}
% \changes{2.3}{2016/01/05}{Added}
% \changes{2.4}{2016/03/15}{Test for excluded}
@@ -5804,8 +7429,8 @@
%
% \noindent{\large\bfseries Changing Name Decisions}
% \begin{macro}{\ForgetName}
-% \changes{0.75}{2012/01/19}{Add new argument}
-% \changes{1.9}{2015/07/09}{Ensure global undef}
+% \changes{0.75}{2012/01/19}{Current args}
+% \changes{1.9}{2015/07/09}{Global undef}
% \changes{2.3}{2016/01/05}{Global or local}
% This undefines a control sequence to force a ``first use.''
% \begin{macrocode}
@@ -5819,7 +7444,6 @@
\def\csab{\@nameauth at Clean{#1!#2}}%
\@nameauth at Error{#2}{macro \string\ForgetName}%
% \end{macrocode}
-% \clearpage\noindent
% Now we parse the arguments, undefining the control sequences either by current name type (via |@nameauth at MainFormat|) or completely (toggled by |@nameauth at LocalNames|).
% \begin{macrocode}
\ifx\arga\@empty
@@ -5874,7 +7498,6 @@
}
% \end{macrocode}
% \end{macro}
-% \clearpage
%
% \begin{macro}{\SubvertName}
% \changes{0.9}{2012/02/10}{Added}
@@ -5949,79 +7572,101 @@
}
% \end{macrocode}
% \end{macro}
-%
+%
% \noindent{\large\bfseries Alternate Names}
% \begin{macro}{\AKA}
% \changes{0.85}{2012/02/05}{Hide commas}
-% \changes{1.26}{2012/04/24}{Fix name suffixes}
-% \changes{1.5}{2013/02/22}{Reversing and caps}
+% \changes{1.26}{2012/04/24}{Fix affixes}
+% \changes{1.5}{2013/02/22}{Reversing, caps}
% \changes{2.0}{2015/11/11}{Trim spaces; fix tagging}
% \changes{2.1}{2015/11/24}{Fix Unicode}
-% \changes{2.3}{2016/01/05}{Expand starred mode}
+% \changes{2.3}{2016/01/05}{Fix starred mode}
% \changes{2.41}{2016/03/17}{Fix token regs}
% \changes{2.6}{2016/09/19}{Fix index commas}
% \changes{3.0}{2016/10/26}{Redesigned}
% \changes{3.1}{2017/01/13}{Can skip index}
+% \changes{3.3}{2020/02/20}{global flag reset}
% \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]
{%
% \end{macrocode}
-% Prevent entering \cmd{\AKA} via itself or \cmd{\@nameauth at Name}. Prevent the index-only flag.
+% Prevent entering \cmd{\AKA} via itself or \cmd{\@nameauth at Name}. Prevent the index-only flag. Tell the formatting system that \cmd{\AKA} is running.
% \begin{macrocode}
+ \if at nameauth@BigLock\@nameauth at Locktrue\fi
\unless\if at nameauth@Lock
- \@nameauth at Locktrue%
- \@nameauth at JustIndexfalse%
+ \@nameauth at Locktrue%
+ \@nameauth at InAKAtrue%
+ \if at nameauth@OldReset
+ \@nameauth at JustIndexfalse%
+ \else
+ \global\@nameauth at JustIndexfalse%
+ \fi
% \end{macrocode}
-% Tell the formatting system that \cmd{\AKA} is running. Test for malformed input.
+% Test for malformed input.
% \begin{macrocode}
- \@nameauth at InAKAtrue%
- \@nameauth at Error{#2}{macro \string\AKA}%
- \@nameauth at Error{#4}{macro \string\AKA}%
+ \@nameauth at Error{#2}{macro \string\AKA}%
+ \@nameauth at Error{#4}{macro \string\AKA}%
% \end{macrocode}
% Names occur in horizontal mode; we ensure that. Next we make copies of the target name arguments and we parse and print the cross-reference name.
% \begin{macrocode}
- \leavevmode\hbox{}%
- \protected at edef\argi{\trim at spaces{#1}}%
- \protected at edef\rooti{\@nameauth at Root{#2}}%
- \protected at edef\suffi{\@nameauth at Suffix{#2}}%
- \@nameauth at Parse[#3]{#4}[#5]{!PN}%
+ \leavevmode\hbox{}%
+ \protected at edef\argi{\trim at spaces{#1}}%
+ \protected at edef\rooti{\@nameauth at Root{#2}}%
+ \protected at edef\suffi{\@nameauth at Suffix{#2}}%
+ \@nameauth at Parse[#3]{#4}[#5]{!PN}%
% \end{macrocode}
% Create an index cross-reference based on the arguments.
% \begin{macrocode}
- \unless\if at nameauth@SkipIndex
- \ifx\argi\@empty
- \ifx\suffi\@empty
- \IndexRef[#3]{#4}[#5]{\rooti}%
+ \unless\if at nameauth@SkipIndex
+ \ifx\argi\@empty
+ \ifx\suffi\@empty
+ \IndexRef[#3]{#4}[#5]{\rooti}%
+ \else
+ \IndexRef[#3]{#4}[#5]{\rooti\space\suffi}%
+ \fi
\else
- \IndexRef[#3]{#4}[#5]{\rooti\space\suffi}%
+ \ifx\suffi\@empty
+ \IndexRef[#3]{#4}[#5]{\rooti,\space\argi}%
+ \else
+ \IndexRef[#3]{#4}[#5]{\rooti,\space\argi,\space\suffi}%
+ \fi
\fi
- \else
- \ifx\suffi\@empty
- \IndexRef[#3]{#4}[#5]{\rooti,\space\argi}%
- \else
- \IndexRef[#3]{#4}[#5]{\rooti,\space\argi,\space\suffi}%
- \fi
\fi
- \fi
% \end{macrocode}
-% Reset all the ``per name'' Boolean values.
+% Reset all the ``per name'' Boolean values. The default is global.
% \begin{macrocode}
- \@nameauth at SkipIndexfalse%
- \@nameauth at Lockfalse%
- \@nameauth at InAKAfalse%
- \@nameauth at AltAKAfalse%
- \@nameauth at NBSPfalse%
- \@nameauth at NBSPXfalse%
- \@nameauth at DoCapsfalse%
- \@nameauth at Accentfalse%
- \@nameauth at AllThisfalse%
- \@nameauth at ShowCommafalse%
- \@nameauth at NoCommafalse%
- \@nameauth at RevThisfalse%
- \@nameauth at RevThisCommafalse%
- \@nameauth at ShortSNNfalse%
- \@nameauth at EastFNfalse%
+ \if at nameauth@OldReset
+ \@nameauth at SkipIndexfalse%
+ \@nameauth at AltAKAfalse%
+ \@nameauth at NBSPfalse%
+ \@nameauth at NBSPXfalse%
+ \@nameauth at DoCapsfalse%
+ \@nameauth at Accentfalse%
+ \@nameauth at AllThisfalse%
+ \@nameauth at ShowCommafalse%
+ \@nameauth at NoCommafalse%
+ \@nameauth at RevThisfalse%
+ \@nameauth at RevThisCommafalse%
+ \@nameauth at ShortSNNfalse%
+ \@nameauth at EastFNfalse%
+ \else
+ \global\@nameauth at SkipIndexfalse%
+ \global\@nameauth at AltAKAfalse%
+ \global\@nameauth at NBSPfalse%
+ \global\@nameauth at NBSPXfalse%
+ \global\@nameauth at DoCapsfalse%
+ \global\@nameauth at Accentfalse%
+ \global\@nameauth at AllThisfalse%
+ \global\@nameauth at ShowCommafalse%
+ \global\@nameauth at NoCommafalse%
+ \global\@nameauth at RevThisfalse%
+ \global\@nameauth at RevThisCommafalse%
+ \global\@nameauth at ShortSNNfalse%
+ \global\@nameauth at EastFNfalse%
+ \fi
+ \@nameauth at Lockfalse%
+ \@nameauth at InAKAfalse%
% \end{macrocode}
% Close the ``locked'' branch.
% \begin{macrocode}
@@ -6043,7 +7688,7 @@
% \end{macro}
%
% \begin{macro}{\PName}
-% \changes{2.3}{2016/01/05}{Work directly with hooks}
+% \changes{2.3}{2016/01/05}{Work with hooks}
% \changes{3.1}{2017/01/13}{Can skip index}
% \cmd{\PName} is a convenience macro that calls \cmd{\NameauthName}, then \cmd{\AKA}. It prevents the index-only feature from triggering.
% \begin{macrocode}
@@ -6073,7 +7718,7 @@
% \changes{2.0}{2015/11/11}{Better arg handling}
% \changes{2.11}{2015/11/29}{Bugfix}
% \changes{2.41}{2016/03/17}{No local \cmd{\newtoks}}
-% The \texttt{nameauth} environment creares macro shorthands. First we define a control sequence \cmd{\<} that takes four parameters, delimited by three ampersands and \texttt{>}.
+% The \texttt{nameauth} environment creates macro shorthands. First we define a control sequence \cmd{\<} that takes four parameters, delimited by three ampersands and \texttt{>}.
% \begin{macrocode}
\newenvironment{nameauth}{%
\begingroup%
@@ -6086,7 +7731,7 @@
\@nameauth at etoksc\expandafter{##3}%
\@nameauth at etoksd\expandafter{##4}%
% \end{macrocode}
-% The first argument must have some text to create a set of control sequences with it. The third argument is the required name field. Redefining a shorthand creates a warning.
+% The first argument must have some text to create a set of control sequences with it. The third argument is the required name argument. Redefining a shorthand creates a warning.
% \begin{macrocode}
\ifx\@arga\@empty
\PackageError{nameauth}%
@@ -6096,21 +7741,21 @@
\ifcsname\@arga\endcsname
\PackageWarning{nameauth}%
{environment nameauth: Shorthand macro already exists}%
- \fi
+ \fi
% \end{macrocode}
-% Set up shorthands according to name form. We have to use \cmd{\expandafter}, not the $\epsilon$-\TeX{} way, due to \cmd{\protected at edef} in the naming macros.
+% Set up shorthands according to name form. We have to use \cmd{\expandafter}, not the \(\epsilon\)-\TeX{} way, due to \cmd{\protected at edef} in the naming macros.
%
% We begin with mononyms and non-Western names that use the new syntax. We use one \cmd{\expandafter} per token because we only have one argument to expand first.
% \begin{macrocode}
- \ifx\@testd\@empty
+ \ifx\@testd\@empty
\ifx\@testb\@empty
- \ex\csgdef\ex{\ex\@arga\ex}\ex{\ex\NameauthName\ex{%
- \the\@nameauth at etoksc}}%
- \ex\csgdef\ex{\ex L\ex\@arga\ex}\ex{%
- \ex\@nameauth at FullNametrue%
+ \ex\csgdef\ex{\ex\@arga\ex}%
+ \ex{\ex\NameauthName\ex{\the\@nameauth at etoksc}}%
+ \ex\csgdef\ex{\ex L\ex\@arga\ex}%
+ \ex{\ex\@nameauth at FullNametrue%
\ex\NameauthLName\ex{\the\@nameauth at etoksc}}%
- \ex\csgdef\ex{\ex S\ex\@arga\ex}\ex{%
- \ex\@nameauth at FirstNametrue%
+ \ex\csgdef\ex{\ex S\ex\@arga\ex}%
+ \ex{\ex\@nameauth at FirstNametrue%
\ex\NameauthFName\ex{\the\@nameauth at etoksc}}%
\else
% \end{macrocode}
@@ -6117,33 +7762,39 @@
% Next we have Western names with no alternate names. Here we have two arguments to expand in reverse order, so we need three, then one uses of \cmd{\expandafter} per token.
% \begin{macrocode}
\ex\ex\ex\csgdef\ex\ex\ex{\ex\ex\ex\@arga\ex\ex\ex}%
- \ex\ex\ex{\ex\ex\ex\NameauthName\ex\ex\ex[%
- \ex\the\ex\@nameauth at etoksb\ex]\ex{\the\@nameauth at etoksc}}%
+ \ex\ex\ex{\ex\ex\ex\NameauthName%
+ \ex\ex\ex[\ex\the\ex\@nameauth at etoksb\ex]%
+ \ex{\the\@nameauth at etoksc}}%
\ex\ex\ex\csgdef\ex\ex\ex{\ex\ex\ex L\ex\ex\ex\@arga%
\ex\ex\ex}\ex\ex\ex{\ex\ex\ex\@nameauth at FullNametrue%
- \ex\ex\ex\NameauthLName\ex\ex\ex[%
- \ex\the\ex\@nameauth at etoksb\ex]\ex{\the\@nameauth at etoksc}}%
+ \ex\ex\ex\NameauthLName%
+ \ex\ex\ex[\ex\the\ex\@nameauth at etoksb\ex]%
+ \ex{\the\@nameauth at etoksc}}%
\ex\ex\ex\csgdef\ex\ex\ex{\ex\ex\ex S\ex\ex\ex\@arga%
\ex\ex\ex}\ex\ex\ex{\ex\ex\ex\@nameauth at FirstNametrue%
- \ex\ex\ex\NameauthFName\ex\ex\ex[%
- \ex\the\ex\@nameauth at etoksb\ex]\ex{\the\@nameauth at etoksc}}%
+ \ex\ex\ex\NameauthFName%
+ \ex\ex\ex[\ex\the\ex\@nameauth at etoksb\ex]%
+ \ex{\the\@nameauth at etoksc}}%
\fi
\else
% \end{macrocode}
-% Below are native Eastern names with alternates and the older syntax. Again, we have three or one use of \cmd{\expandafter} per step before the respective arguments.
+% Below are ``native'' Eastern names with alternates and the older syntax. Again, we have three or one use of \cmd{\expandafter} per step before the respective arguments.
% \begin{macrocode}
\ifx\@testb\@empty
\ex\ex\ex\csgdef\ex\ex\ex{\ex\ex\ex\@arga\ex\ex\ex}%
- \ex\ex\ex{\ex\ex\ex\NameauthName\ex\ex\ex{%
- \ex\the\ex\@nameauth at etoksc\ex}\ex[\the\@nameauth at etoksd]}%
+ \ex\ex\ex{\ex\ex\ex\NameauthName%
+ \ex\ex\ex{\ex\the\ex\@nameauth at etoksc\ex}%
+ \ex[\the\@nameauth at etoksd]}%
\ex\ex\ex\csgdef\ex\ex\ex{\ex\ex\ex L\ex\ex\ex\@arga%
\ex\ex\ex}\ex\ex\ex{\ex\ex\ex\@nameauth at FullNametrue%
- \ex\ex\ex\NameauthLName\ex\ex\ex{%
- \ex\the\ex\@nameauth at etoksc\ex}\ex[\the\@nameauth at etoksd]}%
+ \ex\ex\ex\NameauthLName%
+ \ex\ex\ex{\ex\the\ex\@nameauth at etoksc\ex}%
+ \ex[\the\@nameauth at etoksd]}%
\ex\ex\ex\csgdef\ex\ex\ex{\ex\ex\ex S\ex\ex\ex\@arga%
\ex\ex\ex}\ex\ex\ex{\ex\ex\ex\@nameauth at FirstNametrue%
- \ex\ex\ex\NameauthFName\ex\ex\ex{%
- \ex\the\ex\@nameauth at etoksc\ex}\ex[\the\@nameauth at etoksd]}%
+ \ex\ex\ex\NameauthFName%
+ \ex\ex\ex{\ex\the\ex\@nameauth at etoksc\ex}%
+ \ex[\the\@nameauth at etoksd]}%
\else
% \end{macrocode}
% Here are Western names with alternates. We have three arguments to expand, so we have seven, three, and one respective use of \cmd{\expandafter}.
@@ -6151,32 +7802,36 @@
\ex\ex\ex\ex\ex\ex\ex\csgdef\ex\ex\ex\ex\ex\ex\ex{%
\ex\ex\ex\ex\ex\ex\ex\@arga\ex\ex\ex\ex\ex\ex\ex}%
\ex\ex\ex\ex\ex\ex\ex{\ex\ex\ex\ex\ex\ex\ex\NameauthName%
- \ex\ex\ex\ex\ex\ex\ex[\ex\ex\ex\the\ex\ex\ex\@nameauth at etoksb%
- \ex\ex\ex]\ex\ex\ex{\ex\the\ex\@nameauth at etoksc\ex}\ex[%
- \the\@nameauth at etoksd]}%
+ \ex\ex\ex\ex\ex\ex\ex[\ex\ex\ex\the%
+ \ex\ex\ex\@nameauth at etoksb\ex\ex\ex]%
+ \ex\ex\ex{\ex\the\ex\@nameauth at etoksc\ex}%
+ \ex[\the\@nameauth at etoksd]}%
\ex\ex\ex\ex\ex\ex\ex\csgdef\ex\ex\ex\ex\ex\ex\ex{%
\ex\ex\ex\ex\ex\ex\ex L\ex\ex\ex\ex\ex\ex\ex\@arga%
\ex\ex\ex\ex\ex\ex\ex}\ex\ex\ex\ex\ex\ex\ex{%
\ex\ex\ex\ex\ex\ex\ex\@nameauth at FullNametrue%
- \ex\ex\ex\ex\ex\ex\ex\NameauthLName\ex\ex\ex\ex\ex\ex\ex[%
- \ex\ex\ex\the\ex\ex\ex\@nameauth at etoksb%
- \ex\ex\ex]\ex\ex\ex{\ex\the\ex\@nameauth at etoksc\ex}\ex[%
- \the\@nameauth at etoksd]}%
+ \ex\ex\ex\ex\ex\ex\ex\NameauthLName%
+ \ex\ex\ex\ex\ex\ex\ex[\ex\ex\ex\the\ex\ex\ex%
+ \@nameauth at etoksb\ex\ex\ex]%
+ \ex\ex\ex{\ex\the\ex\@nameauth at etoksc\ex}%
+ \ex[\the\@nameauth at etoksd]}%
\ex\ex\ex\ex\ex\ex\ex\csgdef\ex\ex\ex\ex\ex\ex\ex{%
\ex\ex\ex\ex\ex\ex\ex S\ex\ex\ex\ex\ex\ex\ex\@arga%
\ex\ex\ex\ex\ex\ex\ex}\ex\ex\ex\ex\ex\ex\ex{%
\ex\ex\ex\ex\ex\ex\ex\@nameauth at FirstNametrue%
- \ex\ex\ex\ex\ex\ex\ex\NameauthFName\ex\ex\ex\ex\ex\ex\ex[%
- \ex\ex\ex\the\ex\ex\ex\@nameauth at etoksb\ex\ex\ex]%
- \ex\ex\ex{\ex\the\ex\@nameauth at etoksc\ex}\ex[%
- \the\@nameauth at etoksd]}%
+ \ex\ex\ex\ex\ex\ex\ex\NameauthFName%
+ \ex\ex\ex\ex\ex\ex\ex[\ex\ex\ex\the\ex\ex\ex%
+ \@nameauth at etoksb\ex\ex\ex]%
+ \ex\ex\ex{\ex\the\ex\@nameauth at etoksc\ex}%
+ \ex[\the\@nameauth at etoksd]}%
\fi
- \fi
- \ignorespaces%
+ \fi\ignorespaces%
}\ignorespaces%
}{\endgroup\ignorespaces}
% \end{macrocode}
% \end{environment}
-%\Finale
+% \Finale
\endinput
+%\iffalse
%</package>
+%\fi
Modified: trunk/Master/texmf-dist/source/latex/nameauth/nameauth.ins
===================================================================
--- trunk/Master/texmf-dist/source/latex/nameauth/nameauth.ins 2020-02-21 22:55:44 UTC (rev 53862)
+++ trunk/Master/texmf-dist/source/latex/nameauth/nameauth.ins 2020-02-21 22:56:14 UTC (rev 53863)
@@ -9,7 +9,7 @@
%% --------:| ----------------------------------------------------------------
%% nameauth:| Name authority mechanism for consistency in text and index
%% Author:| Charles P. Schaum
-%% E-mail:| charles dot schaum at comcast dot net
+%% E-mail:| charles dot schaum at comcast.net
%% License:| Released under the LaTeX Project Public License 1.3c or later
%% See:| http://www.latex-project.org/lppl.txt
%%
@@ -21,7 +21,7 @@
--------:| ----------------------------------------------------------------
nameauth:| Name authority mechanism for consistency in text and index
Author:| Charles P. Schaum
- E-mail:| charles dot schaum at comcast dot net
+ E-mail:| charles dot schaum at comcast.net
License:| Released under the LaTeX Project Public License 1.3c or later
See:| http://www.latex-project.org/lppl.txt
@@ -28,12 +28,12 @@
\endpreamble
\postamble
-Copyright (C) 2017 by Charles P. Schaum <charles dot schaum at comcast dot net>
+Copyright (C) 2020 by Charles P. Schaum <charles dot schaum at comcast.net>
-This work may be distributed and/or modified under the
+This work may be distributed and / or modified under the
conditions of the LaTeX Project Public License (LPPL), either
version 1.3c of this license or (at your option) any later
-version. The latest version of this license is in the file:
+version. The latest version of this license is in the file:
http://www.latex-project.org/lppl.txt
@@ -41,10 +41,9 @@
Charles P. Schaum.
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.
-
+These files generate README.txt / README, nameauth.ins, nameauth.sty, and
+nameauth.pdf, with other intermediate files, as a part of this work. See
+the README.txt or README for more information.
\endpostamble
\usedir{tex/latex/nameauth}
@@ -53,12 +52,12 @@
}
\endbatchfile
%%
-%% Copyright (C) 2017 by Charles P. Schaum <charles dot schaum at comcast dot net>
+%% Copyright (C) 2020 by Charles P. Schaum <charles dot schaum at comcast.net>
%%
-%% This work may be distributed and/or modified under the
+%% This work may be distributed and / or modified under the
%% conditions of the LaTeX Project Public License (LPPL), either
%% version 1.3c of this license or (at your option) any later
-%% version. The latest version of this license is in the file:
+%% version. The latest version of this license is in the file:
%%
%% http://www.latex-project.org/lppl.txt
%%
@@ -66,9 +65,8 @@
%% Charles P. Schaum.
%%
%% 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.
-%%
+%% These files generate README.txt / README, nameauth.ins, nameauth.sty, and
+%% nameauth.pdf, with other intermediate files, as a part of this work. See
+%% the README.txt or README for more information.
%%
%% End of file `nameauth.ins'.
Modified: trunk/Master/texmf-dist/tex/latex/nameauth/nameauth.sty
===================================================================
--- trunk/Master/texmf-dist/tex/latex/nameauth/nameauth.sty 2020-02-21 22:55:44 UTC (rev 53862)
+++ trunk/Master/texmf-dist/tex/latex/nameauth/nameauth.sty 2020-02-21 22:56:14 UTC (rev 53863)
@@ -9,17 +9,18 @@
%% --------:| ----------------------------------------------------------------
%% nameauth:| Name authority mechanism for consistency in text and index
%% Author:| Charles P. Schaum
-%% E-mail:| charles dot schaum at comcast dot net
+%% E-mail:| charles dot schaum at comcast.net
%% License:| Released under the LaTeX Project Public License 1.3c or later
%% See:| http://www.latex-project.org/lppl.txt
%%
\NeedsTeXFormat{LaTeX2e}[1999/12/01]
\ProvidesPackage{nameauth}
- [2017/03/22 3.2 Name authority mechanism for consistency in text and index]
+ [2020/02/20 3.3 Name authority mechanism for consistency in text and index]
\newif\if at nameauth@InAKA
\newif\if at nameauth@InName
\newif\if at nameauth@Xref
\newif\if at nameauth@Lock
+\newif\if at nameauth@BigLock
\newif\if at nameauth@InHook
\newif\if at nameauth@DoIndex
\newif\if at nameauth@SkipIndex
@@ -29,6 +30,8 @@
\newif\if at nameauth@MainFormat
\newif\if at nameauth@AKAFormat
\newif\if at nameauth@LocalNames
+\newif\if at nameauth@OldReset
+\newif\if at nameauth@OldPass
\newif\if at nameauth@Forget
\newif\if at nameauth@Subvert
\newif\if at nameauth@FirstFormat
@@ -76,6 +79,8 @@
\DeclareOption{frontmatter}{\@nameauth at MainFormatfalse}
\DeclareOption{formatAKA}{\@nameauth at AKAFormattrue}
\DeclareOption{oldAKA}{\@nameauth at OldAKAtrue}
+\DeclareOption{oldreset}{\@nameauth at OldResettrue}
+\DeclareOption{oldpass}{\@nameauth at OldPasstrue}
\DeclareOption{index}{\@nameauth at DoIndextrue}
\DeclareOption{noindex}{\@nameauth at DoIndexfalse}
\DeclareOption{pretag}{\@nameauth at Pretagtrue}
@@ -187,8 +192,8 @@
}
\newcommand*\@nameauth at Error[2]
{%
- \edef\msga{#2 SNN field empty}%
- \edef\msgb{#2 SNN field malformed}%
+ \edef\msga{#2 SNN arg empty}%
+ \edef\msgb{#2 SNN arg malformed}%
\protected at edef\testname{\trim at spaces{#1}}%
\protected at edef\testroot{\@nameauth at Root{#1}}%
\ifx\testname\@empty
@@ -200,6 +205,7 @@
}
\newcommandx*\@nameauth at Name[3][1=\@empty, 3=\@empty]
{%
+ \if at nameauth@BigLock\@nameauth at Locktrue\fi
\unless\if at nameauth@Lock
\@nameauth at Locktrue%
\@nameauth at InNametrue%
@@ -206,9 +212,19 @@
\@nameauth at Error{#2}{macro \string\@nameauth at name}%
\if at nameauth@JustIndex
\IndexName[#1]{#2}[#3]%
- \@nameauth at InNamefalse%
- \@nameauth at Lockfalse%
- \@nameauth at JustIndexfalse%
+ \if at nameauth@OldPass
+ \@nameauth at JustIndexfalse%
+ \else
+ \if at nameauth@OldReset
+ \@nameauth at FullNamefalse%
+ \@nameauth at FirstNamefalse%
+ \@nameauth at JustIndexfalse%
+ \else
+ \global\@nameauth at FullNamefalse%
+ \global\@nameauth at FirstNamefalse%
+ \global\@nameauth at JustIndexfalse%
+ \fi
+ \fi
\else
\if at nameauth@Forget
\ForgetName[#1]{#2}[#3]%
@@ -225,28 +241,46 @@
\@nameauth at Parse[#1]{#2}[#3]{!NF}%
\fi
\unless\if at nameauth@SkipIndex\IndexName[#1]{#2}[#3]\fi
- \@nameauth at SkipIndexfalse%
- \@nameauth at Forgetfalse%
- \@nameauth at Subvertfalse%
- \@nameauth at Lockfalse%
- \@nameauth at InNamefalse%
- \@nameauth at NBSPfalse%
- \@nameauth at NBSPXfalse%
- \@nameauth at DoCapsfalse%
- \@nameauth at Accentfalse%
- \@nameauth at AllThisfalse%
- \@nameauth at ShowCommafalse%
- \@nameauth at NoCommafalse%
- \@nameauth at RevThisfalse%
- \@nameauth at RevThisCommafalse%
- \@nameauth at ShortSNNfalse%
- \@nameauth at EastFNfalse%
+ \if at nameauth@OldReset
+ \@nameauth at SkipIndexfalse%
+ \@nameauth at Forgetfalse%
+ \@nameauth at Subvertfalse%
+ \@nameauth at NBSPfalse%
+ \@nameauth at NBSPXfalse%
+ \@nameauth at DoCapsfalse%
+ \@nameauth at Accentfalse%
+ \@nameauth at AllThisfalse%
+ \@nameauth at ShowCommafalse%
+ \@nameauth at NoCommafalse%
+ \@nameauth at RevThisfalse%
+ \@nameauth at RevThisCommafalse%
+ \@nameauth at ShortSNNfalse%
+ \@nameauth at EastFNfalse%
+ \else
+ \global\@nameauth at SkipIndexfalse%
+ \global\@nameauth at Forgetfalse%
+ \global\@nameauth at Subvertfalse%
+ \global\@nameauth at NBSPfalse%
+ \global\@nameauth at NBSPXfalse%
+ \global\@nameauth at DoCapsfalse%
+ \global\@nameauth at Accentfalse%
+ \global\@nameauth at AllThisfalse%
+ \global\@nameauth at ShowCommafalse%
+ \global\@nameauth at NoCommafalse%
+ \global\@nameauth at RevThisfalse%
+ \global\@nameauth at RevThisCommafalse%
+ \global\@nameauth at ShortSNNfalse%
+ \global\@nameauth at EastFNfalse%
+ \fi
\fi
+ \@nameauth at Lockfalse%
+ \@nameauth at InNamefalse%
\fi
\if at nameauth@Punct\expandafter\@nameauth at CheckDot\fi
}
\newcommandx*\@nameauth at Parse[4][1=\@empty, 3=\@empty]
{%
+ \if at nameauth@BigLock\@nameauth at Lockfalse\fi
\if at nameauth@Lock
\let\ex\expandafter%
\protected at edef\arga{\trim at spaces{#1}}%
@@ -365,6 +399,7 @@
}
\newcommand*\@nameauth at NonWest[1]
{%
+ \if at nameauth@BigLock\@nameauth at Lockfalse\fi
\if at nameauth@Lock
\unless\ifcsname#1\endcsname
\@nameauth at FirstFormattrue%
@@ -411,12 +446,18 @@
\unless\ifcsname#1\endcsname
\unless\if at nameauth@InAKA\csgdef{#1}{}\fi
\fi
- \@nameauth at FullNamefalse%
- \@nameauth at FirstNamefalse%
+ \if at nameauth@OldReset
+ \@nameauth at FullNamefalse%
+ \@nameauth at FirstNamefalse%
+ \else
+ \global\@nameauth at FullNamefalse%
+ \global\@nameauth at FirstNamefalse%
+ \fi
\fi
}
\newcommand*\@nameauth at West[1]
{%
+ \if at nameauth@BigLock\@nameauth at Lockfalse\fi
\if at nameauth@Lock
\unless\ifcsname#1\endcsname
\@nameauth at FirstFormattrue%
@@ -459,12 +500,18 @@
\unless\ifcsname#1\endcsname
\unless\if at nameauth@InAKA\csgdef{#1}{}\fi
\fi
- \@nameauth at FullNamefalse%
- \@nameauth at FirstNamefalse%
+ \if at nameauth@OldReset
+ \@nameauth at FullNamefalse%
+ \@nameauth at FirstNamefalse%
+ \else
+ \global\@nameauth at FullNamefalse%
+ \global\@nameauth at FirstNamefalse%
+ \fi
\fi
}
\newcommand*\@nameauth at Hook[1]
{%
+ \if at nameauth@BigLock\@nameauth at Lockfalse\fi
\if at nameauth@Lock
\@nameauth at InHooktrue%
\protected at edef\test{#1}%
@@ -507,45 +554,124 @@
\fi
\fi
\fi
- \@nameauth at FirstFormatfalse%
+ \if at nameauth@OldReset
+ \@nameauth at FirstFormatfalse%
+ \else
+ \global\@nameauth at FirstFormatfalse%
+ \fi
\@nameauth at InHookfalse%
\fi
}
\newcommand*\@nameauth at Index[2]
{%
- \def\cseq{#1}%
\let\ex\expandafter%
- \ifcsname\cseq!TAG\endcsname
- \protected at edef\Tag{\csname#1!TAG\endcsname}%
- \ex\def\ex\ShortTag\ex{\ex\@nameauth at TrimTag\ex{\Tag}}%
- \fi
\if at nameauth@DoIndex
- \ifcsname\cseq!TAG\endcsname
- \ifcsname\cseq!PRE\endcsname
- \if at nameauth@Xref%
- \index%
- {\csname\cseq!PRE\endcsname#2\ShortTag}%
+ \ifcsname#1!TAG\endcsname
+ \protected at edef\Tag{\csname#1!TAG\endcsname}%
+ \ex\def\ex\ShortTag\ex{\ex\@nameauth at TrimTag\ex{\Tag}}%
+ \ifcsname#1!PRE\endcsname
+ \protected at edef\Pre{\csname#1!PRE\endcsname}%
+ \if at nameauth@Xref
+ \protected at edef\Entry{\Pre#2\ShortTag}%
\else
- \index%
- {\csname\cseq!PRE\endcsname#2\csname\cseq!TAG\endcsname}%
+ \protected at edef\Entry{\Pre#2\Tag}%
\fi
\else
\if at nameauth@Xref
- \index{#2\ShortTag}%
+ \protected at edef\Entry{#2\ShortTag}%
\else
- \index{#2\csname\cseq!TAG\endcsname}%
+ \protected at edef\Entry{#2\Tag}%
\fi
\fi
\else
- \ifcsname\cseq!PRE\endcsname
- \index{\csname\cseq!PRE\endcsname#2}%
+ \ifcsname#1!PRE\endcsname
+ \protected at edef\Pre{\csname#1!PRE\endcsname}%
+ \protected at edef\Entry{\Pre#2}%
\else
- \index{#2}%
+ \protected at edef\Entry{#2}%
\fi
\fi
+ \ex\index\ex{\Entry}%
\fi
}
\newcommand*\@nameauth at Actual{@}
+\newcommandx*\@nameauth at Debug[3][1=\@empty, 3=\@empty]
+{%
+ \bgroup%
+ \def\index##1{##1}%
+ \@nameauth at DoIndextrue%
+ \protected at edef\arga{\trim at spaces{#1}}%
+ \protected at edef\argc{\trim at spaces{#3}}%
+ \protected at edef\suffb{\@nameauth at Suffix{#2}}%
+ \def\csb{\@nameauth at Clean{#2}}%
+ \def\csbc{\@nameauth at Clean{#2,#3}}%
+ \def\csab{\@nameauth at Clean{#1!#2}}%
+ \@nameauth at Error{#2}{macro \string\@nameauth at Debug}%
+ \ifx\arga\@empty
+ \ifx\argc\@empty
+ \ifdefined\ShortIdxEntry
+ \csundef{\csb!PRE}%
+ \csundef{\csb!TAG}%
+ \csundef{\csb!PN}%
+ \IndexName[#1]{#2}[#3]%
+ \else
+ \ifdefined\LongIdxEntry
+ \csundef{\csb!PN}%
+ \IndexName[#1]{#2}[#3]%
+ \else
+ \csb%
+ \fi
+ \fi
+ \else
+ \ifx\suffb\@empty
+ \ifdefined\ShortIdxEntry
+ \csundef{\csbc!PRE}%
+ \csundef{\csbc!TAG}%
+ \csundef{\csbc!PN}%
+ \IndexName[#1]{#2}[#3]%
+ \else
+ \ifdefined\LongIdxEntry
+ \csundef{\csbc!PN}%
+ \IndexName[#1]{#2}[#3]%
+ \else
+ \csbc%
+ \fi
+ \fi
+ \else
+ \ifdefined\ShortIdxEntry
+ \csundef{\csb!PRE}%
+ \csundef{\csb!TAG}%
+ \csundef{\csb!PN}%
+ \IndexName[#1]{#2}[#3]%
+ \else
+ \ifdefined\LongIdxEntry
+ \csundef{\csb!PN}%
+ \IndexName[#1]{#2}[#3]%
+ \else
+ \csb%
+ \fi
+ \fi
+ \fi
+ \fi
+ \else
+ \ifdefined\ShortIdxEntry
+ \csundef{\csab!PRE}%
+ \csundef{\csab!TAG}%
+ \csundef{\csab!PN}%
+ \IndexName[#1]{#2}[#3]%
+ \else
+ \ifdefined\LongIdxEntry
+ \csundef{\csab!PN}%
+ \IndexName[#1]{#2}[#3]%
+ \else
+ \csab%
+ \fi
+ \fi
+ \fi
+ \global\undef{\LongIdxEntry}%
+ \global\undef{\ShortIdxEntry}%
+ \egroup%
+}
\newcommand*\CapThis{\@nameauth at DoCapstrue}
\newcommand*\AccentCapThis%
{\@nameauth at Accenttrue\@nameauth at DoCapstrue}
@@ -617,6 +743,11 @@
\newcommand*\IndexActual[1]
{\global\renewcommand*\@nameauth at Actual{#1}}
\newcommand*\SeeAlso{\@nameauth at SeeAlsotrue}
+\newcommand*\ShowPattern{\@nameauth at Debug}
+\newcommand*\ShowIdxPageref%
+ {\def\LongIdxEntry{}\ShowPattern}
+\WithSuffix{\newcommand*}\ShowIdxPageref*%
+ {\def\ShortIdxEntry{}\ShowPattern}
\newcommand*\NameParser
{%
\if at nameauth@InHook
@@ -705,6 +836,11 @@
\newcommand\FName{\@nameauth at FirstNametrue\NameauthFName}
\WithSuffix{\newcommand*}\FName*%
{\@nameauth at FirstNametrue\NameauthFName}
+\newcommand*\IndexProtect
+{%
+ \@nameauth at DoIndexfalse%
+ \@nameauth at BigLocktrue%
+}
\newcommandx*\IndexName[3][1=\@empty, 3=\@empty]
{%
\protected at edef\arga{\trim at spaces{#1}}%
@@ -796,9 +932,11 @@
\fi
\else
\if at nameauth@SeeAlso
- \@nameauth at Index{\csb}{\rootb\space\suffb|seealso{\target}}%
+ \@nameauth at Index{\csb}%
+ {\rootb\space\suffb|seealso{\target}}%
\else
- \@nameauth at Index{\csb}{\rootb\space\suffb|see{\target}}%
+ \@nameauth at Index{\csb}%
+ {\rootb\space\suffb|see{\target}}%
\fi
\fi
\csgdef{\csb!PN}{}%
@@ -865,8 +1003,12 @@
\csgdef{\csab!PN}{}%
\fi
\fi
- \@nameauth at SeeAlsofalse%
\@nameauth at Xreffalse%
+ \if at nameauth@OldReset
+ \@nameauth at SeeAlsofalse%
+ \else
+ \global\@nameauth at SeeAlsofalse%
+ \fi
}
\newcommandx*\ExcludeName[3][1=\@empty, 3=\@empty]
{%
@@ -913,7 +1055,7 @@
\ifcsname\csbc!PN\endcsname
\if at nameauth@Verbose
\PackageWarning{nameauth}%
- {macro \ExcludeName: Xref: #2 exists}%
+ {macro \ExcludeName: Xref: #2 #3 exists}%
\fi
\else
\csgdef{\csbc!PN}{!}%
@@ -953,7 +1095,7 @@
\ifcsname\csab!PN\endcsname
\if at nameauth@Verbose
\PackageWarning{nameauth}%
- {macro \ExcludeName: Xref: #2 exists}%
+ {macro \ExcludeName: Xref: #1 #2 exists}%
\fi
\else
\csgdef{\csab!PN}{!}%
@@ -973,18 +1115,36 @@
\ifx\argc\@empty
\ifcsname\csb!PN\endcsname
\edef\testex{\csname\csb!PN\endcsname}%
- \unless\ifx\testex\@empty\global\csundef{\csb!PN}\fi
+ \unless\ifx\testex\@empty\global\csundef{\csb!PN}%
+ \else
+ \if at nameauth@Verbose
+ \PackageWarning{nameauth}%
+ {macro \IncludeName: Xref: #2 exists}%
+ \fi
+ \fi
\fi
\else
\ifx\suffb\@empty
\ifcsname\csbc!PN\endcsname
\edef\testex{\csname\csbc!PN\endcsname}%
- \unless\ifx\testex\@empty\global\csundef{\csbc!PN}\fi
+ \unless\ifx\testex\@empty\global\csundef{\csbc!PN}%
+ \else
+ \if at nameauth@Verbose
+ \PackageWarning{nameauth}%
+ {macro \IncludeName: Xref: #2 #3 exists}%
+ \fi
+ \fi
\fi
\else
\ifcsname\csb!PN\endcsname
\edef\testex{\csname\csb!PN\endcsname}%
- \unless\ifx\testex\@empty\global\csundef{\csb!PN}\fi
+ \unless\ifx\testex\@empty\global\csundef{\csb!PN}%
+ \else
+ \if at nameauth@Verbose
+ \PackageWarning{nameauth}%
+ {macro \IncludeName: Xref: #2 exists}%
+ \fi
+ \fi
\fi
\fi
\fi
@@ -991,7 +1151,13 @@
\else
\ifcsname\csab!PN\endcsname
\edef\testex{\csname\csab!PN\endcsname}%
- \unless\ifx\testex\@empty\global\csundef{\csab!PN}\fi
+ \unless\ifx\testex\@empty\global\csundef{\csab!PN}%
+ \else
+ \if at nameauth@Verbose
+ \PackageWarning{nameauth}%
+ {macro \IncludeName: Xref: #1 #2 exists}%
+ \fi
+ \fi
\fi
\fi
}
@@ -1170,19 +1336,21 @@
\def\csb{\@nameauth at Clean{#2}}%
\def\csbc{\@nameauth at Clean{#2,#3}}%
\def\csab{\@nameauth at Clean{#1!#2}}%
- \@nameauth at Error{#2}{macro \string\NameQueryInfo}%
- \ifx\arga\@empty
- \ifx\argc\@empty
- \ifcsname\csb!DB\endcsname\csname\csb!DB\endcsname\fi
- \else
- \ifx\Suff\@empty
- \ifcsname\csbc!DB\endcsname\csname\csbc!DB\endcsname\fi
+ \unless\if at nameauth@BigLock
+ \@nameauth at Error{#2}{macro \string\NameQueryInfo}%
+ \ifx\arga\@empty
+ \ifx\argc\@empty
+ \ifcsname\csb!DB\endcsname\csname\csb!DB\endcsname\fi
\else
- \ifcsname\csb!DB\endcsname\csname\csb!DB\endcsname\fi
+ \ifx\Suff\@empty
+ \ifcsname\csbc!DB\endcsname\csname\csbc!DB\endcsname\fi
+ \else
+ \ifcsname\csb!DB\endcsname\csname\csb!DB\endcsname\fi
+ \fi
\fi
+ \else
+ \ifcsname\csab!DB\endcsname\csname\csab!DB\endcsname\fi
\fi
- \else
- \ifcsname\csab!DB\endcsname\csname\csab!DB\endcsname\fi
\fi
}
\newcommandx*\NameClearInfo[3][1=\@empty, 3=\@empty]
@@ -1409,48 +1577,69 @@
}
\newcommandx*\AKA[5][1=\@empty, 3=\@empty, 5=\@empty]
{%
+ \if at nameauth@BigLock\@nameauth at Locktrue\fi
\unless\if at nameauth@Lock
- \@nameauth at Locktrue%
- \@nameauth at JustIndexfalse%
- \@nameauth at InAKAtrue%
- \@nameauth at Error{#2}{macro \string\AKA}%
- \@nameauth at Error{#4}{macro \string\AKA}%
- \leavevmode\hbox{}%
- \protected at edef\argi{\trim at spaces{#1}}%
- \protected at edef\rooti{\@nameauth at Root{#2}}%
- \protected at edef\suffi{\@nameauth at Suffix{#2}}%
- \@nameauth at Parse[#3]{#4}[#5]{!PN}%
- \unless\if at nameauth@SkipIndex
- \ifx\argi\@empty
- \ifx\suffi\@empty
- \IndexRef[#3]{#4}[#5]{\rooti}%
- \else
- \IndexRef[#3]{#4}[#5]{\rooti\space\suffi}%
- \fi
+ \@nameauth at Locktrue%
+ \@nameauth at InAKAtrue%
+ \if at nameauth@OldReset
+ \@nameauth at JustIndexfalse%
\else
- \ifx\suffi\@empty
- \IndexRef[#3]{#4}[#5]{\rooti,\space\argi}%
+ \global\@nameauth at JustIndexfalse%
+ \fi
+ \@nameauth at Error{#2}{macro \string\AKA}%
+ \@nameauth at Error{#4}{macro \string\AKA}%
+ \leavevmode\hbox{}%
+ \protected at edef\argi{\trim at spaces{#1}}%
+ \protected at edef\rooti{\@nameauth at Root{#2}}%
+ \protected at edef\suffi{\@nameauth at Suffix{#2}}%
+ \@nameauth at Parse[#3]{#4}[#5]{!PN}%
+ \unless\if at nameauth@SkipIndex
+ \ifx\argi\@empty
+ \ifx\suffi\@empty
+ \IndexRef[#3]{#4}[#5]{\rooti}%
+ \else
+ \IndexRef[#3]{#4}[#5]{\rooti\space\suffi}%
+ \fi
\else
- \IndexRef[#3]{#4}[#5]{\rooti,\space\argi,\space\suffi}%
+ \ifx\suffi\@empty
+ \IndexRef[#3]{#4}[#5]{\rooti,\space\argi}%
+ \else
+ \IndexRef[#3]{#4}[#5]{\rooti,\space\argi,\space\suffi}%
+ \fi
\fi
\fi
+ \if at nameauth@OldReset
+ \@nameauth at SkipIndexfalse%
+ \@nameauth at AltAKAfalse%
+ \@nameauth at NBSPfalse%
+ \@nameauth at NBSPXfalse%
+ \@nameauth at DoCapsfalse%
+ \@nameauth at Accentfalse%
+ \@nameauth at AllThisfalse%
+ \@nameauth at ShowCommafalse%
+ \@nameauth at NoCommafalse%
+ \@nameauth at RevThisfalse%
+ \@nameauth at RevThisCommafalse%
+ \@nameauth at ShortSNNfalse%
+ \@nameauth at EastFNfalse%
+ \else
+ \global\@nameauth at SkipIndexfalse%
+ \global\@nameauth at AltAKAfalse%
+ \global\@nameauth at NBSPfalse%
+ \global\@nameauth at NBSPXfalse%
+ \global\@nameauth at DoCapsfalse%
+ \global\@nameauth at Accentfalse%
+ \global\@nameauth at AllThisfalse%
+ \global\@nameauth at ShowCommafalse%
+ \global\@nameauth at NoCommafalse%
+ \global\@nameauth at RevThisfalse%
+ \global\@nameauth at RevThisCommafalse%
+ \global\@nameauth at ShortSNNfalse%
+ \global\@nameauth at EastFNfalse%
+ \fi
+ \@nameauth at Lockfalse%
+ \@nameauth at InAKAfalse%
\fi
- \@nameauth at SkipIndexfalse%
- \@nameauth at Lockfalse%
- \@nameauth at InAKAfalse%
- \@nameauth at AltAKAfalse%
- \@nameauth at NBSPfalse%
- \@nameauth at NBSPXfalse%
- \@nameauth at DoCapsfalse%
- \@nameauth at Accentfalse%
- \@nameauth at AllThisfalse%
- \@nameauth at ShowCommafalse%
- \@nameauth at NoCommafalse%
- \@nameauth at RevThisfalse%
- \@nameauth at RevThisCommafalse%
- \@nameauth at ShortSNNfalse%
- \@nameauth at EastFNfalse%
- \fi
\if at nameauth@Punct\expandafter\@nameauth at CheckDot\fi
}
\WithSuffix{\newcommand*}\AKA*{\@nameauth at AltAKAtrue\AKA}
@@ -1482,78 +1671,86 @@
\ifcsname\@arga\endcsname
\PackageWarning{nameauth}%
{environment nameauth: Shorthand macro already exists}%
- \fi
- \ifx\@testd\@empty
+ \fi
+ \ifx\@testd\@empty
\ifx\@testb\@empty
- \ex\csgdef\ex{\ex\@arga\ex}\ex{\ex\NameauthName\ex{%
- \the\@nameauth at etoksc}}%
- \ex\csgdef\ex{\ex L\ex\@arga\ex}\ex{%
- \ex\@nameauth at FullNametrue%
+ \ex\csgdef\ex{\ex\@arga\ex}%
+ \ex{\ex\NameauthName\ex{\the\@nameauth at etoksc}}%
+ \ex\csgdef\ex{\ex L\ex\@arga\ex}%
+ \ex{\ex\@nameauth at FullNametrue%
\ex\NameauthLName\ex{\the\@nameauth at etoksc}}%
- \ex\csgdef\ex{\ex S\ex\@arga\ex}\ex{%
- \ex\@nameauth at FirstNametrue%
+ \ex\csgdef\ex{\ex S\ex\@arga\ex}%
+ \ex{\ex\@nameauth at FirstNametrue%
\ex\NameauthFName\ex{\the\@nameauth at etoksc}}%
\else
\ex\ex\ex\csgdef\ex\ex\ex{\ex\ex\ex\@arga\ex\ex\ex}%
- \ex\ex\ex{\ex\ex\ex\NameauthName\ex\ex\ex[%
- \ex\the\ex\@nameauth at etoksb\ex]\ex{\the\@nameauth at etoksc}}%
+ \ex\ex\ex{\ex\ex\ex\NameauthName%
+ \ex\ex\ex[\ex\the\ex\@nameauth at etoksb\ex]%
+ \ex{\the\@nameauth at etoksc}}%
\ex\ex\ex\csgdef\ex\ex\ex{\ex\ex\ex L\ex\ex\ex\@arga%
\ex\ex\ex}\ex\ex\ex{\ex\ex\ex\@nameauth at FullNametrue%
- \ex\ex\ex\NameauthLName\ex\ex\ex[%
- \ex\the\ex\@nameauth at etoksb\ex]\ex{\the\@nameauth at etoksc}}%
+ \ex\ex\ex\NameauthLName%
+ \ex\ex\ex[\ex\the\ex\@nameauth at etoksb\ex]%
+ \ex{\the\@nameauth at etoksc}}%
\ex\ex\ex\csgdef\ex\ex\ex{\ex\ex\ex S\ex\ex\ex\@arga%
\ex\ex\ex}\ex\ex\ex{\ex\ex\ex\@nameauth at FirstNametrue%
- \ex\ex\ex\NameauthFName\ex\ex\ex[%
- \ex\the\ex\@nameauth at etoksb\ex]\ex{\the\@nameauth at etoksc}}%
+ \ex\ex\ex\NameauthFName%
+ \ex\ex\ex[\ex\the\ex\@nameauth at etoksb\ex]%
+ \ex{\the\@nameauth at etoksc}}%
\fi
\else
\ifx\@testb\@empty
\ex\ex\ex\csgdef\ex\ex\ex{\ex\ex\ex\@arga\ex\ex\ex}%
- \ex\ex\ex{\ex\ex\ex\NameauthName\ex\ex\ex{%
- \ex\the\ex\@nameauth at etoksc\ex}\ex[\the\@nameauth at etoksd]}%
+ \ex\ex\ex{\ex\ex\ex\NameauthName%
+ \ex\ex\ex{\ex\the\ex\@nameauth at etoksc\ex}%
+ \ex[\the\@nameauth at etoksd]}%
\ex\ex\ex\csgdef\ex\ex\ex{\ex\ex\ex L\ex\ex\ex\@arga%
\ex\ex\ex}\ex\ex\ex{\ex\ex\ex\@nameauth at FullNametrue%
- \ex\ex\ex\NameauthLName\ex\ex\ex{%
- \ex\the\ex\@nameauth at etoksc\ex}\ex[\the\@nameauth at etoksd]}%
+ \ex\ex\ex\NameauthLName%
+ \ex\ex\ex{\ex\the\ex\@nameauth at etoksc\ex}%
+ \ex[\the\@nameauth at etoksd]}%
\ex\ex\ex\csgdef\ex\ex\ex{\ex\ex\ex S\ex\ex\ex\@arga%
\ex\ex\ex}\ex\ex\ex{\ex\ex\ex\@nameauth at FirstNametrue%
- \ex\ex\ex\NameauthFName\ex\ex\ex{%
- \ex\the\ex\@nameauth at etoksc\ex}\ex[\the\@nameauth at etoksd]}%
+ \ex\ex\ex\NameauthFName%
+ \ex\ex\ex{\ex\the\ex\@nameauth at etoksc\ex}%
+ \ex[\the\@nameauth at etoksd]}%
\else
\ex\ex\ex\ex\ex\ex\ex\csgdef\ex\ex\ex\ex\ex\ex\ex{%
\ex\ex\ex\ex\ex\ex\ex\@arga\ex\ex\ex\ex\ex\ex\ex}%
\ex\ex\ex\ex\ex\ex\ex{\ex\ex\ex\ex\ex\ex\ex\NameauthName%
- \ex\ex\ex\ex\ex\ex\ex[\ex\ex\ex\the\ex\ex\ex\@nameauth at etoksb%
- \ex\ex\ex]\ex\ex\ex{\ex\the\ex\@nameauth at etoksc\ex}\ex[%
- \the\@nameauth at etoksd]}%
+ \ex\ex\ex\ex\ex\ex\ex[\ex\ex\ex\the%
+ \ex\ex\ex\@nameauth at etoksb\ex\ex\ex]%
+ \ex\ex\ex{\ex\the\ex\@nameauth at etoksc\ex}%
+ \ex[\the\@nameauth at etoksd]}%
\ex\ex\ex\ex\ex\ex\ex\csgdef\ex\ex\ex\ex\ex\ex\ex{%
\ex\ex\ex\ex\ex\ex\ex L\ex\ex\ex\ex\ex\ex\ex\@arga%
\ex\ex\ex\ex\ex\ex\ex}\ex\ex\ex\ex\ex\ex\ex{%
\ex\ex\ex\ex\ex\ex\ex\@nameauth at FullNametrue%
- \ex\ex\ex\ex\ex\ex\ex\NameauthLName\ex\ex\ex\ex\ex\ex\ex[%
- \ex\ex\ex\the\ex\ex\ex\@nameauth at etoksb%
- \ex\ex\ex]\ex\ex\ex{\ex\the\ex\@nameauth at etoksc\ex}\ex[%
- \the\@nameauth at etoksd]}%
+ \ex\ex\ex\ex\ex\ex\ex\NameauthLName%
+ \ex\ex\ex\ex\ex\ex\ex[\ex\ex\ex\the\ex\ex\ex%
+ \@nameauth at etoksb\ex\ex\ex]%
+ \ex\ex\ex{\ex\the\ex\@nameauth at etoksc\ex}%
+ \ex[\the\@nameauth at etoksd]}%
\ex\ex\ex\ex\ex\ex\ex\csgdef\ex\ex\ex\ex\ex\ex\ex{%
\ex\ex\ex\ex\ex\ex\ex S\ex\ex\ex\ex\ex\ex\ex\@arga%
\ex\ex\ex\ex\ex\ex\ex}\ex\ex\ex\ex\ex\ex\ex{%
\ex\ex\ex\ex\ex\ex\ex\@nameauth at FirstNametrue%
- \ex\ex\ex\ex\ex\ex\ex\NameauthFName\ex\ex\ex\ex\ex\ex\ex[%
- \ex\ex\ex\the\ex\ex\ex\@nameauth at etoksb\ex\ex\ex]%
- \ex\ex\ex{\ex\the\ex\@nameauth at etoksc\ex}\ex[%
- \the\@nameauth at etoksd]}%
+ \ex\ex\ex\ex\ex\ex\ex\NameauthFName%
+ \ex\ex\ex\ex\ex\ex\ex[\ex\ex\ex\the\ex\ex\ex%
+ \@nameauth at etoksb\ex\ex\ex]%
+ \ex\ex\ex{\ex\the\ex\@nameauth at etoksc\ex}%
+ \ex[\the\@nameauth at etoksd]}%
\fi
- \fi
- \ignorespaces%
+ \fi\ignorespaces%
}\ignorespaces%
}{\endgroup\ignorespaces}
%%
-%% Copyright (C) 2017 by Charles P. Schaum <charles dot schaum at comcast dot net>
+%% Copyright (C) 2020 by Charles P. Schaum <charles dot schaum at comcast.net>
%%
-%% This work may be distributed and/or modified under the
+%% This work may be distributed and / or modified under the
%% conditions of the LaTeX Project Public License (LPPL), either
%% version 1.3c of this license or (at your option) any later
-%% version. The latest version of this license is in the file:
+%% version. The latest version of this license is in the file:
%%
%% http://www.latex-project.org/lppl.txt
%%
@@ -1561,9 +1758,8 @@
%% Charles P. Schaum.
%%
%% 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.
-%%
+%% These files generate README.txt / README, nameauth.ins, nameauth.sty, and
+%% nameauth.pdf, with other intermediate files, as a part of this work. See
+%% the README.txt or README for more information.
%%
%% End of file `nameauth.sty'.
More information about the tex-live-commits
mailing list.