summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/nameauth/nameauth.dtx
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2023-02-04 21:13:12 +0000
committerKarl Berry <karl@freefriends.org>2023-02-04 21:13:12 +0000
commit7f290ee226dfa7f4d24222946b79b3ab76037076 (patch)
tree51db40a79871d52df3f135639aee73de6d51d091 /Master/texmf-dist/source/latex/nameauth/nameauth.dtx
parentbc036b1a7bbed0b49ebef40170780e98435f0c71 (diff)
nameauth (4feb23)
git-svn-id: svn://tug.org/texlive/trunk@65731 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/source/latex/nameauth/nameauth.dtx')
-rw-r--r--Master/texmf-dist/source/latex/nameauth/nameauth.dtx18373
1 files changed, 11312 insertions, 7061 deletions
diff --git a/Master/texmf-dist/source/latex/nameauth/nameauth.dtx b/Master/texmf-dist/source/latex/nameauth/nameauth.dtx
index f755e23dd3f..7dbbbe7712e 100644
--- a/Master/texmf-dist/source/latex/nameauth/nameauth.dtx
+++ b/Master/texmf-dist/source/latex/nameauth/nameauth.dtx
@@ -1,6 +1,6 @@
% \iffalse meta-comment
%
-% Copyright (C) 2021 by Charles P. Schaum <charles[dot]schaum@comcast.net>
+% Copyright (C) 2023 by Charles P. Schaum <charles[dot]schaum@comcast.net>
% -------------------------------------------------------
%
% This file may be distributed and/or modified under the
@@ -18,164 +18,467 @@
%</internal>
%<*readme>
%<<readmevb
-# Short Description
+# 1. Short Description
-The `nameauth` package automates the correct formatting and indexing of names
-for professional writing. This aids the use of a name authority and the
-editing process without needing to retype name references.
+The `nameauth` package automates the correct formatting and indexing of names for professional writing. This aids the use of a name authority and the editing process without needing to retype name references.
-# Files
+# 2. Files in Zip Archive
-|Filename |Description |
-|--------------|---------------------------------------|
-|`nameauth.dtx`|commented style file; source file |
-|`Makefile` |For use with GNU make; with source file|
-|`nameauth.ins`|installation driver (generated file) |
-|`nameauth.sty`|style file (generated file) |
-|`nameauth.pdf`|Documentation (generated file) |
-|`README.md` |This file (generated file) |
-|`examples.tex`|example macros (generated file) |
+The following files are included in the archive that is uploaded to CTAN:
-# Obtaining the Package
+| Filename | Description |
+| :------------- | :------------------------- |
+| `Makefile` | for use with GNU make |
+| `cat01.pdf` | manual illustration, ch. 7 |
+| `beamer01.pdf` | manual illustration, ch. 9 |
+| `beamer02.pdf` | manual illustration, ch. 9 |
+| `beamer03.pdf` | manual illustration, ch. 9 |
+| `nameauth.dtx` | commented macro file |
+| `compat.tex` | compatibility module |
+| `examples.tex` | example file |
+| `nameauth.pdf` | package documentation |
+| `README.md` | this file |
-1. Packaged in your current TeX distrbution: See the appropriate documentation.
+# 3. Installing a Distro Package
-2. Otherwise, download `nameauth.zip` from [CTAN](http://mirrors.ctan.org/macros/latex/contrib/nameauth.zip).
+One can find `nameauth` in one's current TeX distribution. See the appropriate documentation in TeXlive, MikTeX, MacTeX, Linux distro, BSD, etc. Use those tools to ensure that `nameauth` is installed. You are done.
-3. Unpack `nameauth.zip` in an appropriate directory.
+# 4. Installing from CTAN
-4. Change to the directory containing the `nameauth` files.
+## 4.1 Getting the Package Archive
-# File Generation
+If not using the tools above, one can download `nameauth.zip` from [CTAN](https://mirrors.ctan.org/macros/latex/contrib/nameauth.zip). After downloading, unpack `nameauth.zip` in an appropriate directory. Change to the directory containing the supplied files.
-## Automatic Installation
+## 4.2 Using GNU make
-This method requires GNU `make` on a POSIX-compliant environment, such as GNU/Linux, various BSD flavors, perhaps MacOS (e.g., with various porting systems), and even Cygwin on Windows.
+### 4.2.1 Read the File
- * We use the LaTeX installation on the host machine to build the package. When using `make`, any `dvi` files that are created will also be converted to `pdf` format.
+**Please inspect the included `Makefile` before using it.**
-1. Type `make` to generate the release files using `pdflatex`.
+`Makefile` has an extensive comment on usage, as well as many other comments. This file lists all the programs that must be installed in order to use GNU make file, helping one to check for prerequisites and dependencies. This method is designed for a POSIX-compliant environment, such as GNU/Linux, various BSDs, MacOS, and WSL or Cygwin on Windows.
-2. To use another LaTeX engine, type one of the following:
+### 4.2.2 Prepare to Install, No Building
- make ENGINE=xelatex
- make ENGINE=lualatex
- make ENGINE=dvilualatex
- make ENGINE=latex
+One does not need to build `nameauth` completely from source (although it may be a good idea to do a native build). If the provided files are sufficient, one can type:
-3. Type `make inst` to install the files in the user's personal TDS-compliant directory tree.
+ make unpack
-4. Type `sudo make install` to install the files in the system-wide, local TDS-compliant directory tree.
+This target only unpack the supplied generated files from `nameauth.dtx`. It does not try to create the documentation. One will have the following files now:
-5. One can include multiple make targets on the command line, but that goes beyond the scope of this document and is intended for experienced users.
+| Filename | Description | TDS-where to |
+| :------------- | :------------------------- | :----------- |
+| `Makefile` | for use with GNU make | source dir |
+| `cat01.pdf` | manual illustration, ch. 7 | source dir |
+| `beamer01.pdf` | manual illustration, ch. 9 | source dir |
+| `beamer02.pdf` | manual illustration, ch. 9 | source dir |
+| `beamer03.pdf` | manual illustration, ch. 9 | source dir |
+| `nameauth.dtx` | commented macro file | source dir |
+| | | |
+| `nameauth.ins` | installation driver | unneeded |
+| | | |
+| `compat.tex` | compatibility module | doc dir |
+| `examples.tex` | example file | doc dir |
+| `nameauth.pdf` | package documentation | doc dir |
+| `README.md` | this file | doc dir |
+| | | |
+| `nameauth.sty` | style file | package dir |
-## Manual Compilation
+Take a look at **4.2.3 Specific Build Cases** and, depending on the use case, skip either to **4.2.5 Installation** (using make) or **4.3.3 Installation Prerequisites** (manual) below.
-Otherwise, the following steps are used for manual installation. See the general information at the [TeX FAQ](https://www.texfaq.org/FAQ-installthings).
+### 4.2.3 Specific Build Cases: Program Extensions
-1. To build the package on the host system, generate the installation files and a copy of the documentation without the table of contents and cross-references. We use `pdflatex` by default:
+Windows presents some interesting cases. Both Cygwin and WSL provide POSIX environments that include respective TeX distros of their own. Yet they also will operate with native Windows-based TeX distros like MiokTeX and TeXlive.
- pdflatex --shell-escape --recorder --interaction=batchmode nameauth.dtx
+When using the TeX distros built in to Cygwin and WSL exclusively, one can treat it basically as a POSIX-compliant environment.
-2. This will generate the following files:
+Even when using Cygwin and a Windows-based TeX distro, one can treat package building as being mostly the same as a POSIX environment if all the preqequisite programs are installed. Installation, however, must be manual.
- nameauth.ins (complete)
- nameauth.sty (complete)
- nameauth.pdf (incomplete; do steps 3 through 5)
- README.md (complete)
- examples.tex (complete)
+When one uses WSL with a Windows-based TeX distro, the `Makefile` will test whether an ".exe" extension is needed by the programs used in the building process.
-3. Generate the TOC and cross-references for the documentation:
+With both Cygwin and WSL, tests will determine if the standard POSIX method is capable of installing and packaging as intended, or if manual methods are needed.
- pdflatex --recorder --interaction=nonstopmode nameauth.dtx
+* Make will test if `ltxfileinfo` exists. If not, it will produce a zip file with just the package base name to avoid problems that otherwise could arise in Windows.
-4. Generate the index files using `makeindex`:
+* Make will test if `dvipdf` from Ghostscript is installed and use that. Otherwise it will fall back to `dvipdfmx`.
- makeindex -q -s gglo.ist -o nameauth.gls nameauth.glo
- makeindex -q -s gind.ist -o nameauth.ind nameauth.idx
+* Make will test if `pdfjam` is installed, if one needs to remake the manual illustrations. Otherwise, it will advise on how to do that manually.
-5. Integrate the glossary (changes) and index into the documentation. The second run updates the TOC:
+* Make will try to see if the path to the desired install directory exists. If it does not, make will produce an error message and exit. If this happens, which is likely under Windows, please refer to installation of local packages in MikTeX [here](https://docs.miktex.org/manual/localadditions.html#id573803) and [here](https://miktex.org/kb/texmf-roots). Otherwise see the [TeX FAQ](https://www.texfaq.org/FAQ-privinst) and [this page](https://en.wikibooks.org/wiki/LaTeX/Installing_Extra_Packages).
- pdflatex --recorder --interaction=nonstopmode nameauth.dtx
- pdflatex --recorder --interaction=nonstopmode nameauth.dtx
+Here is a table showing the feasibility of a few scenarios:
-One can substitute, e.g., `xelatex`, `lualatex`, `dvilualatex`, and `latex`, for `pdflatex`, but the documentation may look different in some cases.
+| Platform | TeX Distro Platform | Build package and zip with make | Install package with make |
+| :------- | :------------------------ | :------------------------------ | :------------------------------ |
+| POSIX | POSIX | Yes<sup>1</sup> | Yes |
+| Cygwin | Cygwin (distro packages) | Not tested; likely<sup>1</sup> | Not tested; likely <sup>2</sup> |
+| Cygwin | MikTeX (Windows) | Yes<sup>1, 3</sup> | No;<sup>4</sup> do manually |
+| Cygwin | TeXlive (Windows) | Not tested; likely<sup>1</sup> | Not tested; do manually |
+| Cygwin | Both Cygwin and Windows | Not tested; not recommended | Not tested; not recommended |
+| WSL | WSL Linux distro packages | Yes<sup>1</sup> | Yes<sup>5</sup> |
+| WSL | MikTeX (Windows) | Yes<sup>1, 3</sup> | No;<sup>4</sup> do manually |
+| WSL | TeXlive (Windows) | Not tested; likely<sup>1</sup> | Not tested; do manually |
+| WSL | Both WSL and Windows | Not tested; not recommended | Not tested; not recommended |
+| WSL/Cyg | Both WSL and Cygwin | Not tested; not recommended | Not tested; not recommended |
+| GNUWin | any (Windows) | Not tested; not recommended | Not tested; not recommended |
-## Manual File Installation
+<sup>1</sup> All dependencies must be met. Bear in mind MacOS quirks.
-Different TeX distributions have somewhat different ways to store TDS-compliant configuration and package data. See, for example, [MikTeX](https://miktex.org/kb/texmf-roots) and the [TeX FAQ](https://www.texfaq.org/FAQ-privinst). Two approaches below conform generally to a Unix-based system:
+<sup>2</sup> Installs only to Cygwin environment; not to Windows environment.
-## User's Home Directory
+<sup>3</sup> If one attempts the `make images` target, it is unlikely that `pdfjam` will work; one must create pdf page examples included in the manual by compiling the appropriate test files and extracting the pages using a different app.
-`TEXMFHOME` is a variable that points to the root of a TDS-compliant directory tree available to a user. Use `kpsewhich --var-value TEXMFHOME` to obtain its value. Quite often it is equivalent to `$HOME/texmf`. The dollar sign in front of the variable denotes the value of the variable instead of its name. So if `$HOME` is `/home/bob`, then `$TEXMFHOME` would be `/home/bob/texmf`, and we can understand the following paths to be under that directory:
+<sup>4</sup> Neither `ltxfileinfo` nor `kpsewhich` will give useful results; do a manual install.
-|Path |Description |
-|----------------------------------|----------------------------------------|
-|`$TEXMFHOME/source/latex/nameauth`|`ins` and `dtx` files, Makefile |
-|`$TEXMFHOME/tex/latex/nameauth` |`sty` file |
-|`$TEXMFHOME/doc/latex/nameauth` |`pdf` file, `README.md`, `examples.tex` |
+<sup>5</sup> Installs only to WSL Linux distro environment; not to Windows environment.
-On older TeX distributions, run `mktexlsr` on $TEXMFHOME to complete the install process.
+### 4.2.4 Building the Package
-## System-Wide Directory
+In the directory where the files unpacked from the zip archive are located, type `make`. This will do a fresh build of the package using `pdflatex`.
-`TEXMFLOCAL` is a variable that points to the root of a TDS-compliant directory tree available to all users on a local site, system-wide installation. Use `kpsewhich --var-value TEXMFLOCAL` to obtain its value. See the [TeX FAQ](https://www.texfaq.org/FAQ-what-TDS). We can understand the following paths to be under that directory:
+### 4.2.5 Installation
-|Path |Description |
-|-----------------------------------|----------------------------------------|
-|`$TEXMFLOCAL/source/latex/nameauth`|`ins` and `dtx` files, Makefile |
-|`$TEXMFLOCAL/tex/latex/nameauth` |`sty` file |
-|`$TEXMFLOCAL/doc/latex/nameauth` |`pdf` file, `README.md`, `examples.tex` |
+The user must already have a TDS-compliant tree set up in order for installation to work. Thus, one must have created a `texmf` directory to which TEXMFHOME refers, if in a POSIX environment, or have the equivalent in another environment. Currently, `Makefile` only installs into POSIX environments.
-Run `mktexlsr` with the appropriate permissions on `$TEXMFLOCAL` to complete the install process.
+Assuming that one has a use case where one can use GNU make, one can choose the following:
-# Testing
+* Type `make inst` to install the package files in the user's personal TDS-compliant directory tree.
-## Compiling `examples.tex`
+* Type `make install` to install the package files in the system-wide, local TDS-compliant directory tree. The user will be prompted for the `sudo` password.
+
+ If, for some reason, this fails, do a manual install (below).
+
+Note that these make targets depend on `package`, which does not do a clean build. To ensure a clean build, use `make release inst` or `make release install`.
+
+### 4.2.6 Removal
+
+The same constraints that apply to installation also apply to removal. If one can do the former, one can do the latter.
+
+* Type `make uninst` to remove the package files in the user's personal TDS-compliant directory tree.
+
+* Type `make uninstall` to remove the package files in the system-wide, local TDS-compliant directory tree. The user will be prompted for the `sudo` password.
+
+ If, for some reason, this fails, do a manual removal (opposite of steps used below).
+
+The approach of `Makefile` is not to get too aggressive with deletions from the texmf tree, just in case. One may see harmless, extra empty directories after removal.
+
+## 4.3 Manual Method
+
+Unlike when using GNU make, which automates adding extensions, in the case of working with WSL together with native Windows TeX distros, in the command lines below there may be certain cases where one may have to add the ".exe" extension to the programs. Those cases should, however, be few.
+
+### 4.3.1 Prepare to Install, No Building
+
+One does not need to build `nameauth` completely from source (although it may be a good idea to do a native build). If the provided files are sufficient, one can type:
+
+ pdftex nameauth.dtx
+
+This only unpacks the supplied generated files from `nameauth.dtx`. It does not try to create the documentation. One will have the following files now:
+
+| Filename | Description | TDS-where to |
+| :------------- | :------------------------- | :----------- |
+| `Makefile` | for use with GNU make | source dir |
+| `cat01.pdf` | manual illustration, ch. 7 | source dir |
+| `beamer01.pdf` | manual illustration, ch. 9 | source dir |
+| `beamer02.pdf` | manual illustration, ch. 9 | source dir |
+| `beamer03.pdf` | manual illustration, ch. 9 | source dir |
+| `nameauth.dtx` | commented macro file | source dir |
+| | | |
+| `nameauth.ins` | installation driver | unneeded |
+| | | |
+| `compat.tex` | compatibility module | doc dir |
+| `examples.tex` | example file | doc dir |
+| `nameauth.pdf` | package documentation | doc dir |
+| `README.md` | this file | doc dir |
+| | | |
+| `nameauth.sty` | style file | package dir |
+
+One may skip past building to **4.3.3 Installation Prerequisites** below.
+
+### 4.3.2 Building the Package
+
+1. Using the unpacked files from the zip archive, we begin by creating the installation driver, unpacking additional files from `nameauth.dtx`, and generating a copy of the documentation without the table of contents and cross-references:
+
+ pdflatex --shell-escape --recorder --interaction=batchmode nameauth.dtx
+
+ Now we should have the following files:
+
+| Filename | Description |
+| :------------- | :--------------------------- |
+| `Makefile` | for use with GNU make |
+| `cat01.pdf` | manual illustration, ch. 7 |
+| `beamer01.pdf` | manual illustration, ch. 9 |
+| `beamer02.pdf` | manual illustration, ch. 9 |
+| `beamer03.pdf` | manual illustration, ch. 9 |
+| `nameauth.dtx` | commented style file |
+| | |
+| `compat.tex` | compatibility module |
+| `examples.tex` | example file |
+| `nameauth.pdf` | package documentation |
+| `README.md` | this file |
+| | |
+| `nameauth.ins` | installation driver |
+| `nameauth.sty` | style file |
+
+ In addition, we have the following temporary files:
+
+| Filename | Description |
+| :------------- | :--------------------------- |
+| `nameauth.aux` | auxiliary file |
+| `nameauth.fls` | shows files read |
+| `nameauth.glo` | raw glossary entries |
+| `nameauth.hd ` | |
+| `nameauth.idx` | raw index entries |
+| `nameauth.log` | log file |
+| `nameauth.out` | pdf bookmark/hypertext info |
+| `nameauth.tmp` | temp file used with fancyvrb |
+| `nameauth.toc` | table of contents info |
+
+2. Generate the TOC and cross-references within the documentation:
+
+ pdflatex --recorder --interaction=nonstopmode nameauth.dtx
+
+3. Generate the index and glossary files using `makeindex`:
+
+ makeindex -q -s gglo.ist -o nameauth.gls nameauth.glo
+ makeindex -q -s gind.ist -o nameauth.ind nameauth.idx
+
+ This adds the following files:
+
+| Filename | Description |
+| :------------- | :----------------------- |
+| `nameauth.gls` | typeset glossary entries |
+| `nameauth.ilg` | `makeindex` log file |
+| `nameauth.ind` | typeset index entries |
+
+4. Integrate the glossary (list of changes) and index into the documentation. The second run updates the TOC:
+
+ pdflatex --recorder --interaction=nonstopmode nameauth.dtx
+ pdflatex --recorder --interaction=nonstopmode nameauth.dtx
+
+### 4.3.3 Installation Prerequisites
+
+In order to perform manual installation, one should be familiar with the general information at the [TeX FAQ](https://www.texfaq.org/FAQ-installthings).
+
+Different TeX distributions have somewhat different ways to store TDS-compliant configuration and package data. See, for example, for MikTeX [here](https://docs.miktex.org/manual/localadditions.html#id573803) and [here](https://miktex.org/kb/texmf-roots). Otherwise see the [TeX FAQ](https://www.texfaq.org/FAQ-privinst) and [this page](https://en.wikibooks.org/wiki/LaTeX/Installing_Extra_Packages).
+
+The instructions below conform generally to a Unix-based system. There are some cases under Windows where this method may not work. For other systems, please consult the appropriate documentation as needed.
+
+The user must already have a TDS-compliant tree set up in order for installation to work. We assume that one knows how to become superuser, create directories, move files, and the like.
+
+### 4.3.4 User's Home Directory
+
+`TEXMFHOME` is a variable that points to the root of a TDS-compliant directory tree available to a user. To get its value on POSIX-compliant systems, use:
+
+ kpsewhich --var-value TEXMFHOME
+
+Quite often, `$TEXMFHOME` is equivalent to `$HOME/texmf`. The dollar sign in front of the variable denotes the value of the variable instead of its name. If `$HOME` is `/home/bob`, then `$TEXMFHOME` would be `/home/bob/texmf`. We can understand the following paths to be under this home directory.
+
+| Path | Files |
+| :--------------------------------- | :------------- |
+| `$TEXMFHOME/source/latex/nameauth` | `Makefile` |
+| | `cat01.pdf` |
+| | `beamer01.pdf` |
+| | `beamer02.pdf` |
+| | `beamer03.pdf` |
+| | `nameauth.dtx` |
+| | |
+| `$TEXMFHOME/doc/latex/nameauth` | `compat.tex` |
+| | `examples.tex` |
+| | `nameauth.pdf` |
+| | `README.md` |
+| | |
+| `$TEXMFHOME/tex/latex/nameauth` | `nameauth.sty` |
+
+Create the directories in the left-hand column, or whatever one needs to do in one's own case. Move or copy the files in the right-hand column to their respective directories in the left-hand column. On older TeX distributions, run `mktexlsr` on `$TEXMFHOME` to complete the install process (current distributions may not need this).
+
+### 4.3.5 System-Wide Directory
+
+`TEXMFLOCAL` is a variable that points to the root of a TDS-compliant directory tree available to all users on a local site, system-wide installation.To get its value, use:
+
+ kpsewhich --var-value TEXMFLOCAL
+
+See the [TeX FAQ](https://www.texfaq.org/FAQ-what-TDS). We can understand the following paths to be under this local site, system-wide directory:
+
+| Path | Files |
+| :---------------------------------- | :------------- |
+| `$TEXMFLOCAL/source/latex/nameauth` | `Makefile` |
+| | `cat01.pdf` |
+| | `beamer01.pdf` |
+| | `beamer02.pdf` |
+| | `beamer03.pdf` |
+| | `nameauth.dtx` |
+| | |
+| `$TEXMFLOCAL/doc/latex/nameauth` | `compat.tex` |
+| | `examples.tex` |
+| | `nameauth.pdf` |
+| | `README.md` |
+| | |
+| `$TEXMFLOCAL/tex/latex/nameauth` | `nameauth.sty` |
+
+Create the directories in the left-hand column, or whatever one needs to do in one's own case. Move or copy the files in the right-hand column to their respective directories in the left-hand column. Change file ownership as needed (not so much on Windows). If needed, run `mktexlsr` with the appropriate permissions on `$TEXMFLOCAL` to complete the install process. See also the discussion on [this page](https://tex.stackexchange.com/questions/45231/how-to-install-system-wide-packages-without-requiring-an-ls-r-database-with-tex).
+
+# 5. More on Package Building
+
+* `Makefile` has been upgraded to handle more special cases and not to do unexpected or bad things in those cases, especially on Windows.
+
+* The package and manual build on current and older TeX distributions. In a number of examples, some Unicode characters have been replaced with control sequences in order for this compatibility to work, due to how files written out and read back in affects the expansion of active Unicode characters.
+
+* The documentation now builds only with `pdflatex`, but the examples and tests can use any LaTeX engine. This is because several typesetting decisions that are quite helpful for the manual work only with `pdflatex`.
+
+* This release was tested on Linux (Pop! OS; vanilla TL 2022 and 2017) and Windows 10 (MikTeX with both Cygwin and WSL). The tests using TL 2017 include my published book manuscript, *Breath of God, Yet Work of Man: Scripture, Philosophy, Dialogue, and Conflict*, with Dr. Albert B. Collver III.
+
+* The CTAN release was created with vanilla TL 2022 on Pop! OS. The most recent `equivs` file was used to meet package equivalencies. See also [this page](https://tug.org/texlive/debian.html).
+
+* TeXlive 2022 and TL 2017 are managed on Pop! OS using [tl-switch](https://github.com/ServusCarolus/tl-switch).
+
+* Four pdf files (`cat01.pdf` and `beamer*.pdf`) used in graphic illustrations are created from the output of test files associated with this manual (see below). Normally, the user need not generate them; they are supplied as source files.
+
+# 6. Examples / Testing
+
+The file `examples.tex`, which also uses `compat.tex`, usually should be enough to illustrate various non-trivial features of this package. It includes most of the longer examples in the manual, edited to fit together in a single document.
+
+In addition to this file, a special run of `nameauth.dtx` that defines the macro `\NameauthDoTestFiles` will generate many separate test files. Normally they are written out to `nameauth.tmp` and read in again as verbatim text. They are not included in the package archive by default in order to minimize clutter.
+
+To test `nameauth`, either test the files right after installing, or create a new testing directory. One can copy the files from the TDS-compliant source dir and optionally, the documentation directory as well, or unpack the CTAN zip file and build the package.
+
+## 6.1 GNU make: Examples, Tests, Images
+
+* Use the default: `make examples`.
+
+* To create `examples.pdf` with other LaTeX engines, one can do the following:
+
+ make examples ENGINE=xelatex
+ make examples ENGINE=lualatex
+ make examples ENGINE=dvilualatex
+ make examples ENGINE=latex
+
+* If one wants to change engines and re-test the file, type `make exclean`.
+
+* To generate additional test files, type `make tests`.
+
+ This will produce many test files numbered by chapter and example within that chapter from the `nameauth.dtx` file. It will compile all of the test files using `pdflatex`. One can add the value of ENGINE:
+
+ make tests ENGINE=xelatex
+ make tests ENGINE=lualatex
+ make tests ENGINE=dvilualatex
+ make tests ENGINE=latex
+
+* If one wants to change engines and re-test the files, type `make testclean`.
+
+* If, for some reason, one wanted to make the manual illustrations (usually not required), one would type `make images`.
+
+## 6.2 Manual Method
+
+### 6.2.1 Examples
+
+Compile `examples.tex`. In the following command lines, one may substitute `latex`, `xelatex`, `lualatex`, and `dvilualatex` for `pdflatex`.
+
+ pdflatex --interaction=nonstopmode examples
+ pdflatex --interaction=nonstopmode examples
+ makeindex -o examples.ind examples.idx
+
+This next line is needed because the `index` package makes an index of persons.
+
+ makeindex -o examples.rnd examples.rdx
+
+These lines complete the indexes and TOC.
+
+ pdflatex --interaction=nonstopmode examples
+ pdflatex --interaction=nonstopmode examples
+
+Another step is used only with `latex` and `dvilualatex`. We default to `dvipdfmx` in case Ghostscript is not installed. If Ghostscript is already installed, one can use `dvipdf` instead. If a file `examples.out.ps` exists, one may delete it after creating the pdf file.
+
+ dvipdfmx examples
+
+If one changes LaTeX engines, one must remove all of the auxiliary files.
+
+### 6.2.2 Tests
+
+Generate the test files in the following manner from the `dtx`:
+
+ pdflatex "\def\NameauthDoTestFiles{}\input{nameauth.dtx}"
+
+Compile the test files. In the following command lines, one may substitute `latex`, `xelatex`, `lualatex`, and `dvilualatex` for `pdflatex`. One must change the root or base file name for each test file.
+
+ pdflatex --interaction=nonstopmode test01-01
+ pdflatex --interaction=nonstopmode test01-01
+ makeindex -o test01-01.ind test01-01.idx
+
+This next line is needed only for `test07-01.tex` because the `index` package is used for an index of persons.
+
+ makeindex -o test07-01.rnd test07-01.rdx
+
+These lines complete the indexes and TOC.
+
+ pdflatex --interaction=nonstopmode test01-01
+ pdflatex --interaction=nonstopmode test01-01
+
+This step is used only when using `latex` and `dvilualatex`.
+
+ dvipdfmx test01-01
+
+If one changes LaTeX engines, one must remove all of the auxiliary files.
+
+### 6.2.3 Images
+
+If, for some reason, one wants to make the manual illustrations (usually not required), this would be the default procedure:
-1. Either go to the directory used when unpacking the `zip` file or copy the file `examples.tex` from the `doc/latex/nameauth` branch of whatever TDS-compliant tree to a directory of your choice.
+Generate the test files in the following manner from the `dtx`:
-2. If one has access to GNU `make`, use either `Makefile` in the directory where one unpacked the `zip` file or copy `Makefile` from either `src/latex/nameauth` or `doc/latex/nameauth` in whatever TDS-compliant tree it exists.
+ pdflatex "\def\NameauthDoTestFiles{}\input{nameauth.dtx}"
-When using `make`, any `dvi` files that are created will also be converted to `pdf` format.
+Compile the test files:
-3. To compile the test file using `make` and `pdflatex`, simply type `make testing`.
+ pdflatex --interaction=nonstopmode test07-02
+ pdflatex --interaction=nonstopmode test07-02
+ makeindex -o test07-02.ind test07-02.idx
+ pdflatex --interaction=nonstopmode test07-02
+ pdflatex --interaction=nonstopmode test07-02
+
+ pdflatex --interaction=nonstopmode test09-01
+ pdflatex --interaction=nonstopmode test09-01
+ makeindex -o test09-01.ind test09-01.idx
+ pdflatex --interaction=nonstopmode test09-01
+ pdflatex --interaction=nonstopmode test09-01
-4. For multi-format testing using `make` in addition to that above, one can do the following:
+ pdfjam --paper a6paper --landscape --quiet test07_02.pdf 3 --outfile cat01.pdf
+ pdfjam --paper a5paper --landscape --quiet test09_01.pdf 1 --outfile beamer01.pdf
+ pdfjam --paper a5paper --landscape --quiet test09_01.pdf 2 --outfile beamer02.pdf
+ pdfjam --paper a5paper --landscape --quiet test09_01.pdf 3 --outfile beamer03.pdf
- make testing ENGINE=pdflatex
- make testing ENGINE=latex
- make testing ENGINE=lualatex
- make testing ENGINE=dvilualatex
- make testing ENGINE=xelatex
+# 7. Additional Notes
-5. If one does not have `make`, one can use the following commands, substituting, e.g., `latex`, `xelatex`, `lualatex`, and `dvilualatex` for `pdflatex`:
+In version 3.7 I spent over seven months analyzing and optimizing both code and documentation. Stepping away from this package for a bit gave me the perspective and clarity to improve it greatly.
- pdflatex --interaction=nonstopmode examples
- pdflatex --interaction=nonstopmode examples
- makeindex -o examples.ind examples.idx
- makeindex -o examples.rnd examples.rdx
- pdflatex --interaction=nonstopmode examples
- pdflatex --interaction=nonstopmode examples
+* I cast aside a number of stale presuppositions that had built up over time. I explored all the ways that one could use certain features and fixed the bugs that appeared by using a better general approach.
-The use of different extensions for the index results from using the `index` package to generate a persons index separate from a subject index.
+* I brought back some thorough tests reminiscent of early package versions, but moved to the examples file.
-The manual is also a test suite.
+* I rewrote the documentation to remove a lot of idiosyncratic formatting. It looks much cleaner, both as source code and as typeset documentation.
-# Copyright
+* Extensive rewriting has led to the TOC becoming the principal expression of scope and sequence. The goal was greater rigor in keeping the easy stuff easy and the complex stuff more accessible.
-Copyright (C) 2021 by Charles P. Schaum <charles[dot]schaum@comcast.net>
--------------------------------------------------------
+* The package itself has been reorganized to follow the same sequence as the documentation, letting the rhythm of repetition aid learning. One sees this right away in the TOC.
+
+* Several macros have been optimized, leading to simpler and cleaner designs that are easier to debug.
+
+* A few bugs that could result from directly changing internal package flags have been fixed, allowing the user-accessible parser to work in all cases as intended.
+
+* Any name arguments shown in warnings are detokenized in order to prevent potential errors. Regressions caused by a reverted edit in an earlier version that I failed to catch caused several package warnings to halt with errors. These "lameauth" errors are fixed.
+
+# 8. Copyright
+
+Copyright (C) 2023 by Charles P. Schaum <charles[dot]schaum@comcast.net>
This file may be distributed and/or modified under the
conditions of the LaTeX Project Public License, either version 1.3
of this license or (at your option) any later version.
The latest version of this license is in:
- [http://www.latex-project.org/lppl.txt](https://www.latex-project.org/lppl.txt)
+ [https://www.latex-project.org/lppl.txt](https://www.latex-project.org/lppl.txt)
and version 1.3 or later is part of all distributions of LaTeX
version 2005/12/01 or later.
+
%readmevb
%</readme>
%<*internal>
@@ -194,7 +497,7 @@ version 2005/12/01 or later.
This is a generated file.
-Copyright (C) 2021 by Charles P. Schaum <charles[dot]schaum@comcast.net>
+Copyright (C) 2023 by Charles P. Schaum <charles[dot]schaum@comcast.net>
This file may be distributed and/or modified under the conditions of
the LaTeX Project Public License, either version 1.3 of this license
@@ -224,6 +527,9 @@ and version 1.3 or later is part of all distributions of LaTeX version
\generate{
\file{examples.tex}{\from{\jobname.dtx}{examples}}
}
+\generate{
+ \file{compat.tex}{\from{\jobname.dtx}{compat}}
+}
\nopreamble
\generate{
\file{README.md}{\from{\jobname.dtx}{readme}}
@@ -243,10 +549,12 @@ and version 1.3 or later is part of all distributions of LaTeX version
%<package>\NeedsTeXFormat{LaTeX2e}[2005/12/01]
%<package>\ProvidesPackage{nameauth}
%<*package>
- [2021/02/27 3.6 Name authority mechanism for consistency in text and index]
+ [2023/02/03 3.7 Name authority mechanism for consistency in text and index]
%</package>
%
%<*driver>
+%^^A %%%%%%%%%%%%% Stuff Needed in the Document Preamble %%%%%%%%%%%%%%%%%
+
\documentclass[11pt]{ltxdoc}
%^^A Below we check if our TL distribution has the iftex package and load it.
@@ -261,367 +569,598 @@ and version 1.3 or later is part of all distributions of LaTeX version
\usepackage{ifpdf}
\fi
-%^^A We include packages depending on the LaTeX engine, mode,
-%^^A and version of TeX being used.
-\ifxetex %^^A \ifpdf will not be true, but a pdf results.
- \usepackage{fontspec}
- \usepackage{polyglossia}
- \setdefaultlanguage{american}
- \setotherlanguage{german}
- \newcommand\de[1]{\textgerman{#1}}
-\else
- \ifluatex
- \ifpdf %^^A pdf mode
- \usepackage{fontspec}
- \usepackage{polyglossia}
- \setdefaultlanguage{american}
- \setotherlanguage{german}
- \newcommand\de[1]{\textgerman{#1}}
- \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}
- \fi
-\fi
+%^^A We only use pdflatex to make the documentation.
+\IfFileExists{utf8-2018.def}{}{\usepackage[utf8]{inputenc}}
+\usepackage[TS1,T1]{fontenc}
+\usepackage{textcomp} %^^A For backward compatibility
+\usepackage[ngerman,american]{babel}
+\newcommand\de[1]{\foreignlanguage{ngerman}{#1}}
+\usepackage{lmodern}
+\usepackage{newunicodechar}
+\DeclareTextSymbolDefault{\textlongs}{TS1}
+\DeclareTextSymbol{\textlongs}{TS1}{115}
+\newunicodechar{ſ}{\textlongs}
+
+%^^A Finish with fonts and micro-typography.
+\usepackage{manfnt}
+\usepackage{microtype}
-%^^A Used unconditionally because we convert the dvi to pdf
-%^^A Otherwise we would put this in \ifpdf...\fi
+%^^A This helps track down any stray or unintended changes to font sizes.
+\let\savegraf\everypar
+\makeatletter
+\newcommand\FontDebugStart
+{%^^A
+ \let\oldep\everypar%^^A
+ \newtoks\everypar%^^A
+ \oldep{\the\everypar \llap{\f@size pt\hspace{4em plus 1fil minus 1em}}}%^^A
+}
+\newcommand\FontDebugStop
+{%^^A
+ \let\oldep\savegraf%^^A
+ \oldep{\the\everypar}%^^A
+}
+\makeatother
+
+%^^A Add fancy graphical features
\usepackage{tikz}
\usepackage{tcolorbox}
-\usepackage{microtype}
+%^^A Set basic format for boxes drawn by TikZ.
+\tcbset{fonttitle=\bfseries\sffamily,box align=top,lower separated=false}
-%^^A Set up initial page layout to fit both letter and DIN A4.
-\usepackage[textwidth=137mm,textheight=237mm,
- right=25mm,marginparwidth=39mm,nohead]{geometry}
+%^^A Set up page layout to fit both letter and DIN A4.
+\usepackage[paperheight=279.4mm,paperwidth=210mm,
+ textheight=239.4mm,textwidth=140mm,
+ right=20mm,marginparwidth=40mm,nohead]{geometry}
+
+%^^A Two-column TOC
+\usepackage[toc]{multitoc}
+
+%^^A Include an index
+\usepackage{makeidx}
+
+%^^A These options allow the index to focus on names in the index more
+%^^A like one might see in a normal document.
+%^^A \DisableCrossrefs
+\CodelineIndex
+\RecordChanges
+\frenchspacing
%^^A Include specifically the current version of the package.
-\usepackage{\jobname}[2021/02/27]
+\usepackage{\jobname}[2023/02/03]
+
+%^^A Set up the ``actual'' character
+\IndexActual{=}
%^^A Set up all tabular packages. Booktabs makes them pretty,
-%^^A colortabl shades rows, and tabularx allows some fiddly
-%^^A stuff when typesetting the nameauth environment as a table.
+%^^A colortabl shades rows.
\usepackage{booktabs}
\usepackage{colortbl}
%^^A Set up lists.
-\usepackage{enumitem}
+\usepackage[inline]{enumitem}
\setlist{rightmargin=\leftmargin,itemsep=0pt}
-%^^A Create indexes and set up the ``actual'' character in nameauth
-%^^A to conform to gind.ist.
-\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}
+%^^A Use underlining in certain contexts.
+\usepackage{soulutf8}
%^^A Color helps categorize information.
\usepackage{xcolor}
-
-\colorlet{nared}{red!50!black}
+\colorlet{nared}{red!60!black}
\colorlet{nagreen}{green!35!black}
\colorlet{nablue}{blue!50!black}
\colorlet{nabrown}{brown!50!black}
-\colorlet{naviolet}{violet!90!black}
-\colorlet{nataupe}{yellow!40!black}
\colorlet{naslate}{cyan!45!black}
-\colorlet{grey}{black!7!white}
+\colorlet{nagrey}{black!7!white}
+
+%^^A Use color indicators in a couple of tables.
+\newcommand\NO{\bgroup
+ \color{black!20!white}\lower 0.075ex\hbox{\rule{1.5ex}{1.5ex}}\egroup}
+\newcommand\YES{\bgroup
+ \color{black!80!white}\lower 0.075ex\hbox{\rule{1.5ex}{1.5ex}}\egroup}
-%^^A For example...
-\usepackage{verbatim}
+%^^A Let verbatim environments be fancy.
+\usepackage{fancyvrb}
+
+%^^A Define fancyvrb defaults.
+\fvset{gobble=2,numbers=left,fontsize=\small}
+
+%^^A Tweak spacing as needed
+\usepackage{setspace}
+
+%^^A Define some stretch if needed
+\newcommand\smallstretch{\setstretch{1.05}}
+\newcommand\medstretch{\setstretch{1.1}}
+\newcommand\bigstretch{\setstretch{1.2}}
+
+%^^A Permit horizontal boxes to be overfull.
+\hfuzz=3pt
+
+%^^A Define negative skip values if needed.
+\newcommand\negsmallskip{\vspace{-\smallskipamount}}
+\newcommand\negmedskip{\vspace{-\medskipamount}}
+\newcommand\negbigskip{\vspace{-\bigskipamount}}
%^^A Have documentation with hyperlinks
\usepackage[numbered]{hypdoc}
-%^^A Let verbatim environments be numbered or unnumbered, and start or resume that.
-\makeatletter
-\newcommand*\ClearNum{%^^A
- \newcounter{VerbLine}\setcounter{VerbLine}{0}%^^A
- \def\verbatim@processline{\expandafter\@gobble\the\verbatim@line\par}%^^A
+%^^A Change URL color
+\hypersetup{urlcolor=violet}
+
+%^^A Redefine emphasis in the body text because italic has dedicated uses.
+\let\oldemph\emph
+\let\emph\textbf
+
+%^^A Redefine name formatting for this manual.
+\renewcommand*\FrontNamesFormat[1]{\color{red}\sffamily #1}
+\renewcommand*\FrontNameHook[1]{\color{darkgray}\sffamily #1}
+\renewcommand*\NamesFormat[1]{\color{blue}\sffamily #1}
+\renewcommand*\MainNameHook[1]{\sffamily #1}
+
+%^^A Show a ``dangerous bend'' in the margin.
+\newcommand*\Warn
+{%^^A
+ \unless\ifinner
+ {\marginpar{\raggedleft\strut\small\raise0.7ex\hbox{\dbend}}}%^^A
+ \fi
+}
+
+%^^A Put information in the margin.
+\newcommand*\Info[1]
+{%^^A
+ \unless\ifinner
+ {\marginpar{\raggedleft\footnotesize#1}}%^^A
+ \fi
}
-\newcommand*\StartNum{%^^A
- \setcounter{VerbLine}{0}
- \def\verbatim@processline{\stepcounter{VerbLine}\leavevmode%^^A
- \llap{\footnotesize\normalfont\theVerbLine\quad}%^^A
- \expandafter\@gobble\the\verbatim@line\par}%^^A
+
+\newcommand\Same
+ {\Info{Same name patterns\break and index entries\break as above.}}
+
+%^^A Show a name pattern in margin.
+\newcommand*\PatInfo[1]
+{%^^A
+ \unless\ifinner
+ {%^^A
+ \marginpar
+ {\raggedleft\footnotesize Name Pattern(s):\hfill\break
+ \ttfamily#1}%^^A
+ }%^^A
+ \fi
}
-\newcommand*\ContinueNum{%^^A
- \def\verbatim@processline{\stepcounter{VerbLine}\leavevmode%^^A
- \llap{\footnotesize\normalfont\theVerbLine\quad}%^^A
- \expandafter\@gobble\the\verbatim@line\par}%^^A
+
+%^^A Show a basic index entry info in margin.
+\newcommand*\IdxInfo[1]
+{%^^A
+ \unless\ifinner
+ {%^^A
+ \marginpar{\raggedleft\footnotesize Basic Index:\hfill\break#1}%^^A
+ }%^^A
+ \fi
}
-\makeatother
-%^^A Use color indicators in a couple of tables.
-\newcommand\NO{\bgroup\color{black!20!white}\lower 0.075ex\hbox{\rule{1.5ex}{1.5ex}}\egroup}
-\newcommand\YES{\bgroup\color{black!80!white}\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{\raggedleft\strut\textsf{\bfseries#1}}\fi}
-\newcommand*\Warn{{\unless\ifinner\marginpar{\small\strut\raggedleft\raise0.7ex\hbox{\dbend}}\fi}}
-\newcommand*\Info[1]{{\MyStretch\unless\ifinner\marginpar{\small\raggedleft#1}\fi}}
-\newcommand*\SPatInfo[1]{{\MyStretch\unless\ifinner\marginpar{\footnotesize\raggedleft Simplified Name Pattern(s):\break\ttfamily#1}\fi}}
-\newcommand*\PatInfo[1]{{\MyStretch\unless\ifinner\marginpar{\footnotesize\raggedleft Name Pattern(s):\hfill\break\ttfamily#1}\fi}}
-\newcommand*\IdxInfo[1]{{\MyStretch\unless\ifinner\marginpar{\footnotesize\raggedleft Basic Index:\hfill\break#1}\fi}}
-\newcommand*\Illus{{\MyStretch\unless\ifinner\marginpar{\footnotesize\raggedleft
- Name color and\\
- typeface are only\\
- illustrative, not\\
- package defaults.}\fi}}
-
-%^^A Use this example in the body text.
+%^^A Show both name patterns and index entries in margin.
+\newcommand*\BothInfo[2]
+{%^^A
+ \unless\ifinner
+ {%^^A
+ \marginpar{%^^A
+ \raggedleft\footnotesize Name Pattern(s):\hfill\break%^^A
+ {\ttfamily#1}\smallskip\break%^^A
+ \raggedleft\footnotesize Basic Index:\hfill\break#2%^^A
+ }%^^A
+ }%^^A
+ \fi
+}
+
+%^^A Return to the TOC at the end of a major section.
+\newcommand*\ReturnLink
+{%^^A
+ \leavevmode
+ \begin{quote}%^^A
+ \centering\tcbox{Back to \hyperlink{TOC}{Table of Contents}}%^^A
+ \end{quote}%^^A
+}
+
+%^^A Print a high-visibility callout that can have an optional title.
+\newenvironment{InfoBox}[1][]
+{%^^A
+ \def\titulus{#1}%^^A
+ \medskip%^^A
+ \ifx\titulus\empty
+ \begin{tcolorbox}[colback=white,colframe=red!90!black]%^^A
+ \else
+ \begin{tcolorbox}[colback=white,colframe=red!90!black,
+ adjusted title={\bfseries\hfil #1}]%^^A
+ \fi
+}
+{\end{tcolorbox}\medskip}
+
+%^^A Print a callout that can have an optional title.
+\newenvironment{SyntaxBox}[1][]
+{%^^A
+ \def\titulus{#1}%^^A
+ \begingroup\medskip
+ \ifx\titulus\empty
+ \begin{tcolorbox}[colback=white,colframe=darkgray]%^^A
+ \begin{tabular}{@{}l@{}}
+ \else
+ \begin{tcolorbox}[colback=white,colframe=darkgray,
+ adjusted title={\bfseries\hfil #1}]%^^A
+ \begin{tabular}{@{}l@{}}
+ \fi
+}
+{\end{tabular}\end{tcolorbox}\medskip\endgroup}
+
+%^^A Print a two-cell callout that can have an optional title.
+\newenvironment{SyntaxBoxii}[1][]
+{%^^A
+ \def\titulus{#1}%^^A
+ \ifx\titulus\empty
+ \smallskip\begin{tcolorbox}[colback=white,colframe=darkgray]%^^A
+ \begingroup\begin{tabular}{@{}ll@{}}
+ \else
+ \smallskip\begin{tcolorbox}[colback=white,colframe=darkgray,
+ adjusted title={\bfseries\hfil #1}]%^^A
+ \begingroup\begin{tabular}{@{}ll@{}}
+ \fi
+}
+{\end{tabular}\endgroup\end{tcolorbox}\smallskip}
+
+%^^A Print a quote and the source.
+
+\renewcommand{\hrulefill}{%
+ \leavevmode\leaders\hrule height 1.5pt\hfill\kern0pt }
+
+\newenvironment{Quote}[1]
+{\def\QuoteName{#1}\begin{quote}\small\vfill\hrulefill\medskip\\}
+{\\[1ex]\hbox{}\hfill---\normalsize\QuoteName\end{quote}}
+
+%^^A Used for one or more examples
+\newenvironment{Block}
+{%^^A
+ \begin{quote}\small
+ \setlist{rightmargin=0pt,leftmargin=0pt,topsep=0ex,itemsep=0pt}%^^A
+ \begin{itemize}\item[]
+}
+{\end{itemize}\end{quote}}
+
+%^^A Warning repeated throughout the manual
+\newcommand\NameArgWarning
+{%^^A
+ \begin{InfoBox}%^^A
+ When a macro occurs in a name argument and the argument will be
+ displayed in the text and in the index, if there are any concerns
+ about macro expansion, one should put \cmd{\noexpand} before that
+ macro.
+ \end{InfoBox}%^^A
+}
+
+%^^A Macros that handle describing index states
+
+\newcommand\Stay[2]
+{%^^A
+ \parbox{0.685\textwidth}{#1\dotfill}%^^A
+ \lower 2ex\hbox{%^^A
+ \quad\tcbox[boxsep=0.2ex]{\textls[-20]{Stay in State #2}}%^^A
+ }%^^A
+}
+
+\newcommand\Go[2]
+{%^^A
+ \parbox{0.685\textwidth}{#1\dotfill}%^^A
+ \lower 2ex\hbox{%^^A
+ \quad\tcbox[boxsep=0.2ex]{\textls[30]{Go to State #2}}%^^A
+ }%^^A
+}
+
+%^^A Used when introducing name forms
+\newcommand\FUse{\leavevmode\hbox to 5em{First use:\hfill}}
+\newcommand\LUse{\leavevmode\hbox to 5em{Later use:\hfill}}
+
+%^^A Use this example in the body text. It is defined here due
+%^^A to the vertical bars, which are redefined 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 because italic has some dedicated uses.
-\let\oldemph\emph
-\let\emph\textbf
+%^^A Set up all the shorthands, but not all the names. Even if one does
+%^^A not set up all the names here, it is a very good idea to set up the
+%^^A (pre)tags just below, especially in a dtx file, where the vertical
+%^^A bars are active.
-%^^A Set up all the shorthands, but not all the names. Even if one does not set
-%^^A up all the names here, it is a very good idea to set up the (pre)tags just below,
-%^^A especially in a dtx file.
\begin{nameauth}
- \< Adams & John & \noexpand\textSC{Adams} & >
\< Aeth & & Æthelred, II & >
\< Aris & & Aristotle & >
\< Bailey & Betsey & Bailey & >
+ \< Carter & J.E. & Carter, Jr. & >
\< Cicero & M.T. & Cicero & >
\< Confucius & & Confucius & >
\< 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 & >
\< Doug & Frederick & Douglass & >
\< 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 >
+ \< Fukuyama & & \noexpand\textUC{Fukuyama} & Takeshi >
\< JWG & J.W. von & Goethe & >
- \< HAR & & Harun, \noexpand\textSC{\noexpand\AltCaps{a}l-Rashid} & >
+ \< TGrac & \noexpand\TSemp & Gracchus & >
\< Harnack & Adolf & Harnack & >
+ \< AVH & Adolf & Harnack & Adolf\noexpand\von >
\< Henry & & Henry & VIII >
- \< Jeff & Thomas & \noexpand\JEFF & >
+ \< Ike & Dwight D. & Eisenhower & >
+ \< Jeff & Thomas &
+ \noexpand\textSC{Jefferson}\noexpand\GEN{} & >
\< Eriugena & & John, Eriugena & >
+ \< MLK & Martin Luther & King, Jr. & >
\< Lewis & Clive Staples & Lewis & >
\< CSL & Clive Staples & Lewis & C.S. >
+ \< Linc & Abraham & Lincoln & >
\< Luth & Martin & \noexpand\textSC{Luther} & >
- \< Cath & Catherine \noexpand\AltCaps{d}e' & \noexpand\textSC{Medici} & >
- \< Mencius & & \noexpand\textSC{Mencius} & >
- \< Miyaz & & Miyazaki, Hayao & >
+ \< Cath & Catherine \noexpand\AltCaps{d}e' &
+ \noexpand\textSC{Medici} & >
+ \< Miyazaki & & Miyazaki, Hayao & >
\< MSens & & Miyazaki, Hayao & Sensei >
\< Noguchi & Hideyo & Noguchi & >
- \< Pat & George S. & Patton, Jr. & >
- \< JRIII & J.D. & \textSC{Rockefeller},\textSC{III} & >
+ \< Patton & George S. & Patton, Jr. & >
+ \< Plato & & Plato & >
\< JRIV & J.D. & Rockefeller, IV & >
\< JayR & J.D. & Rockefeller, IV & Jay >
\< Scipio & \noexpand\SCIPi & \noexpand\SCIPii & >
- \< OScipio & Publius & \noexpand\CSA & >
+ \< OScipio & Lucius & \noexpand\CSB & >
\< Shak & \noexpand\WM & \noexpand\SHK & >
- \< Striet & John & \de{Strietelmeier} & >
+ \< Striet & John & \noexpand\de{Strietelmeier} & >
+ \< Sun & & Sun, Yat-sen & >
\< KempMed & & Thomas, à~Kempis & >
\< KempW & Thomas & à~Kempis & >
\< Tyson & Mike & Tyson & >
\< Iron & Mike & Tyson & Iron Mike >
\< VBuren & Martin & Van Buren & >
\< Wash & George & Washington & >
- \< White & E.\,B. & White & >
+%^^A We use the next row as an example in the docs.
+%^^A \< White & E.\,B. & White & >
\< Yamt & & Yamamoto, Isoroku & >
\< Yosh & & Yoshida & Shigeru >
\end{nameauth}
-%^^A Add sort tags here for those needing them. Especially for dtx files.
-\PretagName[John]{\noexpand\textSC{Adams}}{Adams, John}
+%^^A Add sort tags here for those needing them.
+
\PretagName{Æthelred, II}{Aethelred 2}
-\PretagName{Atatürk}{Ataturk}
+\PretagName[Thomas]{à~Kempis}{Akempis, Thomas}
+\PretagName{Antiochus, III}{Antiochus 3}
+\PretagName{Antiochus, IV}{Antiochus 4}
+\PretagName{Atat\"urk}{Ataturk}
\PretagName[W.H.]{Auden}{Auden, Wystan}
-\PretagName{\textit{Doctor mellifluus}}{Doctor mellifluus}
-\PretagName[Charles]{\textBF{Babbage}}{Babbage, Charles}
+
+\PretagName[Charles]{\noexpand\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[Charles-Louis]{de Secondat}{deSecondat, Charles}
+\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, William}
-\PretagName[W.E.B.]{DuBois}{Dubois, William}
-\PretagName[Charles]{du~Fresne}{Dufresne, Charles}
+\PretagName{\textit{Doctor mellifluus}}{Doctor mellifluus}
+\PretagName[W.E.B.]{Du~Bois}{DuBois, William}
\PretagName{du~Cange}{Ducange}
+\PretagName[Charles]{du~Fresne}{Dufresne, Charles}
+
\PretagName{Elizabeth, I}{Elizabeth 1}
-\PretagName{\textUC{Fukuyama}, Takeshi}{Fukuyama Takeshi}
-\PretagName[Greta]{\textSC{Garbo}}{Garbo, Greta}
+
+\PretagName{\noexpand\textUC{Fukuyama}}[Takeshi]{Fukuyama Takeshi}
+
+\PretagName[Greta]{\noexpand\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[\noexpand\TSemp]{Gracchus}{Gracchus, Tiberius Sempronius}
+\PretagName{Gregory, I}{Gregory 1}
+
+\PretagName[Thomas]{\noexpand\textSC{Jefferson}\noexpand\GEN{}}
+ {Jefferson, Thomas}
+
+\PretagName{\noexpand\textUC{Kanade}, Takeo}{Kanade Takeo}
+
+\PretagName[Ada]{\noexpand\textIT{Lovelace}}{Lovelace, Ada}
\PretagName[Martin]{\noexpand\textSC{Luther}}{Luther, Martin}
-\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{\textSC{Misora}, Hibari}{Misora Hibari}
+
+\PretagName[Catherine \noexpand\AltCaps{d}e']{\noexpand\textSC{Medici}}
+ {Medici, Catherine de}
+\PretagName{\noexpand\textSC{Misora}, Hibari}{Misora Hibari}
\PretagName[Frenec]{Molnár}{Molnar, Frenec}
-\PretagName[J.D.]{\textSC{Rockefeller},\textSC{III}}{Rockefeller, John D 3}
+
+\PretagName[Sandra Day]{O'Connor}{OConnor, Sandra}
+
+\PretagName{Ptolemy, IV}{Ptolemy 4}
+\PretagName{Ptolemy, V}{Ptolemy 5}
+
\PretagName[J.D.]{Rockefeller, IV}{Rockefeller, John D 4}
-\PretagName[Heinrich Wilhelm]{\textSC{Rühmann}}{Ruehmann, Heinrich Wilhelm}
+\PretagName[Heinrich Wilhelm]{\noexpand\textSC{R\"uhmann}}
+ {Ruehmann, Heinrich Wilhelm}
+\PretagName[Heinz]{\noexpand\textSC{R\"uhmann}}{Ruehmann, Heinz}
+
+\PretagName{Seleucus, III}{Seleucus 3}
\PretagName[\noexpand\SCIPi]{\noexpand\SCIPii}{Scipio Africanus}
-\PretagName[Publius]{\noexpand\CSA}{Cornelius Scipio Africanus}
+\PretagName[Lucius]{\noexpand\CSB}{Cornelius Scipio Barbatus}
\PretagName[\noexpand\WM]{\noexpand\SHK}{Shakespeare, William}
-\PretagName[Heinz]{\textSC{Rühmann}}{Ruehmann, Heinz}
\PretagName{\textit{Snellius}}{Snellius}
-\PretagName[John]{\de{Strietelmeier}}{Strietelmeier, John}
+\PretagName[John]{\noexpand\de{Strietelmeier}}{Strietelmeier, John}
+
\PretagName{Thomas, à~Kempis}{Thomas Akempis}
-\PretagName[Thomas]{à~Kempis}{Akempis, Thomas}
-\PretagName{\textUC{Tokugawa}, Ieyasu}{Tokugawa Ieyasu}
-\PretagName{Vlad, Ţepeş}{Vlad Tepes}
+
+\PretagName{Vlad, {\c T}epe{\c s}}{Vlad Tepes}
+
\PretagName[E.\,B.]{White}{White, Elwyn}
-%^^A Add index tags for all names. Failing to do this here, especially in
-%^^A dtx files, can result in errors.
-\TagName[John]{\noexpand\textSC{Adams}}{, pres.|hyperpage}
+\PretagName[Konrad]{\noexpand\textSC{Zuse}}{Zuse, Konrad}
+
+%^^A Add index tags for all names in the dtx file.
+
\TagName{Æthelred, II}{, king|hyperpage}
+\TagName{Antiochus, III}{ the Great, king|hyperpage}
+\TagName{Antiochus, IV}{ Epiphanes, king|hyperpage}
\TagName{Aristotle}{|hyperpage}
\TagName[W.H.]{Auden}{|hyperpage}
-\TagName[Charles]{\textBF{Babbage}}{|hyperpage}
-\TagName[Thomas Haynes]{Bayly}{|hyperpage}
+
+\TagName[Charles]{\noexpand\textBF{Babbage}}{|hyperpage}
+\TagName[Betsey]{Bailey}{|hyperpage}
+\TagName[Leonard]{Bernstein}{|hyperpage}
\TagName{Bernard, of Clairvaux}{|hyperpage}
\TagName{Bo\"ethius}{|hyperpage}
\TagName[Robert]{\textSC{Burns}}{|hyperpage}
+
+\TagName[Julius]{Caesar}{, imperator|hyperpage}
\TagName[Rudolph]{Carnap}{|hyperpage}
\TagName[J.E.]{Carter, Jr.}{, pres.|hyperpage}
\TagName[Charlie]{Chaplin}{|hyperpage}
+\TagName[Charles W.]{Chesnutt}{|hyperpage}
\TagName[M.T.]{Cicero}{|hyperpage}
\TagName{Chiang}[Kai-shek]{\ddag, pres.|hyperpage}
\TagName[Schuyler]{Colfax}{, v.p.|hyperpage}
\TagName{Confucius}{|hyperpage}
+\TagName{Cratylus}{|hyperpage}
\TagName[e.e.]{cummings}{|hyperpage}
+
\TagName{Dagobert}[I]{\ddag, king|hyperpage}
+\TagName[Sammy]{Davis,Jr.}{|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[Pierre-Jean]
+ {\noexpand\Fbox{\noexpand\AltCaps{d}e~Smet}}{|hyperpage}
\TagName[Hernando]{de~Soto}{|hyperpage}
\TagName[Marc van]{Dongen}{|hyperpage}
\TagName[Frederick]{Douglass}{|hyperpage}
-\TagName[Betsey]{Bailey}{|hyperpage}
\TagName[W.E.B.]{Du~Bois}{|hyperpage}
\TagName[Charles]{du~Fresne}{|hyperpage}
+
\TagName[Albert]{Einstein}{|hyperpage}
+\TagName[Dwight D.]{Eisenhower}{, pres.|hyperpage}
\TagName{Elizabeth, I}{, queen|hyperpage}
-\TagName{\textUC{Fukuyama}, Takeshi}{|hyperpage}
-\TagName[Greta]{\textSC{Garbo}}{|hyperpage}
+
+\TagName[Robin]{Fairbairns}{|hyperpage}
+\TagName{\noexpand\textUC{Fukuyama}}[Takeshi]{\ddag|hyperpage}
+
+\TagName[Greta]{\noexpand\textSC{Garbo}}{|hyperpage}
\TagName{Ghazāli}{|hyperpage}
\TagName{Ghazali}{|hyperpage}
+\TagName[\noexpand\TSemp]{Gracchus}{, consul|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{Hermogenes}{|hyperpage}
\TagName{Henry}[VIII]{, king|hyperpage}
\TagName[Bob]{Hope}{|hyperpage}
-\TagName{Ishida}[Yoko]{\ddag|hyperpage}
-\TagName[Thomas]{\noexpand\JEFF}{, pres.|hyperpage}
+\TagName[Hubert H.]{Humphrey}{, v.p.|hyperpage}
+
+\TagName[Thomas]{\noexpand\textSC{Jefferson}\noexpand\GEN{}}
+ {, pres.|hyperpage}
\TagName{Jesus, Christ}{|hyperpage}
\TagName{John, Eriugena}{|hyperpage}
+
\TagName[Mustafa]{Kemal}{|hyperpage}
+\TagName[John F.]{Kennedy}{, pres.|hyperpage}
+\TagName{Kim, Jong Un}{|hyperpage}
\TagName[Martin Luther]{King, Jr.}{|hyperpage}
+
\TagName{Lao-tzu}{|hyperpage}
\TagName[Clive Staples]{Lewis}{|hyperpage}
+\TagName[Abraham]{Lincoln}{, pres.|hyperpage}
+\TagName[Titus]{Livius}{|hyperpage}
\TagName{Louis, XIV}{, king|hyperpage}
-\TagName[Ada]{\textIT{Lovelace}}{|hyperpage}
+\TagName[Ada]{\noexpand\textIT{Lovelace}}{|hyperpage}
\TagName[Uwe]{Lueck}{|hyperpage}
\TagName[Dan]{Luecking}{|hyperpage}
\TagName[Martin]{\noexpand\textSC{Luther}}{|hyperpage}
+
\TagName{Maimonides}{|hyperpage}
-\TagName{\textSC{Misora}, Hibari}{|hyperpage}
+\TagName[Dean]{Martin}{|hyperpage}
+\TagName{\noexpand\textSC{Misora}, Hibari}{|hyperpage}
\TagName[Nicolas]{Malebranche}{|hyperpage}
-\TagName[Catherine \noexpand\AltCaps{d}e']{\noexpand\textSC{Medici}}{|hyperpage}
+\TagName[Catherine \noexpand\AltCaps{d}e']{\noexpand\textSC{Medici}}
+ {|hyperpage}
\TagName{\noexpand\textSC{Mencius}}{|hyperpage}
\TagName{Miyazaki, Hayao}{|hyperpage}
+\TagName[L.M.]{Montgomery}{|hyperpage}
\TagName[Frenec]{Molnár}{\dag|hyperpage}
+\TagName[Nancy C.]{Mulvany}{|hyperpage}
+
+\TagName{Nippon Gakki}{|hyperpage}
\TagName[Hideyo]{Noguchi}{\dag|hyperpage}
-\TagName{Novalis}{|hyperpage}
+
+\TagName[Sandra Day]{O'Connor}{, justice|hyperpage}
\TagName[Heiko]{Oberdiek}{|hyperpage}
+
\TagName[George S.]{Patton, Jr.}{|hyperpage}
\TagName[Lucius]{Sergius Paulus}{|hyperpage}
+\TagName{Plato}{|hyperpage}
+\TagName{Pontius, Pilate}{|hyperpage}
+\TagName{Ptolemy, IV}{ Philopator, king|hyperpage}
+\TagName{Ptolemy, V}{ Epiphanes, king|hyperpage}
+
\TagName{Rambam}{|hyperpage}
-\TagName[J.D.]{\textSC{Rockefeller},\textSC{III}}{|hyperpage}
+\TagName[Luke]{Ranieri}{|hyperpage}
+\TagName[the]{Rat Pack}{|hyperpage}
\TagName[J.D.]{Rockefeller, IV}{|hyperpage}
-\TagName[Heinz]{\textSC{Rühmann}}{|hyperpage}
+\TagName[Theodore]{Roosevelt}{, pres.|hyperpage}
+\TagName[Heinz]{\noexpand\textSC{R\"uhmann}}{|hyperpage}
+\TagName[Salman]{Rushdie}{|hyperpage}
+
\TagName{Saul, of Tarsus}{|hyperpage}
\TagName[Robert]{Schlicht}{|hyperpage}
+\TagName{Seleucus, III}{ Ceraunus, king|hyperpage}
\TagName[\noexpand\SCIPi]{\noexpand\SCIPii}{|hyperpage}
-\TagName[Publius]{\noexpand\CSA}{|hyperpage}
+\TagName[Lucius]{\noexpand\CSB}{, consul|hyperpage}
\TagName[\noexpand\WM]{\noexpand\SHK}{|hyperpage}
+\TagName[Frank]{Sinatra}{|hyperpage}
\TagName[R.]{Snel van Royen}{|hyperpage}
\TagName[W.]{Snel van Royen}{|hyperpage}
-\TagName[Gertrude]{Stein}{|hyperpage}
+\TagName{Socrates}{|hyperpage}
\TagName[Philipp]{Stephani}{|hyperpage}
-\TagName[John]{\de{Strietelmeier}}{|hyperpage}
+\TagName[John]{\noexpand\de{Strietelmeier}}{|hyperpage}
\TagName{Sun, Yat-sen}{, pres.|hyperpage}
+
\TagName{Thomas, à~Kempis}{|hyperpage}
\TagName{Thomas, Aquinas}{|hyperpage}
-\TagName{\textUC{Tokugawa}, Ieyasu}{|hyperpage}
+\TagName[Henry David]{Thoreau}{|hyperpage}
+\TagName{\noexpand\textUC{Kanade}, Takeo}{|hyperpage}
\TagName[Mark]{Twain}{|hyperpage}
\TagName[Mike]{Tyson}{|hyperpage}
+
+\TagName[Bob]{Uecker}{|hyperpage}
+\TagName[Harold]{Urey}{|hyperpage}
+
\TagName[Martin]{Van Buren}{, pres.|hyperpage}
+\TagName[Publius]{Vegetius Renatus}{|hyperpage}
\TagName[Jesse]{Ventura}{|hyperpage}
\TagName{Vlad, II}{ Dracul|hyperpage}
\TagName{Vlad, III}{ Dracula|hyperpage}
\TagName{Voltaire}{|hyperpage}
+
\TagName[George]{Washington}{, pres.|hyperpage}
+\TagName[Alan]{Watts}{|hyperpage}
\TagName[E.\,B.]{White}{|hyperpage}
-\TagName{William, I}{|hyperpage}
+\TagName{William, I}{, king |hyperpage}
+\TagName{William, the Conqueror}{|hyperpage}
+
+\TagName{Yamaha, Torakusu}{|hyperpage}
+\TagName{Yamaha Corp.}{|hyperpage}
\TagName{Yamamoto, Isoroku}{|hyperpage}
\TagName{Yoshida}[Shigeru]{\ddag, PM|hyperpage}
+
\TagName[Caspar]{Ziegler}{|hyperpage}
-%^^A These options allow the index to focus on names in the index more like
-%^^A one might see in a normal document.
-\DisableCrossrefs
-\CodelineIndex
-\RecordChanges
-\frenchspacing
+\TagName[Konrad]{\noexpand\textSC{Zuse}}{|hyperpage}
\begin{document}
\DocInput{\jobname.dtx}
@@ -629,7 +1168,9 @@ and version 1.3 or later is part of all distributions of LaTeX version
%</driver>
% \fi
%
-% \CheckSum{3447}
+%^^A %%%%%%%%%%%%%%%%%%%%%%% Error Correction %%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%
+% \CheckSum{3451}
%
% \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
@@ -650,1123 +1191,1605 @@ and version 1.3 or later is part of all distributions of LaTeX version
% \changes{0.7}{2011/12/26}{Initial release}
% \changes{0.75}{2012/01/19}{Standardized arguments}
% \changes{0.85}{2012/02/05}{Show or hide commas}
-% \changes{1.0}{2012/02/20}{Works with \textsf{microtype}, \textsf{memoir}}
+% \changes{1.0}{2012/02/20}
+% {Works with \textsf{microtype}, \textsf{memoir}}
% \changes{2.3}{2016/01/05}{New back-end for naming macros}
% \changes{2.5}{2016/04/06}{No default format}
% \changes{3.2}{2017/03/22}{Root, suffix macros renamed, redesigned}
% \changes{3.4}{2020/02/26}{Update manual, \texttt{examples.tex}}
-% \changes{3.5}{2020/11/23}{Updates to manual, \texttt{Readme.md}, \texttt{Makefile}, \texttt{examples.tex}, combine \texttt{Readme.md} and \texttt{examples.tex} files in \texttt{dtx}}
-% \changes{3.6}{2021/02/27}{Updates to \texttt{Readme.md}, \texttt{Makefile}}
+% \changes{3.5}{2020/11/23}{Update manual, \texttt{Readme.md},
+% \texttt{Makefile},\texttt{examples.tex}; combine \texttt{Readme.md}
+% and \texttt{examples.tex} files in \texttt{dtx} file}
+% \changes{3.6}{2021/02/27}
+% {Update \texttt{Readme.md}, \texttt{Makefile}}
+% \changes{3.7}{2023/02/03}{Major updates to all files}
%
% \GetFileInfo{\jobname.dtx}
%
% \DoNotIndex{\@empty, \@gobble, \@period, \@token, \trim@spaces,
% \zap@space}
%
-% \DoNotIndex{\begingroup, \bfseries, \bgroup, \csdef, \csgdef, \csname,
-% \csundef, \DeclareOption, \def, \detokenize, \edef, \egroup, \else,
-% \endcsname, \endgroup, \endinput, \ExecuteOptions, \expandafter, \fi,
-% \futurelet, \global, \hbox, \if, \ifcsname, \ifx, \ignorespaces, \index,
-% \itshape, \leavevmode, \let, \newcommand, \newcommandx, \newenvironment,
-% \newif, \nobreakspace, \PackageError, \PackageWarning, \ProcessOptions,
-% \relax, \renewcommand, \RequirePackage, \scshape, \textbackslash, \uppercase}
-%
-% \hfuzz=3pt
+% \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,
+% \textbackslash,
+% \uppercase}
+%
+%^^A %%%%%%%%%%%%%%% Macros That Must Be Defined Here %%%%%%%%%%%%%%%%%%%%
+%
+%^^A Conditional set if we have an old TeXLive version
+%
+% \newif\ifOldTeX
+% \IfFileExists{utf8-2018.def}{}{\OldTeXtrue}
+%
+%^^A Global definitions of conditionals used for examples
+%^^A must be included here because \newif statements cannot
+%^^A occur within an \iffalse ... \fi pair (driver section).
%
-% \ClearNum
-% \tcbset{fonttitle=\bfseries\sffamily,box align=top,lower separated=false}
-%
-% \renewcommand*\FrontNamesFormat[1]{\color{red}\sffamily #1}
-% \renewcommand*\FrontNameHook[1]{\color{darkgray}\sffamily #1}
-% \renewcommand*\NamesFormat[1]{\color{blue}\sffamily #1}
-% \renewcommand*\MainNameHook[1]{\sffamily #1}
-% \newcommand*\ReturnLink{\leavevmode^^A
-% \begin{tcolorbox}\centering Back to Section~\ref{sec:Dashboard}\end{tcolorbox}^^A
-% \leavevmode}
+%^^A For George Washington/Mustafa Kemal
+% \newif\ifNoTag
%
-%^^A This helps track down any stray or unintended changes to font sizes.
-% \newif\ifFontDebug
-%^^A Uncomment the following line to debug font sizes.
-%^^A\FontDebugtrue
-% \makeatletter
-% \@setpar{^^A
-% \ifFontDebug
-% \edef\@FS{ \f@size pt}^^A
-% \unless\ifinner\marginpar{\scriptsize\normalfont\@FS}\fi
-% \fi
-% \@@par}
-% \makeatother
+%^^A For Thomas Jefferson
+% \newif\ifGenitive
+% \newif\ifDoGenitive
%
-%^^A Global definitions of conditionals for examples
-%^^A For Scipio Africanus
-% \newif\ifSkipGens
+%^^A For the Cornelii Scipiones
+% \newif\ifNoPraenomen
% \newif\ifNoGens
-% \newif\ifSkipAgnomen
+% \newif\ifNoCognomen
% \newif\ifNoAgnomen
-%^^A For Thomas Jefferson
-% \newif\ifGenitive
-% \newif\ifDoGen
-%^^A For George Washington/Mustafa Kemal
-% \newif\ifNoTag
+% \newif\ifXPrae
+% \newif\ifXGens
+% \newif\ifXCogn
+% \newif\ifXAgno
+%
+%^^A For Babbage and company
+% \newif\ifHeadword
+% \newif\ifAncientName
+%
%^^A For William Shakespeare
% \newif\ifSpecialFN
% \newif\ifSpecialSN
% \newif\ifRevertSN
+%
%^^A For advanced hooks
% \newif\ifFbox
% \newif\ifFirstCap
% \newif\ifInHook
% \Fboxtrue
% \newif\ifCaps
+%
%^^A Global definitions of macros for examples
-%^^A For Scipio Africanus
-% \newcommand*\SCIPi{\ifNoGens
-% Publius\else Publius Cornelius\fi}
-% \newcommand*\SCIPii{\ifNoAgnomen
-% Scipio\else Scipio Africanus\fi}
-% \newcommand*\ScipioOnly{\SkipAgnomentrue\Scipio}
-% \newcommand*\CSA{\ifNoGens\ifNoAgnomen
-% Scipio\else
-% Scipio Africanus\fi
-% \else\ifNoAgnomen
-% Cornelius Scipio\else
-% Cornelius Scipio Africanus\fi\fi}
-% \ExcludeName[Publius]{\noexpand\CSA}
+%
%^^A For Thomas Jefferson
-% \newcommand\JEFF{\ifDoGen\textSC{Jefferson's}\else\textSC{Jefferson}\fi}
+% \newcommand*\GEN{\ifDoGenitive\textSC{'s}\fi}
+%
+%^^A For Scipio Africanus
+% \newcommand*\SCIPi
+% {^^A
+% \ifXGens Publius\else
+% \ifXPrae Cornelius\else
+% Publius Cornelius^^A
+% \fi
+% \fi
+% }
+%
+% \newcommand*\SCIPii
+% {^^A
+% \ifXAgno Scipio\else
+% Scipio Africanus^^A
+% \fi
+% }
+%
+%^^A For Gracchus
+% \newcommand*\TSemp
+% {^^A
+% \ifXGens Tiberius\else
+% \ifXPrae Sempronius\else
+% Tiberius Sempronius^^A
+% \fi
+% \fi
+% }
+%
+%^^A For Scipio Barbatus
+% \newcommand*\CSB
+% {^^A
+% \ifXGens
+% \ifXAgno Scipio\else
+% Scipio Barbatus\fi
+% \else
+% \ifXCogn Cornelius\else
+% \ifXAgno Cornelius Scipio\else
+% Cornelius Scipio Barbatus^^A
+% \fi
+% \fi
+% \fi
+% }
+%
%^^A For William Shakespeare
-% \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*\WM
+% {^^A
+% \ifSpecialFN Wm.\else
+% William\fi
+% }
+%
+% \newcommand*\SHK
+% {^^A
+% \ifRevertSN
+% \textSC{Shakespeare}\else
+% \ifSpecialSN
+% \noexpand\AltCaps{t}he Bard\else
+% \textSC{Shakespeare}^^A
+% \fi
+% \fi
+% }
+%
% \newcommand*\Revert{\RevertSNtrue}
-%^^A End of global definitions for examples
%
-% \begingroup^^A This group prevents font debugging on the title page.
-% \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@comcast.net}}
+%^^A %%%%%%%%%%%%%%%%%%%%%%%%%% Title Page %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%
+% \title{\textsf{nameauth} --- Name authority mechanism\\
+% for consistency in text and index^^A
+% \thanks{This file describes version \fileversion, last revised \filedate.}}
+% \author{Charles P. Schaum\thanks{Email: charles[dot]schaum@comcast.net}}
% \date{Released \filedate}
%
% \maketitle
+%^^A This negative space fixes a warning.
+% \vspace{-16.67pt}
%
% \begin{abstract}
-% \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.
+% \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}
%
-% \bgroup\small\tableofcontents\egroup
-% \endgroup^^A End title page group.
-% \newpage
+%^^A %%%%%%%%%%%%%%%%%%%%%%%%%%%%%% TOC %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%
-% \section{Quick Start}
-% \begin{tcolorbox}[colback=white,colframe=nared,adjusted title={\hfil Disclaimer}]
-% \small\noindent Names are about real people; examples should be too. 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.
-% \end{tcolorbox}
+% \begingroup
+% \small
+% \hypertarget{TOC}{}^^A
+% \tableofcontents
+% \endgroup
%
-% \subsection{Introduction}
-% A \emph{name authority} is a canonical, scholarly list of name forms to which all variant name forms and aliases must refer. The task dashboard (Section~\ref{sec:Dashboard}) guides one to various areas of interest. To load the defaults, simply type:
-% \begin{center}
-% \fbox{
-% \begin{tabular}{l}
-% {\Large\strut}\texttt{\textbackslash usepackage\{nameauth\}}\\
-% \end{tabular}
-% }\smallskip
-% \end{center}
-%
-% The \textsf{nameauth} macros permit ambiguity because name forms are ambiguous unless they are put into a cultural context. Therefore, keep it simple. Use the quick interface. Use the fewest number of \textsf{nameauth} macros for one's use case.
+% \bigskip
%
-% \begin{center}\bfseries Package Design and Features\end{center}
+% \begin{InfoBox}[Disclaimer]
+% Names are about real people; examples should be too. 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 or implied by the author.
+% \end{InfoBox}
%
-% The editorial process for book-length projects may require one to add, delete, or relocate text. Several issues emerge from this:
-% \begin{itemize}
-% \item Professional writing needs a full name form to introduce a person, using shorter forms thereafter. Moving text may require re-checking names.
-% \item If a name is keyed to another name or narrative event, moving text may require checking for anachronistic references.
-% \item Including special information in the index, such as including non-Latin script name forms with Latin script forms, can be complex and tedious.
-% \item Unless one is familiar with professional indexing, one might create incorrect index entries.
-% \item One must check if any names straddle page breaks and index them.
-% \end{itemize}
+% \bigskip
%
-% The \textsf{nameauth} package provides automated solutions for all points above at the time of writing. Names become abstractions; they are verbs that alter state and nouns that have state. That improves accuracy and consistency:
-% \begin{itemize}
-% \item \emph{Automate} name forms. First uses of names have long forms. Later uses are short by default. Names vary in the text, but not in the index.
-% \item Implement \emph{cross-cultural, multilingual naming conventions}.
-% \item Implement \emph{complex name formatting} using conditional elements.
-% \item Improve indexing with \emph{automatic sorting and tagging, and cross-reference control.} Indexing rules are based on Nancy C. Mulvany, \textit{Indexing Books} (Chicago: University of Chicago Press, 1994). All references [\hypertarget{Mulvany}{Mulvany}] refer to this edition.
-% \item \emph{Associate and retrieve information} bound to names.
-% \end{itemize}
+% \begin{InfoBox}
+% All direct quotes contained herein are in the public domain or copyrighted works cited in small excerpts under the terms of fair use, to which the present author claims no copyright. Such quotes are used to stimulate the mind and promote the concept that names have value, can take different forms, and can represent sharply different viewpoints. Some quotes are a kind of ``running gag'' about Shakespearian names and roses. That illustrates the transformative aspect of fair use as well as the ratio of work quoted to its total size.
+% \end{InfoBox}
+%
+% \begin{Quote}{\Name[Theodore]{Roosevelt}\break\hbox{}\hfill
+% Introduction, \textit{The Papers and Writings of Abraham Lincoln} (1905)}
+% It is a very poor thing, whether for nations or individuals, to advance the history of great deeds done in the past as an excuse for doing poorly in the present; but it is an excellent thing to study the history of the great deeds of the past, and of the great men who did them, with an earnest desire to profit thereby so as to render better service in the present. In their essentials, the men of the present day are much like the men of the past, and the live issues of the present can be faced to better advantage by men who have in good faith studied how the leaders of the nation faced the dead issues of the past.
+% \end{Quote}
%
+% \newpage
+%
+%^^A %%%%%%%%%%%%%%%%% Start of Documentation Proper %%%%%%%%%%%%%%%%%%%%%
+%
+% \section{Quick Start}
+% \label{sec:QuickStart}
+%
+% A \emph{name authority} is a canonical, scholarly list of names to which variant name forms and aliases refer. This package helps one easily work with a name authority to manage, format, and index names, especially in larger publications.
+%
+% \subsection{Simple Example}
+% \label{sec:QuickExample}
% \begingroup
% \renewcommand{\NamesFormat}{}
% \renewcommand{\MainNameHook}{}
-% For example,\IdxInfo{\ShowIdxPageref*[Frederick]{Douglass}\break \ShowIdxPageref*[Betsey]{Bailey}} from a biography written a century ago, we show reordered paragraphs that require no subsequent changes. We use the ``quick interface'' and no name formatting (the package default). We ``forget'' names at the top of the right-hand column to simulate not using them yet (Section~\ref{sec:NameControl}):
+%
+% We begin with an excerpt from a biography written by \Name[Charles W.]{Chesnutt}[Charles Waddell], a prominent African-American author at the turn of the twentieth century.\footnote{\Name[Charles W.]{Chesnutt}, \textit{Frederick Douglass} (Boston: Small, Maynard, 1899). See also \href{https://docsouth.unc.edu/neh/chesnutt/summary.html} {\bfseries this web page}.}
+% We create a new document and use only the default \textsf{nameauth} package options. We do not create any formatting for names (Section~\ref{sec:Formatting}).
+%
+% The \texttt{nameauth} environment (Section~\ref{sec:QuickUIStart}) is in the preamble. It resembles a \texttt{tabular} with four columns. In column one we define the naming macros. In columns two and three we define the names that the macros will display. We leave column four empty. After the first group, we use \cmd{\Forgetname} (Section~\ref{sec:NameControl}) to ``forget'' that the names appeared, making the conditions of the second group the same as the first for illustrative purposes.
+%
+% \ifdefined\NameauthDoTestFiles \edef\NameauthTestFile{test01_01.tex}\else
+% \edef\NameauthTestFile{\jobname.tmp}\fi
+%
+% \begin{VerbatimOut}{\NameauthTestFile}
+% \documentclass{article}
+% \input{compat.tex} % Included with nameauth; needed only if
+% % compiling on multiple TeX distros or LaTeX engines.
+% \usepackage{makeidx}
+% \usepackage{nameauth}
+% \makeindex
+% \usepackage[inline]{enumitem}
+%
+% \begin{nameauth}
+% % Col. 1 Col. 2 Col. 3 Col. 4
+% \< Doug & Frederick & Douglass & >
+% \< Bailey & Betsey & Bailey & >
+% \end{nameauth}
+%
+% \begin{document}
+%
+% \begin{enumerate*}
+% \item[\textbf{1.}] \Doug\ rose to eminence by sheer force
+% of character and talents that neither slavery nor caste
+% proscription could crush.
+% \item[\textbf{2.}] \Doug's early life is perhaps the most
+% complete indictment of the slave system ever presented at
+% the bar of public opinion.
+% \item[\textbf{3.}] \Doug\ was born in February, l8l7. His
+% earliest memories centered around the cabin of his
+% grandmother, \Bailey.
+% \end{enumerate*}
+%
+% \ForgetName[Frederick]{Douglass}
+% \ForgetName[Betsey]{Bailey}
+% \begin{enumerate*}
+% \item[\textbf{2.}] \Doug's early life is perhaps the most
+% complete indictment of the slave system ever presented at
+% the bar of public opinion.
+% \item[\textbf{3.}] \Doug\ was born in February, l8l7. His
+% earliest memories centered around the cabin of his
+% grandmother, \Bailey.
+% \item[\textbf{1.}] \Doug\ rose to eminence by sheer force
+% of character and talents that neither slavery nor caste
+% proscription could crush.
+% \end{enumerate*}
+%
+% \printindex
+% \end{document}
+% \end{VerbatimOut}
+%
% \begin{quote}\small
-% \begin{multicols}{2}
-% |\Doug\| \Doug\ rose to eminence by sheer force of character and talents that neither slavery nor caste proscription could crush. Circumstances could not prevent him from becoming a freeman and a leader.
+% \VerbatimInput[gobble=0]{\NameauthTestFile}
+% \end{quote}
+%
+% \begin{quote}\small
+% \begin{enumerate*}
+% \item[\textbf{1.}] \Doug\ rose to eminence by sheer force
+% of character and talents that neither slavery nor caste
+% proscription could crush.
+% \item[\textbf{2.}] \Doug's early life is perhaps the most
+% complete indictment of the slave system ever presented at
+% the bar of public opinion.
+% \item[\textbf{3.}] \Doug\ was born in February, l8l7. His
+% earliest memories centered around the cabin of his
+% grandmother, \Bailey.
+% \end{enumerate*}
+%
+% \ForgetName[Frederick]{Douglass}
+% \ForgetName[Betsey]{Bailey}
+% \begin{enumerate*}
+% \item[\textbf{2.}] \Doug's early life is perhaps the most
+% complete indictment of the slave system ever presented at
+% the bar of public opinion.
+% \item[\textbf{3.}] \Doug\ was born in February, l8l7. His
+% earliest memories centered around the cabin of his
+% grandmother, \Bailey.
+% \item[\textbf{1.}] \Doug\ rose to eminence by sheer force
+% of character and talents that neither slavery nor caste
+% proscription could crush.
+% \end{enumerate*}
+% \end{quote}
+%
+% If we reorder the statements, the names change form automatically. In a book-length project, one might manage hundreds of names, associated information, and index entries. The \textsf{nameauth} package automates aspects of academic and business writing to minimize the work of such management:
+%
+% \begin{itemize}
+% \item Automate the display and formatting of names.
+% \item Manage and display information that is associated with names.
+% \item Make decisions relating to names (name control sequence patterns).
+% \item Sort name index entries properly.
+% \item Automatically add information to index entries.
+% \item Ensure correct indexing of names that span page breaks.
+% \item Change name forms in the text while retaining consistent index entries.
+% \item Adopt name forms in the text and index that are culturally appropriate.
+% \item Do not force the user to adopt any one culture's naming conventions.
+% \item Permit European academic conventions (``Continental'' formatting).
+% \end{itemize}
+%
+% Indexing rules implemented by \textsf{nameauth} are based on \Name[Nancy C.]{Mulvany}, \textit{Indexing Books} (Chicago: University of Chicago Press, 1994). All references [\hypertarget{Mulvany}{Mulvany}] refer to this edition. See also \textit{The Chicago Manual of Style} by the same publisher.
+% \endgroup
%
-% |\Doug's| \Doug's early life is perhaps the most complete indictment of the slave system ever presented at the bar of public opinion.
+% \begin{Quote}{\ForgetThis\Doug\break
+% \hbox{}\hfill motto, \textit{The North Star} (Rochester, NY, 1847)}
+% Right Is of No Sex\,---\,Truth Is of No Color\,---\,God Is the Father
+% of Us All, and All We Are Brethren.\vspace{-1ex}
+% \end{Quote}
+%
+% \newpage
%
-% |\Doug\| \Doug\ was born in February, l8l7. His earliest memories centered around the private cabin of his grandmother, |\Bailey,| \Bailey, who was charged with only the duty of looking after young children.
+% \subsection{How To Use the Manual}
+% \label{sec:ManualUse}
%
-% \columnbreak\ForgetName[Frederick]{Douglass}\ForgetName[Betsey]{Bailey}
-% |\Doug's| \Doug's early life is perhaps the most complete indictment of the slave system ever presented at the bar of public opinion.
+% This manual tries to support various learning styles by using layout, colors, shapes, and similar ordering of both document sections and package code.
%
-% |\Doug\| \Doug\ was born in February, l8l7. His earliest memories centered around the private cabin of his grandmother, |\Bailey,| \Bailey, who was charged with only the duty of looking after young children.
+% \subsubsection*{Macro Argument Types}
+% \vspace{-4ex}
%
-% |\Doug\| \Doug\ rose to eminence by sheer force of character and talents that neither slavery nor caste proscription could crush. Circumstances could not prevent him from becoming a freeman and a leader.
+% \begin{multicols}{2}
+% \begin{tcolorbox}[colback=white,colframe=black,
+% adjusted title={\bfseries\hfil \{Mandatory Arguments\}}]
+% \centering This manual shows mandatory arguments in black.
+% \end{tcolorbox}
+%
+% \begin{tcolorbox}[colback=white,colframe=nared,
+% adjusted title={\bfseries\hfil [Optional Arguments]}]
+% \centering This manual shows optional arguments in dark red.
+% \end{tcolorbox}
% \end{multicols}
-% \end{quote}
-% \endgroup
-%
-% \subsection{How to Use the Manual}
-% Topics in this manual that are more basic or frequent in use are toward the front. Topics that are more complex or less-used are toward the back. As topics get more advanced, various sections mutually inform each other.
%
-% For reference, throughout this manual we show simplified and complete \emph{name patterns} in the margins (Section~\ref{sec:NamePatterns}). These patterns control name behavior. In the early pages of the manual we also show \emph{basic index entries} in the margins.
+% \subsubsection*{Scope and Sequence}
+%
+% The table of contents has become detailed in order to indicate more clearly what topics are covered, from frequent and simple to infrequent and complex. Later topics require knowledge from multiple sections. The end of each major section includes a return link to the table of contents.
+%
+% \subsubsection*{Key Concepts}
+%
+% Throughout much of this manual, starting in Section~\ref{sec:BasicStart}, we use debugging macros (Section~\ref{sec:Debugging}) to show \emph{name control patterns} in the margins (cf. Section~\ref{sec:NamePatterns}). These patterns are the key to how names work in \textsf{nameauth}. Through Section~\ref{sec:NameMedieval} we show \emph{basic index entries} in the margins. These macros and the \texttt{idx} file can aid greatly with complex use cases and subtle issues.
+%
+% \subsubsection*{Special Signs}
%
-% \begin{center}\bfseries Special Signs\end{center}
% \noindent This manual uses signs and illustrative typesetting that are not built-in defaults of \textsf{nameauth}, but in some cases are implemented using it:
+%
% \begin{itemize}
-% \item[\ \ ]We often highlight {\NamesFormat{first}} and {\MainNameHook{later}} 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[\ \ ]We highlight {\NamesFormat{First Uses}} and
+% {\MainNameHook{Later Uses}} of names (Sections~\ref{sec:Formatting},
+% \ref{sec:NameControl}).
+% \item[\dag\ ]A dagger indicates reversed Western forms
+% (Sections~\ref{sec:RevNames}).
+% \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.
+% \item[\(\leftarrow\)]The\Warn{} ``dangerous bend'' shows where caution
+% is needed.
% \end{itemize}
-% \vfill
%
-% \begin{tcolorbox}[colback=white,colframe=nared,adjusted title={\hfil Thanks}]
-% \small\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
-% \end{tcolorbox}
+% \subsubsection*{Example Files}
+%
+% The files \texttt{examples.tex} and \texttt{compat.tex} located with this manual. For generating package testing files, see \texttt{README.md}, also located with this manual.
+%
+% \begin{InfoBox}[Thanks]\small
+% For assistance at various times, thanks to \Name[Marc van]{Dongen}, \Name[Enrico]{Gregorio}, \Name[Philipp]{Stephani}, \Name[Heiko]{Oberdiek}, \Name[Uwe]{Lueck}, \Name[Dan]{Luecking}, \Name[Robert]{Schlicht}, and others.\\[1ex]
+% \hbox{}\hfil \textit{In memoriam} \Name[Robin]{Fairbairns}\\[1ex]
+% He was very kind when I first uploaded \textsf{nameauth}, and gracious thereafter as well.
+% \end{InfoBox}
+%
% \newpage
%
-% \subsection{Task Dashboard}
-% \label{sec:Dashboard}
-%
-% 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.
-%
-% \begin{tcolorbox}[colframe=naslate,adjusted title={\hfil Where do you want to go today?}]\centering
-% \tcbox[equal height group=Z,on line,tikznode,colframe=nablue,colback=white,adjusted title={\bfseries\sffamily\hfil Quick Start}]{^^A
-% Basic concepts: \ref{sec:QuickStart}\\
-% Macros: \ref{sec:TradStart}, \ref{sec:SimpleStart}, \ref{sec:SelectOver}\\
-% Various hints: \ref{sec:Hints}}^^A
-% \hfill
-% \tcbox[equal height group=Z,on line,tikznode,colframe=nablue,colback=white,adjusted title={\bfseries\sffamily\hfil Basics}]{^^A
-% Package options: \ref{sec:PkgOptions}\\
-% Name macros: \ref{sec:Naming}, \ref{sec:FName}\\
-% Simple\,Variants\,(text/index): \ref{sec:VarNames}, \ref{sec:Indexing}}^^A
-% \vspace{9pt}
-%
-% \tcbox[equal height group=Zi,on line,tikznode,colframe=nagreen,colback=white,adjusted title={\bfseries\sffamily\hfil Language}]{^^A
-% Western names: \ref{sec:Affix}, \ref{sec:LastFirst}\\
-% Eastern names: \ref{sec:Affix}, \ref{sec:Eastern}\\
-% Particles: \ref{sec:NameParticles}, \ref{sec:AltFormat}, \ref{sec:Hooksiii}}^^A
-% \hfill
-% \tcbox[equal height group=Zi,on line,tikznode,colframe=nagreen,colback=white,adjusted title={\bfseries\sffamily\hfil Language}]{^^A
-% Medieval/Ancient: \ref{sec:NameAncient}, \ref{sec:Hooksi}\\
-% ``Continental'' typesetting:\\
-% \ref{sec:AltFormat}, \ref{sec:AltBasic}, \ref{sec:AltAdvanced}, \ref{sec:Hooksiii}}^^A
-% \vspace{9pt}
-%
-% \tcbox[equal height group=Zii,on line,tikznode,colframe=nataupe,colback=white,adjusted title={\bfseries\sffamily\hfil Index}]{^^A
-% Page entries, index\\
-% \,control, \& xrefs: \ref{sec:GeneralIndex}\,}^^A
-% \hfill
-% \tcbox[equal height group=Zii,on line,tikznode,colframe=nataupe,colback=white,adjusted title={\bfseries\sffamily\hfil Index}]{^^A
-% Setting up automatic sorting: \ref{sec:IndexSort}\\
-% Auto-add info to index entries: \ref{sec:IndexTag}}^^A
-% \vspace{9pt}
-%
-% \tcbox[equal height group=Ziii,on line,tikznode,colframe=nabrown,colback=white,adjusted title={\bfseries\sffamily\hfil Intermediate}]{^^A
-% Name info database: \ref{sec:TextTags}\\
-% Test for the presence of names:\\
-% \ref{sec:NameDecisions}, \ref{sec:NameControl}, \ref{sec:NameTests}}^^A
-% \hfill
-% \tcbox[equal height group=Ziii,on line,tikznode,colframe=nared,colback=white,adjusted title={\bfseries\sffamily\hfil Advanced}]{^^A
-% \hbox{\ }Various discussions about\hbox{\ }\\
-% errors: \ref{sec:NameParticles}, \ref{sec:Warnings}, \ref{sec:Errors},\\
-% \ref{sec:Obsolete}, \ref{sec:NamePatterns}, \ref{sec:Unicode}}^^A
-% \vspace{9pt}
-%
-% \tcbox[equal height group=Ziv,on line,tikznode,colframe=nared,colback=white,adjusted title={\bfseries\sffamily\hfil Advanced}]{^^A
-% Formatting: \ref{sec:Formatting}, \ref{sec:AltFormat}, \ref{sec:AltBasic},\\
-% \ref{sec:AltAdvanced}, \ref{sec:Hooksi}, \ref{sec:Hooksii}, \ref{sec:Hooksiii}\\
-% Customizing: \ref{sec:Customize}}^^A
-% \hfill
-% \tcbox[equal height group=Ziv,on line,tikznode,colframe=nared,colback=white,adjusted title={\bfseries\sffamily\hfil Advanced}]{^^A
-% Link names \& text to sequences\\
-% of time or ideas: \ref{sec:TextTags}, \ref{sec:NameTests}\\
-% (history/game books)}^^A
-% \vspace{9pt}
-%
-% \tcbox[equal height group=Zv,on line,tikznode,colframe=nared,colback=white,adjusted title={\bfseries\sffamily\hfil Advanced}]{^^A
-% Use different formats\\
-% to call out information: \ref{sec:TextTags},\\
-% \ \ref{sec:Formatting}, \ref{sec:AltFormat}, \ref{sec:NameTests},
-% \ref{sec:Hooksi}, \ref{sec:Hooksii},\ \ \ \\
-% \ref{sec:Hooksiii} (history/game books)}^^A
-% \hfill
-% \tcbox[equal height group=Zv,on line,tikznode,colframe=nared,colback=white,adjusted title={\bfseries\sffamily\hfil Advanced}]{^^A
-% 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}}^^A
-% \vspace{4pt}
-%
-% \begin{tcolorbox}[colframe=nared,colback=white]
-% \centering For building the \textsf{nameauth} package, see \texttt{README.md},\\
-% located with this manual, and Section~\ref{sec:TechNotes}.
-% \end{tcolorbox}
-% \vspace{-3pt}
-% \end{tcolorbox}
+% \subsection{Basic Concepts}
%
-% \subsection{Basic Name Concepts}
-% \label{sec:QuickStart}
+% This section introduces fundamental concepts needed by package users.
+%
+% \subsubsection{Name Ambiguity}
+% \negmedskip
%
-% 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}. Section~\ref{sec:Obsolete} shows the obsolete syntax, which is usable but discouraged. Basic syntactic forms are:
+% Apart from cultural context, the elements of a name are ambiguous. The \textsf{nameauth} macros embrace the ambiguity of culture, context, and publishing markets as they create consistent name forms and index entries Let us consider three names from history. Many Western readers will tend to interpret them in this manner:
%
-% \noindent\begin{tcolorbox}[colframe=naslate,adjusted title={Western Name and ``Non-native'' Eastern Name}]
-% \tcbox[equal height group=A,on line,tikznode,colback=white,adjusted title={\bfseries\sffamily Forename(s):\\ \meta{FNN}}]{%
-% Personal name(s):\\
+% \begin{center}\small\medstretch
+% \begin{tabular}{lll}\toprule
+% & Forename(s) & Surname\\
+% \rowcolor{nagrey}\Name[M.T.]{Cicero}[Marcus Tullius] &
+% \FName[M.T.]{Cicero}[Marcus Tullius] &
+% \Name[M.T.]{Cicero}\\
+% \Name{Jesus, Christ} &
+% \Name{Jesus, Christ} &
+% \ForceFN\FName{Jesus, Christ}\\
+% \rowcolor{nagrey}\Name{Pontius, Pilate} &
+% \Name{Pontius, Pilate} &
+% \ForceFN\FName{Pontius, Pilate}\\\bottomrule
+% \end{tabular}
+% \end{center}
+%
+% The problem is that all these interpretations technically are wrong! Yet popular books tend to permit error for the sake of readability. To illustrate that, we encode \Name[M.T.]{Cicero} as a Western name. Yet this approach would be quite incorrect in a scholarly publication or reference work (Section~\ref{sec:Romani}).
+%
+% As a Roman \textit{praenomen}, \FName[M.T.]{Cicero}[Marcus] did not have the same importance or meaning as a modern Western forename.\footnote{\url{https://en.wikipedia.org/wiki/Praenomen}}
+% Moreover, \Name[M.T.]{Cicero} is not the surname of the great Roman orator. His \textit{nomen}, the name of his clan or \textit{gens}, is \FName[M.T.]{Cicero}[Tullius]. For quite some time in English he was known as \IndexRef{Tully}{Cicero, M.T.}\Name{Tully}. The name \Name[M.T.]{Cicero} is a \textit{cognomen}, a name tied to a personal attribute or later, a branch family in a clan.
+%
+% The case of \Name*{Jesus, Christ} becomes clearer when we consider \Name*{Jesus, Christ}[of Nazareth] (John 19:19) and \Name*{Jesus, Christ} [son of David] (Mark~10:47; cf. Matthew~1:20). The personal name is \Name{Jesus, Christ} (Greek for Joshua). Adding \ForceFN \FName*{Jesus, Christ}[of Nazareth] and \ForceFN\FName*{Jesus, Christ} [Son of David] shows, respectively, the place of notable origin and family descent. \ForceFN\FName*{Jesus, Christ} is a religious title (Anointed One), a Greek loan-word from Hebrew \textit{mashiach} (Messiah).
+%
+% The name \Name*{Pontius, Pilate} is interesting because his \textit{praenomen} has been lost to history. This fits with Roman naming trends at the time. \Name{Pontius, Pilate} is a clan name. Most references, including his own inscriptions, favor his \textit{cognomen} \ForceFN\FName{Pontius, Pilate}[Pilatus], which is due likely to its connection to skill with the \textit{pilum} and martial prowess.
+%
+% Thus, in this manual, we make the following name encoding choices, targeted for a ``semi-scholarly'' book that popularizes history for a general Western readership:
+%
+% \begin{center}\small\medstretch
+% \begin{tabular}{lll}\toprule
+% Macro & Type & Index\\
+% \rowcolor{nagrey}|\Name[M.T.]{Cicero}| &
+% Western name &
+% \ShowIdxPageref*[M.T.]{Cicero}\\
+% |\Name{Jesus, Christ}| &
+% ancient name &
+% \ShowIdxPageref*{Jesus, Christ}\\
+% \rowcolor{nagrey}|\Name{Pontius, Pilate}| &
+% ancient name &
+% \ShowIdxPageref*{Pontius, Pilate}\\\bottomrule
+% \end{tabular}
+% \end{center}
+%
+% \begin{Quote}{\ForgetThis\Name[M.T.]{Cicero}[Marcus Tullius]\break
+% \hbox{}\hfill\textit{De oratore} B II; C IX, \S 36}
+% By what other voice, too, than that of the orator, is history, the evidence of time, the light of truth, the life of memory, the directress of life, the herald of antiquity, committed to immortality?\vspace{-1ex}
+% \end{Quote}
+%
+% \subsubsection{Name Arguments}
+% \label{sec:NameArgs}
+%
+% Below are the forms of name arguments, as defined by the current syntax. Compare [\hyperlink{Mulvany}{Mulvany}, 152--82] and the \textit{Chicago Manual of Style}. \Name[Nancy C.]{Mulvany} offers some excellent advice on names, cross-references, and name variants that can guide one well when using this package. The forms below are an adaptation of these sources to \LaTeX.
+%
+% \noindent\begin{tcolorbox}[colframe=naslate,
+% adjusted title={Western Name:
+% \oarg{FNN}\marg{SNN, Affix}\oarg{Alternate}}]
+% \centering\small\smallskip
+%^^A
+% \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}}\hfill
-% \tcbox[equal height group=A,on line,tikznode,colback=white,adjusted title={\bfseries\sffamily Surname(s):\\ \meta{SNN}}]{%
-% Family name:\\
+% \phantom{Family\,/\,clan name}}\hfill^^A
+%^^A
+% \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}}}\hfill
-% \tcbox[equal height group=A,on line,tikznode,colback=white,colframe=nared,adjusted title={\bfseries\sffamily Descriptor:\\ \meta{Affix}}]{%
-% Sobriquet/title:\\
+% \textit{nomen\,/\,cognomen}\\
+% \textit{patronym}\\\vspace{-3ex}
+% \phantom{\textit{nomen\,/\,cognomen}}}\hfill^^A
+%^^A
+% \tcbox[equal height group=A,on line,tikznode,
+% colback=white,colframe=nared,
+% adjusted title={\bfseries\sffamily Qualifier:\\ \meta{Affix}}]
+% {Sobriquet/title:\\
% \textit{Sr., Jr., III\dots}\\
% \textit{notable attribute}\\
-% \textit{origin, region}}
+% \textit{origin, region}\\
+% \phantom{\textit{notable attribute}}}\medskip
%
-% \begin{tcolorbox}[colback=white,colframe=nared,adjusted title={\bfseries\sffamily Alternate Name(s): \meta{Alternate}}]
-% \centering In the body text, not the index, \meta{Alternate} swaps with \meta{FNN}\\
-% for Western names and \meta{Affix} for all other name categories.
-% \end{tcolorbox}
-% \end{tcolorbox}
+% \begin{tcolorbox}[colback=white,colframe=nared,
+% adjusted title={\bfseries\sffamily Alternate Name(s):
+% \meta{Alternate}}]
+% \centering Replaces \meta{FNN} only in the text.
+% \end{tcolorbox}\negsmallskip
%
-% \begin{tcolorbox}[colframe=naslate,adjusted title={``Native'' Eastern Name}]\centering
-% \tcbox[equal height group=B,on line,tikznode,colback=white,adjusted title={\bfseries\sffamily Family name:\\ \meta{SNN}}]{Family/clan name}\hfill
-% \tcbox[equal height group=B,on line,tikznode,colback=white,adjusted title={\bfseries\sffamily Personal name:\\ \meta{Affix}}]{Few multiple\\
+% \end{tcolorbox}
+% \footnotetext{There are several ways of handling the Roman \textit{tria
+% nomina}. See Section~\ref{sec:Romani}.}
+%
+% \begin{tcolorbox}[colframe=naslate,
+% adjusted title={``Native'' Eastern Name}:
+% \marg{SNN, Affix}\oarg{Alternate}]
+% \centering\small\smallskip
+%
+% \tcbox[equal height group=B,on line,tikznode,
+% colback=white,
+% adjusted title={\bfseries\sffamily Family name:\\ \meta{SNN}}]
+% {Family\,/\,clan name}\hfill^^A
+%^^A
+% \tcbox[equal height group=B,on line,
+% tikznode,colback=white,
+% adjusted title={\bfseries\sffamily Personal name:\\ \meta{Affix}}]
+% {Few multiple\\
% names; multi-\\
-% character okay.\\
-% \vspace{-2ex}\hphantom{\textit{ancestor, vocation}}}\hfill
-% \tcbox[equal height group=B,on line,tikznode,colback=white,colframe=nared,adjusted title={\bfseries\sffamily Descriptor:\\ \meta{Alternate}}]{%
-% Replaces \meta{Affix}\\
-% (new); personal\\
-% name (obsolete)\\
-% \vspace{-2ex}\hphantom{Sobriquet/title:}}
+% character okay.\\\vspace{-3ex}
+% \phantom{\textit{nomen\,/\,cognomen}}}\hfill^^A
+%^^A
+% \tcbox[equal height group=B,on line,tikznode,
+% colback=white,colframe=nared,
+% adjusted title={\bfseries\sffamily Alt. name:\\ \meta{Alternate}}]
+% {Replaces \meta{Affix}\\
+% only in text.\footnotemark\\
+% \phantom{\textit{notable attribute}}}\smallskip
% \end{tcolorbox}
-%
-% \begin{tcolorbox}[colframe=naslate,adjusted title={Royal/Medieval/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}}\hfill
-% \tcbox[equal height group=C,on line,tikznode,colback=white,colframe=nared,adjusted title={\bfseries\sffamily Descriptor:\\ \meta{Affix}}]{%
-% Sobriquet/title:\\
+% \footnotetext{The obsolete syntax uses \meta{Alternate} instead of
+% \meta{Affix} for a personal name (Section~\ref{sec:Obsolete}).}
+%
+% \begin{tcolorbox}[colframe=naslate,
+% adjusted title={Royal/Medieval/Ancient Name}:
+% \marg{SNN, Affix}\oarg{Alternate}]
+% \centering\small\smallskip
+%
+% \tcbox[equal height group=C,on line,tikznode,colback=white,
+% adjusted title={\bfseries\sffamily Personal name:\\ \meta{SNN}}]
+% {\small Given name(s)\\
+% \phantom{Family\,/\,clan name}}\hfill^^A
+%^^A
+% \tcbox[equal height group=C,on line,tikznode,
+% colback=white,colframe=nared,
+% adjusted title={\bfseries\sffamily Qualifier:\\ \meta{Affix}}]
+% {Sobriquet/title:\\
% \textit{Sr., Jr., III\dots}\\
% \textit{notable attribute}\\
% \textit{origin, region}\\
-% \textit{patronym}\\
-% \vspace{-2ex}\hphantom{\textit{ancestor, vocation}}}\hfill
-% \tcbox[equal height group=C,on line,tikznode,colback=white,colframe=nared,adjusted title={\bfseries\sffamily Descriptor:\\ \meta{Alternate}}]{%
-% Alternate name\\
-% Replaces \meta{Affix}\\
-% (new); titles,\\
-% etc. (obsolete)\\
-% \hphantom{Sobriquet/title:}}
+% \textit{patronym}\\\vspace{-3ex}
+% \phantom{\textit{nomen\,/\,cognomen}}}\hfill^^A
+%^^A
+% \tcbox[equal height group=C,on line,tikznode,
+% colback=white,colframe=nared,
+% adjusted title={\bfseries\sffamily Alt. name:\\ \meta{Alternate}}]
+% {Replaces \meta{Affix}\\
+% only in text.\footnotemark\\
+% \phantom{\textit{notable attribute}}}\smallskip
% \end{tcolorbox}
+% \footnotetext{The obsolete syntax uses \meta{Alternate} instead of
+% \meta{Affix} for a qualifier (Section~\ref{sec:Obsolete}).}
+%
+% \newpage
+%
+% \subsubsection[Final Optargs]{Final Optional Arguments}
+% \label{sec:FinalOptargs}
+%
+% Macros that take name arguments (Sections~\ref{sec:NameArgs} and~\ref{sec:NameArgMacros}) have the potential to contain a final optional argument. Their trailing arguments look like:
+%
+% \begin{tcolorbox}[colframe=naslate]\centering
+% \begin{tabular}{c@{ }c}
+% \small Required & \small Optional\\
+% \tcbox[equal height group=E,colback=white,
+% tikznode,left=1mm,right=1mm,valign=center]
+% {\bfseries\dots\marg{SNN\color{nared}, Affix}} &
+% \tcbox[equal height group=E,colback=white,
+% tikznode,left=1mm,right=1mm,valign=center]
+% {\bfseries\oarg{\color{nared}Alternate}}
+% \end{tabular}
+% \end{tcolorbox}\smallskip
+%
+% Usually these arguments have no side effects, except in the case where we want to follow a name with an editorial insertion enclosed in square brackets. Since this does occur in academic and journalistic writing, we show how to handle this below and on the next page, where we suppress formatting to focus on syntax:
+%
+% \begin{VerbatimOut}{\jobname.tmp}
+% \begin{itemize}
+% \item We are looking for ``Albert Einstein [said]'' and
+% ``Miyazaki Hayao [said]''; also ``Einstein [said]''
+% and ``Miyazaki [said]''.
+% \item We get ``\Name[Albert]{Einstein} [said]'' and
+% ``\Name{Miyazaki, Hayao} [said]''.
+% The personal names got replaced with alternate
+% name arguments in the long name forms.
+% \item Repeating does not help: ``\Name[Albert]{Einstein}
+% [said]'' and ``\Name{Miyazaki, Hayao} [said]''.
+% The text \texttt{[said]} was not displayed due to
+% shorter name forms being shown by default in
+% subsequent name uses.
+% \item[] \textbf{We fix the situation thus:}
+% \item Add explicit spaces: ``\Name[Albert]{Einstein}\
+% [said]'' and ``\Name {Miyazaki, Hayao}\ [said]''.
+% \item Add curly braces: ``\Name[Albert]{Einstein}{}
+% [said]'' and ``\Name{Miyazaki, Hayao}{} [said]''.
+% \end{itemize}
+% \end{VerbatimOut}
+%
+% \begin{quote}\small
+% \VerbatimInput[gobble=0]{\jobname.tmp}
+% \renewcommand\NamesFormat{}
+% \renewcommand\MainNameHook{}
+%
+% \input{\jobname.tmp}
+% \end{quote}
+%
+% The same situation and resolution happens also when name shorthands have been defined. For example, ``\cmd{\Einstein\textbackslash\ [said]}'' produces ``\Einstein\ [said]'' and ``\cmd{\Miyazaki\textbackslash\ [said]}'' produces ``\Miyazaki\ [said]''. This situation does not arise with great frequency, but it can crop up occasionally and may leave one scratching one's head over something odd in the text.
%
-% \footnotetext{How one handles Roman names depends on index entry form; some possible suggestions are given above. See more on page~\pageref{page:Romani} and following.}
% \newpage
%
% \subsection{Basic Interface}
-% \label{sec:TradStart}
+% \label{sec:BasicStart}
+%
+% The description of macro arguments in this section applies to all \textsf{nameauth} macros that take name arguments (Sections~\ref{sec:NameArgs} and~\ref{sec:NameArgMacros}). Thus, this section and its subsection are the most critical to understanding and mastering the use of \textsf{nameauth}.
%
-% Using \textsf{nameauth}\Illus{} allows one to use names according to one's culture of origin. The name arguments in this section are used in many \textsf{nameauth} macros.
% \begin{itemize}
-% \item The name form's required arguments are shown below in \emph{black}, with optional elements shown in \emph{\color{nared}red}.
-% \item If the required argument \meta{SNN} expands to the empty string, \textsf{nameauth} will generate a package error.
+% \item If the required argument \meta{SNN} is empty, \textsf{nameauth}
+% issues a package error, even when the \meta{Affix} part of an
+% \meta{SNN}, \meta{Affix} pair is not empty.
% \item Extra spaces around each argument are stripped.
-% \item Always include all name arguments to have consistent index entries.
-% \item \cmd{\Name} prints first uses of names long, then short thereafter. \cmd{\Name*} always creates a long form. \cmd{\FName} prints a short form in later uses.
-% \end{itemize}\leavevmode
+% \item Include name arguments consistently to have consistent
+% index entries.
+% \item For all name forms, see Section~\ref{sec:FinalOptargs} regarding
+% final optional arguments.
+% \end{itemize}
+%
+% \subsubsection{Western Names}
+% \negsmallskip
%
-% \begin{tcolorbox}[colframe=naslate,adjusted title={\large\hfil Western Name}]\centering
+% \begin{tcolorbox}[colframe=naslate]\centering\small
% \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{ }}\\ \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}}
+% & Required & Required \meta{SNN} & Optional\\
+% & \meta{FNN} & optional \meta{Affix} & (text only)\\[1ex]
+% \tcbox[equal height group=D,colback=white,tikznode,
+% left=1mm,right=1mm,valign=center]
+% {\normalsize\bfseries \hbox{\cmd{\Name}\texttt{ }}\\
+% \cmd{\Name*}\\
+% \cmd{\FName}} &
+% \tcbox[equal height group=D,colback=white,tikznode,
+% left=1mm,right=1mm,valign=center]
+% {\normalsize\bfseries\oarg{FNN}} &
+% \tcbox[equal height group=D,colback=white,tikznode,
+% left=1mm,right=1mm,valign=center]
+% {\normalsize\bfseries\marg{SNN\color{nared}, Affix}} &
+% \tcbox[equal height group=D,colback=white,tikznode,
+% left=1mm,right=1mm,valign=center]
+% {\normalsize\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}\medskip
%
% \noindent
% Within \textsf{nameauth}, Western names have distinct features:
+%
% \begin{itemize}
% \item Western names must use the first optional \meta{FNN} argument.
-% \item They require a comma to delimit any affixes (Section~\ref{sec:Affix}).
-% \item Western index entries have two general forms: \meta{SNN}, \meta{FNN} and \meta{SNN}, \meta{FNN}, \meta{Affix}.
-% \item They do not share control patterns (Section~\ref{sec:NamePatterns}) and index entry forms with non-Western names.
-% \end{itemize}\smallskip
+% \item They require a comma to delimit any affixes
+% (Section~\ref{sec:Affix}).
+% \item Western index entries have two general forms:
+% \begin{itemize}
+% \item[] \meta{SNN}, \meta{FNN}
+% \item[] \meta{SNN}, \meta{FNN}, \meta{Affix}
+% \end{itemize}
+% \item They have Western name patterns (Section~\ref{sec:NamePatterns})
+% and index entry forms.
+% \end{itemize}
%
-% \bgroup\MyStretch\noindent
-% |\Name [George]{Washington}|\SPatInfo{\ShowPattern[George]{Washington}\break\ShowPattern[George S.]{Patton, Jr.}}\dotfill \Name [George]{Washington}\\
-% |\Name*[George]{Washington}|\dotfill \Name*[George]{Washington}\\
-% |\Name [George]{Washington}|\dotfill \Name [George]{Washington}\\
-% |\FName[George]{Washington}|\IdxInfo{\ShowIdxPageref*[George]{Washington}\break\ShowIdxPageref*[George S.]{Patton, Jr.}}\dotfill \FName[George]{Washington}\medskip\\
-% |\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.}^^A
-% \egroup\medskip
-%
-% Below, \meta{Alternate} swaps with \meta{FNN} only in the text. Alternate forenames print in the text with a first use, \cmd{\Name*}, or \cmd{\FName}. Use \cmd{\DropAffix}, a prefix macro (Section~\ref{sec:SelectOver}), to drop affixes in long name forms, but only in the text.\medskip
-% \newpage
+% \subsubsection*{\hfil Full, Last, and First Names}
+%
+% \cmd{\Name} prints first uses of names long, then short thereafter. \cmd{\Name*} ensures a long form. \cmd{\FName} prints long in first uses, then just a forename in later uses. \cmd{\FName*} does the same thing as \cmd{\FName} (just add an \texttt{F}\dots). The affix in a surname only appears in long name references.
+%
+% \begin{Block}
+% \vspace{3.5ex}
+% \BothInfo{\ShowPattern[George]{Washington}\break
+% \ShowPattern[George S.]{Patton, Jr.}}
+% {\ShowIdxPageref*[George]{Washington}\break
+% \ShowIdxPageref*[George S.]{Patton, Jr.}}
+% \vspace{-3.5ex}
+% \FUse |\Name [George]{Washington}|\dotfill \Name [George]{Washington}\\
+% \LUse |\Name*[George]{Washington}|\dotfill \Name*[George]{Washington}\\
+% \LUse |\Name [George]{Washington}|\dotfill \Name [George]{Washington}\\
+% \LUse |\FName[George]{Washington}|\dotfill \FName[George]{Washington}
+% \end{Block}\negmedskip
+%
+% \begin{Block}
+% \FUse |\Name [George S.]{Patton, Jr.}|\dotfill
+% \Name [George S.]{Patton, Jr.}\\
+% \LUse |\Name*[George S.]{Patton, Jr.}|\dotfill
+% \Name*[George S.]{Patton, Jr.}\\
+% \LUse |\Name [George S.]{Patton, Jr.}|\dotfill
+% \Name [George S.]{Patton, Jr.}\\
+% \LUse |\FName[George S.]{Patton, Jr.}|\dotfill
+% \FName[George S.]{Patton, Jr.}
+% \end{Block}
+%
+% \subsubsection*{\hfil Affixes and Alternate Forms}
+%
+% In a long name reference, \cmd{\DropAffix} drops a name affix from a Western name. The \meta{Alternate} argument permits changes in the text only for long references and forename-only references. Otherwise, the automatic shortening of names will display only a short surname.
%
-% \bgroup\MyStretch\noindent
-% |\Name*[George S.]{Patton, Jr.}|\SPatInfo{\ShowPattern[George S.]{Patton, Jr.}\break \ShowPattern[J.D.]{Rockefeller, IV}\break \ShowPattern[Clive Staples]{Lewis}}\dotfill \Name*[George S.]{Patton, Jr.}\\
-% |\DropAffix\Name*[George S.]{Patton, Jr.}[George]|\dotfill \DropAffix\Name*[George S.]{Patton, Jr.}[George]\medskip\\
-% |\Name [J.D.]{Rockefeller, IV}|\dotfill \Name [J.D.]{Rockefeller, IV}\\
-% |\Name*[J.D.]{Rockefeller, IV}[John David]|\dotfill \Name*[J.D.]{Rockefeller, IV}[John David]\\
-% \vspace{-2ex}\IdxInfo{\ShowIdxPageref*[George S.]{Patton, Jr.}\break \ShowIdxPageref*[J.D.]{Rockefeller, IV}\break \ShowIdxPageref*[Clive Staples]{Lewis}}\vspace{2ex}|\DropAffix\Name*[J.D.]{Rockefeller, IV}[Jay]|\dotfill \DropAffix\Name*[J.D.]{Rockefeller, IV}[Jay]\\
-% |\Name [J.D.]{Rockefeller, IV}[Jay]|\dotfill \Name [J.D.]{Rockefeller, IV}[Jay]\medskip\\
-% |\Name [Clive Staples]{Lewis}|\dotfill \Name [Clive Staples]{Lewis}\\
-% |\Name*[Clive Staples]{Lewis}[C.S.]|\dotfill \Name*[Clive Staples]{Lewis}[C.S.]\\
-% |\FName[Clive Staples]{Lewis}[Jack]|\dotfill \FName[Clive Staples]{Lewis}[Jack]^^A
-% \egroup\medskip
-%
-% Use the first name for sorting names instead of the initials, as with \DropAffix\Name*[J.D.]{Rockefeller, IV}: |\PretagName[J.D.]{Rockefeller, IV}{Rockefeller, John D 4}| (Section~\ref{sec:IndexSort}).
-% For alternate surnames see Sections~\ref{sec:VarNames}, \ref{sec:NameAncient}, \ref{sec:AltAdvanced}, \ref{sec:Hooksiii}.
-% \medskip
+% \begin{itemize}
+% \vspace{5ex}
+% \BothInfo{\ShowPattern[George S.]{Patton, Jr.}\break
+% \ShowPattern[J.D.]{Rockefeller, IV}\break
+% \ShowPattern[Clive Staples]{Lewis}}
+% {\ShowIdxPageref*[George S.]{Patton, Jr.}\break
+% \ShowIdxPageref*[J.D.]{Rockefeller, IV}\break
+% \ShowIdxPageref*[Clive Staples]{Lewis}}
+% \vspace{-5ex}
+% \item Drop the affix in a long name reference:\\[1ex]
+% \FUse |\DropAffix\Name*[George S.]{Patton, Jr.}|\dotfill\hbox{}\\
+% \hbox{}\dotfill \ForgetThis\DropAffix\Name*[George S.]{Patton, Jr.}\\
+% \LUse |\DropAffix\Name*[George S.]{Patton, Jr.}|\dotfill\hbox{}\\
+% \hbox{}\dotfill \DropAffix\Name*[George S.]{Patton, Jr.}
+% \item Use an alternate forename in a long name or forename
+% reference:\\[1ex]
+% \FUse \cmd{\Name[J.D.]\{Rockefeller, IV\}[John Davison]}\dotfill
+% \hbox{}\\
+% \hbox{}\dotfill\Name[J.D.]{Rockefeller, IV}[John Davison]\\
+% \LUse |\FName[George S.]{Patton, Jr.}[George]|\dotfill
+% \FName[George S.]{Patton, Jr.}[George]
+% \item Drop the affix and alter the forenames:\\[1ex]
+% \FUse |\DropAffix\Name*[J.D.]{Rockefeller, IV}[Jay]|\dotfill\hbox{}\\
+% \hbox{}\dotfill\ForgetThis\DropAffix\Name*[J.D.]{Rockefeller, IV}[Jay]
+% \LUse |\DropAffix\Name*[J.D.]{Rockefeller, IV}[Jay]|\dotfill\hbox{}\\
+% \hbox{}\dotfill\DropAffix\Name*[J.D.]{Rockefeller, IV}[Jay]
+% \item Use multiple alternate forenames for the same person:\\[1ex]
+% \FUse |\Name [Clive Staples]{Lewis}|\dotfill \Name [Clive Staples]{Lewis}\\
+% \LUse |\Name*[Clive Staples]{Lewis}[C.S.]|\dotfill
+% \Name*[Clive Staples]{Lewis}[C.S.]\\
+% \LUse |\FName[Clive Staples]{Lewis}[Jack]|\dotfill
+% \FName[Clive Staples]{Lewis}[Jack]
+% \end{itemize}
+% \negmedskip
+%
+% To sort the index consistently and properly, all names should be sorted by their longest unique name forms and by the Arabic equivalents of Roman numerals. See Section~\ref{sec:NameMedieval}, \ref{sec:IndexSort}, \ref{sec:IndexInitials}, \ref{sec:VarNames}. and all of Section~\ref{sec:AdvancedFormat}.
+%
+% \begin{itemize}
+% \item[] For example, with the name \LJRIV:
+% \item The initials \texttt{J.D.} become \texttt{John D} in the sort tag.
+% \item The affix \texttt{IV} becomes \texttt{4}.
+% \item |\PretagName[J.D.]{Rockefeller, IV}{Rockefeller, John D 4}|
+% \end{itemize}
%
-% \begin{tcolorbox}[colframe=naslate,adjusted title={\large\hfil ``Non-native'' Eastern Name}]\centering
+% \begin{Quote}{\ForgetThis\Wash, Farewell Address (1796)}
+% The alternate domination of one faction over another, sharpened by the spirit of revenge, \dots is itself a frightful despotism. But this leads at length to a more formal and permanent despotism. The disorders and miseries, which result, gradually incline the minds of men to seek security and repose in the absolute power of an individual; and sooner or later the chief of some prevailing faction, more able or more fortunate than his competitors, turns this disposition to the purposes of his own elevation, on the ruins of Public Liberty.
+% \end{Quote}
+%
+% \subsubsection[Reversed Western]{Reversed Western Names}
+% \negsmallskip
+%
+% \begin{tcolorbox}[colframe=naslate]\centering\small
% \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{ }}\\ \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}}
+% & Required & Required \meta{SNN} & Optional\\
+% & \meta{FNN} & no \meta{Affix} & (text only)\\[1ex]
+% \tcbox[equal height group=D,colback=white,tikznode,
+% left=1mm,right=1mm,valign=center]
+% {\normalsize\bfseries \hbox{\cmd{\Name}\texttt{ }}\\
+% \cmd{\Name*}\\
+% \cmd{\FName}} &
+% \tcbox[equal height group=D,colback=white,tikznode,
+% left=1mm,right=1mm,valign=center]
+% {\normalsize\bfseries\oarg{FNN}} &
+% \tcbox[equal height group=D,colback=white,tikznode,
+% left=1mm,right=1mm,valign=center]
+% {\normalsize\bfseries\quad\marg{SNN}\quad\hbox{}} &
+% \tcbox[equal height group=D,colback=white,tikznode,
+% left=1mm,right=1mm,valign=center]
+% {\normalsize\bfseries\oarg{\color{nared}Alternate}}
% \end{tabular}
-%
-% Add braces \texttt{\bfseries\{\,\}} after {\bfseries\marg{SNN}} if other text in brackets \texttt{\bfseries[\,]} follows.
% \end{tcolorbox}\medskip
%
% \noindent
-% ``Non-native'' Eastern names (Section~\ref{sec:Eastern}) have these features:
+% Reversed Western names (Section~\ref{sec:RevNames}) have these features:
+%
% \begin{itemize}
% \item They must use the first optional \meta{FNN} argument.
-% \item They cannot use affixes; one would get \meta{FNN} \meta{Affix} \meta{SNN}.
-% \item Index entries have the Western form with no affix: \meta{SNN}, \meta{FNN}.
-% \item They do not share control patterns and index entry forms with non-Western names.
-% \item They do not work with the obsolete syntax (Section~\ref{sec:Obsolete}).
+% \item Avoid using affixes in order to avoid odd name forms. One also
+% could use \cmd{\DropAffix} (Section~\ref{sec:Affix}), but that would
+% not affect index entries.
+% \item Index entries have the Western form: \meta{SNN}, \meta{FNN}.
+% \item They have Western name patterns and index entry forms.
+% \item They do not work with the obsolete syntax
+% (Section~\ref{sec:Obsolete}).
% \end{itemize}
-% % Below we start with Western name forms:\medskip
-%
-% \bgroup\noindent\MyStretch
-% |\Name [Hideyo]{Noguchi}|\SPatInfo{\ShowPattern[Hideyo]{Noguchi}\break\ShowPattern[Frenec]{Molnár}}\dotfill \Name [Hideyo]{Noguchi}\hbox to 0.45em{\hfill}\\
-% |\Name*[Hideyo]{Noguchi}[Doctor]|\dotfill \Name*[Hideyo]{Noguchi}[Doctor]\hbox to 0.45em{\hfill}\\
-% |\Name [Frenec]{Molnár}|\dotfill \Name [Frenec]{Molnár}\footnote{With \texttt{pdflatex} and \texttt{latex}, in \texttt{\ShowPattern[Frenec]{Molnár}} the glyphs \texttt{Ãą} correspond to \cmd{\IeC\{\textbackslash\textquotesingle a\}}.}^^A
-% \egroup\medskip
-%
-% \vspace{1.5ex}\IdxInfo{\ShowIdxPageref*[Hideyo]{Noguchi}\break\ShowIdxPageref*[Frenec]{Molnár}}\vspace{-1.5ex}\noindent We use the prefix macros \cmd{\RevName} and optionally \cmd{\CapName} (Section~\ref{sec:SelectOver}) to print an Eastern or Hungarian name order in the text [\hyperlink{Mulvany}{Mulvany}, 166]. We see above that these macros work in context, not arbitrarily:\medskip
-%
-% \bgroup\vspace{2.4ex}\Info{Same name patterns and\break index entries as above.}\vspace{-2.4ex}\MyStretch\noindent
-% |\CapName\RevName\Name*[Hideyo]{Noguchi}[Sensei]|\dotfill \CapName\RevName\Name*[Hideyo]{Noguchi}[Sensei]\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\\
-% |\RevName\Name [Frenec]{Molnár}|\dotfill \RevName\Name [Frenec]{Molnár}\dag^^A
-% \egroup
-% \newpage
%
-% \begin{tcolorbox}[colframe=naslate,adjusted title={\large\hfil ``Native'' Eastern Name}]\centering
+% \subsubsection*{\hfil Starting with Western Name Forms}
+%
+% \leavevmode^^A
+% \BothInfo{\ShowPattern[Frenec]{Molnár}\break
+% \ShowPattern[Hideyo]{Noguchi}}
+% {\ShowIdxPageref*[Hideyo]{Noguchi}\break
+% \ShowIdxPageref*[Frenec]{Molnár}}
+% These reversed Western forms are used optimally in a context where Hungarian names and similar cases of name order appear in a document because their index entries take a Western form [\hyperlink{Mulvany}{Mulvany}, 166].\footnote{Regarding the margin note that shows name control sequences, with \texttt{pdflatex} and \texttt{latex}, in \texttt{\ShowPattern[Frenec]{Molnár}} the glyphs \texttt{Ãą} correspond to \cmd{\IeC\{\textbackslash\textquotesingle a\}}.}
+%
+% \begin{Block}
+% \FUse |\Name [Frenec]{Molnár}|\dotfill \Name [Frenec]{Molnár}\\
+% \FUse |\Name [Hideyo]{Noguchi}|\dotfill \Name [Hideyo]{Noguchi}\\
+% \LUse |\Name*[Hideyo]{Noguchi}[Doctor]|\dotfill \Name*[Hideyo]{Noguchi}[Doctor]
+% \end{Block}
+%
+% \subsubsection*{\hfil Using the Reversing Macros}
+%
+% \noindent We use the prefix macros \cmd{\RevName} and optionally \cmd{\CapName} (Section~\ref{sec:SelectOver}) to print a Hungarian or ``non-native'' Eastern name in the text while keeping Western forms in the index. These macros, as is the case with many \textsf{nameauth} macros, work properly in context, not arbitrarily:
+%
+% \begin{Block}
+% \LUse |\RevName\Name*[Frenec]{Molnár}\dag|\Same\dotfill
+% \RevName\Name*[Frenec]{Molnár}\dag\\
+% \LUse |\RevName\Name [Frenec]{Molnár}\dag|\dotfill
+% \RevName\Name [Frenec]{Molnár}\dag\\
+% \LUse |\CapName\RevName\Name*[Hideyo]{Noguchi}[Sensei]\dag|\dotfill\\
+% \hbox{}\dotfill \CapName\RevName\Name*[Hideyo]{Noguchi}[Sensei]\dag\\
+% \LUse |\CapName\RevName\Name [Hideyo]{Noguchi}[Sensei]\dag|\dotfill\\
+% \hbox{}\dotfill \CapName\RevName\Name [Hideyo]{Noguchi}[Sensei]\dag
+% \end{Block}
+%
+% If Western names are reversed to have Eastern order, they will have Eastern name order in the text, but \emph{they will retain Western-form index entries.} The reversing macros help when a publication uses only Western name entries in the index, or when printing and indexing names with requirements like Hungarian names.
+%
+% \subsubsection{Eastern Names}
+%
+% All non-Western name forms in \textsf{nameauth} have the syntax: \meta{SNN,Affix}. In Eastern names, \meta{SNN} refers to a family name and \meta{Affix} to a personal name. Otherwise, \meta{SNN} refers to a person's name and \meta{Affix} to added information. Knowing this difference helps one avoid nonsense names.\medskip
+%
+% \negsmallskip\begin{tcolorbox}[colframe=naslate]\centering\small
% \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{ }}\\ \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}}
+% & Required \meta{SNN} & Optional\\
+% & required \meta{Affix} & (text only)\\[1ex]
+% \tcbox[equal height group=D,colback=white,tikznode,
+% left=1mm,right=1mm,valign=center]
+% {\normalsize\bfseries \hbox{\cmd{\Name}\texttt{ }}\\
+% \cmd{\Name*}\\
+% \cmd{\FName}} &
+% \tcbox[equal height group=D,colback=white,tikznode,
+% left=1mm,right=1mm,valign=center]
+% {\normalsize\bfseries\marg{SNN, Affix}} &
+% \tcbox[equal height group=D,colback=white,tikznode,
+% left=1mm,right=1mm,valign=center]
+% {\normalsize\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}\medskip
%
% \noindent
-% These features denote ``native'' Eastern names in \textsf{nameauth}:
+% These features denote ``native'' Eastern names in \textsf{nameauth} (Sections~\ref{sec:Eastern}, \ref{sec:RevNames}):
+%
% \begin{itemize}
% \item They must \emph{leave empty} the \meta{FNN} argument.
% \item They use instead the \meta{SNN, Affix} arguments.
% \item Their index entries take the non-Western form: \meta{SNN Affix}.
-% \item They do not share control patterns and index entry forms with both Western names and ``non-native'' Eastern names.
+% \item Names with the form \meta{SNN, Affix} can use the \meta{Alternate}
+% argument to swap \meta{Affix} with \meta{Alternate}.
+% \item They have non-Western name patterns and index entry forms.
% \end{itemize}
%
-% The basic forms of ``native'' Eastern names are shown below. Notice that the macro \cmd{\FName} does not show the personal name by default. This design choice helps to prevent one from naively causing offense:\medskip
-%
-% \bgroup\MyStretch\noindent
-% \SPatInfo{\ShowPattern{Miyazaki, Hayao}}|\Name {Miyazaki, Hayao}|\dotfill \Name {Miyazaki, Hayao}\\
-% |\Name {Miyazaki, Hayao}|\dotfill \Name {Miyazaki, Hayao}\\
-% \IdxInfo{\ShowIdxPageref*{Miyazaki, Hayao}}|\FName{Miyazaki, Hayao}|\dotfill \FName{Miyazaki, Hayao}^^A
-% \egroup\medskip
-%
-% If ``Native'' Eastern names are reversed, they will have Western name order in the text, but \emph{they will retain Eastern-form index entries.}
+% \subsubsection*{\hfil ``Native'', Reversible Eastern Name Forms}
+%
+% Among the names shown below, \cmd{\FName} does not show a personal name by default. This design helps to prevent Western writers from being culturally insensitive.
+%
+% \begin{Block}
+% \vspace{3.5ex}
+% \BothInfo{\ShowPattern{Miyazaki, Hayao}}
+% {\ShowIdxPageref*{Miyazaki, Hayao}}
+% \vspace{-3.5ex}
+% \FUse |\Name {Miyazaki, Hayao}|\dotfill
+% \ForgetThis\Name {Miyazaki, Hayao}\\
+% \LUse |\Name {Miyazaki, Hayao}|\dotfill \Name {Miyazaki, Hayao}\\
+% \LUse |\Name*{Miyazaki, Hayao}[Sensei]|\dotfill
+% \Name*{Miyazaki, Hayao}[Sensei]\\
+% \LUse |\FName{Miyazaki, Hayao}|\dotfill \FName{Miyazaki, Hayao}
+% \end{Block}
+%
+% One must use \cmd{\ForceFN} with \cmd{\FName} (Section~\ref{sec:FName}) to get a personal name. \meta{Alternate} swaps with \meta{FNN} (in both long forms and in short forms) in the text only. \meta{Alternate} does not work with the obsolete syntax (Section~\ref{sec:Obsolete}):
+%
+% \begin{Block}
+% \LUse |\ForceFN\FName{Miyazaki, Hayao}|\Same\dotfill
+% \ForceFN\FName{Miyazaki, Hayao}\\
+% \LUse |\CapName\Name*{Miyazaki, Hayao}[Sensei]|\dotfill
+% \CapName\Name*{Miyazaki, Hayao}[Sensei]\\
+% \LUse |\ForceFN\FName{Miyazaki, Hayao}[Sensei]|\dotfill
+% \ForceFN\FName{Miyazaki, Hayao}[Sensei]\\
+% \LUse |\RevName\Name*{Miyazaki, Hayao}[Mr.]|\dotfill
+% \RevName\Name*{Miyazaki, Hayao}[Mr.]
+% \end{Block}
+%
+% If ``native'' Eastern names are reversed, they will have Western name order in the text, but \emph{they will retain Eastern-form index entries.}
+%
+% \begin{Quote}{\Name[Harold]{Urey} (1961)}
+% The space program is not only scientific in purpose but also is an expression of man's insistent determination to do the nearly impossible\,---\,to explore the unknown, even at great risk.\vspace{-1ex}
+% \end{Quote}
%
-% One must use the prefix macro \cmd{\ForceFN} (Section~\ref{sec:SelectOver}) with \cmd{\FName} to get a personal name. \meta{Alternate} swaps with \meta{FNN} (in long forms and in short forms using \cmd{\ForceFN}) in the text only. \meta{Alternate} does not work with the obsolete syntax (Section~\ref{sec:Obsolete}):\medskip
-%
-% \bgroup\vspace{2.4ex}\Info{Same name patterns and\break index entries as above.}\vspace{-2.4ex}\MyStretch\noindent
-% |\ForceFN\FName{Miyazaki, Hayao}|\dotfill \ForceFN\FName{Miyazaki, Hayao}\\
-% |\CapName\Name*{Miyazaki, Hayao}[Sensei]|\dotfill \CapName\Name*{Miyazaki, Hayao}[Sensei]\\
-% |\ForceFN\FName{Miyazaki, Hayao}[Sensei]|\dotfill \ForceFN\FName{Miyazaki, Hayao}[Sensei]\\
-% |\RevName\Name*{Miyazaki, Hayao}[Mr.]|\dotfill \RevName\Name*{Miyazaki, Hayao}[Mr.]^^A
-% \egroup\medskip
-%
-% ``Native'' Eastern names have the same kind of macro parameters as do royal, medieval, and ancient names from Europe and the Near East (below). From the standpoint of how the macros work, one can identify ``non-western'' names with the form \meta{SNN, Affix}.
-%
-% Yet one should not confuse similarity in form with similarity in what the names themselves mean. Even though the syntactic form of non-Western names works the same, that form has different meanings in different contexts. For one context, \meta{SNN, Affix} refers to a family name and a personal name. For another context, \meta{SNN, Affix} refers to a person's name and any affixes thereto.
% \newpage
%
-% \begin{tcolorbox}[colframe=naslate,adjusted title={\large\hfil Royal/Medieval/Ancient Name}]\centering
+% \subsubsection[Ancient Names]{Royal, Medieval, and Ancient Names}
+% \negsmallskip
+%
+% \begin{tcolorbox}[colframe=naslate]\centering\small
% \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{ }}\\ \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}}
+% & Required \meta{SNN} & Optional,\\
+% & optional \meta{Affix} & special\\[1ex]
+% \tcbox[equal height group=D,colback=white,tikznode,
+% left=1mm,right=1mm,valign=center]
+% {\normalsize\bfseries \hbox{\cmd{\Name}\texttt{ }}\\
+% \cmd{\Name*}\\
+% \cmd{\FName}} &
+% \tcbox[equal height group=D,colback=white,tikznode,
+% left=1mm,right=1mm,valign=center]
+% {\normalsize\bfseries\marg{SNN\color{nared}, Affix}} &
+% \tcbox[equal height group=D,colback=white,tikznode,
+% left=1mm,right=1mm,valign=center]
+% {\normalsize\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}\medskip
%
% \noindent
% These features denote royal, medieval, and ancient names in \textsf{nameauth}, grouped under the general rubric of ``non-Western'' name forms:
+%
% \begin{itemize}
% \item They must \emph{leave empty} the \meta{FNN} argument.
-% \item They use instead the \meta{SNN, Affix} arguments or just \meta{SNN}.
-% \item Their index entries take the non-Western forms: \meta{SNN Affix} or \meta{SNN}.
-% \item Names\Version{3.0} with the form \meta{SNN, Affix} can use the \meta{Alternate} argument.
-% \item Names with the form \meta{SNN} cannot use \meta{Alternate}.
-% \item They do not share control patterns and index entry forms with both Western names and ``non-native'' Eastern names.
+% \item They use either the \meta{SNN, Affix} arguments or just \meta{SNN}.
+% \item Their index entries take the non-Western forms: \meta{SNN Affix}
+% or \meta{SNN}.
+% \item Names with the form \meta{SNN, Affix} can use the \meta{Alternate}
+% argument to swap \meta{Affix} with \meta{Alternate}.
+% \item Names with the form \meta{SNN} should not use \meta{Alternate}
+% (cf. Section~\ref{sec:Obsolete}).
+% \item They have non-Western name patterns and index entry forms.
+% \item One generally does not reverse these names (Section~\ref{sec:RevNames}).
% \end{itemize}
%
-% As with ``native'' Eastern names, \cmd{\FName} prints \meta{SNN} unless forced otherwise by \cmd{\ForceFN}. This guards against nonsense names in the text:\medskip
+% \subsubsection*{\hfil No School Like the Old School}
%
-% \bgroup\MyStretch\noindent
-% |\Name {Elizabeth, I}|\SPatInfo{\ShowPattern{Elizabeth, I}\break \ShowPattern{John, Eriugena}\break \ShowPattern{Aristotle}}\dotfill \Name {Elizabeth, I}\\
-% |\Name {Elizabeth, I}|\dotfill \Name {Elizabeth, I}\\
-% |\FName{Elizabeth, I}|\dotfill \FName{Elizabeth, I}\\
-% |\ForceFN\FName{Elizabeth, I}|\dotfill \ForceFN\FName{Elizabeth, I}\\
-% |\ForceFN\FName{Elizabeth, I}[Good Queen Bess]|\IdxInfo{\ShowIdxPageref*{Elizabeth, I}\break \ShowIdxPageref*{John, Eriugena}\break \ShowIdxPageref*{Aristotle}}\dotfill \ForceFN\FName{Elizabeth, I}[Good Queen Bess]\medskip\\% |\Name{John, Eriugena}|\dotfill \Name{John, Eriugena}\\
-% |\Name{John, Eriugena}|\dotfill \Name{John, Eriugena}\\
-% |\ForceFN\FName{John, Eriugena}|\dotfill \ForceFN\FName{John, Eriugena}\medskip\\
-% |\Name{Aristotle}|\dotfill \Name{Aristotle}\\
-% |\Name{Aristotle}|\dotfill \Name{Aristotle}^^A
-% \egroup
+% \begin{itemize}
+% \vspace{3ex}
+% \BothInfo{\ShowPattern{Elizabeth, I}\break
+% \ShowPattern{John, Eriugena}\break
+% \ShowPattern{Aristotle}}
+% {\ShowIdxPageref*{Elizabeth, I}\break
+% \ShowIdxPageref*{John, Eriugena}\break
+% \ShowIdxPageref*{Aristotle}}
+% \vspace{-3ex}
+% \item \cmd{\FName} normally prints \meta{SNN} to avoid nonsense names
+% in the text.\\[1ex]
+% \FUse |\Name {Elizabeth, I}|\dotfill \Name {Elizabeth, I}\\
+% \LUse |\Name {Elizabeth, I}|\dotfill \Name {Elizabeth, I}\\
+% \LUse |\FName{Elizabeth, I}|\dotfill \FName{Elizabeth, I}
+%
+% \item Here we work with titles and sobriquets:\\[1ex]
+% \FUse |\ForgetThis\Name{Elizabeth, I}[I ``Gloriana'']|\dotfill\hbox{}\\
+% \hbox{}\dotfill \ForgetThis\Name{Elizabeth, I}[I ``Gloriana'']
+% \LUse |\ForceFN\FName{Elizabeth, I}[Gloriana]|\dotfill
+% \ForceFN\FName{Elizabeth, I}[Gloriana]
+%
+% \item Here we show a non-royal:\\[1ex]
+% \FUse |\Name {John, Eriugena}[Scotus Eriugena]|\dotfill\hbox{}\\
+% \hbox{}\dotfill \Name {John, Eriugena}[Scotus Eriugena]\\
+% \LUse |\Name*{John, Eriugena}|\dotfill \Name*{John, Eriugena}\\
+% \LUse |\Name {John, Eriugena}|\dotfill \Name {John, Eriugena}\\
+% \LUse |\ForceFN\FName{John, Eriugena}|\dotfill
+% \ForceFN\FName{John, Eriugena}
+%
+% \item These are nonsense names:\\[1ex]
+% \LUse |\ForceFN\FName{Elizabeth, I}|\dotfill
+% \ForceFN\FName{Elizabeth, I}\\
+% \LUse |\RevName\Name*{John, Eriugena}|\dotfill
+% \RevName\Name*{John, Eriugena}
+%
+% \item The trivial case:\\[1ex]
+% \FUse |\Name{Aristotle}|\dotfill \Name{Aristotle}\\
+% \LUse |\Name{Aristotle}|\dotfill \Name{Aristotle}
+% \end{itemize}
+%
+% \newpage
%
% \subsection{Quick Interface}
-% \label{sec:SimpleStart}
+% \label{sec:QuickUIStart}
+%
+% \subsubsection{Name Shorthands}
+%
% \DescribeEnv{nameauth}
% To reduce typing, we replace frequently-used macros with the shorthand forms of the quick interface. Using the \texttt{nameauth} environment in the preamble guards against undefined macros. It defines a delimited macro \cmd{\<}, recalling a \texttt{tabular}:
-% \begin{quote}
-% \fbox{
-% \begin{tabular}{l}
-% {\Large\strut}\cmd{\begin\{nameauth\}}\\
-% \hspace{2em}\cmd{\<} \meta{arg1} \texttt{\&} \meta{arg2}
-% \texttt{\&} \meta{arg3} \texttt{\&} \meta{arg4} \texttt{>}\vspace{-1pt}\\
-% {\Large\strut}\cmd{\end\{nameauth\}}\\
-% \end{tabular}
-% }
+%
+% \begin{SyntaxBox}
+% \cmd{\begin\{nameauth\}}\\
+% \hspace{2em}\cmd{\<} \meta{arg1} \texttt{\&}
+% \meta{arg2} \texttt{\&}
+% \meta{arg3} \texttt{\&}
+% \meta{arg4} \texttt{>}\\
+% \cmd{\end\{nameauth\}}
+% \end{SyntaxBox}
+%
+% In this context, \meta{arg1} becomes the root of three new macros per name:\medskip
+%
+% \begin{tabular}{@{\quad}l@{\ same as: }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
+%
+% Usually we leave \meta{arg4} empty, apart from specific contexts. That field permanently displays only alternate names, or is used with the obsolete syntax (Section~\ref{sec:Obsolete}). Here is another way of thinking about arguments in the \texttt{nameauth} environment that relates back to what we have seen:
+%
+% \begin{SyntaxBox}
+% \cmd{\begin\{nameauth\}}\\
+% \hspace{2em}\cmd{\<} \meta{arg1} \texttt{\&}
+% \meta{\color{nared}FNN} \texttt{\&}
+% \meta{SNN\color{nared}, Affix} \texttt{\&}
+% \meta{\color{nared}Alternate} \texttt{>}\\
+% \cmd{\end\{nameauth\}}
+% \end{SyntaxBox}
+%
+% By seeing the mandatory arguments in black and the optional ones in red, it helps us to see that, if either \meta{arg1} or \meta{arg3} are empty, or \meta{SNN} is empty, \textsf{nameauth} will generate a package error. Forgetting the backslash, any ampersand, or angle bracket will cause fatal errors. See Section~\ref{sec:FinalOptargs} on final optional arguments.\medskip
+%
+% Package warnings\Warn\ result when one redefines name shorthands using the \texttt{nameauth} environment. For example, we use \texttt{White} in two different rows to populate \meta{Arg1}. That causes \cmd{\White}, \cmd{\LWhite}, and \cmd{\SWhite} to be redefined:
+%
+% \begin{quote}\small
+% \begin{Verbatim}
+% \begin{nameauth}
+% \< White & E.B. & White & > % version 1
+% \< White & E.\,B. & White & > % version 2
+% \end{nameauth}
+% \end{Verbatim}
% \end{quote}
+% \begin{nameauth}
+% \< White & E.B. & White & > ^^A version 1
+% \< White & E.\,B. & White & > ^^A version 2
+% \end{nameauth}
+%
+% \cmd{\White} produces \White, the version with the thin space. We lost the first version of the name when we redefined it.\footnote{When building this package there should be a warning: \texttt{Shorthand macro already exists.} This is intentional, meant to test if the warning is working properly.}
+%
+% On the next page we will create an example \texttt{nameauth} environment using many of the names that we have so far encountered. We will add other names that we have not yet seen, introducing additional concepts in the process. Those include Western name forms that contain particles (usually prepositions or clan designators), which are discussed in greater detail in Section~\ref{sec:NameParticles}.
+%
% \newpage
-%
-% \noindent
-% The macro \cmd{\<} uses \meta{arg1} as a basis to create three new macros per name:\medskip
%
-% \begin{tabular}{@{\quad}l@{\ same as: }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, any ampersand, argument, or angle bracket will cause errors. The \meta{Alternate} field is \meta{arg4} (see below).
-%
-% Here we do not show the obsolete syntax (Section~\ref{sec:Obsolete}). Comments are not part of the \texttt{nameauth} environment. Extra spaces around each argument are stripped. Put trailing braces \texttt{\{\,\}} after the shorthand macros if text in brackets \texttt{[\,]} follows. We introduce Western name forms with particles (followed by {\color{nared}\textit{W. part.}}).\medskip
-%
-% \def\startrowa{\ \ \cmd{\< }}^^A
-% \def\startrowb{\color{nared}\% }^^A
-% \def\midrowa{\texttt{ \& }}^^A
-% \def\midrowb{\texttt{\ \ \ }}^^A
-% \def\endrowa{\texttt{ >}}^^A
-% \def\endrowb{}^^A
-% \def\startrow{\startrowb}^^A
-% \def\midrow{\midrowb}^^A
-% \def\endrow{\endrowb}^^A
-% \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}}\\
-% Lewis & Clive Staples & Lewis & &{\color{nared} \%
-% \normalfont\textit{Western}}\\
-% Pat & George S. & Patton, Jr. & &{\color{nared} \%
-% \normalfont\textit{W. affix}}\\
-% JRIV & J.D. & Rockefeller, IV & &{\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.}}\\
-% Molnar & Frenec & Molnár & &{\color{nared} \%
-% \normalfont\textit{W. as E.}}\\
-% Miyaz & & Miyazaki, Hayao & &{\color{nared} \%
-% \normalfont\textit{Eastern}}\\
-% Yamt & & Yamamoto, Isoroku & &{\color{nared} \%
-% \normalfont\textit{Eastern}}\\
-% Eliz & & Elizabeth, I & &{\color{nared} \%
-% \normalfont\textit{Royal}}\\
-% Aeth & & Æthelred, II & &{\color{nared} \%
-% \normalfont\textit{Royal}}\\
-% Eriugena & & John, Eriugena & &{\color{nared} \%
-% \normalfont\textit{Medieval}}\\
-% 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
-%
-% \begin{center}\bfseries \meta{Alternate} Tips\end{center}
-% \phantomsection
-% Two shorthands above use \meta{arg4}: \cmd{\CSL} and \cmd{\MSens}. Their similar forms \cmd{\Lewis} and \cmd{\Miyaz} leave \meta{arg4} empty. Here is how they are related:\label{page:ArgIV}
-% \begin{itemize}
-% \item They\SPatInfo{\ShowPattern[Clive Staples]{Lewis}\break \ShowPattern{Miyazaki, Hayao}} share name control patterns (Section~\ref{sec:NamePatterns}). Therefore, they have the same ``first-use'' and ``later-use'' conditions.
-% \item Usually, one adds alternate names to shorthands with an empty \meta{arg4}:\\[1ex]
-% \vspace{-7ex}\IdxInfo{\ShowIdxPageref*[Clive Staples]{Lewis}\break \ShowIdxPageref*{Miyazaki, Hayao}}\vspace{7ex}\leavevmode
-% \begin{tabular}{llll}\toprule
-% \cmd{\LLewis[C.S.]} & \LLewis[C.S.] & \cmd{\LCSL} & \LCSL\\
-% \rowcolor{grey}\cmd{\LMiyaz[Sensei]} & \LMiyaz[Sensei] & \cmd{\LMSens} & \LMSens\\\bottomrule
-% \end{tabular}
-% \item The field \meta{arg4} contains either \meta{Alternate} or uses the obsolete syntax. Trying to add ``alternate names'' to shorthands that use \meta{arg4} fails:\\[1ex]
-% \begin{tabular}{ll}\toprule
-% \cmd{\LCSL[Jack]} & \LCSL[Jack]\\
-% \rowcolor{grey}\cmd{\LMSens[Sensei]} & \LMSens[Sensei]\\\bottomrule
+% The comments below are merely explanatory and in no wise required to use the environment. Likewise, extra spaces that are added for clarity are stripped.
+%
+% \begin{quote}\small
+% \begin{Verbatim}
+% \begin{nameauth}
+% % Western Name Forms
+% % <arg1> <arg2> <arg3> <arg4>
+% \< Wash & George & Washington & >
+% \< Lewis & Clive Staples & Lewis & >
+% % Western Name Forms with Affixes
+% \< Patton & George S. & Patton, Jr. & >
+% \< JRIV & J.D. & Rockefeller, IV & >
+% % Western Name Forms with Particles
+% \< Soto & Hernando & de Soto & >
+% \< JWG & J.W. von & Goethe & >
+% \< VBuren & Martin & Van Buren & >
+% % Reversed Western Forms
+% \< Noguchi & Hideyo & Noguchi & >
+% \< Molnar & Frenec & Molnár & >
+% % ``Native'' Eastern Forms
+% \< Miyazaki & & Miyazaki, Hayao & >
+% % Royal, Medieval, and Ancient Forms
+% \< Eliz & & Elizabeth, I & >
+% \< Aeth & & Æthelred, II & >
+% \< Eriugena & & John, Eriugena & >
+% \< Aris & & Aristotle & >
+% % Name Forms Always Using Alternate Names
+% \< CSL & Clive Staples & Lewis & C.S. >
+% \< MSens & & Miyazaki, Hayao & Sensei >
+% \end{nameauth}
+% \end{Verbatim}
+% \end{quote}
+%
+% Here is an example of how much typing one can save with the quick interface, not to mention the prevention of error by not retyping arguments:
+% \begin{center}\small\medstretch
+% \begin{tabular}{rll}\toprule
+% Output & & Macro\\
+% \rowcolor{nagrey}\Wash & Quick: & \cmd{\Wash}\\
+% \rowcolor{nagrey} & Basic: &
+% \cmd{\Name}\texttt{[George]\{Washington\}}\\
+% \LWash & Quick: & \cmd{\LWash}\\
+% & Basic: &
+% \cmd{\Name*}\texttt{[George]\{Washington\}}\\
+% \rowcolor{nagrey}\SWash & Quick: & \cmd{\SWash}\\
+% \rowcolor{nagrey} & Basic: &
+% \cmd{\FName}\texttt{[George]\{Washington\}}\\
+% \ForgetThis\Wash & Quick: & \cmd{\ForgetThis}\cmd{\Wash}\\
+% & Basic: &
+% \cmd{\ForgetName}\texttt{[George]\{Washington\}}\\
+% & &
+% \cmd{\Name}\texttt{[George]\{Washington\}}\\
+% \rowcolor{nagrey}\ForgetThis\Wash & Quick: & \cmd{\ForgetThis}\cmd{\Wash}\\
+% \rowcolor{nagrey} & Basic: &
+% \cmd{\ForgetThis}\cmd{\Name}\texttt{[George]\{Washington\}}\\
+% \SubvertThis\Wash & Quick: & \cmd{\SubvertThis}\cmd{\Wash}\\
+% & Basic: &
+% \cmd{\SubvertName}\texttt{[George]\{Washington\}}\\
+% & &
+% \cmd{\Name}\texttt{[George]\{Washington\}}\\
+% \rowcolor{nagrey}\SubvertThis\Wash & Quick: & \cmd{\SubvertThis}\cmd{\Wash}\\
+% \rowcolor{nagrey} & Basic: &
+% \cmd{\SubvertThis}\cmd{\Name}\texttt{[George]\{Washington\}}\\
+% \JustIndex\Wash(unseen in text) & Quick: & \cmd{\JustIndex}\cmd{\Wash}\\
+% & Basic: &
+% \cmd{\IndexName}\texttt{[George]\{Washington\}}\\\bottomrule
% \end{tabular}
-% \end{itemize}
+% \end{center}
+%
+% \subsubsection[Name Variants]{Quick Name Variant Overview}
+%
+% After setting up the previous environment, we can use the resulting name shorthands. Below we introduce more ``prefix macros'' that affect syntactic forms of names. For the sake of clarity we use but do not show the prefix macro \cmd{\ForgetThis} (Section~\ref{sec:NameControl}), which produces a first use of a name.
+%
+% \vspace{4ex}
+% \BothInfo{\ShowPattern[George]{Washington}\break
+% \ShowPattern[Hernando]{de~Soto}\break
+% \ShowPattern[George S.]{Patton, Jr.}\break
+% \ShowPattern[J.D.]{Rockefeller, IV}\break
+% \ShowPattern[Clive Staples]{Lewis}\break
+% \ShowPattern{Aristotle}\break
+% \ShowPattern{Æthelred, II}\break
+% \ShowPattern{John, Eriugena}\break
+% \ShowPattern[Hideyo]{Noguchi}\break
+% \ShowPattern{Miyazaki, Hayao}}
+% {\ShowIdxPageref*[George]{Washington}\break
+% \ShowIdxPageref*[Hernando]{de~Soto}\break
+% \ShowIdxPageref*[George S.]{Patton, Jr.}\break
+% \ShowIdxPageref*[J.D.]{Rockefeller, IV}\break
+% \ShowIdxPageref*[Clive Staples]{Lewis}\break
+% \ShowIdxPageref*{Aristotle}\break
+% \ShowIdxPageref*{Æthelred, II}\break
+% \ShowIdxPageref*{John, Eriugena}\break
+% \ShowIdxPageref*[Hideyo]{Noguchi}\break
+% \ShowIdxPageref*{Miyazaki, Hayao}}
+% \vspace{-4ex}
+% \begin{Block}
+% \textsc{Western:} \hfill (Sections~\ref{sec:Naming},
+% \ref{sec:FName}\\
+% \FUse \cmd{\Wash}\dotfill \ForgetThis\Wash\\
+% \LUse \cmd{\LWash}\dotfill \LWash\\
+% \LUse \cmd{\Wash}\dotfill \Wash\\
+% \LUse \cmd{\SWash}\dotfill \SWash
+% \end{Block}
+%
+% \begin{Block}
+% \textsc{Nicknames and Affixes:} \hfill
+% (Sections~\ref{sec:FName}, \ref{sec:Affix})\\
+% \FUse \cmd{\DropAffix}\cmd{\Patton}\hfill
+% \ForgetThis\DropAffix\Patton\\
+% \LUse \cmd{\LPatton}\dotfill \LPatton\\
+% \LUse \cmd{\DropAffix}\cmd{\LPatton}\dotfill \DropAffix\LPatton\\
+% \LUse \cmd{\Patton}\dotfill \Patton\medskip
+%
+% \FUse \cmd{\Patton}\dotfill \ForgetThis\Patton\\
+% \LUse \cmd{\DropAffix}\cmd{\LPatton}\dotfill
+% \DropAffix\LPatton\\
+% \LUse \cmd{\DropAffix}\cmd{\LPatton[George]}\dotfill
+% \DropAffix\LPatton[George]\\
+% \LUse \cmd{\SPatton[George]}\dotfill \SPatton[George]\medskip
+%
+% \FUse \cmd{\JRIV[John Davison]}\dotfill
+% \ForgetThis\JRIV[John Davison]\\
+% \LUse \cmd{\LJRIV}\dotfill \LJRIV\\
+% \LUse \cmd{\DropAffix}\cmd{\LJRIV[Jay]}\dotfill
+% \DropAffix\LJRIV[Jay]\medskip
+%
+% \FUse \cmd{\Lewis}\dotfill \ForgetThis\Lewis\\
+% \LUse \cmd{\LLewis[C.S.]}\dotfill \LLewis[C.S.]\\
+% \LUse \cmd{\LLewis[Jack]}\dotfill \LLewis[Jack]\\
+% \LUse \cmd{\SLewis}\dotfill \SLewis\\
+% \LUse \cmd{\SLewis[Jack]}\dotfill \SLewis[Jack]\\
+% \LUse \cmd{\LCSL}\dotfill \LCSL\\
+% \LUse \cmd{\SCSL}\dotfill \SCSL
+% \end{Block}
+%
+% \begin{Block}
+% \textsc{``Native'' Eastern:} \hfill (Section~\ref{sec:Eastern})\\
+% \FUse \cmd{\CapName}\cmd{\Miyazaki}\dotfill
+% \ForgetThis\CapName\Miyazaki\\
+% \LUse \cmd{\CapName}\cmd{\LMiyazaki}\dotfill
+% \CapName\LMiyazaki\\
+% \LUse \cmd{\CapName}\cmd{\Miyazaki}\dotfill
+% \CapName\Miyazaki\\
+% \LUse \cmd{\RevName}\cmd{\LMiyazaki}\dotfill
+% \RevName\LMiyazaki\\
+% \LUse \cmd{\RevName}\cmd{\LMiyazaki[Mr.]}\dotfill
+% \RevName\LMiyazaki[Mr.]\\
+% \LUse \cmd{\SMiyazaki}\dotfill \SMiyazaki\\
+% \LUse \cmd{\ForceFN}\cmd{\SMiyazaki}\dotfill
+% \ForceFN\SMiyazaki
+% \end{Block}
+%
+% \begin{Block}
+% \textsc{Reversed Western:} \hfill (Section~\ref{sec:RevNames})\\
+% \FUse \cmd{\Noguchi}\dotfill \ForgetThis\Noguchi\\
+% \LUse \cmd{\LNoguchi}\dotfill \LNoguchi\\
+% \LUse \cmd{\LNoguchi[Doctor]}\dotfill \LNoguchi[Doctor]\\
+% \LUse \cmd{\SNoguchi}\dotfill \SNoguchi\\
+% \LUse \cmd{\RevName}\cmd{\LNoguchi}\cmd{\dag}\dotfill
+% \RevName\LNoguchi\dag\\
+% \LUse \cmd{\CapName}\cmd{\RevName}\cmd{\LNoguchi}\cmd{\dag}\dotfill
+% \CapName\RevName\LNoguchi\dag\\
+% \LUse \cmd{\CapName}\cmd{\Noguchi}\cmd{\dag}\dotfill
+% \CapName\Noguchi\dag
+% \end{Block}
+%
+% \begin{Block}
+% \textsc{Western, Reversed by Surname:} \hfill
+% (Section \ref{sec:LastFirst})\\
+% \FUse \cmd{\RevComma}\cmd{\LWash}\dotfill
+% \ForgetThis\RevComma\LWash\\
+% \LUse \cmd{\RevComma}\cmd{\LWash}\dotfill \RevComma\LWash
+% \end{Block}
+%
% \newpage
%
-% \begin{center}\bfseries How Quick Is Quick?\end{center}
-%
-% Prefix macros (Section~\ref{sec:SelectOver}) work with both interfaces. Here we show just a few examples showing how much typing we save with common macros:
-% \begin{center}\small\MyStretch
-% \begin{tabular}{r@{\ \ \ }l@{\ \ }l}\toprule
-% Output & Short Form & Long Form\\\midrule
-% \rowcolor{grey}\Wash & \cmd{\Wash} & \cmd{\Name}\texttt{[George]\{Washington\}}\\
-% \LWash & \cmd{\LWash} & \cmd{\Name*}\texttt{[George]\{Washington\}}\\
-% \rowcolor{grey}\SWash & \cmd{\SWash} & \cmd{\FName}\texttt{[George]\{Washington\}}\\
-% \ForgetThis\Wash & \cmd{\ForgetThis}\cmd{\Wash} & \cmd{\ForgetName}\texttt{[George]\{Washington\}}\\
-% & & \cmd{\Name}\texttt{[George]\{Washington\}}\\
-% \rowcolor{grey}\SubvertThis\Wash & \cmd{\SubvertThis}\cmd{\Wash} & \cmd{\SubvertName}\texttt{[George]\{Washington\}}\\
-% \rowcolor{grey}& & \cmd{\Name}\texttt{[George]\{Washington\}}\\
-% \JustIndex\Wash & \cmd{\JustIndex}\cmd{\Wash} & \cmd{\IndexName}\texttt{[George]\{Washington\}}\\\bottomrule
-% \end{tabular}
-% \end{center}\leavevmode
+% \begin{Block}
+% \textsc{Particles:} \hfill (Section~\ref{sec:NameParticles})\\
+% \LUse \cmd{\Soto}\dotfill \ForgetThis\Soto\\
+% \LUse \cmd{\Soto}\dotfill \Soto\\
+% \LUse \cmd{\CapThis}\cmd{\Soto}\dotfill \CapThis\Soto
+% \end{Block}
+%
+% \begin{Block}
+% \textsc{Royal and Medieval:} \hfill
+% (Section~\ref{sec:NameMedieval})\\
+% \LUse \cmd{\Aeth}\dotfill \ForgetThis\Aeth\footnote
+% {Regarding the margin note that shows name control sequences,
+% with \texttt{pdflatex} and \texttt{latex}, in
+% \texttt{\ShowPattern{Æthelred, II}} the glyphs \texttt{ÃĘ}
+% correspond to \cmd{\IeC\{}\cmd{\AE\}}.}\\
+% \LUse \cmd{\Aeth}\dotfill \Aeth\\
+% \LUse |\LAeth[II, ``Unræd'']|\dotfill
+% \LAeth[II, ``Unræd'']\\[1ex]
+% \LUse \cmd{\Eriugena[Scotus Eriugena]}\dotfill
+% \ForgetThis\Eriugena[Scotus Eriugena]\\
+% \LUse \cmd{\LEriugena}\dotfill \LEriugena\\
+% \LUse \cmd{\Eriugena}\dotfill \Eriugena
+% \end{Block}
+%
+% \begin{Block}
+% \textsc{Ancient Mononym} \hfill (trivial case)\\
+% \LUse \cmd{\Aris}\dotfill \ForgetThis\Aris\\
+% \LUse \cmd{\Aris}\dotfill \Aris
+% \end{Block}
+%
+% \subsubsection[\protect\textit{Alternate} Field]
+% {\protect\meta{Alternate} Name Field Tips}
+% \label{sec:ArgIV}
+%
+% \vspace{3ex}
+% \BothInfo{\ShowPattern[Clive Staples]{Lewis}\break
+% \ShowPattern{Miyazaki, Hayao}}
+% {\ShowIdxPageref*[Clive Staples]{Lewis}\break
+% \ShowIdxPageref*{Miyazaki, Hayao}}
+% \vspace{-3ex}
+% Two shorthands above use \meta{arg4}, the final field in each row of the \texttt{nameauth} environment. These are \cmd{\CSL} and \cmd{\MSens}. They correspond to similar name shorthands \cmd{\Lewis} and \cmd{\Miyazaki}, which leave \meta{arg4} empty. Here is how they are related:
%
-% \begin{center}\bfseries Name Variant Overview\end{center}
-% \phantomsection
+% \begin{itemize}
+% \item They share identical name control patterns
+% (Section~\ref{sec:NamePatterns}).\\[1ex]
+% \ForgetName{Miyazaki, Hayao}\ForgetName[Clive Staples]{Lewis}
+% First: \cmd{\MSens} \MSens; subsequent: \cmd{\Miyazaki} \Miyazaki.\\
+% First: \cmd{\CSL\ \ } \CSL;\hspace{2.2em}
+% subsequent: \cmd{\Lewis \ \ \ } \Lewis.
+% \item Usually, one leaves \meta{arg4} empty and adds alternate names in
+% brackets as needed: \cmd{\LLewis[C.S.]} \LLewis[C.S.]
+% \item By using \meta{arg4}, one trades less work for more ambiguity: Can
+% one add an alternate name or not? To answer that, one should keep track
+% of all name shorthands that use \meta{arg4}.
+% \item Failure to keep track of such macros creates output like
+% \cmd{\LCSL[Jack]} \LCSL[Jack] and \cmd{\LMSens[Sensei]} \LMSens[Sensei].
+% The reason why these macro versions produce undesired output is because
+% \meta{arg4} permanently populates \meta{Alternate}.
+% \item Bear also in mind that \meta{arg4} can be used for the obsolete
+% syntax, as mentioned previously, but we do not cover that here.
+% \end{itemize}
+%
+% \begin{Quote}{\ForgetThis\Miyazaki\break
+% \hbox{}\hfill Proposal for \textit{Princess Mononoke}}
+% We depict hatred, but it is to depict that there are more important things. We depict a curse, to depict the joy of liberation.
+% \end{Quote}
%
-% \vspace{-2ex}\Illus{}\vspace{2ex}Below we use \cmd{\ForgetThis} (Section~\ref{sec:NameControl}) to simulate first uses of names as needed, then proceed with subsequent uses:\footnote{With \texttt{pdflatex} and \texttt{latex}, in \texttt{\ShowPattern{Æthelred, II}} the glyphs \texttt{ÃĘ} correspond to \cmd{\IeC\{}\cmd{\AE\}}.}
-%
-% \begin{center}\footnotesize\MyStretch
-% \leavevmode\SPatInfo{\ShowPattern[George]{Washington}\break \ShowPattern[Hernando]{de~Soto}\break \ShowPattern[George S.]{Patton, Jr.}\break \ShowPattern[J.D.]{Rockefeller, IV}\break \ShowPattern[Clive Staples]{Lewis}\break \ShowPattern{Aristotle}\break \ShowPattern{Æthelred, II}\break \ShowPattern{John, Eriugena}\break \ShowPattern[Hideyo]{Noguchi}\break \ShowPattern{Yamamoto, Isoroku}}\vspace{-2.3ex}
-% \begin{tabular}{@{}p{18.4em}p{22.4em}@{}}
-% \textsc{Western:} \hfill (Sections~\ref{sec:Naming}, \ref{sec:FName})\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
-% &
-% \textsc{Ancient Mononym} \hfill (trivial case)\par
-% |\Aris|\dotfill \ForgetThis\Aris\par
-% |\Aris|\dotfill \Aris \par
-% (This is the trivial case.)\par\hbox{}\par
-% \textsc{Royal and Medieval:} \hfill (Sections~\ref{sec:Eastern}, \ref{sec:NameAncient})\par
-% |\Aeth|\dotfill \ForgetThis\Aeth\par
-% |\Aeth|\dotfill \Aeth\par
-% |\LAeth[Unrædig]|\dotfill \LAeth[Unrædig]\par
-% |\Eriugena|\dotfill \ForgetThis\Eriugena\par
-% |\Eriugena|\dotfill \Eriugena\par
-% \\
-% \end{tabular}
-% \leavevmode\vspace{2ex}\IdxInfo{\ShowIdxPageref*[George]{Washington}\break \ShowIdxPageref*[Hernando]{de~Soto}\break \ShowIdxPageref*[George S.]{Patton, Jr.}\break \ShowIdxPageref*[J.D.]{Rockefeller, IV}\break \ShowIdxPageref*[Clive Staples]{Lewis}\break \ShowIdxPageref*{Aristotle}\break \ShowIdxPageref*{Æthelred, II}\break \ShowIdxPageref*{John, Eriugena}\break \ShowIdxPageref*[Hideyo]{Noguchi}\break \ShowIdxPageref*{Yamamoto, Isoroku}}\vspace{-2.5ex}
-% \begin{tabular}{@{}p{18.4em}p{22.4em}@{}}
-% \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
-% \par\hbox{}\par
-% \textsc{Nicknames:} \hfill (Section~\ref{sec:FName})\par
-% |\DropAffix\LPat[George]|\dotfill \DropAffix\LPat[George]\par
-% |\SPat[George]|\dotfill \SPat[George]\par
-% |\JRIV[John D.]|\dotfill \ForgetThis\JRIV[John D.]\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{``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}\medskip
-% \end{center}
% \newpage
%
-% \subsection[Macro Overview]{Select Macro Overview}
+% \subsection{Select Macro Overview}
% \label{sec:SelectOver}
%
-% \begin{center}\bfseries Macros Taking Name Arguments\end{center}
-%
-% \begin{center}\small\MySmallStretch
-% \begin{tabular}{lrccl}\toprule
-% \llap{Naming\qquad}\meta{prefix macros} & \cmd{\Name} & \meta{optional *} & \meta{name args} & \\
-% \meta{prefix macros} & \cmd{\FName} & \meta{optional *} & \meta{name args} & \\
-% \rowcolor{grey}\llap{Page ref\qquad}\cmd{\SeeAlso} & \cmd{\IndexName} & & \meta{name args} & \\
-% \rowcolor{grey}\llap{Only cross-ref\qquad}\cmd{\SeeAlso} & \cmd{\IndexRef} & & \meta{xref args} & \meta{target}\\
-% \llap{Prevent page ref\qquad} & \cmd{\ExcludeName} & & \meta{name args} & \\
-% \llap{Enable page ref\qquad} & \cmd{\IncludeName} & \meta{optional *} & \meta{name args} & \\
-% \rowcolor{grey}\llap{Sort index\qquad}& \cmd{\PretagName} & & \meta{name args} & \meta{sort key} \\
-% \rowcolor{grey}\llap{Append idx tag\qquad}& \cmd{\TagName} & & \meta{name args} & \meta{tag} \\
-% \rowcolor{grey}\llap{Delete idx tag\qquad}& \cmd{\UntagName} & & \meta{name args} & \\
-% \llap{Make text tag\qquad} & \cmd{\NameAddInfo} & & \meta{name args} & \meta{tag} \\
-% \llap{Show text tag\qquad} & \cmd{\NameQueryInfo} & & \meta{name args} & \\
-% \llap{Delete text tag\qquad} & \cmd{\NameClearInfo} & & \meta{name args} & \\
-% \rowcolor{grey}\llap{Delete name cs\qquad} & \cmd{\ForgetName} & & \meta{name args} & \\
-% \rowcolor{grey}\llap{Create name cs\qquad} & \cmd{\SubvertName} & & \meta{name args} & \\
-% \llap{Name cs tests\qquad} & \cmd{\IfMainName} & & \meta{name args} & \marg{y}\marg{n}\\
-% & \cmd{\IfFrontName} & & \meta{name args} & \marg{y}\marg{n}\\
-% & \cmd{\IfAKA} & & \meta{name args} & \marg{y}\marg{n}\marg{x}\\
-% \rowcolor{grey}\llap{Debugging\qquad} & \cmd{\ShowPattern} & & \meta{name args} & \\
-% \rowcolor{grey} & \cmd{\ShowIdxPageref} & \meta{optional *} & \meta{name args} & \\\bottomrule
+% \subsubsection[With Name Args]{Macros with Name Arguments}
+% \label{sec:NameArgMacros}
+%
+% All macros that take name arguments (Section~\ref{sec:NameArgs}) will update \cmd{\NameauthPattern} (used in Section~\ref{sec:DataTemp}) and can have final optional arguments (Section~\ref{sec:FinalOptargs}). Those with additional starred forms are shown followed by a \texttt{*}. Optional prefix macros are shown in the next subsection.
+%
+% \begin{center}\medstretch
+% \begin{tabular}{lrcll}\toprule
+% Optional Prefix & Macro & & Arguments & \\
+% \rowcolor{nagrey}\llap{Naming\qquad}\meta{prefix macros} &
+% \cmd{\Name} & \texttt{*} & \meta{name args} & \\
+% \rowcolor{nagrey}\llap{\ul{\ \ \ \ \ \ \ \ \ \ \ \ }\qquad}^^A
+% \meta{prefix macros} &
+% \cmd{\FName} & \texttt{*} & \meta{name args} & \\
+% \llap{Page ref\qquad}\cmd{\SeeAlso} & \cmd{\IndexName} & &
+% \meta{name args} & \\
+% \llap{\ul{Only cross-ref}\qquad}\cmd{\SeeAlso} & \cmd{\IndexRef} & &
+% \meta{xref args} & \meta{target}\\
+% \rowcolor{nagrey}\llap{Prevent page ref\qquad} & \cmd{\ExcludeName} & &
+% \meta{name args} & \\
+% \rowcolor{nagrey}\llap{\ul{Enable page ref}\qquad} & \cmd{\IncludeName} &
+% \texttt{*} & \meta{name args} & \\
+% \llap{Sort index\qquad} & \cmd{\PretagName} & & \meta{name args} &
+% \meta{sort key} \\
+% \llap{Append idx tag\qquad} & \cmd{\TagName} & & \meta{name args} &
+% \meta{tag} \\
+% \llap{\ul{Delete idx tag}\qquad}& \cmd{\UntagName} & & \meta{name args} & \\
+% \rowcolor{nagrey}\llap{Make data tag\qquad} & \cmd{\NameAddInfo} & &
+% \meta{name args} & \meta{tag} \\
+% \rowcolor{nagrey}\llap{Show data tag\qquad} & \cmd{\NameQueryInfo} & &
+% \meta{name args} & \\
+% \rowcolor{nagrey}\llap{\ul{Delete data tag}\qquad} & \cmd{\NameClearInfo} & &
+% \meta{name args} & \\
+% \llap{Delete name cs\qquad} & \cmd{\ForgetName} & & \meta{name args} & \\
+% \llap{\ul{Create name cs}\qquad} & \cmd{\SubvertName} & &
+% \meta{name args} & \\
+% \rowcolor{nagrey}\llap{Name cs tests\qquad} & \cmd{\IfMainName} & &
+% \meta{name args} & \marg{y}\marg{n}\\
+% \rowcolor{nagrey}& \cmd{\IfFrontName} & & \meta{name args} &
+% \marg{y}\marg{n}\\
+% \rowcolor{nagrey}\llap{\ul{\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ }\qquad} &
+% \cmd{\IfAKA} & & \meta{name args} & \marg{y}\marg{n}\marg{x}\\
+% \llap{Debugging\qquad} & \cmd{\ShowPattern} & & \meta{name args} & \\
+% & \cmd{\ShowIdxPageref} & \texttt{*} & \meta{name args} & \\
+% & \cmd{\ShowNameInfo} & & \meta{name args} & \\
+% & \cmd{\ShowNameState} & & \meta{name args} &\\\bottomrule
% \end{tabular}
% \end{center}
-% Not shown above are \cmd{\AKA}, \cmd{\AKA*}, \cmd{\PName}, and \cmd{\PName*} (Section~\ref{sec:AKA}). These macros from the early days of \textsf{nameauth} have specialized arguments and issues.
%
-% \begin{center}\bfseries Prefix Macros (One Use Per Name)\end{center}
+% The \meta{xref args} are the same as \meta{name args} for a cross-reference to a \meta{target} (Section~\ref{sec:IndexRef}). Not shown are \cmd{\AKA}, \cmd{\AKA*}, \cmd{\PName}, and \cmd{\PName*} (Section~\ref{sec:AKA}). Here we do not describe in detail what the arguments mean.
+%
+% \begin{Quote}{\ForgetThis\MLK[Dr. Martin Luther]\break
+% \hbox{}\hfill \textit{Stride Towards Freedom} (1958)}
+% \IndexName{Jesus, Christ}^^A
+% We believe firmly in the revelation of God in Jesus Christ. I can see no conflict between our devotion to Jesus Christ and our present action. In fact, I can see a necessary relationship. If one is truly devoted to the religion of Jesus he will seek to rid the earth of social evils. The gospel is social as well as personal.
+% \end{Quote}
+%
+% \newpage
+%
+% \subsubsection{Prefix Macros}
%
-% \begin{center}\small\MySmallStretch
+% Similar to the package options (Section~\ref{sec:PkgOptions}), many prefix macros alter the values of the Boolean flags that reflect the state of names and name processing. The naming and indexing macros reset the Boolean flags after they are invoked.
+%
+% \begin{center}\small\medstretch
% \begin{tabular}{rp{0.72\textwidth}}\toprule
% & \bfseries Capitalization in the Text\\
-% \cmd{\CapName} & Cap entire \meta{SNN} in body text. Overrides \cmd{\CapThis}.\\
-% \cmd{\CapThis} & Capitalize first letter of all name components in body text.\\
+% \cmd{\CapName} &
+% Cap entire \meta{SNN} in body text. Overrides \cmd{\CapThis}.\\
+% \cmd{\CapThis} &
+% Capitalize first letter of all name components in body text.\\
% \cmd{\AccentCapThis} & Fallback when Unicode detection cannot be done.\\
-% \rowcolor{grey} & \bfseries Reversing in the Text\\
-% \rowcolor{grey}\cmd{\RevName} & Reverse order of any name in body text. Overrides \cmd{\RevComma}\\
-% \rowcolor{grey}\cmd{\RevComma} & Reverse only Western names to \meta{SNN}, \meta{FNN}.\\
+% \rowcolor{nagrey} & \bfseries Reversing in the Text\\
+% \rowcolor{nagrey}\cmd{\RevName} &
+% Reverse order of any name in body text. Overrides \cmd{\RevComma}\\
+% \rowcolor{nagrey}\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{grey} & \bfseries Name Breaks in the Text\\
-% \rowcolor{grey}\cmd{\DropAffix} & Drop affix only for a long Western name reference.\\
-% \rowcolor{grey}\cmd{\KeepAffix} & Insert non-breaking space (NBSP) between \meta{SNN}, \meta{FNN/Affix}.\\
-% \rowcolor{grey}\cmd{\KeepName} & Insert NBSP between all name elements. Overrides \cmd{\KeepAffix}.\\
+% \cmd{\NoComma} &
+% No comma between \meta{SNN} and \meta{Affix}. Overrides \cmd{\ShowComma}.\\
+% \rowcolor{nagrey} & \bfseries Name Breaks in the Text\\
+% \rowcolor{nagrey}\cmd{\DropAffix} &
+% Drop affix only for a long Western name reference.\\
+% \rowcolor{nagrey}\cmd{\KeepAffix} &
+% Insert non-breaking space (NBSP) between \meta{SNN}, \meta{FNN/Affix}.\\
+% \rowcolor{nagrey}\cmd{\KeepName} &
+% Insert NBSP between all name elements. Overrides \cmd{\KeepAffix}.\\
% & \bfseries Forcing Name Forms via Control Sequence\\
% \cmd{\ForgetThis} & Force a first-time name use. Negates \cmd{\SubvertThis}.\\
% \cmd{\SubvertThis} & Force a subsequent use.\\
-% \rowcolor{grey} & \bfseries Forcing Name Forms via Boolean Flags\\
-% \rowcolor{grey}\cmd{\ForceName} & Force first-use formatting hooks.\\
-% \rowcolor{grey}\cmd{\ForceFN} & Force printing of \meta{Affix} in non-Western short forms.\\
+% \rowcolor{nagrey} & \bfseries Forcing Name Forms via Boolean Flags\\
+% \rowcolor{nagrey}\cmd{\ForceName} & Force first-use formatting hooks.\\
+% \rowcolor{nagrey}\cmd{\ForceFN} &
+% Force printing of \meta{Affix}/\meta{Alternate} in non-Western
+% short forms.\\
% & \bfseries Indexing\\
-% \cmd{\SeeAlso} & For \cmd{\IndexName}, \cmd{\AKA}, and \cmd{\PName}; make a \textit{see also} xref.\\
+% \cmd{\SeeAlso} &
+% For \cmd{\IndexName}, \cmd{\AKA}, and \cmd{\PName}; make a
+% \textit{see also} xref.\\
% \cmd{\SkipIndex} & For naming macros; do not create an index entry.\\
-% \cmd{\JustIndex} & For naming macros; index only (once); negated by \cmd{\AKA}, \cmd{\PName}.\\\bottomrule
+% \cmd{\JustIndex} &
+% For naming macros; index only (once); negated by \cmd{\AKA},
+% \cmd{\PName}.\\\bottomrule
% \end{tabular}
% \end{center}
-% \newpage
%
-% \begin{center}\bfseries More on Prefix Macros\end{center}
+% \noindent Some important notes include:
+%
% \begin{itemize}
-% \item Prefix macros stack:\\ \hbox{}\quad |\CapThis\RevName\SkipIndex\Name[bar]{foo}| \qquad \CapThis\RevName\SkipIndex\Name[bar]{foo}.
-% \item The Boolean flags governed by the prefix macros are reverted after the appropriate macros produce output in the text (or index) unless the output of the naming macros is suppressed.
-% \item Except for \cmd{\SeeAlso}, use prefix macros only before a naming macro that is designed to print output in the text.
-% \item Use \cmd{\SeeAlso}\Version{3.5} only with \cmd{\IndexRef}, \cmd{\AKA}, and \cmd{\PName}. Otherwise it will be reset by \cmd{\IndexName} and the naming macros.
-% \item Using \cmd{\JustIndex}\Version{3.5} will cause name form modifiers to be reset.
+% \item Prefix macros stack:\\[0.4ex]
+% |\CapThis\RevName\SkipIndex\Name[bar]{foo}|\dotfill
+% \CapThis\RevName\SkipIndex\Name[bar]{foo}
+% \item The Boolean flags governed by the prefix macros are reverted after
+% the appropriate macros produce output in the text (or index) unless the
+% output of the naming macros is suppressed.
+% \item Except for \cmd{\SeeAlso}, use prefix macros only before a naming
+% macro that is designed to print output in the text.
+% \item Use \cmd{\SeeAlso} only with \cmd{\IndexRef}, \cmd{\AKA}, and
+% \cmd{\PName}. Otherwise it will be ignored and reset by \cmd{\IndexName}
+% and the naming macros.
+% \item Using \cmd{\JustIndex} will cause name form modifiers to be reset.
% \end{itemize}
%
-% Macros that do not take name arguments include:
+% \noindent Macros that do not take name arguments include:
+%
% \begin{itemize}
-% \item State-changing macros with broad effects (document, section, scope).
-% \item State-changing macros with single-use effects (prefix macros).
-% \item Macros that alter general \textsf{nameauth} package behavior.
+% \item Prefix macros (Section~\ref{sec:PrefixMacs}).
+% \item Helper macros (Section~\ref{sec:Helpers}).
+% \item Most internal package macros.
% \item Formatting macros.
% \end{itemize}
-%
-% \subsection{Various Hints}
-% \label{sec:Hints}
%
-% In this section we make a brief foray into some technical issues that are good to keep in mind, but not overwhelming at this point. Sections~\ref{sec:Warnings} and~\ref{sec:Errors} go into greater detail on the things that one can do to diagnose missteps and avoid errors. The point here is to keep the quick start quick.
+% \subsection{Names and Complexity}
+% \label{sec:Complexity}
%
-% \begin{center}\bfseries Automatic Stripping of Spaces\end{center}
-% The\SPatInfo{\ShowPattern[Martin Luther]{King, Jr.}} \textsf{nameauth} package trims extra spaces \emph{around} name arguments to prevent errors. Here, name arguments include \meta{FNN}, \meta{SNN}, \meta{Affix}, and \meta{Alternate}. For example,\IdxInfo{\ShowIdxPageref*[Martin Luther]{King, Jr.}} instead of being two different names, below we have the same name in a first, then subsequent use. We use no name formatting below in order to show this:\bigskip
+% The \textsf{nameauth} package allows levels of complexity when representing names. Already, we have seen this example above:
%
-% \begingroup^^A Local scope for format
-% \renewcommand*\NamesFormat{}
-% \renewcommand*\MainNameHook{}
-% \leavevmode\quad\begin{minipage}[c]{0.43\textwidth}\small
-% \StartNum
-% \begin{verbatim*}
-%\Name*[Martin Luther]
-%{King,Jr.}\\
-%\Name*[ Martin Luther ]
-%{ King, Jr. }\end{verbatim*}
-% \end{minipage}
-% \begin{minipage}[c]{0.45\textwidth}\small
-% \def\sep{\vrule width0.5pt\kern-0.5pt}%
-% \begin{tabular}{@{}ll@{}}
-% No spaces: & \sep\SubvertThis\FName[Martin Luther]{King,Jr.}\sep\ \sep\Name*[Martin Luther]{King,Jr.}[\ignorespaces]\sep\\
-% & \sep\hphantom{Martin Luther}\sep\ \sep\hphantom{King Jr.}\sep\\
-% Spaces: & \sep\FName[ Martin Luther ]
-% { King, Jr. }\sep\ \sep\Name*[ Martin Luther ]
-% { King, Jr. }[\ignorespaces]\sep\\
-% \end{tabular}
-% \end{minipage}\bigskip
+% \begin{Block}\small
+% |\LEliz[I ``Gloriana'']|\dotfill \LEliz[I ``Gloriana'']
+% \end{Block}
%
-% \IndexInactive
-% Using macros that expand to spaces will produce a totally different name:\bigskip
-%
-% \leavevmode\quad\begin{minipage}[c]{0.43\textwidth}\small
-% \StartNum
-% \begin{verbatim*}
-%\Name*[ Martin Luther ]
-%{ King, Jr. }\\
-%\Name*[\ Martin Luther\ ]
-%{\ King, Jr.\ }\end{verbatim*}
-% \end{minipage}
-% \begin{minipage}[c]{0.45\textwidth}\small
-% \def\sep{\vrule width0.5pt\kern-0.5pt}%
-% \begin{tabular}{@{}ll@{}}
-% Spaces:\hphantom{No} & \sep\SubvertThis\FName[ Martin Luther ]{ King, Jr. }\sep\ \sep\Name*[ Martin Luther ]{ King, Jr. }[\ignorespaces]\sep\\
-% & \sep\hphantom{Martin Luther}\sep\ \sep\hphantom{King Jr.}\sep\\
-% Macros: & \sep\SubvertThis\FName[\ Martin Luther\ ]
-% {\ King, Jr.\ }\sep\ \sep\Name*[\ Martin Luther\ ]
-% {\ King, Jr.\ }[\ignorespaces]\sep\\
-% \end{tabular}\smallskip
-%
-% Simple Pattern:\\
-% \hphantom{Index: }\fbox{\texttt{\ShowPattern[\ Martin Luther\ ]{\ King, Jr.\ }}}\\
-% Index: \fbox{\ShowIdxPageref*[\ Martin Luther\ ]{\ King, Jr.\ }}
-% \end{minipage}\bigskip
-% \endgroup^^A Local scope for format
+% We can so the same thing with different macros, but they do not offer more features, only more complexity:
%
-% Yet one may have to include a non-breaking space (active character |~|) after a name particle like \textit{de} to keep the name from breaking badly (Section~\ref{sec:NameParticles}). One must use that non-breaking space consistently to avoid errors.
-% \newpage
+% \begin{Block}
+% |\LEliz\ ``\ForceFN\SEliz[Gloriana]''|\dotfill
+% \LEliz\ ``\ForceFN\SEliz[Gloriana]''
+% \end{Block}
%
-% \begin{center}\bfseries Full Stop Detection\end{center}
-% Full 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 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. Below we resume formatting and pretend that we have not seen Dr. King's name yet:
-% \begin{quote}\small\ForgetName[Martin Luther]{King, Jr.}
-% |This is Rev. Dr. \Name[Martin Luther]{King, Jr.}.|\SPatInfo{\ShowPattern[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}
+% In Section~\ref{sec:NameAncient} we will learn how to add a one-time increase in complexity by using ``name info tags'' with modified formatting hooks to do the following that \emph{does} offer potentially more features:
%
-% \begin{center}\bfseries Caveats with Grouping\end{center}
-% Take care when using braces and spaces with a name at the end of a sentence. Braces will change the control sequence patterns generated by name arguments. Put simply, this means that both the names and their index entries will be different and behave differently\,---\,even though they look the same (Sections~\ref{sec:IndexSort}, \ref{sec:NamePatterns}). We disable indexing for the three points below:\IndexInactive
-% \begin{itemize}\small
-% \item If one\SPatInfo{\ShowPattern[Martin Luther]{King,Jr.}} 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\SPatInfo{\ShowPattern[Martin Luther]{King, {Jr.}}\break \ShowPattern[Martin Luther]{King, {Jr}.}} 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[] A solution\vspace{-1ex}\IdxInfo{\ShowIdxPageref*[Martin Luther]{King, {Jr.}}\break \ShowIdxPageref*[Martin Luther]{King, {Jr}.}\break (Looks identical, but not.)}\vspace{1ex} 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[] Yet the name patterns (Section~\ref{sec:NamePatterns}) are different, creating two different names and two different index entries.
-% \item A space\SPatInfo{\ShowPattern[Martin Luther]{King,Jr.}} between a name and full stop hinders punctuation detection, except with the quick interface:\\
-% |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
-% \newpage
-%
-% \begin{center}\bfseries Caveats with Active Characters\end{center}
-% Variations in the use of active characters and control sequences also change name arguments, name control patterns, and index sorting. These changes can depend on the \LaTeX\ engine being used, but often different names are just different, even if they appear the same (Section~\ref{sec:IndexSort}; cf.~\ref{sec:Unicode} and~\ref{sec:TeXengines}):
-% \begin{enumerate}\small
-% \item |\Name*{Æthelred, II}|\dotfill \Name*{Æthelred, II}\SPatInfo{\ShowPattern{Æthelred, II} \textrm{(1)}\break \ShowPattern{\AE thelred, II} \textrm{(2)}\break \ShowPattern{Bo\"ethius} \textrm{(3)}\break \ShowPattern{Boëthius} \textrm{(4)}\break \ShowPattern{Bo{\"e}thius} \textrm{(5)}}\footnote{With \texttt{pdflatex} and \texttt{latex}, in \texttt{\ShowPattern{Æthelred, II}} the glyphs \texttt{ÃĘ} correspond to \cmd{\IeC\{}\cmd{\AE\}}.}\newline We have seen this name earlier.
-% \item |\SkipIndex\Name{\AE thelred, II}|\dotfill \SkipIndex\Name{\AE thelred, II}\hbox to 0.45em{\hfill}\newline This is a new name that looks the same.
-% \item |\Name{Bo\"ethius}|\dotfill \Name{Bo\"ethius}\hbox to 0.45em{\hfill}\newline We introduce this new name.
-% \item |\SkipIndex\Name{Boëthius}|\dotfill \SkipIndex\Name{Boëthius}\footnote{With \texttt{pdflatex} and \texttt{latex}, in \texttt{\ShowPattern{Boëthius}} the glyphs \texttt{Ãń} correspond to \cmd{\IeC\{}\cmd{\"e\}}.}\newline This is a different name that looks the same.
-% \item |\SkipIndex\Name{Bo{\"e}thius}|\dotfill \SkipIndex\Name{Bo{\"e}thius}\hbox to 0.45em{\hfill}\newline This is a third, different name that looks the same.
-% \end{enumerate}
+% \begingroup
+% \NameAddInfo{Elizabeth, I}{ ``Gloriana''}
+% \renewcommand*\NamesFormat[1]
+% {^^A
+% \color{blue}\sffamily #1^^A
+% \ifcsname\NameauthPattern!DB\endcsname
+% \expandafter\csname\NameauthPattern!DB\endcsname^^A
+% \fi
+% }
+% \renewcommand*\MainNameHook{\sffamily}
+% \begin{Block}\small
+% \FUse |\ForgetThis\LEliz|\dotfill \ForgetThis\LEliz\\
+% \LUse |\LEliz|\dotfill \LEliz\\
+% \LUse |\Eliz|\dotfill \Eliz
+% \end{Block}
+% \endgroup
+%
+% There can be needless complexity, and there can be helpful complexity. For example, if \LaTeX\ is used as the back end for an \texttt{xslt} transform, it can be useful to have well-defined macro states that map systematically to the input without needing human intervention.
+%
+% Section~\ref{sec:NameParticles} shows a similar trade-off between a simple example and a formatted example using the name of poet \Name[e.e.]{cummings}. Moving on to Section~\ref{sec:Romani}, complexity increases, yet the state of any given name remains well-defined.
+%
+% \begin{InfoBox}[Avoid the Rabbit Hole]
+% \begin{itemize}[leftmargin=1em]
+% \item There are trade-offs between ease of use and automation.
+% \item Examples that are easy to implement often are not easily automated.
+% \item Examples that are more complex lend themselves to automation using
+% package features as building blocks.
+% \item In \textsf{nameauth}, names are nouns that have state and modifiers.
+% \item In \textsf{nameauth}, names are verbs capable of changing their
+% environment.
+% \end{itemize}
%
-% \begin{center}\bfseries Formatting Initials\end{center}
-% This is a thorny topic. Some publishers are dead-set on having a space between initials. Many designers find that practice to be inelegant at best. Robert Bringhurst wisely advises one to omit spaces between initials.\footnote{Robert Bringhurst, \textit{Elements of Typographic Style} 3.2 ed. (Point Roberts, Washington: Hartley \& Marks, 2008.)}
+% The example in Section~\ref{sec:QuickExample} was quite simple, yet there are many use cases that need not be much more complex than that. Thus, one must discern useful complexity from useless complexity.\medskip
%
-% Yet fighting with one's editor will be a lost cause unless one already has sufficient \textit{gravitas}. 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
+% Unless one has a use case that demands automation and complexity, hopefully illustrated by examples in this manual, one should tend toward simplicity and the macros seen in the earlier pages of this manual.
+% \end{InfoBox}
%
-% \leavevmode\quad\begin{minipage}[c]{0.45\textwidth}\small
-% \StartNum
-% \begin{verbatim}
-%\PretagName[E.\,B.]{White}%
-% {White, Elwyn}
-%\begin{nameauth}
-% \< White & E.\,B. & White & >
-%\end{nameauth}\end{verbatim}
-% \end{minipage}
-% \begin{minipage}[c]{0.35\textwidth}\renewcommand*\NamesFormat{}
-% \def\sep{\vrule width0.5pt\kern-0.5pt}%
-% \begin{tabular}{@{}ll@{}}\toprule
-% \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\\\bottomrule
-% \end{tabular}
-% \end{minipage}\bigskip
+% \ReturnLink
%
-% \begin{center}\bfseries Multicultural Hyphenation\end{center}
-% Names can be hyphenated to reflect their cultural and linguistic origins. With \textsf{nameauth}, one can use either optional hyphens or the \textsf{babel}/\textsf{polyglossia} packages to handle such names. Below we offer a simplified example without alternate formatting (Section~\ref{sec:AltFormat}):
-% \begin{quote}\small
-% \StartNum
-% \begin{verbatim}
-%\newcommand\de[1]{\foreignlanguage{ngerman}{#1}}
-% % or polyglossia: \newcommand\de[1]{\textgerman{#1}}
-%\NameAddInfo[John]{\de{Strietelmeier}}%
-% {a professor at Valparaiso University}
-%\begin{nameauth}
-% \< Striet & John & \de{Strietelmeier} & >
-%\end{nameauth}
-%\PretagName[John]{\de{Strietelmeier}}{Strietelmeier, John}\end{verbatim}
-% \end{quote}
% \newpage
%
-% Now we demonstrate three different ways of engaging this problem. In the first example we use the default hyphenation. We omit this version from the index. One might think that the name were pronounced ``stree-et-el-mai-er'':\medskip
-%
-% \noindent \emph{Not fixed:}\SPatInfo{\ShowPattern[John]{Strietelmeier}}
-%
-% \noindent In English, some names come from other cultures. These names, like \SkipIndex\Name[John]{Strietelmeier}, |\SkipIndex\Name[John]{Strietelmeier},| can break badly.\medskip
-%
-% The next example uses discretionary hyphens. It is a different name from the one above and one must be consistent with the discretionary hyphens. We also omit this version from the index:\medskip
-%
-% \noindent \emph{Fixed with discretionary hyphens:}\SPatInfo{\ShowPattern[John]{Strie\-tel\-meier}}\medskip
+% \section{Package Options}
+% \label{sec:PkgOptions}
+% \negmedskip
%
-% \noindent In English, some names come from other cultures. These names, like \SkipIndex\Name[John]{Strie\-tel\-meier}, |\SkipIndex\Name[John]{Strie\-tel\-meier},| could break badly.\medskip
+% \begin{SyntaxBox}
+% \cmd{\usepackage[}\meta{\(option_1\)}\texttt{,}\meta{\(option_2\)}^^A
+% \texttt{,}\dots\texttt{,}\meta{\(option_n\)}\texttt{]\{nameauth\}}
+% \end{SyntaxBox}
%
-% Finally we use what may be the best general solution, the \textsf{babel} or \textsf{polyglossia} packages. Since the leading element of \meta{SNN} is a macro, using \cmd{\CapThis} would halt \LaTeX\ with errors unless we used alternate formatting (Section~\ref{sec:AltFormat}):\medskip
+% We discuss package options according to the structure of this package. That structure repeats among the Boolean flags, package options, user interface macros, and internal macros. The goal is understanding through repetition.
%
-% \noindent \emph{Fixed with language packages:}\SPatInfo{\ShowPattern[John]{\de{Strietelmeier}}}\medskip
+% Section~\ref{sec:Priorities} shows the hierarchy of these options and related macros. Default options are in \emph{boldface} and need not be invoked by the user. Non-default options are in \emph{\color{nared} dark red} and must be invoked explicitly. Many of these options work together with macros that do the same thing, but with finer control.
%
-% \noindent In English, some names come from other cultures. These names, like \Striet, \cmd{\Striet,} could break badly. \Striet\ was at Valparaiso University.
+% \subsection{Name Grammar and Syntax}
%
-% \begin{center}\bfseries Obsolete Syntax Caution\end{center}
-% We moved the discussion of the obsolete syntax to Section~\ref{sec:Obsolete} because, as this package matures, we do not expect people to use it much anymore. There are more advantages to using the current syntax.
+% \subsubsection[Affix Commas]{Show/Hide Affix Commas}
%
-% \begin{enumerate}
-% \item Only\SPatInfo{\ShowPattern{Henry, VIII}[Tudor]\hfil \textrm{(1--2)}\break \ShowPattern[Henry]{VIII}[Tudor]\hfil \textrm{\ \ \ (3)}} the newer syntax permits variants: \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]. Both\vspace{-2ex}\IdxInfo{\ShowIdxPageref*{Henry}[VIII]\hfil \textrm{(1--2)}\break \ShowIdxPageref*[Henry]{VIII}[Tudor]\hfil \textrm{\ \ (3)}}\vspace{2ex} old and new share name patterns (Section~\ref{sec:NamePatterns}).
-% \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{enumerate}
-%
-% \ReturnLink
-% \vfill
+% \bgroup\begin{tabular}{p{0.22\textwidth}p{0.6\textwidth}}
+% \quad\bfseries\texttt{nocomma} &
+% \bfseries Modern standards: Suppress commas between surnames and
+% affixes.\smallskip\\
+% \leavevmode\color{nared}\quad\texttt{comma} &
+% \leavevmode\color{nared}Older standards: Retain commas between surnames
+% and affixes.\medskip\\
+% \end{tabular}\egroup
%
-% \AltFormatActive^^A
-% \begin{verse}
-% 'Tis but thy name that is my enemy;\dots\\
-% What's in a name? That which we call a rose\\
-% By any other name would smell as sweet;\\
-% So Romeo would, were he not Romeo call'd,\\
-% Retain that dear perfection which he owes\\
-% Without that title. Romeo, doff thy name,\\
-% And for that name which is no part of thee\\
-% Take all myself.\\[1ex]\hfill---\Shak, \textit{Romeo and Juliet}, Act II, Scene II
-% \end{verse}
-% \AltFormatInactive^^A
-% \newpage
+% \noindent These options do not affect the index. They permit different standards for name affixes. The default \texttt{nocomma} option gives, e.g., \Name[J.E.]{Carter, Jr.}[James Earl]. The \texttt{comma} option produces \ShowComma\Name*[J.E.]{Carter, Jr.}[James Earl]. Macros that allow finer control of commas and affixes are shown in Section~\ref{sec:Affix}.
%
-% \section{Detailed Usage}
+% \subsubsection[Surname in Caps]{Capitalize Entire Surnames}
%
-% \subsection{Package Options}
-% \label{sec:PkgOptions}
+% \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, throughout the document.\medskip\\
+% \end{tabular}\egroup
%
-% One includes the \textsf{nameauth} package thus:
-% \begin{quote}
-% \fbox{
-% \begin{tabular}{l}
-% {\Large\strut}\cmd{\usepackage[}\meta{\(option_1\)}\texttt{,}\meta{\(option_2\)}\texttt{,}\dots\texttt{,}\meta{\(option_n\)}\texttt{]\{nameauth\}}
-% \end{tabular}
-% }
-% \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.}
+% \noindent These options do not affect the index. See Section~\ref{sec:Eastern} for finer control. To capitalize names in the index, use caps as desired or alternate formatting (Section~\ref{sec:AltFormat}).
%
-% \begin{center}\bfseries Choosing Features\end{center}
+% \subsubsection{Reverse Name Order}
%
-% \noindent{\bfseries Choose Formatting System}\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 \normalfont (see also page~\pageref{page:PostProcess}).\smallskip\\
-% \leavevmode\color{nared}\quad\texttt{frontmatter} & \leavevmode\color{nared}Start with ``front-matter names'' and hooks until \cmd{\NamesActive} starts the main system.\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}.\medskip\\
+% \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;
+% Western as non-Western, and vice versa.\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 The \texttt{mainmatter} and \texttt{frontmatter} options enable two respectively independent systems of name use and formatting. See Section~\ref{sec:Formatting}.
+% \noindent These options do not affect the index and are mutually exclusive (Sections~\ref{sec:RevNames} and~\ref{sec:LastFirst}). Use \texttt{allrevcomma} option only for listing Western names by surname.
%
-% The \texttt{alwaysformat} option forces ``first use'' hooks globally in both naming systems. Its use is limited in current versions of \textsf{nameauth}.
+% \begin{Quote}{\Name[Mark]{Twain}, \textit{The Innocents Abroad} (1869)}
+% Virtue never has been as respectable as money.
+% \end{Quote}
%
-% 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} only uses ``subsequent use'' formatting hooks.\bigskip
+% \subsection{Indexing}
%
-% \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
+% \subsubsection{Toggle Indexing}
%
-% \noindent These options and related macros 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:GeneralIndex}. For indexing feature priority, see page~\pageref{page:Priorities}.\bigskip
-%
-% \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\\
+% \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 The default allows \cmd{\PretagName} to create sort keys used with \texttt{makeindex}. The \texttt{nopretag} option disables the sorting mechanism and causes \cmd{\PretagName} only to emit warnings. That is designed for cases that use different sorting methods, such as \texttt{xindy}. See Section~\ref{sec:IndexSort}.\newpage
+%^^A Starting with the text below, any errors will force one to remove all
+%^^A auxiliary files before compiling this file. There is no clear indication
+%^^A of why that happens to be the case.
%
-% \noindent{\bfseries Enable ``Global'' Decision Paths}\medskip\\
-% \bgroup\begin{tabular}{p{0.22\textwidth}p{0.6\textwidth}}
-% \leavevmode\color{nared}\quad\texttt{globaltest} & \leavevmode\color{nared}Do not put name decision paths in a local scope.\medskip\\
-% \end{tabular}\egroup
+% \noindent
+% These options and related macros 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 in Section~\ref{sec:GeneralIndex}. For indexing feature priority, see Section~\ref{sec:Priorities}.
%
-% \noindent The default puts the decision paths of \cmd{\IfMainName}, etc., into groups with local scope (Section~\ref{sec:NameTests}). This option removes that scoping.\bigskip
+% \subsubsection{Toggle Index Sorting}
%
-% \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 more diagnostic warnings.\medskip\\
+% \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 suppresses all but the most essential package warnings. Increasing the warnings may help to debug index page entries, cross-references, and exclusions.\bigskip
+% \noindent The default allows \cmd{\PretagName} to create sort keys used with \texttt{makeindex}. The \texttt{nopretag} option disables the sorting mechanism and causes \cmd{\PretagName} only to emit warnings, as may be needed with, e.g., \texttt{xindy}. See Section~\ref{sec:IndexSort}.
+%
+% \subsubsection{Verbose Warnings}
%
-% \noindent{\bfseries Choose Version Compatibility}\medskip\\
-% \textbf{Using these options will increase the chance of undocumented behavior.} They are included only for the sake of backward compatibility.\medskip\\
% \bgroup\begin{tabular}{p{0.22\textwidth}p{0.6\textwidth}}
-% \leavevmode\color{nared}\quad\texttt{oldAKA} & \leavevmode\color{nared}Force \cmd{\AKA*} to act like it did before version 3.0, instead of like \cmd{\FName}.\smallskip\\
-% \leavevmode\color{nared}\quad\texttt{oldreset} & \leavevmode\color{nared}Reset per-use name flags locally; let \cmd{\ForgetThis} and \cmd{\SubvertThis} pass through \cmd{\AKA} (pre-v3.3). Let \cmd{\SeeAlso} pass through \cmd{\IndexName} and other macros. Keep \cmd{\IndexName} and \cmd{\IndexRef} from resetting \cmd{\SkipIndex} (pre-version 3.5).\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.\smallskip\\
-% \leavevmode\color{nared}\quad\texttt{oldtoks} & \leavevmode\color{nared}Token registers holding the arguments of the last-used name are set locally, as before version 3.5.\smallskip\\
-% \leavevmode\color{nared}\quad\texttt{oldsee} & \leavevmode\color{nared}Allow lax handling of \textit{see} references that are extant names, as before version 3.5.\medskip\\
+% \leavevmode\color{nared}\quad\texttt{verbose} &
+% \leavevmode\color{nared}Show more diagnostic warnings.\medskip\\
% \end{tabular}\egroup
%
-% \noindent Previously, local scope for Boolean flags related to the prefix macros and long/short name forms could produce unexpected results, but that could hide the problems with some flags not being reset by \cmd{\AKA}, \cmd{\AKA*}, and the use of \cmd{\JustIndex}. Global name token registers are preferable, as is the newer, stricter control over \textit{see} references related to index page entries.
+% \noindent The default suppresses all but the most essential package warnings. Increasing the warnings may help to debug index page entries, cross-references, and exclusions. Section~\ref{sec:GeneralIndex} shows macros that can enable and disable verbose warnings.
%
-% \begin{center}
-% \begin{tabular}{rr}\toprule
-% \textsf{nameauth} version & compatibility options to approximate:\\\midrule
-% \rowcolor{grey}2.6 & \texttt{oldAKA,oldpass,oldreset,oldtoks,oldsee}\\
-% 3.0--3.2 & \texttt{oldpass,oldreset,oldtoks,oldsee}\\
-% \rowcolor{grey}3.3--3.4 & \texttt{oldreset,oldtoks,oldsee}\\\bottomrule
-% \end{tabular}
-% \end{center}\leavevmode
+% \addtocontents{toc}{\protect\goodbreak}
%
-% \begin{center}\bfseries Affect the Syntax of Names\end{center}
+% \subsection[Formatting]{Formatting and Name Control Sequences}
%
-% \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
+% Formatting, which, in its simplest form is typographic post-processing of a name, and in its complex forms can affect the syntactic form of a name, refers to the appearance of a name in the body text.
%
-% \noindent These options do not affect the index. On comma macro priority, see page~\pageref{page:Priorities}. 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, 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
+% \subsubsection[Choose System]{Choose Formatting System}
%
-% \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, throughout the document.\medskip\\
+% \bfseries\quad\texttt{mainmatter} &
+% \bfseries Start with ``main-matter names'' and formatting hooks \normalfont
+% (Section~\ref{sec:PostProcess}).\smallskip\\
+% \leavevmode\color{nared}\quad\texttt{frontmatter} &
+% \leavevmode\color{nared}Start with ``front-matter names'' and hooks until
+% \cmd{\NamesActive} starts the main system.\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}.\medskip\\
% \end{tabular}\egroup
%
-% \noindent These options do not affect the index. See Section~\ref{sec:Eastern} for finer control. To capitalize names in the index, use all caps or alternate formatting (Section~\ref{sec:AltFormat}). On capitalization feature priority, see page~\pageref{page:Priorities}.\bigskip
+% \noindent The \texttt{mainmatter} and \texttt{frontmatter} options enable two respectively independent systems of name use and formatting. Even when no extra formatting occurs, the formatting hooks are defined. Changes require \cmd{\renewcommand}. See Section~\ref{sec:Formatting}.
%
-% \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
+% The \texttt{alwaysformat} option forces ``first use'' hooks globally in both naming systems. Its use is limited in current versions of \textsf{nameauth}.
%
-% \noindent These options do not affect the index and are mutually exclusive. See also Sections~\ref{sec:LastFirst} and~\ref{sec:Eastern}. Regarding which of these features overrides the other, see page~\pageref{page:Priorities}. 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.
+% The \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} only uses ``subsequent use'' formatting hooks.
%
-% \begin{center}\bfseries Typographic Post-Processing\end{center}
-% \phantomsection
-% \label{page:PostProcess}
+% \subsubsection[Predefined Hooks]{Predefined Formatting Hooks}
+% \label{sec:PostProcess}
%
-% \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\\
+% \quad\bfseries\texttt{noformat} &
+% \bfseries Pass the displayed name through the formatting hooks
+% unchanged.\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 The options above are ``quick'' definitions of \cmd{\NamesFormat} based on English typography.\footnote{For the old default, use the \texttt{smallcaps} option. See also Robert Bringhurst, \textit{The Elements of Typographic Style}, version 3.2 (Point Roberts, Washington: Hartley \& Marks, 2008), 53--60.}
-% The default is no formatting, the overwhelming user preference.
+% \noindent The options above are ``quick'' definitions of \cmd{\NamesFormat} based on English typography. The default is no formatting.\footnote{For the old default, use the \texttt{smallcaps} option. User feedback dictated this change.}
+% See also Robert Bringhurst, \textit{The Elements of Typographic Style}, version 3.2 (Point Roberts, Washington: Hartley \& Marks, 2008), 53--60. All references [\hypertarget{Bringhurst}{Bringhurst}] refer to this edition.
%
-% The following macros are formatting hooks that do ``typographic post-processing'' of names in the text. Originally, \cmd{\NamesFormat} was the only such hook, which resulted in the organic development of the names of these macros. This development reflects the use of two naming systems, one for main-matter text (default) and one for front-matter text.
+% The following macros govern the way that names in the text appear. Two naming systems are used in \textsf{nameauth}, one for main-matter text (default) and one for front-matter text.\footnote{\cmd{\NamesFormat} was once the only formatting hook. The other macros developed from there. Regrettably, this package originated in a time when the present author was ignorant of several cultural and technical aspects of handling names. The ``learn as you go'' approach contributed to a fair bit of ``cargo-cult'' programming.}
+% These hooks do not affect the index. Changes to the formatting hooks normally apply within the scope where they occur:
%
-% Unlike alternate formatting, the hooks do not affect the index. Sections \ref{sec:Formatting}, \ref{sec:Hooksi}, \ref{sec:Hooksii}, and~\ref{sec:Hooksiii} explain these hooks and their redefinition in greater detail. Changes to the formatting hooks apply within the scope where they are made:
% \begin{itemize}
% \item \cmd{\NamesFormat} formats first uses of main-matter names.
% \item \cmd{\MainNameHook} formats subsequent uses of main-matter names.
@@ -1774,1642 +2797,2540 @@ and version 1.3 or later is part of all distributions of LaTeX version
% \item \cmd{\FrontNameHook} formats subsequent uses of front-matter names.
% \end{itemize}
%
-% 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:GeneralIndex} shows how to use \cmd{\IndexRef} and \cmd{\Name} instead.
-%
-% \begin{center}\bfseries Alternate or Continental Formatting\end{center}
+% Sections \ref{sec:Formatting}, \ref{sec:AdvancedFormat}, and~\ref{sec:AdvCustomize} explain these hooks and their redefinition in greater detail. Section~\ref{sec:AKA} discusses how \cmd{\AKA} does not respect these formatting systems.
+%
+% \subsection{Alternate Formatting}
%
-% \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\\
+% \leavevmode\color{nared}\quad\texttt{altformat} &
+% \leavevmode\color{nared}Make available the alternate formatting framework
+% from the start of the document. Activate alternate 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.
+% \noindent A built-in 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:AdvCustomize} goes into greater detail for customization.
%
% Previous methods that produced Continental formatting were more complex than the current ones. Yet these older solutions still should work, as long as one uses the \texttt{altformat} option and related macros.
%
-% \begin{center}\bfseries Feature Priority\end{center}
-% \phantomsection
-% \label{page:Priorities}
+% \subsection[Scope of Decisions]{Change Scope of Name Decision Macros}
+%
+% \bgroup\begin{tabular}{p{0.22\textwidth}p{0.6\textwidth}}
+% \leavevmode\color{nared}\quad\texttt{globaltest} &
+% \leavevmode\color{nared}Do not put name decision paths in a local
+% scope.\medskip\\
+% \end{tabular}\egroup
+%
+% \noindent The default puts the decision paths of \cmd{\IfMainName}, etc., into groups with local scope (Section~\ref{sec:NameTests}). This option removes that scoping.
+%
+% \subsection{Version Compatibility}
+%
+% \emph{Using these options will increase the chance of undocumented behavior.} They are included only for the sake of backward compatibility with older versions of \textsf{nameauth}. The goal is to preserve the behavior of this package at the point it was used in a document, especially if local fixes were employed.\medskip
+%
+% \bgroup\begin{tabular}{p{0.22\textwidth}p{0.6\textwidth}}
+% \leavevmode\color{nared}\quad\texttt{oldAKA} &
+% \leavevmode\color{nared}Force \cmd{\AKA*} to act like it did before version
+% 3.0, instead of like \cmd{\FName}.\smallskip\\
+% \leavevmode\color{nared}\quad\texttt{oldreset} &
+% \leavevmode\color{nared}Reset per-use name flags locally; let
+% \cmd{\ForgetThis} and \cmd{\SubvertThis} pass through \cmd{\AKA} (pre-v3.3).
+% Let \cmd{\SeeAlso} pass through \cmd{\IndexName} and other macros.
+% Keep \cmd{\IndexName} and \cmd{\IndexRef} from resetting \cmd{\SkipIndex}
+% (pre-version 3.5).\smallskip\\
+% \leavevmode\color{nared}\quad\texttt{oldpass} &
+% \leavevmode\color{nared}When \cmd{\Justindex} is called, allow long or short
+% Boolean flags to pass through, as they did before version 3.3.\smallskip\\
+% \leavevmode\color{nared}\quad\texttt{oldtoks} &
+% \leavevmode\color{nared}Token registers holding the arguments of the
+% last-used name are set locally, as before version 3.5.\smallskip\\
+% \leavevmode\color{nared}\quad\texttt{oldsee} &
+% \leavevmode\color{nared}Allow lax handling of \textit{see} references that
+% are extant names, as before version 3.5.\medskip\\
+% \end{tabular}\egroup
+%
+% \noindent Previously, local scope for Boolean flags related to the prefix macros and long/short name forms could produce unexpected results. Those results, in turn, could mask problems caused by some flags not being reset by \cmd{\AKA}, \cmd{\AKA*}, and \cmd{\JustIndex}. The result was undocumented behavior.
+%
+% \begin{itemize}
+% \item Version 2.6 approximate compatibility\\
+% \texttt{oldAKA,oldpass,oldreset,oldtoks,oldsee}
+% \item Versions 3.0--3.2 compatibility\\
+% \texttt{oldpass,oldreset,oldtoks,oldsee}
+% \item Versions 3.3--3.4 compatibility\\
+% \texttt{oldreset,oldtoks,oldsee}
+% \end{itemize}
+% \negbigskip
+%
+% \ReturnLink
%
-% \noindent Below we see the relative priority of package options and macros, with darker rows showing lower priority. Within a column, high priority can override low priority. Thus, \cmd{\IndexInactive} overrides \cmd{\JustIndex}, which overrides \cmd{\SkipIndex}.
+% \begin{Quote}{\Name[John F.]{Kennedy}, Inaugural Address (1961)}
+% The world is very different now. For man holds in his mortal hands the power to abolish all forms of human poverty and all forms of human life. And yet the same revolutionary beliefs for which our forebears fought are still at issue around the globe\,---\,the belief that the rights of man come not from the generosity of the state, but from the hand of God.
+% \end{Quote}
%
-% \begin{center}\small\MyStretch
+% \section{Feature Priority}
+% \label{sec:Priorities}
+%
+% \begin{center}\small\medstretch
% \begin{tabular}{llll}\toprule
-% \bfseries Indexing & \bfseries Capitalization & \bfseries Reversing & \bfseries Name Forms, \\
+% \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!6!white}\cmd{\JustIndex} & \cmd{\CapName} & \cmd{\RevName} & \cmd{\SubvertThis}\\
-% \rowcolor{black!6!white} & & & \cmd{\ForceName}\\
-% \rowcolor{black!6!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!18!white}\cmd{\SeeAlso} & \cmd{\CapThis} & \cmd{\RevComma} & \cmd{\KeepAffix}\\\bottomrule
+% \ttfamily\bfseries index & \ttfamily\bfseries normalcaps &
+% \ttfamily\bfseries notreversed & \cmd{\ForgetThis} \\
+% \ttfamily\bfseries noindex & \ttfamily\bfseries allcaps &
+% \ttfamily\bfseries allreversed & \cmd{\DropAffix} \\
+% \cmd{\IndexActive} & \cmd{\AllCapsInactive} & \cmd{\ReverseActive} \\
+% \cmd{\IndexInactive} & \cmd{\AllCapsActive} & \cmd{\ReverseInactive} \\
+% \rowcolor{black!6!white}
+% \cmd{\JustIndex} & \cmd{\CapName} & \cmd{\RevName} & \cmd{\SubvertThis}\\
+% \rowcolor{black!6!white} & & & \cmd{\ForceName}\\
+% \rowcolor{black!6!white} & & & \cmd{\NoComma}\\
+% \rowcolor{black!12!white}
+% \cmd{\SkipIndex} & \cmd{\AccentCapThis} &
+% \ttfamily\bfseries allrevcomma & \cmd{\KeepName}\\
+% \rowcolor{black!12!white} & & \cmd{\RevCommaActive} & \cmd{\ForceFN}\\
+% \rowcolor{black!12!white} & & \cmd{\RevCommaInactive} & \cmd{\ShowComma}\\
+% \rowcolor{black!18!white}
+% \cmd{\SeeAlso} & \cmd{\CapThis} & \cmd{\RevComma} &
+% \cmd{\KeepAffix}\\\bottomrule
% \end{tabular}
% \end{center}
%
+% Above we see the relative priority of package options and macros. Package options are shown in boldface.
+%
+% \begin{itemize}
+% \item Lighter-colored rows show higher priority. Darker-colored rows show
+% lower priority. Higher-priority options and macros can override
+% lower-priority ones.
+% \item All options and macros in a given row have equal priority and are
+% able to countermand each other within a given column.
+% \item Priority affects macros and options within columns.
+% \cmd{\IndexInactive} overrides \cmd{\JustIndex}, which overrides
+% \cmd{\SkipIndex}. If \cmd{\IndexInactive} is invoked, \cmd{\JustIndex}
+% will have no effect.
+% \item Section~\ref{sec:IdxPrefix} shows the interaction between
+% \cmd{\SkipIndex} and \cmd{\JustIndex} to be complex and non-intuitive.
+% It explains why it is best to use only \cmd{\SkipIndex} or
+% \cmd{\JustIndex} before a naming macro.
+% \item Priority usually does not affect macros and options in different
+% columns. Yet the macros themselves can have specific effects that change
+% the expected behavior of macros in other columns.
+%
+% For example, \cmd{\JustIndex} prevents a name from being displayed in
+% the text. Even if \cmd{\IndexInactive} overrides \cmd{\JustIndex} with
+% respect to indexing, it has no effect on the fact that the name will not
+% be printed.
+%
+% Also, \cmd{\JustIndex} resets the effects of \cmd{\ForgetThis} and
+% \cmd{\SubvertThis} because those prefix macros should precede only naming
+% macros that produce output in the text.
+%
+% Due to this behavior, even though \cmd{\JustIndex} does not ``override''
+% the caps and reversing macros and options, nevertheless it simply prevents
+% any other macros related to the display of a name from taking effect.
+% \end{itemize}
+%
% \ReturnLink
+%
% \newpage
%
-% \subsection{Naming Macros}
+% \section{Naming Macros}
%
-% In this\Illus{} manual we modify the formatting hooks to show first and later name uses, forcing such uses as needed (Sections~\ref{sec:Formatting}--\ref{sec:NameControl}). All naming macros create index entries before and after a name for when a name straddles a page break.
+% This section is a ``pedantic'' presentation of macros, their syntax, and their output. Section~\ref{sec:BasicStart} is better for getting started. All naming macros that have the same arguments also create consistent index entries. These entries are created both at the start and at the end of a name, in case that name spans a page break.
%
-% \subsubsection{\texttt{\textbackslash Name} and \texttt{\textbackslash Name*}}
+% \subsection{\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*}
% then usually just the \meta{SNN} argument thereafter. \cmd{\Name*} always prints the full name:
-% \begin{quote}
-% \fbox{
-% \begin{tabular}{l}
-% {\Large\strut}\cmd{\Name\ }\oarg{FNN}\marg{SNN|,| Affix}\oarg{Alternate}\vspace{-2pt}\\
-% {\Large\strut}\cmd{\Name*}\oarg{FNN}\marg{SNN|,| Affix}\oarg{Alternate}\\
-% \end{tabular}
-% }
-% \end{quote}
%
-% In the body text, not the index, the \meta{Alternate} argument replaces either \meta{FNN} or, if \meta{FNN} is absent, \meta{Affix}. If both \meta{FNN} and \meta{Affix} are absent when \meta{Alternate} is present, then the obsolete syntax is used (Section~\ref{sec:Obsolete}).
+% \begin{SyntaxBox}
+% \cmd{\Name\ }\oarg{FNN}\marg{SNN|,| Affix}\oarg{Alternate}\\
+% \cmd{\Name*}\oarg{FNN}\marg{SNN|,| Affix}\oarg{Alternate}
+% \end{SyntaxBox}
+%
+% In the body text, not the index, the \meta{Alternate} argument replaces either \meta{FNN} or, if \meta{FNN} is absent, \meta{Affix}. If both \meta{FNN} and \meta{Affix} are absent when \meta{Alternate} is present, then the obsolete syntax is used (Section~\ref{sec:Obsolete}, not shown below).
%
% \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}
-%
-% \leavevmode\SPatInfo{\ShowPattern[Albert]{Einstein}\break \ShowPattern[M.T.]{Cicero}\break \ShowPattern{Confucius}\break \ShowPattern{Miyazaki, Hayao}\break \ShowPattern{Elizabeth, I}}\vspace{-4.25ex}
-%
-% \begin{center}\small\MyStretch\leavevmode\vspace{-26ex}\IdxInfo{\ShowIdxPageref*[Albert]{Einstein}\break \ShowIdxPageref*[M.T.]{Cicero}\break \ShowIdxPageref*{Confucius}\break \ShowIdxPageref*{Miyazaki, Hayao}\break \ShowIdxPageref*{Elizabeth, I}}\vspace{26ex}
+% \begin{Verbatim}
+% \begin{nameauth}
+% \< Einstein & Albert & Einstein & >
+% \< Carter & J.E. & Carter, Jr. & >
+% \< Confucius & & Confucius & >
+% \< Miyazaki & & Miyazaki, Hayao & >
+% \< Eliz & & Elizabeth, I & >
+% \end{nameauth}
+% \end{Verbatim}
+% \end{quote}
+%
+% \ForgetName[Albert]{Einstein}\ForgetName[J.E.]{Carter, Jr.}
+% \begin{center}\small
+% \vspace{3ex}
+% \BothInfo{\ShowPattern[Albert]{Einstein}\break
+% \ShowPattern[J.E.]{Carter, Jr.}\break
+% \ShowPattern{Confucius}\break
+% \ShowPattern{Miyazaki, Hayao}\break
+% \ShowPattern{Elizabeth, I}}
+% {\ShowIdxPageref*[Albert]{Einstein}\break
+% \ShowIdxPageref*[J.E.]{Carter, Jr.}\break
+% \ShowIdxPageref*{Confucius}\break
+% \ShowIdxPageref*{Miyazaki, Hayao}\break
+% \ShowIdxPageref*{Elizabeth, I}}
+% \vspace{-3ex}\medstretch
% \begin{tabular}{ll}\toprule
% |\Name [Albert]{Einstein}| or |\Einstein| & \Name [Albert]{Einstein}\\
% |\Name*[Albert]{Einstein}| or |\LEinstein| & \LEinstein\\
% |\Name [Albert]{Einstein}| or |\Einstein| & \Einstein\\
-% \rowcolor{grey}|\Name [M.T.]{Cicero}| or |\Cicero| & \Name [M.T.]{Cicero}\\
-% \rowcolor{grey}|\Name*[M.T.]{Cicero}[Marcus Tullius]| & \Name*[M.T.]{Cicero}[Marcus Tullius]\\
-% \rowcolor{grey}|\Name [M.T.]{Cicero}| or |\Cicero| & \Cicero\\
+% \rowcolor{nagrey}|\Name [J.E.]{Carter, Jr.}| or |\Carter| &
+% \Name [J.E.]{Carter, Jr.}\\
+% \rowcolor{nagrey}|\Name*[J.E.]{Carter, Jr.}[James Earl]| &
+% \LCarter[James Earl]\\
+% \rowcolor{nagrey} or |\LCarter[James Earl]|& \\
+% \rowcolor{nagrey}|\Name [J.E.]{Carter, Jr.}| or |\Carter| & \Carter\\
% |\Name {Confucius}|, |\Confucius| & \Confucius\\
-% \footnotesize Same for all variants; no \meta{Affix} or \meta{Alternate}. & \Confucius\\
-% \rowcolor{grey}|\Name {Miyazaki, Hayao}| or |\Miyaz| & \ForgetThis\Name {Miyazaki, Hayao}\\
-% \rowcolor{grey}|\Name*{Miyazaki, Hayao}[Sensei]| & \Name*{Miyazaki, Hayao}[Sensei]\\
-% \rowcolor{grey}|\Name {Miyazaki, Hayao}| or |\Miyaz| & \Name {Miyazaki, Hayao}\\
+% |\Name {Confucius}|, |\Confucius| & \Confucius\\
+% \rowcolor{nagrey}|\Name {Miyazaki, Hayao}| or |\Miyazaki| &
+% \ForgetThis\Name {Miyazaki, Hayao}\\
+% \rowcolor{nagrey}|\Name*{Miyazaki, Hayao}[Sensei]| &
+% \Name*{Miyazaki, Hayao}[Sensei]\\
+% \rowcolor{nagrey}|\Name {Miyazaki, Hayao}| or |\Miyazaki| &
+% \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
% \end{tabular}
% \end{center}
%
-% When using the quick 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]. Remember the following:
-% \begin{center}\small
-% \begin{tabular}{rll}\toprule
-% \rowcolor{grey}No: & \cmd{\LEinstein}\texttt{\ \ \ [said]\dots} & \LEinstein [said]\dots\\
-% \rowcolor{grey}No: & \cmd{\Einstein}\texttt{\ \ \ \ [said]\dots} & \Einstein [said]\dots\\
-% Yes: & \cmd{\LEinstein}\texttt{\{\} [said]\dots} & \LEinstein{} [said]\dots\\
-% Yes: & \cmd{\Einstein}\texttt{\{\}\ \ [said]\dots} & \Einstein{} [said]\dots\\\bottomrule
-% \end{tabular}
-% \end{center}
-% \newpage
+% When using the quick interface, the preferred way to get alternate names is |``\LCarter[James Earl]''| ``\LCarter[James Earl]'' and |``\LMiyazaki[Sensei]''| ``\LMiyazaki[Sensei]''. The alternate forename is not shown in subsequent short name references e.g., |``\Carter[James Earl]''| is just ``\Carter[James Earl]''. Thus, one must use either long-name references or forename references to see the alternate names.
%
-% \subsubsection{Forenames: \texttt{\textbackslash FName}}
+% \subsection{Forenames: \texttt{\textbackslash 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.
+% \cmd{\FName} and its synonym \cmd{\FName*} print personal names only in subsequent name uses.
% \DescribeMacro{\FName*}
-% These synonyms let one add an \texttt{F} either to \cmd{\Name} or \cmd{\Name*} to get the same effect:
-% \begin{quote}
-% \fbox{
-% \begin{tabular}{l}
-% {\Large\strut}\cmd{\FName\ }\oarg{FNN}\marg{SNN|,| Affix}\oarg{Alternate}\vspace{-2pt}\\
-% {\Large\strut}\cmd{\FName*}\oarg{FNN}\marg{SNN|,| Affix}\oarg{Alternate}\\
-% \end{tabular}
-% }
-% \end{quote}
+% That means when a name control sequence does not exist, they print long name forms because it is a first use of a name.
+%
+% Unlike all other starred forms of macros in \textsf{nameauth}, these macros are synonyms because one might edit either \cmd{\Name} or \cmd{\Name*} by adding an \texttt{F} to create a short name instead of the usual forms. This was implemented before the quick interface.
+%
+% \begin{SyntaxBox}
+% \cmd{\FName\ }\oarg{FNN}\marg{SNN|,| Affix}\oarg{Alternate}\\
+% \cmd{\FName*}\oarg{FNN}\marg{SNN|,| Affix}\oarg{Alternate}
+% \end{SyntaxBox}
+%
+% These forename reference macros will permit all name types, but the normal behavior prints forenames only with Western names. With non-Western names only \meta{SNN} is printed. This is designed to prevent Western writers from causing undue offense in Eastern contexts. It also prevents the display of nonsense names in the context of royal names.\medskip
%
% \DescribeMacro{\ForceFN}
-% These macros work with both Eastern and Western names, but to get an Eastern personal name, one must precede these macros with \cmd{\ForceFN}.\Version{3.0} This was designed to discourage one from being too familiar and causing offense.
-% See also Sections~\ref{sec:NameParticles} and~\ref{sec:NameControl} on how to vary some of the forms below:
+% To get an Eastern personal name or any affixed components of an ancient name, or to get \meta{Alternate} to display in their place, one must precede these macros with \cmd{\ForceFN}. See also Section~\ref{sec:NameMedieval} for more uses of \cmd{\ForceFN}.
%
-% \vspace{1.5ex}\leavevmode\SPatInfo{\ShowPattern[Albert]{Einstein}\break \ShowPattern[M.T.]{Cicero}\break \ShowPattern{Confucius}\break \ShowPattern{Miyazaki, Hayao}\break \ShowPattern{Elizabeth, I}}\vspace{-4ex}
-% \begin{center}\small\MyStretch
+% \begin{center}\small
+% \vspace{3ex}
+% \PatInfo{\ShowPattern[Albert]{Einstein}\break
+% \ShowPattern[J.E.]{Carter, Jr.}\break
+% \ShowPattern{Confucius}\break
+% \ShowPattern{Miyazaki, Hayao}\break
+% \ShowPattern{Elizabeth, I}}
+% \vspace{-3ex}\medstretch
% \begin{tabular}{ll}\toprule
% |\FName[Albert]{Einstein}| or |\SEinstein| & \SEinstein\\
-% \rowcolor{grey}|\FName[M.T.]{Cicero}[Marcus Tullius]| & \\
-% \rowcolor{grey}or |\SCicero[Marcus Tullius]| & \SCicero[Marcus Tullius]\\
+% \rowcolor{nagrey}|\FName[J.E.]{Carter, Jr.}[James Earl]| &
+% \SCarter[James Earl]\\
+% \rowcolor{nagrey}or |\SCarter[James Earl]| & \\
% |\FName{Confucius}| or |\SConfucius |& \FName{Confucius}\\
-% \rowcolor{grey}|\FName{Miyazaki, Hayao}| or |\SMiyaz| & \FName{Miyazaki, Hayao}\\
-% |\ForceFN\FName{Miyazaki, Hayao}| & \\
-% or |\ForceFN\SMiyaz| & \ForceFN\FName{Miyazaki, Hayao} \\
-% \rowcolor{grey}|\ForceFN\FName{Miyazaki, Hayao}[Sensei]| & \\
-% \rowcolor{grey}or |\ForceFN\SMiyaz[Sensei]| & \ForceFN\FName{Miyazaki, Hayao}[Sensei]\\
+% \rowcolor{nagrey}|\FName{Miyazaki, Hayao}| or |\SMiyazaki| &
+% \FName{Miyazaki, Hayao}\\
+% |\ForceFN\FName{Miyazaki, Hayao}| & \ForceFN\FName{Miyazaki, Hayao}\\
+% or |\ForceFN\SMiyazaki| & \\
+% \rowcolor{nagrey}|\ForceFN\FName{Miyazaki, Hayao}[Sensei]| &
+% \ForceFN\FName{Miyazaki, Hayao}[Sensei]\\
+% \rowcolor{nagrey}or |\ForceFN\SMiyazaki[Sensei]| & \\
% |\FName{Elizabeth, I}| or |\SEliz| & \SEliz\\
-% \rowcolor{grey}|\ForceFN\SEliz[Good Queen Bess]| & \ForceFN\SEliz[Good Queen Bess]\\\bottomrule
+% \rowcolor{nagrey}|\ForceFN\SEliz[Good Queen Bess]| &
+% \ForceFN\SEliz[Good Queen Bess]\\\bottomrule
% \end{tabular}
% \end{center}
%
-% The \meta{Alternate} argument replaces forenames in the text, which strongly shapes the use of \cmd{\FName}. We apply page~\pageref{page:ArgIV} to forenames:
+% The \meta{Alternate} argument replaces forenames in the text, which strongly shapes the use of \cmd{\FName}. We already have covered the use of \meta{Arg4} of the \texttt{nameauth} environment in Section~\ref{sec:ArgIV}. Please refer to that material when using \meta{Alternate}, especially with the quick interface.
+%
+% \begin{Quote}{\Name[Dwight D.]{Eisenhower}\break
+% \hbox{}\hfill Associated Press luncheon (24 April 1950)}
+% Censorship, in my opinion, is a stupid and shallow way of approaching the solution to any problem. Though sometimes necessary, as witness a professional and technical secret that may have a bearing upon the welfare and very safety of this country, we should be very careful in the way we apply it, because in censorship always lurks the very great danger of working to the disadvantage of the American nation.
+% \end{Quote}
+%
+% \subsection{Technical Details}
+% \label{sec:TechDetails}
+%
+% \subsubsection{Spaces in Arguments}
+%
+% To get consistent index entries (where spaces are significant), all \textsf{nameauth} macros that take name arguments trim extra spaces around each name argument. We shade those areas below, after which we provide an example with suppressed formatting:\medskip
+%
+% \begin{tcolorbox}[colframe=naslate,
+% valign=center,top=0mm,bottom=0mm]\centering
+% \begin{tabular}{c@{\qquad}c@{\qquad}c@{\qquad}c@{\qquad}c}
+% \tcbox[equal height group=F,colback=white,tikznode,
+% left=1mm,right=1mm,valign=center]
+% {\bfseries\meta{\color{nared}FNN}} &
+% \tcbox[equal height group=F,colback=white,tikznode,
+% left=1mm,right=1mm,valign=center]
+% {\bfseries\meta{SNN}} &
+% \tcbox[equal height group=F,colback=white,tikznode,
+% left=1mm,right=1mm,valign=center]
+% {\bfseries\ttfamily\strut\color{nared},} &
+% \tcbox[equal height group=F,colback=white,tikznode,
+% left=1mm,right=1mm,valign=center]
+% {\bfseries\meta{\color{nared}Affix}} &
+% \tcbox[equal height group=F,colback=white,tikznode,
+% left=1mm,right=1mm,valign=center]
+% {\bfseries\meta{\color{nared}Alternate}}
+% \end{tabular}
+% \end{tcolorbox}\smallskip
+%
+% \begin{VerbatimOut}{\jobname.tmp}
+% No spaces:
+% \fbox{\strut\Name*[Martin Luther]{King,Jr.}}
+% \fbox{\strut\Name [Martin Luther]{King,Jr.}}
+% \fbox{\strut\FName[Martin Luther]{King,Jr.}}
+%
+% Spaces:\hspace{1.4em}
+% \fbox{\strut\Name*[ Martin Luther ]{ King , Jr. }}
+% \fbox{\strut\Name [ Martin Luther ]{ King , Jr. }}
+% \fbox{\strut\FName[ Martin Luther ]{ King , Jr. }}
+% \end{VerbatimOut}
+%
% \begin{quote}\small
-% \StartNum
-% \begin{verbatim}
-%\begin{nameauth}
-% \< Lewis & Clive Staples & Lewis & >
-% \< CSL & Clive Staples & Lewis & C.S. >
-% \< Miyaz & & Miyazaki, Hayao & >
-% \< MSens & & Miyazaki, Hayao & Sensei >
-%\end{nameauth}\end{verbatim}
+% \vspace{3.5ex}
+% \BothInfo{\ShowPattern[Martin Luther]{King, Jr.}\break
+% \ShowPattern[ Martin Luther ]{ King , Jr. }}
+% {\ShowIdxPageref*[Martin Luther]{King, Jr.}\break
+% \ShowIdxPageref*[ Martin Luther ]{ King , Jr. }}
+% \vspace{-3.5ex}
+%
+% \VerbatimInput[gobble=0]{\jobname.tmp}
+% \renewcommand*\NamesFormat{}
+% \renewcommand*\MainNameHook{}
+%
+% \input{\jobname.tmp}
% \end{quote}
%
+% Now we resume this manual's formatting to help show that the names below are different, even though they appear similar.
+%
+% Non-breaking spaces, explicit spaces, thin spaces, and macros that expand to spaces \emph{are not trimmed} by either \LaTeX\ or \textsf{nameauth}. They produce different name patterns and, if used in macro arguments, must be used consistently (Section~\ref{sec:NameParticles}). Below we suppress indexing and show three different names:
+%
+% \begin{center}\IndexInactive\small\medstretch
+% \begin{tabular}{lcl}\toprule
+% Macro\,/\,Char: & Appearance: & Name Pattern:\\
+% \rowcolor{nagrey}|\Name{foo~bar}| & \Name{foo~bar} &
+% \ttfamily\ShowPattern{foo~bar} \\
+% |\Name{foo\ bar}| & \Name{foo\ bar} & \ttfamily\ShowPattern{foo\ bar} \\
+% \rowcolor{nagrey}|\Name{foo\space bar}| &
+% \Name{foo\space bar} & \ttfamily\ShowPattern{foo\space bar} \\\bottomrule
+% \end{tabular}\IndexActive
+% \end{center}
+%
+% \subsubsection{Full Stop Detection}
+%
+% Western names tend to use full stops in these cases:
+%
% \begin{itemize}
-% \item They\SPatInfo{\ShowPattern[Clive Staples]{Lewis}\break \ShowPattern{Miyazaki, Hayao}} share name control patterns (Section~\ref{sec:NamePatterns}). Therefore, they have the same ``first-use'' and ``later-use'' conditions.
-% \item Usually, one adds alternate names to shorthands with an empty \meta{arg4}:\\[1ex]
-% \vspace{-11ex}\IdxInfo{\ShowIdxPageref*[Clive Staples]{Lewis}\break \ShowIdxPageref*{Miyazaki, Hayao}}\vspace{11ex}\leavevmode
-% \begin{tabular}{l@{\ }ll@{\ }l}\toprule
-% \cmd{\SLewis[C.S.]} & \SLewis[C.S.] & \cmd{\SCSL} & \SCSL\\
-% \rowcolor{grey}\cmd{\SMiyaz[Sensei]} & \SMiyaz[Sensei] & \cmd{\SMSens} & \SMSens\\
-% \cmd{\ForceFN}\cmd{\SMiyaz[Sensei]} & \ForceFN\SMiyaz[Sensei] & \cmd{\ForceFN}\cmd{\SMSens} & \ForceFN\SMSens\\\bottomrule
-% \end{tabular}
-% \item Trying to add ``alternate names'' to shorthands that use \meta{arg4} fails:\\[1ex]
-% \begin{tabular}{l@{\ }l}\toprule
-% \rowcolor{grey}\cmd{\SCSL[Jack]} & \SCSL[Jack]\\
-% \cmd{\ForceFN}\cmd{\SMSens[Sensei]} & \ForceFN\SMSens[Sensei]\\\bottomrule
-% \end{tabular}
+% \item After the initial letter abbreviation of forenames.
+% \item After affixes: ``Jr''. (junior), ``Sr''. (senior), ``d.\,Ä.''
+% (\textit{der Ältere}), ``d.\,J.'' (\textit{der Jüngere}) etc.
+% \item In some contexts, after degrees like ``M.D.'' (\textit{Medicinae
+% Doctor}), J.D. (\textit{Juris Doctor}), Ph.D.
+% (\textit{Philosophiae Doctor}), etc.
% \end{itemize}
%
-% \ReturnLink
-% \newpage
+% The naming macros and some others (Section~\ref{sec:AKA}) check if the printed name ends with a full stop. They also check the lookahead token for a full stop and gobble the lookahead. In the following example we ``forget'' the existence of a name pattern via \cmd{\ForgetName} below (Section~\ref{sec:NameControl}) to simulate not having seen it before:
%
-% \subsubsection{Variant Names}
-% \label{sec:VarNames}
+% \begin{VerbatimOut}{\jobname.tmp}
+% Full stop on lookahead gobbled\dotfill
+% \Name[Martin Luther]{King, Jr.}[Rev. Dr. Martin Luther].
+%
+% Full stop remains (affix auto-drops)\dotfill
+% Rev. Dr. \Name[Martin Luther]{King, Jr.}.
+%
+% Full stop gobbled (force long name form)\dotfill
+% \Name*[Martin Luther]{King, Jr.}.
%
-% 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:GeneralIndex}, \ref{sec:IndexSort}, \ref{sec:Formatting}, and \ref{sec:NameControl}. One might want to consult those sections also.\medskip
+% Full stop remains (force affix to drop)\dotfill
+% \DropAffix\Name*[Martin Luther]{King, Jr.}.
+%
+% Full stop gobbled (alternate using initials)\dotfill
+% \FName[Martin Luther]{King, Jr.}[M.L.].
+% \end{VerbatimOut}
%
-% 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}
+% \VerbatimInput[gobble=0]{\jobname.tmp}
+% \ForgetName[Martin Luther]{King, Jr.}
+%
+% \input{\jobname.tmp}
% \end{quote}
%
-% Below,\SPatInfo{\ShowPattern[Mike]{Tyson}} all variants have the same pattern and index entry because they are based on the same name form:
+% \subsubsection{Braces and Spaces}
%
-% \begin{quote}\small\leavevmode\vspace{-8ex}\IdxInfo{\ShowIdxPageref*[Mike]{Tyson}}\vspace{8ex}
-% \begin{tabular}{rlrl}
-% \cmd{\Iron} & \Iron & \cmd{\LTyson[Iron Mike]} & \LTyson[Iron Mike]\\
-% \cmd{\LIron} & \LIron & \cmd{\LTyson} & \LTyson\\
-% \cmd{\SIron} & \SIron & \cmd{\STyson} & \STyson\\
+% We disable indexing for the examples below so that we do not generate unwanted entries. Take care when using curly braces \texttt{\bfseries\{\,\}} in naming macro arguments. They will produce different names, as the formatting shows:
+%
+% \IndexInactive
+% \begin{center}\small\medstretch
+% \begin{tabular}{llll}\toprule
+% & Macro: & Result: & Name Pattern:\\
+% \rowcolor{nagrey} 1 & |\Name[one]{two}| & \Name[one]{two} &
+% \ttfamily\ShowPattern[one]{two} \\
+% 2 & |\Name[{one}]{{t}w{o}}| & \Name[{one}]{{t}w{o}} &
+% \ttfamily\ShowPattern[{one}]{{t}w{o}} \\
+% \rowcolor{nagrey} 3 & |\Name{one, two}| & \Name{one, two} &
+% \ttfamily\ShowPattern{one, two} \\
+% 4 & |\Name{{one}, two}| & \Name{{one}, two} &
+% \ttfamily\ShowPattern{{one}, two} \\
+% \rowcolor{nagrey} 5 & |\Name{{one, two}}| & \Name{{one, two}} &
+% \ttfamily\ShowPattern{{one, two}} \\\bottomrule
% \end{tabular}
-% \end{quote}
-% Since \LIron\ is indexed as ``\ShowIdxPageref*[Mike]{Tyson}'' throughout the document, we can use \cmd{\IndexRef\{Iron Mike\}\{Tyson, Mike\}}\IndexRef{Iron Mike}{Tyson, Mike}, which produces no output in the text. Thus we get ``Iron Mike \textit{see} Tyson, Mike'' as a cross-reference in the index.\medskip
+% \end{center}
%
-% Variant\Info{Variant surnames} family names are more complicated. The following method avoids using macros in name arguments (cf. Page~\pageref{page:Romani}) to get decent results:
-% \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, William}%
-%\PretagName[W.E.B.]{DuBois}{Dubois, William}\end{verbatim}
-% \end{quote}
-% \begin{itemize}
-% \item We decide\SPatInfo{\ShowPattern[W.E.B.]{Du~Bois}\break \ShowPattern[W.E.B.]{DuBois}} the canonical name form: \cmd{\DuBois} \ForgetThis\DuBois.
-% \item Both \cmd{\Name[W.E.B.]\{Du Bois\}} and \cmd{\Name[W.E.B.]\{DuBois\}} have the same pattern: \texttt{\ShowPattern[W.E.B.]{DuBois}} (Section~\ref{sec:NamePatterns}).
-% \item Here\vspace{-3ex}\IdxInfo{\ShowIdxPageref*[W.E.B.]{Du~Bois}\break \ShowIdxPageref*[W.E.B.]{DuBois}}\vspace{3ex} we use |\Name[W.E.B.]{Du~Bois}| to avoid bad breaks.
-% \item The sort key for both names is \texttt{\{Dubois, William\}}. Had we kept the space, the name would be sorted before \texttt{dual} (Section~\ref{sec:IndexSort}). One may have to spell out a name when sorting its initials.
-% \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{itemize}
+% Names one and two are Western; names three and four are non-Western. All names have different patterns and different index entries, even if they look similar in the text (Sections~\ref{sec:NamePatterns}, \ref{sec:IndexSort}). Name~5 is very tricky. The parts of |\Name{{one, two}}| are: \ShowNameInfo{{one, two}}. Compare that with the parts of |\Name{one, two}|: \ShowNameInfo{one, two}. This can affect alternate formatting (Section~\ref{sec:AltFormat}).
+% \IndexActive
%
-% \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).}
+% Curly braces can change the lookahead token and defeat punctuation detection (as well as create a unique name). Using spaces between a name and a full stop can have a similar effect:
%
-% 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{VerbatimOut}{\jobname.tmp}
+% Full stop remains (not in group)\dotfill
+% Dr. {\Name*[Martin Luther]{King, Jr.}}.
%
-% \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}
+% Full stop is gobbled (in containing group)\dotfill
+% Dr. {\Name*[Martin Luther]{King, Jr.}.}
%
-% This author used the vernacular forms as canonical, with the Latin versions as alternates. I translated all the place-names.
+% Full stop remains (affix in own group)\dotfill
+% Dr. \SkipIndex\Name*[Martin Luther]{King, {Jr.}}.
%
-% Below we have candidates for sorting with \cmd{\PretagName} (Section~\ref{sec:IndexSort}) and potential use of \cmd{\CapThis} (Section~\ref{sec:NameParticles}). \emph{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:GeneralIndex}). If one were to use the alternate name \emph{before} using \cmd{\IndexRef}, then \cmd{\SeeAlso}\cmd{\IndexRef} would be used after all name references.
+% Full stop is gobbled (outside affix group)\dotfill
+% Dr. \SkipIndex\Name*[Martin Luther]{King, {Jr}.}.
%
-% \begin{quote}\small\vspace{3.5ex}\SPatInfo{\ShowPattern[Jacques]{De~Pamele}\break \ShowPattern[Jacobus]{Pamelius}\break \ShowPattern[Giovanni]{d'Andrea}\break \ShowPattern[Ioannes]{Andreae}}
-% \vspace{-3ex}
-% \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}
+% Full stop remains (intervening space)\dotfill
+% Dr. \Name*[Martin Luther]{King, Jr.} .
%
-%\PretagName[Giovanni]{d'Andrea}{Dandrea, Giovanni}
-%\Name[Giovanni]{d'Andrea}
-%\IndexRef[Ioannes]{Andreae}{d'Andrea, Giovanni}
-%\Name[Ioannes]{Andreae}\end{verbatim}
+% Full stop gobbled (follows macro cs)\dotfill \LPatton .
%
-% \leavevmode\vspace{-12ex}\IdxInfo{\ShowIdxPageref*[Jacques]{De~Pamele}\break \ShowIdxPageref*[Jacobus]{Pamelius}\break \ShowIdxPageref*[Giovanni]{d'Andrea}\break \ShowIdxPageref*[Ioannes]{Andreae}}\vspace{12ex}
+% Full stop remains (follows optarg)\dotfill \LPatton[George] .
+% \end{VerbatimOut}
%
-% \begin{tabular}{ll}\toprule
-% Canonical Name & Alternate Name\\\midrule
-% \rowcolor{grey}\Name[Jacques]{De~Pamele}[Jacques de~Joigny]\IndexRef[Jacobus]{Pamelius}{De~Pamele, Jacques} &
-% \Name[Jacobus]{Pamelius}\\
-% \Name[Giovanni]{d'Andrea}\IndexRef[Ioannes]{Andreae}{d'Andrea, Giovanni} &
-% \Name[Ioannes]{Andreae}\\\bottomrule
-% \end{tabular}
+% \begin{quote}\small
+% \VerbatimInput[gobble=0]{\jobname.tmp}
+%
+% \input{\jobname.tmp}
% \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}.
+%
+% \subsubsection{Formatting Initials}
+%
+% This is a thorny topic. Some publishers are dead-set on having a space between initials. Many designers find that practice to be inelegant at best. [\hyperlink{Bringhurst}{Bringhurst}] wisely advises one to omit spaces between initials.
+%
+% Yet fighting with one's editor will be a lost cause unless one already has sufficient \textit{gravitas}. If a style guide requires spaces, try thin spaces. The quick interface reduces the likelihood that one will produce names that look the same, but whose arguments and name patterns differ. Below we use no formatting:
+%
+% \begin{quote}^^A Normal size to show the spacing better.
+% \begin{minipage}[c]{0.45\textwidth}
+% \begin{Verbatim}
+% \PretagName[E.\,B.]{White}%
+% {White, Elwyn}
+% \begin{nameauth}
+% \< White & E.\,B. & White & >
+% \end{nameauth}
+% \end{Verbatim}
+% \end{minipage}
+% \begin{minipage}[c]{0.35\textwidth}
+% \renewcommand*\NamesFormat{}\renewcommand*\MainNameHook{}
+% \def\sep{\vrule width0.5pt\kern-0.5pt}%
+% \begin{tabular}{@{}ll@{}}
+% \cmd{\LWhite} & \hspace{0.48pt}\LWhite\\
+% & \sep\hphantom{E.}\sep\,\sep\hphantom{B.}\sep\hphantom{\ }^^A
+% \sep\hphantom{White}\sep\\\hline
+% & \sep\hphantom{E.}\sep\ \sep\hphantom{B.}\sep\ \sep\hphantom{White}\sep\\
+% Normal text:\hfill & E. B. White\\
+% \end{tabular}
+% \end{minipage}
+% \end{quote}
+%
+% One might notice that we used \cmd{\PretagName} to sort this name by something other than its initials: ``White, Elwyn''. sorting only by initials (and with embedded macros like a thin space) will produce unexpected orderings of entries (Section~\ref{sec:IndexInitials}).
%
% \ReturnLink
+%
+% \begin{Quote}{\Name[Leonard]{Bernstein}\break
+% \hbox{}\hfill ``What Makes Opera Grand?'', \textit{Vogue}
+% (December 1958)}
+% \textls[-15]{Any great work of art \dots revives and readapts time and space, and the measure of its success is the extent to which it makes you an inhabitant of that world\,---\,the extent to which it invites you in and lets you breathe its strange, special air.}
+% \end{Quote}
+%
% \newpage
%
-% \subsection{Language Topics}
+% \section{Language Topics}
% \label{sec:Lang}
-% Here we focus on specific issues that are related to parts of names used differently in various cultures and kinds of names related to specific cultures. Comma-delimited affixes \meta{SNN, Affix} are a key concept here. Advanced topics in this section draw on Sections~\ref{sec:Indexing}, \ref{sec:Formatting}, \ref{sec:AltFormat}, and \ref{sec:NameDecisions}.
%
-% \subsubsection[Affixes]{Affixes Require Commas}
+% Here we cover technical issues related to various languages and cultures.
+%
+% \subsection[Active Characters]{Caveats with Active Characters}
+%
+% Active characters affect name patterns and index sorting, depending on the \LaTeX\ engine being used. We pay more attention to \cmd{\PretagName} (Section~\ref{sec:IndexSort}; cf.~\ref{sec:Unicode}):\footnote{Regarding the margin note that shows name control sequences, with \texttt{pdflatex} and \texttt{latex}, in \texttt{\ShowPattern{Æthelred, II}} the glyphs \texttt{ÃĘ} correspond to \cmd{\IeC\{}\cmd{\AE\}}. Likewise in \texttt{\ShowPattern{Boëthius}} the glyphs \texttt{Ãń} correspond to \cmd{\IeC\{}\cmd{\"e\}}.}
+%
+% \begin{enumerate}\small
+% \vspace{4ex}
+% \PatInfo{\ShowPattern{Æthelred, II} \textrm{(1)}\break
+% \ShowPattern{\AE thelred, II} \textrm{(2)}\break
+% \ShowPattern{Bo\"ethius} \textrm{(3)}\break
+% \ShowPattern{Boëthius} \textrm{(4)}\break
+% \ShowPattern{Bo{\"e}thius} \textrm{(5)}}
+% \vspace{-4ex}
+% \item |\Name*{Æthelred, II}|\dotfill \Name*{Æthelred, II}
+% \item[] We have seen this name earlier, as the formatting shows.
+% \item[] We sort this with |\PretagName{Æthelred, II}{Aethelred, 2}|
+% \item |\SkipIndex\Name{\AE thelred, II}|\dotfill
+% \SkipIndex\Name{\AE thelred, II}
+% \item[] This name is new, as the formatting shows us. It looks like the
+% name above, but its control pattern differs by the macro \cmd{\AE}.
+% \item[] We get a different index entry, regardless of how we sort it.
+% \item |\Name{Bo\"ethius}|\dotfill \Name{Bo\"ethius}
+% \item[] This new name uses |\"e| to display a lowercase e with a diaeresis.
+% \item[] We sort it with |\PretagName{Bo\"ethius}{Boethius}|.
+% \item |\SkipIndex\Name{Boëthius}|\dotfill \SkipIndex\Name{Boëthius}
+% \item[] This name differs by the character ë.
+% \item |\SkipIndex\Name{Bo{\"e}thius}|\dotfill \SkipIndex\Name{Bo{\"e}thius}
+% \item[] Yet another different name differs by grouping tokens. These are
+% significant with regard to name patterns and indexing.
+% \end{enumerate}
+%
+% \subsection{Hyphenation}
+% \negmedskip
+% \NameArgWarning
+%
+% In modern English, names can be hyphenated to reflect their cultural origins. With \textsf{nameauth}, one can handle such names by using optional hyphens, the \textsf{babel} package, or the \textsf{polyglossia} package. Below we offer an example using a mancro that does not expand differently throughout the document.\footnote{Using macros in name arguments does introduce potential problems that we discuss in Sections~\ref{sec:NameParticles}, \ref{sec:AltFormat}, and elsewhere, showing how to prevent errors.}
+% \IndexName[John]{\noexpand\de{Strietelmeier}}
+%
+% \begin{quote}\small
+% \begin{Verbatim}
+% \newcommand\de[1]{\foreignlanguage{ngerman}{#1}}
+% % or polyglossia: \newcommand\de[1]{\textgerman{#1}}
+%
+% \begin{nameauth}
+% \< Striet & John & \noexpand\de{Strietelmeier} & >
+% \end{nameauth}
+%
+% \PretagName[John]{\noexpand\de{Strietelmeier}}
+% {Strietelmeier, John}
+% \end{Verbatim}
+% \end{quote}
+%
+% \begin{itemize}
+% \item \textbf{Example 1: Default Hyphenation}
+%
+% \item[] Here\PatInfo{\ShowPattern[John]{Strietelmeier}} we use the default hyphenation. Using \cmd{\textls} from \textsf{microtype} we get the name to break badly. We omit this version from the index. One might think that the name were pronounced ``stre-et-el-mei-er''.\smallskip
+%
+% \item[] \textls[5]{In English, some names come from other cultures. Names
+% like \SkipIndex\Name[John]{Strietelmeier}
+% \cmd{\SkipIndex}\cmd{\Name[John]\{Strietelmeier\}} can break badly.}\medskip
+%
+% \item \textbf{Example 2: Discretionary Hyphens}
+%
+% Here\PatInfo{\ShowPattern[John]{Strie\-tel\-meier}} we create a different name from the one above. One must use the discretionary hyphens consistently in the macro arguments. We also omit this version from the index. We see that it breaks properly.\smallskip
+%
+% \item[] \textls[9]{In English, some names come from other cultures. Names
+% like \SkipIndex\Name[John]{Strie\-tel\-meier}}
+% \textls[10]{\cmd{\SkipIndex}^^A
+% \cmd{\Name[John]\{Strie\textbackslash-tel\textbackslash-meier\}}
+% break badly in some cases.}\medskip
+%
+% \item \textbf{Example 3: Language Packages}
+%
+% Finally\PatInfo{\textls[-5]{\ShowPattern[John]{\de{Strietelmeier}}}} we use the general solution shown above with \textsf{babel} or \textsf{polyglossia}. Since the leading element of \meta{SNN} is a macro, using \cmd{\CapThis} would halt \LaTeX\ with errors unless we used alternate formatting that does not segment the argument (Section~\ref{sec:AltFormat}):\smallskip
+%
+% \item[] \textls[7]{In English, some names come from other cultures. Names
+% like} \Striet, \textls[20]{\cmd{\Striet} or
+% \cmd{\Name[John]\{}\cmd{\noexpand}\cmd{\de\{Strietelmeier\}\}}}\break
+% break badly in some cases.
+% \end{itemize}
+%
+% \subsection{Affixes Need Commas}
% \label{sec:Affix}
%
-% A comma\SPatInfo{\ShowPattern[Oskar]{Hammerstein, II}\break \ShowPattern{Louis, XIV}\break \ShowPattern{Sun, Yat-sen}} separates a Western surname and affix; a ``native'' Eastern family name and personal name; and a royal, medieval, or ancient name and affix. To avoid errors, one must treat \meta{SNN, Affix} as two separate arguments (Section~\ref{sec:AltFormat}). Spaces around the comma are ignored.
+% \negmedskip\begin{InfoBox}
+% Regarding an \meta{SNN, Affix} pair, the key to avoiding error is to apply macros to \meta{SNN} and \meta{Affix} as if they were independent arguments.\end{InfoBox}
+%
+% A comma is not a required name element unless used in an \meta{SNN, Affix} pair. When thus used it delimits a Western surname from its affix, an Eastern family name from a personal name, and an ancient name from an affix.
%
-% \begin{center}\small\ForgetName{Sun, Yat-sen}\IdxInfo{\ShowIdxPageref*[Oskar]{Hammerstein, II}\break \ShowIdxPageref*{Louis, XIV}\break \ShowIdxPageref*{Sun, Yat-sen}}\MyStretch
+% When a comma appears in a required name argument, each member of the \meta{SNN, Affix} pair is treated as a separate argument. Thus, we say that the comma segments the macro argument.
+%
+% If one encapsulates an \meta{SNN, Affix} pair within a macro, \LaTeX\ may halt with errors. We have seen above that spaces around the comma are ignored.
+%
+% \begin{center}\small
+% \vspace{1ex}
+% \BothInfo{\ShowPattern[Oskar]{Hammerstein, II}\break
+% \ShowPattern{Louis, XIV}\break
+% \ShowPattern{Sun, Yat-sen}}
+% {\ShowIdxPageref*[Oskar]{Hammerstein, II}\break
+% \ShowIdxPageref*{Louis, XIV}\break
+% \ShowIdxPageref*{Sun, Yat-sen}}
+% \vspace{-1ex}\medstretch
+% \ForgetName{Sun, Yat-sen}
% \begin{tabular}{ll}\toprule
% |\Name[Oskar]{Hammerstein, II}| & \KeepAffix\Name[Oskar]{Hammerstein, II}\\
% |\Name[Oskar]{Hammerstein, II}| & \Name[Oskar]{Hammerstein, II}\\
-% \rowcolor{grey}|\Name{Louis, XIV}| & \KeepAffix\Name{Louis, XIV}\\
-% \rowcolor{grey}|\Name{Louis, XIV}| & \Name{Louis, XIV}\\
+% \rowcolor{nagrey}|\Name{Louis, XIV}| & \KeepAffix\Name{Louis, XIV}\\
+% \rowcolor{nagrey}|\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\SPatInfo{\ShowPattern[Oskar]{Hammerstein}[II]} names with affixes must use \meta{SNN, Affix}, never the obsolete syntax, which is meant for non-Western names and is discouraged. We get \SkipIndex\Name[Oskar]{Hammerstein}[II] and a bad index entry from, e.g., \cmd{\SkipIndex}\cmd{\Name[Oskar]\{Hammerstein\}[II]}.\medskip
-%
+% \newpage
+%
+% Western names with affixes must use \meta{SNN,Affix},^^A
+% \PatInfo{\ShowPattern[Oskar]{Hammerstein}[II]} never the obsolete syntax, which is meant for non-Western names and is discouraged. We get \SkipIndex\Name[Oskar]{Hammerstein}[II] and a bad index entry from, e.g., \cmd{\SkipIndex}\cmd{\Name[Oskar]\{Hammerstein\}[II]}.\medskip
+%
% \DescribeMacro{\KeepAffix}
-% In the text only, \cmd{\KeepAffix} turns the space \emph{between} \meta{SNN} and \meta{Affix} into a non-breaking space if both \meta{SNN} and \meta{Affix} are displayed. This macro works with all name types, even with the obsolete syntax.\medskip
+% If the name displayed in the text shows both \meta{SNN} and \meta{Affix}, then \cmd{\KeepAffix} turns the space \emph{between} \meta{SNN} and \meta{Affix} into a non-breaking space. \cmd{\KeepAffix}\cmd{\Name\{Louis, XIV\}} will not break between \Name{Louis, XIV} and \ForceFN\FName{Louis, XIV}. All name types that use \meta{Affix} are supported. \medskip
%
% \DescribeMacro{\KeepName}
-% In the text only, \cmd{\KeepName} turns all spaces \emph{between} name elements \meta{FNN}, \meta{SNN}, and \meta{Affix} into non-breaking spaces if those elements are displayed.\Version{3.1} This macro does not alter spaces \emph{within} name elements that have multiple names like French or German forenames and Spanish surnames. As above, this macro works with all name types, even with the obsolete syntax.\medskip
+% In longer name forms, \cmd{\KeepName} turns spaces \emph{between} all visible name elements into non-breaking spaces.
+%
+% \begin{itemize}\small
+% \item |\Name[Sandra Day]{O'Connor}| \Name[Sandra Day]{O'Connor} has two
+% points where the name can break: after \FName[Sandra Day]{O'Connor}[Sandra]
+% and after \FName[Sandra Day]{O'Connor}[Day].
+% \item |\KeepName\Name*[Sandra Day]{O'Connor}|
+% \KeepName\Name*[Sandra Day]{O'Connor}
+% has one point where the name can break: after
+% \FName[Sandra Day]{O'Connor}[Sandra].
+% \end{itemize}
+%
+% This macro does not alter spaces \emph{within} name elements composed of multiple names, like French or German forenames and Spanish surnames. \cmd{\KeepName} works with all name types.\medskip
%
% \DescribeMacro{\DropAffix}
-% Preceding the naming macros with \cmd{\DropAffix} will suppress an affix only in a Western name. |\DropAffix\Name*[Oskar]{Hammerstein, II}| produces\Version{3.0} ``\DropAffix\Name*[Oskar]{Hammerstein, II}''. This macro does not affect non-Western names.
-%
+% If \cmd{\DropAffix} precedes only a Western name, it will suppress the affix after the surname in a first or long reference. We get ``\DropAffix\Name*[Oskar]{Hammerstein, II}'' From |\DropAffix\Name*[Oskar]{Hammerstein, II}|.
+%
% With non-Western names, the \meta{Affix} in the \meta{SNN, Affix} pair drops automatically in the text for subsequent uses, making \cmd{\DropAffix} redundant. We see that above in the case of \Name*{Louis,XIV}, who becomes \Name{Louis,XIV}.\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 text.
+% In a long name form, \cmd{\ShowComma} forces the display of a comma between a Western name and its affix.
% \DescribeMacro{\NoComma}
-% One uses \cmd{\ShowComma} with older publication styles that separate a Western name and affix with a comma. \cmd{\NoComma} works like the \texttt{nocomma} option in the body text on a per-name basis. Neither of these macros affect the use of \cmd{\RevComma}, which always prints a comma.
-% \begin{center}\small\MyStretch
+% It works like the \texttt{comma} option on a per-name basis, and only in the text. One uses \cmd{\ShowComma} with older publication styles that separate a Western name and affix with a comma. \cmd{\NoComma} works like the \texttt{nocomma} option in the body text on a per-name basis.
+%
+% \begin{center}\small\medstretch
% \begin{tabular}{ll}\toprule
-% \rowcolor{grey}|\ShowComma\LPat| & \ShowComma\LPat\\
-% |\NoComma\LPat| & \NoComma\LPat\\\bottomrule
+% |\ShowComma\LPatton| & \ShowComma\LPatton\\
+% \rowcolor{nagrey}|\NoComma\LPatton| & \NoComma\LPatton\\\bottomrule
% \end{tabular}
% \end{center}
%
-% \ReturnLink
-% \newpage
+% Neither \cmd{\ShowComma}, \cmd{\NoComma}, nor their related package options interact with the use of \cmd{\RevComma} and friends (Sections~\ref{sec:Priorities} and~\ref{sec:LastFirst}).
%
-% \subsubsection[Listing by Surname]{Listing Western names by Surname}
-% \label{sec:LastFirst}
-%^^A Starting with this point, if there is an error in the docs then the aux files will
-%^^A be ruined and must be deleted. Above this point it will be okay. Why?
+% \subsection[Eastern Names, Name Caps]
+% {Eastern Names and Family Names in All Caps}
+% \label{sec:Eastern}
%
-% \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 only long Western and ``non-native'' Eastern name forms.\Version{3.0} The first two are broad toggles, while the third works on a per-name basis.
-%
-% \vspace{1.5ex}\leavevmode\SPatInfo{\ShowPattern[Oskar]{Hammerstein, II}\break \ShowPattern[Hideyo]{Noguchi}\break \ShowPattern{Æthelred,II}\break \ShowPattern{Sun, Yat-sen}\break \ShowPattern{Confucius}}\vspace{-4ex}
-% \begin{center}\small\MyStretch
-% \begin{tabular}{lll}\toprule
-% \ForgetThis\VBuren & \RevComma\LVBuren & change\\
-% \ForgetThis\Name[Oskar]{Hammerstein, II} & \RevComma\Name*[Oskar]{Hammerstein, II} & change\\
-% \ForgetThis\LNoguchi & \RevComma\LNoguchi\dag & change\\
-% \rowcolor{grey}\ForgetThis\Aeth & \RevComma\LAeth & no change\\
-% \rowcolor{grey}\ForgetThis\Name{Sun, Yat-sen} & \RevComma\Name*{Sun, Yat-sen} & no change\\
-% \rowcolor{grey}\ForceName\Name{Confucius} & \RevComma\Name{Confucius} & no change\\\bottomrule
-% \end{tabular}
-% \end{center}
+% Proper Eastern names, included with ancient and medieval forms in the broader group of non-Western names, are encoded using comma-delimited syntax (compare the obsolete syntax in Section~\ref{sec:Obsolete}). They have non-Western index entries: \meta{SNN} \meta{Affix} (no comma between name elements). The current syntax permits alternate names; the obsolete does not.
%
-% 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.
+% \begin{SyntaxBox}
+% \cmd{\Name}\marg{SNN, Affix}\oarg{Alternate}
+% \end{SyntaxBox}
%
-% \ReturnLink
+% Even in some academic texts, one sees non-Western names encoded with Western forms.\footnote{\textls[-5]{Jaroslav Pelikan, \textit{The Christian Tradition}, 5 vols. (Chicago: Chicago UP, 1971–1989); Immanuel Geiss, \textit{Personen: Die biographische Dimension der Weltgeschichte}, Geschichte Griffbereit vol. 2 (Munich: Wissen Media Verlag, 2002).} At this time, \href{https://www.nndb.com/}{\bfseries NNDB} sorts \Name{Kim, Jong Un} under U, not K.}
+% The \textsf{nameauth} package seeks to remedy that issue, which has more to do with outsourcing indexes to non-expert providers than with scholars. For example, the macro |\Name*{Sun, Yat-sen}| \Name*{Sun, Yat-sen} ensures correct forms in the text and the index. We get cross-cultural sensitivity and scholarly accuracy.\medskip
%
-% \subsubsection{Eastern Names}
-% \label{sec:Eastern}
+% \DescribeMacro{\AllCapsActive}
+% Certain contexts call for one's entire family name to be capitalized. This differs
+% \DescribeMacro{\AllCapsInactive}
+% from the way in which initial letter capitalization is handled (Section~\ref{sec:NameParticles}). In addition to the \texttt{allcaps} package option
+% \DescribeMacro{\CapName}
+% (Section~\ref{sec:PkgOptions}), \cmd{\AllCapsActive} and \cmd{\AllCapsInactive} work for blocks of text. All have priority over \cmd{\CapName}, which works once per name. These capitalize \meta{SNN} in the body text only. They also work with \cmd{\AKA} and friends. For capitalization in both the text and index (beyond doing it manually) see Sections~\ref{sec:AltFormat} and~\ref{sec:AdvCustomize}.\medskip
%
-% All non-Western name forms using the \textsf{nameauth} macros omit the first optional argument. Yet the reversing macros can make Western names have Eastern name order, but only in the text, not in the index.\medskip
+% 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.
%
-% One\Info{``Non-native''} produces a ``non-native'' Eastern name in the text by reversing a Western name without \meta{Affix} using \cmd{\RevName}, e.g.:
-% \begin{quote}
-% \fbox{
-% \begin{tabular}{l}
-% {\Large\strut}\cmd{\RevName}\cmd{\Name}\oarg{FNN}\marg{SNN}\oarg{Alternate}\\
-% \end{tabular}
-% }
-% \end{quote}
-% 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
+% \vspace{2ex}
+% \BothInfo{\ShowPattern[Hideyo]{Noguchi}\break
+% \ShowPattern{Miyazaki, Hayao}}
+% {\ShowIdxPageref*[Hideyo]{Noguchi}\break
+% \ShowIdxPageref*{Miyazaki, Hayao}}
+% \vspace{-2ex}
+% \begin{center}\small\medstretch
+% \begin{tabular}{ll}\toprule
+% |\LNoguchi| & \LNoguchi \\
+% \rowcolor{nagrey}|\CapName\LNoguchi}| & \CapName\LNoguchi\\
+% |\LMiyazaki| & \LMiyazaki \\
+% \rowcolor{nagrey}|\CapName\LMiyazaki| & \CapName\LMiyazaki\\\bottomrule
+% \end{tabular}
+% \end{center}
%
-% In\Info{``Native''} contrast, ``native'' Eastern names use either comma-delimited syntax or the obsolete syntax (Section~\ref{sec:Obsolete}). They have index entries appropriate to Eastern names: \meta{SNN} \meta{Affix} (no comma). The current syntax permits alternate names; the obsolete does not. These forms work also with ancient and medieval names:
+% \subsection{Reversed Names}
+% \label{sec:RevNames}
%
-% \begin{quote}
-% \fbox{
-% \begin{tabular}{ll}
-% {\Large\strut}\cmd{\Name}\marg{SNN, Affix}\oarg{Alternate} & \color{nared}\texttt{\%} \textit{new syntax}\\
-% \end{tabular}
-% }
-% \end{quote}
-%
-% People\Info{Avoid error} can make mistakes that these forms help one to avoid. For example, in an otherwise excellent German-language multi-volume history text, one finds the incorrect, Western-form index entry ``\ShowIdxPageref*[Sun]{Yat-Sen}''. It should be ``\ShowIdxPageref*{Sun, Yat-sen}''.\footnote{See Immanuel Geiss, \textit{Personen: Die biographische Dimension der Weltgeschichte}, Geschichte Griffbereit vol. 2 (Munich: Wissen Media Verlag, 2002), 720.}
-% The macro |\Name*{Sun, Yat-sen}| \Name*{Sun, Yat-sen} ensures the correct entry by using the correct form. The goal is to promote cross-cultural sensitivity.\medskip
-% \newpage
+% Sometimes the name form in the text differs from its expected index entry, as we saw with Hungarian names. In another example, a publisher might expect Western-style name forms in the index. In \textsf{nameauth} we can use the reversing option and macros to change the form in the text while not disturbing the index entries.\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.
+% In addition to the \texttt{allreversed} option for reversing name order (Section~\ref{sec:PkgOptions}), \cmd{\ReverseActive} and \cmd{\ReverseInactive} do the same for blocks of text.
% \DescribeMacro{\ReverseInactive}
-% These all override the use of \cmd{\RevName}, which reverses once per name.
+% These all have priority over the use of \cmd{\RevName}, used once per name.
% \DescribeMacro{\RevName}
-% These macros do not affect the index. They work also with \cmd{\AKA} and friends. Reversing only affects long name forms. ``Non-native'' forms are shown with a dagger (\dag):
+% These macros do not affect the index. They work also with \cmd{\AKA} and friends. Reversing only affects long name forms. In this manual, reversed Western forms are shown with a dagger (\dag).\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.
%
-% \vspace{1.5ex}\leavevmode\SPatInfo{\ShowPattern[Hideyo]{Noguchi}\break \ShowPattern{Miyazaki, Hayao}}\vspace{-3.5ex}
-% \begin{center}\small\MyStretch\leavevmode\vspace{-29ex}\IdxInfo{\ShowIdxPageref*[Hideyo]{Noguchi}\break \ShowIdxPageref*{Miyazaki, Hayao}}\vspace{29ex}
+% \vspace{4ex}
+% \BothInfo{\ShowPattern[Hideyo]{Noguchi}\break \ShowPattern{Miyazaki, Hayao}}
+% {\ShowIdxPageref*[Hideyo]{Noguchi}\break \ShowIdxPageref*{Miyazaki, Hayao}}
+% \vspace{-4ex}
+% \begin{center}\small\medstretch
% \begin{tabular}{rll}\toprule
-% & unchanged & |\RevName|\\\midrule
-% \rowcolor{grey}|\LNoguchi| & \LNoguchi & \RevName\LNoguchi\dag\\
-% \rowcolor{grey}|\LNoguchi[Doctor]| & \LNoguchi[Doctor] & \raise0.5ex\hbox to 5em{\hfil\rule{3em}{0.6pt}} \\
-% \rowcolor{grey}|\LNoguchi[Sensei]| & \raise0.5ex\hbox to 5em{\hfil\rule{3em}{0.6pt}} & \RevName\LNoguchi[Sensei]\dag\\
-% \rowcolor{grey}|\Noguchi| & \Noguchi & \RevName\Noguchi\dag\\
-% \rowcolor{grey}|\SNoguchi| & \SNoguchi & \RevName\SNoguchi\dag\\
-% |\LMiyaz| & \LMiyaz & \RevName\LMiyaz\\
-% |\LMiyaz[Mr.]| & \raise0.5ex\hbox to 5em{\hfil\rule{3em}{0.6pt}} & \RevName\LMiyaz[Mr.]\\
-% |\LMiyaz[Sensei]| & \LMiyaz[Sensei] & \raise0.5ex\hbox to 5em{\hfil\rule{3em}{0.6pt}}\\
-% |\Miyaz| & \Miyaz & \RevName\Miyaz\\
-% |\SMiyaz| & \SMiyaz & \RevName\SMiyaz\\
-% |\ForceFN\SMiyaz| & \ForceFN\SMiyaz & \ForceFN\RevName\SMiyaz\\\bottomrule
-% \end{tabular}\medskip\\
+% & unchanged & |\RevName|\\
+% \rowcolor{nagrey}|\LNoguchi| & \LNoguchi & \RevName\LNoguchi\dag\\
+% \rowcolor{nagrey}|\LNoguchi[Doctor]| & \LNoguchi[Doctor] &
+% \raise0.5ex\hbox to 5em{\hfil\rule{3em}{0.6pt}} \\
+% \rowcolor{nagrey}|\LNoguchi[Sensei]| &
+% \raise0.5ex\hbox to 5em{\hfil\rule{3em}{0.6pt}} &
+% \RevName\LNoguchi[Sensei]\dag\\
+% \rowcolor{nagrey}|\Noguchi| & \Noguchi & \RevName\Noguchi\dag\\
+% \rowcolor{nagrey}|\SNoguchi| & \SNoguchi & \RevName\SNoguchi\dag\\
+% |\LMiyazaki| & \LMiyazaki & \RevName\LMiyazaki\\
+% |\LMiyazaki[Mr.]| & \raise0.5ex\hbox to 5em{\hfil\rule{3em}{0.6pt}} &
+% \RevName\LMiyazaki[Mr.]\\
+% |\LMiyazaki[Sensei]| & \LMiyazaki[Sensei] &
+% \raise0.5ex\hbox to 5em{\hfil\rule{3em}{0.6pt}}\\
+% |\Miyazaki| & \Miyazaki & \RevName\Miyazaki\\
+% |\SMiyazaki| & \SMiyazaki & \RevName\SMiyazaki\\
+% |\ForceFN\SMiyazaki| & \ForceFN\SMiyazaki &
+% \ForceFN\RevName\SMiyazaki\\\bottomrule
+% \end{tabular}
% \end{center}
%
-% 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
+% \begin{SyntaxBox}[Reversing Western Names]
+% \cmd{\RevName}\cmd{\Name}\oarg{FNN}\marg{SNN}\oarg{Alternate}
+% \end{SyntaxBox}
%
-% \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}
-% 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}):
+% As we see from the syntax, one should avoid using \meta{Affix} with such names. For example, |\RevName\LPatton\dag| produces ``\RevName\LPatton\dag''. The name looks wrong unless one uses either \cmd{\RevComma} or \cmd{\DropAffix}.
%
-% \begin{center}\small\MyStretch\AllCapsActive
-% \begin{tabular}{lll}\toprule
-% & |\CapName| only & |\CapName\RevName|\\\midrule
-% \rowcolor{grey}|\LNoguchi| & \CapName\LNoguchi & \RevName\LNoguchi\dag\\
-% |\LMiyaz| & \LMiyaz & \RevName\LMiyaz\\\bottomrule
-% \end{tabular}\AllCapsInactive
-% \end{center}
+% 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}\dag| \ForgetThis\RevName\Name[Frenec]{Molnár}\dag, \RevName\Name[Frenec]{Molnár}\dag.
%
-% 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.
+% \begin{SyntaxBox}[Reversing Eastern Names]
+% \cmd{\RevName}\cmd{\Name}\marg{SNN, Affix}\oarg{Alternate}
+% \end{SyntaxBox}
%
-% \ReturnLink
+% The index entry of this name form looks like \meta{SNN} \meta{FNN} (no comma). This is and remains a non-Western index entry.
%
-% \subsubsection[Particles]{Particles in Names}
+% \begin{InfoBox}[Reversing Ancient Names]
+% The syntax would be the same for reversing Eastern names, but this
+% usually results in producing nonsense names. We do not recommend it.
+% \end{InfoBox}
+%
+% \subsection[Listing by Surname]{Listing Western names by Surname}
+% \label{sec:LastFirst}
+%
+% \DescribeMacro{\ReverseCommaActive}
+% To make lists of ``last comma first'' names, in addition to the \texttt{allrevcomma} option (Section~\ref{sec:PkgOptions}),
+% \DescribeMacro{\ReverseCommaInactive}
+% the macros \cmd{\ReverseCommaActive} and \cmd{\ReverseCommaInactive} function the same way with blocks of text.\DescribeMacro{\RevComma} They both have priority over \cmd{\RevComma}. These all affect only long Western name forms. The first two are broad toggles, while the third is used once per name.\medskip
+%
+% 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.
+%
+% \begin{center}\small\medstretch
+% \begin{tabular}{lll}\toprule
+% \Name*[Oskar]{Hammerstein, II} &
+% \RevComma\Name*[Oskar]{Hammerstein, II} & change\\
+% \LNoguchi & \RevComma\LNoguchi & change\\
+% \rowcolor{nagrey}\LAeth & \RevComma\LAeth & no change\\
+% \rowcolor{nagrey}\Name*{Sun, Yat-sen} &
+% \RevComma\Name*{Sun, Yat-sen} & no change\\\bottomrule
+% \end{tabular}
+% \end{center}^^A
+% \vspace{-12ex}
+% \PatInfo{\ShowPattern[Oskar]{Hammerstein, II}\break
+% \ShowPattern[Hideyo]{Noguchi}\break
+% \ShowPattern{Æthelred,II}\break
+% \ShowPattern{Sun, Yat-sen}}
+% \vspace{12ex}
+%
+% \begin{Quote}{\small\Name[W.H.]{Auden}\break
+% \hbox{}\hfill \textit{Paris Review} interview (1972) p. 206}
+% I don't think the mystical experience can be verbalized. When the ego disappears, so does power over language.
+% \end{Quote}
+%
+% \newpage
+%
+% \subsection{Particles in Names}
% \label{sec:NameParticles}
%
-% Particles in names have specific rules:
+% Particles are small words attached to names, grouped either with forenames or surnames, that refer often to places of origin or noble houses. Some particles have been carried into modern names through various means.
+%
+% \subsubsection{Standard Rules}
+%
+% Modern standards tend to treat particles in the following way:
+%
% \begin{itemize}
-% \item English use of \textit{de}, \textit{de\ la}, \textit{d'}, \textit{von}, \textit{van}, and \textit{ten} often keeps them with the surname with varied capitalization.
-% \item \textit{Le}, \textit{La}, and \textit{L'} always are capitalized unless preceded by \textit{de}.\footnote{According to [\hyperlink{Mulvany}{Mulvany}, 152–82] and the \textit{Chicago Manual of Style}.}
+% \item English use of \textit{de}, \textit{de\ la}, \textit{d'},
+% \textit{von}, \textit{van}, and \textit{ten} often keeps them with the
+% surname with varied capitalization.
+% \item \textit{Le}, \textit{La}, and \textit{L'} always are capitalized
+% unless preceded by \textit{de}.\footnote{According to
+% [\hyperlink{Mulvany}{Mulvany}, 152–82] and the \textit{Chicago Manual
+% of Style}.}
% \item Modern Romance languages keep particles with the surname.
-% \item German and medieval Romance languages put particles with forenames.
+% \item German and medieval Romance languages keep particles with forenames.
+% \item Welsh, Irish, and Scots names often merge particles with surnames:
+% FitzRoy or Fitzroy; O'Leary; McDonald, MacLeish.
% \end{itemize}
-% \newpage
%
-% \leavevmode\SPatInfo{\ShowPattern[Martin]{Van Buren}\break \ShowPattern[Hernando]{de~Soto}\break \ShowPattern[J.W. von]{Goethe}}
-% \vspace{-3ex}
-% \begin{center}\small\MyStretch\leavevmode\vspace{-12ex}\IdxInfo{\ShowIdxPageref*[Martin]{Van Buren}\break \ShowIdxPageref*[Hernando]{de~Soto}\break \ShowIdxPageref*[J.W. von]{Goethe}}\vspace{12ex}
+% \begin{center}\small
+% \vspace{2ex}
+% \BothInfo{\ShowPattern[Martin]{Van Buren}\break
+% \ShowPattern[Hernando]{de~Soto}\break
+% \ShowPattern[J.W. von]{Goethe}}
+% {\ShowIdxPageref*[Martin]{Van Buren}\break
+% \ShowIdxPageref*[Hernando]{de~Soto}\break
+% \ShowIdxPageref*[J.W. von]{Goethe}}
+% \vspace{-2ex}\medstretch
% \begin{tabular}{rll}\toprule
-% \bfseries Macro & \bfseries Body Text & \bfseries Index \\\midrule
-% \rowcolor{grey}\cmd{\ForgetThis}\cmd{\VBuren} & \ForgetThis\VBuren & \ShowIdxPageref*[Martin]{Van Buren}\\
+% \bfseries Macro & \bfseries Body Text & \bfseries Index \\
+% \rowcolor{nagrey}\cmd{\ForgetThis}\cmd{\VBuren} &
+% \ForgetThis\VBuren & \ShowIdxPageref*[Martin]{Van Buren}\\
% \cmd{\VBuren} & \VBuren & \ShowIdxPageref*[Martin]{Van Buren}\\
-% \rowcolor{grey}\cmd{\ForgetThis}\cmd{\Soto} & \ForgetThis\Soto & \ShowIdxPageref*[Hernando]{de~Soto}\\
-% \cmd{\CapThis}\cmd{\Soto} & \CapThis\Soto & \ShowIdxPageref*[Hernando]{de~Soto}\\
-% \rowcolor{grey}\cmd{\ForgetThis}\cmd{\JWG} & \ForgetThis\JWG & \ShowIdxPageref*[J.W. von]{Goethe}\\
+% \rowcolor{nagrey}\cmd{\ForgetThis}\cmd{\Soto} &
+% \ForgetThis\Soto & \ShowIdxPageref*[Hernando]{de~Soto}\\
+% \cmd{\CapThis}\cmd{\Soto} & \CapThis\Soto &
+% \ShowIdxPageref*[Hernando]{de~Soto}\\
+% \rowcolor{nagrey}\cmd{\ForgetThis}\cmd{\JWG} & \ForgetThis\JWG &
+% \ShowIdxPageref*[J.W. von]{Goethe}\\
% \cmd{\JWG} & \JWG & \ShowIdxPageref*[J.W. von]{Goethe}\\\bottomrule
% \end{tabular}
% \end{center}
%
-% We\Info{A few tips} 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}).\medskip
+% \subsubsection{Non-Breaking Spaces}
%
-% \phantomsection
-% \label{page:CapThis}
-% \DescribeMacro{\CapThis}
-% In English and modern Romance languages, e.g., \LSoto\ 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}
+% Despite the macros in Section~\ref{sec:Affix}, names with particles present their own challenges. We 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}). Here the quick interface helps greatly.
%
-% \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
+% \subsubsection{Look-Alike Particles}
%
-% For\Info{Surname variants} another example, we mention poet \Name[e.e.]{cummings}. One can have formatted name caps and inflections. The easiest way to do that is from Section~\ref{sec:GeneralIndex}:
+% There are characters that look similar, but in fact are different. For example, \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}). If one confuses these similar characters, spurious results can occur.
%
-% \vspace{1.5ex}\leavevmode\SPatInfo{\ShowPattern[e.e.]{cummings}\break \ShowPattern[e.e.]{cummings's}}\vspace{-4.5ex}
-% \begin{quote}\small
-% \StartNum
-% \begin{verbatim}
-%\ExcludeName[e.e.]{cummings's}\IndexName[e.e.]{cummings}
-%\SubvertThis\CapThis\Name[e.e.]{cummings's} motif of the
-%goat-footed balloon man has underlying sexual themes that
-%nevertheless have a childish facade''.\end{verbatim}
-%
-%\vspace{1ex}\IdxInfo{\ShowIdxPageref*[e.e.]{cummings}}\vspace{-1ex}\ExcludeName[e.e.]{cummings's}\IndexName[e.e.]{cummings}
-%\SubvertThis\CapThis\Name[e.e.]{cummings's} motif of the
-%goat-footed balloon man has underlying sexual themes that
-%nevertheless have a childish facade''.
-% \end{quote}
+% \subsubsection{Capitalizing Particles}
%
-% 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. See also Section~\ref{sec:VarNames}.
+% \DescribeMacro{\CapThis}
+% In English and modern Romance languages, names like \LSoto\ have their particles in the \meta{SNN} argument: \Soto. When the particle appears at the beginning of a sentence, one must capitalize it, e.g.,: ``\CapThis\Soto\ |\CapThis\Soto\| was a famous Spanish explorer in North America.''
%
-% 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 formats (French, German, etc.) and grammatical inflections.\medskip
+% \begin{itemize}
+% \item With \texttt{latex} and \texttt{pdflatex}, using \cmd{\CapThis}
+% should work with all of the Unicode characters available in the T1
+% encoding. For a broader set of characters, consider using \texttt{xelatex}
+% and \texttt{lualatex}.
+% \item Section~\ref{sec:NonstandardCaps} applies \cmd{\CapThis}
+% to nonstandard names and indexing.
+% \item Sections~\ref{sec:AltFormat} and~\ref{sec:Unicode} explain
+% potential problems of \cmd{\CapThis}. That is a trade-off
+% for using a natural language approach.
+% \item \cmd{\CapName} overrides the \meta{SNN} created by \cmd{\CapThis}.
+% It is unlikely that the two would be used in the same context.
+% \end{itemize}
%
% \DescribeMacro{\AccentCapThis}
-% If one uses this package on a system that does not support 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}.
+% Before \textsf{nameauth} used automatic Unicode detection, \cmd{\AccentCapThis} placed before \cmd{\CapThis} handled Unicode characters. It remains for backward compatibility. Otherwise it is seldom used
%
-% \ReturnLink
-% \vfill
+% \subsection{Medieval Names}
+% \label{sec:NameMedieval}
%
-% \begin{verse}
-% ``Rose is a rose is a rose is a rose''\\\hfill---\Name[Gertrude]{Stein}, ``Sacred Emily'' in \textit{Geography and Plays}
-% \end{verse}
-% \newpage
-%
-% \subsubsection[Medieval/Ancient]{Medieval, Ancient, and Roman Names}
-% \label{sec:NameAncient}
-% \medskip
+% Medieval names present some interesting difficulties, often based on the expected standards of the context in which they are used. Some publications use them like Western names while others do not. In the following preamble snippet we have:\footnote{Regarding the margin note that shows name control sequences, with \texttt{pdflatex} and \texttt{latex}, in \texttt{\ShowPattern{Thomas, à~Kempis}} the glyphs \texttt{Ãă} correspond to \cmd{\IeC\{}\texttt{\textbackslash\textquotesingle a\}}.}
%
-% \begin{center}\bfseries Medieval Names\end{center}
-% Medieval names present some interesting difficulties, often based on the expected standards of the context in which they are used. Some publications use them like Western names while others do not. In the following preamble snippet we have:
-%
-% \vspace{1.5ex}\leavevmode\SPatInfo{\ShowPattern{Thomas, à~Kempis}\hfill \textrm{(1--4, 7)}\break \ShowPattern{Thomas,\`a~Kempis}\hfill \textrm{(5--6)}\break \ShowPattern[Thomas]{à~Kempis}\hfill \textrm{(8--10)}}\vspace{-4.5ex}
% \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}
+% \begin{Verbatim}
+% \PretagName{Thomas, à~Kempis}{Thomas Akempis} % medieval
+% \PretagName[Thomas]{à~Kempis}{Akempis, Thomas} % Western
+%
+% % We do not index an alternate medieval form
+% \ExcludeName{Thomas, \`a~Kempis}
+%
+% % If we did use the alternate form, we would sort it as
+% \PretagName{Thomas, \`a~Kempis}{Thomas Akempis}
+%
+% \begin{nameauth}
+% \< KempMed & & Thomas, à~Kempis & > % medieval
+% \< KempW & Thomas & à~Kempis & > % Western
+% \end{nameauth}
+%
+% % Create xref before using the Western name.
% \IndexRef[Thomas]{à~Kempis}{Thomas à~Kempis}
+% \end{Verbatim}
% \ExcludeName{Thomas,\`a~Kempis}
-% \end{quote}\vspace{-9ex}\IdxInfo{\ShowIdxPageref*{Thomas, à~Kempis}\hfill (1--4, 7)\break \ShowIdxPageref*{Thomas,\`a~Kempis}\hfill (5--6)\break \ShowIdxPageref*[Thomas]{à~Kempis}\hfill (8--10)}\vspace{8ex}
+% \IndexRef[Thomas]{à~Kempis}{Thomas à~Kempis}
+% \end{quote}
%
+% \begin{itemize}
+% \item Medieval form: \cmd{\KempMed}
+% \BothInfo{\ShowPattern{Thomas, à~Kempis}\hfill \textrm{(1--4, 7)}\break
+% \ShowPattern{Thomas,\`a~Kempis}\hfill \textrm{(5--6)}\break
+% \ShowPattern[Thomas]{à~Kempis}\hfill \textrm{(8--10)}}
+% {\ShowIdxPageref*{Thomas, à~Kempis}\hfill (1--4, 7)\break
+% \ShowIdxPageref*{Thomas,\`a~Kempis}\hfill (5--6)\break
+% \ShowIdxPageref*[Thomas]{à~Kempis}\hfill (8--10)}
% \begin{enumerate}
-% \item \KempMed\Version{3.1} is indexed as ``\ShowIdxPageref*{Thomas, à~Kempis}''.
-% \item Later uses display \KempMed\ because ``\ForceFN\SKempMed'' |\ForceFN\SKempMed| is a place name, not a surname. It is Latin for \textit{von Kempen}.
-% \item \CapThis\ForceFN\SKempMed\ |\CapThis\ForceFN\SKempMed| starts a sentence.
-% \item We use \cmd{\PretagName} (Section~\ref{sec:IndexSort}) to sort the name.
-% \item \Name{Thomas,\`a~Kempis} |\Name{Thomas,\`a~Kempis}| is a different name. As above, we would sort this name with \cmd{\PretagName}.
-% \item We used \cmd{\ExcludeName} (Section~\ref{sec:GeneralIndex}) before using the alternate name to keep it out of the index.
-% \item We index the canonical form here with \JustIndex\KempMed|\JustIndex\KempMed|.
-% \item \KempW\ |\KempW| is a Western form with the index entry: ``\ShowIdxPageref*[Thomas]{à~Kempis}''.
-% \item \CapThis\KempW\ appears via |\CapThis\KempW|.
-% \item We created a cross-reference from the Western form to the medieval form, before we used the Western form, thus preventing any spurious page entries (Section~\ref{sec:GeneralIndex}). We index with the medieval form (7).
+% \item In the text, we see \KempMed\ and \KempMed. The added name
+% ``\ForceFN\SKempMed'' |\ForceFN\SKempMed| is a place name, not a
+% surname. It is Latin for \textit{von Kempen}.
+% \item \KempMed\ is indexed as ``\ShowIdxPageref*{Thomas, à~Kempis}''.
+% \item \CapThis\ForceFN\SKempMed\ |\CapThis\ForceFN\SKempMed|
+% can start a sentence.
+% \item We use \cmd{\PretagName} (Section~\ref{sec:IndexSort}) to sort the
+% name under \texttt{Thomas}, followed by \texttt{Akempis}, not
+% \texttt{A kempis} (cf. 10 below).
+% \end{enumerate}
+% \item Alternate medieval form: |\Name{Thomas,\`a~Kempis}|
+% \begin{enumerate}\addtocounter{enumi}{4}
+% \item \Name{Thomas,\`a~Kempis} is a different name.
+% \item We used \cmd{\ExcludeName} (Section~\ref{sec:IdxFine})
+% before using the alternate form to keep it from generating an extra
+% index entry.
+% \item We index the canonical form here with
+% \JustIndex\KempMed|\JustIndex\KempMed|.
% \end{enumerate}
%
-% Spaces count\Warn{} when sorting index entries (Section~\ref{sec:IndexSort}). Sorting the cross-reference with |\PretagName[Thomas]{à~Kempis}{a Kempis, Thomas}|, would put it before \texttt{aardvark}. |\PretagName[Thomas]{à~Kempis}{Akempis, Thomas}| sorts the cross-reference between \texttt{ajar} and \texttt{alkaline}.
-% \vfil
-%
-% \begin{tcolorbox}[colback=white,colframe=nared]
-% From this point forward, we shall change what we show in the margin.
-% We shall show full name patterns that reflect naming systems,
-% index sorting tags, index entry tags, cross-references,
-% and name info (Section~\ref{sec:NamePatterns}).\\[2ex]
-% No longer shall we show index entries in the margins because they
-% shall become too complex for such display to work well.
-% \end{tcolorbox}
% \newpage
+%
+% \item Western form: \cmd{\KempW}
+% \begin{enumerate}\addtocounter{enumi}{7}
+% \item \KempW\ is a Western name form with the index entry:
+% ``\ShowIdxPageref*[Thomas]{à~Kempis}''.
+% \item \CapThis\KempW\ appears via |\CapThis\KempW|.
+% \item We first created a cross-reference from the Western form to the
+% medieval form to prevent spurious page entries
+% (Section~\ref{sec:IndexRef}).
+% \item[] We index the canonical form again:
+% \JustIndex\KempMed|\JustIndex\KempMed|.
+% \item[\dbend] \cmd{\PretagName[Thomas]\{à~Kempis\}\{a Kempis, Thomas\}}
+% puts \KempMed\ before \texttt{aardvark} in the index. We remove the extra
+% spaces to get the proper sorting between \texttt{ajar} and
+% \texttt{alkaline}:
+% |\PretagName[Thomas]{à~Kempis}{Akempis, Thomas}|
+% \end{enumerate}
+% \end{itemize}
+% \negmedskip
%
-% \begin{center}\bfseries Ancient Names\end{center}
-% \phantomsection
-% \label{page:Sobriquets}
-% \begingroup%^^A Local format hook redefinition
-% \renewcommand*\NamesFormat{}^^A
-% \renewcommand*\MainNameHook{}^^A
-% Ancient contexts may or may not bind particles or other name elements to surnames. One must handle these cases not only in the text, but also in the index. In the rest of this section the examples do not use the formatting conventions of this manual and present themselves as if they were in an ordinary \LaTeX\ document.
+% \ReturnLink
%
-% \begin{itemize}
-% \item For name entries in the index, we can use \cmd{\PretagName} and \cmd{\TagName} to ensure that any ``long form'' information is displayed without using macros in the name arguments. See Sections~\ref{sec:IndexSort}, \ref{sec:IndexTag}.
-% \item In the text, we can use the \meta{Alternate} argument or the name information database (Section~\ref{sec:TextTags}) to add ``long form'' information as needed. Beyond that, we would have to use macros in the name arguments.
-% \end{itemize}
-%
-% First we explore the easiest way to handle royal or ancient variants with extra ``long form'' information using the \meta{Alternate} argument. We use macros introduced in Sections~\ref{sec:IndexSort} and~\ref{sec:IndexTag}.\footnote{Copies of examples in this section are in \texttt{examples.tex}, located with this manual.}
+% \addtocontents{toc}{\protect\goodbreak}
+% \section{Debugging}
+% \label{sec:Debugging}
%
-% \NameAddInfo{Demetrius, I}{ Soter}
-% \vspace{1.5ex}\leavevmode\PatInfo{\ShowPattern{Demetrius, I}!PRE\break \ShowPattern{Demetrius, I}!TAG\break \ShowPattern{Demetrius, I}!MN}\vspace{-4.5ex}
-% \begin{quote}\small
-% \StartNum
-% \begin{verbatim}
-%\PretagName{Demetrius, I}{Demetrius 1}
-%\TagName{Demetrius, I}{ Soter, king}
-%\begin{nameauth}
-% \< Dem & & Demetrius, I & >
-%\end{nameauth}\end{verbatim}
-% \smallskip
-%
-% \MyStretch
-% \begin{tabular}{ll}\toprule
-% \cmd{\Dem[I Soter]} & \Dem[I Soter]\\
-% \rowcolor{grey}^^A
-% \cmd{\LDem} & \LDem\\
-% \cmd{\Dem} & \Dem\\\bottomrule
-% \end{tabular}\smallskip
+% As we move forward in this manual, many concepts will mesh together in complex ways. Indexing is the first topic to do that. Name patterns govern those interactions, and debugging macros illustrate what is going on. First, we explain what the debugging macros are trying to communicate. Next, we describe the macros.
%
-% \IndexActual{@}^^A
-% \TagName{Demetrius, I}{ Soter, king}^^A
-% Index (normal \LaTeX\ document): \texttt{\ShowIdxPageref{Demetrius, I}}^^A
-% \TagName{Demetrius, I}{ Soter, king\string|hyperpage}^^A
+% Previously, we have seen simple name patterns displayed in the margin, which look like the examples shown below:
+%
+% \begin{quote}\small\ttfamily
+% \begin{tabular}{@{\qquad}l}
+% \ShowPattern[George]{Washington}\\
+% \ShowPattern{Miyazaki, Hayao}
+% \end{tabular}
% \end{quote}
-%
-% \makeatletter\renewcommand*\NamesFormat[1]{^^A
-% \begingroup^^A
-% \protected@edef\temp{\endgroup{#1^^A
-% \noexpand\NameQueryInfo[\unexpanded\expandafter{\the\@nameauth@toksa}]
-% {\unexpanded\expandafter{\the\@nameauth@toksb}}
-% [\unexpanded\expandafter{\the\@nameauth@toksc}]}}\temp}\makeatother
-% Using the name information database (``text tags'') with the formatting macros (Sections~\ref{sec:TextTags}, \ref{sec:Hooksii}), we can provide a more automatic approach:
-%
-% \vspace{1.5ex}\leavevmode\PatInfo{\ShowPattern{Demetrius, I}!DB\break \ShowPattern{Demetrius, I}!MN}\vspace{-4.5ex}
+%
+% Now we switch to full name patterns, which indicate the ``system'' or data set to which a control sequence representing a name belongs. Name patterns usually expand to empty, except for exclusions.\footnote{To fit the information in the margin, we display them by taking the output of \cmd{\ShowPattern} and manually adding the system to correspond to the package internals.}
+% The patterns look like this:
+%
% \begin{quote}\small
-% \ContinueNum
-% \begin{verbatim}
-%\NameAddInfo{Demetrius, I}{ Soter}
-%\makeatletter
-%\renewcommand*\NamesFormat[1]{%
-% \begingroup%
-% \protected@edef\temp{\endgroup%
-% {#1\noexpand\NameQueryInfo
-% [\unexpanded\expandafter{\the\@nameauth@toksa}]
-% {\unexpanded\expandafter{\the\@nameauth@toksb}}
-% [\unexpanded\expandafter{\the\@nameauth@toksc}]%
-% }%
-% }%
-% \temp%
-%}
-%\makeatother\end{verbatim}
-%
-% \smallskip\MyStretch
-% \begin{tabular}{ll}\toprule
-% \cmd{\ForgetThis}\cmd{\Dem} & \ForgetThis\Dem\\
-% \rowcolor{grey}^^A
-% \cmd{\LDem} & \LDem\\
-% \cmd{\Dem} & \Dem\\\bottomrule
-% \end{tabular}\smallskip
-%
-% The index entry is the same as above.
+% \ttfamily\begin{tabular}{@{\qquad}l@{\quad \% }l}
+% \ShowPattern[George]{Washington}!MN & name, main matter\\
+% \ShowPattern{Miyazaki, Hayao}!NF & name, front matter\\
+% \ShowPattern[Jay]{Rockefeller}!PN & index cross-reference\\
+% \ShowPattern[W.E.B.]{Du~Bois}!PRE & index sort tag\\
+% \ShowPattern{Gregory, I}!TAG & index data tag\\
+% \ShowPattern[Schuyler]{Colfax}!DB & name data tag\\
+% \end{tabular}
% \end{quote}
-% \endgroup^^A Local format hook redefinition
%
-% \newpage
+% No longer will we show index entries in the margin because they shall become too large and complex to fit there. We will show index entries in the body text.
%
-% \leavevmode\begin{center}\bfseries Roman Names\end{center}
-% \phantomsection
-% \label{page:Romani}
-% Earlier we treated \Name*[M.T.]{Cicero}[Marcus Tullius] as a Western name. Now we handle Roman names properly. The examples below do not use this manual's standard formatting.
-% Roman names have the following format:
-% \begin{itemize}
-% \item A personal name: \textit{praenomen}
-% \item A clan name: \textit{nomen}
-% \item A nickname, often hereditary to denote clan branches: \textit{cognomen}
-% \item Affixed names: \textit{agnomina}
+% \subsection[Name Patterns]{Name Pattern Overview}
+% \label{sec:NamePatterns}
+%
+% The next table shows how macro arguments generate name patterns. The \meta{Alternate} argument only affects patterns when using the obsolete syntax (Section~\ref{sec:Obsolete}). The patterns govern names in both the text and the index. The colon at the beginning of each pattern was added to prevent any collisions with extant macros:
+%
+% \begin{center}\small\medstretch
+% \begin{tabular}{lll}\toprule
+% Macro Arguments & Patterns & Name Type\\
+% \rowcolor{nagrey}\oarg{FNN}\marg{SNN} &
+% :\meta{FNN}!\meta{SNN} & Western\\
+% \oarg{FNN}\marg{SNN}\oarg{Alt} &
+% :\meta{FNN}!\meta{SNN} & Western\\
+% \rowcolor{nagrey}\oarg{FNN}\marg{SNN, Affix} &
+% :\meta{FNN}!\meta{SNN},\meta{Affix} & Western\\
+% \oarg{FNN}\marg{SNN, Affix}\oarg{Alt} &
+% :\meta{FNN}!\meta{SNN},\meta{Affix} & Western\\
+% \rowcolor{nagrey}\hphantom{\oarg{FNN}}\marg{SNN, Affix} &
+% :\meta{SNN},\meta{Affix} & non-Western\\
+% \hphantom{\oarg{FNN}}\marg{SNN, Affix}\oarg{Alt} &
+% :\meta{SNN},\meta{Affix} & non-Western\\
+% \rowcolor{nagrey}\hphantom{\oarg{FNN}}\marg{SNN}\oarg{Alt} &
+% :\meta{SNN},\meta{Alt} & old syntax\\
+% \hphantom{\oarg{FNN}}\marg{SNN} &
+% :\meta{SNN} & non-Western\\\bottomrule
+% \end{tabular}
+% \end{center}\medskip
+%
+% \DescribeMacro{\NameauthPattern}
+% Every time a macro that takes name arguments is called (Section~\ref{sec:NameArgMacros}), the internal name category logic will \cmd{\let} the current name pattern to \cmd{\NameauthPattern}, making it available to formatting hooks (cf. Section~\ref{sec:DataTagHooks}).
+%
+% The name category logic is provided by \cmd{\@nameauth@Choice}, which determines the type of name (Western or non-Western) by its arguments. Various \textsf{nameauth} macros append the appropriate ``system'' or name data set indicator to the pattern. We use this concept starting here, but mostly in Section~\ref{sec:AdvancedFormat}.
+%
+% First we show name patterns generated from name elements and the type of name. Reversed Western names are marked by a dagger (\dag); names that use the obsolete syntax are marked by a double dagger (\ddag). We use two versions of each name, plus variations in formatting, to show that the patterns depend on the arguments, not the appearance of the name. Note also that the obsolete non-Western syntax and the current one still share the same patterns.
+%
+% \begin{center}\small\medstretch
+% \begin{tabular}{rll}\toprule
+% Macro & Body Text & \cmd{\ShowPattern}\\
+% \rowcolor{nagrey}\cmd{\Harnack[Adolf von]} & \Harnack[Adolf von] &
+% \texttt{\ShowPattern[Adolf]{Harnack}}\\
+% \rowcolor{nagrey}\cmd{\LHarnack} & \LHarnack &
+% \texttt{\ShowPattern[Adolf]{Harnack}}\\
+% \cmd{\ForgetThis}\cmd{\Patton} & \ForgetThis\Patton &
+% \texttt{\ShowPattern[George S.]{Patton, Jr.}}\\
+% \cmd{\DropAffix}\cmd{\LPatton} & \DropAffix\LPatton &
+% \texttt{\ShowPattern[George S.]{Patton, Jr.}}\\
+% \rowcolor{nagrey}\cmd{\ForgetThis}\cmd{\Noguchi} & \ForgetThis\Noguchi &
+% \texttt{\ShowPattern[Hideyo]{Noguchi}}\\
+% \rowcolor{nagrey}\cmd{\RevName}\cmd{\LNoguchi}\cmd{\dag} &
+% \RevName\LNoguchi\dag & \texttt{\ShowPattern[Hideyo]{Noguchi}}\\
+% \cmd{\ForgetThis}\cmd{\Yamt} & \ForgetThis\Yamt &
+% \texttt{\ShowPattern{Yamamoto,Isoroku}}\\
+% \cmd{\RevName}\cmd{\LYamt} & \RevName\LYamt &
+% \texttt{\ShowPattern{Yamamoto,Isoroku}}\\
+% \rowcolor{nagrey}\cmd{\Name\{Henry,VIII\}} & \Name{Henry,VIII} &
+% \texttt{\ShowPattern{Henry,VIII}}\\
+% \rowcolor{nagrey}\cmd{\Name*\{Henry\}[VIII]}\cmd{\ddag} &
+% \Name*{Henry}[VIII]\ddag & \texttt{\ShowPattern{Henry,VIII}}\\
+% \cmd{\Dem[I Soter]} & \Dem[I Soter] & \texttt{\ShowPattern{Demetrius,I}}\\
+% \cmd{\LDem} & \LDem & \texttt{\ShowPattern{Demetrius,I}}\\
+% \rowcolor{nagrey}\cmd{\ForgetThis}\cmd{\Aris} & \ForgetThis\Aris &
+% \texttt{\ShowPattern{Aristotle}}\\
+% \rowcolor{nagrey}\cmd{\Aris} & \Aris &
+% \texttt{\ShowPattern{Aristotle}}\\\bottomrule
+% \end{tabular}
+% \end{center}\medskip
+%
+% Six suffixes are appended to these patterns to create six ``systems'' or data sets. The \meta{pattern} element in the next table is the output of \cmd{\ShowPattern}. Within that \meta{pattern} is a leading colon, name elements with spaces removed, and delimiters that separate those elements. Western names use an exclamation point and a comma. Non-Western names only use a comma. For the use of ID, see \cmd{\ShowNameState} on page~\pageref{page:NameState}. For the way that exclusions use the cross-reference system as a special case for preventing index interaction, see Section~\ref{sec:IdxFine}.
+%
+% \begin{center}\small\medstretch
+% \begin{tabular}{llll}\toprule
+% Description & Pattern & ID & Example\\
+% \rowcolor{nagrey}Front-matter names & \meta{pattern}\texttt{!NF} &
+% front & \texttt{\ShowPattern[Adolf]{Harnack}{!NF}}\\
+% Main-matter names & \meta{pattern}\texttt{!MN} & main &
+% \texttt{\ShowPattern[Hideyo]{Noguchi}{!MN}}\\
+% \rowcolor{nagrey}Index cross-refs & \meta{pattern}\texttt{!PN} &
+% xref & \texttt{\ShowPattern{Yamamoto, Isoroku}{!PN}}\\
+% Exclusions & \meta{pattern}\texttt{!PN} &
+% excl & (like xref, special value)\\
+% \rowcolor{nagrey}Index sort tags & \meta{pattern}\texttt{!PRE} & pretag &
+% \texttt{\ShowPattern{Henry, VIII}{!PRE}}\\
+% Index data tags & \meta{pattern}\texttt{!TAG} &
+% idxtag & \texttt{\ShowPattern{Demetrius, I}{!TAG}}\\
+% \rowcolor{nagrey}Name data tags & \meta{pattern}\texttt{!DB} & namedb &
+% \texttt{\ShowPattern{Aristotle}{!DB}}\\\bottomrule
+% \end{tabular}
+% \end{center}
+%
+% The following macros write the patterns that they generate to certain systems or data sets. \cmd{\IndexName} does not generate a name pattern, even though it writes index entries. This lets the index control logic be keyed to cross-references.
+%
+% \begin{center}\small\medstretch
+% \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} \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}
+%
+% \subsection{Indexing: States}
+% \label{sec:RuleStates}
+%
+% Six distinct ``states'' describe any name pattern with respect to the index. They are derived using \cmd{\ShowNameState}. Below we show these states and what they mean.
+%
+% \begin{tcolorbox}
+% [colback=white,colframe=darkgray,
+% adjusted title={\bfseries\hfil State 1: No Name Information Present}]
+% \footnotesize
+% \begin{itemize}[leftmargin=1em,rightmargin=1em]
+% \item \Stay{\cmd{\IndexName} makes index page entry,
+% creates no name pattern control sequence}{1}
+% \item \Stay{\cmd{\TagName} makes index tag, creates a pattern
+% ending in \texttt{!TAG}; \cmd{\UntagName} destroys it}{1}
+% \item \Stay{\cmd{\PretagName} makes index sort tag, creates a
+% pattern ending in \texttt{!PRE} (do only once)}{1}
+% \item \Stay{\cmd{\ForgetName} is redundant; it cannot destroy
+% a control sequence that does not exist.}{1}
+% \item \Go{Naming macro makes name pattern (\texttt{!MN} or
+% \texttt{!NF}), prints name, makes two index page entries}{2}
+% \item \Go{\cmd{\SubvertName} makes a name pattern ending
+% either in \texttt{!MN} or in \texttt{!NF}, or both at once}{2}
+% \item \Go{\cmd{\IndexRef} makes an xref pattern ending with
+% \texttt{!PN}; that pattern expands to empty}{3}
+% \item \Go{\cmd{\SeeAlso}\cmd{\IndexRef} makes an xref pattern
+% ending with \texttt{!PN}; that pattern expands to empty}{3}
+% \item \Go{\cmd{\ExcludeName} makes an xref pattern ending with
+% \texttt{!PN}; that pattern expands to \texttt{!x!}}{5}
% \end{itemize}
+% \end{tcolorbox}
%
-% Popular\Info{Popular works} sources tend to treat the \textit{cognomen} as if it were a Western surname.\footnote{See Geiss, \textit{Geschichte Griffbereit}; Kinder and Hilgemann, \textit{dtv-Atlas zur Weltgeschichte}, 2 vols., 29th printing (1964; Munich: Deutscher Taschenbuch Verlag, 1993). See also \href{http://books.infotoday.com/books/Indexing-names.shtml}{this page} on indexing and \href{https://en.wikipedia.org/wiki/Roman_naming_conventions}{Wikipedia} on Roman names.}
-% Using this approach, Roman names have the indexed form:
-% \begin{quote}
-% \ShowIdxPageref*[\meta{praenomen} \meta{nomen}]{\meta{cognomen} \meta{agnomen}}
-% \end{quote}
+% \begin{tcolorbox}
+% [colback=white,colframe=darkgray,
+% adjusted title={\bfseries\hfil State 2: Only a Name Pattern Exists}]
+% \footnotesize
+% \begin{itemize}[leftmargin=1em,rightmargin=1em]
+% \item \Stay{\cmd{\IndexName} makes index page entry, creates
+% no name pattern control sequence}{2}
+% \item \Stay{\cmd{\TagName} makes index tag, creates a pattern
+% ending in \texttt{!TAG}; \cmd{\UntagName} destroys it}{2}
+% \item \Stay{\cmd{\PretagName} is doable, but not recommended
+% (that will create spurious entries)}{2}
+% \item \Stay{Naming macro makes name pattern (\texttt{!MN} or
+% \texttt{!NF}), prints name, makes two index page entries}{2}
+% \item \Stay{\cmd{\SubvertName} is redundant; it cannot create
+% a control sequence that already exists.}{2}
+% \item \Stay{\cmd{\IndexRef} by itself does nothing because a
+% name pattern already exists}{2}
+% \item \Go{\cmd{\ForgetName} destroys a name pattern ending in
+% \texttt{!MN}, \texttt{!NF}, or both at once}{1}
+% \item \Go{\cmd{\SeeAlso}\cmd{\IndexRef} makes an xref pattern
+% ending with \texttt{!PN}; that pattern expands to empty}{4}
+% \item \Go{\cmd{\ExcludeName} makes an xref pattern ending with
+% \texttt{!PN}, that pattern expands to \texttt{!x!}}{6}
+% \end{itemize}
+% \end{tcolorbox}
%
-% Using \textsf{nameauth}, one can drop both \textit{praenomen} and \textit{nomen} automatically in subsequent uses in the text. We accomplish this by designing names using macros in their arguments. When doing so, here are a few tips:
+% \begin{tcolorbox}
+% [colback=white,colframe=darkgray,
+% adjusted title={\bfseries\hfil State 3: Only an Xref Pattern Exists}]
+% \footnotesize
+% \begin{itemize}[leftmargin=1em,rightmargin=1em]
+% \item \Stay{\cmd{\PretagName} is doable, but not recommended
+% (that will create spurious entries)}{3}
+% \item \Stay{\cmd{\TagName}, \cmd{\UntagName}, \cmd{\IndexName},
+% \cmd{\IndexRef} (also with \cmd{\SeeAlso}), \cmd{\ExcludeName},
+% and \cmd{\IncludeName} do nothing}{3}
+% \item \Stay{\cmd{\ForgetName} is redundant; it cannot destroy
+% a control sequence that does not exist.}{3}
+% \item \Go{\cmd{\Includename*} destroys an extant xref pattern
+% (\texttt{!PN})}{1}
+% \item \Go{Naming macro makes name pattern (\texttt{!MN} or
+% \texttt{!NF}), prints name, makes no index entries}{4}
+% \item \Go{\cmd{\SubvertName} creates a name pattern ending
+% either in \texttt{!MN} or in \texttt{!NF}, or both at once}{4}
+% \end{itemize}
+% \end{tcolorbox}
%
-% \begin{itemize}
-% \item Use alternate formatting (Sections~\ref{sec:AltFormat}) if the macros in the name arguments will be ``segmented'' in some way, as \cmd{\CapThis} does by separating the first letter from the rest.
-% \item Use \cmd{\noexpand} before the macros in the name arguments if they contain conditional statements. Otherwise one will get spurious index entries.
-% \item Ensure that the default state of any Boolean flags (\texttt{\textbackslash if}\meta{flag}) trigger expansion so that all the desired names appear in the index entry.
+% \begin{tcolorbox}
+% [colback=white,colframe=darkgray,
+% adjusted title={\bfseries\hfil State 4: Both Name and
+% Xref Patterns Exist}]
+% \footnotesize
+% \begin{itemize}[leftmargin=1em,rightmargin=1em]
+% \item \Stay{\cmd{\PretagName} is doable, but not recommended
+% (that will create spurious entries)}{4}
+% \item \Stay{\cmd{\TagName}, \cmd{\UntagName}, \cmd{\IndexName},
+% \cmd{\IndexRef} (also with \cmd{\SeeAlso}), \cmd{\ExcludeName},
+% and \cmd{\IncludeName} do nothing}{4}
+% \item \Stay{Naming macro makes name pattern (\texttt{!MN} or
+% \texttt{!NF}), prints name, makes no index entries}{4}
+% \item \Stay{\cmd{\SubvertName} is redundant; it cannot create
+% a control sequence that already exists.}{4}
+% \item \Go{\cmd{\Includename*} destroys an extant xref pattern
+% (\texttt{!PN})}{2}
+% \item \Go{\cmd{\ForgetName} destroys a name pattern ending in
+% \texttt{!MN}, \texttt{!NF}, or both at once}{3}
+% \end{itemize}
+% \end{tcolorbox}
+%
+% \begin{tcolorbox}
+% [colback=white,colframe=darkgray,
+% adjusted title={\bfseries\hfil State 5: Only an Exclusion Exists}]
+% \footnotesize
+% \begin{itemize}[leftmargin=1em,rightmargin=1em]
+% \item \Stay{\cmd{\PretagName} is doable, but not recommended
+% (that will create spurious entries)}{5}
+% \item \Stay{\cmd{\TagName}, \cmd{\UntagName}, \cmd{\IndexName},
+% \cmd{\IndexRef} (also with \cmd{\SeeAlso}), and
+% \cmd{\ExcludeName} do nothing}{5}
+% \item \Stay{\cmd{\ForgetName} is redundant; it cannot destroy
+% a control sequence that does not exist.}{5}
+% \item \Go{\cmd{\Includename}, \cmd{\Includename*} destroy xref
+% pattern ending with \texttt{!PN}, expanding to \texttt{!x!}}{1}
+% \item \Go{Naming macro makes name pattern (\texttt{!MN} or
+% \texttt{!NF}), prints name, makes no index entries}{6}
+% \item \Go{\cmd{\SubvertName} creates a name pattern ending either
+% in \texttt{!MN} or in \texttt{!NF}, or both at once}{6}
+% \end{itemize}
+% \end{tcolorbox}
+%
+% \begin{tcolorbox}
+% [colback=white,colframe=darkgray,
+% adjusted title={\bfseries\hfil State 6: Both Name Pattern and
+% Exclusion Exist}]
+% \footnotesize
+% \begin{itemize}[leftmargin=1em,rightmargin=1em]
+% \item \Stay{\cmd{\PretagName} is doable, but not recommended
+% (that will create spurious entries)}{6}
+% \item \Stay{\cmd{\TagName}, \cmd{\UntagName}, \cmd{\IndexName},
+% \cmd{\IndexRef} (also with \cmd{\SeeAlso}), and
+% \cmd{\ExcludeName} do nothing}{6}
+% \item \Stay{Naming macro makes name pattern (\texttt{!MN} or
+% \texttt{!NF}), prints name, makes no index entries}{6}
+% \item \Go{\cmd{\Includename}, \cmd{\Includename*} destroy xref
+% pattern ending with \texttt{!PN}, expanding to \texttt{!x!}}{2}
+% \item \Go{\cmd{\ForgetName} destroys a name pattern ending in
+% \texttt{!MN}, \texttt{!NF}, or both at once}{5}
% \end{itemize}
-% We define all macros and conditionals used in naming macro arguments in the preamble. We use \cmd{\noexpand} in the naming macro arguments to prevent error. Since we do not use \cmd{\CapThis} in the examples below, we skip alternate formatting for simplicity, yet we still recommend it.
+% \end{tcolorbox}
+%
+% \subsection{Debugging Macros}
+% \label{sec:DebuggingMacros}
+%
+% \DescribeMacro{\ShowPattern}
+% We use \cmd{\ShowPattern} in Section~\ref{sec:NamePatterns} to illustrate name control patterns. It displays how the name arguments create name patterns that form name control sequences. One can debug pattern collisions and other issues with this macro:
+%
+% \begin{SyntaxBox}
+% \cmd{\ShowPattern}\oarg{FNN}\marg{SNN|,| Affix}\oarg{Alternate}
+% \end{SyntaxBox}
+%
+% Thus, |\texttt{\ShowPattern[Hernando]{de~Soto}}| will produce the output \JustIndex\Soto\texttt{\ShowPattern[Hernando]{de~Soto}}. As we have seen before, using \textsf{inputenc}/\textsf{fontenc} will cause names like |\texttt{\ShowPattern{Boëthius}}| to produce \texttt{\ShowPattern{Boëthius}}\JustIndex\Name{Bo\"ethius}.\medskip
+%
+% \DescribeMacro{\ShowIdxPageref}
+% \cmd{\ShowIdxPageref} displays a full index entry in the text as if it were only a page reference, not a cross-reference.
+%
+% \begin{SyntaxBox}
+% \cmd{\ShowIdxPageref\ }\oarg{FNN}\marg{SNN|,| Affix}\oarg{Alternate}
+% \end{SyntaxBox}
%
-%Since we have four name components, we need two Boolean flags to reflect local changes and two global flags to trigger the local changes without affecting the index. 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}.
+% Index styles, \cmd{\PretagName}, and \cmd{\TagName} affect the output of \cmd{\ShowIdxPageref}. Active characters and macros appear as printed, not as in \texttt{idx} files. In a normal \LaTeX\ document, for example, if we mention \LSoto\ after setting up the following sort tag (Section~\ref{sec:IndexSort}), we get:
%
% \begin{quote}\small
-% \StartNum
-% \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}
-%\begin{nameauth}
-% \< Scipio & \noexpand\SCIPi & \noexpand\SCIPii & >
-%\end{nameauth}
-%\PretagName[\noexpand\SCIPi]{\noexpand\SCIPii}{Scipio Africanus}\end{verbatim}
+% |\PretagName[Hernando]{de~Soto}{Desoto, Hernando}|
+%
+% \IndexActual{@}\UntagName[Hernando]{de~Soto}
+% |\ShowIdxPageref[Hernando]{de~Soto}|\\
+% \ShowIdxPageref[Hernando]{de~Soto}\footnote{We cannot generate any index
+% entries in this quote because we changed \cmd{\IndexActual}.}
% \end{quote}
%
-% We begin a new scope below, redefining the formatting hooks (Section~\ref{sec:Formatting}), which affect only names printed in the text. If the local Boolean flags are false, one gets longer name forms. If the flags are true, one gets shorter forms. This approach allows the global state of the flags to be false by default, meaning that one need not remember to set any of them true in the preamble. That results in one less thing to remember, and one less problem to fix.
-%\begingroup^^A Local format hook redefinition
-%\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}
+% In this \texttt{dtx} file, however, due to extra setup needed in the
+% ``commented'' part of the file (Section~\ref{sec:IndexTag}), we get:
+%
% \begin{quote}\small
-% \ContinueNum
-% \begin{verbatim}
-%\renewcommand*\NamesFormat[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}\end{verbatim}
+% |\PretagName[Hernando]{de~Soto}{Desoto, Hernando}|\\
+% \verb+\TagName[Hernando]{de~Soto}{\string|hyperpage}+
+%
+% \TagName[Hernando]{de~Soto}{\string|hyperpage}
+% \IndexActual{=}
+% |\ShowIdxPageref[Hernando]{de~Soto}|\\
+% \ShowIdxPageref[Hernando]{de~Soto}
% \end{quote}
%
-% The index always shows the name determined by the global state of \cmd{\NoGens} and \cmd{\NoAgnomen}, which we set up as false, meaning a maximally long name form. In the body text we have:
+% \DescribeMacro{\ShowIdxPageref*}
+% Throughout this manual, \cmd{\ShowIdxPageref*} illustrates basic index entries that do not contain sorting information or tags. The syntax is:
+%
+% \begin{SyntaxBox}
+% \cmd{\ShowIdxPageref*}\oarg{FNN}\marg{SNN|,| Affix}\oarg{Alternate}
+% \end{SyntaxBox}
+%
+% Regardless of whether we have a normal \LaTeX\ document or a \texttt{dtx} file, we get:\JustIndex\Soto
+%
% \begin{quote}\small
-% \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}.
+% |\ShowIdxPageref*[Hernando]{de~Soto}|\\
+% \ShowIdxPageref*[Hernando]{de~Soto}
% \end{quote}
%
-% Below we show more information about popular name forms by way of comparison with scholarly name forms.\medskip
+% \DescribeMacro{\ShowNameInfo}
+% Here we can see how the macros that take name arguments interpret them. We can check our intent against what the package actually sees.
%
-% The\Info{Scholarly works} \textit{Oxford Classical Dictionary} and other scholarly sources index according to the \textit{nomen}. That approach moves the \textit{nomen} from \meta{FNN} to \meta{SNN}. They have the the indexed form:
-% \begin{quote}
-% \ShowIdxPageref*[\meta{praenomen}]{\meta{nomen} \meta{cognomen} \meta{agnomen}}
-% \end{quote}
+% \begin{SyntaxBox}
+% \cmd{\ShowNameInfo}\oarg{FNN}\marg{SNN|,| Affix}\oarg{Alternate}
+% \end{SyntaxBox}
%
-% The two methods do not clash \textit{per se} in the text, but they make incompatible index entries. In this case, since we have indexed \ScipioOnly\ under the popular form above, we use \cmd{\ExcludeName} to exclude the scholarly form below.
+% Below we show several name forms. This macro shows detokenized name arguments to prevent potential errors and to disclose any macros in the name arguments, which are designated according to Section~\ref{sec:NameArgs}. Below are names that (mostly) appear elsewhere in the manual:
+%
+% \begin{itemize}\small
+% \item |\ShowNameInfo[J.E.]{Carter, Jr.}[James Earl]|
+% \item[] \ShowNameInfo[J.E.]{Carter, Jr.}[James Earl]
+% \item[] |\Name*[J.E.]{Carter, Jr.}[James Earl]|\dotfill
+% \Name*[J.E.]{Carter, Jr.}[James Earl]
+% \item |\ShowNameInfo{Miyazaki, Hayao}[Sensei]|
+% \item[] \ShowNameInfo{Miyazaki, Hayao}[Sensei]
+% \item[] |\Name*{Miyazaki, Hayao}[Sensei]|\dotfill
+% \Name*{Miyazaki, Hayao}[Sensei]
+% \item |\ShowNameInfo{Elizabeth, I}[I, ``Gloriana'']|
+% \item[] \ShowNameInfo{Elizabeth, I}[I, ``Gloriana'']
+% \item[] |\Name*{Elizabeth, I}[I, ``Gloriana'']|\dotfill
+% \Name*{Elizabeth, I}[I, ``Gloriana'']
+%
+% \newpage
+%
+% \item |\ShowNameInfo{Henry}[VIII]| (obsolete syntax)
+% \item[] \ShowNameInfo{Henry}[VIII]
+% \item[] |\Name*{Henry}[VIII]\ddag|\dotfill
+% \Name*{Henry}[VIII]\ddag
+% \item |\ShowNameInfo{Confucius}|
+% \item[]\ShowNameInfo{Confucius}
+% \item[] |\Name*{Confucius}|\dotfill\Name*{Confucius}
+% \end{itemize}
+%
+% For the following examples we activate alternate formatting
+% (Section~\ref{sec:AltFormat}).
+%
+% \AltFormatActive
+% \begin{itemize}\small
+% \item |\ShowNameInfo[John]{\noexpand\de{Strietelmeier}}|
+% \item[]\ShowNameInfo[John]{\noexpand\de{Strietelmeier}}
+% \item[]|\Name* [John]{\noexpand\de{Strietelmeier}|\dotfill\LStriet
+% \item |\ShowNameInfo[Catherine \noexpand\AltCaps{d}e']|\\
+% |{\noexpand\textSC{Medici}}|
+% \item[]\ShowNameInfo[Catherine \noexpand\AltCaps{d}e']
+% {\noexpand\textSC{Medici}}
+% \item[]|\Name [Catherine \noexpand\AltCaps{d}e']|\\
+% |{\noexpand\textSC{Medici}}|\dotfill\Cath
+% \item |\ShowNameInfo[Martin]{\noexpand\textSC{Luther}}|\footnote{In
+% several cases (e.g., here) when one uses small caps, harmless
+% font substitution warnings result.}
+% \item[]\ShowNameInfo[Martin]{\noexpand\textSC{Luther}}
+% \item[]|\Name* [Martin]{\noexpand\textSC{Luther}}|\dotfill\Luth
+% \item Using \cmd{\noexpand} before macros in name arguments
+% ``fixates'' them.
+% \begin{itemize}
+% \item|\ShowNameInfo[John]{\noexpand\de{Strietelmeier}}|
+% \item[]\ShowNameInfo[John]{\noexpand\de{Strietelmeier}}
+% \item|\ShowNameInfo[John]{\de{Strietelmeier}}|
+% \item[]\footnotesize\ShowNameInfo [John]{\de{Strietelmeier}}
+% \end{itemize}
+% \item If one uses an undefined macro in the arguments,
+% but precedes it with \cmd{\noexpand}, \cmd{\ShowNameInfo}
+% will not generate an error.
+% \begin{itemize}
+% \item|\ShowNameInfo{\noexpand\SomeUndefinedMacro}|
+% \item\ShowNameInfo{\noexpand\SomeUndefinedMacro}
+% \end{itemize}
+% \end{itemize}
+% \AltFormatInactive
+%
+% \negmedskip
+% \NameArgWarning
+% \medskip
+%
+% \phantomsection
+% \label{page:NameState}
+% \DescribeMacro{\ShowNameState}
+% With this macro we can see all the systems with which a name pattern is associated and the current index ``state'' described in Section~\ref{sec:RuleStates}. Its syntax is:
+%
+% \begin{SyntaxBox}
+% \cmd{\ShowNameState}\oarg{FNN}\marg{SNN|,| Affix}\oarg{Alternate}
+% \end{SyntaxBox}
+%
+% For example: |\ShowNameState[George]{Washington}| outputs a line of plain text regarding \LWash, which we can typeset any way we like:
%
-% In the document preamble we define the following Boolean flags and macros. We use a nested conditional in \meta{SNN}. The default still is to show all names so that they can be indexed that way:
% \begin{quote}\small
-% \StartNum
-% \begin{verbatim}
-%\newif\ifSkipGens % These flags remain the same as above.
-%\newif\ifNoGens
-%\newif\ifSkipAgnomen
-%\newif\ifNoAgnomen
-%\global\def\CSA{\ifNoGens\ifNoAgnomen
-% Scipio\else
-% Scipio Africanus\fi
-% \else\ifNoAgnomen
-% Cornelius Scipio\else
-% Cornelius Scipio Africanus\fi\fi}
-%\ExcludeName[Publius]{\noexpand\CSA}
-%\begin{nameauth}
-% \< OScipio & Publius & \noexpand\CSA & > % O for Oxford
-%\end{nameauth}
-%\PretagName[Publius]{\noexpand\CSA}{Cornelius Scipio Africanus}\end{verbatim}
+% \hfil\ShowNameState[George]{Washington}.\IndexName[George]{Washington}
% \end{quote}
%
-% We keep the same formatting macros that we defined above. By the way, these formatting macros could work with regular names as well as Roman names, e.g., \LDem, because they have no side effects.
+% \newpage
%
-% The scholarly form of Roman names has a different name pattern, so it is not compatible with the popular version. Nevertheless, we show what the index entries would be in a normal \LaTeX\ document without hyperlinks. Since we have excluded the scholarly form in order to suppress any spurious index entries, we only index the popular form below:
+% The information given includes:
%
-% \begin{center}\footnotesize\IndexActual{@}
-% \begin{tabular}{ll}
-% \multicolumn{2}{l}{\small\textbf{Simplified Name Patterns:}}\\
-% Scholarly: & \texttt{\ShowPattern[Publius]{\noexpand\CSA}}\\
-% Popular: & \texttt{\ShowPattern[\noexpand\SCIPi]{\noexpand\SCIPii}}\\[2ex]
-%
-% \multicolumn{2}{l}{\small\textbf{Full Index Entries:}}\\
-% \UntagName[Publius]{\noexpand\CSA}^^A
-% \UntagName[\noexpand\SCIPi]{\noexpand\SCIPii}^^A
-% Scholarly: & \texttt{\ShowIdxPageref[Publius]{\noexpand\CSA}}\\
-% Popular: & \texttt{\ShowIdxPageref[\noexpand\SCIPi]{\noexpand\SCIPii}}^^A
-% \TagName[Publius]{\noexpand\CSA}{\string|hyperpage}^^A
-% \TagName[\noexpand\SCIPi]{\noexpand\SCIPii}{\string|hyperpage}\\[2ex]
-%
-% \multicolumn{2}{l}{\small\textbf{Basic Index Entries:}}\\
-% \UntagName[Publius]{\noexpand\CSA}^^A
-% Scholarly: & \ShowIdxPageref*[Publius]{\noexpand\CSA}\\
-% Popular: & \ShowIdxPageref*[\noexpand\SCIPi]{\noexpand\SCIPii}^^A
-% \TagName[Publius]{\noexpand\CSA}{\string|hyperpage}\\
-% \end{tabular}
-% \end{center}
-%
-% Below we compare some differences between the scholarly and popular forms, and how to get equivalent forms in the text while understanding that they would be two separate forms in the index.
+% \begin{itemize}
+% \item Base name pattern, the base control pattern that
+% \textsf{nameauth} sees.
+% \item Type of name, referring to how the name in the argument was parsed.
+% \begin{itemize}[leftmargin=3.7em]
+% \item[w :] Western (regardless of whether it is reversed)
+% \item[nw :] non-Western (regardless of whether it is reversed)
+% \item[nw,os :] non-Western name, obsolete syntax (Section~\ref{sec:Obsolete})
+% \end{itemize}
+% \item Index state (Section~\ref{sec:RuleStates}) shows what index-related
+% options are permissible and how the indexing macros will behave.
+% \begin{itemize}[leftmargin=3.7em]
+% \item[states :] 1, 2, 3, 4, 5, and 6
+% \end{itemize}
+% \item All the control systems (Section~\ref{sec:NamePatterns}) that
+% the name pattern inhabits.
+% \begin{itemize}[leftmargin=4.5em]
+% \item[systems :] front, main, xref, excl, pretag, idxtag, namedb.
+% \end{itemize}
+% \end{itemize}
%
-% \begin{center}\footnotesize
-% \begin{tabular}{p{0.51\textwidth}l}
-% \multicolumn{2}{l}{\small\textbf{First use:}}\\
-% scholarly:\dotfill \cmd{\OScipio} & \OScipio\\
-% popular:\dotfill \cmd{\Scipio} & \ForgetThis\Scipio\\[2ex]
-%
-% \multicolumn{2}{l}{\small\textbf{Subsequent use:}}\\
-% scholarly:\dotfill \cmd{\OScipio} & \OScipio\\
-% scholarly:\dotfill \cmd{\SkipGenstrue}\cmd{\OScipio} & \SkipGenstrue\OScipio\\
-% popular:\dotfill \cmd{\Scipio} & \SkipGenstrue\Scipio\\[2ex]
-%
-% \multicolumn{2}{l}{\small\textbf{Subsequent use, full, no \textit{agnomen}:}}\\
-% scholarly:\dotfill \cmd{\SkipAgnomentrue}\cmd{\LOScipio} & \SkipAgnomentrue\LOScipio\\
-% popular:\dotfill \cmd{\SkipAgnomentrue}\cmd{\LScipio} & \SkipAgnomentrue\LScipio\\[2ex]
-%
-% \multicolumn{2}{l}{\small\textbf{Subsequent use, shortest forms:}}\\
-% scholarly:\dotfill \cmd{\SkipAgnomentrue}\cmd{\OScipio} & \SkipAgnomentrue\OScipio\\
-% \hfill\cmd{\SkipGenstrue}\cmd{\SkipAgnomentrue}\cmd{\OScipio} & \SkipGenstrue\SkipAgnomentrue\OScipio\\
-% popular:\dotfill \cmd{\SkipAgnomentrue}\cmd{\Scipio\ } & \SkipAgnomentrue\Scipio\\[2ex]
-%
-% \multicolumn{2}{l}{\small\textbf{Subsequent use, personal name:}}\\
-% scholarly:\dotfill \cmd{\SOScipio} & \SOScipio\\
-% popular:\dotfill \cmd{\SScipio} & \SScipio\\
-% popular:\dotfill \cmd{\SkipGenstrue}\cmd{\SScipio} & \SkipGenstrue\SScipio
+% In the next table we show examples that have indexing states in order from one to six, and we illustrate all name types and control systems. All extant names have index tags because, in a \texttt{dtx} file using the \textsf{ltxdoc} class with \textsf{hypdoc}, one must add a hyperlink to all names in the index (Section~\ref{sec:SpecialTag}). Otherwise, names need not always have a control pattern in the \texttt{idxtag} system.
+%
+% \begin{center}\small\medstretch
+% \begin{tabular}{p{0.4\textwidth}p{0.5\textwidth}}\toprule
+% Name & \cmd{\ShowNameState}\\
+% \rowcolor{nagrey}(\textit{unused in naming macro})\par
+% |\ShowNameState{Not Seen, Yet}| & \ShowNameState{Not Seen, Yet} \\
+% \Name*[Rudolph]{Carnap}\par |\Name*[Rudolph]{Carnap}| &
+% \ShowNameState[Rudolph]{Carnap}\\
+% \rowcolor{nagrey}\Name*{Henry, VIII}\par
+% |\Name*{Henry, VIII}| & \ShowNameState{Henry, VIII}\\
+% \Name*{Henry}[VIII]\ddag\par |\Name*{Henry}[VIII]\ddag| &
+% \ShowNameState{Henry}[VIII]\\
+% \rowcolor{nagrey}\Name*{Thomas, à~Kempis}\par
+% |\Name*{Thomas, à~Kempis}| & \ShowNameState{Thomas, à~Kempis}\\
+% (\textit{unused in naming macro})\par
+% |\IndexRef{Sun King}{Louis XIV}|\IndexRef{Sun King}{Louis XIV}\par
+% |\ShowNameState{Sun King}| & \hbox{}\par \ShowNameState{Sun King}\\
+% \rowcolor{nagrey}\Name*{Sun King}\par
+% |\Name*{Sun King}| & \ShowNameState{Sun King}\\
+% (\textit{unused in naming macro})\ExcludeName{Santa, Claus}\par
+% |\ExcludeName{Santa, Claus}| & \ShowNameState{Santa, Claus}\\
+% \rowcolor{nagrey}\Name*{Thomas,\`a~Kempis}\par
+% |\Name*{Thomas,\`a~Kempis}| & \ShowNameState{Thomas,\`a~Kempis}\\
+% \bottomrule
% \end{tabular}
% \end{center}
-% \endgroup^^A Local format hook redefinition
%
% \ReturnLink
-% \vfill
%
-% \begin{verse}
-% Oft fühl ich jetzt \dots [und] je tiefer ich einsehe, dass\\
-% Schicksal und Gemüt Namen eines Begriffes sind.\\[1ex]\hfill---\Name{Novalis}, \textit{Heinrich von Ofterdingen}
-% \end{verse}
% \newpage
%
-% \subsection{Indexing Macros}
+% \section{Indexing Macros}
% \label{sec:Indexing}
+% \IndexWarnVerbose
%
-% The strictness\Version{3.5} of the \textsf{nameauth} indexing macros and the detail of index-related warnings, especially with the \texttt{verbose} option, are comparable to professional indexing software. In addition to the macros below, please see also:
-%
-% \begin{center}\small\MyStretch
-% \begin{tabular}{ll}\toprule
-% error prevention & page~\pageref{page:IdxErrors}\\
-% \rowcolor{grey}index-related prefix macros & page~\pageref{page:IdxPrefix}\\
-% variant names and cross-references & page~\pageref{page:IdxVariants}\\\bottomrule
-% \end{tabular}
-% \end{center}
-%
-% Here also are the general protection rules for the indexing macros:
-% \begin{center}\small\MyStretch
-% \begin{tabular}{c@{\ \ }c@{\ \ }p{0.6\textwidth}}\toprule
-% Permit & Ignore & Attempted Action \\\midrule
-% \NO & \YES & Use \cmd{\IndexRef} with an extant name.\\
-% \YES & \NO & Use \cmd{\SeeAlso}\cmd{\IndexRef} with an extant name.\\
-% \NO & \YES & Create page references to a name after \cmd{\IndexRef} created a cross-reference using that name.\\\midrule
-% \NO & \YES & Try to make the same cross-reference multiple times.\\
-% \NO & \YES & Use \cmd{\IndexName} with a cross-reference.\\
-% \NO & \YES & Use \cmd{\ExcludeName} with a cross-reference.\\
-% \NO & \YES & Use \cmd{\IncludeName} with a cross-reference.\\
-% \YES & \NO & Use \cmd{\IncludeName*} with a cross-reference.\\
-% \YES & \NO & Use \cmd{\PretagName} to sort a cross-reference.\\
-% \NO & \YES & Use \cmd{\TagName} and \cmd{\UntagName} with a cross-reference.\\\bottomrule
-% \end{tabular}
-% \end{center}\smallskip
-%
-% \begin{tcolorbox}[colback=white,colframe=nared]
-% \centering We test \cmd{\ExcludeName\{Gregory, I\}}\ExcludeName{Gregory, I} here. See page~\pageref{page:ExPage}.
-% \end{tcolorbox}
+% We discuss indexing here because it pulls together all the concepts from the previous sections and applies them to the index instead of the body text.
%
-% \subsubsection[General Macros]{General Indexing Macros}
+% \subsection[General Control]{General Indexing Control}
% \label{sec:GeneralIndex}
%
-% \begin{center}\bfseries General Control\end{center}
+% \subsubsection{Toggle Indexing}
+%
% \DescribeMacro{\IndexInactive}
-% \cmd{\IndexInactive} deactivates the indexing functions of the naming macros, \cmd{\IndexName}, and \cmd{\IndexRef}.
+% \cmd{\IndexInactive} deactivates the indexing functions of the naming macros, as well as \cmd{\IndexName}, and \cmd{\IndexRef}.
% \DescribeMacro{\IndexActive}
-% \cmd{\IndexActive} enables indexing.
-% These can be used throughout the document.
-%
+% \cmd{\IndexActive} enables indexing. These can be used throughout the document. They do not affect indexing apart from \textsf{nameauth}.
+%
+% \vspace{2ex}
+% \Info{Test indexing rules:\break
+% \Name{Yamaha, Torakusu}\label{page:Idx1}\break
+% create index entry:\break
+% \cmd{\IndexName}\break
+% \texttt{\{Nippon Gakki\}}\IndexName{Nippon Gakki}}
+% \vspace{-2ex}
% \begin{itemize}
-% \item \cmd{\IndexInactive} broadly suppresses \cmd{\IndexName}, \cmd{\IndexRef}, the page entry indexing components of the naming macros, and the cross-referencing components of \cmd{\AKA} and \cmd{\PName}.
-% \item For a fine degree of control, use \cmd{\ExcludeName} and \cmd{\IncludeName}.
+% \item \cmd{\IndexInactive} broadly suppresses \cmd{\IndexName},
+% \cmd{\IndexRef}, and the indexing components of the naming macros,
+% \cmd{\AKA}, and \cmd{\PName}.
+% \item For a fine degree of control, use \cmd{\ExcludeName} and
+% \cmd{\IncludeName}.
% \end{itemize}
%
-% \cmd{\IndexActive}\Info{\cmd{\global}} and \cmd{\IndexInactive} can be used as a pair or singly within a group. They have top priority (page~\pageref{page:Priorities}). Use \cmd{\global} to force a global effect.\medskip
-%
-% \DescribeMacro{\IndexProtect}
-% This macro causes all naming macros to do nothing. \cmd{\IndexProtect} is local in scope, e.g., |{\IndexProtect\Name{Error}}|{\IndexProtect\Name{Error}} is isolated.\Version{3.3}
-% The naming macros and \cmd{\AKA} have locks that prevent them from being used in their own arguments to prevent errors. To prevent unlikely errors in the index, one can use \cmd{\IndexProtect} right before \cmd{\printindex} to eliminate spurious output.\footnote{This manual uses the tag \S\ for \cmd{\Name\{foo}\cmd{\Name\{bar\}\}}, not shown in the example.}
+% \cmd{\IndexActive}\Info{\cmd{\global}} and \cmd{\IndexInactive} can be used as a pair or singly within a group. They have top priority (Section~\ref{sec:Priorities}). Use \cmd{\global} to force a global effect.
%
-% \begin{center}\small\MyStretch
-% \begin{tabular}{llll}\toprule
-% \bfseries Macro & \bfseries Text & \bfseries \texttt{.ind} file & \bfseries Index\\\midrule
-% \rowcolor{grey}|\Name{foo\Name{bar}}| & \Name{foo\Name{bar}} & |\item foo\Name {bar}| & foo{\NamesFormat bar}\\
-% \rowcolor{grey}\cmd{\printindex} (next iteration adds) \(\rightarrow\) & & |\item bar| & bar\\
-% |\Name{foo\Name{bar}}| & \Name{foo\Name{bar}} & |\item foo\Name {bar}| & foo\\
-% \cmd{\IndexProtect}\cmd{\printindex} & & (no further output) & \\\bottomrule
-% \end{tabular}
-% \end{center}
+% \subsubsection{Multiple Indexes}
%
% \DescribeMacro{\NameauthIndex}
-% \LaTeX\ has various ways to produce multiple indexes. \cmd{\NameauthIndex}, which is defined as \cmd{\index}, can be redefined to implement multiple indexes of names.\Version{3.5} Below we use the \textsf{index} package to do this, but other alternatives also are possible.\footnote{See also \href{https://www.texfaq.org/FAQ-multind}{this} on multiple indexes and the test in \texttt{examples.tex}, located with this manual.}
+% \LaTeX\ has various ways to produce multiple indexes; see \href{https://www.texfaq.org/FAQ-multind}{\bfseries this page}. \cmd{\NameauthIndex} is the indexing hook defined by default as \cmd{\index}. Users can redefined this hook for use with multiple indexes. Below we use the \textsf{index} package to do this.
+%
+% \ifdefined\NameauthDoTestFiles \edef\NameauthTestFile{test07_01.tex}\else
+% \edef\NameauthTestFile{\jobname.tmp}\fi
+%
+% \begin{VerbatimOut}{\NameauthTestFile}
+% \documentclass{article}
+ % \input{compat.tex} % Included with nameauth; needed only if
+% % compiling on multiple TeX distros or LaTeX engines.
+% \usepackage{index}
+% \usepackage{nameauth}
%
-%\begin{quote}\small\StartNum
-%\begin{verbatim}
-%\documentclass{article}
-%\usepackage[T1]{fontenc}
-%\usepackage{index}
-%\usepackage{nameauth}
+% \makeindex % Default index
+% \newindex{per}{rdx}{rnd}{Index of Persons} % Other index
+% \renewcommand*\NameauthIndex{\index[per]}
%
-%\makeindex % Default index
-%\newindex{per}{rdx}{rnd}{Index of Persons} % Other index
-%\renewcommand\NameauthIndex{\index[per]}
+% \begin{document}
+% The Electric Boogaloo\index{Boogaloo, Electric}\\ % main index
+% was created by \Name{Ollie~\& Jerry}. % name index
%
-%\begin{document}
-% Electric Boogaloo\index{Boogaloo, Electric}% to main index
-% by \Name{Ollie~\& Jerry}% to name index
+% \printindex[per] % Shows the entry: Ollie & Jerry, 1
%
-% \printindex[per]% Shows the entry: Ollie & Jerry, 1
+% \renewcommand\indexname{Index of Subjects}
+% \printindex % Shows the entry: Boogaloo, Electric, 1
+% \end{document}
+% \end{VerbatimOut}
%
-% \renewcommand\indexname{Index of Subjects}
-% \printindex % Shows the entry: Boogaloo, Electric, 1
-%\end{document}\end{verbatim}
+% \begin{quote}\small
+% \VerbatimInput[gobble=0]{\NameauthTestFile}
% \end{quote}
%
-% \begin{center}\bfseries Page Entries\end{center}
+% \subsubsection{Verbose Warnings}
+%
+% \DescribeMacro{\IndexWarnVerbose}
+% As with many of the other options in \textsf{nameauth}, we have added two macros that toggle verbose index warnings like the \texttt{verbose} option (default is terse).
+% \DescribeMacro{\IndexWarnTerse}
+% To disable verbose warnings, use \cmd{\IndexWarnTerse}. To enable verbose warnings, use the \texttt{verbose} option or \cmd{\IndexWarnVerbose}. Throughout Section~\ref{sec:Indexing} we enable verbose warnings.\footnote{We both enable verbose warnings, and we deliberately trigger many of them. This helps to test if they are working as expected.}
+%
+% \newpage
+%
+% \cmd{\IndexWarnVerbose}\Info{\cmd{\global}} and \cmd{\IndexWarnTerse} can be used as a pair or singly within a group. They have the same priority as the \texttt{verbose} option, but they do not affect what is displayed in the document. Use \cmd{\global} to force a global effect.
+%
+% \subsubsection{Index Protection}
+%
+% \DescribeMacro{\IndexProtect}
+% This macro prevents naming macros from producing output, both in the text and in the index. It is local in scope. Its primary use is to prevent errors in the index, in case the naming macros get passed as arguments to themselves or passed into index entries by mistake. The core naming engine uses internal locks to protect against this problem in the text.
+%
+% \vspace{3ex}
+% \Info{Test indexing rules:\break
+% \Name{Yamaha, Torakusu}\label{page:Idx2}}
+% \vspace{-3ex}
+% One can use \cmd{\IndexProtect} right before \cmd{\printindex} to protect the index against bogus output. For example:
+%
+% \begin{itemize}
+% \item |\Name{foo\Name{bar}}| in the text generates \Name{foo\Name{bar}}.
+% Notice that the internal locks prevent |\Name{bar}| from producing
+% output in the text.
+% \item The first \LaTeX\ pass creates |\indexentry{foo\Name {bar}}|
+% in the \texttt{idx} file. With enough passes, using also
+% \texttt{makeindex}, in the \texttt{ind} file we get both
+% |\item foo\Name {bar}| from the text and an additional
+% |\item bar| from the macro executed in the index.
+% \item That gives one index entry ``foo{\NamesFormat bar}'' and
+% another entry ``bar''.
+% \item Using \cmd{\IndexProtect} \cmd{\printindex} still permits
+% the index entry generated by |\item foo\Name {bar}|, but it does not
+% allow |\Name {bar}| to generate any output or additional entries
+% in the index.
+% \item We get only one entry ``foo'', similar to what we see in the text.
+% This manual uses the tag \S\ for \cmd{\Name\{foo}\cmd{\Name\{bar\}\}},
+% not shown in the example for the sake of clarity.
+% \end{itemize}
+%
+% \subsection{Page Entries}
+% \label{sec:IndexPageno}
+%
% \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{
-% \begin{tabular}{l}
-% {\Large\strut}\cmd{\IndexName}\oarg{FNN}\marg{SNN|,| Affix}\oarg{Alternate}\\
-% \end{tabular}
-% }
-% \end{quote}
+% The internal version of this macro is used also by the naming macros. This is the user interface to create index page entries in the same way that the naming macros do. \cmd{\IndexName} prints nothing in the body text.
%
-% If \meta{FNN} is present, it ignores \meta{Alternate} for Western and ``native'' Eastern name forms. If \meta{FNN} is absent, \cmd{\IndexName} can use either the current or the obsolete non-Western syntax (Section~\ref{sec:Obsolete}). Indexing follows [\hyperlink{Mulvany}{Mulvany}, 152--82].
+% \begin{SyntaxBox}
+% \cmd{\IndexName}\oarg{FNN}\marg{SNN|,| Affix}\oarg{Alternate}
+% \end{SyntaxBox}
%
-% Currently,\Version{3.5} we assume that if one wants to use \cmd{\IndexName}, one really wants to index something. That means \cmd{\IndexName} will not respect \cmd{\SkipIndex}. Using \cmd{\IndexInactive} will still suppress indexing. The naming macros have used the following for some time, which causes \cmd{\IndexName} to obey \cmd{\SkipIndex}:
-% \begin{quote}\small
-% |\unless\if@nameauth@SkipIndex \IndexName|\dots|\fi.|
-% \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} can use either the current or the obsolete non-Western syntax (Section~\ref{sec:Obsolete}). Indexing follows [\hyperlink{Mulvany}{Mulvany}, 152--82]. The points below deal with macros explained in Section~\ref{sec:IdxPrefix}.
%
-% The stricter indexing control\Version{3.5} in place means that:
% \begin{itemize}
-% \item \cmd{\IndexName} will not index names excluded by \cmd{\ExcludeName}, as well as cross-references. This has been true for quite a while.
-% \item \cmd{\IndexName} resets the effects of both \cmd{\SeeAlso} and \cmd{\SkipIndex} unless one uses the \texttt{oldreset} option.
+% \item \cmd{\IndexName} obeys both \cmd{\IndexInactive} and
+% \cmd{\IndexActive}, which are used to deactivate and activate indexing.
+% \item \cmd{\IndexName} does not obey \cmd{\SkipIndex}. The latter
+% only works with macros that display a name in the text, which
+% \cmd{\IndexName} does not.
+% \item \cmd{\IndexName} will not make page entries for any names that are
+% excluded by \cmd{\ExcludeName}. Nor will it make entries names that
+% have been used to create cross-references.
+% \item \cmd{\IndexName} resets the effects of both \cmd{\SeeAlso} and
+% \cmd{\SkipIndex} unless one uses the \texttt{oldreset} option.
+% \item Section~\ref{sec:IdxPrefix} shows behavior among
+% \cmd{\SkipIndex}, \cmd{\JustIndex}, and the naming macros that
+% differs from the same macros and \cmd{\IndexName}.
% \end{itemize}
%
-% \DescribeMacro{\SkipIndex}
-% The prefix macro \cmd{\SkipIndex} will suppress indexing for just one instance of a naming macro.\Version{3.1} See also page~\pageref{page:IdxPrefix}. |\SkipIndex\Name[Monty]{Python}| produces \SkipIndex\Name[Monty]{Python} and \SkipIndex\Name[Monty]{Python} in the text, but with no index entry.\medskip
+% \subsection{Cross-References}
+% \label{sec:IndexRef}
%
-% \DescribeMacro{\JustIndex}
-% This prefix macro makes \cmd{\Name}, \cmd{\Name*}, \cmd{\FName}, and the quick interface shorthand macros act similar to a one-time call to \cmd{\IndexName}.\Version{3.5} \cmd{\JustIndex} suppresses name output in the text, but it resets flags for long and first name forms as if the naming macro had produced output. Using the \texttt{oldreset} option prevents these flags from being reset. See also page~\pageref{page:IdxPrefix}.
+% Index cross-references have two kinds. \textit{See} references only point from a name to other name entries containing page references. \textit{See also} references occur at the end of an entry with page references or subentries.
+%
+% \subsubsection[Basic Macro]{Basic Macros for Both Kinds of Xrefs}
%
-% \begin{center}\bfseries Cross-References\end{center}
% \DescribeMacro{\IndexRef}
-% By default, \cmd{\IndexRef} creates a \textit{see} reference from the name defined by its first three arguments to the target in its final argument:
-% \begin{quote}
-% \fbox{
-% \begin{tabular}{@{}l@{}}
-% {\Large\strut}\small\cmd{\IndexRef}\oarg{FNN}\marg{SNN|,| Affix}\oarg{Alternate}\marg{reference target}\\
-% \end{tabular}
-% }
-% \end{quote}
+% By default, \cmd{\IndexRef} creates a \textit{see} reference from the name defined by its first three arguments to the target in its final argument. To create a \textit{see also} reference, one must precede it with \cmd{\SeeAlso} (Section~\ref{sec:IdxPrefix}). Thus, the two forms used are:
+%
+% \begin{SyntaxBox}
+% \phantom{\cmd{\SeeAlso}}\cmd{\IndexRef}\oarg{FNN}\marg{SNN|,|
+% Affix}\oarg{Alternate}\marg{Target}\\
+% \cmd{\SeeAlso}\cmd{\IndexRef}\oarg{FNN}\marg{SNN|,|
+% Affix}\oarg{Alternate}\marg{Target}
+% \end{SyntaxBox}
+%
+% Although it might be redundant to point this out, in practice, when using \cmd{\IndexName} and \cmd{\IndexRef}, one can forget that the latter has four arguments, at least two of which are required. Missing text and bad xrefs can result.
%
-% The stricter indexing control\Version{3.5} in place means that:
% \begin{itemize}
-% \item \cmd{\IndexRef} will not cross-reference names excluded by \cmd{\ExcludeName}, as well as cross-references. This has been true for quite a while.
-% \item \cmd{\IndexRef} will not index any extant names used with \cmd{\Name} and friends, as well as the quick interface, unless one uses the \texttt{oldsee} option.
-% \item \cmd{\IndexName} resets the effects of both \cmd{\SeeAlso} and \cmd{\SkipIndex} unless one uses the \texttt{oldreset} option.
-% \item To have multiple names and cross-references interact, see page~\pageref{page:IdxVariants}.
+% \item Define \textit{see} references \emph{before} making any
+% \cmd{\Name} references to them.
+% \vspace{-1ex}
+% \Info{Test indexing rules:\break
+% Creating \textit{see also} xref\break\footnotesize
+% \cmd{\SeeAlso}\cmd{\IndexRef}\break\ttfamily
+% \{Yamaha, Torakusu\}\break
+% \{Nippon Gakki\}\SeeAlso\IndexRef{Yamaha, Torakusu}{Nippon Gakki}^^A
+% \label{page:Idx3}}
+% \vspace{1ex}
+% \item Define \textit{see also} references \emph{after} all
+% \cmd{\Name} references to the respective names have been created.
+% \item \cmd{\IndexRef} will not alter or repeat extant cross-references.
+% \item \cmd{\IndexRef} will not cross-reference names excluded
+% by \cmd{\ExcludeName}.
+% \item \cmd{\IndexRef} will not add a \textit{see} cross-reference
+% that would map also to an extant name control pattern, unless one
+% uses the \texttt{oldsee} option. A fuller explanation of this
+% non-trivial fact lies in Section~\ref{sec:RuleStates}, illustrated
+% by a state diagram. A page entry usually correlates with a name
+% control pattern, but that may not always be the case. We check for
+% a control sequence (name pattern); usually, a page entry also exists.
+% \item \cmd{\IndexName} resets the effects of both \cmd{\SeeAlso}
+% and \cmd{\SkipIndex}, unless one uses the \texttt{oldreset} option.
+% \item To have multiple names and cross-references interact, see
+% Section~\ref{sec:IdxVariants}.
% \end{itemize}
%
% \cmd{\IndexRef} prints nothing in the text. The name parsing is like \cmd{\IndexName}. The final argument is not checked in any way. For example:
-% \begin{quote}\leavevmode\Info{\vspace{-4ex}\break \strut\footnotesize Name Pattern(s):\hfill \break\ttfamily\ShowPattern{Sun King}!PN}
+%
+% \begin{quote}\small
+% \vspace{3ex}
+% \Info{\strut\footnotesize Name Pattern(s):\hfill
+% \break\ttfamily\ShowPattern{Sun King}!PN}
+% \vspace{-3ex}
% \begin{tabular}{ll}
-% source: & \cmd{\IndexRef}\texttt{\{Sun King\}\{Louis XIV\}}\IndexRef{Sun King}{Louis XIV}\\
-% index: & Sun King \textit{see} Louis XIV\\
+% source: & \cmd{\IndexRef}\texttt{\{Sun King\}\{Louis XIV\}}^^A
+% \IndexRef{Sun King}{Louis XIV}\\[0.5ex]
+% index: & Sun King \textit{see} Louis XIV\\
% \end{tabular}
% \end{quote}
%
-% \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.5} If enabled before invoking \cmd{\PName}, \cmd{\SeeAlso} will be disabled when the regular name is generated, then enabled when the cross-reference is generated. Currently \cmd{\IndexName} and any macros that use it will reset the Boolean flag governed by \cmd{\SeeAlso} unless one uses the \texttt{oldreset} option. This does not change the intended behavior of \cmd{\SeeAlso}. Rather, it prevents a stray use of the macro from affecting the index.\medskip
-%
-% \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{
-% \begin{tabular}{l}
-% {\Large\strut}\cmd{\ExcludeName}\oarg{FNN}\marg{SNN|,| Affix}\oarg{Alternate}\\
-% \end{tabular}
-% }
+% \cmd{\IndexRef} will not merge multiple cross-references and it will not allow more than one cross-reference. For multiple cross-references one must use something like the following example, or create manual index entries:
+%
+% \begin{quote}\small
+% \begin{tabular}{ll}
+% source: & |\IndexRef{bar}{baz; foo}|\\[0.5ex]
+% index: & bar, \textit{see} baz; foo\\
+% \end{tabular}
% \end{quote}
-% Unlike \cmd{\IndexInactive} and \cmd{\IndexActive}, which inhibit indexing altogether, this macro only excludes a specific name from being printed as a page reference or cross-reference in the index. See the following example, as well as examples in Sections~\ref{sec:VarNames} and \ref{sec:NameParticles}:
+%
% \newpage
%
-% \begin{quote}\small\leavevmode\PatInfo{\ShowPattern[Kris]{Kringle}!PN\break \ShowPattern[Santa]{Claus}!PN\break \ShowPattern{Grinch}!PN\break \ShowPattern[Kris]{Kringle}!MN\break \ShowPattern[Santa]{Claus}!MN\break \ShowPattern{Grinch}!MN}
-% \ExcludeName[Kris]{Kringle}\ExcludeName[Santa]{Claus}\ExcludeName{Grinch}
-% \StartNum\vspace{-5ex}
-% \begin{verbatim}
-%\ExcludeName[Kris]{Kringle}
-%\ExcludeName[Santa]{Claus}
-%\ExcludeName{Grinch}
-%\Name[Kris]{Kringle}, a.k.a. \Name[Santa]{Claus}
-%even likes the \Name{Grinch}.\end{verbatim}
-%
-% \Name[Kris]{Kringle}, a.k.a. \Name[Santa]{Claus}
-% even likes the \Name{Grinch}.
+% \subsubsection[Fine Control]{Fine Control of Xref Logic}
+% \label{sec:IdxFine}
+%
+% Here we show how the index control logic pertinent to cross-references can be extended to establish fine-grained control that can exclude or include names.\medskip
+%
+% \DescribeMacro{\ExcludeName}
+% We can prevent a name from being used as either an index entry or as an index cross-reference. This macro will not exclude extant cross-references:
+%
+% \begin{SyntaxBox}
+% \cmd{\ExcludeName}\oarg{FNN}\marg{SNN|,| Affix}\oarg{Alternate}
+% \end{SyntaxBox}
+%
+% Unlike \cmd{\IndexInactive} and \cmd{\IndexActive}, which globally prevent and permit indexing, \cmd{\ExcludeName} only excludes a specific name from being printed as a page reference or cross-reference in the index. See the following example, as well as examples in Sections~\ref{sec:NameParticles} and \ref{sec:VarNames}. Indexing remains active:
+%
+% \begin{VerbatimOut}{\jobname.tmp}
+% \ExcludeName{Mr. Baseball}
+% In this example we cannot get page references for
+% \Name{Mr. Baseball}, the nickname of
+% \Name[Bob]{Uecker}, because it was excluded.
+% \end{VerbatimOut}
+%
+% \begin{quote}\small
+% \vspace{3ex}
+% \PatInfo{\ShowPattern{Mr. Baseball}!PN\break
+% \ShowPattern[Bob]{Uecker}!MN}
+% \vspace{-3ex}
+% \VerbatimInput[gobble=0]{\jobname.tmp}
+%
+% \input{\jobname.tmp}
% \end{quote}
%
% \DescribeMacro{\IncludeName}
% Use these macros to break a few indexing rules. They remove the protections used for exclusion and cross-referencing.
% \DescribeMacro{\IncludeName*}
% They have the same syntax as \cmd{\ExcludeName}:
-% \begin{quote}
-% \fbox{
-% \begin{tabular}{l}
-% {\Large\strut}\cmd{\IncludeName\ }\oarg{FNN}\marg{SNN|,| Affix}\oarg{Alternate}\vspace{-2pt}\\
-% {\Large\strut}\cmd{\IncludeName*}\oarg{FNN}\marg{SNN|,| Affix}\oarg{Alternate}\\
-% \end{tabular}
-% }
-% \end{quote}
%
-% \phantomsection
-% \label{page:ExPage}
-% \cmd{\IncludeName} only voids an exclusion created by \cmd{\ExcludeName}. The more extreme \cmd{\IncludeName*} completely un-protects a cross-reference. Thereafter, one may create page entries for it as a name. For example:
+% \begin{SyntaxBox}
+% \cmd{\IncludeName\ }\oarg{FNN}\marg{SNN|,| Affix}\oarg{Alternate}\\
+% \cmd{\IncludeName*}\oarg{FNN}\marg{SNN|,| Affix}\oarg{Alternate}
+% \end{SyntaxBox}
%
-% \begin{itemize}
-% \item As an\PatInfo{\ShowPattern{Gregory, I}!PN\break \ShowPattern{Gregory, I}!MN} excluded name, |\Name*{Gregory, I}| \Name*{Gregory, I} does not create an index entry.
-% \item \cmd{\IfAKA\{Gregory, I\}}|{|\meta{an xref}|}{|\meta{a name}|}{|\meta{excluded}|}| tells us that \Name{Gregory, I} is \IfAKA{Gregory, I}{\meta{an xref}}{\meta{a name}}{\meta{excluded}} (cf. Section~\ref{sec:NameTests}).
-% \end{itemize}
+% \cmd{\IncludeName} removes an exclusion attached to a name by \cmd{\ExcludeName}. \cmd{\IncludeName*} completely erases both exclusion and cross-reference information. Once that protection is removed, one can create page references to a name in the index that had been used as a cross-reference.
+%
+% \vspace{3ex}
+% \Info{Test indexing rules:\break \Name{Yamaha, Torakusu}\label{page:Idx4}}
+% \vspace{-3ex}
+% Analogously, \cmd{\ForgetName} (Section~\ref{sec:NameControl}) removes name control patterns, allowing one to create a cross-reference. Section~\ref{sec:RuleStates} explains this behavior as a set of states. Below we run some tests (cf. Section~\ref{sec:NameTests}) and produce a few warnings because verbose warnings are active here.
%
-% After using |\IncludeName{Gregory, I}|\IncludeName{Gregory, I}, the following points are true:
% \begin{itemize}
-% \item |\Name*{Gregory, I}| displays \Name*{Gregory, I} and creates an index entry.
-% \item \cmd{\IfAKA\{Gregory, I\}}|{|\meta{an xref}|}{|\meta{a name}|}{|\meta{excluded}|}| now tells us that \Name{Gregory, I} has become \IfAKA{Gregory, I}{\meta{an xref}}{\meta{a name}}{\meta{excluded}}.
+% \item \Name*{Mr. Baseball} is
+% \IfAKA{Mr. Baseball}{\meta{an xref}}{\meta{a name}}{\meta{excluded}}.
+% The test used was:
+% \item[] |\IfAKA{Mr. Baseball}{|\meta{an xref}|}{|\meta{a name}^^A
+% |}{|\meta{excluded}|}|
+% \item We now try |\IndexRef{Mr. Baseball}{Uecker, Bob}|^^A
+% \IndexRef{Mr. Baseball}{Uecker, Bob}.
+% \Name*{Mr. Baseball} is still
+% \IfAKA{Mr. Baseball}{\meta{an xref}}{\meta{a name}}{\meta{excluded}}.
+% No cross-reference was created.
+% \item Using |\IncludeName{Mr. Baseball}|\IncludeName{Mr. Baseball}
+% makes it
+% \IfAKA{Mr. Baseball}{\meta{an xref}}{\meta{a name}}{\meta{excluded}}.
+% Now we could create page entries with a naming macro, but we
+% do not do so.
+% \item Instead, we use
+% |\ForgetName{Mr. Baseball}|\ForgetName{Mr. Baseball} to destroy
+% the name pattern, the control sequence that governs the name.
+% It is now
+% \IfAKA{Mr. Baseball}
+% {\meta{an xref}}
+% {\IfMainName{Mr. Baseball}{\meta{extant}}
+% {\IfFrontName{Mr. Baseball}
+% {\meta{extant}}{\meta{destroyed}}^^A
+% }^^A
+% }
+% {\meta{excluded}}.
+% \item |\IndexRef{Mr. Baseball}{Uecker, Bob}|^^A
+% \IndexRef{Mr. Baseball}{Uecker, Bob} creates
+% \IfAKA{Mr. Baseball}{\meta{an xref}}{\meta{a name}}{\meta{excluded}}.
% \end{itemize}
%
-% Cross-references get more protection.\PatInfo{\ShowPattern[J.D.]{Rockefeller, IV}!MN\break \ShowPattern[Jay]{Rockefeller}!PN\break \ShowPattern[Jay]{Rockefeller}!MN} We have seen \DropAffix\LJRIV[Jay] indexed under ``\ShowIdxPageref*[J.D.]{Rockefeller, IV}'' with |\DropAffix\LJRIV[Jay]|. We create the cross-index \IndexRef[Jay]{Rockefeller}{Rockefeller, J.D., IV}|\IndexRef[Jay]{Rockefeller}{Rockefeller, J.D., IV}|.
+% \newpage
+%
+% Cross-references get more protection. We have seen
+% \DropAffix\LJRIV[Jay] indexed under
+% ``\ShowIdxPageref*[J.D.]{Rockefeller, IV}'' with
+% |\DropAffix\LJRIV[Jay]|.
+% We create the following cross-reference:
+% \IndexRef[Jay]{Rockefeller}{Rockefeller, J.D., IV}^^A
+% |\IndexRef[Jay]{Rockefeller}{Rockefeller, J.D., IV}|.
+% \vspace{-6ex}
+% \PatInfo{\ShowPattern[J.D.]{Rockefeller, IV}!MN\break
+% \ShowPattern[Jay]{Rockefeller}!PN\break
+% \ShowPattern[Jay]{Rockefeller}!MN}
+% \vspace{6ex}
% \begin{itemize}
-% \item \cmd{\IfAKA[Jay]\{Rockefeller\}}|{|\meta{xref}|}{|\meta{name}|}{}| calls \SJRIV[Jay] an \IfAKA[Jay]{Rockefeller}{\meta{xref}}{\meta{name}}{}.
-% \item After |\IncludeName[Jay]{Rockefeller}|\IncludeName[Jay]{Rockefeller} he still is an \IfAKA[Jay]{Rockefeller}{\meta{xref}}{\meta{name}}{}.
-% \item After |\IncludeName*[Jay]{Rockefeller}|\IncludeName*[Jay]{Rockefeller} he becomes a \IfAKA[Jay]{Rockefeller}{\meta{xref}}{\meta{name}}{}.
-% \item Now \cmd{\Name[Jay]\{Rockefeller\}} will create page entries.
+% \item
+% \cmd{\IfAKA[Jay]\{Rockefeller\}}|{|\meta{xref}|}{|\meta{name}|}{}|
+% calls \SJRIV[Jay] an
+% \IfAKA[Jay]{Rockefeller}{\meta{xref}}{\meta{name}}{}.
+% \item After
+% |\IncludeName[Jay]{Rockefeller}|\IncludeName[Jay]{Rockefeller}
+% he still is an
+% \IfAKA[Jay]{Rockefeller}{\meta{xref}}{\meta{name}}{}.
+% \item After
+% |\IncludeName*[Jay]{Rockefeller}|\IncludeName*[Jay]{Rockefeller}
+% he may be a \IfAKA[Jay]{Rockefeller}{\meta{xref}}{\meta{name}}{}.
+% \item Now \cmd{\Name[Jay]\{Rockefeller\}} can create page entries.
% \end{itemize}
%
-% Analogous to how \cmd{\IncludeName*} allows one to turn an xref into a name with page references, \cmd{\ForgetName} and possibly \cmd{\ForgetThis} (Section~\ref{sec:NameControl}) allow one to assign a \textit{see} reference to an extant name. This is bad when using one index, but desirable when using multiple indexes.\medskip
+% \negmedskip
+% \begin{InfoBox}
+% Using \cmd{\IncludeName*} is necessary when creating index sub-entries for a name using \cmd{\IndexTag}. If one creates a cross-reference in any sub-entry of a name, \cmd{\IncludeName*} will permit additional page references to be made for the other sub-entries of that name or for the name itself. See Section~\ref{sec:CatSub}.
+% \end{InfoBox}
%
-% \begin{center}\bfseries Error Prevention\end{center}
-% \phantomsection
-% \label{page:IdxErrors}
-% \cmd{\IndexName} and \cmd{\IndexRef}\Version{3.5} strictly enforce professional indexing practices. Now they are more sensitive to order of use. Both \cmd{\ForgetName} and \cmd{\ForgetThis} (Section~\ref{sec:NameControl}) can affect this mechanism. The \texttt{verbose} option aids debugging.
-% \begin{itemize}
-% \item[]
-% \bgroup\small\MyStretch\begin{tabular}{rp{0.38\textwidth}@{\ }p{0.23\textwidth}}\toprule
-% Page & Macro & Index Result\\\midrule
-% \rowcolor{grey}1 & \cmd{\Name\{bar\}}\dotfill \hbox{} & bar, 1\\
-% 2 & \cmd{\Name\{bar\}}\dotfill \hbox{} & bar, 1, 2\\
-% \end{tabular}\egroup\smallskip
-%
-% \item A \textit{see also} reference to a certain name must follow all page references to that name. The use of \cmd{\SeeAlso}\cmd{\IndexRef\{bar\}\{foo\}} on page~3 prevents \cmd{\Name\{bar\}} from creating an index page reference on page~4:\\[1.5ex]
-% \bgroup\small\MyStretch\begin{tabular}{rp{0.38\textwidth}@{\ }p{0.23\textwidth}}
-% \phantom{Page} & \phantom{Macro} & \phantom{Index Result}\\[-2.5ex]
-% \rowcolor{grey}3 & \cmd{\SeeAlso}\cmd{\IndexRef\{bar\}\{foo\}} & bar, 1, 2, \textit{see also} foo\\
-% 4 & \cmd{\Name\{bar\}}\dotfill \hbox{} & bar, 1, 2, \textit{see also} foo\\
-% \end{tabular}\egroup\smallskip
-%
-% \item Targets of cross-references are not affected by this. \cmd{\Name\{foo\}} creates index page entries because it is the target, not the xref:\\[1.5ex]
-% \bgroup\small\begin{tabular}{rp{0.38\textwidth}@{\ }p{0.23\textwidth}}
-% \phantom{Page} & \phantom{Macro} & \phantom{Index Result}\\[-2.5ex]
-% \rowcolor{grey}5 & \cmd{\Name\{foo\}}\dotfill \hbox{} & bar, 1, 2, \textit{see also} foo\\
-% \rowcolor{grey}& & foo, 5\\
-% \end{tabular}\egroup
+% \subsection[Prefix Macros]{Prefix Macros Used for Indexing}
+% \label{sec:IdxPrefix}
%
-% \item A \textit{see}\Version{3.5} reference is supposed to have no page references; a \textit{see also} reference does have page references, but only before it is created. Trying to use an extant name as a \textit{see} reference is strictly ignored:\\[1.5ex]
-% \bgroup\small\begin{tabular}{rp{0.38\textwidth}@{\ }p{0.23\textwidth}}
-% \phantom{Page} & \phantom{Macro} & \phantom{Index Result}\\[-2.5ex]
-% 6 & \cmd{\Name\{baz\}}\dotfill \hbox{} & bar, 1, 2, \textit{see also} foo\\
-% & & baz, 6\\
-% & & foo, 5\\
-% \rowcolor{grey}7 & \cmd{\IndexRef\{baz\}\{meschugge\}}\dotfill \hbox{} & bar, 1, 2, \textit{see also} foo\\
-% \rowcolor{grey}& & baz, 6\\
-% \rowcolor{grey}& & foo, 5\\\bottomrule
-% \end{tabular}\egroup
-% \end{itemize}\leavevmode
+% Indexing macros ignore Boolean flags meant for naming macros. Yet there are three prefix macros that affect indexing: \cmd{\SeeAlso}, \cmd{\SkipIndex}, and \cmd{\JustIndex}.\medskip
%
-% \begin{center}\bfseries Prefix Macros and Indexing Macros\end{center}
-% \phantomsection
-% \label{page:IdxPrefix}
-% Indexing macros ignore Boolean flags meant for naming macros. Yet there are three prefix macros that affect indexing: \cmd{\SeeAlso}, \cmd{\SkipIndex}, and \cmd{\JustIndex}.
+% \DescribeMacro{\SeeAlso}
+% Put \cmd{\SeeAlso} before \cmd{\IndexRef}, \cmd{\AKA}, and \cmd{\PName} (Section~\ref{sec:AKA}) to make a \textit{see also} reference for a name that has appeared already in the index. If enabled before invoking \cmd{\PName}, \cmd{\SeeAlso} will be disabled when the regular name is generated, then enabled when the cross-reference is generated.
+%
+% \begin{VerbatimOut}{\jobname.tmp}
+% One can refer to \Name[the]{Rat Pack} as a group of entertainers
+% including \Name[Sammy]{Davis, Jr.}, \Name[Dean]{Martin}, and
+% \Name[Frank]{Sinatra}. No more page references to
+% \Name*[the]{Rat Pack} will occur after this line, and a
+% \textit{see also} xref will exist.
+% \SeeAlso\IndexRef[the]{Rat Pack}
+% {Davis, Sammy, Jr.; Martin, Dean; Sinatra, Frank}
+% \end{VerbatimOut}
+%
+% \begin{quote}\small
+% \VerbatimInput[gobble=0]{\jobname.tmp}
+%
+% \input{\jobname.tmp}
+% \end{quote}
+%
+% \leavevmode\Info{Test indexing rules:\break
+% \Name{Nippon Gakki}\label{page:Idx5}}
+% Currently \cmd{\IndexName} and other \textsf{nameauth} macros that create index entries will reset the Boolean flag governed by \cmd{\SeeAlso} unless one uses the \texttt{oldreset} option. preventing a stray use of the macro from affecting the index.\medskip
+%
+% \DescribeMacro{\SkipIndex}
+% The prefix macro \cmd{\SkipIndex} will suppress indexing for just one instance of a name displayed by a naming macro. |\SkipIndex\Name[Monty]{Python}| produces \SkipIndex\Name[Monty]{Python} in the text, but with no index entry. \cmd{\SkipIndex} works with the naming macros. Side effects include:
%
% \begin{itemize}
-% \item \cmd{\SeeAlso} works with and is reset by \cmd{\IndexRef}, \cmd{\AKA}, and \cmd{\PName} (see also Section~\ref{sec:AKA}). There are few, if any, side effects.\medskip
-% \item \cmd{\SkipIndex} works with the naming macros. Side effects include:
-% \begin{itemize}
-% \item Unless the \texttt{oldreset} option is used,\Version{3.5} both \cmd{\IndexName} and \cmd{\IndexRef} issue warnings if \cmd{\SkipIndex} precedes them, ignore \cmd{\SkipIndex}, and reset its flag.
-% \item Only when the \texttt{oldreset} option is used, both \cmd{\PName}\Version{3.5} and \cmd{\PName*} issue warnings when \texttt{\textbackslash if@nameauth@SkipIndex} is true on exit.
-% \end{itemize}
-% \item \cmd{\JustIndex} makes the naming macros act like \cmd{\IndexName}. That affects both the printing and indexing flags governed by prefix macros.
+% \item Unless the \texttt{oldreset} option is used, both \cmd{\IndexName}
+% and \cmd{\IndexRef} issue warnings if \cmd{\SkipIndex} precedes them,
+% ignore \cmd{\SkipIndex}, and reset its flag.
+% \item Only when the \texttt{oldreset} option is used, both \cmd{\PName}
+% and \cmd{\PName*} issue warnings when {\ttfamily
+% \string \if@nameauth@SkipIndex} is true on exit.
% \end{itemize}
%
-% There are many potential side effects related to \cmd{\JustIndex}:
-% \begin{itemize}
-% \item Both \cmd{\AKA} and \cmd{\PName} ignore \cmd{\JustIndex} and go on about their business. They also set \cmd{\@nameauth@JustIndexfalse}.
-% \item \cmd{\JustIndex} causes the naming macros to imitate \cmd{\IndexName} and ignore most flags, except for those discussed in the next bullet point. That makes the following two lines equivalent:
-% \begin{quote}\small\MyStretch
-% \cmd{\SkipIndex} \cmd{\JustIndex} \cmd{\Name\{A\}} \cmd{\Name\{B\}}\\
-% \cmd{\JustIndex} \cmd{\Name\{A\}} \cmd{\SkipIndex} \cmd{\Name\{B\}}
-% \end{quote}
-% According to the table on page~\pageref{page:Priorities}, \cmd{\JustIndex} takes priority with \cmd{\Name\{A\}} and passes \cmd{\@nameauth@SkipIndextrue} to \cmd{\Name\{B\}}.
-% \item Currently,\Version{3.3} the naming macros always reset \cmd{\@nameauth@FullNamefalse} and \cmd{\@nameauth@FirstNamefalse}. For example:\\[1.5ex]
-% \bgroup\small\vspace{-17ex}\PatInfo{\ShowPattern[George]{Washington}!MN}\vspace{17ex}\MyStretch\begin{tabular}{ll}\toprule
-% Source & Output\\\midrule
-% \rowcolor{grey}|\JustIndex\FName[George]{Washington}%| & \\
-% \rowcolor{grey}| \Name[George]{Washington}| &
-% \JustIndex\FName[George]{Washington}\Name[George]{Washington}\\
-% \rowcolor{grey}|\JustIndex\SWash \Wash| & \JustIndex\SWash \Wash \hphantom{ George}\\
-% |\JustIndex\Name*[George]{Washington}%| & \\
-% | \Name[George]{Washington}| &
-% \JustIndex\Name*[George]{Washington}\Name[George]{Washington}\\
-% |\JustIndex\LWash \Wash| & \JustIndex\LWash \Wash\\
-% \end{tabular}\egroup\smallskip
-%
-% \item The \texttt{oldpass} option restores the old behavior, which did not always reset the name length modifier. For example:\\[1.5ex]
-% \bgroup\makeatletter\@nameauth@OldPasstrue\makeatother%
-% \small\vspace{-17ex}\PatInfo{\ShowPattern[George]{Washington}!MN}\vspace{17ex}\MyStretch\begin{tabular}{ll}
-% \rowcolor{grey}|\JustIndex\FName[George]{Washington}%| & \\
-% \rowcolor{grey}| \Name[George]{Washington}| &
-% \JustIndex\FName[George]{Washington}\Name[George]{Washington}\\
-% \rowcolor{grey}|\JustIndex\SWash \Wash| & \JustIndex\SWash \Wash\\
-% |\JustIndex\Name*[George]{Washington}%| & \\
-% | \Name[George]{Washington}| &
-% \JustIndex\Name*[George]{Washington}\Name[George]{Washington}\\
-% |\JustIndex\LWash \Wash| & \JustIndex\LWash \Wash\\\bottomrule
-% \end{tabular}\egroup
-% \end{itemize}\leavevmode
+% \DescribeMacro{\JustIndex}
+% This prefix macro makes \cmd{\Name}, \cmd{\Name*}, \cmd{\FName}, and the quick interface shorthand macros act similar to \cmd{\IndexName}. \cmd{\JustIndex} suppresses name output in the text, but flags for long and first name forms are reset as if the naming macro had produced output. Using the \texttt{oldreset} option prevents these flags from being reset, completely mimicking a call to \cmd{\IndexName}.
+%
+% \begin{center}\small\medstretch
+% \begin{tabular}{lll}\toprule
+% Option & Source & Output\\
+% \rowcolor{nagrey}default & |\JustIndex\SWash \Wash| &
+% \JustIndex\SWash \Wash \hphantom{ George}\\
+% default & |\JustIndex\LWash \Wash| & \JustIndex\LWash \Wash\\
+% \rowcolor{nagrey}\ttfamily oldpass & |\JustIndex\SWash \Wash| &
+% \JustIndex\SWash \Wash\\
+% \ttfamily oldpass & |\JustIndex\LWash \Wash| &
+% \JustIndex\LWash \Wash\\\bottomrule
+% \end{tabular}
+% \vspace{-15ex}\PatInfo{\ShowPattern[George]{Washington}!MN}\vspace{15ex}
+% \end{center}
%
-% \begin{center}\bfseries Variant Names and Cross-References\end{center}
% \phantomsection
-% \label{page:IdxVariants}
-% Here we show differences among variants and cross-references. We can choose to index variants under the canonical name or we can set up cross-references with variants. The order in which we do that is significant:
-% \begin{enumerate}
-% \item We use\PatInfo{\ShowPattern[J.E.]{Carter, Jr.}!MN\hfill \textrm{(1--2)}\break \ShowPattern[Jimmy]{Carter}!PN\hfill \textrm{(3, 6)}\break \ShowPattern[Jimmy]{Carter}!MN\hfill \textrm{(4)}\break \ShowPattern[J.E.]{Carter, Jr.}!PN\hfill \textrm{(5)}} the canonical name to create page references:\smallskip\\
-% \hbox{}\quad|\Name*[J.E.]{Carter, Jr.}|\dotfill \Name*[J.E.]{Carter, Jr.}
-% \item Variants that use \meta{Alternate} in the text create page entries under the canonical form, not the variant form:\smallskip\\
-% \hbox{}\quad|\DropAffix\Name*[J.E.]{Carter, Jr.}[Jimmy]|\dotfill \DropAffix\Name*[J.E.]{Carter, Jr.}[Jimmy]\\
-% \hbox{}\quad|\ShowIdxPageref*[J.E.]{Carter, Jr.}[Jimmy]|\dotfill \ShowIdxPageref*[J.E.]{Carter, Jr.}[Jimmy]
-% \item We must create\Version{3.5} a \textit{see} reference from an alternate form to a canonical form \emph{before} using the alternate form in a naming macro, or it will be ignored and a warning will result:\smallskip\\
-% \hbox{}\quad|\IndexRef[Jimmy]{Carter}{Carter, J.E., Jr.}|\IndexRef[Jimmy]{Carter}{Carter, J.E., Jr.}
-% \item No page references will occur below because we made the \textit{see} reference first. Note how the alternate form is an independent name:\smallskip\\
-% \hbox{}\quad|\Name[Jimmy]{Carter}|\dotfill \Name[Jimmy]{Carter}
-% \item If we want to index the alternate name, we have to use the canonical name instead of the alternate name:\smallskip\\
-% \hbox{}\quad|\IndexName[J.E.]{Carter, Jr.}|
-% \item If instead we wanted to make a \textit{see also} reference, we would use both the canonical name and the alternate name, then create the cross-reference \emph{after} all uses of the alternate name (at the end of the document), e.g.:\smallskip\\
-% \hbox{}\quad|\SeeAlso\IndexRef[Jimmy]{Carter}{Carter, J.E., Jr.}|
-% \end{enumerate}
+% \vspace{1ex}
+% \Info{Test indexing rules:\break
+% Creating \textit{see} xref\break\footnotesize
+% \cmd{\IndexRef}\ttfamily \{Nippon Gakki\}\break
+% \{Yamaha Corp.\}^^A
+% \IndexRef{Nippon Gakki}{Yamaha Corp.}^^A
+% \label{page:Idx6}}
+% \vspace{-1ex}
+% There are potential side effects related to \cmd{\JustIndex}:
%
-% 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{enumerate}
-% \item We use\PatInfo{\ShowPattern{Maimonides}!MN \textrm{(1)}\break \ShowPattern{Moses, ben-Maimon}!PN \textrm{(2)}\break \ShowPattern{Moses, ben-Maimon}!MN \textrm{(3)}\break \ShowPattern{Rambam}!MN \textrm{(4)}\break \ShowPattern{Rambam}!PN \textrm{(5)}} 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}
-% \item We now have a main name with a page entry and a ``\textit{see} reference'' to that name. No page references will occur below because we made the \textit{see} reference first:\smallskip\\
-% \hbox{}\qquad|\Name{Moses, ben-Maimon}|\dotfill \Name{Moses, ben-Maimon}
-% \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{enumerate}
+% \begin{itemize}
+% \item Both \cmd{\AKA} and \cmd{\PName} ignore \cmd{\JustIndex}
+% and go on about their business. They also set
+% \cmd{\@nameauth@JustIndexfalse}.
+% \item \cmd{\JustIndex} resets the flags set by \cmd{\ForgetThis}
+% and \cmd{\SubvertThis}, preventing them from passing through.
+% \item The following three lines are equivalent. According to
+% Section~\ref{sec:Priorities}, \cmd{\JustIndex} takes priority
+% with \cmd{\Name\{A\}} and passes \cmd{\SkipIndex} to
+% \cmd{\Name\{B\}}.
%
-% \cmd{\IndexRef}\Info{Combining xrefs} will not merge multiple cross-references and it will not allow more than one cross-reference. For multiple cross-references one must use something like:
-% \begin{quote}
-% \begin{tabular}{ll}
-% source: & |\IndexRef{bar}{baz; foo}|\\[0.5ex]
-% index: & bar, \textit{see} baz; foo\\
-% \end{tabular}
+% \begin{quote}\small
+% \cmd{\JustIndex} \cmd{\SkipIndex} \cmd{\Name\{A\}} \cmd{\Name\{B\}}\\
+% \cmd{\SkipIndex} \cmd{\JustIndex} \cmd{\Name\{A\}} \cmd{\Name\{B\}}\\
+% \cmd{\JustIndex} \cmd{\Name\{A\}} \cmd{\SkipIndex} \cmd{\Name\{B\}}
% \end{quote}
%
-% There\Info{Multiple targets} is a special case where one cross-reference can point to multiple targets, such as demonstrated in the example below:
-%
-% \begin{quote}\small\leavevmode\PatInfo{\ShowPattern{\textit{Snellius}}!PRE\break \ShowPattern{\textit{Snellius}}!PN\break \ShowPattern[W.]{Snel van Royen}!MN\break \ShowPattern[R.]{Snel van Royen}!MN}\vspace{-5ex}
-% \StartNum
-% \begin{verbatim}
-%\PretagName{\textit{Snellius}}{Snellius}
-%\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{verbatim}
+% \item One cannot use \cmd{\JustIndex} and the naming macros in place
+% of \cmd{\IndexRef}.
+% \end{itemize}
%
-% \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}
+% \subsection{Automatic Rules}
+% \label{sec:IdxRules}
+%
+% Below we indicate what to expect regarding index rules in any given state. Here we do not attempt to concatenate page ranges. Above, we put a series of names and cross-references in margin notes, Here is the result:
+%
+% \begin{center}\footnotesize\smallstretch
+% \begin{tabular}{rp{0.3\textwidth}p{0.5\textwidth}}\toprule
+% Page & Macro & Index Result\\
+% \rowcolor{nagrey}\pageref{page:Idx1} &
+% \cmd{\Name\{Yamaha, Torakusu\}}\par
+% \cmd{\IndexName\{Nippon Gakki\}} &
+% \ShowIdxPageref*{Yamaha, Torakusu}, \pageref{page:Idx1}\par
+% \ShowIdxPageref*{Nippon Gakki}, \pageref{page:Idx1}\\
+% \pageref{page:Idx2} &
+% \cmd{\Name\{Yamaha, Torakusu\}} &
+% \ShowIdxPageref*{Yamaha, Torakusu}, \pageref{page:Idx1},
+% \pageref{page:Idx2}\par
+% \ShowIdxPageref*{Nippon Gakki}, \pageref{page:Idx1}\\
+% \rowcolor{nagrey}\pageref{page:Idx3} &
+% \cmd{\SeeAlso}\cmd{\IndexRef\{Yamaha,}\par
+% \texttt{Torakusu\}\{Nippon Gakki\}} &
+% \ShowIdxPageref*{Yamaha, Torakusu}, \pageref{page:Idx1},
+% \pageref{page:Idx2} \textit{see also} Nippon Gakki\par
+% \ShowIdxPageref*{Nippon Gakki}, \pageref{page:Idx1}\\
+% \pageref{page:Idx4} &
+% \cmd{\Name\{Yamaha, Torakusu\}} &
+% \ShowIdxPageref*{Yamaha, Torakusu}, \pageref{page:Idx1},
+% \pageref{page:Idx2} \textit{see also} Nippon Gakki\par
+% \ShowIdxPageref*{Nippon Gakki}, \pageref{page:Idx1}\\
+% \rowcolor{nagrey}\pageref{page:Idx5} &
+% \cmd{\Name\{Nippon Gakki\}} &
+% \ShowIdxPageref*{Yamaha, Torakusu}, \pageref{page:Idx1},
+% \pageref{page:Idx2} \textit{see also} Nippon Gakki\par
+% \ShowIdxPageref*{Nippon Gakki}, \pageref{page:Idx1}, \pageref{page:Idx5}\\
+% \pageref{page:Idx6} &
+% \cmd{\IndexRef\{Nippon Gakki\}}\par \texttt{\{Yamaha Corp.\}} &
+% \ShowIdxPageref*{Yamaha, Torakusu}, \pageref{page:Idx1},
+% \pageref{page:Idx2} \textit{see also} Nippon Gakki\par
+% \ShowIdxPageref*{Nippon Gakki}, \pageref{page:Idx1},
+% \pageref{page:Idx5}\\\bottomrule
+% \end{tabular}
+% \end{center}
%
-% \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.
+% \begin{enumerate}
+% \item On page \pageref{page:Idx1}^^A
+% \PatInfo{\ShowPattern{Yamaha,Torakusu}!MN}
+% there are no name control patterns (Section~\ref{sec:NamePatterns})
+% for either a name or a cross-reference. Then the name
+% \Name*{Yamaha, Torakusu} comes into being, along with its control
+% pattern. A pair of index page entries are generated, one before and
+% one after the name.
+% \item[] Also on \pageref{page:Idx1} an index page entry is created for
+% \Name{Nippon Gakki}, whose control pattern does not yet exist.
+% \item On page \pageref{page:Idx2}^^A
+% \PatInfo{\ShowPattern{Yamaha,Torakusu}!MN}
+% the name \Name{Yamaha, Torakusu} appears again. Since a control
+% pattern exists, a short form is printed and two index page entries
+% are generated.
+% \item On page \pageref{page:Idx3}^^A
+% \PatInfo{\ShowPattern{Yamaha,Torakusu}!PN}
+% we create a \textit{see also} cross reference from
+% \Name*{Yamaha, Torakusu} to the name \Name{Nippon Gakki}. Now a
+% cross-reference pattern exists for Mr. \Name{Yamaha, Torakusu}.
+% We can no longer create index page entries for him.
+% \item On page \pageref{page:Idx4} we attempt to make an index page
+% entry to Mr. \Name{Yamaha, Torakusu} by invoking his name. That
+% attempt fails due to the extant xref.
+% \item On page \pageref{page:Idx5}^^A
+% \PatInfo{\ShowPattern{Nippon Gakki}!MN}
+% we print the name \Name{Nippon Gakki}, bringing its name control
+% sequence into being. Even though it was the \emph{target} of an xref,
+% that does not restrict the ability to make page entries for it.
+% \item On page \pageref{page:Idx6}^^A
+% \PatInfo{\ShowPattern{Yamaha Corp.}!MN}
+% we attempt to create a \textit{see} cross reference from
+% \Name{Nippon Gakki} to the name \Name{Yamaha Corp.}. (Notice that
+% the extra full stop in the text gets gobbled.) That fails because,
+% unlike a \textit{see also} reference, a \textit{see} reference
+% cannot be created when a name control pattern already exists.
+% \end{enumerate}
%
-% \ReturnLink
-% \newpage
+% This manual's index entries for \Name{Nippon Gakki} and \Name{Yamaha Corp.} will also include this page in addition to those shown above.
%
-% \subsubsection{Index Sorting}
+% \subsection[Sorting Names]{Sorting Names in the Index}
% \label{sec:IndexSort}
%
-% Here we introduce the index sorting macros, with examples of error prevention:
-% \begin{center}\small\MyStretch
-% \begin{tabular}{ll}\toprule
-% potential sorting problems & page~\pageref{page:DebugSort}\\
-% \rowcolor{grey}example reference work & page~\pageref{page:ContinentalXref}\\\bottomrule
-% \end{tabular}
-% \end{center}
+% When using \texttt{makeindex}, all names with characters outside the ASCII range \texttt{[A–Za–z]} need to be sorted. All names with macros in their arguments need to be sorted. All names with particles need to be sorted. We do that with sort tags.
+%
+% \subsubsection{General Approach}
%
% \DescribeMacro{\IndexActual}
-% Using \cmd{\index\{}\meta{sort key}\texttt{@}\meta{actual}\texttt{\}} works with both \texttt{makeindex} and \texttt{texindy}.\footnote{The general practice for sorting with \texttt{makeindex -s} involves creating an \texttt{.ist} file (pages 659--65 in \textit{The Latex Companion}).}
-% 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
+% Using \cmd{\index\{}\meta{sort key}\texttt{@}\meta{actual}\texttt{\}} works with both \texttt{makeindex} and \texttt{texindy}. The general practice for sorting with \texttt{makeindex -s} involves creating an \texttt{ist} file (pages 659--65 in \textit{The Latex Companion}).
+%
+% 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 creating index entries with the naming macros. \cmd{\PretagName} does not care about the ``actual'' character, but it provides the information that is automatically added after that character. \medskip
%
% Effects of \cmd{\IndexActual}\Info{\cmd{\global}} are local in scope. Use \cmd{\global} to make it otherwise, but that will affect every use of \cmd{\PretagName} thereafter. We demonstrate this scoping below as it pertains to \texttt{gind.ist} in a \texttt{dtx} file:
-% \begin{quote}\small\leavevmode\PatInfo{\ShowPattern{Ægidius}!PRE}\vspace{-5ex}
-% \StartNum
-% \begin{verbatim}
-%\PretagName{Ægidius}{Aegidius}
-%\begingroup
-% \IndexActual{@}
-% \ShowIdxPageref{Ægidius}\qquad
-%\endgroup
-%\ShowIdxPageref{Ægidius}\end{verbatim}
-%
-%\PretagName{Ægidius}{Aegidius}
-%\begingroup
-% \IndexActual{@}
-% \ShowIdxPageref{Ægidius}\qquad
-%\endgroup
-%\ShowIdxPageref{Ægidius}
+%
+% \begin{quote}\small
+% \vspace{4ex}
+% \PatInfo{\ShowPattern{Ægidius}!PRE}
+% \vspace{-4ex}
+% \begin{Verbatim}
+% \PretagName{Ægidius}{Aegidius}
+%
+% In a \texttt{dtx} file the ``actual'' character is \texttt{=}.
+% \begingroup
+% In a local scope we change to the normal character \texttt{@}
+% and show the index entry:
+% \texttt{\IndexActual{@}\ShowIdxPageref{Ægidius}}.
+% \endgroup
+% Now back to \texttt{dtx} mode: \texttt{\ShowIdxPageref{Ægidius}}.
+% \end{Verbatim}
+%
+% \PretagName{Ægidius}{Aegidius}
+%
+% In a \texttt{dtx} file the ``actual'' character is \texttt{=}.
+% \begingroup
+% In a local scope we change to the normal character \texttt{@}
+% and show the index entry:
+% \texttt{\IndexActual{@}\ShowIdxPageref{Ægidius}}.
+% \endgroup
+% Now back to \texttt{dtx} mode: \texttt{\ShowIdxPageref{Ægidius}}.
% \end{quote}
-%
+%
% \noindent \DescribeMacro{\PretagName}
% The \textsf{nameauth} package enables automatic index sorting using a ``pretag'' (cf. Section~\ref{sec:NamePatterns}). Unless the \texttt{nopretag} option is used (which results in warnings), \cmd{\PretagName} creates a sort key terminated with the ``actual'' character. Do not put the ``actual'' character in the ``pretag'':
%
-% \begin{quote}
-% \fbox{
-% \begin{tabular}{l}
-% {\Large\strut}\cmd{\PretagName}\oarg{FNN}\marg{SNN|,| Affix}\oarg{Alternate}\marg{tag}\\
-% \end{tabular}
-% }
-% \end{quote}
+% \begin{SyntaxBox}
+% \cmd{\PretagName}\oarg{FNN}\marg{SNN|,| Affix}\oarg{Alternate}\marg{tag}
+% \end{SyntaxBox}
%
-% One can ``pretag'' any name, any cross-reference, and even excluded names. Once made, sorting tags cannot be unmade. If one uses \cmd{\PretagName} in the preamble, those names will be sorted automatically. For example:
+% \vspace{2ex}
+% \PatInfo{\ShowPattern{Æthelred, II}!PRE\break
+% \ShowPattern[W.E.B.]{Du~Bois}!PRE\break
+% \ShowPattern{Æthelred, II}!MN\break
+% \ShowPattern[W.E.B.]{Du~Bois}!MN}
+% \vspace{-2ex}
+% One can ``pretag'' any name, any cross-reference, and even excluded names. Once made, sorting tags cannot be unmade. If one uses \cmd{\PretagName} in the preamble, those names will be sorted automatically throughout the document. For example:
%
-% \begin{quote}\small\leavevmode\PatInfo{\ShowPattern{Æthelred, II}!PRE\break \ShowPattern[W.E.B.]{Du~Bois}!PRE\break \ShowPattern{Æthelred, II}!MN\break \ShowPattern[W.E.B.]{Du~Bois}!MN}\vspace{-5ex}
-% \StartNum
-% \begin{verbatim}
-%\PretagName{Æthelred, II}{Aethelred 2}
-%\PretagName[W.E.B.]{Du~Bois}{Dubois, William}\end{verbatim}
+% \begin{quote}\small
+% \begin{Verbatim}
+% \PretagName{Æthelred, II}{Aethelred 2}
+% \PretagName[W.E.B.]{Du~Bois}{Dubois, William}
+% \end{Verbatim}
% \end{quote}
%
-% Every reference to \LAeth\ and \LDuBois\ is automatically tagged and sorted. One should ``pretag'' all names that contain active characters or macros. That can differ when using \texttt{xindy} and Unicode-based \LaTeX. We keep this example simple and do not use alternate formatting (cf. Sections~\ref{sec:NameAncient}, \ref{sec:AltFormat}). The name patterns are: \texttt{\ShowPattern{\textit{Doctor angelicus}}!PRE \ShowPattern{\textit{Doctor angelicus}}!PN \ShowPattern{Thomas, Aquinas}!MN \ShowPattern{\textit{Doctor angelicus}}!MN}:
+% Every reference to \LAeth\ and \LDuBois\ is automatically tagged and sorted.\footnote{Regarding the margin note that shows name control sequences, with \texttt{pdflatex} and \texttt{latex}, in \texttt{\ShowPattern{Æthelred, II}} the glyphs \texttt{ÃĘ} correspond to \cmd{\IeC\{}\cmd{\AE\}}.} One should ``pretag'' all names that contain active characters or macros. That can differ when using \texttt{xindy} and Unicode-based \LaTeX.
%
-% \begin{quote}\small
-% \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}
+% We keep the next example simple to illustrate the concept. We do not use alternate formatting because we do not capitalize, mutate, or segment the alias ``\textit{Doctor angelicus}'' (cf. Sections~\ref{sec:NameMedieval}, \ref{sec:AltFormat}). We create a \textit{see} reference before using this alias, for which no page entries will be generated. The name patterns are:
%
-% \smallskip
-% \PretagName{\textit{Doctor angelicus}}{Doctor Angelicus}
+% \begin{VerbatimOut}{\jobname.tmp}
+% \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}
+% \end{VerbatimOut}
%
-% Spaces change sorting. For example, the\Info{Particles and\break languages} sort tag \texttt{De\textvisiblespace Soto} precedes \texttt{deal} due to the space therein. 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
-%
-% 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 also the documentation for \texttt{xindy} and \texttt{makeindex}.
+% \begin{quote}\small
+% {\ttfamily\ShowPattern{\textit{Doctor angelicus}}!PRE\\
+% \ShowPattern{\textit{Doctor angelicus}}!PN\\
+% \ShowPattern{Thomas, Aquinas}!MN\\
+% \ShowPattern{\textit{Doctor angelicus}}!MN}
%
-% \begin{center}\bfseries Potential Sorting Problems\end{center}
-% \phantomsection
-% \label{page:DebugSort}
-% If an entry is sorted incorrectly 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}
+% \VerbatimInput[gobble=0]{\jobname.tmp}
%
-% Since 2018, changes in the way that \texttt{pdflatex} and \texttt{latex} handle Unicode characters have made indexing simpler and more intuitive, e.g.
+% \input{\jobname.tmp}
+% \end{quote}
%
-% \def\arrow{\ \(\rightarrow\)\ }
-% \def\midrowa{\arrow\quad}
-% \def\midrowb{\hphantom{\arrow}\quad}
-% \def\midrow{\midrowb}
-% \begin{center}\MyStretch
-% \begin{tabular}{l@{\ }l>{\hspace{-1em}\midrow}ll@{\ }l>{\hspace{-1em}\midrow}l}\toprule
-% pre-2018 & text & index & post-2018 & text & index\gdef\midrow{\midrowa}\\\midrule
-% \rowcolor{grey} & ä & \texttt{\cmd{\IeC\textvisiblespace}\{\cmd{\"a}\}} & & ä & \texttt{ä}\\
-% & æ & \texttt{\cmd{\IeC\textvisiblespace}\{\cmd{\ae\textvisiblespace}\}}
-% & & æ & \texttt{æ}\\\bottomrule
-% \end{tabular}
-% \end{center}
+% If we had wanted \Name{\textit{Doctor angelicus}} to have page entries and a \textit{see also} reference, we would have omitted line~2 above, waited until the end of the body text, after both names were fully indexed, and then used the following:
%
-% One can test for this change and take different approaches with:
% \begin{quote}\small
-% \cmd{\IfFileExists\{utf8-2018.def\}}\marg{yes}\marg{no}
+% |\SeeAlso\IndexRef{\textit{Doctor angelicus}}{Thomas Aquinas}|
% \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.
+% Spaces change sorting. For example, the\Info{Particles} sort tag \texttt{De\textvisiblespace Soto} precedes \texttt{deal} due to the space therein. The sort tag \texttt{DeSoto} falls as expected between \texttt{derp} and \texttt{determinism}.
%
-% 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.
-%
-% This is not an issue with the \textsf{nameauth} package as such. Rather, it stems from the use of \cmd{\protected@edef}. This package requires \cmd{\protected@edef} in any situation where the macros that generate index entries are written to the \texttt{aux} file for execution there, such as in the \textsf{memoir} class. Without \cmd{\protected@edef}, any active Unicode characters would start expanding, thus making different index entries than those one might make by hand. Since we do not want a ``package way'' to index names and a ``regular way'' that is different and hard to integrate with the ``package way'', this is an unavoidable necessity.
% \newpage
%
-% Below we show the general minimal working example:
-% \begin{quote}\small
-% \StartNum
-% \begin{verbatim}
-%\newcommand\Idx[1]{%
-% \protected@edef\arg{#1}%
-% \index{\arg}}\end{verbatim}
-% \medskip
+% German\Info{Collating\break sequences} \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}.
%
-% The macro \cmd{\Idx\{}\cmd{\textsc\{football\}\}} produces:\\
-% \hbox{}\qquad\cmd{\indexentry}\texttt{\{\cmd{\textsc\textvisiblespace\textvisiblespace}\{football\}\}\{}\meta{page}\texttt{\}}\\[1ex]
-% The macro \cmd{\index\{}\cmd{\textsc\{football\}\}} produces:\\
-% \hbox{}\qquad\cmd{\indexentry}\texttt{\{\cmd{\textsc}\{football\}\}\{}\meta{page}\texttt{\}}
+% Additional examples\Info{Alternate\break formatting} starting with Section~\ref{sec:RealAltEx} deal with index sorting as it relates to alternate formatting and ``Continental'' practice. When sorting names that use alternate formatting or macros in name arguments, please ensure that the macros expand to the form desired in the index. If one is not using built-in macros related to alternate formatting, additional steps might be required when using \cmd{\PretagName} with names containing macros.
+%
+% \subsubsection{Sorting Initials}
+% \label{sec:IndexInitials}
+%
+% Sorting \Name*[J.D.]{Rockefeller, IV} |\Name*[J.D.]{Rockefeller, IV}| presents a problem that does not occur with \Name*[Clive Staples]{Lewis} |\Name*[Clive Staples]{Lewis}|. In the case of \Name*[J.D.]{Rockefeller, IV}[Jay], the initials will appear in the index, while with \Name*[Clive Staples]{Lewis}[C.S.], the longer names will appear in the index.
+%
+% \begin{InfoBox}
+% In order to sort the index consistently and properly, all names
+% should be sorted by their longer name forms, not their initials.
+% \end{InfoBox}
+%
+% In \textsf{nameauth} we have a specific way to do that once per name, and all the remaining names will be sorted as expected. Before we use a name like \Name[J.D.]{Rockefeller, IV}, preferably in the preamble, we use the following macro:
+%
+% \begin{quote}\small
+% |\PretagName[J.D.]{Rockefeller, IV}{Rockefeller, John D 4}|
% \end{quote}
-%
-% The debugging macros will not help at this point. We must inspect the \texttt{idx} file. The problem with the debugging macros is that they show how an index entry will appear on the page, more or less, but not how it will appear in the \texttt{idx} file, which determines sorting.
%
-% \ReturnLink
+% Notice that we follow the form of the index entry, which will be ``\ShowIdxPageref*[J.D.]{Rockefeller, IV}''. We spell out the first forename, leave enough of the second forename for sorting, and turn the Roman numeral affix into an Arabic numeral so that it does not sort like alphabetic letters. For more examples of handling alternate forms of surnames see Sections~\ref{sec:NameMedieval}, \ref{sec:VarNames}, all subsections of Section~\ref{sec:AdvancedFormat}, and~\ref{sec:AdvCustomize}.
%
-% \subsubsection{Index Tags}
+% \subsection{Index Tags}
% \label{sec:IndexTag}
%
+% Index info tags (``index tags'') are information added automatically to index page entries for names used with \textsf{nameauth} macros.
+%
+% \subsubsection{General Approach}
+%
% \DescribeMacro{\TagName}
-% This macro creates a tag appended to all index entries for a corresponding \cmd{\Name}.
+% This macro creates a tag that persists until one changes it with \cmd{\TagName} or destroys it with \cmd{\UntagName}.
% \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} have \emph{global scope} and handle arguments like \cmd{\IndexName}:
-% \begin{quote}
-% \fbox{
-% \begin{tabular}{l}
-% {\Large\strut}\cmd{\TagName}\oarg{FNN}\marg{SNN|,| Affix}\oarg{Alternate}\marg{tag}\vspace{-2pt}\\
-% {\Large\strut}\cmd{\UntagName}\oarg{FNN}\marg{SNN|,| Affix}\oarg{Alternate}\\
-% \end{tabular}
-% }
-% \end{quote}
+% Tags can include life dates, regnal dates, and other information. Both \cmd{\TagName} and \cmd{\UntagName} have \emph{global scope} and handle arguments in the same way as \cmd{\IndexName}:
+%
+% \begin{SyntaxBox}
+% \cmd{\TagName}\oarg{FNN}\marg{SNN|,| Affix}\oarg{Alternate}\marg{tag}\\
+% \cmd{\UntagName}\oarg{FNN}\marg{SNN|,| Affix}\oarg{Alternate}
+% \end{SyntaxBox}
%
% 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. The following graphic illustrates the ``segments'' of an index entry and the \textsf{nameauth} macros that affect the respective segments:
%
-% \begin{center}\small\MyStretch
-% \begin{tabular}{r@{\,\vrule width0.5pt\,}c@{\,\vrule width0.5pt\,}c@{\,\vrule width0.5pt\,}l}
+% \begin{center}\small\smallstretch
+% \begin{tabular}{r|l|l|l}\toprule
+% & & Naming macros\\
% & \cmd{\PretagName} & \cmd{\IndexName}\\
-% \large\bfseries|\index{| & \large\bfseries|Aethelred 2@| & \large\bfseries|Æthelred II| & \large\bfseries|, king}|\\
-% & & & \quad\cmd{\TagName}\\
-% & & & \quad\cmd{\UntagName}\\
+% \large\bfseries|\index{| & \large\bfseries|Aethelred 2@| &
+% \large\bfseries|Æthelred II| & \large\bfseries|, king}|\\
+% & & & \cmd{\TagName}\\
+% & & & \cmd{\UntagName}\\\bottomrule
% \end{tabular}
% \end{center}
%
-% 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 created below:
-% \begin{quote}\small\leavevmode\PatInfo{\ShowPattern{Gregory, I}!TAG\break \ShowPattern{Gregory, I}!MN\break \ShowPattern{Gregory, the Great}!PN}\vspace{-5ex}
-% \StartNum
-% \begin{verbatim}
-%\TagName{Gregory, I}{, pope}
-%Pope \Name*{Gregory, I} was known as \Name{Gregory, I}
-%``the Great''.\IndexRef{Gregory, the Great}{Gregory I}\end{verbatim}
+% Tags created by \cmd{\TagName} can be \Info{Scholarly texts}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 created below:
%
-% \smallskip
+% \begin{VerbatimOut}{\jobname.tmp}
+% \TagName{Gregory, I}{, pope}
% Pope \Name*{Gregory, I} was known as \Name{Gregory, I}
% ``the Great''.\IndexRef{Gregory, the Great}{Gregory I}
+% \end{VerbatimOut}
+%
+% \begin{quote}\small
+% \vspace{3.5ex}
+% \PatInfo{\ShowPattern{Gregory, I}!TAG\break
+% \ShowPattern{Gregory, I}!MN\break
+% \ShowPattern{Gregory, the Great}!PN}
+% \vspace{-3.5ex}
+% \VerbatimInput[gobble=0]{\jobname.tmp}
+%
+% Pope \Name*{Gregory, I} was known as \Name{Gregory, I}
+% ``the Great''.\IndexRef{Gregory, the Great}{Gregory I}
% \end{quote}
%
-% \cmd{\TagName} works with all names, but not with cross-references from \cmd{\IndexRef}, \cmd{\AKA}, etc. (cf. Sections~\ref{sec:GeneralIndex}, \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
+% \cmd{\TagName} works with all names that produce index page entries. It does not work with with cross-references that are produced by \cmd{\IndexRef}, \cmd{\AKA}, etc.
%
-% 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.:
+% Tags can hold different kinds of information, but they should not be overly verbose. They can include 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.
%
-% \begin{quote}\small\leavevmode\PatInfo{\ShowPattern[E.]{Humperdinck}!TAG\break \ShowPattern[E.]{Humperdinck}!MN}\vspace{-4.5ex}
-% \StartNum
-% \begin{verbatim}
-%\TagName[E.]{Humperdinck}{ (composer)}
-%This refers to the classical composer:
-%\Name[E.]{Humperdinck}[Engelbert].
+% \subsubsection[Identical Names]{Disambiguating Identical Names}
%
-%\TagName[E.]{Humperdinck}{ (singer)}
-%This refers to the pop singer from the 60s and 70s:
-%\ForgetThis\Name[E.]{Humperdinck}[Engelbert].\end{verbatim}
+% We 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, while the name decision macros can set up specific logic for each name:
%
-% \smallskip
-% \TagName[E.]{Humperdinck}{ (composer)\string|hyperpage}
+% \begin{VerbatimOut}{\jobname.tmp}
+% \TagName[E.]{Humperdinck}{ (composer)}
% This refers to the classical composer:
% \Name[E.]{Humperdinck}[Engelbert].
%
-% \TagName[E.]{Humperdinck}{ (singer)\string|hyperpage}
+% \TagName[E.]{Humperdinck}{ (singer)}
% This refers to the pop singer from the 60s and 70s:
% \ForgetThis\Name[E.]{Humperdinck}[Engelbert].
+% \end{VerbatimOut}
+%
+% \begin{quote}\small
+% \vspace{4ex}
+% \PatInfo{\ShowPattern[E.]{Humperdinck}!TAG\break
+% \ShowPattern[E.]{Humperdinck}!MN}
+% \vspace{-4ex}
+% \VerbatimInput[gobble=0]{\jobname.tmp}
+%
+% \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}
+%
+% \subsubsection[Special Tags]{Special Tags for Special Cases}
+% \label{sec:SpecialTag}
+%
+% \cmd{\TagName} can create ``special'' index entries for names with the general form below. These tags are compatible with \textsf{hyperref} used in normal \LaTeX\ documents.\footnote{This was implemented in v.3.3, based on the answer of \Name*[Heiko]{Oberdiek} to \href{https://tex.stackexchange.com/questions/201720/index-produces-invalid-idx-entry-with-manual-style-commaparse-hyperref}
+% {\bfseries this question}.}
+% When \texttt{\textbackslash}\meta{macro}\texttt{\#1\{\#1\}} exists and \meta{name args} are the arguments, one can use the form:
+%
+% \begin{SyntaxBox}
+% \cmd{\TagName}\meta{name args}\texttt{\{\textbar}\meta{macro}\texttt{\}}
+% \end{SyntaxBox}
+%
+% When \Warn\ using the \textsf{ltxdoc} class with \textsf{hypdoc}, as in this manual, \textsf{nameauth} does not create hyperlinked page entries. If one puts index tags in the |<driver>| section of the \texttt{dtx} file, which will read the ``commented''part of the \texttt{dtx} file into a \texttt{document} environment, then one can use the following:
+%
+% \begin{quote}\small
+% \cmd{\TagName}\meta{name args}\texttt{\{\textbar hyperpage\}}
% \end{quote}
%
-% One\Info{Special tags} can use \cmd{\TagName} to create ``special'' index entries for names with the general form \cmd{\TagName}\meta{name args}\texttt{\{\textbar}\meta{Macro}\texttt{\}},\Version{3.3} when \cmd{\def}\texttt{\textbackslash}\meta{Macro}\texttt{\#1\{\#1\}} exists. These 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 \Name*[Heiko]{Oberdiek} in \href{https://tex.stackexchange.com/questions/201720/index-produces-invalid-idx-entry-with-manual-style-commaparse-hyperref}{this question}.}
+% Things get more complicated in the ``commented'' part of the package documentation in this \texttt{dtx} file. There, thanks to \textsf{ltxdoc}, the vertical bar is active. Index tags in the documentation part must use the form:
+%
+% \begin{quote}\small
+% \cmd{\TagName}\meta{name args}\texttt{\{}\cmd{\string}\texttt{\textbar
+% hyperpage\}}
+% \end{quote}
%
-% 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}. In this manual we had to tag every name with \cmd{\TagName}\meta{name args}\texttt{\{\textbar hyperpage\}} in the driver section of the \texttt{dtx} file.
+% Internally, in \cmd{\@nameauth@IdxFormat}, when a cross-reference is being created, a tag of the form \meta{some text}\texttt{\textbar}\meta{some macro} is reduced to \meta{some text}, allowing the macros \texttt{\textbar see} and \texttt{\textbar seealso} internally to be appended to the index entry even if a tag with a vertical bar exists.
%
-% 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 args}\texttt{\{}\cmd{\string}\texttt{\textbar hyperpage\}}.
+% Next we create a special tag. Since we used lines~1–2 in this \texttt{dtx} file\Warn, we put them in the driver section to avoid both errors with the redefinition of the vertical bar and any possible confusion when using \cmd{\string}.
%
-% 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}
+% \begin{Verbatim}
+% \newcommand\Orphan[2]{#1(\hyperpage{#2})}
+% \TagName[Lost]{Name}{\,\S|Orphan{perdit}}
+% \Name[Lost]{Name}
+% \end{Verbatim}
%
-% \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}|}|
+% \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}
%
-% When \cmd{\IndexRef}\Info{Error\break prevention} calls \cmd{\@nameauth@Index}, a tag of the form \meta{some text}\texttt{\textbar}\meta{some macro} is reduced to \meta{some text}, allowing a new \texttt{\textbar}\meta{cross-reference} macro to be added. This keeps cross-references from breaking.\medskip
+% The \textsf{microtype}\Info{Manual breaks\break and entries} 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. Yet we could add manual breaks after editing is complete.
%
-% The \textsf{microtype}\Info{Manual breaks\break and entries} 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 the very end of the editing and proofreading passes. That is fairly easy to do.
+% We must create a helper macro that takes an argument and adds a break after that argument. That is how macros like \cmd{\textbf} use implied page references in the index page entries, e.g.: \cmd{\index\{Doe, John\string|textbf\}}.
%
-% We cannot just insert something like \cmd{\newpage} or \cmd{\columnbreak} directly into an index. Instead, we create a helper macro that takes an argument and adds a break after that argument. That is, for example, how macros like \cmd{\textbf} use implied page references: \cmd{\index\{Doe, John\string|textbf\}}.
-%
-% 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}. On line 1 we define the \cmd{\Endbreak} macro that will break the index page or column at the end of an entry. On line 3 we do the same for somewhere in the middle of an index entry. In the latter case there will be a comma that we must \cmd{\@gobble} after a page reference:
+% Below we use \cmd{\newpage} to jump to a new column. See also the \textsf{multicol} and \textsf{idxlayout} packages, as well as classes like \textsf{memoir}. On line~1 we define the \cmd{\Endbreak} macro that will break the column after the end of an index entry.
%
% \begin{quote}\small
-% \StartNum
-% \begin{verbatim}
-%\newcommand*{\EndBreak}[1]{#1\newpage}
-%\makeatletter
-%\newcommand*{\MidBreak}[1]{#1\newpage\@gobble}
-%\makeatother\end{verbatim}
+% |\newcommand*{\EndBreak}[1]{#1\newpage}|
% \end{quote}
%
-% Using \cmd{\MidBreak} to insert a break into the middle of an index entry does work to some extent, but what it does is quite sketchy and error-prone. We avoid using it for these reasons, but we just wanted to show that it can be done.
-%
-% Instead, we use \cmd{\EndBreak} after the last page in a given entry. This method works for manual index entries and for the \textsf{nameauth} macros. If all instances of \cmd{\Name\{Some, Name\}} on page 18 have the same tag, there will be no duplicate page entries, hyperlinks will work, and the index will break as indicated:
+% We use \cmd{\EndBreak} after the last page in a given entry. This method works for both manual index entries and for the \textsf{nameauth} macros. If all instances of \cmd{\Name\{Some, Name\}} on the same page have that same index tag, there will be no duplicate page entries, hyperlinks will work, and the index will break as indicated:
%
-% \begin{quote}\footnotesize\MyStretch
+% \begin{quote}\footnotesize\smallstretch
% \begin{tabular}{p{0.055\textwidth}@{\ }p{0.4\textwidth}@{\ }l}\toprule
-% Page & Macro & Index Result\\\midrule
-% \rowcolor{grey}10 & \cmd{\Name\{Some, Name\}}\dotfill \hbox{} & Some Name, 10\\
-% \rowcolor{grey} & \cmd{\index\{Topic\}}\dotfill \hbox{} & Topic, 10\\
+% Page & Macro & Index Result\\
+% \rowcolor{nagrey}10 & \cmd{\Name\{Some, Name\}}\dotfill \hbox{} &
+% Some Name, 10\\
+% \rowcolor{nagrey} & \cmd{\index\{Topic\}}\dotfill \hbox{} &
+% Topic, 10\\
% 15 & \cmd{\Name\{Some, Name\}}\dotfill \hbox{} & Some Name, 10, 15\\
% & \cmd{\index\{Topic\}}\dotfill \hbox{} & Topic, 10, 15\\
-% \rowcolor{grey}18 & \cmd{\TagName\{Some, Name\textbar EndBreak\}\%} & \\
-% \rowcolor{grey} & \cmd{\Name\{Some, Name\}}\dotfill \hbox{} & Some Name, 10, 15, 18\meta{break}\\
-% \rowcolor{grey} & \cmd{\index\{Topic\textbar EndBreak\}}\dotfill \hbox{} & Topic, 10, 15, 18\meta{break}\\
+% \rowcolor{nagrey}18 & \cmd{\TagName\{Some, Name\textbar EndBreak\}\%} & \\
+% \rowcolor{nagrey} & \cmd{\Name\{Some, Name\}}\dotfill \hbox{} &
+% Some Name, 10, 15, 18\meta{break}\\
+% \rowcolor{nagrey} &
+% \cmd{\index\{Topic\textbar EndBreak\}}\dotfill \hbox{} &
+% Topic, 10, 15, 18\meta{break}\\\bottomrule
% \end{tabular}
% \end{quote}
%
% We do not have to supply an argument to \cmd{\EndBreak} because, as with the font switching example above, the page reference is implied.
%
-% We can intermix \textsf{nameauth} macros with manual index entries. We may need to look at the \texttt{idx} or \texttt{ind} files to craft matching entries on the page where the break occurs. Instead of using \cmd{\TagName}, we can do this:
+% We can intermix \textsf{nameauth} macros with manual index entries. We may need to look at the \texttt{idx} or \texttt{ind} files to craft matching entries on the page where the break occurs. Instead of using \cmd{\TagName}, we also can do this:
%
-% \begin{quote}\footnotesize\MyStretch
-% \begin{tabular}{p{0.055\textwidth}@{\ }p{0.4\textwidth}@{\ }l}
-% 18 & \cmd{\SkipIndex}\cmd{\Name\{Some, Name\}\%}\hfill\hbox{} & \\
-% & \cmd{\index\{Some Name\textbar EndBreak\}}\dotfill \hbox{} & Some Name, 10, 15, 18\meta{break}\\\bottomrule
+% \begin{quote}\footnotesize\smallstretch
+% \begin{tabular}{p{0.055\textwidth}@{\ }p{0.4\textwidth}@{\ }l}\toprule
+% Page & Macro & Index Result\\
+% \rowcolor{nagrey} 18 &
+% \cmd{\SkipIndex}\cmd{\Name\{Some, Name\}\%}\hfill\hbox{} & \\
+% \rowcolor{nagrey} &
+% \cmd{\index\{Some Name\textbar EndBreak\}}\dotfill \hbox{} &
+% Some Name, 10, 15, 18\meta{break}\\\bottomrule
% \end{tabular}
% \end{quote}
%
-% Results for manual entries may 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. All instances of \cmd{\index\{Some Name\textbar EndBreak\}} must fall on the same page.
+% Results for manual entries may vary, depending on what distribution of \LaTeX\ is being used and how old it is. Any name with active characters needs to be handled differently before 2018 than after 2018. All instances of \cmd{\index\{Some Name\textbar EndBreak\}} must fall on the same page.
+%
+% We do not\Warn\ recommend breaking an index entry in the middle. There are several web pages that discuss the topic of gobbling the commas that are generated when one wants to use macros to manipulate index entries. \href{https://tex.stackexchange.com/questions/86646/indexing-subentries-and-see-also}{\bfseries This page} and \href{https://tex.stackexchange.com/questions/231840/what-is-the-proper-use-of-several-seealso-in-the-same-index-entry-with-makeinde}{\bfseries this one} also share a number of viewpoints. A ``quick and dirty'' version corresponding to the \cmd{\EndBreak} macro above would be the one that follows:
+%
+% \begin{quote}\small
+% \begin{Verbatim}
+% \makeatletter
+% \newcommand*{\MidBreak}[1]{#1\newpage\@gobble}
+% \makeatother
+% \end{Verbatim}
+% \end{quote}
+%
+% Nevertheless, it is clear from some discussions that such macros can be rather fiddly at times and can produce unexpected results. One is advised to take caution when breaking index entries midway or otherwise modifying them in this manner.
+%
+% \subsection[Categories/Sub-entries]{Categories and Sub-entries}
+% \label{sec:CatSub}
+%
+% It is possible for indexes to have a structure of categories and sub-entries similar to the example outline below:
+%
+% \begin{itemize}
+% \item[] \meta{category 1}
+% \begin{itemize}
+% \item[] \meta{name entry}
+% \begin{itemize}
+% \item[] \meta{name sub-entry 1}
+% \item[] \meta{name sub-entry 2}\dots
+% \end{itemize}
+% \item[] \meta{name entry}\dots
+% \end{itemize}
+% \item[] \meta{category 2}\dots
+% \end{itemize}
+%
+% In order to get names in \textsf{nameauth} to work with this structure, one must make use of both \cmd{\PretagName} and \cmd{\TagName}. For example, to sort a name under \meta{category}, one must use, e.g.:
+%
+% \begin{SyntaxBox}
+% \cmd{\PretagName[}\meta{FNN}\texttt{]\{}\meta{SNN}\texttt
+% {\}\{}\meta{category 1}\texttt{!}\meta{SNN}\texttt
+% {, }\meta{FNN}\texttt{\}}
+% \end{SyntaxBox}
+%
+% Whenever one wants to generate a sub-entry for a name, one can use \cmd{\TagName} to create that sub-entry when needed via, e.g.:
+%
+% \begin{SyntaxBox}
+% \cmd{\TagName[}\meta{FNN}\texttt{]\{}\meta{SNN}\texttt
+% {\}\{!}\meta{name sub-entry 1}\texttt{\}}
+% \end{SyntaxBox}
+%
+% One is not restricted to Western or non-Western name arguments; the boxes above are meant just to show the basic tag formats.
+%
+% One could use \Warn\cmd{\TagName} to change to another sub-entry or the default tag as needed, or use \cmd{\UntagName} to remove the tag. If a sub-entry contains a cross-reference via \cmd{\IndexRef}, it is necessary to follow that with \cmd{\IncludeName*} to permit any further page references in other sub-entries or the main name entry. Below we demonstrate how one would implement sub-entries using index tags in a normal \LaTeX\ document. We cannot show categories when using \texttt{gind.ist}.
+%
+% Categories higher than names are handled by \cmd{\PretagName}. Categories lower in the hierarchy are handled by \cmd{\TagName}. It is best practice to have three or less levels of categories in an index. Two levels are more common. Using such levels also depends on the index style and formatting files.
+% \JustIndex\Wash \JustIndex\Ike
+%
+% \ifdefined\NameauthDoTestFiles \edef\NameauthTestFile{test07_02.tex}\else
+% \edef\NameauthTestFile{\jobname.tmp}\fi
+%
+% \begin{VerbatimOut}{\NameauthTestFile}
+% \documentclass{article}
+% \input{compat.tex} % Included with nameauth; needed only if
+% % compiling on multiple TeX distros or LaTeX engines.
+% \usepackage{makeidx}
+% \usepackage{nameauth}
+% \makeindex
+% \usepackage[a6paper,landscape,left=1cm,right=1cm]{geometry}
+%
+% \newcommand*{\EndBreak}[1]{#1\newpage}
+%
+% % Sort these names under: US Presidents.
+% \PretagName[George]{Washington}{US Presidents!Washington, George}
+% \PretagName[Abraham]{Lincoln}{US Presidents!Lincoln, Abraham}
+%
+% % Sort these names under: Philosophers.
+% \PretagName{Aristotle}{Philosophers!Aristotle}
+% \PretagName{Plato}{Philosophers!Plato}
+%
+% % Sort these names under: Black Americans, famous.
+% \PretagName[Frederick]{Douglass}
+% {Black Americans, famous!Douglass, Frederick}
+% \PretagName[Martin Luther]{King, Jr.}
+% {Black Americans, famous!King, Martin Luther, Jr.}
+%
+% % Sort these names under: Europeans, historical.
+% \PretagName{\AE thelred, II}{Europeans, historical!Aethelred 2}
+% \PretagName[Hernando]{de Soto}
+% {Europeans, historical!de Soto, Hernando}
+%
+% % This is not a sub-category.
+% \TagName[George S.]{Patton, Jr.}{, general}
+%
+% \begin{nameauth}
+% \< Wash & George & Washington & >
+% \< Aris & & Aristotle & >
+% \< Plato & & Plato & >
+% \< Aeth & & \AE thelred, II & >
+% \< Sun & & Sun, Yat-sen & >
+% \< Linc & Abraham & Lincoln & >
+% \< MLK & Martin Luther & King, Jr. & >
+% \< Soto & Hernando & de Soto & >
+% \< Goethe & J.W. von & Goethe & >
+% \< Patton & George S. & Patton, Jr. & >
+% \< Ike & Dwight D. & Eisenhower & >
+% \end{nameauth}
+%
+% \begin{document}
+% \small
+%
+% \section{Famous Black Americans}
+%
+% \Name[Frederick]{Douglass} rose to eminence by sheer force of
+% character and talents that neither slavery nor caste
+% proscription could crush. Circumstances made
+% \Name[Frederick]{Douglass} a slave, but they could not prevent
+% him from becoming a freeman and a leader among mankind.\\
+%
+% We also celebrate \MLK, then \MLK.
+%
+% \section{Patres Patriae}
+%
+% We mention President \Wash; again, \Wash.
+% Family and close friends called him \SWash.\\
+%
+% \TagName[George]{Washington}{!as general}
+% We can reminisce about \LWash[General].
+% \UntagName[George]{Washington}
+%
+% When speaking of \Linc, we can refer to \LLinc[Abe].
+%
+% \section{Philosophers}
+%
+% Among philosophers we consider \Plato\ and \Aris.
+%
+% \section{Historical Figures}
+%
+% \TagName{Sun, Yat-sen}{|EndBreak}
+% We ponder about \Aeth, then \Aeth.
+% We speak of \Sun, then \Sun.
+% We note \Soto, then just \Soto.
+% \CapThis\Soto{} starts a sentence.
+%
+% \section{Further Discussion}
+%
+% \TagName[George]{Washington}{!as general}
+% \TagName[Dwight D.]{Eisenhower}{!as general}
+% \LWash, \LPatton, and \LIke\ were high-ranking generals.\\
+%
+% \TagName[Dwight D.]{Eisenhower}{!as president}
+% \UntagName[George]{Washington}
+% \Wash\ and \Ike\ also were US presidents.
+%
+% % Instead of pre-tagging Ike we do the following:
+% \index{US Presidents!other|see{Eisenhower, Dwight D., president}}
+%
+% \small
+% \printindex
+% \end{document}
+% \end{VerbatimOut}
+%
+% \begin{quote}\small
+% \VerbatimInput[gobble=0]{\NameauthTestFile}
+% \end{quote}
+%
+% Below we show only the index, which is page three of the document.
+% A few notable features include:
+%
+% \begin{itemize}
+% \item \Patton\ uses a regular index tag instead of a subcategory.
+% If one cannot use a subcategory due to layout constraints, regular
+% index tags are a good substitute.
+% \item \Ike\ illustrates multiple subcategories for a name. A
+% cross-reference from a sub-entry of US presidents points to him.
+% \item \Wash\ illustrates having both a super-category and a subcategory.
+% \item \Ike, \Patton, and \Sun\ are not sorted under categories. The
+% other names are sorted under categories.
+% \end{itemize}\smallskip
+% \JustIndex\MLK \JustIndex\Doug \JustIndex\Aeth \JustIndex\Soto
+% \JustIndex\Aris \JustIndex\Plato \JustIndex\Linc
+%
+% \begin{tcolorbox}[colback=white]
+% \IfFileExists{cat01.pdf}{\includegraphics[scale=0.85]{cat01.pdf}}
+% {\hbox{\vbox to 8cm{\hbox{\hfill}}}}
+% \end{tcolorbox}
+% \JustIndex\Wash \JustIndex\Ike
+% \medskip
+%
+% \IndexWarnTerse
%
% \ReturnLink
+%
+% \begin{Quote}{\Name[Publius]{Vegetius Renatus}, \textit{De re militari}}
+% Igitur qui desiderat pacem, praeparet bellum.\\
+% (Accordingly, the person who would desire peace prepares for war.)
+% \end{Quote}
+%
% \newpage
%
-% \subsection{``Text Tags''}
-% \label{sec:TextTags}
+% \section{Name Data Tags}
+% \label{sec:DataTags}
%
% \DescribeMacro{\NameAddInfo}
-% 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{
-% \begin{tabular}{l}
-% {\Large\strut}\cmd{\NameAddInfo}\oarg{FNN}\marg{SNN|,| Affix}\oarg{Alternate}\marg{tag}\\
-% \end{tabular}
-% }
-% \end{quote}\PatInfo{\ShowPattern[George]{Washington}!DB\break \ShowPattern[George]{Washington}!MN}
+% All valid names in \textsf{nameauth} can have data tags; no restrictions exist. Unlike index tags, name data tags are not printed automatically with every name managed by \textsf{nameauth}. Sections~\ref{sec:NameTests} and~\ref{sec:DataTagHooks} have more examples. The macro is \cmd{\long}, allowing for some complexity in the \meta{tag} argument:
+%
+% \begin{SyntaxBox}
+% \cmd{\NameAddInfo}\oarg{FNN}\marg{SNN|,| Affix}\oarg{Alternate}\marg{tag}
+% \end{SyntaxBox}
%
-% 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
+% \vspace{2ex}
+% \PatInfo{\ShowPattern[George]{Washington}!DB\break
+% \ShowPattern[George]{Washington}!MN}
+% \vspace{-2ex}
+% For example, |\NameAddInfo[George]{Washington}{(1732--99)}| \NameAddInfo[George]{Washington}{(1732--99)} makes a data tag but does not print whenever \Wash\ \cmd{\Wash} is used. The data tag is a hidden macro that needs to be displayed using another helper macro keyed to that name, which we discuss below.\medskip
%
% \DescribeMacro{\NameQueryInfo}
-% 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{
-% \begin{tabular}{l}
-% {\Large\strut}\cmd{\NameQueryInfo}\oarg{FNN}\marg{SNN|,| Affix}\oarg{Alternate}\\
-% \end{tabular}
-% }
-% \end{quote}
+% To print the data tag macro associated with a name, we use \cmd{\NameQueryInfo}, a helper macro that uses the name arguments to display the hidden macro associated with that name in the name info data set:
+%
+% \begin{SyntaxBox}
+% \cmd{\NameQueryInfo}\oarg{FNN}\marg{SNN|,| Affix}\oarg{Alternate}
+% \end{SyntaxBox}
+%
+% Since we already created a data tag for \LWash, we will retrieve that data now: \cmd{\NameQueryInfo[George]\{Washington\}} expands to \NameQueryInfo[George]{Washington}. Of course, it may seem tedious to retrieve this information by hand. In Section~\ref{sec:DataTagHooks} and thereafter we show how one can automate the retrieval of data tags using formatting hooks, Yet therein also lies a caution:
+%
+% \begin{InfoBox}[Caution for Using \cmd{\noexpand}]
+% When using a formatting hook definition based on the recommended template (Section~\ref{sec:DataTemp}), one can use \cmd{\noexpand} in arguments for \cmd{\NameAddInfo}, \cmd{\NameQueryInfo}, and \cmd{\NameClearInfo} without restriction.\medskip
+%
+% When using designs based on older templates, using \cmd{\noexpand} may cause \cmd{\NameQueryInfo} to print nothing if one uses the basic interface. Using the quick interface will work as expected.
+% \end{InfoBox}
+%
+% One can insert a space at the start of a data tag; use signs like asterisks, daggers, and the like; and even create footnotes, such as the source for footnote \addtocounter{footnote}{1}\arabic{footnote}\addtocounter{footnote}{-1} on the following page:
+%
+% \begin{VerbatimOut}{\jobname.tmp}
+% \NameAddInfo[Ulysses S.]{Grant}
+% {eighteenth US president (1869--1877)}
+% \NameAddInfo[Schuyler]{Colfax}
+% {\footnote{\Name[Schuyler]{Colfax} was the seventeenth US
+% vice-president during the first term (1869--73) of
+% \Name*[Ulysses S.]{Grant}, \NameQueryInfo[Ulysses S.]{Grant}.}}
+%
+% Remember \Name[Schuyler]{Colfax}?\NameQueryInfo[Schuyler]{Colfax}
+% Derived from the same origin as ``scholar'', this name can occur
+% as ``Skylar'' for girls and ``Skyler'' for boys.
+% \end{VerbatimOut}
%
-% \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}|\PatInfo{\ShowPattern[George]{Washington}!DB\break \ShowPattern[Ulysses S.]{Grant}!DB\break \ShowPattern[Schuyler]{Colfax}!DB\break \ShowPattern[Schuyler]{Colfax}!MN\break \ShowPattern[Ulysses S.]{Grant}!MN} 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}|
+% \vspace{3.5ex}
+% \PatInfo{\ShowPattern[George]{Washington}!DB\break
+% \ShowPattern[Ulysses S.]{Grant}!DB\break
+% \ShowPattern[Schuyler]{Colfax}!DB\break
+% \ShowPattern[Schuyler]{Colfax}!MN\break
+% \ShowPattern[Ulysses S.]{Grant}!MN}
+% \vspace{-3.5ex}
+% \VerbatimInput[gobble=0]{\jobname.tmp}
+%
+% \input{\jobname.tmp}
% \end{quote}
%
-% One can\Warn{} nest ``text tags'' and have them call each other. Therefore, one must protect against a stack overflow by using Boolean flags to stop the recursion:
-% \begin{quote}\small
+% The previous\Warn{} example cannot be used in a formatting hook (Section~\ref{sec:DataTagHooks}). Within the formatting hooks, one is in a ``locked path'' that will not permit the ``re-entrant'' call to a naming macro. This is necessary to prevent a stack overflow. Were this example called in a formatting hook, \Name*[Ulysses S.]{Grant} would not print, although the data tag for \Name[Ulysses S.]{Grant} would print because it is called separately.
+%
+% One can\Warn{} nest data tags and have them call each other. Therefore, one must protect against a stack overflow by using Boolean flags and conditional statements. In the minimal working example below, \cmd{\NameQueryInfo} calls a tag that sets a Boolean flag true, which causes the \emph{other} tag called later to stop the potential for recursion and exit.
+%
+% \begin{VerbatimOut}{\jobname.tmp}
% \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
+% \NameAddInfo{A}
+% {\Atrue A \ifB Stop \else \NameQueryInfo{B} \fi \Afalse}
+% \NameAddInfo{B}
+% {\Btrue B \ifA Stop \else \NameQueryInfo{A} \fi \Bfalse}
+% \begin{itemize}
+% \item \NameQueryInfo{A}
+% \item \NameQueryInfo{B}
+% \end{itemize}
+% \end{VerbatimOut}
+%
+% \begin{quote}\small
+% \VerbatimInput[gobble=0]{\jobname.tmp}
%
-% \MyStretch\begin{tabular}{@{}l@{ \(\rightarrow\) }l}
-% \cmd{\NameQueryInfo\{A\}} & \NameQueryInfo{A}\\
-% \cmd{\NameQueryInfo\{B\}} & \NameQueryInfo{B}\\
-% \end{tabular}
+% \input{\jobname.tmp}
% \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}
-% \fbox{
-% \begin{tabular}{l}
-% {\Large\strut}\cmd{\NameClearInfo}\oarg{FNN}\marg{SNN|,| Affix}\oarg{Alternate}\\
-% \end{tabular}
-% }
-% \end{quote}
+% \cmd{\NameAddInfo} will replace one data tag with another data tag, but it does not delete a data tag. That is the role of \cmd{\NameClearInfo}. The syntax is:
%
-% After using\PatInfo{\ShowPattern[George]{Washington}!DB} |\NameClearInfo[George]{Washington}|\NameClearInfo[George]{Washington}, the next attempt to query the tag |\NameQueryInfo[George]{Washington}| will produce nothing\NameQueryInfo[George]{Washington}.
+% \begin{SyntaxBox}
+% \cmd{\NameClearInfo}\oarg{FNN}\marg{SNN|,| Affix}\oarg{Alternate}
+% \end{SyntaxBox}
+%
+% We now revisit \LWash\ and his associated data tag. \PatInfo{\ShowPattern[George]{Washington}!DB}
+%
+% \begin{VerbatimOut}{\jobname.tmp}
+% The data tag is: \fbox{\NameQueryInfo[George]{Washington}}\quad
+% Clearing data.\NameClearInfo[George]{Washington}\quad
+% The data tag is empty: \fbox{\NameQueryInfo[George]{Washington}}
+% \end{VerbatimOut}
+%
+% \begin{quote}\small
+% \VerbatimInput[gobble=0]{\jobname.tmp}
+%
+% \input{\jobname.tmp}
+% \end{quote}
%
% \ReturnLink
+%
% \newpage
%
+% \section[Formatting and Decisions]{Basic Formatting and Name Decisions}
+% \label{sec:FormatChoice}
+%
+% Since both syntactic name forms and formatting interact heavily with the presence and absence of name patterns, we include them together in one section.
+%
% \subsection{Basic Formatting}
% \label{sec:Formatting}
%
-% Below are color-coded forms and formats of names, showing most (but not all) of the variations that can occur. The next several sections will explain such variations (and quite a few more) in detail:\medskip
-%
-% \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\\
-% & (cf. Section~\ref{sec:NameControl})\\
-% \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{\L}\meta{macro}\\ \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}
-% \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}
-% \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\\
-% & (cf. Section~\ref{sec:NameControl})\\
-% \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{\L}\meta{macro}\\ \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}
-% \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}
-% \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}
-% \newpage
+% This section offers a brief overview; Section~\ref{sec:AdvancedFormat} goes into great detail. Even when using the default options for \textsf{nameauth} wherein no formatting occurs, we can observe syntactic changes to names:
%
-% Since\Info{Naming system\break behavior} formatting is related closely to name usage (the existence of a name control sequence), we use similar descriptors for these distinct topics. A name's classification, elements, and control sequence are determined in the syntactic element layer. A name's displayed form is determined in the name display layer. Finally, a name's typographic form is determined by the format hook dispatcher and formatting hooks. Here is the general layout:
-%
-% \begin{tcolorbox}[colframe=naslate,colback=white,adjusted title={\bfseries Syntactic Element Layer}]
-% \cmd{\@nameauth@Parse}: Determine name category, capitalization, punctuation, elements to be used, and pass on to\dots
-% \begin{tcolorbox}[colframe=nablue,adjusted title={\sffamily\bfseries Name Display Layer}]
-% \cmd{\@nameauth@NonWest}: Consult rules, construct displayed form.\\
-% \cmd{\@nameauth@West}: Consult rules, construct displayed form.\\
-% \cmd{\@nameauth@Form}: ``Magic Eight Ball'' of rules for name forms. Includes checking if a name control sequence exists, checking which is the calling macro, and so on.
-% Pass the information to\dots
-% \begin{tcolorbox}[colframe=nared,colback=white,adjusted title={\sffamily\bfseries Format Hook Dispatcher}]
-% \cmd{\@nameauth@Hook}: Check the name to be printed for a final full stop. Check which naming system we are using. Call a formatting hook to print the name in the text.
-% \end{tcolorbox}
-% \end{tcolorbox}
-% \cmd{\@nameauth@Parse}: Instantiate name control sequence.
+% \begingroup
+% \renewcommand\NamesFormat{}
+% \renewcommand\MainNameHook{}
+% \renewcommand\FrontNamesFormat{}
+% \renewcommand\FrontNameHook{}
+% \begin{tcolorbox}[colframe=naslate,colback=white,
+% adjusted title={\hfil Syntactic Changes;^^A
+% No Formatting/Post-Processing}]\centering
+% \begin{tabular}{llll}\toprule
+% First & Later & First name & Later name\\\midrule
+% \cmd{\Patton} & \cmd{\Patton} & \ForgetThis\Patton & \Patton\\
+% \cmd{\LPatton} & \cmd{\LPatton} & \ForgetThis\LPatton &
+% \LPatton\\
+% \cmd{\SPatton} & \cmd{\SPatton} & \ForgetThis\SPatton &
+% \SPatton\\\midrule
+% \cmd{\Yamt} & \cmd{\Yamt} & \ForgetThis\Yamt & \Yamt\\
+% \cmd{\LYamt} & \cmd{\LYamt} & \ForgetThis\LYamt & \LYamt\\
+% \cmd{\SYamt} & \cmd{\SYamt} & \ForgetThis\SYamt & \SYamt\\\bottomrule
+% \end{tabular}
% \end{tcolorbox}
+% \endgroup
+%
+% We can add formatting to these syntactic changes. In its basic form, formatting is typographic post-processing. In its advanced form, formatting locally affects also the syntactic forms of names while leaving index entries undisturbed.
+%
+% Many books are structured with front matter that includes a table of contents, foreword, introductory material or survey material, and other instructive content that is not part of the main matter. The \textsf{nameauth} package has separate syntax and formatting system for front matter (\texttt{!NF}) and main matter (\texttt{!MN}). These formatting systems are linked to the existence of a name control pattern.
%
-% The different forms and formats seen on the previous page are a result of all three layers interacting. Sections~\ref{sec:Formatting} and~\ref{sec:AltFormat} (with its subsections) deal mostly with the format hook dispatcher and formatting hooks, but they also interact with the name display layer. Section~\ref{sec:NameDecisions} (with its subsections) deals mostly with the syntactic element and name display layers, but also in some cases with the format hook dispatcher and formatting hooks. The following concepts flow from this layout and affect both form and formatting:
% \begin{itemize}
-% \item \textbf{Name first use}
+% \item Name first use
% \begin{itemize}
% \item No name control sequence exists.
% \item A name is printed with its long form (default).
% \item The ``first-use'' formatting hook is used (default).
-% \item When the name is printed, a name control sequence is created.
+% \item After the name is printed, a name control sequence is created.
% \end{itemize}
-% \item \textbf{Name subsequent use}
+% \item Name subsequent use
% \begin{itemize}
% \item A name control sequence already exists.
% \item A name is printed using a shorter form (default).
@@ -3422,9 +5343,9 @@ and version 1.3 or later is part of all distributions of LaTeX version
% \DescribeMacro{\NamesActive}
% Independent ``main-matter'' and ``front-matter'' systems are used to format first and subsequent name uses.
% \DescribeMacro{\NamesInactive}
-% \cmd{\NamesInactive} and the \texttt{frontmatter} option enable the front-matter system. \cmd{\NamesActive}
-% switches names to the main-matter system. The \texttt{mainmatter} option is the default setting for names.
-% \medskip
+% \cmd{\NamesInactive} and the \texttt{frontmatter} option enable the front-matter system. \cmd{\NamesActive} switches names to the main-matter system. The \texttt{mainmatter} option is the default setting for names.
+%
+% Especially with the macros that deal with formatting, the naming scheme is unfortunate because it involved some groping in the dark regarding the concepts.\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
%
@@ -3433,2510 +5354,4378 @@ and version 1.3 or later is part of all distributions of LaTeX version
% \DescribeMacro{\MainNameHook}
% \cmd{\MainNameHook} for subsequent uses. The front-matter system uses \cmd{\FrontNamesFormat}
% \DescribeMacro{\FrontNamesFormat}
-% for first uses and \cmd{\FrontNameHook} for subsequent uses. The \texttt{alwaysformat}
+% for first uses and \cmd{\FrontNameHook} for subsequent uses. The \texttt{alwaysformat}
% \DescribeMacro{\FrontNameHook}
-% option causes only \cmd{\NamesFormat} and \cmd{\FrontNamesFormat} to be used.\footnote{The names of these macros grew from \cmd{\NamesFormat}, originally the only formatting hook.}
-% Section~\ref{sec:NamePatterns} shows how name control sequences are keyed either to the main-matter system or to the front-matter system.
-% The two formatting systems are distinct, useful for separate document elements. We color-code them below:\smallskip
-%
-% \begin{center}\small\vspace{2ex}\PatInfo{\textrm{front-matter}\hfill\break \ShowPattern[Rudolph]{Carnap}!NF\break \ShowPattern[Nicolas]{Malebranche}!NF\break \textrm{main-matter}\hfill\break \ShowPattern[Rudolph]{Carnap}!MN\break \ShowPattern[Nicolas]{Malebranche}!MN}\vspace{-2ex}\MyStretch
+% option causes only \cmd{\NamesFormat} and \cmd{\FrontNamesFormat} to be used. Since the formatting hooks always are defined when using \textsf{nameauth}, one must use \cmd{\renewcommand} when changing their definitions.\footnote{The names of these macros grew from \cmd{\NamesFormat}, originally the only formatting hook.}
+% Section~\ref{sec:NamePatterns} shows how name control sequences are keyed either to the main-matter system or to the front-matter system. The two formatting systems are distinct, useful for separate document elements. We color-code them and ``forget'' any previous name uses: \medskip
+%
+% \ForgetName[Rudolph]{Carnap}
+% \vspace{4ex}
+% \PatInfo{\textrm{front-matter}\hfill\break
+% \ShowPattern[Rudolph]{Carnap}!NF\break
+% \ShowPattern[Nicolas]{Malebranche}!NF\break
+% \textrm{main-matter}\hfill\break
+% \ShowPattern[Rudolph]{Carnap}!MN\break
+% \ShowPattern[Nicolas]{Malebranche}!MN}
+% \vspace{-4ex}
+% \begin{tcolorbox}[colframe=red,colback=white,
+% adjusted title={\hfil Front-matter system: \cmd{\NamesInactive}}]
% \NamesInactive
-% \begin{tabular}{ll}\toprule
-% Front-matter system: & \cmd{\NamesInactive}\\\midrule
-% \rowcolor{grey}|\Name[Rudolph]{Carnap}| & \Name[Rudolph]{Carnap}\\
+% \begin{tabular}{ll}
% |\Name[Rudolph]{Carnap}| & \Name[Rudolph]{Carnap}\\
-% \rowcolor{grey}|\Name[Nicolas]{Malebranche}| & \Name[Nicolas]{Malebranche}\\
-% |\Name[Nicolas]{Malebranche}| & \Name[Nicolas]{Malebranche}\\\bottomrule
-% \end{tabular}\\[4ex]
+% |\Name[Rudolph]{Carnap}| & \Name[Rudolph]{Carnap}\\
+% |\Name[Nicolas]{Malebranche}| & \Name[Nicolas]{Malebranche}\\
+% |\Name[Nicolas]{Malebranche}| & \Name[Nicolas]{Malebranche}\\
+% \end{tabular}
+% \end{tcolorbox}
+% \medskip
%
+% \begin{tcolorbox}[colframe=blue,colback=white,
+% adjusted title={\hfil Main-matter system: \cmd{\NamesActive}}]
% \NamesActive
-% \begin{tabular}{ll}\toprule
-% Main-matter system: & \cmd{\NamesActive}\\\midrule
-% \rowcolor{grey}|\Name[Rudolph]{Carnap}| & \Name[Rudolph]{Carnap}\\
+% \begin{tabular}{ll}
+% |\Name[Rudolph]{Carnap}| & \Name[Rudolph]{Carnap}\\
% |\Name[Rudolph]{Carnap}| & \Name[Rudolph]{Carnap}\\
-% \rowcolor{grey}|\Name[Nicolas]{Malebranche}| & \Name[Nicolas]{Malebranche}\\
-% |\Name[Nicolas]{Malebranche}| & \Name[Nicolas]{Malebranche}\\\bottomrule
+% |\Name[Nicolas]{Malebranche}| & \Name[Nicolas]{Malebranche}\\
+% |\Name[Nicolas]{Malebranche}| & \Name[Nicolas]{Malebranche}\\
% \end{tabular}
-% \end{center}
+% \end{tcolorbox}
+% \medskip
%
-% We achieved that color coding using the following macros and the \textsf{xcolor} package:
+% We used the \textsf{xcolor} package with the following macros:
% \begin{quote}\small
-% \StartNum
-% \begin{verbatim}
-%\renewcommand*\FrontNamesFormat[1]{\color{red}\sffamily #1}
-%\renewcommand*\FrontNameHook[1]{\color{darkgray}\sffamily #1}
-%\renewcommand*\NamesFormat[1]{\color{blue}\sffamily #1}
-%\renewcommand*\MainNameHook[1]{\sffamily #1}\end{verbatim}
+% \begin{Verbatim}
+% \renewcommand*\FrontNamesFormat[1]{\color{red}\sffamily #1}
+% \renewcommand*\FrontNameHook[1]{\color{darkgray}\sffamily #1}
+% \renewcommand*\NamesFormat[1]{\color{blue}\sffamily #1}
+% \renewcommand*\MainNameHook[1]{\sffamily #1}
+% \end{Verbatim}
% \end{quote}
%
% \DescribeMacro{\ForceName}
-% We show examples of \cmd{\ForceName} in Sections~\ref{sec:NameControl}, \ref{sec:AKA}, and~\ref{sec:Hooksii}. Use this prefix macro to force ``first use'' formatting for the next \cmd{\Name}, etc.,\Version{3.1} but without changing any name control sequences. Thus:
+% We show examples of \cmd{\ForceName} in Sections~\ref{sec:NameControl}, \ref{sec:DataTagHooks}, and~\ref{sec:AKA}. Use this prefix macro to force ``first use'' formatting for the next \cmd{\Name}, etc., but without deleting any name control sequences. Thus:
+%
% \begin{quote}\small
-% \hphantom{\cmd{\ForceName}}\PatInfo{\ShowPattern[Rudolph]{Carnap}!MN}\cmd{\Name[Rudolph]\{Carnap\}} \Name[Rudolph]{Carnap}\\
-% \cmd{\ForceName}\cmd{\Name[Rudolph]\{Carnap\}} \ForceName\Name[Rudolph]{Carnap}
+% \hphantom{\cmd{\ForceName}}^^A
+% \PatInfo{\ShowPattern[Rudolph]{Carnap}!MN}^^A
+% \cmd{\Name[Rudolph]\{Carnap\}} \Name[Rudolph]{Carnap}\\
+% \cmd{\ForceName}\cmd{\Name[Rudolph]\{Carnap\}}
+% \ForceName\Name[Rudolph]{Carnap}
% \end{quote}
%
% Below\Info{\texttt{alwaysformat}} we simulate \texttt{alwaysformat} via package internals:
+%
% \makeatletter\@nameauth@AlwaysFormattrue\makeatother%
% \ForgetName[M.T.]{Cicero}\ForgetName{Elizabeth, I}%
% \begin{itemize}
-% \item Front matter: \NamesInactive \Name[Albert]{Einstein}, \Name[Albert]{Einstein}; \Name{Confucius}, \Name{Confucius}.\\ Patterns: \texttt{\ShowPattern[Albert]{Einstein}!NF \ShowPattern{Confucius}!NF}
-% \item Main matter: \NamesActive \Name[M.T.]{Cicero}, \Name[M.T.]{Cicero}; \Name{Elizabeth, I}, \Name{Elizabeth, I}.\\ Patterns: \texttt{\ShowPattern[M.T.]{Cicero}!MN \ShowPattern{Elizabeth, I}!MN}
+% \item Front matter: \NamesInactive \Name[Albert]{Einstein},
+% \Name[Albert]{Einstein}; \Name{Confucius}, \Name{Confucius}.\\
+% Patterns: \texttt{\ShowPattern[Albert]{Einstein}!NF
+% \ShowPattern{Confucius}!NF}
+% \item Main matter: \NamesActive \Name[M.T.]{Cicero}, \Name[M.T.]{Cicero};
+% \Name{Elizabeth, I}, \Name{Elizabeth, I}.\\
+% Patterns: \texttt{\ShowPattern[M.T.]{Cicero}!MN
+% \ShowPattern{Elizabeth, I}!MN}
% \end{itemize}
% \makeatletter\@nameauth@AlwaysFormatfalse\makeatother
+%
% \newpage
%
-% The name parser\Info{Hook caveats} determines what syntactic name elements exist and how they are constituted. It passes that information to macros that determine the form of non-Western or Western names to be displayed. They in turn call the format hook dispatcher for post-processing, which calls the formatting hooks using the pattern:
+% The internal name parser\Info{Hook caveats} determines what syntactic name elements exist and how they are constituted. It passes that information to macros that determine the form of non-Western or Western names to be displayed. They in turn call the format hook dispatcher for post-processing, which calls the formatting hooks using the pattern:
+%
% \begin{quote}\small
% \cmd{\bgroup}\meta{Hook}\texttt{\{\#1\}}\cmd{\egroup}.
% \end{quote}
-% Thus, one can create hooks that take either no arguments or one argument, e.g.:
-% \begin{quote}\small\MyStretch
+%
+% One can create formatting hooks that take either no argument or one argument. Since the formatting hooks are already defined, one must not use \cmd{\newcommand} to create new hooks. Instead, use \cmd{\renewcommand} e.g.:
+%
+% \begin{quote}\small
% \cmd{\renewcommand*}\cmd{\NamesFormat\{}\meta{content}\texttt{\}}\\
% \cmd{\renewcommand*}\cmd{\NamesFormat[1]\{}\meta{content}\texttt{\}}
% \end{quote}
-% A hook that takes one argument can discard it and invoke \cmd{\NameParser} (Page~\pageref{page:Intermediate}). Due to the dispatcher design, both the following achieve the same effect, giving the choice of non-robust and robust forms:
-% \begin{quote}\small\MyStretch
+%
+% A hook that takes one argument can use, change, or discard it and invoke \cmd{\NameParser} (Section~\ref{sec:SpecialUses}). Due to package design using local scope, both the following achieve exactly the same effect:
+%
+% \begin{quote}\small
% \cmd{\renewcommand*}\cmd{\NamesFormat\{}\cmd{\itshape}\texttt{\}}\\
% \cmd{\renewcommand*}\cmd{\NamesFormat\{}\cmd{\textit}\texttt{\}}
% \end{quote}
-%
-% The\Info{Applied to\break footnotes} independent systems of names work with footnotes. Names in the body text, such as \Harnack, normally affect name forms in the footnotes.\footnote{We have \Harnack\ from \cmd{\Harnack} instead of \ForgetThis\Harnack.}
+%
+% \subsection{Application: Footnotes}
+%
+% The independent systems of names work with footnotes. Names in the body text, such as \ForgetThis\Harnack\ (later ennobled to \LHarnack[Adolf von]), normally affect name forms in the footnotes.\footnote{We have \Harnack\ from \cmd{\Harnack} instead of \ForgetThis\Harnack.}
% In footnote \arabic{footnote} \cmd{\MainNameHook} is called instead of \cmd{\NamesFormat} because \Harnack\ already had occurred above. We can use the front-matter system to change that:
+%
+% \begin{VerbatimOut}{\jobname.tmp}
% \makeatletter
% \let\@oldfntext\@makefntext
% \long\def\@makefntext#1{\NamesInactive\@oldfntext{#1}\NamesActive}
% \makeatother
-% \begin{quote}\small\leavevmode\PatInfo{\ShowPattern[Adolf]{Harnack}!MN\break \ShowPattern[Adolf]{Harnack}!NF}\vspace{-5ex}
-% \StartNum
-% \begin{verbatim}
-%\begingroup
-%\makeatletter
-%\let\@oldfntext\@makefntext
-%\long\def\@makefntext#1{\NamesInactive\@oldfntext{#1}\NamesActive}
-%\makeatother\end{verbatim}
+% \end{VerbatimOut}
+%
+% \begin{quote}\small
+% \vspace{4ex}
+% \PatInfo{\ShowPattern[Adolf]{Harnack}!MN\break
+% \ShowPattern[Adolf]{Harnack}!NF}
+% \vspace{-4ex}
+% \VerbatimInput[gobble=0]{\jobname.tmp}
% \end{quote}
+% \input{\jobname.tmp}
%
% When we create another footnote, we see very different results.\footnote{We have \Harnack\ from \cmd{\Harnack}, then \Harnack.}
-% Footnote \arabic{footnote} shows a different result. One can synchronize the two systems with \cmd{\ForgetThis} and \cmd{\SubvertThis} (Section~\ref{sec:NameControl}). Below we revert footnotes with:
+% Footnote \arabic{footnote} shows the first use of a name because it is the first use in the front-matter system. One can synchronize the two systems with \cmd{\ForgetThis} and \cmd{\SubvertThis} (Section~\ref{sec:NameControl}). Below we revert footnotes with:
+%
+% \begin{VerbatimOut}{\jobname.tmp}
% \makeatletter
% \let\@makefntext\@oldfntext
% \makeatother
+% \end{VerbatimOut}
+%
% \begin{quote}\small
-% \ContinueNum
-% \begin{verbatim}
-% \makeatletter
-% \let\@makefntext\@oldfntext
-% \makeatother\end{verbatim}
+% \VerbatimInput[gobble=0]{\jobname.tmp}
% \end{quote}
-% \ReturnLink
-% \vfill
-%
-% \begingroup^^A Local format hook redefinition
-% \AltFormatActive
-% \begin{verse}
-% Eyn Chriſten menſch iſt eyn freyer herr / über alle ding /\\
-% \qquad und niemande unterthan.\\
-% Eyn Chriſten menſch iſt eyn dienſtpar knecht aller ding\\
-% \qquad und yderman unterthan.\\[1ex]\hfill---\Luth, \textit{Von der Freiheit eines Christenmenschen}
-% \end{verse}
-% \newpage
+% \input{\jobname.tmp}
%
-% \subsection{Alternate Formatting}
-% \label{sec:AltFormat}
+% \begin{Quote}{\Name[Hubert H.]{Humphrey}, speech (26 March 1966)}
+% In real life, unlike in Shakespeare, the sweetness of the rose depends upon the name it bears. Things are not only what they are. They are, in very important respects, what they seem to be.
+% \end{Quote}
%
-% \noindent The\Info{In this section, the name patterns do not fit in the margin.} 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.
+% \newpage
%
-% We already saw the use of macros in name arguments for Roman names (page~\pageref{page:Romani}). We did not use alternate formatting there because we knew that we would not use an \meta{SNN}\texttt{,}\meta{Affix} pair; we would not use \cmd{\CapThis}; and we used \cmd{\noexpand} before the macros in the arguments.
+% \subsection{Making Name Decisions}
+% \label{sec:NameControl}
%
-% In larger contexts, however, these constraints might not hold. The following scenarios, especially where there is segmentation of input, can be problematic:
-% \begin{itemize}
-% \item Using a comma-delimited required name argument pair as the argument of a robust macro like \cmd{\textsc} will halt \LaTeX\ with errors. The \textsf{nameauth} macros will split that pair, which will break the robust macro:\\[1ex]
-% \bgroup\small\MyStretch\begin{tabular}{@{\qquad}ll}
-% Bad & \cmd{\Name\{}\cmd{\textsc\{}\meta{SNN}\texttt{,}\meta{Affix}\texttt{\}\}}\\
-% Good & \cmd{\Name\{}\cmd{\textsc\{}\meta{SNN}\texttt{\},}\cmd{\textsc\{}\meta{Affix}\texttt{\}\}}\\
-% \end{tabular}\egroup\\[1ex]
-% Not even alternate formatting can fix this issue; one simply must avoid the problem when encoding names.
-% \item Using \cmd{\CapThis} with a name whose leading element in any one argument is neither a letter nor an active Unicode character, such as a macro. This may work in normal formatting or it may fail, depending on the macro. Use alternate formatting to have \cmd{\CapThis} activate the alternate capitalization mechanism.
-% \item In a name argument, using a macro that contains a conditional statement can cause the macro to expand to different results. When such conditional changes occur, spurious results follow. Use \cmd{\noexpand} in the name arguments to fix this.
-% \end{itemize}
+% By default, the macros below produce global effects. They change both the \texttt{!MN} and \texttt{!NF} data sets (Section~\ref{sec:NamePatterns}). Those changes implicitly affect syntactic name forms, name formatting, index protection with respect to creating cross-references (Section~\ref{sec:IndexRef}), and the name testing macros (Section~\ref{sec:NameTests}).\medskip
%
-% \subsubsection{Basic Features}
-% \label{sec:AltBasic}
+% \DescribeMacro{\ForgetName}
+% This macro takes the same arguments as \cmd{\Name}, but it prints no output. It ``forgets'' a name, forcing a ``pre-first use'' state. The next time a naming macro makes reference to the name, it will display as if the name did not yet exist:
%
-% What we call ``basic'' alternate formatting is meant to be a temporary stop on the road to ``advanced'' usage, which is more robust. For reasons shown above, it is quite helpful to use \cmd{\noexpand} before macros in name arguments:
+% \begin{SyntaxBox}
+% \cmd{\ForgetName}\oarg{FNN}\marg{SNN|,| Affix}\oarg{Alternate}
+% \end{SyntaxBox}
%
-% \begin{center}\small\MyStretch
-% \begin{tabular}{ll}
-% |\Name[Martin]{\textSC{Luther}}| & {\color{nared}|%| \textit{basic; good}}\\
-% |\Name[Martin]{\noexpand\textSC{Luther}}| & {\color{nared}|%| \textit{advanced; better}}\\
-% \end{tabular}
-% \end{center}
+% \cmd{\ForgetName} ``unprotects'' names like \cmd{\IncludeName*} ``unprotects'' xrefs. This allows one to make both \textit{see} and \textit{see also} cross-references to a name, even if that name already has index page references.\medskip
%
-% The reason why the basic features work is because the built-in formatting macros discussed below have their effects set when alternate formatting is enabled. If one does not use the macros in names apart from alternate formatting and one does not change the Boolean flags that govern them, the basic features may suffice.
+% \DescribeMacro{\ForgetThis}
+% This prefix macro causes the next instance of a naming macro or shorthand to ``forget'' a name before printing it. After knowing |\Einstein| ``\Einstein'' we forget him and again have a first reference: |\ForgetThis\Einstein| ``\ForgetThis\Einstein''. \cmd{\ForgetThis} no longer affects the index unless one uses the \texttt{oldreset} option.\medskip
%
-% \begin{center}\bfseries Enabling and Disabling\end{center}
-% The first thing we need to know is how to enable and disable alternate formatting. The macros that accomplish this are global in scope and cannot be isolated in a local scope. Normally, they are used in pairs, except with the \texttt{altformat} option.
+% \DescribeMacro{\SubvertName}
+% This macro takes the same arguments as \cmd{\Name}, but it produces no output in the text. It ``subverts'' a name by creating a name pattern control sequence, forcing a ``subsequent use'', and ``protecting'' a name from being used as a \textit{see} reference (analogous to \cmd{\ExcludeName} and \cmd{\IndexRef}:
%
-% At the start of this section we used \cmd{\AltFormatActive} to enable alternate formatting and activate the formatting macros (see below). At the end of this section we must use \cmd{\AltFormatInactive} to deactivate and disable them.\medskip
+% \begin{SyntaxBox}
+% \cmd{\SubvertName}\oarg{FNN}\marg{SNN|,| Affix}\oarg{Alternate}
+% \end{SyntaxBox}
%
-% \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{Disabled} means that the normal behavior of \cmd{\CapThis} is again in force and alternate formatting is inhibited.
-% \item \emph{Activated} means that \cmd{\textSC} and other alternate formatting macros below format their arguments.
-% \item \emph{Deactivated} means that \cmd{\textSC} and other macros below do not format their arguments.
-% \end{itemize}
+% \DescribeMacro{\SubvertThis}
+% This prefix macro causes the next instance of a naming macro or shorthand to ``subvert'' a name before printing it. As indicated in Section~\ref{sec:Priorities}, \cmd{\ForgetThis} has a higher priority than \cmd{\SubvertThis} and negates it. \cmd{\SubvertThis} no longer affects the index unless one uses the \texttt{oldreset} option.
%
-% \DescribeMacro{\AltFormatActive*}
-% 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
+% \begin{InfoBox}
+% \centering We still advise one to avoid using \cmd{\ForgetThis} and \cmd{\SubvertThis}\\ before any naming macro that produces no output in the text.
+% \end{InfoBox}
%
-% \DescribeMacro{\AltFormatInactive}
-% This macro both disables and deactivates alternate formatting. This reverts globally to standard formatting and the normal function of \cmd{\CapThis}.
+% \DescribeMacro{\LocalNames}
+% By default, \cmd{\ForgetName}, \cmd{\SubvertName}, \cmd{\ForgetThis}, and \cmd{\SubvertThis} are not limited either by scope or by the active naming system.
+% \DescribeMacro{\GlobalNames}
+% \cmd{\LocalNames} restricts the effects of these macros to the current naming system, but not to scope. \cmd{\GlobalNames} restores the default behavior that affects both systems. Both macros always have global scope.
%
-% \begin{center}\MyStretch
-% \begin{tabular}{lcc}\toprule
-% Macro & Enabled & Activated\\\midrule
-% \cmd{\AltFormatActive} & \YES & \YES\\
-% \cmd{\AltFormatActive*} & \YES & \NO\\
-% \cmd{\AltFormatInactive} & \NO & \NO\\\bottomrule
-% \end{tabular}
-% \end{center}\leavevmode
+% To see how these two macros work, in the following example we define a macro that reports whether or not |\Name[Charlie]{Chaplin}| exists. This macro gives four possible results: the name exists in the main matter, it exists in the front matter, it exists in both systems, or it does not exist (see Section~\ref{sec:NameTests}):
%
-% \begin{tcolorbox}[colback=white,colframe=nared]
-% \centering All three macros \emph{always} make global changes.\\ This differs from other macros in \textsf{nameauth}.
-% \end{tcolorbox}\smallskip
+% \begin{VerbatimOut}{\jobname.tmp}
+% \def\CheckChuck{{\bfseries\IfFrontName[Charlie]{Chaplin}
+% {\IfMainName[Charlie]{Chaplin}{both}{front}}
+% {\IfMainName[Charlie]{Chaplin}{main}{none}}}}
+% \end{VerbatimOut}
%
-% \begin{center}\bfseries Basic Alternate Formatting\end{center}
-% \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} (Section~\ref{sec:IndexSort}):
-% \DescribeMacro{\textUC}
% \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}}\\
-% |\Name{\textUC{Tokugawa}, Ieyasu}|\dotfill \Name{\textUC{Tokugawa}, Ieyasu}; \Name{\textUC{Tokugawa}, Ieyasu}
+% \VerbatimInput[gobble=0]{\jobname.tmp}
% \end{quote}
+% \input{\jobname.tmp}
%
-% Font substitutions might occur with these macros.\footnote{Since we switch to Latin Modern Sans in the formatting hooks, the switch to small caps forces a substitution to Latin Modern Roman. This action varies with the font being used.}
-% They \emph{always format their arguments} when using the \texttt{altformat} option or after \cmd{\AltFormatActive}. Likewise, they \emph{never format their arguments} when \cmd{\AltFormatActive*} is used. Still, \cmd{\CapName}, \cmd{\RevComma}, and \cmd{\RevName} can modify the effects of alternate formatting, but only in the text, not the index:
+% \begin{itemize}
+% \item Start in the ``main-matter'' system with no extant name:
+% \begin{itemize}[rightmargin=2\leftmargin]
+% \ForgetName[Charlie]{Chaplin}
+% \item[] |\CheckChuck|\dotfill \CheckChuck
+% \end{itemize}
%
-% \begin{center}\small\MyStretch
-% \begin{tabular}{rl}\toprule
-% |\CapName\Name*[Greta]{\textSC{Garbo}}| & \CapName\Name*[Greta]{\textSC{Garbo}}\\
-% \rowcolor{grey}|\RevComma\Name*[Ada]{\textIT{Lovelace}}| & \RevComma\Name*[Ada]{\textIT{Lovelace}}\\
-% |\RevName\Name*{\textUC{Tokugawa}, Ieyasu}| & \RevName\Name*{\textUC{Tokugawa}, Ieyasu}\\\bottomrule
-% \end{tabular}
-% \end{center}
+% \item Create a name in the ``main matter'':
+% \PatInfo{\ShowPattern[Charlie]{Chaplin}!MN}
+% \begin{itemize}[rightmargin=2\leftmargin]
+% \ForgetName[Charlie]{Chaplin}
+% \item[] |\Name[Charlie]{Chaplin}|\dotfill \Name[Charlie]{Chaplin}
+% \item[] |\CheckChuck|\dotfill \CheckChuck
+% \end{itemize}
%
-% Here is a more practical example on how to format the required argument \marg{SNN\texttt{,\,}Affix} as two separate arguments:
-% \begin{quote}\small
-% \StartNum
-% \begin{verbatim}
-%\PretagName[J.D.]{\textSC{Rockefeller},\textSC{III}}
-% {Rockefeller, John D 3}
-%\PretagName{\textUC{Fukuyama}, Takeshi}{Fukuyama Takeshi}
-%\begin{nameauth}
-% \< JRIII & J.D. & \textSC{Rockefeller},\textSC{III} & >
-% \< Fukuyama & & \textUC{Fukuyama}, Takeshi & >
-%\end{nameauth}\end{verbatim}
-% \end{quote}
+% \item Switch to the ``front-matter'' system and create a name.
+% \PatInfo{\ShowPattern[Charlie]{Chaplin}!NF}
+% Ifone is within a group or local scope, one may have to add
+% \cmd{\global} to \cmd{\NamesInactive}:
+% \begin{itemize}[rightmargin=2\leftmargin]
+% \item[] |\global\NamesInactive|\global\NamesInactive
+% \item[] |\Name[Charlie]{Chaplin}|\dotfill \Name[Charlie]{Chaplin}
+% \item[] |\CheckChuck|\dotfill \CheckChuck
+% \end{itemize}
%
-% From above we get \JRIII, then \JRIII. This works also for non-Western names. Applying the macros above, we get:
-% \begin{center}\small\MyStretch
-% \begin{tabular}{rl}\toprule
-% \rowcolor{grey}|\Fukuyama| & \Fukuyama \\
-% |\Fukuyama| & \Fukuyama \\\bottomrule
-% \end{tabular}
-% \end{center}
+% \item use \cmd{\LocalNames} to make both \cmd{\ForgetName} and
+% \cmd{\SubvertName} work with only the current system.
+% \begin{itemize}[rightmargin=2\leftmargin]
+% \item[] |\LocalNames|\LocalNames
+% \end{itemize}
%
-% Only the new syntax allows one to use alternate names in the text. 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''.\smallskip
+% \item Had we not used \cmd{\global} above, we would have implicitly
+% returned to the main-matter system due to scoping and environments
+% like \texttt{quote} and \texttt{itemize}. We ``forget'' only the
+% name in the front-matter system.
+% \begin{itemize}[rightmargin=2\leftmargin]
+% \item[] |\ForgetName[Charlie]{Chaplin}|\ForgetName[Charlie]{Chaplin}
+% \item[] |\CheckChuck|\dotfill \CheckChuck
+% \end{itemize}
%
-% \begin{tcolorbox}[colback=white,colframe=nared]
-% \centering Using names designed for alternate formatting also with regular formatting will produce inconsistent formatting and spurious index entries.
-% \end{tcolorbox}\leavevmode
+% \item Next ``subvert'' the front-matter name to ``remember'' it again.
+% Then switch to main matter:
+% \begin{itemize}[rightmargin=2\leftmargin]
+% \item[] |\Subvert\Name[Charlie]{Chaplin}|\SubvertName[Charlie]{Chaplin}
+% \item[] |\CheckChuck|\dotfill \CheckChuck
+% \item[] |\global\NamesActive|\global\NamesActive
+% \end{itemize}
%
-% \begin{center}\bfseries Example Reference Work\end{center}
-% \phantomsection
-% \label{page:ContinentalXref}
-% This example uses basic Continental formatting. We build on our knowledge so far to construct head-words and articles. Below we use alternate formatting, sort index entries, set up a cross-reference, and define an article macro:
-% \AltFormatActive
-%\newcommand{\RefArticle}[3]{^^A
-% \def\check{#2}^^A
-% \ifx\check\empty
-% \noindent\ForgetThis#1\ #3
-% \else
-% \noindent\ForgetThis#1\ #2\ #3
-% \fi
-%}
-% \begin{quote}\small
-% \StartNum
-% \begin{verbatim}
-%\PretagName[Greta]{\textSC{Garbo}}{Garbo, Greta}
-%\PretagName{\textSC{Misora}, Hibari}{Misora Hibari}
-%\PretagName[Heinz]{\textSC{Rühmann}}{Ruehmann, Heinz}
-%\PretagName[Heinrich Wilhelm]{\textSC{Rühmann}}%
-% {Ruehmann, Heinrich Wilhelm}
-%\IndexRef[Heinrich Wilhelm]{\textSC{Rühmann}}%
-% {\textSC{Rühmann}, Heinz}%
-%
-%\newcommand{\RefArticle}[3]{%
-% \def\check{#2}%
-% \ifx\check\empty
-% \noindent\ForgetThis#1\ #3
-% \else
-% \noindent\ForgetThis#1\ #2\ #3
-% \fi
-%}\end{verbatim}
-% \end{quote}
-% \IndexRef[Heinrich Wilhelm]{\textSC{Rühmann}}{\textSC{Rühmann}, Heinz}
+% \item Now the current system is main matter. We forget the main-matter
+% name only, leaving the front-matter name intact:
+% \begin{itemize}[rightmargin=2\leftmargin]
+% \item[] |\ForgetName[Charlie]{Chaplin}|\ForgetName[Charlie]{Chaplin}
+% \item[] |\CheckChuck|\dotfill \CheckChuck
+% \end{itemize}
%
-% \cmd{\RefArticle} either formats the name from the first argument and appends the third argument, ignoring the the second if it is empty, or it formats the first two arguments and appends the third. We determine what those arguments mean by including specific naming macros. That includes using \cmd{\RevComma} for Western names, but not for Eastern ones.
-% \begin{quote}\small
-% \ContinueNum
-% \begin{verbatim}
-%\RefArticle
-% {\RevComma\Name[Greta]{\textSC{Garbo}}}
-% {}
-% {(18 September 1905\,--\,15 April 1990) was a Swedish
-% film actress during the 1920s and 1930s.}
-%
-%\RefArticle
-% {\Name{\textSC{Misora}, Hibari}}
-% {}
-% {(W: ``\RevName\Name*{\textSC{Misora}, Hibari}'';
-% 29 May 1937\,--\,24 June 1989) was a Japanese singer
-% and actress noted for her positive message.}
-%
-%\RefArticle
-% {\RevComma\Name[Heinrich Wilhelm]{\textSC{Rühmann}}}
-% {``\SubvertThis\ForceName\FName[Heinz]{\textSC{Rühmann}}''}
-% {(7 March 1902\,--\,3 October 1994) was a German actor
-% in over 100 films.}
-%\AltFormatInactive\end{verbatim}
-% \end{quote}
+% \item Use \cmd{\GlobalNames} to make \cmd{\ForgetName} and
+% \cmd{\SubvertName} work with both systems again:
+% \begin{itemize}[rightmargin=2\leftmargin]
+% \item[] |\GlobalNames|\GlobalNames
+% \end{itemize}
%
-% \begin{quote}\small
-%\RefArticle
-% {\RevComma\Name[Greta]{\textSC{Garbo}}}
-% {}
-% {(18 September 1905\,--\,15 April 1990) was a Swedish
-% film actress during the 1920s and 1930s.}
-%
-%\RefArticle
-% {\Name{\textSC{Misora}, Hibari}}
-% {}%
-% {(W: ``\RevName\Name*{\textSC{Misora}, Hibari}'';
-% 29 May 1937\,--\,24 June 1989) was a Japanese singer
-% and actress noted for her positive message.}
-%
-%\RefArticle
-% {\RevComma\Name[Heinrich Wilhelm]{\textSC{Rühmann}}}
-% {``\SubvertThis\ForceName\FName[Heinz]{\textSC{Rühmann}}''}
-% {(7 March 1902\,--\,3 October 1994) was a German actor
-% in over 100 films.}
-% \end{quote}
+% \item Finally, we forget everything. Even though we are in a main-matter
+% section, the front-matter name also goes away:
+% \begin{itemize}[rightmargin=2\leftmargin]
+% \item[] |\ForgetName[Charlie]{Chaplin}|\ForgetName[Charlie]{Chaplin}
+% \item[] |\CheckChuck|\dotfill \CheckChuck
+% \end{itemize}
+% \end{itemize}
%
-% \subsubsection[Advanced Features]{Advanced Formatting Features}
-% \label{sec:AltAdvanced}
+% \subsection{Formatting and Decisions}
%
-% Advanced features involve a dance of sorts between the name argument macros and the formatting hooks. We are moving from immutability to changeability. Yet so far, we have heard that this could change conditional statements and create spurious index entries.
-%
-% Using \cmd{\noexpand} befor macros in name arguments that expand conditionally will solve this problem for us:
-% \begin{itemize}
-% \item The use of \cmd{\noexpand} isolates the global state of \cmd{\textSC} and the other formatting macros from local changes in the formatting hooks.
-% \item Indexing never occurs within the formatting hooks.
-% \item Special triggering macros in the formatting hooks isolate local changes.
+% We pull together information on name forms and formatting, focusing on what happens in one naming system only, since the two systems are independent.
+%
+% \begin{itemize}[leftmargin=3cm]\small
+% \item[First Use:] \cmd{\Bailey} \dotfill \ForgetThis\Bailey\\
+% \cmd{\LBailey} \dotfill \ForgetThis\LBailey\\
+% \cmd{\SBailey} \dotfill \ForgetThis\SBailey\\
+% Name control pattern created with text output.
+% Index state 2, 4, or 6 (Section~\ref{sec:RuleStates}).
+% Name form: long. First-use hooks.
+%
+% \item[Later Use:] \cmd{\Bailey} \dotfill \Bailey\\
+% \cmd{\LBailey} \dotfill \LBailey\\
+% \cmd{\SBailey} \dotfill \SBailey\\
+% No change to name pattern. Index state 2, 4, or 6.
+% Name form: short. Subsequent-use hooks.
+%
+% \item[Forgotten:] \cmd{\ForgetName[Betsey]\{Bailey\}} \dotfill
+% (no output)\ForgetName[Betsey]{Bailey}\\
+% Name pattern deleted. Index state 1, 3, or 5
+% (Section~\ref{sec:RuleStates}).
+% Next use usually will be a first use, e.g.: \Bailey.
+%
+% \item[Subverted:] \cmd{\SubvertName[Betsey]\{Bailey\}} \dotfill
+% (no output)\SubvertName[Betsey]{Bailey}\\
+% Name pattern created. Index state 2, 4, or 6.
+% Next use usually will be a later use, e.g.: \Bailey, \LBailey, \SBailey.
+%
+% \item[\cmd{\ForgetThis}:]
+% \cmd{\ForgetThis}\cmd{\Bailey} \dotfill \ForgetThis\Bailey\\
+% \cmd{\ForgetThis}\cmd{\LBailey} \dotfill \ForgetThis\LBailey\\
+% \cmd{\ForgetThis}\cmd{\SBailey} \dotfill \ForgetThis\SBailey\\
+% Name pattern deleted, then created again. Index state 2, 4, or 6.
+% Name form and format: same as first use above. Next use usually
+% will be a later use, e.g.: \Bailey, \LBailey, \SBailey.
+%
+% \item[\cmd{\SubvertThis}:]
+% \cmd{\SubvertThis}\cmd{\Bailey} \dotfill \SubvertThis\Bailey\\
+% \cmd{\SubvertThis}\cmd{\LBailey} \dotfill \SubvertThis\LBailey\\
+% \cmd{\SubvertThis}\cmd{\SBailey} \dotfill \SubvertThis\SBailey\\
+% Name pattern created. Index state 2, 4, or 6.
+% Name form and format: same as later use above. Next use usually
+% will be a later use, e.g.: \Bailey, \LBailey, \SBailey.
+%
+% \item[Format First:]
+% \cmd{\ForceName}\cmd{\Bailey} \dotfill \ForceName\Bailey\\
+% \cmd{\ForceName}\cmd{\LBailey} \dotfill \ForceName\LBailey\\
+% \cmd{\ForceName}\cmd{\SBailey} \dotfill \ForceName\SBailey\\
+% No change to name pattern. Index state 2, 4, or 6.
+% Name form: short or long. Name format: First-use hooks.
% \end{itemize}
+%
+% \AltFormatActive
+% \begin{Quote}{\ForgetThis\Luth\break
+% \hbox{}\hfill \textit{Von der Freiheit eines Christenmenschen}
+% (1520)\footnote{In several cases (e.g., here) when one uses small
+% caps, harmless font substitution warnings result.}}
+% Eyn Chriſten menſch iſt eyn freyer herr /
+% u\raise 0.2ex\hbox{\kern -1.1ex\textsuperscript{e}\kern 1pt}ber alle
+% ding / und niemande unterthan. Eyn Chriſten menſch iſt eyn dienſtpar
+% knecht aller ding und yderman unterthan.
%
-% As a result of these points, advanced alternate formatting works as expected. It uses a similar approach as did the Boolean flags for Roman names (page~\pageref{page:Romani}).
-% \smallskip
+% (A Christian is a free lord, above all things, and subject to no one.
+% A Christian is a willing servant of all things and is subject to
+% everyone.)
+% \end{Quote}
+% \AltFormatInactive
%
-% \begin{tcolorbox}[colback=white,colframe=nared]
-% \centering Using \cmd{\noexpand} is key to consistent index entries.
-% \end{tcolorbox}\smallskip
% \newpage
%
-% \begin{center}\bfseries Alternate Capitalization\end{center}
-% When alternate formatting is enabled, \cmd{\CapThis}\DescribeMacro{\AltCaps}\ causes \cmd{\AltCaps} to format its argument only in a formatting hook. It is enabled whenever alternate formatting is enabled, but it works independently of \cmd{\AltOn} and \cmd{\AltOff} below:
-% \begin{quote}
-% \fbox{
-% \begin{tabular}{l}
-% {\Large\strut}\cmd{\noexpand}\cmd{\AltCaps}\marg{Arg}\\
-% \end{tabular}
-% }
-% \end{quote}
+% \subsection{Testing Name Decisions}
+% \label{sec:NameTests}
%
-% We introduce this macro with a silly example, disabling indexing in the process:
-% \IndexInactive
-% \begin{quote}\small
-% \StartNum
-% \begin{verbatim}
-%\IndexInactive
-%What's in \Name[\noexpand\AltCaps{a}]{Name}?
-%\CapThis\Name*[\noexpand\AltCaps{a}]{Name} smells not,
-%but a rose does, even if it has a
-%\Name[\noexpand\AltCaps{a}]{Name}.\end{verbatim}
+% Since name patterns are control sequences like macros, we can test for their existence. This can relate names to each other dynamically throughout a document.
%
-% What's in \Name[\noexpand\AltCaps{a}]{Name}?
-% \CapThis\Name*[\noexpand\AltCaps{a}]{Name} smells not,
-% but a rose does, even if it has a
-% \Name[\noexpand\AltCaps{a}]{Name}.
-% \end{quote}
+% \subsubsection{Testing Macros}
%
-% \begin{center}\bfseries Advanced Alternate Formatting\end{center}
-% Advanced features come with ``some assembly required''. An author must put one of the trigger macros below into one or more of the \textsf{nameauth} formatting hooks. These macros change the state of the formatting macros.\medskip
+% The macros in this section test for the presence or absence of a name, then expand to a result based on the outcome of the test.\medskip
%
-% Vaguely reminiscent of\DescribeMacro{\AltOff}\ an automobile's manual clutch and gearbox, \cmd{\AltOff} deactivates \cmd{\textSC}, \cmd{\textBF}, \cmd{\textIT}, and \cmd{\textUC} only in a formatting hook.\medskip
+% \DescribeMacro{\GlobalNameTest}
+% The default behavior encapsulates the decision paths in a local scope, insulating any changes therein.
+% \DescribeMacro{\LocalNameTest}
+% If this is not desired, use the \texttt{globaltest} option or \cmd{\GlobalNameTest}. \cmd{\LocalNameTest} will re-enable the default. These commands affect assignment statements in test paths. By default, one must explicitly use \cmd{\global} when desired. See also the examples below.\medskip
%
-% Likewise, \cmd{\AltOn}\DescribeMacro{\AltOn}\ activates \cmd{\textSC}, \cmd{\textBF}, \cmd{\textIT}, and \cmd{\textUC} only in a formatting hook.\medskip
+% \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:
%
-% Continuing the example (indexing suppressed), we redefine \cmd{\MainNameHook} to suppress small caps. Note the copious use of \cmd{\noexpand}:
-% \renewcommand*\MainNameHook{\sffamily\AltOff}
-% \begin{quote}\small
-% \ContinueNum
-% \begin{verbatim}
-%\renewcommand*\MainNameHook%
-% {\sffamily\AltOff}% we match the manual
-%
-%\CapThis\Name
-% [\noexpand\textSC{\noexpand\AltCaps{a} Name}]
-% {\noexpand\textSC{Problem}}
-%will not become a \Name
-% [\noexpand\textSC{\noexpand\AltCaps{a} Name}]
-% {\noexpand\textSC{Problem}},
-%even if it smells like a rose.
-%\IndexActive\end{verbatim}
-%
-%\CapThis\Name
-% [\noexpand\textSC{\noexpand\AltCaps{a} Name}]
-% {\noexpand\textSC{Problem}}
-%will not become a \Name
-% [\noexpand\textSC{\noexpand\AltCaps{a} Name}]
-% {\noexpand\textSC{Problem}},
-%even if it smells like a rose.
-% \end{quote}
-% \IndexActive
+% \begin{SyntaxBox}
+% \cmd{\IfMainName}\oarg{FNN}\marg{SNN|,| Affix}\oarg{Alternate}^^A
+% \marg{yes}\marg{no}
+% \end{SyntaxBox}
+%
+% For example we have not encountered |\Name[Bob]{Hope}| yet. Using \cmd{\IndexName} does not affect the tests in this section. We could do the following test that will reflect whether or not the name is present in the text:
+%
+% \begin{VerbatimOut}{\jobname.tmp}
+% I heard someone say: \IfMainName[Bob]{Hope}
+% {Bob here!}
+% {No Bob here.}\IndexName[Bob]{Hope}
+% \end{VerbatimOut}
%
-% Now indexing is active again. Using the same \cmd{\MainNameHook} defined above, consider the following in a document preamble:
% \begin{quote}\small
-% \StartNum
-% \begin{verbatim}
-%\begin{nameauth}
-% \< Luth & Martin & \noexpand\textSC{Luther} & >
-% \< Cath & Catherine \noexpand\AltCaps{d}e'
-% & \noexpand\textSC{Medici} & >
-%\end{nameauth}
-%\PretagName[Martin]{\noexpand\textSC{Luther}}{Luther, Martin}
-%\PretagName[Catherine \noexpand\AltCaps{d}e']
-% {\noexpand\textSC{Medici}}{Medici, Catherine de}\end{verbatim}
+% \VerbatimInput[gobble=0]{\jobname.tmp}
+%
+% \input{\jobname.tmp}
% \end{quote}
%
-% In the body text, we see \cmd{\ForgetThis}\cmd{\Luth} \ForgetThis\Luth\ and \cmd{\Luth} \Luth. Likewise \cmd{\Cath} \Cath, then \cmd{\Cath} \Cath. Medieval Italian differs from modern Italian with respect to particles. To get \LCath[\noexpand\AltCaps{d}e'] in the text, use |\LCath[\noexpand\AltCaps{d}e']|, with which \cmd{\CapThis} also works. The index entry should be ``\ShowIdxPageref*[Catherine \noexpand\AltCaps{d}e']{\noexpand\textSC{Medici}}\,'', instead of ``\ShowIdxPageref*[Catherine]{de'~\textSC{Medici}}''.\medskip
+% Now we test for |\Name{Elizabeth,I}|, a name that has occurred, and we also show the difference between local and global test paths. We see that the default keeps local any assignments made in the test paths:
%
-% \phantomsection
-% \label{page:Inflections}
-% We\Info{Name inflections} can design grammatical inflections either with or without alternate formatting. \cmd{\DoGentrue} occurs only in the formatting hook, keeping the index entries consistent via \cmd{\noexpand}. Highly inflected languages require two Boolean flags per case and nested conditional statements.\footnote{We hide the same information that we did on page~\pageref{page:Sobriquets}. A copy of this example is in \texttt{examples.tex}, located with this manual.} In the example below we do not use the formatting in this manual and we hide the special tags used herein. In the preamble of a document we would have:
+% \begin{VerbatimOut}{\jobname.tmp}
+% \GlobalNameTest
+% \def\msg{We are unsure about \LEliz}
+%
+% \IfMainName{Elizabeth,I}
+% {\def\msg{We really do know of \LEliz}}
+% {\def\msg{We do not know of \LEliz}}
+%
+% \parbox{0.4\textwidth}{\msg} (\cmd{\GlobalNameTest}).
+%
+% \LocalNameTest
+% \def\msg{We are unsure about \LEliz}
+%
+% \IfMainName{Elizabeth,I}
+% {\def\msg{We really do know of \LEliz}}
+% {\def\msg{We do not know of \LEliz}}
+%
+% \parbox{0.4\textwidth}{\msg} (\cmd{\LocalNameTest}).
+% \end{VerbatimOut}
%
% \begin{quote}\small
-% \StartNum
-% \begin{verbatim}
-%\newif\ifGenitive
-%\newif\ifDoGen
-%\newcommand*\JEFF{\ifDoGen\textSC{Jefferson's}\else
-% \textSC{Jefferson}\fi}
-%\begin{nameauth}
-% \< Jeff & Thomas & \noexpand\JEFF & >
-%\end{nameauth}
-%\PretagName[Thomas]{\noexpand\JEFF}{Jefferson, Thomas}
-%\TagName[Thomas]{\noexpand\JEFF}{, pres.}\end{verbatim}
+% \VerbatimInput[gobble=0]{\jobname.tmp}
+%
+% \input{\jobname.tmp}
% \end{quote}
%
-% In the preamble or document text, we can have:
-% \renewcommand*\NamesFormat[1]{\ifGenitive\DoGentrue\fi#1\global\Genitivefalse}
-% \renewcommand*\MainNameHook[1]{\ifGenitive\DoGentrue\fi\AltOff#1\global\Genitivefalse}
+% \newpage
+%
+% \DescribeMacro{\IfFrontName}
+% In order to test whether or not a ``front matter'' name pattern exists, use this long macro that can accommodate paragraph breaks. Its syntax is:
+%
+% \begin{SyntaxBox}
+% \cmd{\IfFrontName}\oarg{FNN}\marg{SNN|,| Affix}\oarg{Alternate}^^A
+% \marg{yes}\marg{no}
+% \end{SyntaxBox}
+%
+% This macro works just like \cmd{\IfMainName}, except using the ``front matter'' name control sequences as the test subject. These testing macros prove their worth especially through combination. For example, we do a test based on Section~\ref{sec:Formatting}.
+%
+% \begin{VerbatimOut}{\jobname.tmp}
+% \IfFrontName[Rudolph]{Carnap}
+% {\IfMainName[Rudolph]{Carnap}
+% {\Name[Rudolph]{Carnap} is in both main- and front-matter text.}
+% {\Name[Rudolph]{Carnap} is only in front-matter text.}}
+% {\IfMainName[Rudolph]{Carnap}
+% {\Name[Rudolph]{Carnap} is only in main-matter text.}
+% {\Name[Rudolph]{Carnap} has not been mentioned.}}
+% \end{VerbatimOut}
+%
% \begin{quote}\small
-% \ContinueNum
-% \begin{verbatim}
-%\renewcommand*\NamesFormat[1]
-% {\ifGenitive\DoGentrue\fi#1\global\Genitivefalse}
-%\renewcommand*\MainNameHook[1]
-% {\ifGenitive\DoGentrue\fi\AltOff#1\global\Genitivefalse}
-%
-%Consider \Genitivetrue\Jeff\ legacy. 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.
+% \VerbatimInput[gobble=0]{\jobname.tmp}
+%
+% \input{\jobname.tmp}
% \end{quote}
%
-% Now we end the scope, resume normal formatting, and 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^^A Local format hook redefinition
+% \DescribeMacro{\IfAKA}
+% This macro tests whether or not a regular or excluded form of cross-reference control sequence exists. The syntax is:
%
-% \ReturnLink
-% \vfill
+% \begin{SyntaxBox}
+% \cmd{\IfAKA}\oarg{FNN}\marg{SNN|,|Affix}\oarg{Alternate}^^A
+% \marg{y}\marg{n}\marg{excl}
+% \end{SyntaxBox}
%
-% \noindent Perhaps one can use the \textsf{nameauth package}\dots
-% \begin{verse}
-% There in the ring where name and image meet\\[1ex]\hfill---\Name[W.H.]{Auden}, ``Perhaps''
-% \end{verse}
-% \newpage
+% This macro also works like \cmd{\IfMainName}, except that it has an additional \meta{excl} branch in order to detect the activity of \cmd{\ExcludeName} (Section~\ref{sec:GeneralIndex}). Cross-references are governed by name control sequences ending in \texttt{!PN} (Section~\ref{sec:NamePatterns}).
%
-% \subsection{Name Decisions}
-% \label{sec:NameDecisions}
+% \begin{itemize}
+% \item Excluded control sequences (the \meta{excl} path) expand
+% to the value of \cmd{\@nameauth@Exclude}.
+% \item Regular cross-references (the \meta{y} path) do not expand
+% to that value. At present, they are empty.
+% \item \cmd{\ExcludeName} creates excluded xrefs. \cmd{\IncludeName}
+% destroys them.
+% \item Regular xrefs are created by \cmd{\IndexRef}, \cmd{\AKA},
+% \cmd{\PName} and their starred forms. Regular xrefs are destroyed
+% by \cmd{\IncludeName*}.
+% \end{itemize}
+%
+% Based on the known facts above, below we offer some examples:
+%
+% \begin{enumerate}
+% \item In\PatInfo{\ShowPattern[Jesse]{Ventura}!MN\break
+% \ShowPattern[James]{Janos}!PN\break
+% \ShowPattern[James]{Janos}!MN}
+% the text we first create a reference 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
+% \meta{excl} branch empty:
+% \end{enumerate}
%
-% 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}, located with this manual.}
% \begin{quote}\small
-% \StartNum
-% \begin{verbatim}
-%\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}\\
-% This version of \Name[Ulysses S.]{Grant} changes.
-% \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}\\
-% This version of \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[Ulysses S.]{Grant}
+% \begin{Verbatim}
+% \IfAKA[James]{Janos}
+% {\Name*[Jesse]{Ventura} is a stage name}
+% {\Name*[Jesse]{Ventura} is a regular name}
+% {}
+% \end{Verbatim}
% \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
%
-% \subsubsection{Making Decisions}
-% \label{sec:NameControl}
+% We can combine all these macros to create a complete, unified test:
+%
+% \begin{quote}\small
+% \begin{Verbatim}
+% \IfAKA[FNN]{SNN, Affix}[Alternate]
+% {%
+% % yes; it is an xref
+% }
+% {%
+% % no, it is a name
+% \IfFrontName[FNN]{SNN, Affix}[Alternate]
+% {%
+% % yes, it is in the front matter
+% \IfMainName[FNN]{SNN, Affix}[Alternate]
+% {%
+% % it is in both front and main matter
+% }
+% {%
+% % it is only in the front matter
+% }%
+% }
+% {%
+% % no, it is not in the front matter
+% \IfMainName[FNN]{SNN, Affix}[Alternate]
+% {%
+% % it is only in the main matter
+% }
+% {%
+% % it does not exist
+% }%
+% }%
+% }
+% {%
+% % no; it is excluded
+% }
+% \end{Verbatim}
+% \end{quote}
%
-% By 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 both indexing error protection (Section~\ref{sec:GeneralIndex}) and the name testing macros (Section~\ref{sec:NameTests}).\medskip
+% \subsubsection[Applications]{Applications: Game Books, Histories, Etc.}
+%
+% In any text where encountering certain names can change variables, character statistics, personal information, the macros described above can be used to key various pieces of information to the presence or the absence of a name. For example, in a series of independent document sections, one can craft notes like the one below to sketch out character development:
%
-% \DescribeMacro{\ForgetName}
-% This macro takes the same arguments as \cmd{\Name}, but it prints no output. It ``forgets'' a name, forcing a ``pre-first use'' state that will trigger a first-time name use the next time a naming macro makes reference to the name:
% \begin{quote}
-% \fbox{
-% \begin{tabular}{l}
-% {\Large\strut}\cmd{\ForgetName}\oarg{FNN}\marg{SNN|,| Affix}\oarg{Alternate}\\
-% \end{tabular}
-% }
+% \begin{Verbatim}
+% \ifMainName[Ferris}{Bueller}
+% {\Name[Cameron]{Frye} is gloomy and introspective.}
+% {\Name[Cameron]{Frye} is developing positive traits.}
+% \end{Verbatim}
% \end{quote}
-% This macro ``unprotects'' names like \cmd{\IncludeName*} ``unprotects'' cross-references, allowing one to make a \textit{see} reference to a name, even if that name already has index page references. If one is using a single name index, that could be an error. If one is using multiple indexes for names, however, that could be necessary.\medskip
%
-% \DescribeMacro{\SubvertName}
-% This macro takes the same arguments as \cmd{\Name}, but it produces no output in the text. It ``subverts'' a name by creating a name pattern control sequence, forcing a ``subsequent use'', and ``protecting'' a name from being used as a \textit{see} reference (similar to \cmd{\ExcludeName} and cross-references):
+% In some instances, one might test for the presence of a name to determine whether or not to use a particular version of that name:
+%
% \begin{quote}
-% \fbox{
-% \begin{tabular}{l}
-% {\Large\strut}\cmd{\SubvertName}\oarg{FNN}\marg{SNN|,| Affix}\oarg{Alternate}\\
-% \end{tabular}
-% }
+% \JustIndex\JWG^^A
+% \begin{Verbatim}
+% \ifMainName[J.W. von}{Goethe}
+% {\Name[J.W. von}{Goethe}}
+% {\Name[J.W. von}{Goethe}[Johann Wolfgang von]}
+% \end{Verbatim}
% \end{quote}
%
-% \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
-%
-% This\Warn{} macro does not affect the index unless one uses \cmd{\ForgetThis} in a situation where a naming macro produces no output in the text. That results in the same outcome as a careless use of \cmd{\ForgetName}:
-% \begin{center}\small\MyStretch
-% \begin{tabular}{c@{\ \ }p{0.43\textwidth}@{\ }p{0.22\textwidth}}\toprule
-% Page & Macro & Index Result\\\midrule
-% \rowcolor{grey}^^A
-% 10 & \cmd{\ForgetThis}\cmd{\JustIndex}\cmd{\Einstein} & Einstein, Albert, 10\\
-% 12 & \cmd{\IndexRef[Albert]\{Einstein\}\%} & \\
-% & \texttt{\{Smart Dude\}}\dotfill \hbox{} & Einstein, Albert, 10, \textit{see} Smart Dude\\\bottomrule
-% \end{tabular}
-% \end{center}
+% In Sections~\ref{sec:NameAncient} and~\ref{sec:SpecialUses} we explore ways that one could automate something like what we have above. Section~\ref{sec:SpecialUses} applies better to Western names.
%
+% In addition to using the name decision testing macros by themselves, one can use them with name data tags to ensure that the information associated with a given name is not anachronistic.
%
-% \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 indicated in the table on page~\pageref{page:Priorities}, \cmd{\ForgetThis} has a higher priority than \cmd{\SubvertThis} and negates it. The caveat regarding naming macro output applies to both \cmd{\SubvertThis} and \cmd{\ForgetThis}.
-% \vfil
+% For example, we know that certain people are associated with chronological events. We associate those people and events to the information presented in a name data tag via name testing macros:
%
-% \begin{tcolorbox}[colback=white,colframe=nared]
-% \centering We advise one to avoid using \cmd{\ForgetThis} and \cmd{\SubvertThis}\\ before any naming macro that produces no output in the text.
-% \end{tcolorbox}\medskip
-% \newpage
+% \begin{VerbatimOut}{\jobname.tmp}
+% \NameAddInfo{Saul, of Tarsus}
+% {\IfMainName{Jesus, Christ}
+% {\IfMainName[Lucius]{Sergius Paulus}
+% {finally renamed himself \Name{Paul}, in
+% honor of his patron}
+% {next became a preacher to the Gentiles}}
+% {wrote first that he persecuted Christians}}
+% \ForgetName{Jesus, Christ}
+% \ForgetName[Lucius]{Sergius Paulus}
+% \IndexRef{Paul}{Saul of Tarsus}
%
-% \begin{center}\bfseries Name Decision and Formatting Summary\end{center}
-% \phantomsection
+% \Name{Saul, of Tarsus} \NameQueryInfo{Saul, of Tarsus}.
+% He wrote in the letter to the Galatians, later reported in
+% the book of Acts, that he saw a vision of \Name{Jesus, Christ}
+% on the road to Damascus.
%
-% \begin{itemize}\small
-% \item[First Use:] \cmd{\Bailey} \dotfill \ForgetThis\Bailey\\
-% Name control sequence (cseq) undefined, then created with text output. Index \textit{see} protection set.
-% Default name form (long). Default first-use format hooks.
+% \Name{Saul, of Tarsus} \NameQueryInfo{Saul, of Tarsus}.
+% He undertook three great missionary trips before being
+% sent to Rome to face trial in an appeal to Caesar. On one
+% journey, while in Cyprus, \Name{Saul, of Tarsus} converted
+% \Name[Lucius]{Sergius Paulus}, who became a patron.
%
-% \item[Later Use:] \cmd{\Bailey} \dotfill \Bailey\\
-% No change to extant name cseq. No change to index \textit{see} protection.
-% Default name form (short). Default later-use format hooks.
+% \Name{Saul, of Tarsus} \NameQueryInfo{Saul, of Tarsus}.
+% Under the name \Name{Paul} he wrote his letters.
+% \end{VerbatimOut}
%
-% \item[Forgotten:] \cmd{\ForgetName[Betsey]\{Bailey\}} \dotfill (no output)\ForgetName[Betsey]{Bailey}\\
-% \emph{Name cseq deleted. Index \textit{see} protection removed. Force first use.}
-% Next use of \cmd{\Bailey} will be a first use.
+% \begin{quote}\small
+% \vspace{3ex}
+% \PatInfo{\ShowPattern{Paul}!PN\break
+% \ShowPattern{Saul, of Tarsus}!DB\break
+% \ShowPattern{Jesus, Christ}!MN\break
+% \textls[-10]{\ShowPattern[Lucius]{Sergius Paulus}!MN}\break
+% \ShowPattern{Paul}!MN\break
+% \ShowPattern{Saul, of Tarsus}!MN}
+% \vspace{-3ex}
+% \VerbatimInput[gobble=0]{\jobname.tmp}
%
-% \item[Subverted:] \cmd{\SubvertName[Betsey]\{Bailey\}} \dotfill (no output)\SubvertName[Betsey]{Bailey}\\
-% \emph{Name cseq created. Index \textit{see} protection set. Force later use.}
-% Next use of \cmd{\Bailey} will be a later use.
+% \input{\jobname.tmp}
+% \end{quote}
%
-% \item[\cmd{\ForgetThis}:] \cmd{\ForgetThis}\cmd{\Bailey} \dotfill \ForgetThis\Bailey\\
-% \emph{Name cseq deleted, then created. Index \textit{see} protection removed, then set. Force first use.} Default form (long). Default first-use format hooks. Next use of \cmd{\Bailey} will be a later use if output occurs.
+% Using these tests\Info{Caveats} inside other macros or passing control sequences to them may create false results (see \textit{The \TeX book}, 212--15). This was especially the case before 2018 with names using diacritical marks and other letters outside the basic Latin characters. That is why \textsf{nameauth} uses token registers to save name arguments.
%
-% \item[\cmd{\SubvertThis}:] \cmd{\SubvertThis}\cmd{\Bailey} \dotfill \SubvertThis\Bailey\\
-% \emph{Name cseq created if undefined. Index \textit{see} protection set.
-% Force later use.} Default form (short). Default later-use format hooks. Next use of \cmd{\Bailey} will be a later use if output occurs.
+% We have stressed and will continue to stress using \cmd{\noexpand} in macros passed as name arguments to stabilize what happens. See also Section~\ref{sec:Unicode} regarding how one might engage possible Unicode issues in certain \LaTeX\ engines.
%
-% \item[Long Use:] \cmd{\LBailey} \dotfill \LBailey\\
-% No change to extant name cseq. No change to index \textit{see} protection.
-% \emph{Force long name form.} No change to format hooks.
+% In addition to these points, using the \textsf{trace} package, \cmd{\show}, or \cmd{\meaning} can help one to mitigate problems.
%
-% \item[``Short'', first:] \cmd{\ForgetThis}\cmd{\SBailey} \dotfill \ForgetThis\SBailey\\
-% \emph{Name cseq deleted, then created}. \emph{Index \textit{see} protection removed, then set}. \emph{First use forces long form.} Default first-use format hooks.
+% \newpage
%
-% \item[Short, later:] \cmd{\SBailey} \dotfill \SBailey\\
-% No change to extant name cseq. No change to index \textit{see} protection.
-% \emph{Force first name or short name.} No change to format hooks.
+% \subsubsection{Beamer Example}
%
-% \item[Forced, later:] \cmd{\ForceName}\cmd{\Bailey} \dotfill \ForceName\Bailey\\
-% No change to extant name cseq. No change to index \textit{see} protection. Default name form. \emph{Force first-use hooks.}
+% Below we keep names consistent with \textsf{beamer} overlays using some of the macros explained in this section. Otherwise, name forms will change automatically as one advances the slides. We do not use indexing in this example.
%
-% \item[Forced, long:] \cmd{\ForceName}\cmd{\LBailey} \dotfill \ForceName\LBailey\\
-% No change to extant name cseq. No change to index \textit{see} protection. \emph{Force long name form. Force first-use hooks.}
+% \ifdefined\NameauthDoTestFiles \edef\NameauthTestFile{test09_01.tex}\else
+% \edef\NameauthTestFile{\jobname.tmp}\fi
%
-% \item[Forced, short:] \cmd{\ForceName}\cmd{\SBailey} \dotfill \ForceName\SBailey\\
-% No change to extant name cseq. No change to index \textit{see} protection.
-% \emph{Force first name or short name if subsequent use. Force first-use hooks.}
-% \end{itemize}
-% \medskip
+% \begin{VerbatimOut}{\NameauthTestFile}
+% \documentclass{beamer}
+% \input{compat.tex} % Included with nameauth; needed only if
+% % compiling on multiple TeX distros or LaTeX engines.
+% \usepackage[noindex]{nameauth}
+% \mode<presentation>
+% \beamerdefaultoverlayspecification{<+->}
%
-% \DescribeMacro{\LocalNames}
-% By default, \cmd{\ForgetName}, \cmd{\SubvertName}, \cmd{\ForgetThis}, and \cmd{\SubvertThis} are not limited either by scope or by the active naming system.
-% \DescribeMacro{\GlobalNames}
-% \cmd{\LocalNames} restricts the effects of these macros to the current naming system, but not to scope. \cmd{\GlobalNames} restores the default behavior that affects both systems. Both macros always have global scope.
-%
-% To see how these two macros work, in the following example we define a macro that reports whether or not |\Name[Charlie]{Chaplin}| exists. This macro gives four possible results: the name exists in the main matter, it exists in the front matter, it exists in both systems, or it does not exist (see Section~\ref{sec:NameTests}):
-% \newpage
+% \begin{document}
+%
+% \begin{frame}{Move Text Without Retyping Names}
+% \begin{itemize}\footnotesize
+% \item<1-> Original\ForgetName[George]{Washington}%
+% \ForgetName[George]{Washington's}\\
+% This version of \Name[Ulysses S.]{Grant} changes.
+% \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}%
+% {\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}\\
+% This version of \ForgetThis\Name[Ulysses S.]{Grant}
+% does not change.
+% \begin{enumerate}
+% \item<3-> \IfMainName[George]{Washington}{His}%
+% {\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{VerbatimOut}
%
-% \def\CheckChuck{{\bfseries\IfFrontName[Charlie]{Chaplin}%
-% {\IfMainName[Charlie]{Chaplin}{both}{front}}%
-% {\IfMainName[Charlie]{Chaplin}{main}{none}}}}%
% \begin{quote}\small
-% \StartNum
-% \begin{verbatim}
-%\def\CheckChuck{{\bfseries\IfFrontName[Charlie]{Chaplin}%
-% {\IfMainName[Charlie]{Chaplin}{both}{front}}%
-% {\IfMainName[Charlie]{Chaplin}{main}{none}}}}\end{verbatim}
-% \end{quote}
-% \noindent
-% We start in the ``main-matter'' system with no extant name:
-% \begin{quote}\small\MyStretch\ForgetName[Charlie]{Chaplin}
-% |\CheckChuck|\dotfill \CheckChuck\qquad\qquad\qquad\hbox{}
-% \end{quote}
-% 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{}
+% \VerbatimInput[gobble=0]{\NameauthTestFile}
+% \IndexName[George]{Washington}
+% \IndexName[Ulysses S.]{Grant}
% \end{quote}
-% We switch to the ``front-matter'' system 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}
-% We now have two names. Their patterns are: \texttt{\ShowPattern[Charlie]{Chaplin}!MN} for the main matter and \texttt{\ShowPattern[Charlie]{Chaplin}!NF} for the front matter (Section~\ref{sec:NamePatterns}).
%
-% We use \cmd{\LocalNames} to make both \cmd{\ForgetName} and \cmd{\SubvertName} work with only the current system. When we ``forget'' the name, the current system is front matter, so 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}
-% 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}
-% Now the current system is main matter. We then forget the main-matter name only. Additionally, we use \cmd{\GlobalNames} to reset the default behavior so that \cmd{\ForgetName} and \cmd{\SubvertName} work with both systems again:
-% \begin{quote}\small\MyStretch
-% |\ForgetName[Charlie]{Chaplin}|\ForgetName[Charlie]{Chaplin}\\
-% |\GlobalNames|\GlobalNames\\
-% |\CheckChuck|\dotfill \CheckChuck\qquad\qquad\qquad\hbox{}
-% \end{quote}
-% 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}
+% The overlays, numbered from one to three, keep name forms consistent by deleting name control sequence patterns for each new overlay. Otherwise, name patterns would change for each new overlay.
+%
+% \newpage
+%
+% Name conditionals ensure specific, context-dependent forms based on what name has appeared. These conditionals allow the text in each overlay to be order-independent and able to be moved around at will. The first overlay shows the use of \cmd{\ForgetThis} to keep names constant.
+%
+% \begin{tcolorbox}\centering
+% \IfFileExists{beamer01.pdf}{\includegraphics[scale=0.6]{beamer01.pdf}}
+% {\hbox{\vbox to 8cm{\hbox{\hfill}}}}
+% \end{tcolorbox}
+% \IndexName[George]{Washington}
+% \IndexName[Ulysses S.]{Grant}
+% \medskip
+%
+% The second overlay uses \cmd{\ForgetName} forcing specific name forms respective to each overlay, instead of respective to the overall sequence of overlays. We also observe the use of name conditionals in text elements that one might reorder.
+%
+% \begin{tcolorbox}\centering
+% \IfFileExists{beamer02.pdf}{\includegraphics[scale=0.6]{beamer02.pdf}}
+% {\hbox{\vbox to 8cm{\hbox{\hfill}}}}
+% \end{tcolorbox}
+% \IndexName[George]{Washington}
+% \IndexName[Ulysses S.]{Grant}
+%
+% Overlay three fully illustrates how all these features integrate. This could allow a presenter to maintain information used in different presentations, making each element or slide a ``drop-in'' unit that can figure out how to present names, name forms, and related information without extensive retyping.
+%
+% \begin{tcolorbox}\centering
+% \IfFileExists{beamer03.pdf}{\includegraphics[scale=0.6]{beamer03.pdf}}
+% {\hbox{\vbox to 8cm{\hbox{\hfill}}}}
+% \end{tcolorbox}
+% \IndexName[George]{Washington}
+% \IndexName[Ulysses S.]{Grant}
+%
% \ReturnLink
+%
+% \AltFormatActive
+% \begin{Quote}{\ForgetThis\Shak\break
+% \hbox{}\hfill ``Romeo and Juliet'', Act II, Scene II}
+% 'Tis but thy name that is my enemy;\dots\\
+% What's in a name? That which we call a rose\\
+% By any other name would smell as sweet;\\
+% So Romeo would, were he not Romeo call'd,\\
+% Retain that dear perfection which he owes\\
+% Without that title. Romeo, doff thy name,\\
+% And for that name which is no part of thee\\
+% Take all myself.
+% \end{Quote}
+% \AltFormatInactive
+%
% \newpage
%
-% \subsubsection{Testing Decisions}
-% \label{sec:NameTests}
+% \section{Name Authority Basics}
%
-% The macros in this section test for the presence or absence of a name, then expand to a result based on the outcome of the test.\medskip
-%
-% \DescribeMacro{\GlobalNameTest}
-% The default behavior encapsulates the decision paths in a local scope, insulating any changes therein.
-% \DescribeMacro{\LocalNameTest}
-% If this is not desired, use the \texttt{globaltest} option or \cmd{\GlobalNameTest}. \cmd{\LocalNameTest} will enable it again.\Version{3.5} These commands affect assignment statements in test paths. By default, one must explicitly use \cmd{\global} when desired. See also the example below.\medskip
+% \subsection{Variant Names}
+% \label{sec:VarNames}
%
-% \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}
-% \fbox{
-% \begin{tabular}{@{}l@{}}
-% {\Large\strut}\cmd{\IfMainName}\oarg{FNN}\marg{SNN|,| Affix}\oarg{Alternate}\marg{yes}\marg{no}\\
-% \end{tabular}
-% }
-% \end{quote}
+% This section explains how to manage simpler surname variants. There are several ways that \textsf{nameauth} can handle variants, in increasing levels of complexity.
%
-% For example we have not encountered |\Name[Bob]{Hope}| yet. Using \cmd{\IndexName} does not affect the tests in this section. We could do the following test that will reflect whether or not the name is present:
-% \begin{quote}\small
-% \StartNum
-% \begin{verbatim}
-%I heard someone say: \IfMainName[Bob]{Hope}
-% {Bob here!}
-% {No Bob here.}\IndexName[Bob]{Hope}\end{verbatim}
+% \begin{enumerate}
+% \item Use \meta{Alternate} to create variant forms, yet retain consistent
+% index entries. This is the default function of \textsf{nameauth} that
+% readers already have seen.
+% \item Create several names. Index one or more occurrences of these names
+% as ``standard'' variants that refer to each other via \textit{see also}
+% references. In relation to the ``standard'' variants, any other variants
+% would be indexed only with a \textit{see} reference. The macros
+% \cmd{\JustIndex}, \cmd{\IndexName}, and \cmd{\IndexRef} play a big role
+% here (Sections~\ref{sec:IndexPageno} and~\ref{sec:IndexRef}).
+% \item Use alternate formatting, \cmd{\noexpand}, and macros in the name
+% arguments that expand differently under specific conditions in the
+% formatting hooks, but expand consistently when indexed.
+% \end{enumerate}
%
-% I heard someone say: \IfMainName[Bob]{Hope}
-% {Bob here!}
-% {No Bob.}\IndexName[Bob]{Hope}
-% \end{quote}
+% We will repeat the following rule in the discussion of Roman names (Section~\ref{sec:Romani}) and in the discussion of alternate formatting (Section~\ref{sec:AltFormat}). One cannot overstate this point when using mutable macros in name arguments:
%
-% Now we test for |\Name{Elizabeth,I}|, a name that has occurred, and we also show the difference between local and global test paths:
-% \begin{quote}\small
-% \StartNum
-% \begin{verbatim}
-%\GlobalNameTest
-%\def\msg{We are unsure about \LEliz}
-%\IfMainName{Elizabeth,I}
-% {\def\msg{We really do know of \LEliz}}
-% {\def\msg{We do not know of \LEliz}}
-% \msg\quad (\cmd{\GlobalNameTest}).
-%
-%\LocalNameTest
-%\def\msg{We are unsure about \LEliz}
-%\IfMainName{Elizabeth,I}
-% {\def\msg{We really do know of \LEliz}}
-% {\def\msg{We do not know of \LEliz}}
-% \msg\quad (\cmd{\LocalNameTest}).\end{verbatim}
-% \smallskip
+% \NameArgWarning
%
-% \GlobalNameTest
-% \def\msg{We are unsure about \LEliz}
-% \IfMainName{Elizabeth,I}
-% {\def\msg{We really do know of \LEliz}}
-% {\def\msg{We do not know of \LEliz}}
-% \msg\quad (\cmd{\GlobalNameTest}).
+% \subsubsection[Alternate Argument]{Variants and the Alternate Argument}
%
-% \LocalNameTest
-% \def\msg{We are unsure about \LEliz}
-% \IfMainName{Elizabeth,I}
-% {\def\msg{We really do know of \LEliz}}
-% {\def\msg{We do not know of \LEliz}}
-% \msg\quad (\cmd{\LocalNameTest}).
-% \end{quote}
-% We see that the default keeps local any assignments made in the test paths.\medskip
+% We begin with the first kind of variant names listed above. We decide that the canonical name to be used is \Tyson. We set up both the canonical name and a alternate name in the \texttt{nameauth} environment:
%
-% \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}
-% \fbox{
-% \begin{tabular}{@{}l@{}}
-% {\Large\strut}\cmd{\IfFrontName}\oarg{FNN}\marg{SNN|,| Affix}\oarg{Alternate}\marg{yes}\marg{no}\\
-% \end{tabular}
-% }
+% \begin{quote}\small
+% \vspace{4ex}
+% \PatInfo{\ShowPattern[Mike]{Tyson}!MN}
+% \vspace{-4ex}
+% \begin{Verbatim}
+% \begin{nameauth}
+% \< Tyson & Mike & Tyson & >
+% \< Iron & Mike & Tyson & Iron Mike >
+% \end{nameauth}
+% \end{Verbatim}
+% \end{quote}
+%
+% When one takes advantage of \meta{Alternate}, all index page entries for the name variants occur under the canonical entry. The only additional step that one needs to include is a cross-reference: \cmd{\IndexRef\{Iron Mike\}\{Tyson, Mike\}}\IndexRef{Iron Mike}{Tyson, Mike} which will produce ``Iron Mike \textit{see} Tyson, Mike'' in the index.
+%
+% \begin{quote}\small\medstretch
+% \begin{tabular}{rlrl}\toprule
+% Macro & Output & Macro & Output\\
+% \rowcolor{nagrey}\cmd{\LIron} \qquad & \LIron &
+% \cmd{\LTyson[Iron Mike]} & \LTyson[Iron Mike]\\
+% \cmd{\Iron} & \Iron & \cmd{\Tyson} & \Tyson\\
+% \rowcolor{nagrey}\cmd{\SIron} & \SIron & \cmd{\STyson} &
+% \STyson\\\bottomrule
+% \end{tabular}
% \end{quote}
-% This macro works just like \cmd{\IfMainName}, except using the ``front matter'' name control sequences as the test subject. These testing macros prove their worth especially through combination. For example, on the next page we do a test based on Section~\ref{sec:Formatting}.
-% \newpage
%
-% \phantomsection\label{page:Carnap}
+% Yet \meta{Alternate} does more than handle variant forenames in Western name forms. It can be used to manage alternate names in Eastern and ancient forms, as we have already seen. For this to work properly, we must have a name where \meta{SNN} and \meta{Affix} are both populated in order to use \meta{Alternate}. Otherwise, one winds up with the obsolete syntax (Section~\ref{sec:Obsolete}).
+%
+% We will engage this topic more, beginning with Section~\ref{sec:NameAncient}, Here we give a basic illustration of how one can start to manage these names. For instance:
+%
% \begin{quote}\small
-% \StartNum
-% \begin{verbatim}
-%\IfFrontName[Rudolph]{Carnap}
-%{%
-% \IfMainName[Rudolph]{Carnap}
-% {\Name[Rudolph]{Carnap} is in both main- and front-matter text.}
-% {\Name[Rudolph]{Carnap} is only in front-matter text.}
-%}%
-%{%
-% \IfMainName[Rudolph]{Carnap}
-% {\Name[Rudolph]{Carnap} is only in main-matter text.}
-% {\Name[Rudolph]{Carnap} has not been mentioned.}
-%}\end{verbatim}
+% \vspace{4ex}
+% \PatInfo{\ShowPattern{Elizabeth, I}!MN}
+% \vspace{-4ex}
+% \begin{Verbatim}
+% \begin{nameauth}
+% \< Eliz & & Elizabeth, I & >
+% \end{nameauth}
%
-% \IfFrontName[Rudolph]{Carnap}
-% {%
-% \IfMainName[Rudolph]{Carnap}
-% {\Name[Rudolph]{Carnap} is in both main- and front-matter text.}
-% {\Name[Rudolph]{Carnap} is only in front-matter text.}
-% }%
-% {%
-% \IfMainName[Rudolph]{Carnap}
-% {\Name[Rudolph]{Carnap} is only in main-matter text.}
-% {\Name[Rudolph]{Carnap} has not been mentioned.}
-% }
-% \end{quote}
+% \LEliz[I, ``Gloriana''] was known also as
+% \ForceFN\SEliz[``Good Queen Bess''].
+% \IndexRef{Gloriana}{Elizabeth I}
+% \IndexRef[Good Queen]{Bess}{Elizabeth I}
+% \end{Verbatim}
%
-% \DescribeMacro{\IfAKA}
-% This macro tests whether or not a regular or excluded form of cross-reference control sequence exists. The syntax is:
-% \begin{quote}
-% \fbox{
-% \begin{tabular}{@{}l@{}}
-% {\Large\strut}^^A
-% \cmd{\IfAKA}\oarg{FNN}\marg{SNN|,|Affix}\oarg{Alternate}\marg{y}\marg{n}\marg{excl}\\
-% \end{tabular}
-% }
+% \LEliz[I, ``Gloriana''] was known also as
+% \ForceFN\SEliz[``Good Queen Bess''].
% \end{quote}
%
-% This macro also works like \cmd{\IfMainName}, except that it has an additional \meta{excl} branch in order to detect the activity of \cmd{\ExcludeName} (Section~\ref{sec:GeneralIndex}).
+% \subsubsection[Multiple Variants]{Managing Multiple Variant Names}
%
-% Cross-references\Version{3.5} are governed by name control sequences ending in \texttt{!PN} (Section~\ref{sec:NamePatterns}).
-% \begin{itemize}
-% \item Excluded control sequences (the \meta{excl} path) expand to the value of \cmd{\@nameauth@Exclude}.
-% \item Regular cross-references (the \meta{y} path) do not expand to that value. At present, they are empty.
-% \item \cmd{\ExcludeName} creates excluded xrefs. \cmd{\IncludeName} destroys them.
-% \item Regular xrefs are created by \cmd{\IndexRef}, \cmd{\AKA}, \cmd{\PName} and their starred forms. Regular xrefs are destroyed by \cmd{\IncludeName*}.
-% \end{itemize}
-%
-% Based on the known facts above, here we offer some examples about how to use this logic:
-% \begin{enumerate}
-% \item In the\PatInfo{\ShowPattern[Jesse]{Ventura}!MN\break \ShowPattern[James]{Janos}!PN\break \ShowPattern[James]{Janos}!MN} 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}|.
+% With the second class of name variants listed above, we get into pseudonyms, aliases, and variant family names. This class is more complicated:
%
-% \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 \meta{excl} branch empty:
+% \begin{enumerate}
+% \item Names that change capitalization in the surname, take grammatical
+% endings, or vary in other ways. See Sections~\ref{sec:NameParticles},
+% \ref{sec:NameMedieval}, \ref{sec:NameAncient}, \ref{sec:RealAltEx}ff.,
+% and~\ref{sec:Romani}, for increasingly complex examples.
+% \item Names having separate index entries that are linked together with
+% cross-references. Sections~\ref{sec:IndexPageno} and~\ref{sec:IndexRef}
+% give many examples, which we will not repeat here because most of the
+% work is done with indexing macros.
+% \item Names that the author wants to treat as different, yet which the
+% \textsf{nameauth} internals might see as the same. One can use the
+% naming macros, index tagging macros, and formatting macros to simulate
+% the existence of multiple identical names (see below and
+% Section~\ref{sec:IndexTag}).
% \end{enumerate}
+%
+% The following method avoids using macros in name arguments and it is easier to set up. The trade-off is that, while macros in name arguments are harder to set up, they benefit from automation. Below we establish two names and a sort key for the main name under which both names are indexed:
+%
% \begin{quote}\small
-% \StartNum
-% \begin{verbatim}
-%\IfAKA[James]{Janos}%
-% {\Name*[Jesse]{Ventura} is a stage name}%
-% {\Name*[Jesse]{Ventura} is a regular name}%
-% {}\end{verbatim}
+% \begin{Verbatim}
+% \begin{nameauth}
+% \< DuBois & W.E.B. & Du~Bois & >
+% \< AltDuBois & W.E.B. & DuBois & >
+% \end{nameauth}
+% \PretagName[W.E.B.]{Du~Bois}{DuBois, William}
+% \end{Verbatim}
% \end{quote}
%
-% Otherwise, based on Section~\ref{sec:GeneralIndex}, we get:
-% ``\IfAKA{Grinch}
-% {\Name{Grinch} is an alias}
-% {\Name{Grinch} is not an alias}
-% {\Name{Grinch} is excluded}'':
-% \begin{quote}\small\leavevmode\PatInfo{\ShowPattern{Grinch}!PN}\vspace{-5ex}
-% \StartNum
-% \begin{verbatim}
-%``\IfAKA{Grinch}%
-% {\Name{Grinch} is an alias}%
-% {\Name{Grinch} is not an alias}%
-% {\Name{Grinch} is excluded}''\end{verbatim}
-% \end{quote}
+% \begin{itemize}
+% \item Based on\PatInfo{\ShowPattern[W.E.B.]{Du~Bois}!MN\break
+% \ShowPattern[W.E.B.]{DuBois}!MN} historical research and what we can
+% tell from some name authorities, we decide that the the canonical
+% name will be: \cmd{\DuBois} \ForgetThis\DuBois.
+% \item We use the non-breaking space (the tilde active character) because
+% internally, \textsf{nameauth} removes all regular spaces from
+% name patterns. Both \cmd{\Name[W.E.B.]\{Du Bois\}} and
+% \cmd{\Name[W.E.B.]\{DuBois\}} have the same name control pattern:
+% \texttt{\ShowPattern[W.E.B.]{DuBois}} (Section~\ref{sec:NamePatterns}).
+% The name pattern \texttt{\ShowPattern[W.E.B.]{Du~Bois}} differs from
+% both of the other names.
+% \item Another reason to use the non-breaking space is that it prevents
+% a line break between the particle \textit{Du} and the name \textit{Bois}.
+% \item The sort key that could be applicable to both names is
+% \texttt{\{DuBois, William\}}. Had we used the sort key
+% \texttt{\{Du Bois, William\}}, the name would be sorted before
+% \texttt{dual}, which is not in order (Section~\ref{sec:IndexInitials}).
+% \item Instead of using \cmd{\SkipIndex}\cmd{\AltDuBois} many times, we
+% create a cross-reference before the alternate name is used to prevent
+% index page entries from being created for the alternate form:
+% \IndexRef[W.E.B.]{DuBois}{Du Bois, W.E.B.}\smallskip\\
+% | \IndexRef[W.E.B.]{DuBois}{Du Bois, W.E.B.}|
+% \item We can keep full stop detection, modify name forms, and check
+% if the name straddles a page break in order to append
+% |\JustIndex\DuBois| if needed:
+%
+% \begin{VerbatimOut}{\jobname.tmp}
+% \newcommand\VarDuBois{\JustIndex\DuBois\AltDuBois}
+% \newcommand\LVarDuBois{\JustIndex\DuBois\LAltDuBois}
+% \newcommand\SVarDuBois{\JustIndex\DuBois\SAltDuBois}
+% Speaking of \VarDuBois[William E.B.].\\
+% Speaking of \LVarDuBois.\\
+% Speaking of \SVarDuBois[William E.B.].
+% \end{VerbatimOut}
%
-% 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}
+% \VerbatimInput[gobble=0]{\jobname.tmp}
%
-% If\Info{Sync with floats} one uses names in floats and in the text, the testing macros can synchronize a float with the text. Assume that we want to print a full name for whichever appears first, like \LJWG[Johann Wolfgang von] instead of \LJWG. In both the text and the float we use the following:
-% \begin{quote}\small\leavevmode\PatInfo{\ShowPattern[J.W. von]{Goethe}!MN}\vspace{-5ex}
-% \StartNum
-% \begin{verbatim}
-%\IfMainName[J.W. von]{Goethe}
-% {\Name*[J.W. von]{Goethe}}
-% {\Name*[J.W. von]{Goethe}[Johann Wolfgang von]}\end{verbatim}
+% \input{\jobname.tmp}
% \end{quote}
%
-% Text tags can work\Info{Sync with events} with the conditional macros to prevent anachronistic references. This aids working with history texts, game books, and so on. One must avoid unbounded recursion that results in a stack overflow (Section~\ref{sec:TextTags}):
-% \begin{quote}\small\leavevmode\PatInfo{\ShowPattern{Paul}!PN\break \ShowPattern{Saul, of Tarsus}!DB\break \ShowPattern{Jesus, Christ}!MN\break \ShowPattern[Lucius]{Sergius Paulus}!MN\break \ShowPattern{Paul}!MN\break \ShowPattern{Saul, of Tarsus}!MN}\vspace{-5ex}
-% \StartNum
-% \begin{verbatim}
-%\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}}
-%\Name{Saul, of Tarsus} \NameQueryInfo{Saul, of Tarsus}.
-%He saw a vision of \Name{Jesus, Christ} on the road to Damascus.
-%\Name{Saul, of Tarsus} became \NameQueryInfo{Saul, of Tarsus}.
-%After converting \Name[Lucius]{Sergius Paulus},
-%\Name{Saul, of Tarsus} \NameQueryInfo{Saul, of Tarsus}.\end{verbatim}
+% \item The macro below loses full stop detection, but it does
+% automatically handle the name spanning a page break, just like the
+% regular naming macros. Yet it is rather inelegant.
%
-% \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}}
-% \Name{Saul, of Tarsus} \NameQueryInfo{Saul, of Tarsus}.
-% He saw a vision of \Name{Jesus, Christ} on the road to Damascus.
-% \Name{Saul, of Tarsus} became \NameQueryInfo{Saul, of Tarsus}.
-% After converting \Name[Lucius]{Sergius Paulus},
-% \Name{Saul, of Tarsus} \NameQueryInfo{Saul, of Tarsus}.
+% \begin{quote}\small
+% \begin{Verbatim}
+% \newcommand\NewDuBois[2]{%
+% \def\Test{#1}%
+% \def\Long{L}%
+% \def\Short{S}%
+% \JustIndex\DuBois%
+% \ifx\Test\Long \LAltDuBois[#2] \else
+% \ifx\Test\Short \SAltDuBois[#2] \else
+% \AltDuBois \fi\fi
+% \JustIndex\DuBois}
+% \ForgetThis\NewDuBois{}{William E.B.}\\
+% \NewDuBois{L}{}\\
+% \NewDuBois{S}{William}
+% \end{Verbatim}
+% \medskip
+% \newcommand\NewDuBois[2]{^^A
+% \def\Test{#1}^^A
+% \def\Long{L}^^A
+% \def\Short{S}^^A
+% \JustIndex\DuBois^^A
+% \ifx\Test\Long \LAltDuBois[#2] \else
+% \ifx\Test\Short \SAltDuBois[#2] \else
+% \AltDuBois[#2] \fi\fi
+% \JustIndex\DuBois}
+% \ForgetThis\NewDuBois{}{William E.B.}\\
+% \NewDuBois{L}{}\\
+% \NewDuBois{S}{William}
% \end{quote}
+% \end{itemize}
%
-% Using these tests\Info{Caveats} 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.
+% \begin{Quote}{\ForgetThis\DuBois\break
+% \hbox{}\hfill \textit{Darkwater} (1920), C II: The Souls of White Folk}
+% The cause of war is preparation for war.\vspace{-1ex}
+% \end{Quote}
%
-% \ReturnLink
% \newpage
%
-% \subsection{Alternate Name Macros}
-% \label{sec:AKA}
+% \subsubsection[Nonstandard Caps]{Nonstandard Capitalization and Indexing}
+% \label{sec:NonstandardCaps}
%
-% The\Version{3.0} macros in this section predate \cmd{\IndexRef} and are less flexible than just using \cmd{\IndexRef} with \cmd{\Name} (cf. page~\pageref{page:IdxVariants}). We recommend the macros below only for backward compatibility, or if one likes using them. To save space, we show the syntax of these macros using \meta{SAFX} as the equivalent of \meta{SNN|,| Affix}.
+% Here we look at nonstandard capitalization. We consider poet \ForgetThis\Name[e.e.]{cummings}. As long as one sticks with the default \texttt{noformat} option, the easiest solution is to begin a sentence with something like:
%
-% \begin{itemize}
-% \item These macros do not create page references.
-% \item Opposite of \cmd{\IndexRef}, the target \oarg{FNN}\marg{SAFX} comes first; then the cross-reference \oarg{xref FNN}\marg{xref SAFX}\oarg{xref Alternate}.
-% \item The obsolete syntax cannot be used with \oarg{FNN}\marg{SAFX}; it can be used with \oarg{xref FNN}\marg{xref SAFX}\oarg{xref Alternate}.
-% \item Only \meta{SAFX} and \meta{xref SAFX} can have 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}
+% \begin{VerbatimOut}{\jobname.tmp}
+% \SubvertThis\CapThis\Name[e.e.]{cummings}'s motif of the
+% goat-footed balloon man has underlying sexual themes that
+% nevertheless have a childish facade.
+% \end{VerbatimOut}
%
-% \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*}
-% They format names differently than \cmd{\Name}, etc.:
% \begin{quote}\small
-% \fbox{
-% \begin{tabular}{@{}l@{}}
-% {\Large\strut}\cmd{\AKA\ }\oarg{FNN}\marg{SAFX}\oarg{xref FNN}\marg{xref SAFX}\oarg{xref Alternate} \vspace{-2pt}\\
-% {\Large\strut}\cmd{\AKA*}\oarg{FNN}\marg{SAFX}\oarg{xref FNN}\marg{xref SAFX}\oarg{xref Alternate}\\
-% \end{tabular}
-% }
+% \vspace{4ex}
+% \BothInfo{\ShowPattern[e.e.]{cummings}!MN}
+% {\ShowIdxPageref*[e.e.]{cummings}}
+% \vspace{-4ex}
+% \VerbatimInput[gobble=0]{\jobname.tmp}
+% \renewcommand*\NamesFormat{}
+% \renewcommand*\MainNameHook{}
+%
+% \input{\jobname.tmp}
% \end{quote}
%
-% \begin{itemize}
-% \item 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}.
-% \item The order of the name and cross-reference in \cmd{\AKA} is opposite that of \cmd{\IndexRef} in order to avoid ambiguity.
-% \item \cmd{\AKA} prints a long form of the cross-reference name in the text. \cmd{\SeeAlso} works with \cmd{\AKA}, \cmd{\AKA*}, \cmd{\PName}, and \cmd{\PName*}.
-% \item \cmd{\AKA} prints the \meta{xref FNN} and \meta{xref SAFX} arguments in the text.
-% \item If \meta{xref Alternate} is present with \meta{xref FNN}, or if \meta{xref Affix} when \meta{xref FNN} is absent, \cmd{\AKA} swaps them only in the text.
-% \item If \meta{xref Alternate} is present without \meta{xref FNN} and \meta{xref Affix}, the obsolete syntax is used.
-% \item \cmd{\AKA*}\Version{3.0} is analogous to \cmd{\FName} and \cmd{\ForceFN} works with it. The \texttt{oldAKA} option implies \cmd{\ForceFN} with every use of \cmd{\AKA*}.
-% \item Neither\Version{3.5} \cmd{\AKA} nor its derivatives permit the effects of \cmd{\ForgetThis} and \cmd{\SubvertThis} to ``pass through'' because they produce output in the text. The \texttt{oldreset} option negates this.
-% \end{itemize}
+% Suppose, however, that we want both some kind of name formatting and still use capitalization. We can use the indexing macros discussed in Section~\ref{sec:GeneralIndex}:
%
-% We make cross-references to \Name[Bob]{Hope}; all of the forms below will create the cross-reference ``\ShowIdxPageref*[Leslie Townes]{Hope} \textit{see} \ShowIdxPageref*[Bob]{Hope}'':
-% \begin{center}\footnotesize\vspace{2ex}\Info{\strut\footnotesize Name Pattern(s):\hfill \break \ttfamily \ShowPattern[Bob]{Hope}!MN\break \ShowPattern[Leslie Townes]{Hope}!PN}\vspace{-2ex}\MyStretch
-% \begin{tabular}{p{0.6\textwidth}l}\toprule
-% |\AKA[Bob]{Hope}[Leslie Townes]{Hope}| & \AKA[Bob]{Hope}[Leslie Townes]{Hope}\\
-% \rowcolor{grey}|\RevComma\AKA[Bob]{Hope}[Leslie Townes]{Hope}| & \RevComma\AKA[Bob]{Hope}[Leslie Townes]{Hope}\\
-% |\AKA[Bob]{Hope}[Leslie Townes]{Hope}[Lester T.]| & \AKA[Bob]{Hope}[Leslie Townes]{Hope}[Lester T.]\\
-% \rowcolor{grey}|\AKA*[Bob]{Hope}[Leslie Townes]{Hope}| & \AKA*[Bob]{Hope}[Leslie Townes]{Hope}\\
-% |\AKA*[Bob]{Hope}[Leslie Townes]{Hope}[Lester]| & \AKA*[Bob]{Hope}[Leslie Townes]{Hope}[Lester]\\\bottomrule
-% \end{tabular}
-% \end{center}
+% \begin{VerbatimOut}{\jobname.tmp}
+% \ExcludeName[e.e.]{cummings's}\IndexName[e.e.]{cummings}
+% \SubvertThis\CapThis\Name[e.e.]{cummings's} motif of the
+% goat-footed balloon man has underlying sexual themes that
+% nevertheless have a childish facade.
+% \end{VerbatimOut}
%
-% Next we refer to \KeepAffix\Name*{Louis, XIV}, and \Name{Lao-tzu}, as well as \Name[Lafcadio]{Hearn} and \Name[Charles]{du~Fresne}. The caps and reversing macros work. Even with \cmd{\ForceName}, the formatting hooks do not change. \cmd{\AKA} and its derivatives use only \cmd{\MainNamesHook} and \cmd{\FrontNamesHook}.
+% \begin{quote}\small
+% \vspace{4.5ex}
+% \PatInfo{\ShowPattern[e.e.]{cummings's}}
+% \vspace{-4.5ex}
+% \VerbatimInput[gobble=0]{\jobname.tmp}
%
-% \begin{center}\small\vspace{2ex}\PatInfo{\ShowPattern{Louis, XIV}!MN\break \ShowPattern{Lao-tzu}!MN\break \ShowPattern[Lafcadio]{Hearn}!MN\break \ShowPattern[Charles]{du~Fresne}!MN\break \ShowPattern{Sun King}!PN\break \ShowPattern{Li, Er}!PN\break \ShowPattern{du~Cange}!PN\break \ShowPattern{Koizumi, Yakumo}!PN}\vspace{-2ex}\MyStretch
-% \begin{tabular}{p{0.65\textwidth}l}\toprule
-% \rowcolor{grey}|\AKA{Louis, XIV}{Sun King}| & \AKA{Louis, XIV}{Sun King}\\
-% |\ForceName\AKA{Louis, XIV}{Sun King}| & \ForceName\AKA{Louis, XIV}{Sun King}\\
-% \rowcolor{grey}|\AKA*{Louis, XIV}{Sun King}| & \AKA{Louis, XIV}{Sun King}\\
-% |\AKA{Lao-tzu}{Li, Er}| & \AKA{Lao-tzu}{Li, Er}\\
-% \rowcolor{grey}|\AKA*{Lao-tzu}{Li, Er}| & \AKA*{Lao-tzu}{Li, Er}\\
-% |\AKA[Charles]{du~Fresne}{du~Cange}| & \AKA[Charles]{du~Fresne}{du~Cange}\\
-% \rowcolor{grey}|\CapThis\AKA[Charles]{du~Fresne}{du~Cange}| & \CapThis\AKA[Charles]{du~Fresne}{du~Cange}\\
-% |\CapName\AKA[Lafcadio]{Hearn}{Koizumi, Yakumo}| & \CapName\AKA[Lafcadio]{Hearn}{Koizumi, Yakumo}\\
-% \rowcolor{grey}|\RevName\AKA[Lafcadio]{Hearn}{Koizumi, Yakumo}| & \RevName\AKA[Lafcadio]{Hearn}{Koizumi, Yakumo}\\\bottomrule
-% \end{tabular}
-% \end{center}\medskip
+% \input{\jobname.tmp}
+% \end{quote}
%
-% In order to format\Info{\texttt{formatAKA}} cross-references like names, either avoid using these older macros or use the \texttt{formatAKA} option. That allows \cmd{\ForceName} to work properly, 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}|:
+% In both examples above, we\Warn{} use \cmd{\SubvertThis} to force a subsequent use in order to prevent a first use that looks like ``\ForgetThis\CapThis\Name[e.e.]{cummings's}''. The macro \cmd{\CapThis} will capitalize the first letter in all name elements. Using \cmd{\ExcludeName} keeps one from having to use \cmd{\SkipIndex} every time.
%
-% \begin{center}\small\vspace{2ex}\PatInfo{\ShowPattern{Elizabeth, I}!NF\break \ShowPattern[Good Queen]{Bess}!PN\break \ShowPattern{Elizabeth, I}!MN}\vspace{-2ex}\MyStretch
-% \makeatletter\@nameauth@AKAFormattrue\makeatother
-% \begin{tabular}{rlll}\toprule
-% \global\NamesInactive Front Matter: & \ForgetThis\Eliz & \Eliz & \AKA{Elizabeth,I}[Good Queen]{Bess}\\
-% \rowcolor{grey}\global\NamesActive Main Matter: & \ForgetThis\Eliz & \Eliz & \AKA{Elizabeth, I}[Good Queen]{Bess}\\
-% Using \cmd{\ForceName}: & & & \ForceName\AKA{Elizabeth, I}[Good Queen]{Bess}\\\bottomrule
-% \end{tabular}
-% \end{center}
+% Section~\ref{sec:AltFormat} explains how to use \cmd{\CapThis} with alternate formatting when using macros in name arguments. Section~\ref{sec:InflNames} describes how automation lends itself to grammatical inflections of names.\medskip
%
-% The first appearance of \AKA{Elizabeth,I}[Good Queen]{Bess} uses either \cmd{\NamesFormat} or \cmd{\FrontNamesFormat}. After that, only \cmd{\mainNameHook} and \cmd{\FrontNameHook} can be used without \cmd{\ForceName}, which triggers the first-use hooks.\medskip
+% \subsubsection[Variants and Xrefs]{Variant Names and Index Cross-References}
+% \label{sec:IdxVariants}
%
-% Below\Info{\texttt{alwaysformat}} we compare the behavior of the \texttt{alwaysformat} option, where all regular names use only \cmd{\NamesFormat} and \cmd{\FrontNamesFormat}:
+% Here we show differences among variants and cross-references. We can choose to index variants under the canonical name or we can set up cross-references with variants. The order in which we do that is significant:
%
-% \begin{quote}\small\MyStretch
-% \makeatletter\@nameauth@AlwaysFormattrue\makeatother
-% \ForgetThis\LEliz\ was known as ``\AKA{Elizabeth,I}[Good Queen]{Bess}''. Again we mention Queen \Eliz, ``\AKA{Elizabeth, I}[Good Queen]{Bess}''. Using \cmd{\ForceName}: \ForceName\AKA{Elizabeth, I}[Good Queen]{Bess}.
-% \end{quote}
+% \begin{enumerate}
+% \item We use\PatInfo{\ShowPattern[J.E.]{Carter, Jr.}!MN\hfill
+% \textrm{(1--2)}\break
+% \ShowPattern[Jimmy]{Carter}!PN\hfill \textrm{(3, 6)}\break
+% \ShowPattern[Jimmy]{Carter}!MN\hfill \textrm{(4)}\break
+% \ShowPattern[J.E.]{Carter, Jr.}!PN\hfill
+% \textrm{(5)}}
+% the canonical name to create page references:\smallskip\\
+% \hbox{}\quad|\Name*[J.E.]{Carter, Jr.}|\dotfill
+% \Name*[J.E.]{Carter, Jr.}
+% \item Variants that use \meta{Alternate} in the text create page
+% entries under the canonical form, not the variant form:\smallskip\\
+% \hbox{}\quad|\DropAffix\Name*[J.E.]{Carter, Jr.}[Jimmy]|\dotfill
+% \DropAffix\Name*[J.E.]{Carter, Jr.}[Jimmy]\\
+% \hbox{}\quad|\ShowIdxPageref*[J.E.]{Carter, Jr.}[Jimmy]|\dotfill
+% \ShowIdxPageref*[J.E.]{Carter, Jr.}[Jimmy]
+% \item We must create a \textit{see} reference from an alternate form
+% to a canonical form \emph{before} using the alternate form in a naming
+% macro, or it will be ignored and a warning will result:\smallskip\\
+% \hbox{}\quad|\IndexRef[Jimmy]{Carter}{Carter, J.E., Jr.}|
+% \IndexRef[Jimmy]{Carter}{Carter, J.E., Jr.}
+% \item No page references will occur below because we made the
+% \textit{see} reference first. Note how the alternate form is an
+% independent name:\smallskip\\
+% \hbox{}\quad|\Name[Jimmy]{Carter}|\dotfill \Name[Jimmy]{Carter}
+% \item If we want to index the alternate name, we have to use the
+% canonical name instead of the alternate name:\smallskip\\
+% \hbox{}\quad|\IndexName[J.E.]{Carter, Jr.}|
+% \item If instead we wanted to make a \textit{see also} reference, we
+% would use both the canonical name and the alternate name, then create
+% the cross-reference \emph{after} all uses of the alternate name
+% (at the end of the document), e.g.:\smallskip\\
+% \hbox{}\quad|\SeeAlso\IndexRef[Jimmy]{Carter}{Carter, J.E., Jr.}|
+% \end{enumerate}
+%
+% 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{enumerate}
+% \item We use\PatInfo{\ShowPattern{Maimonides}!MN \textrm{(1)}\break
+% \ShowPattern{Moses, ben-Maimon}!PN \textrm{(2)}\break
+% \ShowPattern{Moses, ben-Maimon}!MN \textrm{(3)}\break
+% \ShowPattern{Rambam}!MN \textrm{(4)}\break
+% \ShowPattern{Rambam}!PN \textrm{(5)}}
+% 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}
+% \item We have a main name with a page entry and a ``\textit{see}
+% reference'' to that name. No page references will occur below because
+% we made the xref first:\smallskip\\
+% \hbox{}\qquad|\Name{Moses, ben-Maimon}|\dotfill \Name{Moses, ben-Maimon}
+% \item Before creating \textit{see also} cross-references, we use the other
+% alias 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{enumerate}
+%
+% There\Info{Multiple targets} is a case where one cross-reference can point to multiple targets, such as demonstrated in the example below:
+%
+% \begin{VerbatimOut}{\jobname.tmp}
+% \PretagName{\textit{Snellius}}{Snellius}
+% \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{VerbatimOut}
%
-% \DescribeMacro{\PName}
-% These convenience macros (an early feature) print a main name and a cross-reference in parentheses:
-% \DescribeMacro{\PName*}
% \begin{quote}\small
-% \fbox{
-% \begin{tabular}{@{}l@{}}
-% {\Large\strut}\cmd{\PName\ }\oarg{FNN}\marg{SAFX}\oarg{xref\,FNN}\marg{xref\,SAFX}\oarg{xref\,Alternate}\vspace{-2pt}\\
-% {\Large\strut}\cmd{\PName*}\oarg{FNN}\marg{SAFX}\oarg{xref\,FNN}\marg{xref\,SAFX}\oarg{xref\,Alternate}\\
-% \end{tabular}
-% }
+% \vspace{5ex}
+% \PatInfo{\ShowPattern{\textit{Snellius}}!PRE\break
+% \ShowPattern{\textit{Snellius}}!PN\break
+% \ShowPattern[W.]{Snel van Royen}!MN\break
+% \ShowPattern[R.]{Snel van Royen}!MN}
+% \vspace{-5ex}
+% \VerbatimInput[gobble=0]{\jobname.tmp}
+%
+% \input{\jobname.tmp}
% \end{quote}
-% 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}.
+%
+% One must plan the location of xrefs or use \cmd{\IncludeName*}. Above, we have no page entry for |\Name{\textit{Snellius}}| because \cmd{\IndexRef} comes first.
+%
+% \begin{Quote}{\ForgetThis\Name{Maimonides},
+% \textit{Guide for the Perplexed} (1190)}
+% For a truth, once established by proof, does neither gain force nor certainty by the consent of all scholars, nor lose by the general dissent.
+% \end{Quote}
+%
+% \newpage
+%
+% \subsection{Using a Name Authority}
+%
+% 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} was typeset using \LaTeX, but had to be converted to a different format.}
+%
+% Constructing that name authority of over 500 names was a challenge. The deceased translator left names in abbreviated Latin. He left many place-names in Latin and incorrectly translated some others. To get valid names that one can research, the present author recommends:
%
% \begin{itemize}
-% \item Most prefix macros only affect \meta{FNN}\meta{SAFX}, not the cross-reference, which always has a long form.
-% \item \cmd{\SkipIndex} keeps both names out of the index.
-% \item \cmd{\PName} allows the obsolete syntax only for the alternate name.
-% \item Even though it is permitted, please avoid using the obsolete syntax with the xref part of \cmd{\PName}, such as \cmd{\PName\{Lao-tzu\}\{Li\}[Er]} and \cmd{\PName\{William, I\}\{William\}[the Conqueror]}.
+% \item \href{https://data.cerl.org/thesaurus/_search}{CERL Thesaurus}
+% \item \href{https://viaf.org/}{Virtual International Authority File}
+% \item \href{https://edit16.iccu.sbn.it/web/edit-16}{EDIT16}
+% \item \href{https://www.worldcat.org/}{WorldCat}
+% \item \href{https://id.loc.gov/authorities/names.html}{Library of Congress}
+% \item \href{https://www.columbia.edu/acis/ets/Graesse/contents.html}
+% {Older version of Graesse, \textit{Orbis Latinus}}
% \end{itemize}
%
-% Alternate names for the non-Western syntax do not work with the name portion of \cmd{\PName}; only the cross-reference portion can support it. 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}''. We use |\ForgetName{William, I}|\ForgetName{William, I} to prepare for the example below that shows the preferred usage of these macros:\footnote{The xref pattern \texttt{\ShowPattern{\textit{Doctor mellifluus}}!PN} is too large for the margin note. With \texttt{pdflatex} and \texttt{latex}, in \texttt{\ShowPattern[François-Marie]{Arouet}!PN} the glyphs \texttt{Ãğ} correspond to the Unicode encoding macro \cmd{\IeC\{}\cmd{\c\ c\}}.}
-%
-% \begin{center}\small\vspace{2ex}\PatInfo{\scriptsize\ShowPattern[Mark]{Twain}!MN\break \ShowPattern[Samuel L.]{Clemens}!PN\break \ShowPattern{Voltaire}!MN\break \ShowPattern[François-Marie]{Arouet}!PN\break \ShowPattern{William, I}!MN\break \ShowPattern{William, the Conqueror}!PN\break \ShowPattern{Bernard, of Clairvaux}!MN\break \ShowPattern{Lao-tzu}!MN\break \ShowPattern{Li, Er}!PN}\vspace{-2ex}\MyStretch
-% \begin{tabular}{p{0.42\textwidth}@{\ \ }p{0.46\textwidth}}\toprule
-% \bfseries\small Macro/Output & \bfseries\small Index\\\midrule
-% \rowcolor{grey}\multicolumn{2}{l}{\cmd{\PName[Mark]\{Twain\}[Samuel L.]\{Clemens\}}}\\
-% \rowcolor{grey}\PName[Mark]{Twain}[Samuel L.]{Clemens} & \ShowIdxPageref*[Samuel L.]{Clemens} \textit{see} \ShowIdxPageref*[Mark]{Twain}\\
-% \rowcolor{grey}\PName[Mark]{Twain}[Samuel L.]{Clemens} & \ShowIdxPageref*[Samuel L.]{Clemens} \textit{see} \ShowIdxPageref*[Mark]{Twain}\\
-% \multicolumn{2}{l}{\cmd{\PName*[Mark]\{Twain\}[Samuel L.]\{Clemens\}[Sam]}}\\
-% \PName*[Mark]{Twain}[Samuel L.]{Clemens}[Sam] & \ShowIdxPageref*[Samuel L.]{Clemens} \textit{see} \ShowIdxPageref*[Mark]{Twain}\\
-% \rowcolor{grey}\multicolumn{2}{l}{\cmd{\PName\{Voltaire\}[François-Marie]\{Arouet\}}}\\
-% \rowcolor{grey}\PName{Voltaire}[François-Marie]{Arouet} & \ShowIdxPageref*[François-Marie]{Arouet} \textit{see} \ShowIdxPageref*{Voltaire}\\
-% \rowcolor{grey}\PName{Voltaire}[François-Marie]{Arouet} & \ShowIdxPageref*[François-Marie]{Arouet} \textit{see} \ShowIdxPageref*{Voltaire}\\
-% \multicolumn{2}{l}{\cmd{\PName\{William, I\}\{William, the Conqueror\}}}\\
-% \PName{William, I}{William, the Conqueror} & \ShowIdxPageref*{William, the Conqueror} \textit{see} \ShowIdxPageref*{William, I}\\
-% \PName{William, I}{William, the Conqueror} & \ShowIdxPageref*{William, the Conqueror} \textit{see} \ShowIdxPageref*{William, I}\\
-% \rowcolor{grey}\multicolumn{2}{l}{\cmd{\PretagName\{}\cmd{\textit\{Doctor mellifluus\}\}\{Doctor mellifluus\}}}\\
-% \rowcolor{grey}\multicolumn{2}{l}{\cmd{\PName\{Bernard, of Clairvaux\}\{}\cmd{\textit\{Doctor mellifluus\}}}\\
-% \rowcolor{grey}\PName{Bernard, of Clairvaux}{\textit{Doctor mellifluus}} & \ShowIdxPageref*{\textit{Doctor mellifluus}} \textit{see} \ShowIdxPageref*{Bernard, of Clairvaux}\\
-% \rowcolor{grey}\PName{Bernard, of Clairvaux}{\textit{Doctor mellifluus}} & \ShowIdxPageref*{\textit{Doctor mellifluus}} \textit{see} \ShowIdxPageref*{Bernard, of Clairvaux}\\
-% \multicolumn{2}{l}{\cmd{\ForgetThis}\cmd{\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}\\\bottomrule
-% \end{tabular}
-% \end{center}
+% I set the vernacular forms as canonical, with the Latin versions referring to them. I re-translated all the place-names. I also did the following:
+%
+% \begin{enumerate*}
+% \item Sort vernacular names with \cmd{\PretagName} due to
+% particles (Section~\ref{sec:IndexSort}).
+% \item If Latin names are only cross-references, use
+% \cmd{\IndexRef}\meta{name args} to generate cross-references
+% before referring to any names (Section~\ref{sec:IndexRef}).
+% \item If Latin names have page references, then place
+% \cmd{\SeeAlso}\cmd{\IndexRef}\meta{name args} as needed
+% at the end of the document, before \cmd{\printindex}.
+% \item Use \cmd{\CapThis} (Section~\ref{sec:NameParticles}).
+% \end{enumerate*}
+%
+% \begin{quote}\small
+% \vspace{3.5ex}
+% \BothInfo{\ShowPattern[Jacques]{De~Pamele}!MN\break
+% \ShowPattern[Jacobus]{Pamelius}!MN\break
+% \ShowPattern[Giovanni]{d'Andrea}!MN\break
+% \ShowPattern[Ioannes]{Andreae}!MN}
+% {\ShowIdxPageref*[Jacques]{De~Pamele}\break
+% \ShowIdxPageref*[Jacobus]{Pamelius}\break
+% \ShowIdxPageref*[Giovanni]{d'Andrea}\break
+% \ShowIdxPageref*[Ioannes]{Andreae}}
+% \vspace{-3ex}
+% \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}
+% \end{quote}
+% \negmedskip
+%
+% \IndexRef[Jacobus]{Pamelius}{De~Pamele, Jacques}
+% \IndexRef[Ioannes]{Andreae}{d'Andrea, Giovanni}
+% \begin{itemize}[leftmargin=3.5cm]
+% \item[Canonical Name] |\Name[Jacques]{De~Pamele}[Jacques de~Joigny]|\\
+% \Name[Jacques]{De~Pamele}[Jacques de~Joigny]
+% \item[Latin Name] |\Name[Jacobus]{Pamelius}|
+% \Name[Jacobus]{Pamelius}
+% \item[Canonical Name] |\Name[Giovanni]{d'Andrea}|
+% \Name[Giovanni]{d'Andrea}
+% \item[Latin Name] |\Name[Ioannes]{Andreae}|
+% \Name[Ioannes]{Andreae}
+% \end{itemize}
+%
+% \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}.\negmedskip
%
% \ReturnLink
-% \BigBlank
+%
% \newpage
%
-% \begingroup^^A General format hook redefinition.
-% \subsection{Longer Examples}
-% \label{sec:Hooks}
+% \section{Advanced Formatting}
+% \label{sec:AdvancedFormat}
%
-% For the rest of this manual, many examples are in \texttt{examples.tex} with the \textsf{nameauth} documentation. Here we set the formatting hooks to the package default.
-% \renewcommand*\NamesFormat{}
-% \renewcommand*\FrontNamesFormat{}
-% \renewcommand*\MainNameHook{}
-% \renewcommand*\FrontNameHook{}
+% Up to this point, formatting hooks have taken a name whose form was set in the internal name parser and the hooks applied some typographic changes to that name.
%
-% A reminder: 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 this section we start using formatting hooks in ways that interact with and change the syntactic form of a name, perhaps in addition to making typographic changes to that name.
%
-% \subsubsection{Hooks: Intro}
-% \label{sec:Hooksi}
+% We thus merge the two concepts of syntax and formatting to create more complex examples that are able to do more complicated things with names. We thus can meet a few specific, real-world cultural expectations and scholarly conventions.
%
-% 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. Unlike the rest of this section, we do not change formatting macros within a scope. Instead, we illustrate a different approach using \cmd{\let} to save the old value, then restore it later.
-% \begin{quote}\small
-% \StartNum
-% \begin{verbatim}
-%\let\OldFormat\NamesFormat
-%\renewcommand*\NamesFormat[1]{\textbf{#1}\unless\ifinner
-% \marginpar{\raggedleft\scriptsize #1}\fi}
-%\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:
+% Before we delve into this section, below we see a general scheme of how the core name engine processes a name:\bigskip
+%
+% \begin{tcolorbox}[colback=white,
+% adjusted title={\bfseries Naming Macro Layer}]
+%
+% Naming macros \cmd{\Name}, \cmd{\Name*}, \cmd{\FName}, \cmd{\FName*}, and
+% the macros created by the \texttt{nameauth} environment all send their
+% arguments to three hooks that, by default, point to \cmd{\@nameauth@Name}
+% (Section~\ref{sec:FullCustomize}). Here \cmd{\@nameauth@Name} handles the
+% work requested by \cmd{\JustIndex}, \cmd{\SubvertThis}, \cmd{\ForgetThis},
+% and \cmd{\SkipIndex}. It then hands off the name arguments to the name
+% parser, either with a main-matter \texttt{!MN} suffix or a front-matter
+% \texttt{!NF} suffix\dots
+%
+% \begin{tcolorbox}[colframe=naslate,colback=white,
+% adjusted title={\bfseries Syntactic Element Layer}]
+%
+% \cmd{\@nameauth@Parse}: Determine name category, capitalization,
+% punctuation, elements to be used, and pass on to\dots
+%
+% \begin{tcolorbox}[colframe=nablue,colback=white,
+% adjusted title={\sffamily\bfseries Name Display Layer}]
+%
+% \cmd{\@nameauth@NonWest}: Consult rules, construct displayed form.\\
+% \cmd{\@nameauth@West}: Consult rules, construct displayed form.\\
+% \cmd{\@nameauth@Form}: ``Magic Eight Ball'' of rules for name forms.
+% Includes checking if a name control sequence exists, checking which is
+% the calling macro, and so on. Pass the information to\dots
+%
+% \begin{tcolorbox}[colframe=nared,colback=white,
+% adjusted title={\sffamily\bfseries Format Hook Dispatcher}]
+%
+% \cmd{\@nameauth@Hook}: Check the name to be printed for a final full
+% stop. Check which naming system we are using.
+%
+% Call a formatting hook depending on if our name control sequence
+% pattern exists, and if we are in the main-matter system or the
+% front-matter system. The formatting hook prints the name in the text.
+%
+% \end{tcolorbox}
+%
+% \end{tcolorbox}
+%
+% \cmd{\@nameauth@Parse}: Make name control sequence from name pattern.
+%
+% \end{tcolorbox}
+%
+% \cmd{\@nameauth@NameEngine}: If the final full stop flag is true, check
+% the lookahead token for a full stop and gobble it if needed.
+%
+% \end{tcolorbox}
+%
+% \newpage
+%
+% \subsection{Formatting Hooks}
+% \label{sec:ComplexHooks}
+%
+% This proof of concept puts the first mention of a name either in italics (front matter) or in boldface (main matter), and it adds a margin note if that is allowed. We use \cmd{\let} to save and restore the old hooks, although we also could use a group to keep format changes in a local scope:
+%
+% \ifdefined\NameauthDoTestFiles \edef\NameauthTestFile{test11_01.tex}\else
+% \edef\NameauthTestFile{\jobname.tmp}\fi
+%
+% \begin{VerbatimOut}{\NameauthTestFile}
+% \documentclass{article}
+% \input{compat.tex} % Included with nameauth; needed only if
+% % compiling on multiple TeX distros or LaTeX engines.
+% \usepackage{makeidx}
+% \usepackage{nameauth}
+% \makeindex
+%
+% % First save main- and front-matter hooks. Then change
+% % first-use hooks for both main matter and front matter.
% \let\OldFormat\NamesFormat
+% \let\OldFrontNames\FrontNamesFormat
+%
% \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}
+% \marginpar{\raggedleft\scriptsize #1}\fi}
+% \renewcommand*\FrontNamesFormat[1]{\textit{#1}\unless\ifinner
+% \marginpar{\raggedleft\scriptsize #1}\fi}
+%
+% \PretagName{Vlad, {\c T}epe{\c s}}{Vlad Tepes} % for accented names
+% \TagName{Vlad, II}{ Dracul} % for index information
+% \TagName{Vlad, III}{ Dracula}
+% \IndexRef{Dracula}{Vlad III}
+%
+% \begin{document}
+%
+% The new format (front matter):\NamesInactive
%
% \Name{Vlad, III}[III Dracula], known as
-% \AKA{Vlad III}{Vlad, Ţepeş} (the Impaler)
+% \IndexRef{Vlad, {\c T}epe{\c s}}{Vlad III}
+% \SubvertThis\Name*{Vlad, {\c T}epe{\c s}}
+% (\Name*{Vlad, {\c T}epe{\c s}}[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.
+%
+% The new format (main matter):\NamesActive
+%
+% \Name{Vlad, III}[III Dracula], known as
+% \IndexRef{Vlad, {\c T}epe{\c s}}{Vlad III}
+% \SubvertThis\Name*{Vlad, {\c T}epe{\c s}}
+% (\Name*{Vlad, {\c T}epe{\c s}}[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}
+% \let\FrontNamesFormat\OldFrontNames
+%
+% We are back in the old format.
+%
+% in the front matter we see: \NamesInactive
+% \ForgetThis\Name{Vlad, III}[III Dracula],
+% \Name*{Vlad, III}, and \Name{Vlad, III}.
+%
+% in the main matter we see: \NamesActive
+% \ForgetThis\Name{Vlad, III}[III Dracula],
+% \Name*{Vlad, III}, and \Name{Vlad, III}.
+%
+% \printindex
+% \end{document}
+% \end{VerbatimOut}
+%
+% \begin{quote}\small
+% \VerbatimInput[gobble=0]{\NameauthTestFile}
+%
+% \let\OldFormat\NamesFormat
+% \let\OldFrontNames\FrontNamesFormat
+%
+% \renewcommand*\NamesFormat[1]{\textbf{#1}\unless\ifinner
+% \marginpar{\raggedleft\scriptsize #1}\fi}
+% \renewcommand*\FrontNamesFormat[1]{\textit{#1}\unless\ifinner
+% \marginpar{\raggedleft\scriptsize #1}\fi}
+%
+% The new format (front matter):\NamesInactive
+%
+% \Name{Vlad, III}[III Dracula], known as
+% \IndexRef{Vlad, {\c T}epe{\c s}}{Vlad III}
+% \SubvertThis\Name*{Vlad, {\c T}epe{\c s}}
+% (\Name*{Vlad, {\c T}epe{\c s}}[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.
+%
+% The new format (main matter):\NamesActive
+%
+% \Name{Vlad, III}[III Dracula], known as
+% \IndexRef{Vlad, {\c T}epe{\c s}}{Vlad III}
+% \SubvertThis\Name*{Vlad, {\c T}epe{\c s}}
+% (\Name*{Vlad, {\c T}epe{\c s}}[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
+% \let\FrontNamesFormat\OldFrontNames
+%
+% We are back in the old format.
+%
+% in the front matter we see: \NamesInactive
+% \ForgetThis\Name{Vlad, III}[III Dracula],
+% \Name*{Vlad, III}, and \Name{Vlad, III}.
+%
+% in the main matter we see: \NamesActive
+% \ForgetThis\Name{Vlad, III}[III Dracula],
+% \Name*{Vlad, III}, and \Name{Vlad, III}.
% \end{quote}
-% Now we have reverted to the default \cmd{\NamesFormat} and we get:
+%
+% The reason why we redefine \cmd{\NamesFormat} is because it is more common to add extra information with the first mention of a name. Yet one similarly could redefine \cmd{\MainNameHook} or \cmd{\FrontNameHook} for subsequent uses of names.
+%
+% \subsection{Data tags in Hooks}
+% \label{sec:DataTagHooks}
+%
+% By recalling name data tags (Section~\ref{sec:DataTags}) in formatting hooks, one can automate how they either appear with a name or not. This package is all about automation and the associated trade-offs.
+%
+% Formatting hooks are called within a local scope. They take zero or one argument (Section~\ref{sec:Formatting}). When they take one argument, they have the option to print that argument, add information to the argument, or discard the argument. Yet macros used in formatting hooks can present challenges that we show how to manage:
+%
% \begin{itemize}
-% \item \cmd{\ForgetThis}\cmd{\Name\{Vlad, III\}[III Dracula]}\dotfill \ForgetThis\Name{Vlad, III}[III Dracula]
-% \item \cmd{\Name*\{Vlad, III\}}\dotfill \Name*{Vlad, III}
-% \item \cmd{\Name\{Vlad, III\}}\dotfill \Name{Vlad, III}
+% \item When \cmd{\noexpand} is used in a name argument, \cmd{\NameQueryInfo}
+% and perhaps other macros may not produce output within a formatting hook
+% when using the basic interface, but the quick interface works fine.
+% \item Macros that are used to make local changes in formatting hooks should
+% never make the same changes outside of that context, else spurious index
+% entries will occur.
% \end{itemize}
-% We also set up the cross-reference \cmd{\IndexRef\{Dracula\}\{Vlad III\}}\IndexRef{Dracula}{Vlad III}. Compare the examples for \LDem\ in Section~\ref{sec:NameAncient}.
%
-% \ReturnLink
+% \DescribeMacro{\@nameauth@toksa}
+% Three token registers contain each of the name arguments used in a macro that takes them.
+% \DescribeMacro{\@nameauth@toksb}
+% They are needed to manage the proper expansion of name arguments, especially in the index.
+% \DescribeMacro{\@nameauth@toksc}
+% Historically, these registers have been necessary for names that contain accents and diacritics. In Section~\ref{sec:AKA}, these registers correspond to the \emph{last} three name arguments. They can be used, if needed, in formatting hooks by \textsf{nameauth} macros that take name arguments.
+%
+% Their chief use, historically speaking, was to facilitate retrieving name data tags via \cmd{\NameQueryInfo}. That use has been superseded by \cmd{\NameauthPattern}, which is described in Section~\ref{sec:NamePatterns}.
+%
% \newpage
%
-% \subsubsection{Hooks: Life Dates}
-% \label{sec:Hooksii}
-% \begingroup^^A Local format hook redefinition
-% We can use name conditionals (Section~\ref{sec:NameTests}) and text tags (Section~\ref{sec:TextTags}) to add life information to names when desired. We begin a local scope to isolate any changes to the formatting hooks.
+% \subsubsection{Hook Templates}
+% \label{sec:DataTemp}
%
-% \DescribeMacro{\if@nameauth@InName}
-% The example \cmd{\NamesFormat} below adds a text tag to the first occurrences of main-matter names.
-% \DescribeMacro{\if@nameauth@InAKA}
-% It uses internal macros of \cmd{\@nameauth@Name}. To prevent errors, the Boolean values \texttt{\textbackslash if@nameauth@InName} and \texttt{\textbackslash if@nameauth@InAKA} are true only within the scope of \cmd{\@nameauth@Name} and \cmd{\AKA} respectively.
+% \begingroup ^^A Local formatting hook change
%
-% \DescribeMacro{\@nameauth@toksa}
-% This package makes three token registers available to facilitate using the name conditional macros as we do below.
-% \DescribeMacro{\@nameauth@toksb}
-% These registers are necessary for names that contain accents and\DescribeMacro{\@nameauth@toksc}
-% diacritics.\footnote{In \cmd{\AKA} these registers correspond to the \emph{last} three arguments, the xref.}
+% \subsubsection*{\hfil Recommended Template}
%
-% 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 have to use \cmd{\AKA}. We use \cmd{\ForceName} as needed with \cmd{\AKA}. In the document preamble we set up the following:
-% \begin{quote}\small
-% \StartNum
-% \begin{verbatim}
-%\newif\ifNoTag
-%\makeatletter
-%\renewcommand*\NamesFormat[1]{\begingroup%
-% \protected@edef\temp{\endgroup\textsc{#1}%
-% \unless\ifNoTag
-% \if@nameauth@InName
-% {\bfseries\noexpand\NameQueryInfo
-% [\unexpanded\expandafter{\the\@nameauth@toksa}]
-% {\unexpanded\expandafter{\the\@nameauth@toksb}}
-% [\unexpanded\expandafter{\the\@nameauth@toksc}]}\fi
-% \if@nameauth@InAKA
-% {\normalfont\noexpand\NameQueryInfo
-% [\unexpanded\expandafter{\the\@nameauth@toksa}]
-% {\unexpanded\expandafter{\the\@nameauth@toksb}}
-% [\unexpanded\expandafter{\the\@nameauth@toksc}]}\fi
-% \fi}\temp\global\NoTagfalse%
-%}
-%\makeatother
-%\let\FrontNamesFormat\NamesFormat\end{verbatim}
+% The hook below prints the name data tag with the first use of a name in the main-matter system, if such a tag exists. It is simple, it avoids the \cmd{\NameQueryInfo} problem, and it is easy to debug.
+%
+% \begin{quote}
+% \begin{Verbatim}
+% \renewcommand*\NamesFormat[1]
+% {%
+% #1%
+% \ifcsname\NameauthPattern!DB\endcsname
+% \expandafter\csname\NameauthPattern!DB\endcsname%
+% \fi
+% }
+% \end{Verbatim}
% \end{quote}
+%
+% \subsubsection*{\hfil Older Templates}
+%
+% Two other hook designs were used in the past to display name data tags. They are included here only for the sake of illustration. After showing the templates, we test all three of them to show why we recommend the template above.
+%
+% We use \(\epsilon\)-\TeX\ features next. See \href{https://tex.stackexchange.com/questions/140785/how-is-unexpanded-defined}{\bfseries this page} on the use of \cmd{\unexpanded} and \href{https://tex.stackexchange.com/questions/61223/explanations-about-begingroup-edef-x-endgroup}{\bfseries another page} pertinent to the structure of this hook. We print the name, expand the arguments of \cmd{\NameQueryInfo}, and use those arguments to print the tag.
+%
+% \begin{quote}
+% \vspace{3ex}\Info{Alternate A}\vspace{-3ex}
+% \begin{Verbatim}
% \makeatletter
-% \renewcommand*\NamesFormat[1]{\begingroup^^A
-% \protected@edef\temp{\endgroup\textsc{#1}^^A
-% \unless\ifNoTag
-% \if@nameauth@InName
-% {\bfseries\noexpand\NameQueryInfo
+% \renewcommand*\NamesFormat[1]{%
+% \begingroup%
+% \protected@edef\temp{\endgroup%
+% {#1\noexpand\NameQueryInfo
% [\unexpanded\expandafter{\the\@nameauth@toksa}]
% {\unexpanded\expandafter{\the\@nameauth@toksb}}
-% [\unexpanded\expandafter{\the\@nameauth@toksc}]}\fi
-% \if@nameauth@InAKA
-% {\normalfont\noexpand\NameQueryInfo
+% [\unexpanded\expandafter{\the\@nameauth@toksc}]%
+% }%
+% }%
+% \temp%
+% }
+% \makeatother
+% \end{Verbatim}
+% \end{quote}
+%
+% The older form of this hook was the first to be used in \textsf{nameauth},
+% based on \href{https://www.tug.org/TUGboat/tb09-1/tb20bechtolsheim.pdf}{\bfseries this \texttt{pdf} article} from \textit{TUGboat} that gives a tutorial on \cmd{\expandafter}. As one can see, it is more tedious, but gets the same result as above:
+%
+% \begin{quote}
+% \vspace{3ex}\Info{Alternate B}\vspace{-3ex}
+% \begin{Verbatim}
+% \let\ex\expandafter
+% \makeatletter
+% \renewcommand*\NamesFormat[1]{%
+% #1%
+% \ex\ex\ex\ex\ex\ex\ex\NameQueryInfo%
+% \ex\ex\ex\ex\ex\ex\ex[\ex\ex\ex\the%
+% \ex\ex\ex\@nameauth@toksa\ex\ex\ex]%
+% \ex\ex\ex{\ex\the\ex\@nameauth@toksb\ex}%
+% \ex[\the\@nameauth@etoksc]%
+% }
+% \makeatother
+% \end{Verbatim}
+% \end{quote}
+%
+% \subsubsection*{\hfil Template Test}
+%
+% We set up the following test for our three templates, with indexing suppressed:
+%
+% \begin{itemize}
+% \item A macro in a name argument is preceded by \cmd{\noexpand}. That
+% occurs with greater frequency in advanced formatting.
+% \item If we see the outcome, ``Test passed'', we have success.
+% \item If we see the outcome, ``Test'', we have failure.
+% \end{itemize}
+%
+% \IndexInactive
+% \begin{VerbatimOut}{\jobname.tmp}
+% \newcommand\testname{Test}
+% \NameAddInfo{\noexpand\testname}{ passed}
+% \begin{nameauth}
+% \< Test & & \noexpand\testname & >
+% \end{nameauth}
+% \end{VerbatimOut}
+%
+% \begin{quote}
+% The macro \cmd{\testname} contains the first part of our test output.
+% The name data tag contains the second part. We will use both name
+% interfaces with all three templates.
+%
+% \VerbatimInput[gobble=0]{\jobname.tmp}
+% \end{quote}
+%
+% \input{\jobname.tmp}
+%
+% \begin{itemize}
+% \item The recommended hook gives us:\\
+% \renewcommand*\NamesFormat[1]
+% {^^A
+% #1^^A
+% \ifcsname\NameauthPattern!DB\endcsname
+% \expandafter\csname\NameauthPattern!DB\endcsname^^A
+% \fi
+% }
+% \begin{tabular}{lll}
+% \cmd{\ForgetThis}\cmd{\Name\{}\cmd{\noexpand}\cmd{\testname\}} &
+% \ForgetThis\Name{\noexpand\testname} & success \\
+% \cmd{\ForgetThis}\cmd{\Test} & \ForgetThis\Test & success \\
+% \end{tabular}
+%
+% \item Alternate A gives us:\\
+% \makeatletter
+% \renewcommand*\NamesFormat[1]{^^A
+% \begingroup^^A
+% \protected@edef\temp{\endgroup^^A
+% {#1\noexpand\NameQueryInfo
% [\unexpanded\expandafter{\the\@nameauth@toksa}]
% {\unexpanded\expandafter{\the\@nameauth@toksb}}
-% [\unexpanded\expandafter{\the\@nameauth@toksc}]}\fi
-% \fi}\temp\global\NoTagfalse}^^A
+% [\unexpanded\expandafter{\the\@nameauth@toksc}]^^A
+% }^^A
+% }^^A
+% \temp^^A
+% }
% \makeatother
-% \let\FrontNamesFormat\NamesFormat
+% \begin{tabular}{lll}
+% \cmd{\ForgetThis}\cmd{\Name\{}\cmd{\noexpand}\cmd{\testname\}} &
+% \ForgetThis\Name{\noexpand\testname} & failure \\
+% \cmd{\ForgetThis}\cmd{\Test} & \ForgetThis\Test & success \\
+% \end{tabular}
%
-% 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.
+% \item Alternate B gives us:\\
+% \let\ex\expandafter
+% \makeatletter
+% \renewcommand*\NamesFormat[1]{^^A
+% #1^^A
+% \ex\ex\ex\ex\ex\ex\ex\NameQueryInfo^^A
+% \ex\ex\ex\ex\ex\ex\ex[\ex\ex\ex\the^^A
+% \ex\ex\ex\@nameauth@toksa\ex\ex\ex]^^A
+% \ex\ex\ex{\ex\the\ex\@nameauth@toksb\ex}^^A
+% \ex[\the\@nameauth@etoksc]^^A
+% }
+% \makeatother
+% \begin{tabular}{lll}
+% \cmd{\ForgetThis}\cmd{\Name\{}\cmd{\noexpand}\cmd{\testname\}} &
+% \ForgetThis\Name{\noexpand\testname} & failure \\
+% \cmd{\ForgetThis}\cmd{\Test} & \ForgetThis\Test & success \\
+% \end{tabular}
+% \end{itemize}
%
-% 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: \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}
+% \endgroup ^^A Local formatting hook change
+%
+% \subsubsection[Ancient Names]{Application: Ancient Names}
+% \label{sec:NameAncient}
+%
+% \begingroup%^^A Local format hook redefinition
+%
+% \renewcommand*\NamesFormat{}^^A
+% \renewcommand*\MainNameHook{}^^A
+% Ancient names tend to be the most fluid regarding the meaning and use of affixes. Certain scholarly contexts add more information to a name when it is first introduced. Here we look at ways to address that need. For the sake of clarity, here the examples do not use the formatting conventions of this manual.
+%
+% First we explore the easiest way to handle royal or ancient variants by manually adding any epithets or sobriquets to a standard name form:
+%
+% \begin{itemize}
+% \item We use \cmd{\PretagName}\PatInfo{\ShowPattern{Antiochus, IV}!PRE}
+% to sort especially Roman numerals in the index. For example:
+% \cmd{\PretagName\{Antiochus, IV\}\{Antiochus 4\}}
+% \item We use \cmd{\TagName}\PatInfo{\ShowPattern{Antiochus, IV}!TAG} to
+% ensure that any ``long form'' information is displayed in the index:
+% \cmd{\TagName\{Antiochus, IV]\}\{ Epiphanes, king\}}.
+% \item Using \cmd{\PretagName} and \cmd{\TagName} in the preamble ensures
+% consistency.
+% \item We use \meta{Alternate} to add ``long form'' information in the text,
+% e.g:\PatInfo{\ShowPattern{Antiochus, IV}!MN}
+% \end{itemize}
+% \begin{Block}
+% \cmd{\Name\ \{Antiochus, IV\}[IV Epiphanes]}\dotfill
+% \Name{Antiochus, IV}[IV Epiphanes]\\
+% \cmd{\Name*\{Antiochus, IV\}}\dotfill \Name*{Antiochus, IV}\\
+% \cmd{\Name\ \{Antiochus, IV\}}\dotfill \Name{Antiochus, IV}
+% \end{Block}
+%
+% \newpage
+%
+% Next we show a snippet that uses the quick interface with this same method. We trigger a first use, followed by long and short subsequent uses:
+%
+% \begin{quote}
+% \vspace{3ex}
+% \PatInfo{\ShowPattern{Demetrius, I}!PRE\break
+% \ShowPattern{Demetrius, I}!TAG\break
+% \ShowPattern{Demetrius, I}!MN}
+% \vspace{-3ex}
+% \begin{Verbatim}
+% \PretagName{Demetrius, I}{Demetrius 1}
+% \TagName{Demetrius, I}{ Soter, king}
+% \begin{nameauth}
+% \< Dem & & Demetrius, I & >
+% \end{nameauth}
+% \end{Verbatim}
+% \end{quote}
+%
+% \begin{Block}
+% |\ForgetName{Demetrius, I}|\ForgetName{Demetrius, I}\\
+% \cmd{\Dem[I Soter]}\dotfill \Dem[I Soter]\\
+% \cmd{\LDem}\dotfill \LDem\\
+% \cmd{\Dem}\dotfill \Dem
+% \end{Block}
+%
+% As discussed in Section~\ref{sec:Complexity}, simple examples do not lend themselves to automation. Below we trade automation, where we do not need to add information manually to the \meta{Alternate} argument, for a complex initial setup that uses name data tags and the recommended template:
+%
+% \begin{quote}
+% \vspace{3ex}
+% \PatInfo{\ShowPattern{Demetrius, I}!DB}
+% \vspace{-3ex}
+% \begin{Verbatim}[firstnumber=last]
+% \NameAddInfo{Demetrius, I}{ Soter}
+% \renewcommand*\NamesFormat[1]
+% {%
+% #1%
+% \ifcsname\NameauthPattern!DB\endcsname
+% \expandafter\csname\NameauthPattern!DB\endcsname%
+% \fi
+% }
+% \renewcommand*\MainNameHook{}
+% \end{Verbatim}
% \end{quote}
+% \NameAddInfo{Demetrius, I}{ Soter}
+% \renewcommand*\NamesFormat[1]
+% {^^A
+% #1^^A
+% \ifcsname\NameauthPattern!DB\endcsname
+% \expandafter\csname\NameauthPattern!DB\endcsname^^A
+% \fi
+% }
+% \renewcommand*\MainNameHook{}
+%
+% \begin{Block}
+% |\ForgetName{Demetrius, I}|\ForgetName{Demetrius, I}\\
+% \cmd{\Dem}\dotfill \Dem\\
+% \cmd{\LDem}\dotfill \LDem\\
+% \cmd{\Dem}\dotfill \Dem
+% \end{Block}
+%
+% In both cases, the index entry in a normal document would be sorted like the following:
+% \begingroup
+% \IndexActual{@}^^A
+% \TagName{Demetrius, I}{ Soter, king}^^A
+% \texttt{\ShowIdxPageref{Demetrius, I}}.^^A
+% \TagName{Demetrius, I}{ Soter, king\string|hyperpage}
+% \endgroup
+%
+% The first use of a name, or one after the use of \cmd{\ForgetName} or \cmd{\ForgetThis}, shows the most information. A long reference to an extant name shows a little less info, and a short reference shows the least. Every difference in name form corresponds with a macro in a known state.
+% \endgroup^^A Local format hook redefinition
+%
+% \subsubsection[Life Dates]{Application: Life Dates}
+%
+% \begingroup^^A Local format hook redefinition
+%
+% History texts tend to use life dates, regnal dates, and dates when certain figures flourished. As we used more information with ancient names via name data tags, we can do something similar here.
+%
+% First we must create any data tags that might be used. Whether it is in the preamble or in the body text, the main point is that the tag can only be used if it exists. The tags have a leading space because they are printed conditionally.
+%
+% We also define a cross-reference ``Atat\"urk,'' yet we use naming macros with that name, printing formatted names in the text but making no index page entries. We add a Boolean flag to the formatting hook that lets us suppress dates in first uses as needed, while normally displaying dates in first uses by default. Below we suppress the usual formatting of this manual.
+%
+% \ifdefined\NameauthDoTestFiles \edef\NameauthTestFile{test11_02.tex}\else
+% \edef\NameauthTestFile{\jobname.tmp}\fi
+%
+% \begin{VerbatimOut}{\NameauthTestFile}
+% \documentclass{article}
+% \input{compat.tex} % Included with nameauth; needed only if
+% % compiling on multiple TeX distros or LaTeX engines.
+% \usepackage{makeidx}
+% \usepackage{nameauth}
+% \makeindex
+%
+% % Add data tags to names.
% \NameAddInfo[George]{Washington}{ (1732--99)}
% \NameAddInfo[Mustafa]{Kemal}{ (1881--1938)}
-% \NameAddInfo{Atatürk}{ (in 1934, a special surname)}
-% \IndexRef{Atatürk}{Kemal, Mustafa}
-% \newpage
+% \NameAddInfo{Atat\"urk}{ (in 1934, a special surname)}
+%
+% % Ensure that Atat\"urk is a cross-reference that
+% % has no page entries in the index.
+% \IndexRef{Atat\"urk}{Kemal, Mustafa}
+%
+% % Manually suppress data tag in ``first'' reference
+% \newif\ifNoTag
+%
+% % Redesign formatting hook to usually print a tag
+% % only in ``first'' reference. On exit, It resets
+% % the flag that suppresses tags, making that flag
+% % work only once per name use.
+%
+% \renewcommand*\NamesFormat[1]
+% {%
+% #1%
+% \ifcsname\NameauthPattern!DB\endcsname
+% \unless\ifNoTag
+% \expandafter\csname\NameauthPattern!DB\endcsname%
+% \fi
+% \global\NoTagfalse%
+% \fi
+% }
+%
+% \begin{document}
+%
+% \ForgetThis\Name[George]{Washington} held office as the first US
+% president from 1789 to 1797. \Name[George]{Washington} was the only
+% president whose term in office was completely in the eighteenth
+% century. If we need to trigger the first use hook at some point,
+% we can suppress dates and get an automatic long reference via:
+% \NoTagtrue\ForgetThis\Name[George]{Washington}. Or we can trigger
+% the first-use hook in a subsequent name use and still have dates:
+% \ForceName\Name[George]{Washington}.
+%
+% We can add name info tags to names used only as cross-
+% references. For example, \Name[Mustafa]{Kemal} was granted
+% the name \Name{Atat\"urk}. We mention \Name[Mustafa]{Kemal}
+% and \Name{Atat\"urk} again. Likewise, we can trigger a
+% first use, but with no data tag tag:
+% \NoTagtrue\ForgetThis\Name{Atat\"urk}.
+%
+% \printindex
+% \end{document}
+% \end{VerbatimOut}
+%
+% \NameAddInfo[George]{Washington}{ (1732--99)}
+% \NameAddInfo[Mustafa]{Kemal}{ (1881--1938)}
+% \NameAddInfo{Atat\"urk}{ (in 1934, a special surname)}
+% \IndexRef{Atat\"urk}{Kemal, Mustafa}
+% \renewcommand*\NamesFormat[1]
+% {^^A
+% #1^^A
+% \ifcsname\NameauthPattern!DB\endcsname
+% \unless\ifNoTag
+% \expandafter\csname\NameauthPattern!DB\endcsname^^A
+% \fi
+% \global\NoTagfalse^^A
+% \fi
+% }
+% \renewcommand*\MainNameHook{}
%
-% Now we begin with the first example, which, after all the setup, looks deceptively simple, but highly reusable without extra work:
% \begin{quote}\small
-% \ContinueNum
-% \begin{verbatim}
-%\ForgetThis\Wash held office 1789--97.
-%No tags: \Wash.\\
-%First use, dates suppressed: \NoTagtrue\ForgetThis\Wash.\\
-%Subsequent use with format and dates: \ForceName\Wash.\end{verbatim}
-%
-% \smallskip
-% \ForgetThis\Wash\ held office 1789--97.\\
-% No tags: \Wash.\\
-% First use, dates suppressed: \NoTagtrue\ForgetThis\Wash.\\
-% Subsequent use with format and dates: \ForceName\Wash.
+% \VerbatimInput[gobble=0,lastline=34]{\NameauthTestFile}
% \end{quote}
%
-% 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:
+% Up to this point it seems as if there has been a lot of setup. The payoff, however, comes in the main body text where the use of the naming macros does not look much different than normal.
+%
% \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}.
+% \VerbatimInput[gobble=0,firstline=35,lastline=45]{\NameauthTestFile}
+%
+% \ForgetThis\Name[George]{Washington} held office as the first US
+% president from 1789 to 1797. \Name[George]{Washington} was the only
+% president whose term in office was completely in the eighteenth
+% century. If we need to trigger the first use hook at some point,
+% we can suppress dates and get an automatic long reference via:
+% \NoTagtrue\ForgetThis\Name[George]{Washington}. Or we can trigger
+% the first-use hook in a subsequent name use and still have dates:
+% \ForceName\Name[George]{Washington}.
% \end{quote}
%
-% 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}:
+% Since we already set up a cross-reference with \cmd{\IndexRef}, we can use just the the naming macros with ``Atat\"urk'' and get the desired formatting without any page references in the index:
+%
% \begin{quote}\small
-% \ContinueNum
-% \begin{verbatim}
-%\makeatletter\@nameauth@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@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}%
-% Now we end the scope to revert any changes to formatting hooks.
+% \VerbatimInput[gobble=0,firstline=46]{\NameauthTestFile}
+%
+% We can add name info tags to names used only as cross-
+% references. For example, \Name[Mustafa]{Kemal} was granted
+% the name \Name{Atat\"urk}. We mention \Name[Mustafa]{Kemal}
+% and \Name{Atat\"urk} again. Likewise, we can trigger a
+% first use, but with no data tag tag:
+% \NoTagtrue\ForgetThis\Name{Atat\"urk}.
+% \end{quote}
+%
% \endgroup^^A Local format hook redefinition
%
-% \ReturnLink
+% \subsection{Alternate Formatting}
+% \label{sec:AltFormat}
+%
+% We build on the subject of complex formatting hooks that \cmd{\noexpand} playing a role therein, Before we engage the topic of Roman names and other complex examples, we need to cover alternate formatting.
+%
+% \subsubsection[Enabling/Disabling]{Enabling and Disabling}
+%
+% The first thing we need to know is how to enable and disable alternate formatting:
+%
+% \begin{center}\small\medstretch
+% \begin{tabular}{lcc}\toprule
+% Macro & Enabled & Activated\\\midrule
+% \cmd{\AltFormatActive} & \YES & \YES\\
+% \cmd{\AltFormatActive*} & \YES & \NO\\
+% \cmd{\AltFormatInactive} & \NO & \NO\\\bottomrule
+% \end{tabular}
+% \end{center}
+%
+% \begin{itemize}
+% \item \emph{Enabled} means that the alternate formatting mechanism
+% inhibits the normal behavior of \cmd{\CapThis}.
+% \item \emph{Disabled} means that the normal behavior of \cmd{\CapThis}
+% is again in force and alternate formatting is inhibited.
+% \item \emph{Activated} means that built-in alternate formatting macros
+% like \cmd{\textSC} format their arguments.
+% \item \emph{Deactivated} means that built-in alternate formatting macros
+% like \cmd{\textSC} do not format their arguments.
+% \end{itemize}
+%
+% \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*}.\medskip
+%
+% \DescribeMacro{\AltFormatActive*}
+% The starred form \cmd{\AltFormatActive*} enables alternate formatting but deactivates the built-in alternate 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
%
-% \subsubsection{Hooks: Advanced}
-% \label{sec:Hooksiii}
-% \AltFormatActive
-% In this section we invoke \cmd{\AltFormatActive} and create several scopes containing respective examples. Some macros in this section normally should be defined in a document preamble. We define them locally and ensure that names do not use them when they are undefined. This is not best practices, but it makes sense for this manual's need for multiple redefinitions.
% \newpage
%
-% \begin{center}\bfseries Alternate Formatting: Details\end{center}
-% \phantomsection
-% Here we discuss the implementation details of alternate formatting, which will engage the rest of the section. This framework provides features that aid both error protection and ease of hook design. Names that use alternate formatting may cause spurious index entries if used also in the default formatting regime.
+% \DescribeMacro{\AltFormatInactive}
+% This macro both disables and deactivates alternate formatting. This reverts globally to standard formatting and the normal function of \cmd{\CapThis}. \medskip
%
-% Both \cmd{\AltFormatActive} and \cmd{\AltFormatActive*} globally set the internal Boolean flag \cmd{\@nameauth@AltFormattrue}, enabling alternate formatting. \cmd{\AltFormatActive} globally sets \cmd{\@nameauth@DoAlttrue}, which activates formatting. Both flags are reset globally by \cmd{\AltFormatInactive} and normal formatting resumes.
+% Most \textsf{nameauth}\Info{Global scope} macros that turn things on and off have a local scope unless one uses \cmd{\global}. These alternate formatting macros have global scope to eliminate implied scope becoming a point of failure, creating spurious index entries.
%
-% \cmd{\AltFormatActive*} normally suppresses formatting changes but it still forces \cmd{\CapThis} to work through \cmd{\AltCaps}. One can leverage this to get the default look of \textsf{nameauth} while mitigating errors if many names use macros in their arguments.
+% \begin{InfoBox}
+% The macros above \emph{always} make global changes. Using names designed for alternate formatting in a document section that uses regular formatting will produce an inconsistent appearance in the text and spurious index entries.
+% \end{InfoBox}
+% \negmedskip
%
-% Alternate formatting protects against errors created when \cmd{\@nameauth@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}).
+% \subsubsection{Using \texttt{\textbackslash noexpand}}
%
-% \begin{center}\bfseries Continental Format: Predefined\end{center}
-% \phantomsection
-% 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@nameauth@DoAlt\textsc{#1}\else#1\fi
-%}\end{verbatim}
-% \end{quote}
+% As we get into advanced formatting, we will encounter \cmd{\noexpand} with greater frequency. Even before we consider that discussion, we need to touch on a few ways that macros can break \textsf{nameauth} when used in name arguments.
%
-% If the \texttt{altformat} option or \cmd{\AltFormatActive} is used, formatting occurs in both the text and in the index. \cmd{\AltOff} deactivates formatting only in the formatting hooks:
-% \begin{quote}\small
-% \ContinueNum
-% \begin{verbatim}
-%\newcommand*\AltOff{%
-% \if@nameauth@InHook\@nameauth@DoAltfalse\fi
-%}\end{verbatim}
+% In order to handle the inherent ambiguity of name forms, macros that take name arguments trade a certain ``fragility'' for the ability to be as close to natural language as possible. In versions of \textsf{nameauth} before 3.5, enclosing an \meta{SNN},\meta{Affix} argument within a robust macro like \cmd{\textsc} would halt \LaTeX\ with errors. That seems to be no longer the case. Nevertheless, depending on the macros used, it may be helpful to apply macros separately to \meta{SNN} and \meta{Affix} like this:
+%
+% \begin{quote}
+% |\Name{\noexpand\MyMacro{|\meta{SNN}|},\noexpand\MyMacro{|\meta{Affix}|}}|.
% \end{quote}
%
-% \cmd{\CapThis} triggers \cmd{\AltCaps} to capitalize its argument:
+% Using \cmd{\CapThis} with a name whose leading element is a macro may fail, depending on the particular macro. Use alternate formatting to have \cmd{\CapThis} activate the alternate capitalization mechanism.
+%
+% \NameArgWarning
+%
+% In Section~\ref{sec:DebuggingMacros} we encountered reasons for using \cmd{\noexpand} in name arguments, as well as related caveats. Now we include more reasons to use \cmd{\noexpand}:
+%
+% \begin{itemize}
+% \item If a macro is undefined, even putting \cmd{\noexpand} before it will
+% permit an error unless the macro is detokenized or verbatim.
+% \item The use of \cmd{\noexpand} isolates the local, conditional expansion of
+% macros in the formatting hooks from the global macro state in the index.
+% \item Indexing of such names normally does not occur within the formatting
+% hooks. Otherwise, different index entries would result.
+% \item One can use macros in the formatting hooks to trigger local changes. If
+% using Boolean flags to trigger those changes, one needs two flags per change
+% (e.g., grammatical inflection) but not per name.
+% \item Local flags are false when the hook executes. Global flags are reset
+% when the hook terminates.
+% \item Take care when using macros in name arguments without using
+% \cmd{\noexpand} before them.
+% \end{itemize}
+%
+% \subsubsection[Capitalization]{Alternate Capitalization}
+% \AltFormatActive
+%
+% Above we referred to potential problems using \cmd{\CapThis}. When alternate formatting is enabled, \cmd{\CapThis} changes its mechanism to avoid such problems.\medskip
+%
+% \DescribeMacro{\AltCaps}
+% Using the aid of the helper macro \cmd{\AltCaps}, \cmd{\CapThis} will cause \cmd{\AltCaps} to capitalize its argument only in a formatting hook. \cmd{\AltCaps} is enabled whenever alternate formatting is enabled, but it works independently of both \cmd{\AltOn} and \cmd{\AltOff}, which are covered in the next section. We describe the syntax:
+%
+% \begin{SyntaxBox}
+% \cmd{\noexpand}\cmd{\AltCaps}\marg{Arg}
+% \end{SyntaxBox}
+%
+% We offer a silly example below, taking advantage of the local scope of the \texttt{quote} environment to disable indexing temporarily:
+%
+% \begin{VerbatimOut}{\jobname.tmp}
+% \IndexInactive
+% What's in \Name[\noexpand\AltCaps{a}]{Name}?
+% \CapThis\Name*[\noexpand\AltCaps{a}]{Name} smells not,
+% but a rose does, even if it has
+% \Name*[\noexpand\AltCaps{a}]{Name}.
+% \end{VerbatimOut}
+%
% \begin{quote}\small
-% \ContinueNum
-% \begin{verbatim}
-%\newcommand*\AltCaps[1]{%
-% \if@nameauth@InHook
-% \if@nameauth@DoCaps\MakeUppercase{#1}\else#1\fi
-% \else#1\fi
-%}\end{verbatim}
-% \end{quote}
+% \VerbatimInput[gobble=0]{\jobname.tmp}
%
-% We must put \cmd{\noexpand} before \cmd{\textSC}, \cmd{\AltCaps}, and so on to prevent them from expanding outside of the formatting hooks.
+% \input{\jobname.tmp}
+% \end{quote}
%
-% Before we alter the formatting hooks, either we 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.
-% \newpage
+% \cmd{\AltCaps} does not partition its argument, so it will not have the same issues as the normal use of \cmd{\CapThis}, adding to stability and robustness at the expense of doing a little more work.
+% \AltFormatInactive
%
-% \begin{center}\bfseries Continental Format: User-Defined\end{center}
-% \phantomsection
% \begingroup^^A Local format hook redefinition
-% The user must implement this final step. We use \cmd{\AltFormatActive}, then redefine \cmd{\MainNameHook} to have small caps on by default in the index and first uses in the text, then off in subsequent uses in the text:
+%
+% \subsubsection{Formatting Features}
+% \label{sec:AltFeatures}
+% \AltFormatActive
+%
+% \DescribeMacro{\textSC}
+% Using alternate formatting can be as easy as using any one of four predefined macros.
+% \DescribeMacro{\textIT}
+% These macros are analogous to the predefined formatting hooks that are accessible via package options.
+% \DescribeMacro{\textBF}
+% They \emph{always format} their arguments when using the \texttt{altformat} option or \cmd{\AltFormatActive}.
+% \DescribeMacro{\textUC}
+% They \emph{never format} their arguments when \cmd{\AltFormatActive*} is used or alternate formatting is disabled.
+%
+% By themselves, they do not change format. Yet the macros \cmd{\AltOff} and \cmd{\AltOn}, described shortly, are able to turn the formatting of these macros on and off. We advise using \cmd{\noexpand} before these macros because they can be made to change format. Assuming that we have sorted the following names with \cmd{\PretagName} (Section~\ref{sec:IndexSort}), we get the following, using this manual's formatting conventions:
+%
+% \begin{VerbatimOut}{\jobname.tmp}
+% \Name[Konrad]{\noexpand\textSC{Zuse}};
+% \Name[Konrad]{\noexpand\textSC{Zuse}}\\
+% \Name[Ada]{\noexpand\textIT{Lovelace}};
+% \Name[Ada]{\noexpand\textIT{Lovelace}}\\
+% \Name[Charles]{\noexpand\textBF{Babbage}};
+% \Name[Charles]{\noexpand\textBF{Babbage}}\\
+% \Name{\noexpand\textUC{Kanade}, Takeo};
+% \Name{\noexpand\textUC{Kanade}, Takeo}
+% \end{VerbatimOut}
+%
% \begin{quote}\small
-% \StartNum
-% \begin{verbatim}
-%\renewcommand*\MainNameHook{\AltOff}
-%\let\FrontNameHook\MainNameHook\end{verbatim}
+% \VerbatimInput[gobble=0]{\jobname.tmp}
+%
+% \input{\jobname.tmp}
% \end{quote}
-%\renewcommand*\MainNameHook{\AltOff}
-%\let\FrontNameHook\MainNameHook
%
-% To suppress all formatting in the front-matter text, one need simply to use \cmd{\let}\cmd{\FrontNamesFormat}\cmd{\MainNameHook}. We do not do that here. Usually, we set up the names and any related macros in the preamble:
+% Font substitutions might occur with these macros, depending on the font used. \cmd{\CapName}, \cmd{\RevComma}, and \cmd{\RevName} can modify the names, but only in the text.
+%
+% The alternate formatting macros shown above become more interesting when we automate how they turn on and off. Using \cmd{\noexpand} is necessary here. Both macros below are used in formatting hooks. They hide some complexity from authors.\medskip
+%
+% Vaguely reminiscent of depressing\DescribeMacro{\AltOff}\ an automobile's manual clutch lever, \cmd{\AltOff} deactivates \cmd{\textSC}, \cmd{\textBF}, \cmd{\textIT}, and \cmd{\textUC} only in a formatting hook. The alternate formatting mechanism is still ``running'', but it is not transferring ``power'' to the formatting macros. They display their arguments unmodified.\medskip
+%
+% Likewise, \cmd{\AltOn}\DescribeMacro{\AltOn}\ activates \cmd{\textSC}, \cmd{\textBF}, \cmd{\textIT}, and \cmd{\textUC} only in a formatting hook, as if one let out the clutch pedal, causing ``power'' to transfer through the gearbox to the formatting macros. They now modify their arguments.\medskip
+%
+% If one uses the \texttt{altformat} option or \cmd{\AltFormatActive}, the formatting ``power'' goes to the formatting macros by default in order to have formatted names in the index. Otherwise, the normal formatting regime isolates formatting in the text, as the Anglosphere is wont to do.
+%
+% We use \cmd{\noexpand} as discussed and add a formatting hook to get changes in the text, not in the index. We also suspend this manual's formatting conventions:
+%
+% \ifdefined\NameauthDoTestFiles \edef\NameauthTestFile{test11_03.tex}\else
+% \edef\NameauthTestFile{\jobname.tmp}\fi
+%
+% \begin{VerbatimOut}{\NameauthTestFile}
+% \documentclass{article}
+% \input{compat.tex} % Included with nameauth; needed only if
+% % compiling on multiple TeX distros or LaTeX engines.
+% \usepackage{makeidx}
+% \usepackage[altformat]{nameauth}
+% \makeindex
+%
+% \PretagName[Konrad]{\noexpand\textSC{Zuse}}{Zuse, Konrad}
+% \PretagName[Ada]{\noexpand\textIT{Lovelace}}{Lovelace, Ada}
+% \PretagName[Charles]{\noexpand\textBF{Babbage}}
+% {Babbage, Charles}
+% \PretagName{\noexpand\textUC{Kanade}, Takeo}{Kanade Takeo}
+%
+% \begin{document}
+%
+% \renewcommand*\MainNameHook{\AltOff}
+%
+% \ForgetThis\Name[Konrad]{\noexpand\textSC{Zuse}};
+% \Name[Konrad]{\noexpand\textSC{Zuse}}\\
+% \ForgetThis\Name[Ada]{\noexpand\textIT{Lovelace}};
+% \Name[Ada]{\noexpand\textIT{Lovelace}}\\
+% \ForgetThis\Name[Charles]{\noexpand\textBF{Babbage}};
+% \Name[Charles]{\noexpand\textBF{Babbage}}\\
+% \ForgetThis\Name{\noexpand\textUC{Kanade}, Takeo};
+% \Name{\noexpand\textUC{Kanade}, Takeo}
+%
+% \printindex
+% \end{document}
+% \end{VerbatimOut}
+%
% \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}
+% \VerbatimInput[gobble=0]{\NameauthTestFile}
+%
+% \renewcommand*\NamesFormat{}
+% \renewcommand*\MainNameHook{\AltOff}
+%
+% \ForgetThis\Name[Konrad]{\noexpand\textSC{Zuse}};
+% \Name[Konrad]{\noexpand\textSC{Zuse}}\\
+% \ForgetThis\Name[Ada]{\noexpand\textIT{Lovelace}};
+% \Name[Ada]{\noexpand\textIT{Lovelace}}\\
+% \ForgetThis\Name[Charles]{\noexpand\textBF{Babbage}};
+% \Name[Charles]{\noexpand\textBF{Babbage}}\\
+% \ForgetThis\Name{\noexpand\textUC{Kanade}, Takeo};
+% \Name{\noexpand\textUC{Kanade}, Takeo}
% \end{quote}
%
-% Likewise in the preamble, we must ensure that these names are sorted properly in the index. When sorting names, be sure to use \cmd{\noexpand} as well:
+% \AltFormatInactive
+% \endgroup^^A Local format hook redefinition
+%
+% \subsubsection{History Text}
+% \label{sec:RealAltEx}
+% \AltFormatActive
+%
+% \begingroup^^A Local format hook redefinition
+%
+% First we engage the idea of a history text, where we use standards for medieval Italian to encode a name instead of those used in modern Romance languages.
+%
+% \ifdefined\NameauthDoTestFiles \edef\NameauthTestFile{test11_04.tex}\else
+% \edef\NameauthTestFile{\jobname.tmp}\fi
+%
+% \begin{VerbatimOut}{\NameauthTestFile}
+% \documentclass{article}
+% \input{compat.tex} % Included with nameauth; needed only if
+% % compiling on multiple TeX distros or LaTeX engines.
+% \usepackage{makeidx}
+% \usepackage[altformat]{nameauth}
+% \makeindex
+%
+% \begin{nameauth}
+% \< Luth & Martin & \noexpand\textSC{Luther} & >
+% \< Cath & Catherine \noexpand\AltCaps{d}e'
+% & \noexpand\textSC{Medici} & >
+% \end{nameauth}
+% \PretagName[Martin]{\noexpand\textSC{Luther}}{Luther, Martin}
+% \PretagName[Catherine \noexpand\AltCaps{d}e']
+% {\noexpand\textSC{Medici}}{Medici, Catherine de}
+%
+% \renewcommand*\MainNameHook{\sffamily\AltOff}
+%
+% \begin{document}
+%
+% \ForgetThis\Luth\ was a leading figure in the Protestant
+% Reformation. \Luth\ believed that one is declared
+% righteous in a forensic sense by divine grace through faith
+% created by the Holy Spirit via the Gospel and the Sacraments.
+%
+% \ForgetThis\Cath\ was not only Queen of France in her own right,
+% but she also guided the reigns of her three sons.
+% \CapThis\LCath[\noexpand\AltCaps{d}e']
+% was blamed for the St.\ Bartholomew's Day massacre that saw the
+% murder of thousands of Huguenots.
+%
+% \printindex
+% \end{document}
+% \end{VerbatimOut}
+%
+% \renewcommand*\MainNameHook{\sffamily\AltOff}
% \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}
+% \VerbatimInput[gobble=0]{\NameauthTestFile}
+%
+% \ForgetThis\Luth\ was a leading figure in the Protestant
+% Reformation. \Luth\ believed that one is declared
+% righteous in a forensic sense by divine grace through faith
+% created by the Holy Spirit via the Gospel and the Sacraments.
+%
+% \ForgetThis\Cath\ was not only Queen of France in her own right,
+% but she also guided the reigns of her three sons.
+% \CapThis\LCath[\noexpand\AltCaps{d}e']
+% was blamed for the St.\ Bartholomew's Day massacre that saw the
+% murder of thousands of Huguenots.
% \end{quote}
%
-% \begin{center}
-% \small\noindent\begin{tabular}{llll}\toprule
-% First & Next & Long & Short \\\midrule
-% \rowcolor{grey}\cmd{\Adams} & \cmd{\Adams} & \cmd{\LAdams} & \cmd{\SAdams}\\
-% \rowcolor{grey}\Adams & \Adams & \LAdams & \SAdams\\
-% \cmd{\SDJR} & \cmd{\SDJR} & \cmd{\LSDJR} & \cmd{\SSDJR}\\
-% \SDJR & \SDJR & \LSDJR & \SSDJR\\
-% \rowcolor{grey}\cmd{\HAR} & \cmd{\HAR} & \cmd{\LHAR} & \cmd{\SHAR}\\
-% \rowcolor{grey}\HAR & \HAR & \LHAR & \SHAR\\
-% \cmd{\Mencius} & \cmd{\Mencius} & \cmd{\LMencius} & \cmd{\SMencius}\\
-% \Mencius & \Mencius & \LMencius & \SMencius\\\bottomrule
-% \end{tabular}
-% \end{center}
+% Comparing the example above to Section~\ref{sec:NameParticles} shows us some differences. Medieval Italian, similar to modern German, keeps the particle(s) with the forename(s). Modern Italian groups particles and surnames together. Thus, we must use here:
%
-% \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 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.\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.
+% \begin{itemize}
+% \item \parbox{0.3\textwidth}{\LCath[\noexpand\AltCaps{d}e']}
+% |\LCath[\noexpand\AltCaps{d}e']|
+% \item \parbox{0.3\textwidth}{\CapThis\LCath[\noexpand\AltCaps{d}e']}
+% |\CapThis\LCath[\noexpand\AltCaps{d}e']|
% \end{itemize}
+% \endgroup^^A Local format hook redefinition
+%
+%
+% \subsubsection{Inflected Names}
+% \label{sec:InflNames}
+% \begingroup^^A Local format hook redefinition
+%
+% Next we design grammatical inflections for use with alternate formatting. We do not use the general formatting conventions in this manual. We shall build on this example in order to design the more complex hooks used for Roman names.
+%
+% We need two Boolean flags for one change in name form, which is a grammatical inflection in this case. Thus, we set up \texttt{\textbackslash ifGenitive} as the global flag and \texttt{\textbackslash ifDoGenitive} as the local flag.
+%
+% \cmd{\DoGenitivetrue} occurs only in the formatting hook. The macro that produces the genitive (or possessive) ending only does so when \texttt{\textbackslash ifDoGenitive} is true. This keeps the index entries consistent via \cmd{\noexpand}. Likewise, \cmd{\AltOff} only occurs in the formatting hook \cmd{\MainNameHook}.
+% \JustIndex\Jeff
+%
+% \ifdefined\NameauthDoTestFiles \edef\NameauthTestFile{test11_05.tex}\else
+% \edef\NameauthTestFile{\jobname.tmp}\fi
+%
+% \begin{VerbatimOut}{\NameauthTestFile}
+% \documentclass{article}
+% \input{compat.tex} % Included with nameauth; needed only if
+% % compiling on multiple TeX distros or LaTeX engines.
+% \usepackage{makeidx}
+% \usepackage[altformat]{nameauth}
+% \makeindex
+%
+% \newif\ifGenitive
+% \newif\ifDoGenitive
+%
+% \newcommand*\GEN{\ifDoGenitive\textSC{'s}\fi}
+%
+% \begin{nameauth}
+% \< Jeff & Thomas &
+% \noexpand\textSC{Jefferson}\noexpand\GEN{} & >
+% \end{nameauth}
+%
+% \PretagName[Thomas]{\noexpand\textSC{Jefferson}\noexpand\GEN{}}
+% {Jefferson, Thomas}
+% \TagName[Thomas]{\noexpand\textSC{Jefferson}\noexpand\GEN{}}
+% {, pres.}
+%
+% \renewcommand*\NamesFormat[1]
+% {\ifGenitive\DoGenitivetrue\fi#1\global\Genitivefalse}
+% \renewcommand*\MainNameHook[1]
+% {\ifGenitive\DoGenitivetrue\fi\AltOff#1\global\Genitivefalse}
+%
+% \begin{document}
+%
+% Consider \Genitivetrue\Jeff\ legacy as the author of the
+% colonies' Declaration of Independence and his impact as third
+% president of the United States. \Jeff\ was a complex historical
+% figure whose actions defy a consistent moral compass both in
+% public policy and in personal affairs.
+%
+% \printindex
+% \end{document}
+% \end{VerbatimOut}
%
-% \makeatletter\@nameauth@AKAFormattrue\makeatother
-% With the \texttt{formatAKA} option we refer to \Mencius\ as \AKA{\noexpand\textSC{Mencius}}{\noexpand\textSC{Meng}, Ke} and \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}
+% \VerbatimInput[gobble=0]{\NameauthTestFile}
+%
+% \renewcommand*\NamesFormat[1]
+% {\ifGenitive\DoGenitivetrue\fi#1\global\Genitivefalse}
+% \renewcommand*\MainNameHook[1]
+% {\ifGenitive\DoGenitivetrue\fi\AltOff#1\global\Genitivefalse}
+%
+% Consider \Genitivetrue\Jeff\ legacy as the author of the
+% colonies' Declaration of Independence and his impact as third
+% president of the United States. \Jeff\ was a complex historical
+% figure whose actions defy a consistent moral compass both in
+% public policy and in personal affairs.
% \end{quote}
-% \makeatletter\@nameauth@AKAFormatfalse\makeatother
% \endgroup^^A Local format hook redefinition
%
-% \begin{center}\bfseries Rolling Your Own: Basic\end{center}
-% \phantomsection
+% \subsubsection{Reference Work I}
% \begingroup^^A Local format hook redefinition
-% 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}.
%
-% When\Warn{} redesigning formatting hooks, we recommend using \cmd{\AltFormatActive} or the \texttt{altformat} option to enable alternate formatting and prevent \cmd{\CapThis} from breaking custom formatting macros.
+% Here we show how \textsf{nameauth} might be used in a reference work, where names are also the head-words of articles. We present examples that include a basic Western name, a basic Eastern name, and a more complicated Western name that includes an alias. Here are a few points to consider:
+%
+% \begin{itemize}
+% \item Sort all names that use alternate formatting.
+% \item Match index entry forms to article head-words. Name variants
+% are cross-referenced to the name form in the head-word.
+% \item Ensure that the first appearance of a name displays only the
+% active alternate formatting. Any additional formatting comes from
+% the macro that formats entries.
+% \item Deactivate alternate formatting in subsequent name references.
+% \item Since some \LaTeX\ fonts do not combine small caps and boldface,
+% we instead use slanted text to set the head-words off from the articles.
+% That font switch is done in the macro that formats the articles
+% (\cmd{\RefArticle}).
+% \end{itemize}
+%
+% \ifdefined\NameauthDoTestFiles \edef\NameauthTestFile{test11_06.tex}\else
+% \edef\NameauthTestFile{\jobname.tmp}\fi
+%
+% \begin{VerbatimOut}{\NameauthTestFile}
+% \documentclass{article}
+% \input{compat.tex} % Included with nameauth; needed only if
+% % compiling on multiple TeX distros or LaTeX engines.
+% \usepackage{makeidx}
+% \usepackage[altformat]{nameauth}
+% \makeindex
+%
+% % Sort any names with macros in the arguments.
+%
+% \PretagName[Greta]{\noexpand\textSC{Garbo}}{Garbo, Greta}
+% \PretagName{\noexpand\textSC{Misora}, Hibari}{Misora Hibari}
+% \PretagName[Heinz]{\noexpand\textSC{R\"uhmann}}{Ruehmann, Heinz}
+% \PretagName[Heinrich Wilhelm]{\noexpand\textSC{R\"uhmann}}
+% {Ruehmann, Heinrich Wilhelm}
+%
+% % Make a cross-reference from a variant name form to the
+% % form of the head-words
+%
+% \IndexRef[Heinrich Wilhelm]{\noexpand\textSC{R\"uhmann}}
+% {\noexpand\textSC{R\"uhmann}, Heinz}
+%
+% % Define the formatting hooks. Since we use the `altformat'
+% % option, alternate formatting is turned off in later
+% % name uses.
+%
+% \renewcommand*\MainNameHook{\AltOff}
+%
+% % Typeset head-words with a slanted font.
+%
+% \newcommand{\RefArticle}[3]
+% {%
+% \def\check{#2}%
+% \ifx\check\empty
+% \noindent\ForgetThis\textsl{#1}\ #3
+% \else
+% \noindent\ForgetThis\textsl{#1}\ #2\ #3
+% \fi\medskip
+% }
%
-% We recommend examining the internal package flag \cmd{\@nameauth@DoAlt}, which activates alternate formatting, \cmd{\@nameauth@DoCaps}, which handles capitalization, and \cmd{\@nameauth@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{document}
+%
+% \RefArticle
+% {\RevComma\Name[Greta]{\noexpand\textSC{Garbo}}}
+% {}
+% {(18 September 1905\,--\,15 April 1990) was a Swedish
+% film actress during the 1920s and 1930s.
+% \Name[Greta]{\noexpand\textSC{Garbo}}\dots}
+%
+% \RefArticle
+% {\Name{\noexpand\textSC{Misora}, Hibari}}
+% {(W:\,``\RevName\Name*{\noexpand\textSC{Misora}, Hibari}'';}
+% {29 May 1937\,--\,24 June 1989) was a Japanese singer
+% and actress noted for her positive message.
+% \Name{\noexpand\textSC{Misora}, Hibari}\dots}
+%
+% \RefArticle
+% {\RevComma\Name[Heinz]{\noexpand\textSC{R\"uhmann}}}
+% {(\SubvertThis\ForceName
+% \FName[Heinrich Wilhelm]{\noexpand\textSC{R\"uhmann}};}
+% {7 March 1902\,--\,3 October 1994) was a German actor
+% in over 100 films.
+% \Name[Heinz]{\noexpand\textSC{R\"uhmann}}\dots}
+%
+% \printindex
+% \end{document}
+% \end{VerbatimOut}
%
-% Normally we define a macro for use in name arguments in the document preamble in order to ensure that it is always defined:
% \begin{quote}\small
-% \StartNum
-% \begin{verbatim}
-%\makeatletter
-%\newcommand*\Fbox[1]{%
-% \if@nameauth@DoAlt\protect\fbox{#1}\else#1\fi
-%}
-%\makeatother\end{verbatim}
+% \VerbatimInput[gobble=0]{\NameauthTestFile}
+%
+% \IndexRef[Heinrich Wilhelm]{\noexpand\textSC{R\"uhmann}}
+% {\noexpand\textSC{R\"uhmann}, Heinz}
+%
+% \renewcommand*\NamesFormat{}
+% \renewcommand*\MainNameHook{\AltOff}
+%
+% \newcommand{\RefArticle}[3]
+% {^^A
+% \def\check{#2}^^A
+% \ifx\check\empty
+% \noindent\ForgetThis\textsl{#1}\ #3
+% \else
+% \noindent\ForgetThis\textsl{#1}\ #2\ #3
+% \fi\medskip
+% }
+%
+% \RefArticle
+% {\RevComma\Name[Greta]{\noexpand\textSC{Garbo}}}
+% {}
+% {(18 September 1905\,--\,15 April 1990) was a Swedish
+% film actress during the 1920s and 1930s.
+% \Name[Greta]{\noexpand\textSC{Garbo}}\dots}
+%
+% \RefArticle
+% {\Name{\noexpand\textSC{Misora}, Hibari}}
+% {(W:\,``\RevName\Name*{\noexpand\textSC{Misora}, Hibari}'';}
+% {29 May 1937\,--\,24 June 1989) was a Japanese singer
+% and actress noted for her positive message.
+% \Name{\noexpand\textSC{Misora}, Hibari}\dots}
+%
+% \RefArticle
+% {\RevComma\Name[Heinz]{\noexpand\textSC{R\"uhmann}}}
+% {(\SubvertThis\ForceName
+% \FName[Heinrich Wilhelm]{\noexpand\textSC{R\"uhmann}};}
+% {7 March 1902\,--\,3 October 1994) was a German actor
+% in over 100 films.
+% \Name[Heinz]{\noexpand\textSC{R\"uhmann}}\dots}
% \end{quote}
-% \makeatletter\newcommand*\Fbox[1]{\if@nameauth@DoAlt\protect\fbox{#1}\else#1\fi}\makeatother
%
-% 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:
+% \endgroup^^A Local format hook redefinition
+% \AltFormatInactive
+%
+% \begin{Quote}{\Name[L.M.]{Montgomery},
+% \textit{Anne of Green Gables}, C 5}
+% I read in a book once that a rose by any other name would smell as sweet, but I've never been able to believe it. I don't believe a rose \textsc{would} be as nice if it was called a thistle or a skunk cabbage.
+% \end{Quote}
+%
+% \newpage
+%
+% \subsection{Roman Names}
+% \label{sec:Romani}
+%
+% Roman names tend to be among the most variable in terms of treatment. As far as \textsf{nameauth} is concerned, they range from being treated as Western names to being treated in very special ways. Below we show some variations.
+%
+% \subsubsection[General Market]{Casual Reading / General Book Market}
+%
+% \begin{itemize}
+% \item Treat as a Western name, especially among well-known Roman names like
+% \Name*[M.T.]{Cicero}[Marcus Tullius], where the final name, \Cicero, is a
+% surname and the rest forenames:\footnote{Philip J. Adler, \textit{World
+% Civilizations}, 3rd ed. (Belmont, Calif.: Thomson/Wadsworth, 2003).}
+%
% \begin{quote}\small
-% \ContinueNum
-% \begin{verbatim}
-%\renewcommand*\MainNameHook{\AltOff}
-%\let\FrontNameHook\MainNameHook\end{verbatim}
+% \begin{Verbatim}
+% \TagName[Julius]{Caesar}{, imperator} % for index
+% \Name[Julius]{Caesar}[Gaius Julius]\\
+% \Name*[Julius]{Caesar}\\
+% \Name[Julius]{Caesar}
+% \end{Verbatim}
+% \Name[Julius]{Caesar}[Gaius Julius]^^A
+% \PatInfo{\ShowPattern[Julius]{Caesar}[Gaius Julius]!MN}\\
+% \Name*[Julius]{Caesar}\\
+% \Name[Julius]{Caesar}\\[1ex]
+% Index: \ShowIdxPageref*[Julius]{Caesar}^^A
+% \end{quote}
+%
+% \item Treat as a Western name; put \textit{nomen} and \textit{cognomen} in
+% \meta{SNN}:\footnote{Paul L. Maier, \textit{In the Fullness of Time: A
+% Historian Looks at Christmas, Easter, and the Early Church}, revised ed.
+% (San Francisco: Harper, 1991).}
+%
+% \begin{quote}\small
+% \begin{Verbatim}
+% \ForgetThis\Name[Lucius]{Sergius Paulus}\\
+% \Name[Lucius]{Sergius Paulus}
+% \end{Verbatim}
+% \ForgetThis\Name[Lucius]{Sergius Paulus}^^A
+% \PatInfo{\ShowPattern[Lucius]{Sergius Paulus}!MN}\\
+% \Name[Lucius]{Sergius Paulus}\\[1ex]
+% Index: \ShowIdxPageref*[Lucius]{Sergius Paulus}^^A
% \end{quote}
-%\renewcommand*\MainNameHook{\AltOff}
-%\let\FrontNameHook\MainNameHook
%
-% When sorting names, be sure to use \cmd{\noexpand} as shown previously:
+% \item Treat as ancient names, especially those with no \textit{praenomen}:
+%
% \begin{quote}\small
-% \ContinueNum
-% \begin{verbatim}
-%\begin{nameauth}
-% \< deSmet & Pierre-Jean &
-% \noexpand\Fbox{\noexpand\AltCaps{d}e~Smet} & >
-%\end{nameauth}
-%
-%\PretagName[Pierre-Jean]%
-% {\noexpand\Fbox{\noexpand\AltCaps{d}e~Smet}}%
-% {de~Smet, Pierre-Jean}\end{verbatim}
+% \begin{Verbatim}
+% \ForgetThis\Name{Pontius, Pilate}[Pilatus]\\
+% \Name*{Pontius, Pilate}\\
+% \Name{Pontius, Pilate}\\
+% \end{Verbatim}
+% \ForgetThis\Name{Pontius, Pilate}[Pilatus]^^A
+% \PatInfo{\ShowPattern{Pontius, Pilate}[Pilatus]!MN}\\
+% \Name*{Pontius, Pilate}\\
+% \Name{Pontius, Pilate}\\[1ex]
+% Index: \ShowIdxPageref*{Pontius, Pilate}^^A
% \end{quote}
+% \end{itemize}
%
-% 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.
+% There is also a method where Roman names are indexed as mononyms using the most recognizable of their names.\footnote{Justo L. González, \textit{The Story of Christianity}, 2 vols. (San Francisco: Harper, 1984).} That method is ill-suited for \textsf{nameauth}.
%
-% \begin{center}\small
-% \begin{tabular}{rll}\toprule
-% First & \cmd{\deSmet} & \deSmet\\
-% \rowcolor{grey}Next & \cmd{\deSmet} & \deSmet\\
-% Long & \cmd{\LdeSmet} & \LdeSmet\\
-% \rowcolor{grey}Short & \cmd{\SdeSmet} & \SdeSmet\\
-% & \cmd{\CapThis}\cmd{\deSmet} & \CapThis\deSmet\\
-% \rowcolor{grey} & \cmd{\ForceName}\cmd{\CapThis}\cmd{\deSmet} & \ForceName\CapThis\deSmet\\\bottomrule
-% \end{tabular}
-% \end{center}
+% \begin{Quote}{\ForgetThis\Name[Julius]{Caesar},
+% \textit{De bello gallico} 3.16.6}
+% Fere libenter homines, id quod volunt, credunt.\\
+% (In general, people willingly believe what they want [to believe].)
+% \end{Quote}
%
-% 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.
-% \endgroup^^A Local format hook redefinition
% \newpage
%
-% \begin{center}\bfseries Rolling Your Own: Intermediate\end{center}
-% \phantomsection
-% \label{page:Intermediate}
+% \subsubsection[Student Reference]{Student-Oriented Reference Works}
+% \AltFormatActive
+%
% \begingroup^^A Local format hook redefinition
-% ``Intermediate'' and ``advanced'' refer to the way that formatting 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
+% \renewcommand*\NamesFormat{}
+% \renewcommand*\MainNameHook{}
%
-% \DescribeMacro{\NameParser}
-% This user-accessible parser (Section~\ref{sec:UserInterface}) builds a printed name from internal, locally-scoped macros \cmd{\FNN}, \cmd{\SNN}, \cmd{\rootb} and \cmd{\suffb}.\Version{3.1} It uses only these Boolean flags:\footnote{The capitalization macros interact with the internal macros before the name parser, therefore, they do not directly engage the output of the name parser.}
-% \begin{quote}\small\MyStretch
-% Only one or the other of these can be true to avoid undocumented behavior.\smallskip\\
-% |\if@nameauth@FullName|\hfill Print a full name if true.\\
-% |\if@nameauth@FirstName|\hfill Print a first name if true.\smallskip\\
-% Reversing without commas overrides reversing with commas.\smallskip\\
-% |\if@nameauth@RevThis|\hfill Reverse name order if true.\\
-% |\if@nameauth@EastFN|\hfill toggled by \cmd{\ForceFN}.\\
-% |\if@nameauth@RevThisComma|\hfill Reverse Western name, add comma.
+% We focus here on reference works meant for general education. In this subsection and the next, we do not use the general formatting conventions of this manual and we activate alternate formatting. Roman names have the following format:
+%
+% \begin{itemize}
+% \item A personal name (\textit{praenomen})
+% \item A clan name (\textit{nomen})
+% \item A distinguishing name, sometimes denoting clan branches
+% (\textit{cognomen}); that could include various affixed names
+% (\textit{agnomina})
+% \end{itemize}
+%
+% In ancient Rome, the family name (\textit{nomen}) was important, helping also to structure society.\footnote{\url{https://en.wikipedia.org/wiki/Patrician_(ancient_Rome)}}
+% The exact roles of names changed over time.\footnote{\url{https://en.wikipedia.org/wiki/Roman_naming_conventions}}
+% A very \href{https://www.youtube.com/watch?v=RMLb1jVl_Uo}{helpful video} can be found on the YouTube channel PolýMATHY by \Name[Luke]{Ranieri}.
+%
+% Some reference works treat the \textit{cognomen} as if it were a Western surname.\footnote{See Geiss, \textit{Geschichte Griffbereit}; Kinder and Hilgemann, \textit{dtv-Atlas zur Weltgeschichte}, 2 vols., 29th printing (1964; Munich: Deutscher Taschenbuch Verlag, 1993). See also \href{https://books.infotoday.com/books/Indexing-names.shtml}{\bfseries this page}.}
+% Using this approach, Roman names encoded with \textsf{nameauth} have this form:
+%
+% \begin{quote}
+% Index: \ShowIdxPageref*[\meta{praenomen} \meta{nomen}]
+% {\meta{cognomen} \meta{agnomen}}\\[1ex]
+% Macro: |\Name[|\meta{praenomen}| |\meta{nomen}|]{|\meta{cognomen}|,|
+% \meta{agnomen}|}|
% \end{quote}
%
-% We create a hook that can ignore the output of \cmd{\@nameauth@Name}, which is the \texttt{\#1} in the hook dispatcher's code \cmd{\bgroup}\meta{Hook}\texttt{\{\#1\}}\cmd{\egroup}:
-% \begin{quote}\small\MyStretch
-% \cmd{\renewcommand*}\meta{FirstHook}\texttt{[1]\{\dots}\cmd{\NameParser}\texttt{\dots\}}
+% With both \textit{praenomen} and \textit{nomen} in \meta{FNN}, as well as the \textit{agnomina} in \meta{Affix}, they drop automatically in subsequent name uses. With a \textit{cognomen} as an effective surname, our choices for name components in the text take on this logic:
+%
+% \begin{itemize}
+% \item Display one of the following in \meta{FNN}:
+% \begin{itemize}
+% \item Only the \textit{praenomen}
+% \item Only the \textit{nomen}
+% \item Both \textit{praenomen} and \textit{nomen}
+% \end{itemize}
+%
+% \item Display one of the following in \meta{SNN}:
+% \begin{itemize}
+% \item Only the \textit{cognomen}
+% \item Both \textit{cognomen} and \textit{agnomina}
+% \end{itemize}
+% \end{itemize}
+%
+% We accomplish this by using macros in the name arguments:
+%
+% \begin{itemize}
+% \item If the macros in the name arguments will be ``segmented'' in some
+% way, as \cmd{\CapThis} does, then use alternate formatting
+% (Sections~\ref{sec:AltFormat}).
+% \item When using Boolean flags (\texttt{\textbackslash if}\meta{flag}) in
+% the macros that represent name elements, ensure that those flags only change
+% their value within the local scope of the name formatting hooks
+% (Section~\ref{sec:Formatting}).
+% \item Two Boolean flags are needed for each automated variant in the name. One
+% flag reflects the global state and the name form in the index. The other
+% reflects the local state of the formatting hooks.
+% \end{itemize}
+%
+% \negmedskip
+% \NameArgWarning
+%
+% Since we have four name components, we need at most eight Boolean flags. Our two examples each use six flags, with four in common and one separate pair each. In the preamble we define all macros and conditionals used in naming macro arguments. Instead of \texttt{\textbackslash ifNoNomen} we use \texttt{\textbackslash ifNoGens} for readability.
+%
+% We must use \cmd{\noexpand} in the macro arguments. We define macros in both \meta{FNN} and \meta{SNN} that expand conditionally. We use the quick interface to define name shorthands, and we sort the name with \cmd{\PretagName}. False Boolean flags display longer name forms. True flags display shorter forms.
+%
+% We used \cmd{\PretagName} and \cmd{\TagName} as needed (cf. Section~\ref{sec:NameAncient}. These formatting hooks used with Roman names also work with other name types.
+%
+% \ifdefined\NameauthDoTestFiles \edef\NameauthTestFile{test11_07.tex}\else
+% \edef\NameauthTestFile{\jobname.tmp}\fi
+%
+% \begin{VerbatimOut}{\NameauthTestFile}
+% \documentclass{article}
+% \input{compat.tex} % Included with nameauth; needed only if
+% % compiling on multiple TeX distros or LaTeX engines.
+% \usepackage{makeidx}
+% \usepackage[altformat]{nameauth}
+% \makeindex
+%
+% % Global Boolean flags need to be defined only once.
+% \newif\ifNoPraenomen
+% \newif\ifNoCognomen
+% \newif\ifNoGens
+% \newif\ifNoAgnomen
+%
+% % Local Boolean flags need to be defined only once.
+% \newif\ifXPrae
+% \newif\ifXCogn
+% \newif\ifXGens
+% \newif\ifXAgno
+%
+% % Name variant macros need to be defined uniquely for each
+% % name. First is Scipio. Second is Gracchus.
+%
+% \newcommand*\SCIPi
+% {%
+% \ifXGens Publius\else
+% \ifXPrae Cornelius\else
+% Publius Cornelius%
+% \fi
+% \fi
+% }
+%
+% \newcommand*\SCIPii
+% {%
+% \ifXAgno Scipio\else
+% Scipio Africanus%
+% \fi
+% }
+%
+% \newcommand*\TSemp
+% {%
+% \ifXGens Tiberius\else
+% \ifXPrae Sempronius\else
+% Tiberius Sempronius%
+% \fi
+% \fi
+% }
+%
+% % Quick interface definitions. The first shows
+% % the concept of Roman names without extra features.
+% % The second (Gracchus) adds name info tags.
+%
+% \begin{nameauth}
+% \< Scipio & \noexpand\SCIPi & \noexpand\SCIPii & >
+% \< TGrac & \noexpand\TSemp & Gracchus & >
+% \end{nameauth}
+%
+% % We add the name data tag.
+% \NameAddInfo[\noexpand\TSemp]{Gracchus}
+% { (consul, 177 \textsc{bc})}
+%
+% % Sorting and tagging the names
+% \PretagName[\noexpand\SCIPi]{\noexpand\SCIPii}
+% {Scipio Africanus}
+% \PretagName[\noexpand\TSemp]{Gracchus}
+% {Gracchus, Tiberius Sempronius}
+% \TagName[\noexpand\TSemp]{Gracchus}{, consul}
+%
+% \begin{document}
+%
+% % Although it is helpful to set everything up
+% % In the preamble, it is not absolutely necessary.
+% % Here we define the simpler set of formatting hooks
+% % for Scipio, although the complex hooks will work
+% % for both equally as well.
+%
+% \renewcommand*\NamesFormat[1]
+% {%
+% \ifNoPraenomen\XPraetrue\fi%
+% \ifNoGens\XGenstrue\fi%
+% \ifNoCognomen\XCogntrue\fi%
+% \ifNoAgnomen\XAgnotrue\fi%
+% #1%
+% \global\NoPraenomenfalse%
+% \global\NoGensfalse%
+% \global\NoCognomenfalse%
+% \global\NoAgnomenfalse%
+% }
+%
+% \renewcommand*\MainNameHook[1]
+% {%
+% \ifNoPraenomen\XPraetrue\fi%
+% \ifNoGens\XGenstrue\fi%
+% \ifNoCognomen\XCogntrue\fi%
+% \ifNoAgnomen\XAgnotrue\fi%
+% #1%
+% \global\NoPraenomenfalse%
+% \global\NoGensfalse%
+% \global\NoCognomenfalse%
+% \global\NoAgnomenfalse%
+% }
+%
+% \Scipio\ was born around 236 \textsc{bc} into the
+% Scipiones branch of the Cornelii clan.
+% \NoAgnomentrue\Scipio\ rose to military fame during the
+% Second Punic War. Thereafter he was known as \Scipio.
+% He flourished during the Egyptian reigns of
+% \Name{Ptolemy, IV}[IV Philopator] and
+% \Name{Ptolemy, V}[V Epiphanes], and the Syrian
+% reigns of \Name{Seleucus, III}[III Ceraunus] and
+% \Name{Antiochus, III}[III the Great].
+%
+% % We make no change to \MainNameHook, but we do
+% % change \NamesFormat to display any extant
+% % name data tags.
+%
+% \renewcommand*\NamesFormat[1]
+% {%
+% \ifNoPraenomen\XPraetrue\fi%
+% \ifNoGens\XGenstrue\fi%
+% \ifNoCognomen\XCogntrue\fi%
+% \ifNoAgnomen\XAgnotrue\fi%
+% #1%
+% \ifcsname\NameauthPattern!DB\endcsname
+% \expandafter\csname\NameauthPattern!DB\endcsname%
+% \fi
+% \global\NoPraenomenfalse%
+% \global\NoGensfalse%
+% \global\NoCognomenfalse%
+% \global\NoAgnomenfalse%
+% }
+%
+% \TGrac\ served as tribune of the plebs in 184 \textsc{bc}.
+% \NoGenstrue\STGrac\ was elected praetor for 180 \textsc{bc},
+% after which he was appointed governor of Hispania Citerior.
+% serving with the rank of proconsul. In 177 \textsc{bc},
+% he was elected consul, again in 163 \textsc{bc}.
+%
+% \printindex
+% \end{document}
+% \end{VerbatimOut}
+%
+% \begin{quote}
+% \VerbatimInput[gobble=0, lastline=74]{\NameauthTestFile}
% \end{quote}
%
-% 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
-% \cmd{\renewcommand*}\meta{SubsequentHook}\texttt{[1]\{\dots}\cmd{\AltOff}\cmd{\NameParser}\texttt{\dots\}}
+% Formatting hook macros need to be redefined only once. We reset the global Boolean flags to ensure the longest name forms in the index. The local Boolean flags automatically revert to false outside the scope of the formatting hooks.
+%
+% \renewcommand*\NamesFormat[1]
+% {^^A
+% \ifNoPraenomen\XPraetrue\fi^^A
+% \ifNoGens\XGenstrue\fi^^A
+% \ifNoCognomen\XCogntrue\fi^^A
+% \ifNoAgnomen\XAgnotrue\fi^^A
+% #1^^A
+% \global\NoPraenomenfalse^^A
+% \global\NoGensfalse^^A
+% \global\NoCognomenfalse^^A
+% \global\NoAgnomenfalse^^A
+% }
+%
+% \renewcommand*\MainNameHook[1]
+% {^^A
+% \ifNoPraenomen\XPraetrue\fi^^A
+% \ifNoGens\XGenstrue\fi^^A
+% \ifNoCognomen\XCogntrue\fi^^A
+% \ifNoAgnomen\XAgnotrue\fi^^A
+% #1^^A
+% \global\NoPraenomenfalse^^A
+% \global\NoGensfalse^^A
+% \global\NoCognomenfalse^^A
+% \global\NoAgnomenfalse^^A
+% }
+% \begin{quote}\small
+% \VerbatimInput[gobble=0, firstline=75, lastline=87]{\NameauthTestFile}
+%
+% \newpage
+%
+% \VerbatimInput[gobble=0, firstline=88, lastline=110]{\NameauthTestFile}
+%
+% \Scipio\ was born around 236 \textsc{bc} into the
+% Scipiones branch of the Cornelii clan.
+% \NoAgnomentrue\Scipio\ rose to military fame during the
+% Second Punic War. Thereafter he was known as \Scipio.
+% He flourished during the Egyptian reigns of
+% \Name{Ptolemy, IV}[IV Philopator] and
+% \Name{Ptolemy, V}[V Epiphanes], and the Syrian
+% reigns of \Name{Seleucus, III}[III Ceraunus] and
+% \Name{Antiochus, III}[III the Great].
+% \end{quote}
+%
+% Below we show more name name variations than were shown above. In addition, we use those same formatting hooks to display non-Roman names:
+%
+% \begin{Block}
+% |\ForgetThis\Scipio|\dotfill\ForgetThis\Scipio\\
+% |\LScipio|\dotfill\LScipio\\
+% |\Scipio|\dotfill\Scipio\\
+% |\SScipio|\dotfill\SScipio\\[2ex]
+% |\NoAgnomentrue\LScipio|\dotfill\NoAgnomentrue\LScipio\\
+% |\NoAgnomentrue\Scipio|\dotfill\NoAgnomentrue\Scipio\\
+% |\NoGenstrue\SScipio|\dotfill\NoGenstrue\SScipio\\
+% |\NoPraenomentrue\SScipio|\dotfill\NoPraenomentrue\SScipio\\[2ex]
+% |\Name*{Ptolemy, IV}[IV Philopator]|\dotfill\Name*{Ptolemy, IV}[IV Philopator]\\
+% |\Name*{Ptolemy, IV}|\dotfill\Name*{Ptolemy, IV}\\
+% |\Name{Ptolemy, IV}|\dotfill\Name{Ptolemy, IV}
+% \end{Block}
+%
+% In Section~\ref{sec:NameAncient}, we used name data tags instead of \meta{Alternate} in the first-use formatting hook. Here we show the changes needed to add name data tags to the first-use formatting hook. Even though we are changing the formatting hooks throughout the document, none of the changes cause different index entries and will be unnoticed in the finished document.
+%
+% \NameAddInfo[\noexpand\TSemp]{Gracchus}
+% { (consul, 177 \textsc{bc})}
+% \renewcommand*\NamesFormat[1]
+% {^^A
+% \ifNoPraenomen\XPraetrue\fi^^A
+% \ifNoGens\XGenstrue\fi^^A
+% \ifNoCognomen\XCogntrue\fi^^A
+% \ifNoAgnomen\XAgnotrue\fi^^A
+% #1^^A
+% \ifcsname\NameauthPattern!DB\endcsname
+% \expandafter\csname\NameauthPattern!DB\endcsname^^A
+% \fi
+% \global\NoPraenomenfalse^^A
+% \global\NoGensfalse^^A
+% \global\NoCognomenfalse^^A
+% \global\NoAgnomenfalse^^A
+% }
+% \begin{quote}\small
+% \VerbatimInput[gobble=0,firstline=111]{\NameauthTestFile}
+%
+% \TGrac\ served as tribune of the plebs in 184 \textsc{bc}.
+% \NoGenstrue\STGrac\ was elected praetor for 180 \textsc{bc},
+% after which he was appointed governor of Hispania Citerior.
+% serving with the rank of proconsul. In 177 \textsc{bc},
+% he was elected consul, again in 163 \textsc{bc}.
+% \end{quote}
+%
+% Below we show both a Roman name and a different name type working the same way with the formatting hook:
+%
+% \begin{Block}
+% |\ForgetThis\TGrac|\dotfill\ForgetThis\TGrac\\
+% |\LTGrac|\dotfill\LTGrac\\
+% |\NoGenstrue\LTGrac|\dotfill\NoGenstrue\LTGrac\\
+% |\TGrac|\dotfill\TGrac\\
+% |\STGrac|\dotfill\STGrac\\
+% |\NoGenstrue\STGrac|\dotfill\NoGenstrue\STGrac\\
+% |\NoPraenomentrue\STGrac|\dotfill\NoPraenomentrue\STGrac\\[2ex]
+% |\ForgetThis\Dem|\dotfill\ForgetThis\Dem\\
+% |\LDem|\dotfill\LDem\\
+% |\Dem|\dotfill\Dem
+% \end{Block}
+%
+% \begin{Quote}{\ForgetThis\Scipio\break
+% \hbox{}\hfill attributed by \Name[Titus]{Livius} in
+% \textit{Ab urbe condita} B 30}
+% Bellum parate, quoniam pacem pati non potuistis.\\
+% (Prepare for war, for it seems that you are unable to tolerate peace.)
+% \end{Quote}
+%
+% \newpage
+%
+% \subsubsection[Scholarly Reference]{Scholarly Reference Works}
+%
+% The \textit{Oxford Classical Dictionary} and other scholarly sources index according to the \textit{nomen}. That approach moves the \textit{nomen} from \meta{FNN} to \meta{SNN} thus:
+%
+% \begin{quote}
+% Index: \ShowIdxPageref*[\meta{praenomen}]{\meta{nomen} \meta{cognomen}
+% \meta{agnomen}}\\[1ex]
+% Macro: |\Name[|\meta{praenomen}|]{|\meta{nomen} \meta{cognomen}
+% \meta{agnomen}|}|
+% \end{quote}
+%
+% This indexing method is incompatible with the previous section, but we show both in this manual. We retain most of the code used in the last section, but we change the macros used in the name arguments. The logic still shows all names for the index, but we make different choices in the text:
+%
+% \begin{itemize}
+% \item Display the \textit{praenomen} in \meta{FNN}:
+% \item Display one of the following in \meta{SNN}:
+% \begin{itemize}
+% \item Only the \textit{cognomen}
+% \item Both the \textit{cognomen} and \textit{agnomina}
+% \item Only the \textit{nomen}
+% \item Both the \textit{nomen} and \textit{cognomen}
+% \item The \textit{nomen}, \textit{cognomen}, and \textit{agnomina}
+% \end{itemize}
+% \end{itemize}
+%
+% \ifdefined\NameauthDoTestFiles \edef\NameauthTestFile{test11_08.tex}\else
+% \edef\NameauthTestFile{\jobname.tmp}\fi
+%
+% \begin{VerbatimOut}{\NameauthTestFile}
+% \documentclass{article}
+% \input{compat.tex} % Included with nameauth; needed only if
+% % compiling on multiple TeX distros or LaTeX engines.
+% \usepackage{makeidx}
+% \usepackage[altformat]{nameauth}
+% \makeindex
+%
+% % Global Boolean flags need to be defined only once.
+% \newif\ifNoPraenomen
+% \newif\ifNoCognomen
+% \newif\ifNoGens
+% \newif\ifNoAgnomen
+%
+% % Local Boolean flags need to be defined only once.
+% \newif\ifXPrae
+% \newif\ifXCogn
+% \newif\ifXGens
+% \newif\ifXAgno
+%
+% % Name variant macros need to be defined
+% % uniquely for each name.
+%
+% \newcommand*\CSB
+% {%
+% \ifXGens
+% \ifXAgno Scipio\else
+% Scipio Barbatus\fi
+% \else
+% \ifXCogn Cornelius\else
+% \ifXAgno Cornelius Scipio\else
+% Cornelius Scipio Barbatus%
+% \fi
+% \fi
+% \fi
+% }
+%
+% % Quick interface definition
+% \begin{nameauth}
+% \< OScipio & Lucius & \noexpand\CSB & > % O for Oxford
+% \end{nameauth}
+%
+% % Sorting and tagging
+% \PretagName[Lucius]{\noexpand\CSB}{Cornelius Scipio Barbatus}
+% \TagName[Lucius]{\noexpand\CSB}{, consul}
+%
+% \renewcommand*\NamesFormat[1]
+% {%
+% \ifNoPraenomen\XPraetrue\fi%
+% \ifNoGens\XGenstrue\fi%
+% \ifNoCognomen\XCogntrue\fi%
+% \ifNoAgnomen\XAgnotrue\fi%
+% #1%
+% \ifcsname\NameauthPattern!DB\endcsname
+% \expandafter\csname\NameauthPattern!DB\endcsname%
+% \fi
+% \global\NoPraenomenfalse%
+% \global\NoGensfalse%
+% \global\NoCognomenfalse%
+% \global\NoAgnomenfalse%
+% }
+%
+% \begin{document}
+%
+% \OScipio\ was born around 337 \textsc{bc} into the
+% Scipiones branch of the Cornelii clan, one of the large
+% patrician clans. \NoGenstrue\NoAgnomentrue\OScipio\ was
+% one of the two elected consuls in 298 \textsc{bc}
+% and served during the Third Samnite War.
+%
+% \printindex
+% \end{document}
+% \end{VerbatimOut}
+%
+% \begin{quote}\small
+% \VerbatimInput[gobble=0]{\NameauthTestFile}
+%
+% \OScipio\ was born around 337 \textsc{bc} into the
+% Scipiones branch of the Cornelii clan, one of the large
+% patrician clans. \NoGenstrue\NoAgnomentrue\OScipio\ was
+% one of the two elected consuls in 298 \textsc{bc}
+% and served during the Third Samnite War.
% \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
-% \cmd{\renewcommand*}\meta{Hook}\texttt{[1]\{\dots}\cmd{\AltOn}\cmd{\NameParser}\texttt{\dots\}}
+% Instead of relying on some \textsf{nameauth} features that drop some names automatically, in all but \meta{FNN} we have to state explicitly what we want:
+%
+% \begin{Block}
+% |\ForgetThis\OScipio|\dotfill\ForgetThis\OScipio\\
+% |\LOScipio|\dotfill\LOScipio\\
+% |\OScipio|\dotfill\OScipio\\
+% |\SOScipio|\dotfill\SOScipio\\[2ex]
+% |\NoCognomentrue\OScipio|\dotfill\NoCognomentrue\OScipio\\
+% |\NoAgnomentrue\OScipio|\dotfill\NoAgnomentrue\OScipio\\
+% |\NoGenstrue\OScipio|\dotfill\NoGenstrue\OScipio\\
+% |\NoGenstrue\NoAgnomentrue\OScipio|\dotfill\NoGenstrue\NoAgnomentrue\OScipio
+% \end{Block}
+%
+% One may create convenience macros instead of using the Boolean flags. Yet this might make things less clear at first glance, for example:
+%
+% \begin{Block}
+% \newcommand*\LucScipio{\NoGenstrue\NoAgnomentrue\OScipio}
+% |\newcommand*\LucScipio{\NoGenstrue\NoAgnomentrue\OScipio}|\\
+% |\ForgetThis\LucScipio|\dotfill\ForgetThis\LucScipio\\
+% |\LucScipio|\dotfill\LucScipio
+% \end{Block}
+%
+% The student and scholarly forms of Roman names are incompatible. Yet we show what the index entries would be in a normal \LaTeX document without hyperlinks:
+%
+% \begin{quote}\small
+% \IndexActual{@}
+% \UntagName[\noexpand\SCIPi]{\noexpand\SCIPii}
+% \TagName[\noexpand\TSemp]{Gracchus}{, consul}
+% \TagName[Lucius]{\noexpand\CSB}{, consul}
+% {\normalsize Popular Reference Works:}\\
+% |\ShowIdxPageref[\noexpand\SCIPi]{\noexpand\SCIPii}|\\
+% \ShowIdxPageref[\noexpand\SCIPi]{\noexpand\SCIPii}\\[1ex]
+% |\ShowIdxPageref[\noexpand\TSemp]{Gracchus}|\\
+% \ShowIdxPageref[\noexpand\TSemp]{Gracchus}\\[1ex]
+% {\normalsize Scholarly Reference Works:}\\
+% |\ShowIdxPageref[Lucius]{\noexpand\CSB}|\\
+% \ShowIdxPageref[Lucius]{\noexpand\CSB}
+% \TagName[\noexpand\SCIPi]{\noexpand\SCIPii}{\string|hyperpage}
+% \TagName[\noexpand\TSemp]{Gracchus}{, consul\string|hyperpage}
+% \TagName[Lucius]{\noexpand\CSB}{, consul\string|hyperpage}
% \end{quote}
+% \endgroup^^A Local format hook redefinition
+% \AltFormatInactive
+%
+% \subsection[Special Uses]{Special Name Uses}
+% \label{sec:SpecialUses}
+%
+% \AltFormatActive
+% \begingroup^^A Local format hook redefinition
+% Previously, formatting hooks either changed typefaces or mutated their arguments. Now we move beyond parsing the argument as we have received it.\medskip
+%
+% \DescribeMacro{\NameParser}
+% The user-accessible parser (Section~\ref{sec:NameParser}) builds a printed name from internal, locally-scoped macros. Its output is affected by a subset of the Boolean flags, namely, those flags that affect long and short forms, as well as name reversal. Within the hooks we can use the user-accessible parser as often as we want.
+%
+% \begin{itemize}
+% \item |\if@nameauth@FullName| toggles long or short name forms, as in
+% \cmd{\Name} versus \cmd{\Name*}. |\if@nameauth@FirstName| toggles
+% forenames when |\if@nameauth@FullName| is false. When modifying
+% these flags, one must know when they are normally true or false.
+% \item |\if@nameauth@RevThis| reverses name order.
+% \cmd{\ForceFN} normally toggles |\if@nameauth@EastFN|.
+% Using |\if@nameauth@RevThis|, reversing without commas,
+% overrides |\if@nameauth@RevThisComma| if both are true.
+% \item |\if@nameauth@RevThisComma| creates the form
+% \meta{SNN}, \meta{FNN}.
+% \end{itemize}
+%
+% Two Boolean\Info{\texttt{\textbackslash ifNameauthWestern}\break \texttt{\textbackslash ifNameauthObsolete}} flags are available to users so that they can know quickly what type of name was processed most recently by \cmd{\@nameauth@Choice}, which is called by all macros that take name arguments. These allow hook designers to vary the hook behavior based on the name type. They also persist after the macro that uses name arguments exits, unlike many other flags.
+%
+% \begin{center}\small\medstretch
+% \begin{tabular}{lccl}\toprule
+% Boolean flag & True & False & Name Type\\
+% \midrule
+% \texttt{\textbackslash ifNameauthWestern} & \YES & \NO & Western\\
+% \texttt{\textbackslash ifNameauthObsolete} & \NO & \NO\\\midrule
+% \texttt{\textbackslash ifNameauthWestern} & \NO & \YES & Non-Western\\
+% \texttt{\textbackslash ifNameauthObsolete} & \NO & \NO & current syntax\\
+% \midrule
+% \texttt{\textbackslash ifNameauthWestern} & \NO & \YES & Non-Western\\
+% \texttt{\textbackslash ifNameauthObsolete} & \NO & \YES & obsolete syntax\\
+% \bottomrule
+% \end{tabular}
+% \end{center}
+%
+% Since we are using the \texttt{altformat} option or \cmd{\AltFormatActive}, we can expect that formatting is activated by default. We design a subsequent-use hook that deactivates alternate formatting inside of it:
+%
+% \begin{SyntaxBox}
+% \cmd{\renewcommand*}\meta{SubsequentHook}\texttt{[1]\{\dots}\cmd
+% {\AltOff}\cmd{\NameParser}\texttt{\dots\}}
+% \end{SyntaxBox}
+%
+% If we used \cmd{\AltFormatActive*}, where the formatting macros are enabled, but deactivated by default, then we might want a hook that activates the macros:
+%
+% \begin{SyntaxBox}
+% \cmd{\renewcommand*}\meta{Hook}\texttt{[1]\{\dots}\cmd{\AltOn}\cmd
+% {\NameParser}\texttt{\dots\}}
+% \end{SyntaxBox}
+% \negmedskip
+%
+% \subsubsection{Reference Work II}
+%
+% Below we revisit the idea of a reference work, leveraging the formatting hooks to format headwords, add information from name info tags:
+%
+% \ifdefined\NameauthDoTestFiles \edef\NameauthTestFile{test11_09.tex}\else
+% \edef\NameauthTestFile{\jobname.tmp}\fi
+%
+% \begin{VerbatimOut}{\NameauthTestFile}
+% \documentclass{article}
+% \input{compat.tex} % Included with nameauth; needed only if
+% % compiling on multiple TeX distros or LaTeX engines.
+% \usepackage{makeidx}
+% \usepackage[altformat]{nameauth}
+% \makeindex
+%
+% % Boolean flags; the first sets up headwords and the second
+% % indicates that a non-Western form should not be reversed.
+% \newif\ifHeadword
+% \newif\ifAncientName
+%
+% % Sorting and tagging the names:
+% \PretagName[Charles]{\noexpand\textBF{Babbage}}{Babbage, Charles}
+% \PretagName{\noexpand\textUC{Kanade}, Takeo}{Kanade Takeo}
+% \PretagName[Ada]{\noexpand\textIT{Lovelace}}{Lovelace, Ada}
+%
+% % Adding name information:
+% \NameAddInfo{Aristotle}{ (384--322 \textsc{bc})}
+% \NameAddInfo[Charles]{\noexpand\textBF{Babbage}}{ (1791--1871)}
+% \NameAddInfo{\noexpand\textUC{Kanade}, Takeo}{ (1945-- )}
+% \NameAddInfo[Ada]{\noexpand\textIT{Lovelace}}
+% { (Augusta Ada King, Countess of Lovelace
+% [n\'ee Byron]; 1815--52)}
+%
+% % Redefining the formatting hooks:
+% \makeatletter
+% \renewcommand\NamesFormat[1]
+% {%
+% \ifHeadword
+% \ifNameauthWestern
+% \@nameauth@RevThisCommatrue%
+% \bfseries \NameParser%
+% \normalfont%
+% \ifcsname\NameauthPattern!DB\endcsname
+% \expandafter\csname\NameauthPattern!DB\endcsname%
+% \fi
+% \else
+% \bgroup%
+% \bfseries \NameParser%
+% \unless\ifAncientName
+% \normalfont; W:\AltOff\space
+% \@nameauth@RevThistrue \NameParser%
+% \fi
+% \normalfont%
+% \ifcsname\NameauthPattern!DB\endcsname
+% \expandafter\csname\NameauthPattern!DB\endcsname%
+% \fi
+% \egroup%
+% \fi
+% \else
+% \NameParser%
+% \fi
+% \global\Headwordfalse%
+% \global\AncientNamefalse%
+% }
+% \makeatother
+% \renewcommand\MainNameHook{\AltOff}
+%
+% % Define related macros:
+% \newcommand\Headword{\Headwordtrue\ForgetThis}
+% \newcommand{\RefArticle}[2]
+% {%
+% \noindent\Headword #1 #2%
+% \medskip
+% }
+%
+% \begin{document}
+%
+% \RefArticle{\AncientNametrue\Name{Aristotle}}{was the first to offer
+% a system of logic, most notably syllogistic logic, that would
+% become the basis for discrete states and circuitry of
+% digital computers. \Name{Aristotle}\dots}
+%
+% \RefArticle{\Name[Charles]{\noexpand\textBF{Babbage}}}{designed and
+% built the Difference Engine and began work on the Analytical
+% Engine. \Name[Charles]{\noexpand\textBF{Babbage}}\dots}
+%
+% \RefArticle{\Name{\noexpand\textUC{Kanade}, Takeo}}{is one of the
+% foremost pioneers in the field of computer vision.
+% \Name{\noexpand\textUC{Kanade}, Takeo}\dots}
+%
+% \RefArticle{\Name[Ada]{\noexpand\textIT{Lovelace}}}{collaborated with
+% \Name*[Charles]{\noexpand\textBF{Babbage}}* and wrote what some
+% consider to be the first computer program for the Analytical
+% Engine. \Name[Ada]{\noexpand\textIT{Lovelace}}\dots}
+%
+% \printindex
+% \end{document}
+% \end{VerbatimOut}
%
-% Within the hooks we can use the user-side parser as often as we want. We also can change internal Boolean flags, for example:
% \begin{quote}\small
-% \StartNum
-% \begin{verbatim}
-%\makeatletter
-%\renewcommand*\NamesFormat[1]{\small%
-% \hbox to 3.5em{[now]\hfill}\space\NameParser\\%
-% \@nameauth@FullNametrue%
-% \hbox to 3.5em{[long]\hfill}\space\NameParser\\%
-% \@nameauth@FullNamefalse%
-% \@nameauth@FirstNametrue%
-% \hbox to 3.5em{[short]\hfill}\space\NameParser}
-%\makeatother
-%\let\MainNameHook\NamesFormat\end{verbatim}
-%
-% \smallskip
+% \VerbatimInput[gobble=0]{\NameauthTestFile}
+%
+% \NameAddInfo{Aristotle}{ (384--322 \textsc{bc})}
+% \NameAddInfo[Charles]{\noexpand\textBF{Babbage}}{ (1791--1871)}
+% \NameAddInfo{\noexpand\textUC{Kanade}, Takeo}{ (1945-- )}
+% \NameAddInfo[Ada]{\noexpand\textIT{Lovelace}}
+% { (Augusta Ada King, Countess of Lovelace
+% [n\'ee Byron]; 1815--52)}
+%
% \makeatletter
-% \renewcommand*\NamesFormat[1]{\small^^A
-% \hbox to 3.5em{[now]\hfill}\space\NameParser\\^^A
-% \@nameauth@FullNametrue^^A
-% \hbox to 3.5em{[long]\hfill}\space\NameParser\\^^A
-% \@nameauth@FullNamefalse^^A
-% \@nameauth@FirstNametrue^^A
-% \hbox to 3.5em{[short]\hfill}\space\NameParser}
+% \renewcommand\NamesFormat[1]
+% {^^A
+% \ifHeadword
+% \ifNameauthWestern
+% \@nameauth@RevThisCommatrue^^A
+% \bfseries \NameParser^^A
+% \normalfont^^A
+% \ifcsname\NameauthPattern!DB\endcsname
+% \expandafter\csname\NameauthPattern!DB\endcsname^^A
+% \fi
+% \else
+% \bgroup^^A
+% \bfseries \NameParser^^A
+% \unless\ifAncientName
+% \normalfont; W:\AltOff\space
+% \@nameauth@RevThistrue \NameParser^^A
+% \fi
+% \normalfont^^A
+% \ifcsname\NameauthPattern!DB\endcsname
+% \expandafter\csname\NameauthPattern!DB\endcsname^^A
+% \fi
+% \egroup^^A
+% \fi
+% \else
+% \NameParser^^A
+% \fi
+% \global\Headwordfalse^^A
+% \global\AncientNamefalse^^A
+% }
% \makeatother
-% \let\MainNameHook\NamesFormat
+% \renewcommand\MainNameHook{\AltOff}
+%
+% \newcommand\Headword{\Headwordtrue\ForgetThis}
+% \newcommand{\RefArticle}[2]
+% {^^A
+% \noindent\Headword #1 #2^^A
+% \medskip
+% }
+%
+% \RefArticle{\AncientNametrue\Name{Aristotle}}{was the first to offer
+% a system of logic, most notably syllogistic logic, that would
+% become the basis for discrete states and circuitry of
+% digital computers. \Name{Aristotle}\dots}
+%
+% \RefArticle{\Name[Charles]{\noexpand\textBF{Babbage}}}{designed and
+% built the Difference Engine and began work on the Analytical
+% Engine. \Name[Charles]{\noexpand\textBF{Babbage}}\dots}
%
-% One instance of \cmd{\JRIV} displays:
+% \RefArticle{\Name{\noexpand\textUC{Kanade}, Takeo}}{is one of the
+% foremost pioneers in the field of computer vision.
+% \Name{\noexpand\textUC{Kanade}, Takeo}\dots}
%
-% \JRIV
+% \RefArticle{\Name[Ada]{\noexpand\textIT{Lovelace}}}{collaborated with
+% \Name*[Charles]{\noexpand\textBF{Babbage}}* and wrote what some
+% consider to be the first computer program for the Analytical
+% Engine. \Name[Ada]{\noexpand\textIT{Lovelace}}\dots}
% \end{quote}
%
-% The proof of concept above is interesting, but not very useful in a practical setting. Now we move on toward more useful and practical designs.
-% \newpage
+% \subsubsection{Marginalia}
+%
+% \ifdefined\NameauthDoTestFiles \edef\NameauthTestFile{test11_10.tex}\else
+% \edef\NameauthTestFile{\jobname.tmp}\fi
+%
+% \begin{VerbatimOut}{\NameauthTestFile}
+% \documentclass{article}
+% \input{compat.tex} % Included with nameauth; needed only if
+% % compiling on multiple TeX distros or LaTeX engines.
+% \usepackage{makeidx}
+% \usepackage[altformat]{nameauth}
+% \makeindex
+%
+% % Global Boolean flags need to be defined only once.
+% \newif\ifSpecialFN
+% \newif\ifSpecialSN
+% \newif\ifRevertSN
+%
+% % Name variant macros need to be defined
+% % uniquely for each name.
+%
+% % For a long name, we want to use ``William'' in the text
+% % and ``Wm.'' in the margin.
+%
+% \newcommand*\WM
+% {%
+% \ifSpecialFN Wm.\else
+% William\fi
+% }
+%
+% % The first surname use will be ``Shakespeare'', but ``the
+% % Bard'' thereafter. We allow for alternate caps.
+% % We can get ``Shakespeare'' thereafter by toggling a flag.
+%
+% \newcommand*\SHK
+% {%
+% \ifRevertSN
+% \textSC{Shakespeare}\else
+% \ifSpecialSN
+% \noexpand\AltCaps{t}he Bard\else
+% \textSC{Shakespeare}%
+% \fi
+% \fi
+% }
+%
+% % Here is how we toggle that flag.
+%
+% \newcommand*\Revert{\RevertSNtrue}
+%
+% % Quick interface name definition:
+%
+% \begin{nameauth}
+% \< Shak & \noexpand\WM & \noexpand\SHK & >
+% \end{nameauth}
+%
+% % Sorting and tagging the name:
+%
+% \PretagName[\noexpand\WM]{\noexpand\SHK}
+% {Shakespeare, William}
+% \PretagName[Robert]{\textSC{Burns}}{Burns, Robert}
+%
+% % The ``first-use'' hook prints a name, then tries
+% % to insert a margin note using a different name form
+% % and the user-accessible parser. Finally it resets
+% % the reversion flag, which is only effective in the
+% % ``subsequent-use'' hook. Note how macros in the
+% % name arguments take the role of what the internal
+% % Boolean flags might otherwise handle.
%
% \makeatletter
-% \renewcommand*\NamesFormat[1]{^^A
-% \RevertSNfalse\SpecialFNfalse\SpecialSNfalse#1^^A
-% \unless\ifinner\marginpar{^^A
-% \footnotesize\raggedleft^^A
-% \@nameauth@FullNametrue^^A
-% \@nameauth@FirstNamefalse^^A
-% \@nameauth@EastFNfalse^^A
-% \SpecialFNtrue\SpecialSNfalse^^A
-% \NameParser}^^A
-% \fi\global\RevertSNfalse}
-% \renewcommand*\MainNameHook[1]{^^A
-% \AltOff\SpecialFNfalse\SpecialSNtrue#1^^A
+% \renewcommand*\NamesFormat[1]
+% {%
+% \RevertSNfalse\SpecialFNfalse\SpecialSNfalse%
+% #1%
+% \unless\ifinner
+% \marginpar
+% {%
+% \footnotesize\raggedleft%
+% \SpecialFNtrue\SpecialSNfalse%
+% \NameParser%
+% }%
+% \fi
+% \global\RevertSNfalse%
+% }
+%
+% \renewcommand*\MainNameHook[1]
+% {%
+% \AltOff\SpecialFNfalse\SpecialSNtrue%
+% #1%
% \unless\ifinner
% \unless\ifRevertSN
-% \marginpar{^^A
+% \marginpar
+% {%
+% \footnotesize\raggedleft%
+% \SpecialFNfalse\SpecialSNfalse%
+% \NameParser%
+% }%
+% \fi
+% \fi
+% \global\RevertSNfalse%
+% }
+% \makeatother
+%
+% \begin{document}
+%
+% \ForgetThis\Shak\ is the national poet of England
+% in much the same way that \Name[Robert]{\textSC{Burns}}
+% is that of Scotland. With the latter's rise of influence
+% in the 1800s, \Revert\Shak\ became known as ``\Shak''.
+%
+% \printindex
+% \end{document}
+% \end{VerbatimOut}
+%
+% Starting where we left off with Roman names, we begin in the document preamble by defining Boolean flags and macros. As with Roman names, their default values produce the name form in the index entry. The default name form aligns with the default Boolean flag setting: false. All non-default values and expansions of these macros occur only in the formatting hooks. We use \cmd{\PretagName} to sort the names. \cmd{\Revert} is used to print a last name without a margin note.
+%
+% \begin{quote}
+% \VerbatimInput[gobble=0,lastline=39]{\NameauthTestFile}
+% \end{quote}
+%
+% Next we define the two formatting hooks that structure the ways in which these macros can expand when printed in the text. We force \cmd{\NamesFormat} to print only allows only the default name via \cmd{\RevertSNfalse}, \cmd{\SpecialFNfalse}, and \cmd{\SpecialSNfalse}. \cmd{\MainNameHook} disables alternate formatting with \cmd{\AltOff}, but it allows variant name forms.
+%
+% We print the default name in the body text. If allowed, we print a margin paragraph with an alternate full name using \cmd{\NameParser}. Both hooks set \cmd{\RevertSNfalse} on exit, so that \cmd{\Revert} works on a per-name basis.
+%
+% \makeatletter
+% \renewcommand*\NamesFormat[1]
+% {^^A
+% \RevertSNfalse\SpecialFNfalse\SpecialSNfalse^^A
+% #1^^A
+% \unless\ifinner
+% \marginpar
+% {^^A
% \footnotesize\raggedleft^^A
-% \@nameauth@FullNamefalse^^A
-% \@nameauth@FirstNamefalse^^A
-% \@nameauth@EastFNfalse^^A
-% \SpecialFNfalse\SpecialSNfalse^^A
-% \NameParser}^^A
+% \SpecialFNtrue\SpecialSNfalse^^A
+% \NameParser^^A
+% }^^A
+% \fi
+% \global\RevertSNfalse^^A
+% }
+% \renewcommand*\MainNameHook[1]
+% {^^A
+% \AltOff\SpecialFNfalse\SpecialSNtrue^^A
+% #1^^A
+% \unless\ifinner
+% \unless\ifRevertSN
+% \marginpar
+% {^^A
+% \footnotesize\raggedleft^^A
+% \SpecialFNfalse\SpecialSNfalse^^A
+% \NameParser^^A
+% }^^A
% \fi
-% \fi\global\RevertSNfalse}
+% \fi
+% \global\RevertSNfalse^^A
+% }
% \makeatother
-% We begin in the document preamble by defining a series of conditionals and macros whose default expansion produces the index entry, yet whose other expansions occur only in the formatting hooks. Then we create a name that is composed only of macros, using \cmd{\noexpand} with \cmd{\WM} and \cmd{\SHK}. We use \cmd{\PretagName} to sort the names. \cmd{\Revert} is used to print a last name without a margin note.
% \begin{quote}\small
-% \StartNum
-% \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}
-%
-%\begin{nameauth}
-% \< Shak & \noexpand\WM & \noexpand\SHK & >
-%\end{nameauth}
-%
-%\PretagName[\noexpand\WM]{\noexpand\SHK}{Shakespeare, William}
-%\PretagName[Robert]{\textSC{Burns}}{Burns, Robert}\end{verbatim}
+% \VerbatimInput[gobble=0,firstline=40]{\NameauthTestFile}
+%
+% \ForgetThis\Shak\ is the national poet of England
+% in much the same way that \Name[Robert]{\textSC{Burns}}
+% is that of Scotland. With the latter's rise of influence
+% in the 1800s, \Revert\Shak\ became known as ``\Shak''.
% \end{quote}
%
-% Below we define the two formatting hooks that structure the ways in which these macros can expand when printed in the text. \cmd{\NamesFormat} allows only the canonical name via \cmd{\RevertSNfalse}, \cmd{\SpecialFNfalse}, and \cmd{\SpecialSNfalse}. We print the canonical name in the body text. If allowed, 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.
+% \endgroup^^A Local format hook redefinition
+% \AltFormatInactive
+% \negmedskip
+%
+% \ReturnLink
+%
+% \AltFormatActive
+% \begin{Quote}{\ForgetThis\Shak\break
+% \hbox{}\hfill ``Julius Caesar'', Act III, Scene II}
+% \textbf{Antony:} Friends, Romans, countrymen, lend me your ears;\\
+% I come to bury Caesar, not to praise him.\\
+% The evil that men do lives after them;\\
+% The good is oft interred with their bones;\\
+% So let it be with Caesar. The noble Brutus\\
+% Hath told you Caesar was ambitious:\\
+% If it were so, it was a grievous fault,\\
+% And grievously hath Caesar answer'd it.\\
+% Here, under leave of Brutus and the rest---\\
+% For Brutus is an honourable man;\\
+% So are they all, all honourable men---\\
+% Come I to speak in Caesar's funeral.\\
+% He was my friend, faithful and just to me:\\
+% But Brutus says he was ambitious;\\
+% And Brutus is an honourable man.
+% \end{Quote}
+% \AltFormatInactive
+%
+% \newpage
+%
+% \section{Planned Obsolescence}
+%
+% \subsection[Pseudonyms]{Almost Obsolete: Pseudonym Macros}
+% \label{sec:AKA}
+%
+% The macros described in this section were early features of \textsf{nameauth}. They do not work like many of the other macros that display names and may be removed in the future. We retain them at present for backward compatibility.
+%
+% \subsubsection{Special Syntax}
+%
+% To save space, we show \meta{SAFX} as the equivalent of \meta{SNN|,| Affix}. The macros in this section all take arguments of the form:
+%
+% \begin{SyntaxBoxii}
+% Target Name & Cross-Reference Name\\\midrule
+% \oarg{FNN}\marg{SAFX} & \oarg{xref FNN}\marg
+% {xref SAFX}\oarg{xref Alternate}\\
+% \end{SyntaxBoxii}\negmedskip
+%
+% \begin{itemize}
+% \item The target name comes first, which is the opposite of
+% \cmd{\IndexRef}. There the target name comes last because it is text
+% passed to the index macros.
+% \item The cross-reference comes last to allow for the widest range of
+% name forms (again, the opposite of \cmd{\IndexRef}).
+% We avoid two optional arguments in succession by preventing the target
+% from having a final optional argument. Neither \meta{Alternate} nor
+% the obsolete syntax cannot be used with the target name. Both can be
+% used with the cross-reference.
+% \item \meta{SAFX} and \meta{xref SAFX} can have comma-delimited suffixes.
+% \item One cannot use \cmd{\TagName} with a cross-reference, but one can
+% sort a cross-reference with \cmd{\PretagName}
+% (Section~\ref{sec:IndexSort}):
+% \end{itemize}\negmedskip
+%
+% \subsubsection{The Macros}
+%
+% \DescribeMacro{\AKA}
+% The \textit{also known as} macro and its starred form display an alias in the text and create a cross-reference in the index.
+% \DescribeMacro{\AKA*}
+% They format names differently than the naming macros because they use the name patterns for cross-references as a means to account for the name forms that they print in the test.
+%
+% \begin{SyntaxBox}
+% \cmd{\AKA\ }\oarg{FNN}\marg{SAFX}\oarg{xref FNN}\marg
+% {xref SAFX}\oarg{xref Alternate}\\
+% \cmd{\AKA*}\oarg{FNN}\marg{SAFX}\oarg{xref FNN}\marg
+% {xref SAFX}\oarg{xref Alternate}\\
+% \end{SyntaxBox}\negmedskip
+%
+% \begin{itemize}
+% \item Both macros create a cross-reference in the index to the
+% target name.
+% \item \cmd{\AKA} prints a long form of the cross-reference name in
+% the text. \cmd{\SeeAlso} works with \cmd{\AKA}, \cmd{\AKA*},
+% \cmd{\PName}, and \cmd{\PName*}.
+% \item If \meta{xref Alternate} is present in a Western name form, then
+% instead of \meta{xref FNN}, \meta{xref Alternate} will be printed
+% in the text.
+% \item If \meta{xref Alternate} is present in a non-Western name form,
+% then instead of \meta{xref Affix} (if present), \meta{xref Alternate}
+% will be printed in the text.
+% \item If \meta{xref Alternate} is present without either \meta{xref FNN}
+% or \meta{xref Affix}, the obsolete syntax is used.
+% \item \cmd{\AKA*} is analogous to \cmd{\FName}. \cmd{\ForceFN} works
+% with it. The \texttt{oldAKA} option implies \cmd{\ForceFN} with every
+% use of \cmd{\AKA*}.
+% \item Neither \cmd{\AKA} nor its derivatives permit the effects of
+% \cmd{\ForgetThis} and \cmd{\SubvertThis} to ``pass through'' because
+% they produce output in the text. The \texttt{oldreset} option negates
+% this.
+% \end{itemize}
+%
+% Below we make cross-references to \cmd{\Name[Bob]\{Hope\}} \Name[Bob]{Hope}; all of the forms listed create the cross-reference ``\ShowIdxPageref*[Leslie Townes]{Hope} \textit{see} \ShowIdxPageref*[Bob]{Hope}''.
+%
+% \begin{center}\footnotesize
+% \vspace{2ex}
+% \Info{\strut\footnotesize Name Pattern(s):\hfill \break
+% \ttfamily \ShowPattern[Bob]{Hope}!MN\break
+% \ShowPattern[Leslie Townes]{Hope}!PN}
+% \vspace{-2ex}\smallstretch
+% \begin{tabular}{p{0.6\textwidth}l}\toprule
+% |\AKA[Bob]{Hope}[Leslie Townes]{Hope}| &
+% \AKA[Bob]{Hope}[Leslie Townes]{Hope}\\
+% \rowcolor{nagrey}|\RevComma\AKA[Bob]{Hope}[Leslie Townes]{Hope}| &
+% \RevComma\AKA[Bob]{Hope}[Leslie Townes]{Hope}\\
+% |\AKA[Bob]{Hope}[Leslie Townes]{Hope}[Lester T.]| &
+% \AKA[Bob]{Hope}[Leslie Townes]{Hope}[Lester T.]\\
+% \rowcolor{nagrey}|\AKA*[Bob]{Hope}[Leslie Townes]{Hope}| &
+% \AKA*[Bob]{Hope}[Leslie Townes]{Hope}\\
+% |\AKA*[Bob]{Hope}[Leslie Townes]{Hope}[Lester]| &
+% \AKA*[Bob]{Hope}[Leslie Townes]{Hope}[Lester]\\\bottomrule
+% \end{tabular}
+% \end{center}
+%
+% We display other name forms after referring to some names to ensure that they have sensible page references:
+%
% \begin{quote}\small
-% \ContinueNum
-% \begin{verbatim}
-%\makeatletter
-%\renewcommand*\NamesFormat[1]{%
-% \RevertSNfalse\SpecialFNfalse\SpecialSNfalse#1%
-% \unless\ifinner\marginpar{%
-% \footnotesize\raggedleft%
-% \@nameauth@FullNametrue%
-% \@nameauth@FirstNamefalse%
-% \@nameauth@EastFNfalse%
-% \SpecialFNtrue\SpecialSNfalse%
-% \NameParser}%
-% \fi\global\RevertSNfalse}
-%\renewcommand*\MainNameHook[1]{%
-% \AltOff\SpecialFNfalse\SpecialSNtrue#1%
-% \unless\ifinner
-% \unless\ifRevertSN
-% \marginpar{%
-% \footnotesize\raggedleft%
-% \@nameauth@FullNamefalse%
-% \@nameauth@FirstNamefalse%
-% \@nameauth@EastFNfalse%
-% \SpecialFNfalse\SpecialSNfalse%
-% \NameParser}%
-% \fi
-% \fi\global\RevertSNfalse}
-%\makeatother\end{verbatim}
-%
-% \smallskip
-% \ForgetThis\Shak\ \cmd{\ForgetThis}\cmd{\Shak} is the national poet of England in much the same way that \Name[Robert]{\textSC{Burns}} \cmd{\Name[Robert]\{}\cmd{\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}.
+% \begin{tabular}{ll}
+% \cmd{\ForgetThis}\cmd{\Name\{Louis, XIV\}} &
+% \ForgetThis\Name{Louis, XIV}\\
+% \cmd{\Name\{Lao-tzu\}} & \Name{Lao-tzu}\\
+% \cmd{\Name[Lafcadio]\{Hearn\}} & \Name[Lafcadio]{Hearn}\\
+% \cmd{\Name[Charles]\{du\string~Fresne\}} &
+% \Name[Charles]{du~Fresne}\\
+% \end{tabular}
% \end{quote}
-% \endgroup^^A Local format hook redefinition
+% Caps and reversing macros work on the arguments that are printed
+% in the text.
%
-% \begin{center}\bfseries Rolling Your Own: Advanced\end{center}
-% \phantomsection
+% \begin{center}\small
+% \vspace{2ex}
+% \PatInfo{\ShowPattern{Louis, XIV}!MN\break
+% \ShowPattern{Lao-tzu}!MN\break
+% \ShowPattern[Lafcadio]{Hearn}!MN\break
+% \ShowPattern[Charles]{du~Fresne}!MN\break
+% \ShowPattern{Sun King}!PN\break
+% \ShowPattern{Li, Er}!PN\break
+% \ShowPattern{du~Cange}!PN\break
+% \ShowPattern{Koizumi, Yakumo}!PN}
+% \vspace{-2ex}\medstretch
+% \begin{tabular}{p{0.65\textwidth}l}\toprule
+% |\AKA{Louis, XIV}{Sun King}| & \AKA{Louis, XIV}{Sun King}\\
+% \rowcolor{nagrey}|\AKA*{Louis, XIV}{Sun King}| &
+% \AKA{Louis, XIV}{Sun King}\\
+% |\AKA{Lao-tzu}{Li, Er}| & \AKA{Lao-tzu}{Li, Er}\\
+% \rowcolor{nagrey}|\AKA*{Lao-tzu}{Li, Er}| & \AKA*{Lao-tzu}{Li, Er}\\
+% |\AKA[Charles]{du~Fresne}{du~Cange}| &
+% \AKA[Charles]{du~Fresne}{du~Cange}\\
+% \rowcolor{nagrey}|\CapThis\AKA[Charles]{du~Fresne}{du~Cange}| &
+% \CapThis\AKA[Charles]{du~Fresne}{du~Cange}\\
+% |\CapName\AKA[Lafcadio]{Hearn}{Koizumi, Yakumo}| &
+% \CapName\AKA[Lafcadio]{Hearn}{Koizumi, Yakumo}\\
+% \rowcolor{nagrey}|\RevName\AKA[Lafcadio]{Hearn}{Koizumi, Yakumo}| &
+% \RevName\AKA[Lafcadio]{Hearn}{Koizumi, Yakumo}\\\bottomrule
+% \end{tabular}
+% \end{center}
+% \medskip
+%
+% \DescribeMacro{\PName}
+% These convenience macros were an early feature of \textsf{nameauth}. They print a main name followed by a cross-reference in parentheses.
+% \DescribeMacro{\PName*}
+% If one is inclined to view \cmd{\AKA} as rubbish, these two macros are a biological hazard.
+%
+% \begin{SyntaxBox}
+% \cmd{\PName\ }\oarg{FNN}\marg{SAFX}\oarg{xref\,FNN}\marg
+% {xref\,SAFX}\oarg{xref\,Alternate}\\
+% \cmd{\PName*}\oarg{FNN}\marg{SAFX}\oarg{xref\,FNN}\marg
+% {xref\,SAFX}\oarg{xref\,Alternate}\\
+% \end{SyntaxBox}
+%
+% \cmd{\PName*} is like \cmd{\Name*} to the extent that it prints a long form
+% of \meta{FNN}\meta{SAFX}. It does not affect the cross-reference
+% \meta{xref FNN}\meta{xref SAFX}\meta{xref Alternate}.
+%
+% \begin{itemize}
+% \item Most prefix macros only affect \meta{FNN}\meta{SAFX},
+% not the cross-reference.
+% \item The cross-reference always has a long form.
+% \item \cmd{\SkipIndex} keeps both names out of the index.
+% \item \meta{Alternate} and the obsolete syntax work only with
+% the cross-reference.
+% \end{itemize}
+%
+% If we attempted to use |\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}''. We use \cmd{\ForgetName\{William, I\}}^^A
+% \ForgetName{William, I} to prepare for the following example. We do not show the name patterns in the margin.
+%
+% \begingroup\small
+% \begin{itemize}[leftmargin=2cm]
+% \item[Macro:] \cmd{\PName[Mark]\{Twain\}[Samuel L.]\{Clemens\}}
+% \item[Text:] \ForgetThis\PName[Mark]{Twain}[Samuel L.]{Clemens}\\
+% \PName[Mark]{Twain}[Samuel L.]{Clemens}
+% \item[Macro:] \cmd{\PName*[Mark]\{Twain\}[Samuel L.]\{Clemens\}}
+% \item[Text:] \PName*[Mark]{Twain}[Samuel L.]{Clemens}
+% \item[Index:] \ShowIdxPageref*[Samuel L.]{Clemens} \textit{see}
+% \ShowIdxPageref*[Mark]{Twain}\medskip
+% \item[Macro:] \cmd{\PName\{Voltaire\}[François-Marie]\{Arouet\}}
+% \item[Text:] \PName{Voltaire}[François-Marie]{Arouet}
+% \item[Index:] \ShowIdxPageref*[François-Marie]{Arouet} \textit{see}
+% \ShowIdxPageref*{Voltaire}\medskip
+% \item[Macro:] \cmd{\PName\{William, I\}\{William, the Conqueror\}}
+% \item[Text:] \PName{William, I}{William, the Conqueror}\\
+% \PName{William, I}{William, the Conqueror}
+% \item[Index:] \ShowIdxPageref*{William, the Conqueror} \textit{see}
+% \ShowIdxPageref*{William, I}\medskip
+% \item[Macro:] \cmd{\PretagName\{}\cmd{\textit\{Doctor mellifluus\}\}^^A
+% \{Doctor mellifluus\}}\\
+% \cmd{\PName\{Bernard, of Clairvaux\}\{}\cmd{\textit\{Doctor mellifluus\}}
+% \item[Text:] \PName{Bernard, of Clairvaux}{\textit{Doctor mellifluus}}\\
+% \PName{Bernard, of Clairvaux}{\textit{Doctor mellifluus}}
+% \item[Index:] \ShowIdxPageref*{\textit{Doctor mellifluus}} \textit{see}
+% \ShowIdxPageref*{Bernard, of Clairvaux}\medskip
+% \item[Macro:] \cmd{\ForgetThis}\cmd{\PName\{Lao-tzu\}\{Li, Er\}}
+% \item[Text:] \ForgetThis\PName{Lao-tzu}{Li, Er}
+% \item[Index:] \ShowIdxPageref*{Li, Er} \textit{see}
+% \ShowIdxPageref*{Lao-tzu}
+% \end{itemize}
+% \endgroup
+%
+% While these macros certainly work, much like the obsolete syntax, they can be criticized as a design idea that originally seemed to hold promise, yet disappointed in practice due to using the cross-reference system for name formatting.
+%
+% \subsubsection[Workarounds]{Formatting Workarounds}
+%
+% By default, the macros in this section use only the formatting hooks for subsequent instances of names (Section~\ref{sec:Formatting}).\medskip
+%
+% First, the \texttt{formatAKA}\Info{\texttt{formatAKA}} option will permit \cmd{\ForceName} to force the ``first-use'' formatting hooks to be employed, but under different conditions. The name patterns that control these uses (Section~\ref{sec:NamePatterns}) apply only to cross-references; they are a distinct system of patterns that differs from normal names and ignores the difference between main-matter and front-matter name formatting.
+%
+% \begin{center}\small\medstretch
+% \makeatletter\@nameauth@AKAFormattrue\makeatother\global\NamesInactive
+% \begin{tabular}{rll}\toprule
+% & |\ForgetThis\Eliz| & |\AKA{Elizabeth,I}%|\\
+% & & |[Good Queen]{Bess}|\\
+% \rowcolor{nagrey}^^A
+% Front Matter: & \ForgetThis\Eliz &
+% \AKA{Elizabeth,I}[Good Queen]{Bess}\\
+% \global\NamesActive^^A
+% Main Matter: & \ForgetThis\Eliz &
+% \AKA{Elizabeth, I}[Good Queen]{Bess}\\
+% \rowcolor{nagrey}^^A
+% With \cmd{\ForceName}: & &
+% \ForceName\AKA{Elizabeth, I}[Good Queen]{Bess}\\\bottomrule
+% \end{tabular}
+% \vspace{-14ex}
+% \small\PatInfo{\ShowPattern{Elizabeth, I}!NF\break
+% \ShowPattern[Good Queen]{Bess}!PN\break
+% \ShowPattern{Elizabeth, I}!MN}
+% \vspace{14ex}
+% \end{center}\medskip
+%
+% The first appearance of \AKA{Elizabeth,I}[Good Queen]{Bess} above uses \cmd{\FrontNamesFormat} as its formatting hook because it is the first occurrence of the alternate name in the front matter. After that, even though \AKA{Elizabeth,I}[Good Queen]{Bess} occurs for the first time in the main matter, it uses the subsequent-use \cmd{\MainNameHook} because we are not using the regular name patterns. We need to use \cmd{\ForceName}, which triggers the expected use of \cmd{\NamesFormat}, the first-use main-matter hook.\medskip
+%
+% Second,\Info{\texttt{alwaysformat}} we can use the \texttt{alwaysformat} option to force only the use of \cmd{\NamesFormat} and \cmd{\FrontNamesFormat}. Of course, this can look like rubbish in certain circumstances.
+%
+% \begin{quote}\small
+% \makeatletter\@nameauth@AlwaysFormattrue\makeatother
+% \ForgetThis\LEliz\ was known as ``\AKA{Elizabeth,I}[Good Queen]{Bess}''.
+% Again we mention Queen \Eliz, ``\AKA{Elizabeth, I}[Good Queen]{Bess}''.
+% Using \cmd{\ForceName}: \ForceName\AKA{Elizabeth, I}[Good Queen]{Bess}.
+% \end{quote}
+%
+% \subsection{Obsolete Syntax}
+% \label{sec:Obsolete}
+%
+% This non-Western syntax limits alternate names and cross-references, prevents the use of comma-delimited names, and complicates indexing. It is a ``ghost of \textsf{nameauth} past'' that remains for the sake of backward compatibility and to prevent ``holes'' where naming macro arguments are discarded without apparent reason.
+%
+% \begin{SyntaxBox}
+% \cmd{\Name}\marg{SNN}\oarg{Alternate}
+% \end{SyntaxBox}
+%
+% The genesis of this syntax was the use of the \meta{Alternate} field for variant forenames in Western names, personal names in Eastern names, and sobriquets, titles, and so on in ancient names. Yet this prevented using alternate names for non-Western names and it limited those names to an unacceptable second-tier status. Developing the comma delimiter in \meta{SNN, Affix} presented significant challenges, but it was worth overcoming them to put all name forms on equal footing.
+%
+% We show this syntax for the sake of completeness, but we strongly encourage using the comma-delimited syntax instead.
+%
+% \begin{itemize}
+% \item One must \emph{leave empty} the first optional \meta{FNN} argument.
+% \item One must \emph{never} use the comma-delimited argument \meta{Affix}.
+% \item These names \emph{always} use \meta{Alternate}, which acts like
+% \meta{Affix} usually does, and affects both name and index patterns
+% (Section~\ref{sec:NamePatterns}).
+% \item These names take the form \meta{SNN Alternate} in the index.
+% \item In this manual we designate these names with a double dagger (\ddag).
+% \end{itemize}
+%
+% \begin{quote}\small
+% \begin{Verbatim}
+% \Name{Henry}[VIII] % Ancient
+% \Name{Chiang}[Kai-shek] % Eastern
+% \begin{nameauth}
+% \< Dagb & & Dagobert & I > % Ancient
+% \< Yosh & & Yoshida & Shigeru > % Eastern
+% \< Fukuyama & &
+% \noexpand\textUC{Fukuyama} & Takeshi > % Alt. format
+% \end{nameauth}
+% \end{Verbatim}
+% \end{quote}
+%
+% \AltFormatActive
+% After studying in the US during the 1930s, in 1954 Rev.
+% \cmd{\Fukuyama}\cmd{\ddag} \Fukuyama\ddag\ published
+% \textit{Nihon Fukuin R\=uteru Ky\=okai Shi} (History
+% of the Evangelical Lutheran Church in Japan).
+% \AltFormatInactive
+%
+% \newpage
+%
+% \begin{center}\small\medstretch
+% \begin{tabular}{ll}\toprule
+% |\ForgetThis\Name{Henry}[VIII]\ddag| &
+% \ForgetThis\Name{Henry}[VIII]\ddag\\
+% |\Name{Henry}[VIII]\ddag| &
+% \Name{Henry}[VIII]\ddag\\
+% \rowcolor{nagrey}|\ForgetThis\Name{Chiang}[Kai-shek]\ddag| &
+% \ForgetThis\Name{Chiang}[Kai-shek]\ddag\\
+% \rowcolor{nagrey}|\Name{Chiang}[Kai-shek]\ddag| &
+% \Name{Chiang}[Kai-shek]\ddag\\
+% |\Dagb\ddag| & \Dagb\ddag\\
+% |\Dagb\ddag| & \Dagb\ddag\\
+% \rowcolor{nagrey}|\CapName\Yosh\ddag| & \CapName\Yosh\ddag\\
+% \rowcolor{nagrey}|\CapName\RevName\LYosh\ddag| & \CapName\RevName\LYosh\ddag\\
+% |\AltFormatActive| \AltFormatActive\\
+% |\ForgetThis\Fukuyama\ddag| & \ForgetThis\Fukuyama\ddag\\
+% |\Fukuyama\ddag| & \Fukuyama\ddag\\
+% |\AltFormatInactive| \AltFormatInactive\\\bottomrule
+% \end{tabular}
+% \end{center}
+%
+% Regardless of its flaws, the obsolete syntax shares name patterns, index tags, data tags, and index entries with the current syntax:
+%
+% \begin{quote}\small
+% \begin{tabular}{@{}lll}
+% Obsolete syntax: & \cmd{\ForgetThis}\cmd{\Name\{Henry\}[VIII]}\cmd{\ddag} &
+% \ForgetThis\Name{Henry}[VIII]\ddag\\
+% & \cmd{\ShowPattern\{Henry\}[VIII]} & \ShowPattern{Henry}[VIII]\\[1ex]
+% Current syntax: & \cmd{\Name\{Henry, VIII\}} & \Name{Henry, VIII}\\
+% & \cmd{\ShowPattern\{Henry, VIII\}} & \ShowPattern{Henry, VIII}\\
+% \end{tabular}
+% \end{quote}
+%
+% We do not expect people to use the obsolete syntax much anymore. Here we list more advantages to using the current syntax and avoiding the old.
+%
+% \begin{itemize}
+% \item Only the newer syntax permits variants:\\
+% \cmd{\Name*\{Henry, VIII\}[Tudor]} \Name*{Henry, VIII}[Tudor].
+% \item The proper form for the old syntax is, e.g.:\\
+% \cmd{\Name*\{Henry\}[VIII]}: \Name*{Henry}[VIII].
+% \IndexInactive
+% \item \cmd{\Name[Henry]\{VIII\}} is a malformed Western name:\\
+% ``\Name*[Henry]{VIII}'' and ``\Name[Henry]{VIII}''.
+% \item \cmd{\Name[Henry]\{VIII\}[Tudor]} also is malformed:\\
+% ``\Name*[Henry]{VIII}[Tudor]'' and ``\Name[Henry]{VIII}[Tudor]''
+% \item Both incorrect name forms have the same index entry:\\
+% ``\ShowIdxPageref*[Henry]{VIII}''
+% \IndexActive
+% \end{itemize}
+% \negmedskip
+%
+% \ReturnLink
+%
+% \begin{Quote}{\Name[Salman]{Rushdie}, \textit{The Satanic Verses} (1988)}
+% Names, once they are in common use, quickly become mere sounds, their etymology being buried, like so many of the earth's marvels, beneath the dust of habit.
+% \end{Quote}
+%
+% \newpage
+%
+% \begingroup^^A General format hook redefinition.
+% \section{Advanced Customization}
+% \label{sec:AdvCustomize}
+%
+% This section is meant to help those who want to access package internals as they add features, as well as those who want to design their own constructs and mesh them with \textsf{nameauth}. Here we set the formatting hooks to the package default, setting aside the common usage in this manual. We also use alternate formatting for much of this section. We set up the following hooks:
+%
+% \begin{VerbatimOut}{\jobname.tmp}
+% \renewcommand*\NamesFormat{}
+% \renewcommand*\FrontNamesFormat{}
+% \renewcommand*\MainNameHook{\AltOff}
+% \renewcommand*\FrontNameHook{\AltOff}
+% \end{VerbatimOut}
+%
+% \begin{quote}\small
+% \VerbatimInput[gobble=0]{\jobname.tmp}
+% \end{quote}
+% \input{\jobname.tmp}
+%
+% \AltFormatActive
% \begingroup^^A Local format hook redefinition
-% Here is how formatting hooks were designed before version 3.0. Updating older hooks may be helpful, but is not necessary. We\Warn{} 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 mitigate errors. In the preamble, three flags replace package internals.\footnote{The internal flag \texttt{\textbackslash @nameauth@DoAlt} activates formatting, \cmd{\CapThis} sets \texttt{\textbackslash @nameauth@DoCaps} true, and \texttt{\textbackslash @nameauth@InHook} is set by the hook dispatcher.}
-% Setting \texttt{\textbackslash Fboxtrue} is equivalent to using \cmd{\AltFormatActive}:
+%
+% \subsection{Using Package Internals}
+%
+% We move toward custom formatting by starting with the established paradigm of alternate formatting (Section~\ref{sec:AltFormat}). We will change the ``back-end'' macros to a degree, so that we get a substantially similar experience with custom code.
+%
+% \ifdefined\NameauthDoTestFiles \edef\NameauthTestFile{test13_01.tex}\else
+% \edef\NameauthTestFile{\jobname.tmp}\fi
+%
+% \begin{VerbatimOut}{\NameauthTestFile}
+% \documentclass{article}
+% \input{compat.tex} % Included with nameauth; needed only if
+% % compiling on multiple TeX distros or LaTeX engines.
+% \usepackage{makeidx}
+% \usepackage[altformat]{nameauth}
+% \makeindex
+%
+% % Alternate formatting macro definition
+% \makeatletter
+% \newcommand*\Fbox[1]{%
+% \if@nameauth@DoAlt\protect\fbox{#1}\else#1\fi
+% }
+% \makeatother
+%
+% % Quick interface definition
+% \begin{nameauth}
+% \< deSmet & Pierre-Jean &
+% \noexpand\Fbox{\noexpand\AltCaps{d}e~Smet} & >
+% \end{nameauth}
+%
+% % Sorting and tagging
+% \PretagName[Pierre-Jean]%
+% {\noexpand\Fbox{\noexpand\AltCaps{d}e~Smet}}%
+% {de~Smet, Pierre-Jean}
+%
+% \renewcommand*\MainNameHook{\AltOff}
+% \renewcommand*\FrontNameHook{\AltOff}
+%
+% \begin{document}
+%
+% \deSmet\ was a Jesuit missionary who arrived in North
+% America in 1821 at the age of twenty, after a year of seminary
+% education. \CapThis\deSmet\ was ordained in 1827 and worked
+% among American Indian nations after 1837. We can show the forms
+% \LdeSmet\ and \SdeSmet.
+%
+% \printindex
+% \end{document}
+% \end{VerbatimOut}
+%
+% When designing macros that work with alternate formatting hooks, the Boolean flags that one must know are \texttt{\textbackslash if@nameauth@DoAlt}, which is toggled by \cmd{\AltOn} and \cmd{\AltOff}; \texttt{\textbackslash if@nameauth@DoCaps}, which handles capitalization via \cmd{\AltCaps}, and \texttt{\textbackslash if@nameauth@InHook}, which is true when the formatting hooks are called.
+%
+% Next, instead of using \cmd{\textSC} and friends, we define a new macro that works in similar fashion. \cmd{\Fbox} draws a frame around the name:
+%
% \begin{quote}\small
-% \StartNum
-% \begin{verbatim}
-%\newif\ifFbox% Replaces \@nameauth@DoAlt
-%\newif\ifFirstCap% Replaces \@nameauth@DoCaps
-%\newif\ifInHook% Replaces \@nameauth@InHook
-%\Fboxtrue\end{verbatim}
+% \VerbatimInput[gobble=0,lastline=13]{\NameauthTestFile}
% \end{quote}
%
-% \newcommand*\Fbox[1]{\ifFbox\protect\fbox{#1}\else#1\fi}
-% Also in the preamble, the formatting macro is like what we have seen, except it refers to \texttt{\textbackslash ifFbox}:\footnote{As previously noted, we define \cmd{\Fbox} locally in this manual because it has multiple definitions, but are very careful where we use names with it.}
+% Since \cmd{\AltCaps} is part of \textsf{nameauth}, one need not reinvent that wheel. Just use it in the name arguments and sorting macros:
+%
% \begin{quote}\small
-% \ContinueNum
-% \begin{verbatim}
-%\newcommand*\Fbox[1]{%
-% \ifFbox\protect\fbox{#1}\else#1\fi
-%}\end{verbatim}
+% \VerbatimInput[gobble=0,firstline=14,lastline=24]{\NameauthTestFile}
% \end{quote}
%
-% \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:
+% \makeatletter
+% \newcommand*\Fbox[1]{^^A
+% \if@nameauth@DoAlt\protect\fbox{#1}\else#1\fi
+% }^^A
+% \makeatother
+%
+% \newpage
+%
+% The final step is redefining the hooks, which can be quite simple:
+%
% \begin{quote}\small
-% \ContinueNum
-% \begin{verbatim}
-%\renewcommand*\AltCaps[1]{%
-% \ifInHook
-% \ifFirstCap\MakeUppercase{#1}\else#1\fi
-% \else
-% #1%
-% \fi
-%}\end{verbatim}
+% \VerbatimInput[gobble=0,firstline=25]{\NameauthTestFile}
+%
+% \deSmet\ was a Jesuit missionary who arrived in North
+% America in 1821 at the age of twenty, after a year of seminary
+% education. \CapThis\deSmet\ was ordained in 1827 and worked
+% among American Indian nations after 1837. We can show the forms
+% \LdeSmet\ and \SdeSmet.
% \end{quote}
%
+% Some formatting, such as the use of \cmd{\textSC}, is fairly standard. Other formatting, such as \cmd{\Fbox} above, is more ornamental.
+% \endgroup^^A Local format hook redefinition
+% \AltFormatInactive
+%
+% \AltFormatActive
+% \begingroup^^A Local format hook redefinition
+%
+% \subsection{Using Separate Macros}
+%
+% \ForgetName[Pierre-Jean]{\noexpand\Fbox{\noexpand\AltCaps{d}e~Smet}}
+% One is not tied to the internal mechanisms of \textsf{nameauth} in order to design alternate formatting, but this approach is more labor-intensive and requires one to keep track of more details.
+%
+% We still recommend using \cmd{\AltFormatActive} to mitigate errors. The following example tries to show how far one might go afield, yet remain compatible with standard names.
+%
+% Three Boolean flags replace package internals. The flag \texttt{\textbackslash ifFbox} activates formatting, \cmd{\CapThis} sets \texttt{\textbackslash ifFirstCap} true, and \texttt{\textbackslash ifInHook} is set manually, instead of being set by the hook dispatcher.
+%
+% \ifdefined\NameauthDoTestFiles \edef\NameauthTestFile{test13_02.tex}\else
+% \edef\NameauthTestFile{\jobname.tmp}\fi
+%
+% \begin{VerbatimOut}{\NameauthTestFile}
+% \documentclass{article}
+% \input{compat.tex} % Included with nameauth; needed only if
+% % compiling on multiple TeX distros or LaTeX engines.
+% \usepackage{makeidx}
+% \usepackage[altformat]{nameauth}
+% \makeindex
+%
+% \newif\ifFbox % Replaces \if@nameauth@DoAlt
+% \newif\ifFirstCap % Replaces \if@nameauth@DoCaps
+% \newif\ifInHook % Replaces \if@nameauth@InHook
+% \Fboxtrue % Replaces \AltFormatActive
+%
+% % Alternate formatting macro definition
+% \newcommand*\Fbox[1]{%
+% \ifFbox\protect\fbox{#1}\else#1\fi
+% }
+%
+% % Redefinition of \AltCaps and \CapThis
+% \renewcommand*\AltCaps[1]{%
+% \ifInHook
+% \ifFirstCap\MakeUppercase{#1}\else#1\fi
+% \else
+% #1%
+% \fi
+% }
% \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:
+%
+% % Quick interface definition
+% \begin{nameauth}
+% \< deSmet & Pierre-Jean &
+% \noexpand\Fbox{\noexpand\AltCaps{d}e~Smet} & >
+% \end{nameauth}
+%
+% % Sorting and tagging
+% \PretagName[Pierre-Jean]%
+% {\noexpand\Fbox{\noexpand\AltCaps{d}e~Smet}}%
+% {de~Smet, Pierre-Jean}
+%
+% \begin{document}
+%
+% \deSmet\ was a Jesuit missionary who arrived in North
+% America in 1821 at the age of twenty, after a year of seminary
+% education. \CapThis\deSmet\ was ordained in 1827 and worked
+% among American Indian nations after 1837. We can show the forms
+% \LdeSmet\ and \SdeSmet.
+%
+% \printindex
+% \end{document}
+% \end{VerbatimOut}
+%
% \begin{quote}\small
-% \ContinueNum
-% \begin{verbatim}
-%\renewcommand*\CapThis{\FirstCaptrue}\end{verbatim}
+% \VerbatimInput[gobble=0,lastline=11]{\NameauthTestFile}
% \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}
+% The formatting macro is like what we have seen, except it refers to \texttt{\textbackslash ifFbox}. We define \cmd{\Fbox} locally in this manual, but \cmd{\noexpand} helps isolate those effects.
+%
+% \begin{quote}
+% \VerbatimInput[gobble=0,firstline=12,lastline=16]{\NameauthTestFile}
% \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 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}
+% Our new \cmd{\AltCaps} works like the built-in version, except it does not use the internal macros and flags. We also redefine \cmd{\CapThis} to use our flag instead of the internal flag:
+%
+% \begin{quote}
+% \VerbatimInput[gobble=0,firstline=17,lastline=26]{\NameauthTestFile}
% \end{quote}
%
-% We avoid spurious index entries in the front matter by using the same hooks.
+% We have to reproduce the logic and macros that the package would have provided. That means defining everything from scratch. To emphasize these differences, instead of displaying the macro argument, we use \cmd{\NameParser} to do that.
+%
+% 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} in \cmd{\MainNameHook}:
+%
+% \begin{quote}
+% \VerbatimInput[gobble=0,firstline=27,lastline=32]{\NameauthTestFile}
+% \end{quote}
+%
+% By using the same hook logic and \cmd{\noexpand}, the new ``back-end'' meshes with the ``front-end'' macros used before without creating spurious index entries.
+%
+% \newcommand*\Fbox[1]{^^A
+% \ifFbox\protect\fbox{#1}\else#1\fi
+% }
+% \renewcommand*\AltCaps[1]{^^A
+% \ifInHook
+% \ifFirstCap\MakeUppercase{#1}\else#1\fi
+% \else
+% #1^^A
+% \fi
+% }
+% \renewcommand*\CapThis{\FirstCaptrue}
+% \renewcommand*\NamesFormat[1]
+% {\InHooktrue\NameParser\global\FirstCapfalse}
+% \renewcommand*\MainNameHook[1]
+% {\Fboxfalse\InHooktrue\NameParser\global\FirstCapfalse}
+% \let\FrontNamesFormat\Namesformat
+% \let\FrontNameHook\MainNameHook
+%
% \begin{quote}\small
-% \ContinueNum
-% \begin{verbatim}
-%\let\FrontNamesFormat\Namesformat
-%\let\FrontNameHook\MainNameHook\end{verbatim}
+% \VerbatimInput[gobble=0,firstline=33]{\NameauthTestFile}
+%
+% \deSmet\ was a Jesuit missionary who arrived in North
+% America in 1821 at the age of twenty, after a year of seminary
+% education. \CapThis\deSmet\ was ordained in 1827 and worked
+% among American Indian nations after 1837. We can show the forms
+% \LdeSmet\ and \SdeSmet.
% \end{quote}
%
-% Because we use \cmd{\noexpand}, our ``old-style'' macros will index the following names under the same entry as the ``new-style'' macros.
+% \ifdefined\NameauthDoTestFiles \edef\NameauthTestFile{test13_03.tex}\else
+% \edef\NameauthTestFile{\jobname.tmp}\fi
%
-% \begin{center}\small
-% \begin{tabular}{rll}\toprule
-% First & \cmd{\deSmet} & \ForgetThis\deSmet\\
-% \rowcolor{grey}Next & \cmd{\deSmet} & \deSmet\\
-% Long & \cmd{\LdeSmet} & \LdeSmet\\
-% \rowcolor{grey}Short & \cmd{\SdeSmet} & \SdeSmet\\
-% & \cmd{\CapThis}\cmd{\deSmet} & \CapThis\deSmet\\
-% \rowcolor{grey} & \cmd{\ForceName}\cmd{\CapThis}\cmd{\deSmet} & \ForceName\CapThis\deSmet\\\bottomrule
-% \end{tabular}
-% \end{center}
+% \begin{VerbatimOut}{\NameauthTestFile}
+% \documentclass{article}
+% \input{compat.tex} % Included with nameauth; needed only if
+% % compiling on multiple TeX distros or LaTeX engines.
+% \usepackage{makeidx}
+% \usepackage[altformat]{nameauth}
+% \makeindex
+%
+% \newif\ifCaps % Replaces \if@nameauth@DoAlt
+% \newif\ifFirstCap % Replaces \if@nameauth@DoCaps
+% \newif\ifInHook % Replaces \if@nameauth@InHook
+% \Capstrue % Replaces \AltFormatActive
+%
+% % Alternate formatting macro definition
+% \renewcommand*\textSC[1]{\ifCaps\textsc{#1}\else#1\fi}
+%
+% % Redefinition of \AltCaps and \CapThis
+% \renewcommand*\AltCaps[1]{%
+% \ifInHook
+% \ifFirstCap\MakeUppercase{#1}\else#1\fi
+% \else
+% #1%
+% \fi
+% }
+% \renewcommand*\CapThis{\FirstCaptrue}
+%
+% \renewcommand*\NamesFormat[1]
+% {\InHooktrue#1\global\FirstCapfalse}
+%
+% \renewcommand*\MainNameHook[1]
+% {\Capsfalse\InHooktrue#1\global\FirstCapfalse}
+%
+% \let\FrontNamesFormat\Namesformat
+% \let\FrontNameHook\MainNameHook
+%
+% \begin{nameauth}
+% \< Luth & Martin & \noexpand\textSC{Luther} & >
+% \< Cath & Catherine \noexpand\AltCaps{d}e'
+% & \noexpand\textSC{Medici} & >
+% \end{nameauth}
+% \PretagName[Martin]{\noexpand\textSC{Luther}}{Luther, Martin}
+% \PretagName[Catherine \noexpand\AltCaps{d}e']
+% {\noexpand\textSC{Medici}}{Medici, Catherine de}
+%
+% \begin{document}
+%
+% \ForgetThis\Luth\ was a leading figure in the Protestant
+% Reformation. \Luth\ believed that one is declared
+% righteous in a forensic sense by divine grace through faith
+% created by the Holy Spirit via the Gospel and the Sacraments.
+%
+% \ForgetThis\Cath\ was not only Queen of France in her own right,
+% but she also guided the reigns of her three sons.
+% \CapThis\LCath[\noexpand\AltCaps{d}e']
+% was blamed for the St.\ Bartholomew's Day massacre that saw the
+% murder of thousands of Huguenots.
+%
+% \printindex
+% \end{document}
+% \end{VerbatimOut}
%
-% 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:
% \Capstrue
% \renewcommand*\textSC[1]{\ifCaps\textsc{#1}\else#1\fi}
+% \renewcommand*\AltCaps[1]{^^A
+% \ifInHook
+% \ifFirstCap\MakeUppercase{#1}\else#1\fi
+% \else
+% #1^^A
+% \fi
+% }
+% \renewcommand*\CapThis{\FirstCaptrue}
+% \renewcommand*\NamesFormat[1]
+% {\InHooktrue#1\global\FirstCapfalse}
% \renewcommand*\MainNameHook[1]
-% {\Capsfalse\InHooktrue\NameParser\global\FirstCapfalse}
+% {\Capsfalse\InHooktrue#1\global\FirstCapfalse}
+% \let\FrontNamesFormat\Namesformat
% \let\FrontNameHook\MainNameHook
+%
+% We can go one step further and use our own macros with names designed for the built-in macros, as the next example shows:
+%
% \begin{quote}\small
-% \StartNum
-% \begin{verbatim}
-%\newif\ifCaps
-%\Capstrue
-%\renewcommand*\textSC[1]{%
-% \ifCaps\textsc{#1}\else#1\fi
-%}
-%\renewcommand*\MainNameHook[1]
-%{%
-% \Capsfalse\InHooktrue\NameParser%
-% \global\FirstCapfalse%
-%}
-%\let\FrontNameHook\MainNameHook\end{verbatim}
-% \end{quote}
+% \VerbatimInput[gobble=0]{\NameauthTestFile}
%
-% 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
-% \rowcolor{grey}\ForgetThis\Adams & \Adams & \LAdams & \SAdams\\
-% \ForgetThis\SDJR & \SDJR & \LSDJR & \SSDJR\\
-% \rowcolor{grey}\ForgetThis\HAR & \HAR & \LHAR & \SHAR\\
-% \ForgetThis\Mencius & \Mencius & \LMencius & \SMencius\\\bottomrule
-% \end{tabular}
-% \end{center}
+% \ForgetThis\Luth\ was a leading figure in the Protestant
+% Reformation. \Luth\ believed that one is declared
+% righteous in a forensic sense by divine grace through faith
+% created by the Holy Spirit via the Gospel and the Sacraments.
%
-% \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 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}
+% \ForgetThis\Cath\ was not only Queen of France in her own right,
+% but she also guided the reigns of her three sons.
+% \CapThis\LCath[\noexpand\AltCaps{d}e']
+% was blamed for the St.\ Bartholomew's Day massacre that saw the
+% murder of thousands of Huguenots.
+% \end{quote}
%
-% We now close the scope of this current example and resume normal formatting.
% \endgroup^^A Local format hook redefinition
% \AltFormatInactive
%
-% \ReturnLink
-% \newpage
-%
-% \subsubsection{Customization}
-% \label{sec:Customize}
+% \subsection{Full Customization}
+% \label{sec:FullCustomize}
%
-% 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.
+% One can redesign or augment the core naming macros, 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@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@FullNametrue}, then calls \cmd{\NameauthLName}.
% \DescribeMacro{\NameauthFName}
-% \cmd{\FName}, or an S-shorthand, sets \cmd{\@nameauth@FirstNametrue}, then calls \cmd{\NameauthFName}. One should not modify \cmd{\Name} and \cmd{\FName} directly.
+% \cmd{\FName}, or an S-shorthand, sets \cmd{\@nameauth@FirstNametrue}, then calls \cmd{\NameauthFName}. One should not modify \cmd{\Name} and \cmd{\FName} directly. Since \textsf{nameauth} uses \textsf{xargs}, the next example uses it also.
%
-% Since \textsf{nameauth} depends on \textsf{xargs}, we use that in a minimal working example that implements the obsolete syntax (Section~\ref{sec:Obsolete}). 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. Note that the \texttt{quote} environment creates a local scope that we leverage below:
+% \ifdefined\NameauthDoTestFiles \edef\NameauthTestFile{test13_04.tex}\else
+% \edef\NameauthTestFile{\jobname.tmp}\fi
+%
+% \begin{VerbatimOut}{\NameauthTestFile}
+% \documentclass{article}
+% \input{compat.tex} % Included with nameauth; needed only if
+% % compiling on multiple TeX distros or LaTeX engines.
+% \usepackage{makeidx}
+% \usepackage[altformat]{nameauth}
+% \makeindex
+% \usepackage{xcolor}
%
-% \begin{quote}\small
-% \StartNum
-% \begin{verbatim}
-%\makeatletter
-%\newcommandx*\MyName[3][1=\@empty, 3=\@empty]{%
-% \protected@edef\a{\trim@spaces{#1}}%
-% \protected@edef\b{\trim@spaces{#2}}%
-% \protected@edef\c{\trim@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@FullNamefalse%
-% \global\@nameauth@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@edef\a{\trim@spaces{#1}}^^A
-% \protected@edef\b{\trim@spaces{#2}}^^A
-% \protected@edef\c{\trim@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@FullNamefalse^^A
-% \global\@nameauth@FirstNamefalse^^A
+%
+% % Change the general-case name macro to show
+% % a name in a framed, colored box.
+%
+% \newcommandx*\MyName[3][1=\@empty, 3=\@empty]{%
+% \global\@nameauth@toksa\expandafter{#1}%
+% \global\@nameauth@toksb\expandafter{#2}%
+% \global\@nameauth@toksc\expandafter{#3}%
+% \fcolorbox{black}{gray!25!white}{\@nameauth@Name[#1]{#2}[#3]}%
+% }
+%
+% % Likewise change the macro for when names are forced long.
+% \newcommandx*\MyLName[3][1=\@empty, 3=\@empty]{%
+% \global\@nameauth@toksa\expandafter{#1}%
+% \global\@nameauth@toksb\expandafter{#2}%
+% \global\@nameauth@toksc\expandafter{#3}%
+% \fcolorbox{black}{green!25!white}{\@nameauth@Name[#1]{#2}[#3]}%
+% }
+%
+% % Likewise change the macro when personal names are desired.
+% \newcommandx*\MyFName[3][1=\@empty, 3=\@empty]{%
+% \global\@nameauth@toksa\expandafter{#1}%
+% \global\@nameauth@toksb\expandafter{#2}%
+% \global\@nameauth@toksc\expandafter{#3}%
+% \fcolorbox{black}{yellow!25!white}{\@nameauth@Name[#1]{#2}[#3]}%
% }
% \makeatother
-% \let\MyLName\MyName
-% \let\MyFName\MyName
+%
+% % Change the formatting hooks, but do not use alternate.
+% % formatting, which is separate from that above.
+% \renewcommand*\NamesFormat[1]{\scshape#1}
+% \renewcommand*\MainNameHook[1]{#1}
+%
+% % Change the naming macro hooks.
% \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 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
+% \begin{document}
+%
+% \ForgetThis\Name[Adolf]{Harnack} was a theologian who stressed
+% the Fatherhood of God and the brotherhood of man.
+% \Name[Adolf]{Harnack} flourished in the early twentieth
+% century. We also produce \Name*[Adolf]{Harnack} and
+% \FName[Adolf]{Harnack}.
%
-% We continue to use features of \textsf{xargs}, as well as the local scope of a \texttt{quote} environment. Below we introduce formatting that is additional to, inter-operative with, yet distinct from the formatting hooks:
+% \printindex
+% \end{document}
+% \end{VerbatimOut}
%
% \begin{quote}\small
-% \StartNum
-% \begin{verbatim}
-%\makeatletter
-%\newcommandx*\MyName[3][1=\@empty, 3=\@empty]{%
-% \global\@nameauth@toksa\expandafter{#1}%
-% \global\@nameauth@toksb\expandafter{#2}%
-% \global\@nameauth@toksc\expandafter{#3}%
-% \hbox to 4em{Normal: \hfill}%
-% \fcolorbox{black}{gray!25!white}{\@nameauth@Name[#1]{#2}[#3]}%
-%}
-%\newcommandx*\MyLName[3][1=\@empty, 3=\@empty]{%
-% \global\@nameauth@toksa\expandafter{#1}%
-% \global\@nameauth@toksb\expandafter{#2}%
-% \global\@nameauth@toksc\expandafter{#3}%
-% \hbox to 4em{Long: \hfill}%
-% \fcolorbox{black}{green!25!white}{\@nameauth@Name[#1]{#2}[#3]}%
-%}
-%\newcommandx*\MyFName[3][1=\@empty, 3=\@empty]{%
-% \global\@nameauth@toksa\expandafter{#1}%
-% \global\@nameauth@toksb\expandafter{#2}%
-% \global\@nameauth@toksc\expandafter{#3}%
-% \hbox to 4em{Short: \hfill}%
-% \fcolorbox{black}{yellow!25!white}{\@nameauth@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}
+% \VerbatimInput[gobble=0]{\NameauthTestFile}
+%
% \makeatletter
% \newcommandx*\MyName[3][1=\@empty, 3=\@empty]{^^A
% \global\@nameauth@toksa\expandafter{#1}^^A
% \global\@nameauth@toksb\expandafter{#2}^^A
% \global\@nameauth@toksc\expandafter{#3}^^A
-% \hbox to 4em{Normal: \hfill}^^A
% \fcolorbox{black}{gray!25!white}{\@nameauth@Name[#1]{#2}[#3]}^^A
% }
+%
% \newcommandx*\MyLName[3][1=\@empty, 3=\@empty]{^^A
% \global\@nameauth@toksa\expandafter{#1}^^A
% \global\@nameauth@toksb\expandafter{#2}^^A
% \global\@nameauth@toksc\expandafter{#3}^^A
-% \hbox to 4em{Long: \hfill}^^A
% \fcolorbox{black}{green!25!white}{\@nameauth@Name[#1]{#2}[#3]}^^A
% }
+%
% \newcommandx*\MyFName[3][1=\@empty, 3=\@empty]{^^A
% \global\@nameauth@toksa\expandafter{#1}^^A
% \global\@nameauth@toksb\expandafter{#2}^^A
% \global\@nameauth@toksc\expandafter{#3}^^A
-% \hbox to 4em{Short: \hfill}^^A
% \fcolorbox{black}{yellow!25!white}{\@nameauth@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*\NamesFormat[1]{\scshape#1}
+% \renewcommand*\MainNameHook[1]{#1}
+% \renewcommand*\NameauthName{\MyName}
+% \renewcommand*\NameauthLName{\MyLName}
% \renewcommand*\NameauthFName{\MyFName}
%
-% \smallskip
-% \cmd{\ForgetName[Adolf]\{Harnack\}}\ForgetName[Adolf]{Harnack}\\[1ex]
-% \begin{tabular}{@{}rl}
-% \cmd{\Harnack} & \Harnack\\
-% \cmd{\LHarnack[Adolf von]} & \LHarnack[Adolf von]\\
-% \cmd{\Harnack} & \Harnack\\
-% \cmd{\SHarnack} & \SHarnack\\
-% \end{tabular}
-% \end{quote}\medskip
+% \ForgetThis\Name[Adolf]{Harnack} was a theologian who stressed
+% the Fatherhood of God and the brotherhood of man.
+% \Name[Adolf]{Harnack} flourished in the early twentieth
+% century. We also produce \Name*[Adolf]{Harnack} and
+% \FName[Adolf]{Harnack}.
+% \end{quote}
%
-% After\Version{3.3} the name is printed in the body text, the internal macros \emph{globally} set \cmd{\@nameauth@FullNamefalse} and \cmd{\@nameauth@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:GeneralIndex}.\medskip
+% After the name is printed in the body text, the internal macros \emph{globally} set \cmd{\@nameauth@FullNamefalse} and \cmd{\@nameauth@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.\medskip
%
% Like\Info{\cmd{\global}} many of the macros in this package, these macros can be redefined or used locally within a scope without making global changes to the document unless you specifically use \cmd{\global}.
% \endgroup^^A General format hook redefinition
+% \negmedskip
%
% \ReturnLink
+%
+% \begin{Quote}{\ForgetThis\Name{Confucius}, \textit{The Analects}, C II}
+% He who exercises government by means of his virtue may be compared to the north polar star, which keeps its place and all the stars turn towards it.
+% \end{Quote}
+%
% \newpage
%
-% \subsection{Technical Notes}
+% \section{Technical Notes and Tips}
% \label{sec:TechNotes}
%
-% \subsubsection{General}
-% \label{sec:GenNotes}
-%
-% About the package itself:
-% \begin{itemize}
-% \item Current features\Version{3.5} allow \textsf{nameauth} to meet its goals: stability, professional features, and backward-compatibility.
-% \begin{itemize}
-% \item Internal macros not in a local scope start with \cmd{\@nameauth@}. No more assumptions of ``throwaway'' macro names.
-% \item Index control has become stricter and more sensitive to the order of both name and xref creation.
-% \item It is now easy to have a separate index of persons when using packages and classes that enable that.
-% \item Internals of all macros that handle name arguments use a standard, optimized logic.
-% \end{itemize}
-% \item We keep \textsf{xargs} for backward compatibility. Future package versions will use \textsf{xparse} instead of \textsf{xargs} and shed all compatibility options. A ``maintenance'' version will be preserved for backward compatibility.
-% \item The package works with both \texttt{texindy} and \texttt{makeindex}.
-% \end{itemize}
+% \subsection{Tips: General}
%
-% \noindent About the manual (which is the test suite):
% \begin{itemize}
-% \item It has been reworked and expanded. Many months of testing has yielded better explanations that reflect best practices.
-% \item We now emphasize current workflows and de-emphasize older, less-relevant macros and the obsolete syntax.
-% \item It is compatible with both A4 and US letter formats.
-% \item We mention when this manual changes package internals, does actions that are not visually discernible, or deviates from ``normal'' usage.
+% \item A missing square bracket or curly brace can cause errors like
+% ``\texttt{Paragraph ended}'' and ``\texttt{Missing} \meta{grouping token}
+% \texttt{inserted.}''
+% \item Ensure that macros and conditionals used in name arguments are
+% defined in the preamble or outermost scope.
+% \item Because \cmd{\CapThis} segments a name argument, using it with
+% macros in name arguments can cause errors if not used with alternate
+% formatting (Section~\ref{sec:AltFormat}).
+% \item Something like |\edef\foo{\CapThis\Name{bar}}| will fail. Yet
+% one can use |\CapThis\Name{bar}| as an argument to |\edef\foo#1{#1}|.
+% \item In \texttt{dtx} files, put the \texttt{nameauth} environment and
+% tags in the \texttt{<driver>} section preamble. Do not, however put
+% any \cmd{\newif} statements there because they cannot be placed between
+% \texttt{\textbackslash iffalse} and \texttt{\textbackslash fi}. Save the
+% \cmd{\newif} statements for the ``commented'' part.
% \end{itemize}
%
-% \noindent About package building:
-% \begin{itemize}
-% \item Consult \texttt{README.md} for building instructions.
-% \item The \textsf{nameauth} package requires \textsf{etoolbox}, \textsf{suffix}, \textsf{trimspaces}, and \textsf{xargs}.
-% \item The package and manual build on current and older \LaTeX\ distributions.
-% \item The \texttt{dvi} test modes (\texttt{latex} and \texttt{dvilualatex}) use \texttt{dvipdf} to make \textit{TikZ} and \textsf{tcolorbox} render properly. The \texttt{pdf} test modes use \texttt{pdflatex}, \texttt{lualatex}, and \texttt{xelatex}. All modes use \texttt{makeindex}.
-% \item This release was tested ``officially'' on Linux (Manjaro; vanilla TL 2020 and 2017) and Windows 10 (Mik\TeX). The CTAN release is created with the latest vanilla TL release on Manjaro.
-% \end{itemize}\bigskip
-%
-% \begin{center}\bfseries This manual was created with
-% {\ttfamily\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}.\end{center}
-%
-% \ReturnLink
-% \newpage
-%
-% \subsubsection{Package Warnings}
-% \label{sec:Warnings}
-% \medskip
+% \subsection[Tips: Indexing]{Tips: Indexing and Sorting}
+% \label{sec:DebugSort}
%
-% \begin{center}\bfseries Standard and Verbose Warnings\end{center}
-% Package warnings\Info{Standard warnings} result if one redefines name shorthands in the \texttt{nameauth} environment. That could be a problem. Yet if one uses, for example, a new \texttt{nameauth} environment per chapter, such warnings might be harmless. For example:
-% \begin{quote}\small\StartNum
-% \begin{verbatim}
-%\PretagName[E.\,B.]{White}{White, Elwyn}
-%\begin{nameauth}
-% \< White & E.B. & White & > % v.1
-% \< White & E.\,B. & White & > % v.2
-%\end{nameauth}\end{verbatim}
-%\begin{nameauth}
-% \< White & E.B. & White & >
-% \< White & E.\,B. & White & >
-%\end{nameauth}
-% \cmd{\White} gives ``\White''. We lost the first version when we redefined it. We ``forget'' \White\ for later (Section~\ref{sec:NameControl}) with |\ForgetName[E.\,B.]{White}|.\ForgetName[E.\,B.]{White}\footnote{There should be two package warnings for redefining \cmd{\White}. We defined it in the \texttt{dtx} driver, then redefined it twice above.}
-% \end{quote}
+% The following warnings are always active. These warnings are issued when the following actions are attempted, but are \emph{not allowed} unless certain package options are used:
%
-% Additionally,\Version{3.5} the following situations cause package warnings, especially since the indexing macros have been made stricter:
% \begin{itemize}
-% \item \emph{Ignore \& reset:} \cmd{\IndexName} and \cmd{\IndexRef} warn if \cmd{\SkipIndex} is active, and they reset its flag unless the \texttt{oldreset} option is used.
-% \item \emph{Ignore \& reset:} \cmd{\IndexName} warns if it or a naming macro that contains it was preceded by \cmd{\SeeAlso}, whose Boolean flag is then reset.
-% \item \emph{Ignore:} \cmd{\IndexRef} warns if one tries to create a \textit{see} reference from an extant name and ignores the attempt unless the \texttt{oldsee} option is used.
-% \item \emph{Ignore:} \cmd{\PretagName} warns if the \texttt{nopretag} option is used and it produces no sort tags in that case.
-% \item \emph{Warn:} \cmd{\PName} and \cmd{\PName*} warn if \cmd{\@nameauth@SkipIndextrue} on exit (only if the \texttt{oldreset} option is used).
+% \item Use \cmd{\SeeAlso} before \cmd{\IndexName} or a naming macro.
+% \item Use \cmd{\PretagName} with the \texttt{nopretag} option.
+% \item Use \cmd{\IndexRef} with an extant name.
+% The \texttt{oldsee} option permits this.
+% \item Put \cmd{\SkipIndex} before \cmd{\IndexName} and \cmd{\IndexRef}.
+% The \texttt{oldsee} option permits this.
+% \item Prevent \cmd{\SkipIndex} from remaining active after being done
+% with \cmd{\PName} and \cmd{\PName*}. Only when the \texttt{oldreset}
+% option is used, do not reset \cmd{\SkipIndex} and warn if is effects
+% remain active.
% \end{itemize}
%
-% Package warnings\Info{Verbose warnings} result from the following \emph{only} when using the \texttt{verbose} option. The macros either allow or ignore certain actions:
+% Many warnings occur only when the \texttt{verbose} package option is used. These are less likely to indicate a serious problem, but might be helpful:
%
% \begin{itemize}
-% \item \emph{Allow:} \cmd{\ExcludeName} with an extant name.
-% \item \emph{Allow:} \cmd{\PretagName} to sort cross-references.
-% \item \emph{Allow:}\Version{3.5} \cmd{\IndexRef} with the \texttt{oldsee} option.
-% \item \emph{Ignore:} make an index page reference from an xref or excluded name.
-% \item \emph{Ignore:} make the same cross-reference multiple times.
-% \item \emph{Ignore:} use \cmd{\ExcludeName} with a cross-reference.
-% \item \emph{Ignore:} use \Version{3.3} \cmd{\IncludeName} with an xref (but \cmd{\IncludeName*} works.
-% \item \emph{Ignore:} use \cmd{\TagName} and \cmd{\UntagName} with a cross-reference.
+% \item When the following actions are attempted, they are \emph{not allowed}
+% unless certain package options are used:
+% \begin{itemize}
+% \item Use \cmd{\IndexName} or a naming macro with a cross-reference
+% or exclusion.
+% \item Use \cmd{\IndexRef} with a cross-reference or exclusion.
+% \item Use \cmd{\ExcludeName}, \cmd{\IncludeName}, \cmd{\TagName},
+% or \cmd{\UntagName} with a cross-reference.
+% \item Only if the \texttt{oldsee} option is used, instead of preventing
+% \cmd{\IndexRef} to create an xref on top of an extant name, just warn
+% if a name exists and creates a \textit{see} reference, which
+% prevents further page entries for that name.
% \end{itemize}
-% \ReturnLink
-% \newpage
-%
-% \subsubsection[Debugging/Errors]{Debugging and Avoiding Errors}
-% \label{sec:Errors}
-% \medskip
-%
-% \begin{center}\bfseries Debugging Macros\end{center}
-% \DescribeMacro{\ShowPattern}
-% We use \cmd{\ShowPattern} in Section~\ref{sec:NamePatterns} to illustrate name control patterns. It displays how\Version{3.3} the name arguments create name patterns that form name control sequences. One can debug pattern collisions and other issues with this macro:
-% \begin{quote}
-% \fbox{
-% \begin{tabular}{l}
-% {\Large\strut}\cmd{\ShowPattern}\oarg{FNN}\marg{SNN|,| Affix}\oarg{Alternate}\\
-% \end{tabular}%
-% }
-% \end{quote}
-%
-% Thus, |\texttt{\ShowPattern[Hernando]{de~Soto}}| will produce the output \JustIndex\Soto\texttt{\ShowPattern[Hernando]{de~Soto}}. As we have seen above, using \textsf{inputenc}/\textsf{fontenc} will cause names like |\texttt{\ShowPattern{Boëthius}}| to produce \texttt{\ShowPattern{Boëthius}}\JustIndex\Name{Bo\"ethius}.\medskip
-%
-% \DescribeMacro{\ShowIdxPageref}
-% \cmd{\ShowIdxPageref} displays a full index entry in the text.
-% Its counterpart is \cmd{\ShowIdxPageref*},
-% \DescribeMacro{\ShowIdxPageref*}
-% which shows a short index entry. Both only show names formatted as page references, even if they are cross-references\Version{3.3}:
-% \begin{quote}
-% \fbox{
-% \begin{tabular}{l}
-% {\Large\strut}\cmd{\ShowIdxPageref\ }\oarg{FNN}\marg{SNN|,| Affix}\oarg{Alternate}\vspace{-2pt}\\
-% {\Large\strut}\cmd{\ShowIdxPageref*}\oarg{FNN}\marg{SNN|,| Affix}\oarg{Alternate}\\
-% \end{tabular}
-% }
-% \end{quote}
-%
-% Index styles, \cmd{\PretagName}, and \cmd{\TagName} affect the output of \cmd{\ShowIdxPageref}. Active characters and macros appear as printed, not as in \texttt{idx} files. In a normal \LaTeX\ document without hyperlinks, for example, we would get:
-%
-% \begin{quote}\small
-% \StartNum
-% \begin{verbatim}
-%\PretagName[Hernando]{de~Soto}{Desoto, Hernando}
-%\texttt{\ShowIdxPageref[Hernando]{de~Soto}}\\\end{verbatim}
-%
-% \IndexActual{@}\UntagName[Hernando]{de~Soto}
-% \texttt{\ShowIdxPageref[Hernando]{de~Soto}}
-% \TagName[Hernando]{de~Soto}{\string|hyperpage}
-% \end{quote}
-%
-% Throughout this manual, \cmd{\ShowIdxPageref*} illustrates basic index entries that do not contain sorting information or tags. The simple index entry of \Name*[Hernando]{de~Soto} is |``\ShowIdxPageref*[Hernando]{de~Soto}''| ``\ShowIdxPageref*[Hernando]{de~Soto}''.
-%
-% \begin{center}\bfseries Avoiding Common Errors: General\end{center}
+% \item When the following actions are attempted, they are \emph{permitted.}
% \begin{itemize}
-% \item A missing square bracket or curly brace can cause errors like ``\texttt{Paragraph ended}'' and ``\texttt{Missing} \meta{grouping token} \texttt{inserted.}''
-% \item In the \texttt{nameauth} environment, \cmd{\<} \meta{arg1} \texttt{\&} \meta{arg2} \texttt{\&} \meta{arg3} \texttt{\&} \meta{arg4} \texttt{>}\\
-% is a macro that cannot miss a delimiter, an argument, or an ampersand.
-% \item Generally use \cmd{\noexpand} before macros in name arguments, which is required if the macros contain conditional statements.
-% \item Ensure that macros and conditionals used in name arguments are defined in the preamble or outermost scope (see below).
-% \item Do not format \meta{SNN},\meta{Affix} together as a pair. Format \meta{SNN} and \meta{Affix} separately (Section~\ref{sec:AltFormat}). The comma will segment the input into two arguments, which could cause errors.
-% \item Using \cmd{\CapThis} on a name with macros in its arguments while not using alternate formatting (Section~\ref{sec:AltFormat}) could trigger an error. Normally \cmd{\CapThis} also segments the input, which could cause errors.
-% \item Something like |\edef\foo{\CapThis\Name{bar}}| will fail. Yet one can use |\CapThis\Name{bar}| as an argument to a macro defined with either \cmd{\edef} or \cmd{\xdef}.
-% \item In \texttt{dtx} files, put the \texttt{nameauth} environment and tags in the \texttt{<driver>} section preamble that inputs the \texttt{dtx} file as documentation.
-% \item \cmd{\Name\ }\oarg{FNN}\marg{SNN}\texttt{[\cmd{\ignorespaces}]} prints only \meta{SNN}.\\
-% \cmd{\Name*}\oarg{FNN}\marg{SNN, Affix}\texttt{[\cmd{\ignorespaces}]} prints \meta{SNN} \meta{Affix}.\\
-% \cmd{\FName}\oarg{FNN}\marg{SNN}\texttt{[\cmd{\ignorespaces}]} either prints \meta{SNN}\\
-% \hbox{}\qquad or acts like the macro \cmd{\leavevmode}.\\
-% \cmd{\Name\ }\marg{SNN, Affix}\texttt{[\cmd{\ignorespaces}]} prints only \meta{SNN}^^A
-% \texttt{\textvisiblespace}.\\
-% \cmd{\FName}\marg{SNN, Affix}\texttt{[\cmd{\ignorespaces}]} either prints \meta{SNN}^^A
-% \texttt{\textvisiblespace}\\
-% \hbox{}\qquad or acts like the macros \cmd{\leavevmode}\cmd{\space}.
+% \item Use \cmd{\ExcludeName} with an extant name.
+% \item Use \cmd{\IncludeName*} with a cross-reference.
+% \item Use \cmd{\PretagName} to sort a cross-reference.
+% \end{itemize}
% \end{itemize}
%
-% \begin{center}\bfseries Avoiding Common Errors: Indexing\end{center}
% \begin{itemize}
-% \item Be sure to define all \textit{see} references with \cmd{\IndexRef} \emph{before} making any \cmd{\Name} references to them. Otherwise \cmd{\IndexRef} will generate a warning that it could not create a \textit{see} reference.
-% \item Be sure to define all \textit{see also} references with \cmd{\SeeAlso}\cmd{\IndexRef} \emph{after} making all needed \cmd{\Name} references to the respective names. Otherwise \cmd{\IndexName} and the naming macros will not create page references to the respective \cmd{\Name} thereafter.
-% \item Two names may look identical on the page, but their internal name patterns can differ (Sections~\ref{sec:IndexSort} and~\ref{sec:NamePatterns}). This will create spurious index entries. Check the \texttt{idx} file and possibly use (below).
+% \item Two names may look alike on the page, but their name patterns can
+% differ, creating spurious index entries. Check the \texttt{idx} file
+% to be sure.
% \item To fix spurious entries, compare index entries with names in the text.
% \begin{itemize}
% \item Check if naming macros always use the same arguments.
% \item Check sorting tags (\cmd{\PretagName} (Section~\ref{sec:IndexSort}).
% \item Check use of active Unicode characters (Section~\ref{sec:Unicode}).
-% \item Use \cmd{\ShowPattern} and \cmd{\ShowIdxPageref} (below).
-% \item Check if macros in name arguments did not follow \cmd{\noexpand}.
+% \item Use \cmd{\ShowPattern}, \cmd{\ShowIdxPageref}, and
+% \cmd{\ShowNameState}.
+% \item Did \cmd{\noexpand} precede macros in name arguments?
+% \end{itemize}
+% \item Check \textsf{nameauth} package warnings. Set the \texttt{verbose}
+% option, which will offer a number of ``informational'' warnings that
+% could be of assistance.
+% \item If an entry is sorted incorrectly in the index, check the following:
+% \begin{itemize}
+% \item Are there any ac tive characters, 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}
-% \item Check \textsf{nameauth} package warnings. Set the \texttt{verbose} option, which will offer a number of ``informational'' warnings that could be of assistance with the index.
% \end{itemize}
%
-% \begin{center}\bfseries Macros in Name Arguments\end{center}
+% Extra spaces are significant when sorting index entries, yet usually are not significant in the body text. Macros that use \cmd{\protected@edef} can add spaces to index entries. Because \textsf{nameauth} must work with classes that write index entries to \texttt{aux} files, its macros must use \cmd{\protected@edef}. The only way to verify this is to inspect the \texttt{idx} file. We show this below:
+%
+% \begin{quote}\small
+% \begin{Verbatim}
+% \makeatletter
+% \newcommand\Idx[1]{\protected@edef\arg{#1}\index{\arg}}
+% \makeatother
+% \end{Verbatim}
+%
+% \cmd{\Idx\{}\cmd{\textsc\{football\}\}} produces:\\
+% \hbox{}\qquad\cmd{\indexentry}\texttt
+% {\{\cmd{\textsc\textvisiblespace\textvisiblespace}\{football\}\}\{}\meta
+% {page}\texttt{\}}\\[1ex]
+% The macro \cmd{\index\{}\cmd{\textsc\{football\}\}} produces:\\
+% \hbox{}\qquad\cmd{\indexentry}\texttt
+% {\{\cmd{\textsc}\{football\}\}\{}\meta{page}\texttt{\}}
+% \end{quote}
+%
+% \subsection[Tips: Name Args]{Tips: Macros in Name Arguments}
+%
% \begin{itemize}
-% \item Use alternate formatting to avoid potential problems, especially when using \cmd{\CapThis} (Sections~\ref{sec:AltFormat}, \ref{sec:Hooksiii}).
-% \item Use \cmd{\noexpand}\meta{macro} in name macro arguments as a best practice. This is required for all such macros that contain conditional statements.
-% \item Macros used in name arguments must be defined either in the preamble or in the outermost document environment scope to avoid \texttt{Undefined control sequence} errors.
-% \item Boolean flags (\texttt{\textbackslash if}\meta{flag}) used in formatting hooks must be defined either in the preamble or in the outermost document scope.
-% \item The \cmd{\global} modifier does not work with \cmd{\newif} and \cmd{\newcommand}.\footnote{See \href{https://tex.stackexchange.com/questions/51733/global-renewcommand-equivalent-of-global-def}{this page} on redefining \cmd{\newcommand}, with the caveats that apply.}
-% Yet \cmd{\global} can precede a macro defined with \cmd{\newcommand}, and the first \cmd{\def} used therein may be global.
+% \item Use alternate formatting to avoid potential problems, especially
+% when using \cmd{\CapThis} (Sections~\ref{sec:AltFormat},
+% \ref{sec:AdvCustomize}).
+% \item |\SkipIndex\Name{\noexpand\empty}| will not trigger a package error,
+% while |\SkipIndex\Name{\empty}| will trigger an error.
+% \item Use \cmd{\noexpand}\meta{macro} in name macro arguments as
+% a best practice.
+% \item Macros used in name arguments must be defined either in the
+% preamble or in the outermost document scope to avoid errors.
+% \item Boolean flags (\texttt{\textbackslash if}\meta{flag}) used in
+% formatting hooks must be defined either in the preamble or in the
+% outermost document scope.
+% \item The \cmd{\global} modifier does not work with \cmd{\newif} and
+% \cmd{\newcommand}. Yet \cmd{\global} can precede the use of a macro
+% defined with \cmd{\newcommand}.
+% \textit{The \TeX book}, pages 275--277, shows what \cmd{\global} can
+% and cannot do. See more about this issue and \cmd{\newcommand} on
+% \href{https://tex.stackexchange.com/questions/51733/global-renewcommand-equivalent-of-global-def}
+% {\bfseries this page}.
% \end{itemize}
%
-% \textit{The \TeX book}, pages 275--277, shows what \cmd{\global} can and cannot do. In the following example, we declare a Boolean flag and a macro in the outer scope, then make several declarations and assignments in the inner scope. After the inner scope ends, we test to see what has happened:
+% Below we demonstrate how scoping rules work:
%
+% \begin{VerbatimOut}{\jobname.tmp}
% \newif\ifCondA
% \newcommand\MacroA{}
-% \begingroup^^A Demo local scope
+% \begingroup
% \newif\ifCondB
% \global\newif\ifCondC
% \global\newcommand\MacroB{}
% \newcommand\MacroC{\def\MacroD{}}
% \global\MacroC
% \global\CondAtrue
-% \endgroup^^A Demo local scope
+% \endgroup
+% \end{VerbatimOut}
+%
% \begin{quote}\small
-% \StartNum
-% \begin{verbatim}
-%\newif\ifCondA
-%\newcommand\MacroA{}
-%\begingroup
-% \newif\ifCondB
-% \global\newif\ifCondC
-% \global\newcommand\MacroB{}
-% \newcommand\MacroC{\def\MacroD{}}
-% \global\MacroC
-% \global\CondAtrue
-%\endgroup\end{verbatim}
+% \VerbatimInput[gobble=0]{\jobname.tmp}
% \end{quote}
+% \input{\jobname.tmp}
%
-%\begin{itemize}
-% \item \ifdefined\CondAtrue \texttt{\textbackslash ifCondA} is defined \else \texttt{\textbackslash ifCondA} is not defined \fi in the outer scope (outer definition).
-% \item \ifdefined\MacroA \cmd{\MacroA} is \else \cmd{\MacroA} is not \fi defined in the outer scope (outer definition).
-% \item \ifdefined\CondBtrue \texttt{\textbackslash ifCondB} is defined \else \texttt{\textbackslash ifCondB} is not defined \fi in the outer scope (local definition).
-% \item \ifdefined\CondCtrue \texttt{\textbackslash ifCondC} is defined \else \texttt{\textbackslash ifCondC} is not defined \fi in the outer scope (no \cmd{\global}\cmd{\newif}).
-% \item \ifdefined\MacroB \cmd{\MacroB} is defined \else
-% \cmd{\MacroB} is not defined \fi in the outer scope (no \cmd{\global}\cmd{\newcommand}).
-% \item \cmd{\MacroC} \ifdefined\MacroC is defined \else is not defined \fi in the outer scope (local definition).
-% \item \cmd{\MacroD} \ifdefined\MacroD is defined \else is not defined \fi in the outer scope (\cmd{\global} affects \cmd{\def} in \cmd{\MacroC}).
-% \item \ifCondA \texttt{\textbackslash ifCondA} is true \else \texttt{\textbackslash ifCondA} is false \fi (\cmd{\global} assignment works, not instantiation).
+% \begin{itemize}
+% \item \ifdefined\CondAtrue \texttt{\textbackslash ifCondA} is defined
+% \else \texttt{\textbackslash ifCondA} is not defined \fi
+% in the outer scope (outer definition).
+% \item \ifdefined\MacroA \cmd{\MacroA} is defined
+% \else \cmd{\MacroA} is not defined \fi
+% in the outer scope (outer definition).
+% \item \ifdefined\CondBtrue \texttt{\textbackslash ifCondB} is defined
+% \else \texttt{\textbackslash ifCondB} is not defined \fi
+% in the outer scope (local definition).
+% \item \ifdefined\CondCtrue \texttt{\textbackslash ifCondC} is defined
+% \else \texttt{\textbackslash ifCondC} is not defined \fi
+% in the outer scope (no \cmd{\global}\cmd{\newif}).
+% \item \ifdefined\MacroB \cmd{\MacroB} is defined
+% \else \cmd{\MacroB} is not defined \fi
+% in the outer scope (no \cmd{\global}\cmd{\newcommand}).
+% \item \cmd{\MacroC} \ifdefined\MacroC is defined
+% \else is not defined \fi
+% in the outer scope (local definition).
+% \item \cmd{\MacroD} \ifdefined\MacroD is defined
+% \else is not defined \fi
+% in the outer scope (\cmd{\global} affects \cmd{\def} in \cmd{\MacroC}).
+% \item \ifCondA \texttt{\textbackslash ifCondA} is true
+% \else \texttt{\textbackslash ifCondA} is false \fi
+% (\cmd{\global} assignment works, not instantiation).
% \end{itemize}
%
% Any macro that is used in the argument of a naming macro must be defined in all scopes in which that name is used. Below we deactivate indexing and show this:
+%
% \begin{quote}\small
% \IndexInactive
-% \StartNum
-% \begin{verbatim}
-%\begin{nameauth}
-% \< Testi & & \noexpand\TESTi & >
-% \< Testii & & \noexpand\TESTii & >
-%\end{nameauth}
-%\def\TESTi{Test One}
-%\indent \hbox to 10em{(Outer 1) \Testi\hfill}
-%\bgroup
-% (Inner 1) \Testi\\
-% \def\TESTii{Test Two}
-% \hbox to 10em{(Inner 2) \Testii\hfill}
-%\egroup
-%(Outer 2) \unless\ifdefined\TESTii \cmd{\TESTii} undefined\fi\end{verbatim}
-%
-%\begin{nameauth}
-% \< Testi & & \noexpand\TESTi & >
-% \< Testii & & \noexpand\TESTii & >
-%\end{nameauth}
-%\def\TESTi{Test One}
-%\indent \hbox to 10em{(Outer 1) \Testi\hfill}
-%\bgroup
-% (Inner 1) \Testi\\
-% \def\TESTii{Test Two}
-% \hbox to 10em{(Inner 2) \Testii\hfill}
-%\egroup
-%(Outer 2) \unless\ifdefined\TESTii \cmd{\TESTii} undefined\fi
+% \begin{Verbatim}
+% \begin{nameauth}
+% \< Testi & & \noexpand\TESTi & >
+% \< Testii & & \noexpand\TESTii & >
+% \end{nameauth}
+% \def\TESTi{Test One}
+% \indent \hbox to 10em{(Outer 1) \Testi\hfill}
+% \begingroup
+% (Inner 1) \Testi\\
+% \def\TESTii{Test Two}
+% \hbox to 10em{(Inner 2) \Testii\hfill}
+% \ndegroup
+% (Outer 2) \unless\ifdefined\TESTii \cmd{\TESTii} undefined\fi
+% \end{Verbatim}
+%
+% \begin{nameauth}
+% \< Testi & & \noexpand\TESTi & >
+% \< Testii & & \noexpand\TESTii & >
+% \end{nameauth}
+% \def\TESTi{Test One}
+% \indent \hbox to 10em{(Outer 1) \Testi\hfill}
+% \begingroup
+% (Inner 1) \Testi\\
+% \def\TESTii{Test Two}
+% \hbox to 10em{(Inner 2) \Testii\hfill}
+% \endgroup
+% (Outer 2) \unless\ifdefined\TESTii \cmd{\TESTii} undefined\fi
% \end{quote}
-
-% \ReturnLink
-% \newpage
%
-% \subsubsection{Obsolete Syntax}
-% \label{sec:Obsolete}
-%
-% This non-Western syntax limits alternate names and xrefs, excludes comma-delimited names, and complicates indexing. It is a ghost of \textsf{nameauth} past.
-% \begin{quote}
-% \fbox{
-% \begin{tabular}{ll}
-% {\Large\strut}\cmd{\Name}\marg{SNN}\oarg{Alternate} & \color{nared}\texttt{\%} \textit{obsolete syntax}\\
-% \end{tabular}
-% }
-% \end{quote}
+% \newpage
%
-% \begin{itemize}
-% \item One must \emph{leave empty} the first optional \meta{FNN} argument.
-% \item One must \emph{never} use the comma-delimited argument \meta{SNN, Affix}.
-% \item Instead, these names \emph{always} use the final optional \meta{Alternate} argument, which acts like \meta{Affix} and affects both name and index patterns (Section~\ref{sec:NamePatterns}).
-% \item These names take the form \meta{SNN Alternate} in the index.
-% \end{itemize}
-% In this manual we designate these names with a double dagger (\ddag):
-%
-% \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}|%| \textit{Ancient}}\\
-% | \< Yosh & & Yoshida & Shigeru > | {\color{nared}|%| \textit{Eastern}}\\
-% | \< OFukuyama & & |\\
-% | \textUC{Fukuyama} & Takeshi > | {\color{nared}|%| \textit{Alt. format}}\\
-% |\end{nameauth}|
-% \end{quote}
+% \subsection[Active Unicode]{Active Unicode Characters}
+% \label{sec:Unicode}
%
-% \begin{center}\small\PatInfo{\ShowPattern{Henry}[VIII]!MN\break \ShowPattern{Chiang}[Kai-shek]!MN\break \ShowPattern{Dagobert}[I]!MN\break \ShowPattern{Yoshida}[Shigeru]!MN}\MyStretch
-% \begin{tabular}{ll}\toprule
-% |\ForgetThis\Name{Henry}[VIII]| & \ForgetThis\Name{Henry}[VIII]\ddag\\
-% |\Name{Henry}[VIII]| & \Name{Henry}[VIII]\ddag\\
-% \rowcolor{grey}^^A
-% |\ForgetThis\Name{Chiang}[Kai-shek]| & \ForgetThis\Name{Chiang}[Kai-shek]\ddag\\
-% \rowcolor{grey}^^A
-% |\Name{Chiang}[Kai-shek]| & \Name{Chiang}[Kai-shek]\ddag\\
-% |\Dagb| & \Dagb\ddag\\
-% |\Dagb| & \Dagb\ddag\\
-% \rowcolor{grey}|\CapName\Yosh| & \CapName\Yosh\ddag\\
-% \rowcolor{grey}|\CapName\RevName\LYosh| & \CapName\RevName\LYosh\ddag\\
-% |\AltFormatActive| \AltFormatActive\\
-% |\ForgetThis\OFukuyama| & \ForgetThis\OFukuyama\ddag\\
-% |\OFukuyama| & \OFukuyama\ddag\\
-% |\AltFormatInactive| \AltFormatInactive\\\bottomrule
-% \end{tabular}
-% \end{center}
+% \subsubsection{General Information}
%
-% Regardless of its flaws,\Version{2.6} the obsolete syntax shares name patterns, index tags, text tags, and index entries with the current syntax:
-% \begin{quote}\small\MyStretch
-% \begin{tabular}{@{}lll}
-% Obsolete syntax: & \cmd{\ForgetThis}\cmd{\Name\{Henry\}[VIII]} & \ForgetThis\Name{Henry}[VIII]\ddag\\
-% Current syntax: & \cmd{\Name\{Henry, VIII\}} & \Name{Henry, VIII}\\
-% \end{tabular}
-% \end{quote}
+% With |\usepackage[T1]{fontenc}|, \texttt{latex} and \texttt{pdflatex} can use many active Unicode characters automatically. Use \cmd{\PretagName} to sort names with these characters (Section~\ref{sec:IndexSort}). More Unicode characters can be made available when using fonts with TS1 glyphs (pages 455--463 in \textit{The Latex Companion}). Compare \href{https://tug.ctan.org/info/symbols/comprehensive/}{\bfseries this page} or type either \texttt{texdoc comprehensive}, \texttt{texdoc symbols-A4}, or \texttt{texdoc symbols-letter}.
%
-% \ReturnLink
-% \bigskip
+% Active Unicode characters work much like macros. When using a font with TS1 glyphs and slots, the following preamble snippet is an example of how one might add more Unicode characters, such as a long s (\textit{s-medialis}):
%
-% \subsubsection[Name Patterns]{Name Pattern Overview}
-% \label{sec:NamePatterns}
+% \begin{quote}\small
+% \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}
+%
+% In Congreſs, July 4, 1776
+% \end{Verbatim}
+%
+% In Congreſs, July 4, 1776
+% \end{quote}
+%
+% Many Unicode characters have native support in \texttt{xelatex} and
+% \texttt{lualatex}, but not in \texttt{pdflatex}. Yet the latter has
+% features (e.g., in \textsf{microtype}) that others lack. The features of
+% \texttt{makeindex} do not always equate to those in \texttt{xindy}.
+% Those differences impact design choices.
+% Below we group characters by accents and diacritical marks:
%
-% 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:\medskip
-% \begin{center}\MyStretch
+% \begin{center}\large\bigstretch
+% \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
-% Macro Arguments & Patterns & Type\\\midrule
-% \rowcolor{grey}\oarg{FNN}\marg{SNN} & \meta{FNN}!\meta{SNN} & \normalfont Western\\
-% \oarg{FNN}\marg{SNN, Affix} & \meta{FNN}!\meta{SNN},\meta{Affix} & \normalfont Western\\
-% \rowcolor{grey}\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{grey}\hphantom{\oarg{FNN}}\marg{SNN} & \meta{SNN} & \normalfont non-Western\\\bottomrule
-% \end{tabular}
-% \end{center}\medskip
-%
-% The internal parser \cmd{\@nameauth@Parse} determines the type of name through the presence or absence of certain arguments. Then it assigns name control sequences keyed to the type of name pattern and the current naming system. Other macros do similar tasks with name control sequences associated with other data sets.
-%
-% First we show name patterns generated from name elements and the type of name. ``Non-native'' Eastern names are marked by a dagger (\dag); names that use the obsolete syntax are marked by a double dagger (\ddag).\medskip
-% \begin{center}\footnotesize\MyStretch
-% \begin{tabular}{rll}\toprule
-% Macro & Body Text & \cmd{\ShowPattern}\\\midrule
-% \rowcolor{grey}\cmd{\ForgetThis}\cmd{\Harnack[Adolf von]} & \ForgetThis\Harnack[Adolf von] & \texttt{\ShowPattern[Adolf]{Harnack}}\\
-% \rowcolor{grey}\cmd{\LHarnack} & \LHarnack & \texttt{\ShowPattern[Adolf]{Harnack}}\\
-% \cmd{\ForgetThis}\cmd{\Pat} & \ForgetThis\Pat & \texttt{\ShowPattern[George S.]{Patton, Jr.}}\\
-% \cmd{\DropAffix}\cmd{\LPat} & \DropAffix\LPat & \texttt{\ShowPattern[George S.]{Patton, Jr.}}\\
-% \rowcolor{grey}\cmd{\ForgetThis}\cmd{\Noguchi} & \ForgetThis\Noguchi & \texttt{\ShowPattern[Hideyo]{Noguchi}}\\
-% \rowcolor{grey}\cmd{\RevName}\cmd{\LNoguchi} & \RevName\LNoguchi\dag & \texttt{\ShowPattern[Hideyo]{Noguchi}}\\
-% \cmd{\ForgetThis}\cmd{\Yamt} & \ForgetThis\Yamt & \texttt{\ShowPattern{Yamamoto,Isoroku}}\\
-% \cmd{\RevName}\cmd{\LYamt} & \RevName\LYamt & \texttt{\ShowPattern{Yamamoto,Isoroku}}\\
-% \rowcolor{grey}\cmd{\ForgetThis}\cmd{\Name\{Henry,VIII\}} & \ForgetThis\Name{Henry,VIII} & \texttt{\ShowPattern{Henry,VIII}}\\
-% \rowcolor{grey}\cmd{\Name*\{Henry\}[VIII]} & \Name*{Henry}[VIII]\ddag & \texttt{\ShowPattern{Henry,VIII}}\\
-% \cmd{\ForgetThis}\cmd{\Dem[I Soter]} & \ForgetThis\Dem[I Soter] & \texttt{\ShowPattern{Demetrius,I}}\\
-% \cmd{\LDem} & \LDem & \texttt{\ShowPattern{Demetrius,I}}\\
-% \rowcolor{grey}\cmd{\ForgetThis}\cmd{\Aris} & \ForgetThis\Aris & \texttt{\ShowPattern{Aristotle}}\\
-% \rowcolor{grey}\cmd{\Aris} & \Aris & \texttt{\ShowPattern{Aristotle}}\\\bottomrule
-% \end{tabular}
-% \ForgetName{Demetrius, I}\ForgetName[Adolf]{Harnack}
-% \end{center}\medskip
-%
-% \noindent Six suffixes are appended to these patterns to create independent data sets:\medskip
-% \begin{center}\small\MyStretch
-% \begin{tabular}{llll}\toprule
-% Description & Pattern & Mnemonic & Example\\\midrule
-% \rowcolor{grey}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{grey}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{grey}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
+% acute & Á Ć É Ǵ \Bullet{H} Í Ĺ &
+% á ć é ǵ \bullet{h} í ĺ \strut\\
+% & Ń Ó Ŕ Ś Ú Ý Ź &
+% ń ó ŕ ś ú ý ź \strut\\
+% \rowcolor{nagrey}grave & À \Bullet{C} È \Bullet{G} \Bullet{H} Ì Ò Ù &
+% à \bullet{c} è \bullet{g} \bullet{h} ì ò ù \strut\\
+% circumflex & Â Ĉ Ê Ĝ Ĥ Î Ĵ Ô Ŝ Û Ŵ Ŷ &
+% â ĉ ê ĝ ĥ î ĵ ô ŝ û ŵ ŷ \strut\\
+% \rowcolor{nagrey}tilde &
+% Ã \Bullet{C} \Bullet{E} \Bullet{G} \Bullet{H} Ĩ Ñ Õ Ũ &
+% ã \bullet{c} \bullet{e} \bullet{g} \Bullet{h} ĩ ñ õ ũ \strut\\
+% diaeresis\footnotemark & Ä \Bullet{C} Ë \Bullet{G} \Bullet{H} Ï Ö Ü Ÿ &
+% ä \bullet{c} ë \bullet{g} \bullet{h} ï ö ü ÿ \strut\\
+% \rowcolor{nagrey}cedilla & \Bullet{A} Ç \Bullet{E} Ģ Ķ Ļ Ņ Ŗ Ş Ţ &
+% \bullet{a} ç \bullet{e} ģ ķ ļ ņ ŗ ş ţ \strut\\
+% macron & Ā \Bullet{C} Ē Ḡ \Bullet{H} Ī Ō Ū Ǣ Ȳ &
+% ā \bullet{c} ē ḡ \bullet{h} ī ō ū ǣ ȳ \strut\\
+% \rowcolor{nagrey}breve & Ă \Bullet{C} \Bullet{E} Ğ \Bullet{H} Ĭ Ŏ Ŭ &
+% ă \bullet{c} \bullet{e} ğ \bullet {h} ĭ ŏ ŭ \strut\\
+% dot/dotless & Ḃ Ċ Ė Ġ \Bullet{H} İ Ż & ḃ ċ ė ġ \bullet{h} ı ż \strut\\
+% \rowcolor{nagrey}ogonek & Ą \Bullet{C} Ę \Bullet{G} \Bullet{H} Į Ǫ Ų &
+% ą \bullet{c} ę \bullet{g} \bullet{h} į ǫ ų \strut\\
+% caron & Ǎ Č Ď Ě Ǧ Ǐ Ǩ Ľ & ǎ č ď ě ǧ ǐ ǰ ǩ ľ \strut\\
+% & Ň Ǒ Ř Š Ť Ǔ Ž & ň ǒ ř š ť ǔ ž \strut\\
+% \rowcolor{nagrey}various & Å Æ Ð (eth) Đ (stroke) IJ\ Ł &
+% å æ ð đ ij\ ł \strut\\
+% \rowcolor{nagrey} & Ŋ Ø Œ Ő Ů Ű Ș Ț Þ &
+% ŋ ø œ ő ů ű ș ß ț þ \strut\\\bottomrule
% \end{tabular}
+% \footnotetext{A diaeresis mark is one way to indicate a sound change
+% (\textit{Umlaut}). German originally used a superscript \textsf{e} over
+% \textsf{a}, \textsf{o}, and \textsf{u}. The cursive form of \textsf{e}
+% simplified to a diaeresis in the 1800s. A diaeresis also signals
+% pronouncing a diphthong or digraph as two monophthongs, e.g., ``noëtic''.}
% \end{center}
-% \newpage
%
-% \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}\leavevmode
+% \newpage
%
-% \ReturnLink
+% \subsubsection[Compatibility]{Compatibility: Old and New}
%
-% \subsubsection[Active Unicode]{Active Unicode Characters}
-% \label{sec:Unicode}
+% Since 2018, changes in the way that \texttt{pdflatex} and \texttt{latex} handle Unicode characters have made indexing simpler and more intuitive, e.g.
%
-% \leavevmode\begin{center}\bfseries General Information\end{center}
-% Below we group characters by accents and diacritical marks:
-% \begin{center}\large\setstretch{1.3}
-% \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\\
-% & Ń Ó Ŕ Ś Ú Ý Ź & ń ó ŕ ś ú ý ź \strut\\
-% \rowcolor{grey}grave & À \Bullet{C} È \Bullet{G} \Bullet{H} Ì Ò Ù & à \bullet{c} è \bullet{g} \bullet{h} ì ò ù \strut\\
-% circumflex & Â Ĉ Ê Ĝ Ĥ Î Ĵ Ô Ŝ Û Ŵ Ŷ & â ĉ ê ĝ ĥ î ĵ ô ŝ û ŵ ŷ \strut\\
-% \rowcolor{grey}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{grey}cedilla & \Bullet{A} Ç \Bullet{E} Ģ Ķ Ļ Ņ Ŗ Ş Ţ & \bullet{a} ç \bullet{e} ģ ķ ļ ņ ŗ ş ţ \strut\\
-% macron & Ā \Bullet{C} Ē Ḡ \Bullet{H} Ī Ō Ū Ǣ Ȳ & ā \bullet{c} ē ḡ \bullet{h} ī ō ū ǣ ȳ \strut\\
-% \rowcolor{grey}breve & Ă \Bullet{C} \Bullet{E} Ğ \Bullet{H} Ĭ Ŏ Ŭ & ă \bullet{c} \bullet{e} ğ \bullet {h} ĭ ŏ ŭ \strut\\
-% dot/dotless & Ḃ Ċ Ė Ġ \Bullet{H} İ Ż & ḃ ċ ė ġ \bullet{h} ı ż \strut\\
-% \rowcolor{grey}ogonek & Ą \Bullet{C} Ę \Bullet{G} \Bullet{H} Į Ǫ Ų & ą \bullet{c} ę \bullet{g} \bullet{h} į ǫ ų \strut\\
-% caron & Ǎ Č Ď Ě Ǧ Ǐ Ǩ Ľ & ǎ č ď ě ǧ ǐ ǰ ǩ ľ \strut\\
-% & Ň Ǒ Ř Š Ť Ǔ Ž & ň ǒ ř š ť ǔ ž \strut\\
-% \rowcolor{grey}various & Å Æ Ð (eth) Đ (stroke) IJ\ Ł & å æ ð đ ij\ ł \strut\\
-% \rowcolor{grey} & Ŋ Ø Œ Ő Ů Ű Ș Ț Þ & ŋ ø œ ő ů ű ș ß ț þ \strut\\\bottomrule
+% \begin{center}\small\medstretch
+% \begin{tabular}{rllrll}\toprule
+% pre-2018 text & & index & post-2018 text & & index\\
+% \rowcolor{nagrey} ä & \textrightarrow &
+% \texttt{\cmd{\IeC\textvisiblespace}\{\cmd{\"a}\}} &
+% ä & \textrightarrow & \texttt{ä}\\
+% æ & \textrightarrow &
+% \texttt{\cmd{\IeC\textvisiblespace}\{\cmd{\ae\textvisiblespace}\}} &
+% æ & \textrightarrow & \texttt{æ}\\\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}
-% \newpage
%
-% With |\usepackage[T1]{fontenc}|, \texttt{latex} and \texttt{pdflatex} can use many active Unicode characters automatically. Use \cmd{\PretagName} to sort names with these characters (Section~\ref{sec:IndexSort}). Currently, most documents typeset with \texttt{latex} and \texttt{pdflatex} do not require explicit loading of either \textsf{inputenc} or \textsf{inputenx}.
+% The \cmd{\IeC} macro plus its argument then would expand to \cmd{\T1} plus its argument, which would occur especially if accented characters were written out to a file, then read in again. This could cause a number of problems.
%
-% Additional Unicode characters can be made available when using fonts with TS1 glyphs (pages 455--463 in \textit{The Latex Companion}). Compare the list on \href{http://tug.ctan.org/info/symbols/comprehensive/}{this page} or type \texttt{texdoc comprehensive} in a terminal window.
-%
-% Active Unicode characters work much like macros. When using a font with TS1 glyphs and slots, the following preamble snippet is an example of how one might add more Unicode characters, such as a long s (\textit{s-medialis}):
+% One can test for this change and take different approaches as needed. In making such choices, one may need to consult the entries in the \texttt{idx} and \texttt{ind} files to see how the name arguments are being indexed. The basic test is:
%
% \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}
-%
-%In Congreſs, July 4, 1776\end{verbatim}
-%
-%In Congreſs, July 4, 1776
+% \cmd{\IfFileExists\{utf8-2018.def\}}\marg{new}\marg{old}
% \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.
+% Now we apply the test to an example. Before 2018, some index styles like \texttt{gind.ist} could not work with characters that contained macrons:
%
-% \begin{center}\bfseries Compatibility: Old and New\end{center}
-% As mentioned\Warn{} in Section~\ref{sec:IndexSort}, before 2018, some index styles could not work with characters that contained macrons:
% \begin{center}\large
% \begin{tabular}{ll}
% Ā Ē Ḡ Ī Ō Ū Ǣ Ȳ & ā ē ḡ ī ō ū ǣ ȳ\\
% \end{tabular}
% \end{center}
-% Since 2018, those restrictions have been removed due to better handling of Unicode characters in \texttt{latex} and \texttt{pdflatex}.
%
-% If compiled on a recent version of \LaTeX, one will see a macron in the name below. To allow the manual to compile on older versions, the following code prints a version without the macron as needed:
+% Since 2018, those restrictions have been removed. In order to create a document that can work with old or new versions of \LaTeX, one can conditionally use macrons or not. In a recent version of \LaTeX, one will see a macron in the name
+% \ifPDFTeX^^A
+% \IfFileExists{utf8-2018.def}^^A
+% {\Name{Ghazāli}}{\Name{Ghazali}}^^A
+% \else\Name{Ghazāli}^^A
+% \fi.
+% Otherwise, no macron will be present. We avoid errors that could arise with control sequences like \cmd{\=a} in the index when using \texttt{makeindex} and \texttt{gind.ist} by using the following snippet:
+%
% \begin{quote}\small
-% \StartNum
-% \begin{verbatim}
-%\ifPDFTeX
-% \IfFileExists{utf8-2018.def}%
-% {\Name{Ghazāli}}{\Name{Ghazali}}%
-% \else\Name{Ghazāli}%
-%\fi\end{verbatim}
-%
-%\ifPDFTeX^^A
-% \IfFileExists{utf8-2018.def}^^A
-% {\Name{Ghazāli}}{\Name{Ghazali}}^^A
-% \else\Name{Ghazāli}\fi
+% \begin{Verbatim}
+% \ifPDFTeX
+% \IfFileExists{utf8-2018.def}%
+% {\Name{Ghazāli}}{\Name{Ghazali}}%
+% \else\Name{Ghazāli}%
+% \fi
+% \end{Verbatim}
% \end{quote}
%
-% Even now,\Warn{} although one can use the Unicode characters with macrons, control sequences like \cmd{\=a} in the index will cause undocumented behavior when using \texttt{makeindex} and \texttt{gind.ist}. The latter index style, used for \texttt{dtx} files, changes the ``actual'' character from~\texttt{@} to~\texttt{=}.
-% \newpage
+% The challenge of compatibility arises in this manual in a few instances, which we summarize below to mention specific resources without going too far afield.
%
-% \begin{center}\bfseries Fragility of Active Unicode\end{center}
-% \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{itemize}
+% \item To use older distributions, one must include the \textsf{textcomp}
+% package for backward compatibility. Otherwise it is not needed in
+% recent \TeX\ distributions, e.g., since 2019.
+% \item We \cmd{\input} the included snippet \texttt{compat.tex} to
+% allow \texttt{examples.tex} and the test files (see \texttt{README.md})
+% to be compatible with different \LaTeX\ engines and older \TeX\
+% distributions. The file \texttt{examples.tex} includes additional
+% examples that deal with compatibility.
+% \item Use of certain text elements, such as \cmd{\dotfill} within
+% tables, has become more permissive in recent \TeX\ distributions.
+% This manual avoids situations that would cause compatibility
+% problems in older distributions.
+% \end{itemize}
+%
+% \subsubsection[Fragility]{Fragility of Active Unicode}
%
-% \begin{center}\MyStretch
+% \TeX\ macros that partition their arguments can break active Unicode characters.The simple macro |\def\foo#1#2#3!{<#1#2><#3>}| takes three arguments, groups the first two, then the third, followed by a delimiter that ends the argument list:
+%
+% \begin{center}\small\medstretch
% \def\foo#1#2#3!{<#1#2><#3>}
% \begin{tabular}{llll}\toprule
-% Argument & Macro & Engine & Result\\\midrule
-% \rowcolor{grey}|abc| & |\foo abc!| & (any) & \foo abc!\\
-% \rowcolor{grey}|{æ}bc| & |\foo {æ}bc!| & (any) & \foo {æ}bc!\\
-% \rowcolor{grey}|\ae bc| & |\foo \ae bc!| & (any) & \foo \ae bc!\\
-% |æbc| & |\foo æbc!| & \texttt{xelatex} & \ifxetex\foo æbc!\else<æb><c>\fi\\
-% |æbc| & |\foo æbc!| & \texttt{lualatex} & \ifluatex\foo æbc!\else<æb><c>\fi\\
-% \rowcolor{grey}|æbc| & |\foo æbc!| & \texttt{pdflatex} & \unless\ifxetex\unless\ifluatex\foo æbc!\else<æ><bc>\fi\else<æ><bc>\fi\\
-% \rowcolor{grey}|æbc| & |\foo æbc!| & \texttt{latex} & \unless\ifxetex\unless\ifluatex\foo æbc!\else<æ><bc>\fi\else<æ><bc>\fi\\\bottomrule
+% Argument & Macro & Engine & Result\\
+% \rowcolor{nagrey}|abc| & |\foo abc!| & (any) & \foo abc!\\
+% \rowcolor{nagrey}|{æ}bc| & |\foo {æ}bc!| & (any) & \foo {æ}bc!\\
+% \rowcolor{nagrey}|\ae bc| & |\foo \ae bc!| & (any) & \foo \ae bc!\\
+% |æbc| & |\foo æbc!| & \texttt{xelatex} &
+% \ifxetex\foo æbc!\else<æb><c>\fi\\
+% |æbc| & |\foo æbc!| & \texttt{lualatex} &
+% \ifluatex\foo æbc!\else<æb><c>\fi\\
+% \rowcolor{nagrey}|æbc| & |\foo æbc!| & \texttt{pdflatex} & \foo æbc!\\
+% \rowcolor{nagrey}|æbc| & |\foo æbc!| & \texttt{latex} & \foo æbc!\\
+% \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.
+% 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. Both \texttt{xelatex} and \texttt{lualatex} likewise treat the Unicode letter \texttt{æ} as one argument. Thus, in all these cases, the first two glyphs are grouped together in |#1#2| and \texttt{c} is left by itself in |#3|.
%
-% 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@two@octets has an extra \}}.
+% In \texttt{latex} and \texttt{pdflatex}, however, \texttt{æ} is an active Unicode control sequence that uses two arguments all by itself: |#1#2|. The rest of the input, \texttt{bc}, is in |#3|. This is not intuitive. 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@two@octets has an extra \}}.
%
-% \begin{center}\bfseries Testing for Fragility\end{center}
-% 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}).
+% Starting on page \pageref{page:Caps} we show how to 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} 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:AltFeatures}).
%
% \ReturnLink
%
-% \subsubsection{\LaTeX\ Engines}
-% \label{sec:TeXengines}
+% \begin{Quote}{\Name{Plato}, opening statement in \textit{Cratylus}}
+% \Name{Hermogenes}: I should explain to you, \Name{Socrates}, that our friend \Name{Cratylus} has been arguing about names; he says that they are natural and not conventional; not a portion of the human voice which men agree to use; but that there is a truth or correctness in them, which is the same for Hellenes as for barbarians. Whereupon I ask him, whether his own name of \Name{Cratylus} is a true name or not, and he answers `Yes.' And \Name{Socrates}? `Yes.' Then every man's name, as I tell him, is that which he is called. To this he replies{---}`If all the world were to call you \Name{Hermogenes}, that would not be your name.' And when I am anxious to have a further explanation he is ironical and mysterious, and seems to imply that he has a notion of his own about the matter, if he would only tell, and could entirely convince me, if he chose to be intelligible.
+% \end{Quote}
%
-% This preamble snippet lets us build \textsf{nameauth}, e.g., on TL 2017. We load \texttt{iftex.sty} only if it exists. We load transitional packages when \textsf{iftex} is absent or old:\footnote{A copy of this example is in \texttt{examples.tex}, located 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}
-%
-% If we
-% 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 at need. The font packages do affect \textsf{nameauth} indirectly. The use of \textit{TikZ} does not, but it is easy to let such concerns also use the test below. With \textsf{fontspec}, Latin Modern is the default. Otherwise, Computer Modern is the default. If we \emph{only} make \texttt{pdf} documents, the test below simplifies to a test for for \cmd{\Umathchar}, then loading either \textsf{fontspec} (success) or \textsf{fontenc} (failure).
-%
-% \begin{quote}\small
-% \ContinueNum
-% \begin{verbatim}
-%\newif\ifDoTikZ % If dvi-only workflow
-%\ifxetex
-% \usepackage{fontspec}
-% \usepackage{polyglossia}
-% \setdefaultlanguage{american} % Use own language
-% \usepackage{tikz}
-% \DoTikZtrue % If dvi-only workflow
-%\else
-% \ifluatex
-% \ifpdf
-% \usepackage{fontspec}
-% \usepackage{polyglossia}
-% \setdefaultlanguage{american} % Use own language
-% \usepackage{tikz}
-% \DoTikZtrue % If dvi-only workflow
-% \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
-% \usepackage{tikz} % If dvi-only workflow
-% \DoTikZtrue % If dvi-only workflow
-% \fi
-% \fi
-%\fi\end{verbatim}
-% \end{quote}
-%
-% To avoid problems, \texttt{\textbackslash ifDoTikZ} can help one conditionally load \textit{TikZ}. One can observe some \texttt{dvi} viewers (e.g., \texttt{yap}, \texttt{dviout}) crash either when loading or at some later point if one loads \textit{TikZ}. Neither \texttt{xdvi} nor \texttt{advi} crash.
-%
-% Using \texttt{xdvi} or \texttt{advi} (from \href{http://cristal.inria.fr/whizzytex/}{Whizzy\TeX}) may result in certain aspects of \textit{TikZ} not rendering correctly until conversion to \texttt{ps}/\texttt{pdf}. Using either \texttt{dvipdf} or \texttt{dvips} with \texttt{ps2pdf} will fix that. Using \texttt{dvipdfm} does not help here.
-% \newpage
-%
-% In the body text we can use something like the test below for:
-%
-% \begin{center}\fbox{\ifxetex doing \texttt{pdf} things\else \ifpdf doing \texttt{pdf} things\else doing \texttt{dvi} things\fi\fi}\end{center}
-%
-% \begin{quote}\small
-% \StartNum
-% \begin{verbatim}
-%\ifxetex
-% doing \texttt{pdf} things
-%\else
-% \ifpdf
-% doing \texttt{pdf} things
-% \else
-% doing \texttt{dvi} things
-% \fi
-%\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
-% \FontDebugfalse^^A prevents font debugging errors
% \let\emph\oldemph
-% \newgeometry{textwidth=160mm,textheight=237mm,right=25mm}
+% \newgeometry{textheight=239mm,left=20mm,right=20mm,nohead}
% \IndexProtect\PrintChanges\newpage\PrintIndex
% }
% \iffalse
@@ -5946,144 +9735,254 @@ and version 1.3 or later is part of all distributions of LaTeX version
% \section{Implementation}
% \small
%
-% \subsection{Flags and Registers}
-% \begin{center}\normalsize\bfseries General Process Flow Control\end{center}
+% This package has been reorganized so that the manual and the package
+% have substantially the same ordering. This repetition should aid
+% understanding how the components work.
%
-% \noindent{\normalsize\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 and page entries in the index.
-% \begin{macrocode}
-\newif\if@nameauth@Verbose
-% \end{macrocode}\medskip
+% \subsection{Boolean Flags}
+%
+% The \textsf{nameauth} package is a parser. The flags in this section
+% show the state of that parser.
+%
+% \subsubsection{Flow Control}
+%
+% \subsubsection*{\hfil Who Called Me?}
+%
+% Let name formatting macros in the core name engine know if they were
+% called by the naming macros or by the pseudonym macros.
%
-% \noindent{\normalsize\bfseries Who Called Me?}\medskip\\
-% Various macros use these flags to protect against stack overflows or choose the right output.
% \begin{macrocode}
\newif\if@nameauth@InAKA
\newif\if@nameauth@InName
-\newif\if@nameauth@Xref
-% \end{macrocode}\smallskip
+% \end{macrocode}
+%
+% \subsubsection*{\hfil Core Macro Locks}
+%
+% \cmd{\@nameauth@Name}, \cmd{\AKA}, and macros that call them use
+% \texttt{\textbackslash if@nameauth@Lock} to avoid a stack overflow.
+% Setting \texttt{\textbackslash if@nameauth@BigLock} true will prevent
+% the core name engine from executing until it is set false.
%
-% \noindent{\normalsize\bfseries Core Macro Locks}\medskip\\
-% \cmd{\@nameauth@Name}, \cmd{\AKA}, and other macros use a lock to avoid a stack overflow. With \texttt{\textbackslash @nameauth@BigLock} one prevents execution. See also Sections~\ref{sec:Hooksii} and~\ref{sec:Hooksiii}.
% \begin{macrocode}
\newif\if@nameauth@Lock
\newif\if@nameauth@BigLock
-\newif\if@nameauth@InHook
-% \end{macrocode}\smallskip
+% \end{macrocode}
%
-% \noindent{\normalsize\bfseries Name Decision Paths}\medskip\\
-% \cmd{\IfMainName}, \cmd{\IfFrontName}, and \cmd{\IfAKA} use locally-scoped paths by default. This flag causes that scoping not to be used.
-% \begin{macrocode}
-\newif\if@nameauth@GlobalScope
-% \end{macrocode}\smallskip
+% \subsubsection*{\hfil Formatting Hook Indicator}
%
-% \noindent{\normalsize\bfseries Debugging}\medskip\\
-% Both flags below are used to show name patterns and index entries in the text.
-% \begin{macrocode}
-\newif\if@nameauth@IdxDebug
-\newif\if@nameauth@LongIdxDebug
-% \end{macrocode}\smallskip
+% Tell alternate formatting control macros that they are in
+% a formatting hook.
%
-% \noindent{\normalsize\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 \cmd{\@nameauth@Name} act like a call to \cmd{\IndexName}:
% \begin{macrocode}
-\newif\if@nameauth@DoIndex
-\newif\if@nameauth@SkipIndex
-\newif\if@nameauth@JustIndex
+\newif\if@nameauth@InHook
% \end{macrocode}
-% The \texttt{pretag} and \texttt{nopretag} options toggle the flag below, which allows or prevents the insertion of index sort keys.
+%
+% \subsubsection*{\hfil Core Name Engine Choices}
+%
+% \cmd{\JustIndex} toggles this flag, which makes the core name engine
+% act like \cmd{\IndexName}.
+%
% \begin{macrocode}
-\newif\if@nameauth@Pretag
+\newif\if@nameauth@JustIndex
% \end{macrocode}
-% The first flag determines whether \cmd{\IndexRef} creates a \textit{see} reference or a \textit{see also} reference. The second determines how strict to be with \textit{see} references.
-% \begin{macrocode}
-\newif\if@nameauth@SeeAlso
-\newif\if@nameauth@OldSee
-% \end{macrocode}\smallskip
+% These two flags trigger \cmd{\ForgetName} and \cmd{\SubvertName}
+% within \cmd{\@nameauth@Name}.
%
-% \noindent{\normalsize\bfseries Formatting}\medskip\\
-% \cmd{\NamesActive} and \cmd{\NamesInactive}, with the \texttt{mainmatter} and \texttt{frontmatter} options, toggle formatting hooks via \texttt{\textbackslash if@nameauth@MainFormat}. \texttt{\textbackslash if@nameauth@AKAFormat} permits \cmd{\AKA} to call the first-use hooks once.
-% \begin{macrocode}
-\newif\if@nameauth@MainFormat
-\newif\if@nameauth@AKAFormat
-% \end{macrocode}\medskip
-% The next flag works with \cmd{\LocalNames} and \cmd{\GlobalNames}.
-% \begin{macrocode}
-\newif\if@nameauth@LocalNames
-% \end{macrocode}\medskip
-% These three flags are used only for backward compatibility. The first broadly determines how per-name flags are reset; the second affects the behavior of \cmd{\JustIndex}; and the third toggles whether or not the name argument token registers are set globally.
-% \begin{macrocode}
-\newif\if@nameauth@OldReset
-\newif\if@nameauth@OldPass
-\newif\if@nameauth@OldToks
-% \end{macrocode}\medskip
-% These two flags trigger \cmd{\ForgetName} and \cmd{\SubvertName} within \cmd{\@nameauth@Name}.
% \begin{macrocode}
\newif\if@nameauth@Forget
\newif\if@nameauth@Subvert
-% \end{macrocode}\medskip
-% \texttt{\textbackslash if@nameauth@FirstFormat} triggers the first-use hooks to be called; otherwise the second-use hooks are called. Additionally, \texttt{\textbackslash if@nameauth@AlwaysFormat} forces this true, except when \texttt{\textbackslash if@nameauth@AKAFormat} is false.
+% \end{macrocode}
+%
+% \subsubsection[Syntax]{Name Grammar and Syntax}
+%
+% \subsubsection*{\hfil Name Types}
+%
+% These flags\Info{\texttt{\textbackslash ifNameauthWestern}\break
+% \texttt{\textbackslash ifNameauthObsolete}}
+% reflect the last name type evaluated by any macro that takes
+% name arguments. The first shows whether or not we have a Western
+% or non-Western name. The second shows the kind of non-Western
+% syntax used. These are not reset after evaluation.
+%
% \begin{macrocode}
-\newif\if@nameauth@FirstFormat
-\newif\if@nameauth@AlwaysFormat
+\newif\ifNameauthWestern
+\newif\ifNameauthObsolete
% \end{macrocode}
%
-% \begin{center}\normalsize\bfseries Specific Name Form Modifications\end{center}
+% \subsubsection*{\hfil Show/Hide Affix Commas}
+%
+% The \texttt{comma} and \texttt{nocomma} options toggle the first
+% flag below. \cmd{\ShowComma} and \cmd{\NoComma} respectively toggle
+% the second and third.
%
-% \noindent{\normalsize\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@nameauth@AlwaysComma
\newif\if@nameauth@ShowComma
\newif\if@nameauth@NoComma
-% \end{macrocode}\medskip
+% \end{macrocode}
+%
+% \subsubsection*{\hfil Capitalize Entire Surnames}
+%
+% The first flag is global. The second is for individual names.
%
-% \noindent{\normalsize\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@nameauth@NBSP
-\newif\if@nameauth@NBSPX
-% \end{macrocode}\medskip
+\newif\if@nameauth@AllCaps
+\newif\if@nameauth@AllThis
+% \end{macrocode}
+%
+% \subsubsection*{\hfil Reverse Name Order}
+%
+% These flags govern name reversing. The first is global.
+% The second is for individual names.
+%
+% \begin{macrocode}
+\newif\if@nameauth@RevAll
+\newif\if@nameauth@RevThis
+% \end{macrocode}
+% These flags deals with Western names ordered
+% in a list according to surname.
+%
+% \begin{macrocode}
+\newif\if@nameauth@RevAllComma
+\newif\if@nameauth@RevThisComma
+% \end{macrocode}
+%
+% \subsubsection*{\hfil Full Stop Detection}
+%
+% This flag is used to prevent double full stops after a name
+% is displayed.
%
-% \noindent{\normalsize\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@nameauth@Punct
-% \end{macrocode}\medskip
+% \end{macrocode}
+%
+% \subsubsection*{\hfil Name Breaking}
+%
+% \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@nameauth@NBSP
+\newif\if@nameauth@NBSPX
+% \end{macrocode}
+%
+% \subsubsection*{\hfil Long and Short Names}
%
-% \noindent{\normalsize\bfseries Long and Short Names}\medskip\\
-% \texttt{\textbackslash if@nameauth@FullName} is true for a long name reference. \texttt{\textbackslash if@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@nameauth@FullName} is true for a long
+% name form. \texttt{\textbackslash if@nameauth@FirstName} causes only
+% Western forenames or non-Western surnames to be displayed when a shorter
+% form is used. The default is to reset both globally on a per-name basis.
%
-% \texttt{\textbackslash if@nameauth@AltAKA} is toggled respectively by \cmd{\AKA} and \cmd{\AKA*} to print a longer or shorter name. \texttt{\textbackslash if@nameauth@OldAKA} forces the pre-3.0 behavior of \cmd{\AKA*}.
+% \texttt{\textbackslash if@nameauth@ShortSNN} is used with
+% \cmd{\DropAffix} to suppress the affix of a Western name.
+% \texttt{\textbackslash if@nameauth@EastFN} toggles the forced printing
+% of Eastern forenames.
%
-% \texttt{\textbackslash if@nameauth@ShortSNN} is used with \cmd{\DropAffix} to suppress the affix of a Western name. \texttt{\textbackslash if@nameauth@EastFN} toggles the forced printing of Eastern forenames.
% \begin{macrocode}
\newif\if@nameauth@FullName
\newif\if@nameauth@FirstName
\newif\if@nameauth@AltAKA
-\newif\if@nameauth@OldAKA
\newif\if@nameauth@ShortSNN
\newif\if@nameauth@EastFN
-% \end{macrocode}\medskip
+% \end{macrocode}
+%
+% \subsubsection{Debugging}
+%
+% When used with the index debugging macros, show complete index entries
+% if true, otherwise show simple entries.
%
-% \noindent{\normalsize\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@nameauth@RevAll
-\newif\if@nameauth@RevThis
-\newif\if@nameauth@AllCaps
-\newif\if@nameauth@AllThis
-% \end{macrocode}\medskip
+\newif\if@nameauth@LongIdxDebug
+% \end{macrocode}
+%
+% \subsubsection{Indexing}
+%
+% \subsubsection*{\hfil Toggle Indexing}
+%
+% 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.
%
-% \noindent{\normalsize\bfseries Last-Comma-First}\medskip\\
-% This pair of flags deals with Western names reordered in a list according to surname.
% \begin{macrocode}
-\newif\if@nameauth@RevAllComma
-\newif\if@nameauth@RevThisComma
-% \end{macrocode}\medskip
+\newif\if@nameauth@DoIndex
+\newif\if@nameauth@SkipIndex
+% \end{macrocode}
+%
+% \subsubsection*{\hfil Toggle Index Sorting}
+%
+% Allow or prevent the insertion of index sort keys.
+%
+% \begin{macrocode}
+\newif\if@nameauth@Pretag
+% \end{macrocode}
+%
+% \subsubsection*{\hfil Verbose Warnings}
+%
+% Control the number of warnings concerning the index; default is terse.
+%
+% \begin{macrocode}
+\newif\if@nameauth@Verbose
+% \end{macrocode}
+%
+% \subsubsection*{\hfil Cross-References}
+%
+% Tell the index entry formatter to create a cross-reference.
+%
+% \begin{macrocode}
+\newif\if@nameauth@Xref
+% \end{macrocode}
+% Determine whether \cmd{\IndexRef} creates a \textit{see} reference
+% or a \textit{see also} reference.
+%
+% \begin{macrocode}
+\newif\if@nameauth@SeeAlso
+% \end{macrocode}
+%
+% \subsubsection[Formatting]{Formatting and Name Control Sequences}
+%
+% \subsubsection*{\hfil Choose Formatting System}
+%
+% \cmd{\NamesActive} and \cmd{\NamesInactive}, with the
+% \texttt{mainmatter} and \texttt{frontmatter} options, toggle
+% formatting hooks via \texttt{\textbackslash if@nameauth@MainFormat}.
+%
+% \begin{macrocode}
+\newif\if@nameauth@MainFormat
+% \end{macrocode}
+%
+% \subsubsection*{\hfil Modify Pseudonym Formatting}
+%
+% Permit \cmd{\AKA} and related macros to call the first-use formatting
+% hooks once.
+%
+% \begin{macrocode}
+\newif\if@nameauth@AKAFormat
+% \end{macrocode}
+%
+% \subsubsection*{\hfil Select Formatting Hooks}
+%
+% \texttt{\textbackslash if@nameauth@FirstFormat} triggers the first-use
+% hooks to be called; otherwise the second-use hooks are called.
+% Additionally, \texttt{\textbackslash if@nameauth@AlwaysFormat} forces
+% this true, except when \texttt{\textbackslash if@nameauth@AKAFormat}
+% is false.
+%
+% \begin{macrocode}
+\newif\if@nameauth@FirstFormat
+\newif\if@nameauth@AlwaysFormat
+% \end{macrocode}
+%
+% \subsubsection*{\hfil Caps and Alternate Formatting}
+%
+% The next flags deal with first-letter capitalization. \cmd{\CapThis}
+% sets the first Boolean value. The second is triggered by
+% \cmd{\@nameauth@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 within formatting hooks.
%
-% \noindent{\normalsize\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@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@nameauth@DoCaps
\newif\if@nameauth@UTF
@@ -6092,11 +9991,66 @@ and version 1.3 or later is part of all distributions of LaTeX version
\newif\if@nameauth@DoAlt
% \end{macrocode}
%
-% \begin{center}\normalsize\bfseries Name Argument Token Registers\end{center}
+% \subsubsection{Name Decisions}
+%
+% \subsubsection*{\hfil Creating and Destroying Name Patterns}
+%
+% Restrict the creation and destruction of name patters to the current
+% name system if true.
+%
+% \begin{macrocode}
+\newif\if@nameauth@LocalNames
+% \end{macrocode}
+%
+% \subsubsection*{\hfil Scope of Name Decision Macros}
+%
+% \cmd{\IfMainName}, \cmd{\IfFrontName}, and \cmd{\IfAKA} use
+% locally-scoped paths by default. When true, this flag causes these
+% macros to not apply local scope, retaining the current scope.
+%
+% \begin{macrocode}
+\newif\if@nameauth@GlobalScope
+% \end{macrocode}
+%
+% \subsubsection[Compatibility]{Version Compatibility}
+%
+% \texttt{\textbackslash if@nameauth@AltAKA} is toggled respectively
+% by \cmd{\AKA} and \cmd{\AKA*} to print a longer or shorter name.
+% \texttt{\textbackslash if@nameauth@OldAKA} forces the pre-3.0 behavior
+% of \cmd{\AKA*}.
+%
+% \begin{macrocode}
+\newif\if@nameauth@OldAKA
+% \end{macrocode}
+% Determine how strict to be with \textit{see} references.
+%
+% \begin{macrocode}
+\newif\if@nameauth@OldSee
+% \end{macrocode}
+% These three flags are used only for backward compatibility. The first
+% broadly determines how per-name flags are reset; the second affects the
+% behavior of \cmd{\JustIndex}; and the third toggles whether or not the
+% name argument token registers are set globally.
+%
+% \begin{macrocode}
+\newif\if@nameauth@OldReset
+\newif\if@nameauth@OldPass
+\newif\if@nameauth@OldToks
+% \end{macrocode}
+%
+% \subsection[Registers, Hooks, Values]
+% {Token Registers, Hooks, and Internal Values}
+%
+% \subsubsection[Token Registers]{Name Argument Token Registers}
+%
% \begin{macro}{\@nameauth@toksa}
% \begin{macro}{\@nameauth@toksb}
% \begin{macro}{\@nameauth@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.
+% 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@toksa
\newtoks\@nameauth@toksb
@@ -6105,88 +10059,158 @@ and version 1.3 or later is part of all distributions of LaTeX version
% \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.
+% These three token registers contain the current values of the name
+% arguments in each line of the \texttt{nameauth} environment, thus, \texttt{@nameauth@e} for that environment.
+%
% \begin{macrocode}
\newtoks\@nameauth@etoksb
\newtoks\@nameauth@etoksc
\newtoks\@nameauth@etoksd
% \end{macrocode}
%
-% \subsection{Hooks}
+% \subsubsection{Hooks}
+%
% \begin{macro}{\NamesFormat}
-% Post-process ``first'' instance of final complete name form in text. See Sections~\ref{sec:Formatting} and~\ref{sec:Hooksi}. Called when both |\@nameauth@MainFormat| and |\@nameauth@FirstFormat| are true.
+% Post-process ``first'' instance of final complete name form in text.
+% See Sections~\ref{sec:Formatting} and~\ref{sec:ComplexHooks}. Called when
+% both |\@nameauth@MainFormat| and |\@nameauth@FirstFormat| are true.
+%
% \begin{macrocode}
\newcommand*\NamesFormat{}
% \end{macrocode}
% \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:Hooksi}f. Called when |\@nameauth@MainFormat| is true and the Boolean flag |\@nameauth@FirstFormat| is false.
+% Post-process subsequent instance of final complete name form in
+% main-matter text. See Sections~\ref{sec:Formatting}
+% and~\ref{sec:ComplexHooks}f. Called when |\@nameauth@MainFormat| is true
+% and the Boolean flag |\@nameauth@FirstFormat| is false.
+%
% \begin{macrocode}
\newcommand*\MainNameHook{}
% \end{macrocode}
% \end{macro}
+%
% \begin{macro}{\FrontNamesFormat}
% \changes{2.5}{2016/04/06}{Added}
-% Post-process ``first'' instance of final complete name form in front-matter text. Called when |\@nameauth@MainFormat| is false and |\@nameauth@FirstFormat| is true.
+% Post-process ``first'' instance of final complete name form in
+% front-matter text. Called when |\@nameauth@MainFormat| is false
+% and |\@nameauth@FirstFormat| is true.
+%
% \begin{macrocode}
\newcommand*\FrontNamesFormat{}
% \end{macrocode}
% \end{macro}
+%
% \begin{macro}{\FrontNameHook}
% \changes{2.4}{2016/03/15}{Added}
-% Post-process subsequent instance of final complete name form in front-matter text. Called when |\@nameauth@MainFormat| is false and |\@nameauth@FirstFormat| is false.
+% Post-process subsequent instance of final complete name form in
+% front-matter text. Called when |\@nameauth@MainFormat| is false
+% and |\@nameauth@FirstFormat| is false.
+%
% \begin{macrocode}
\newcommand*\FrontNameHook{}
% \end{macrocode}
% \end{macro}
+%
+% \noindent The following three macros usually point to the core name
+% engine, \cmd{\@nameauth@Name}. They allow users to customize the naming
+% macros in the fullest sense. See Section~\ref{sec:FullCustomize}.
+%
% \begin{macro}{\NameauthName}
% \changes{2.2}{2015/12/01}{Added}
-% The last three hooks usually point to \cmd{\@nameauth@Name}. See Section~\ref{sec:Customize}.
+% Hook called when no special name modification is made.
+%
% \begin{macrocode}
\newcommand*\NameauthName{\@nameauth@Name}
% \end{macrocode}
% \end{macro}
+%
% \begin{macro}{\NameauthLName}
% \changes{2.3}{2016/01/05}{Added}
-% Customization hook called after \cmd{\@nameauth@FullName} is set true. See Section~\ref{sec:Customize}.
+% Hook called after a name is forced long via
+% \texttt{\textbackslash if@nameauth@name} being set to true.
+%
% \begin{macrocode}
\newcommand*\NameauthLName{\@nameauth@Name}
% \end{macrocode}
% \end{macro}
+%
% \begin{macro}{\NameauthFName}
% \changes{2.2}{2015/12/01}{Added}
-% Customization hook called after \cmd{\@nameauth@FirstName} is set true. See Section~\ref{sec:Customize}.
+% Hook called after \texttt{\textbackslash if@nameauth@FirstName}
+% is set true.
+%
% \begin{macrocode}
\newcommand*\NameauthFName{\@nameauth@Name}
% \end{macrocode}
% \end{macro}
+%
% \begin{macro}{\NameauthIndex}
% \changes{3.5}{2020/11/23}{Added}
-% Customization hook that allows one to redefine what happens when any naming or indexing function calls the equivalent of \cmd{\index}. See Section~\ref{sec:GeneralIndex}.
+% This hook allows one to redefine what happens when any naming macro
+% or indexing macro calls the equivalent of \cmd{\index}. See
+% Section~\ref{sec:GeneralIndex}.
+%
% \begin{macrocode}
\newcommand*\NameauthIndex{\index}
% \end{macrocode}
% \end{macro}
%
+% \begin{macro}{\NameauthPattern}
+% \changes{3.7}{2023/02/03}{Added}
+% Gives access to the current name control pattern. This hook can be
+% used, e.g., in formatting hooks to recall a name data tag
+% (Section~\ref{sec:DataTagHooks}). We preset it to an empty value. With
+% every call to a macro that takes name arguments
+% (Section~\ref{sec:NameArgMacros}), this hook is updated.
+%
+% \begin{macrocode}
+\let\NameauthPattern\@empty
+% \end{macrocode}
+% \end{macro}
+%
+% \subsubsection{Internal Values}
+%
+% \begin{macro}{\@nameauth@Actual}
+% \changes{2.0}{2015/11/11}{Added}
+% \changes{3.5}{2020/11/23}{Use \cmd{\def}}
+% This sets the ``actual'' character used by \textsf{nameauth} for
+% index sorting. This lets one use, for example, |\global\IndexActual{=}|.
+%
+% \begin{macrocode}
+\def\@nameauth@Actual{@}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\@nameauth@Exclude}
+% \changes{3.5}{2020/11/23}{Added}
+% This makes an xref into an ``exclusion''. An exclusion is any name
+% control sequence ending in \texttt{!PN} that expands to this value.
+% See \cmd{\ExcludeName}.
+%
+% \begin{macrocode}
+\newcommand*\@nameauth@Exclude{!}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\@nameauth@space}
+% \changes{3.7}{2023/02/03}{Made global}
+% This macro provides a consistent space character for index entries.
+%
+% \begin{macrocode}
+\def\@nameauth@space{ }
+% \end{macrocode}
+% \end{macro}
+%
% \subsection{Package Options}
-% The following package options interact with many of the prior Boolean values.
+%
+% \subsubsection[Syntax]{Name Grammar and Syntax}
+%
+% Change the way that names are displayed, specifically with respect to their syntactic forms.
+%
% \begin{macrocode}
-\DeclareOption{mainmatter}{\@nameauth@MainFormattrue}
-\DeclareOption{frontmatter}{\@nameauth@MainFormatfalse}
-\DeclareOption{alwaysformat}{\@nameauth@AlwaysFormattrue}
-\DeclareOption{formatAKA}{\@nameauth@AKAFormattrue}
-\DeclareOption{index}{\@nameauth@DoIndextrue}
-\DeclareOption{noindex}{\@nameauth@DoIndexfalse}
-\DeclareOption{pretag}{\@nameauth@Pretagtrue}
-\DeclareOption{nopretag}{\@nameauth@Pretagfalse}
-\DeclareOption{verbose}{\@nameauth@Verbosetrue}
-\DeclareOption{globaltest}{\@nameauth@GlobalScopetrue}
-\DeclareOption{oldAKA}{\@nameauth@OldAKAtrue}
-\DeclareOption{oldreset}{\@nameauth@OldResettrue}
-\DeclareOption{oldpass}{\@nameauth@OldPasstrue}
-\DeclareOption{oldtoks}{\@nameauth@OldTokstrue}
-\DeclareOption{oldsee}{\@nameauth@OldSeetrue}
\DeclareOption{nocomma}{\@nameauth@AlwaysCommafalse}
\DeclareOption{comma}{\@nameauth@AlwaysCommatrue}
\DeclareOption{normalcaps}{\@nameauth@AllCapsfalse}
@@ -6197,20 +10221,80 @@ and version 1.3 or later is part of all distributions of LaTeX version
{\@nameauth@RevAlltrue\@nameauth@RevAllCommafalse}
\DeclareOption{allrevcomma}%
{\@nameauth@RevAllfalse\@nameauth@RevAllCommatrue}
+% \end{macrocode}
+%
+% \subsubsection{Indexing}
+%
+% Global setting for enabling indexing, sort tags, and verbose warnings.
+%
+% \begin{macrocode}
+\DeclareOption{index}{\@nameauth@DoIndextrue}
+\DeclareOption{noindex}{\@nameauth@DoIndexfalse}
+\DeclareOption{pretag}{\@nameauth@Pretagtrue}
+\DeclareOption{nopretag}{\@nameauth@Pretagfalse}
+\DeclareOption{verbose}{\@nameauth@Verbosetrue}
+% \end{macrocode}
+%
+% \subsubsection{Formatting}
+%
+% Start off in a different naming regime or change formatting behavior in general or for \cmd{\AKA}.
+%
+% \begin{macrocode}
+\DeclareOption{mainmatter}{\@nameauth@MainFormattrue}
+\DeclareOption{frontmatter}{\@nameauth@MainFormatfalse}
+\DeclareOption{alwaysformat}{\@nameauth@AlwaysFormattrue}
+\DeclareOption{formatAKA}{\@nameauth@AKAFormattrue}
+% \end{macrocode}
+%
+% \subsubsection[Predefined Hooks]{Predefined Formatting Hooks}
+%
+% \begin{macrocode}
\DeclareOption{noformat}{\renewcommand*\NamesFormat{}}
\DeclareOption{smallcaps}{\renewcommand*\NamesFormat{\scshape}}
\DeclareOption{italic}{\renewcommand*\NamesFormat{\itshape}}
\DeclareOption{boldface}{\renewcommand*\NamesFormat{\bfseries}}
+% \end{macrocode}
+%
+% \subsubsection{Alternate Formatting}
+%
+% Enable alternate formatting.
+%
+% \begin{macrocode}
\DeclareOption{altformat}{%
\@nameauth@AltFormattrue\@nameauth@DoAlttrue}
-\ExecuteOptions%
- {nocomma,mainmatter,index,pretag,%
- normalcaps,notreversed,noformat}
-\ProcessOptions\relax
% \end{macrocode}
%
-% Now we load the required packages. They facilitate the first/subsequent name uses, the parsing of arguments, and the implementation of starred forms.
+% \subsubsection{Scope}
+%
+% Name test paths are either local or the same scope in which they are called.
+%
+% \begin{macrocode}
+\DeclareOption{globaltest}{\@nameauth@GlobalScopetrue}
+% \end{macrocode}
+%
+% \subsubsection[Compatibility]{Version Compatibility}
+%
+% Revert package behavior to mimic older versions.
+%
+% \begin{macrocode}
+\DeclareOption{oldAKA}{\@nameauth@OldAKAtrue}
+\DeclareOption{oldreset}{\@nameauth@OldResettrue}
+\DeclareOption{oldpass}{\@nameauth@OldPasstrue}
+\DeclareOption{oldtoks}{\@nameauth@OldTokstrue}
+\DeclareOption{oldsee}{\@nameauth@OldSeetrue}
+% \end{macrocode}
+%
+% \subsection{Package Initialization}
+%
+% Execute default options and process options passed by the user.
+% Load required packages for $\epsilon$-\TeX\ features, trimming
+% spaces from arguments, starred commands, and optional arguments.
+%
% \begin{macrocode}
+\ExecuteOptions
+ {nocomma,mainmatter,index,pretag,
+ normalcaps,notreversed,noformat}
+\ProcessOptions\relax
\RequirePackage{etoolbox}
\RequirePackage{trimspaces}
\RequirePackage{suffix}
@@ -6220,27 +10304,17 @@ and version 1.3 or later is part of all distributions of LaTeX version
% \subsection{Internal Macros}
% \label{sec:InternalMacros}
%
-% \noindent{\normalsize\bfseries Internal Values}
-% \begin{macro}{\@nameauth@Actual}
-% \changes{2.0}{2015/11/11}{Added}
-% \changes{3.5}{2020/11/23}{Use \cmd{\def}}
-% This sets the ``actual'' character used by \textsf{nameauth} for index sorting. This lets one use, for example, |\global\IndexActual{=}|.
-% \begin{macrocode}
-\def\@nameauth@Actual{@}
-% \end{macrocode}
-% \end{macro}
+% \subsubsection{Fundamental Macros}
%
-% \begin{macro}{\@nameauth@Exclude}
-% \changes{3.5}{2020/11/23}{Added}
-% This makes an xref into an ``exclusion''. An exclusion is any name control sequence ending in \texttt{!PN} that expands to this value. See \cmd{\ExcludeName}.
-% \begin{macrocode}
-\newcommand*\@nameauth@Exclude{!}
-% \end{macrocode}
-% \end{macro}
+% The following macros are the most essential to the concept of ``name''.
+%
+% \subsubsection*{\hfil Name Control Sequence: Who Am I?}
%
-% \noindent{\normalsize\bfseries Name Control Sequence: Who Am I?}
% \begin{macro}{\@nameauth@Clean}
-% Thanks to \Name*[Heiko]{Oberdiek}, this macro produces a ``sanitized'' string to make a control sequence for a name. Testing the existence of that control sequence is the core of \textsf{nameauth}.
+% Thanks to \Name*[Heiko]{Oberdiek}, this macro produces a ``sanitized''
+% string to make a control sequence for a name. Testing the existence of
+% that control sequence is the core of \textsf{nameauth}.
+%
% \begin{macrocode}
\newcommand*\@nameauth@Clean[1]
{\expandafter\zap@space\detokenize{#1} \@empty}
@@ -6249,7 +10323,9 @@ and version 1.3 or later is part of all distributions of LaTeX version
%
% \begin{macro}{\@nameauth@MakeCS}
% \changes{3.5}{2020/11/23}{Added}
-% Unless we are in \cmd{\AKA}, create a name control sequence in the core name engine.
+% Unless we are in \cmd{\AKA}, create a name control sequence
+% in the core name engine.
+%
% \begin{macrocode}
\newcommand*\@nameauth@MakeCS[1]
{%
@@ -6260,9 +10336,13 @@ and version 1.3 or later is part of all distributions of LaTeX version
% \end{macrocode}
% \end{macro}
%
-% \noindent{\normalsize\bfseries Parsing: Root and Suffix}
+% \subsubsection*{\hfil Parsing: Root and Suffix}
+%
% \begin{macro}{\@nameauth@Root}
-% The following two macros return everything before a comma in \meta{SNN}.
+% These two macros return everything before a comma in \meta{SNN}.
+% We do this with a delimited macro as a helper that determines the
+% root, the suffix, and the end of input.
+%
% \begin{macrocode}
\newcommand*\@nameauth@Root[1]{\@nameauth@@Root#1,\\}
% \end{macrocode}
@@ -6273,6 +10353,7 @@ and version 1.3 or later is part of all distributions of LaTeX version
% \changes{3.0}{2016/10/26}{Redesigned}
% \changes{3.2}{2017/03/22}{Renamed}
% Throw out the comma and suffix, return the radix.
+%
% \begin{macrocode}
\def\@nameauth@@Root#1,#2\\{\trim@spaces{#1}}
% \end{macrocode}
@@ -6281,7 +10362,10 @@ and version 1.3 or later is part of all distributions of LaTeX version
% \begin{macro}{\@nameauth@TrimTag}
% \changes{3.0}{2016/10/26}{Added}
% \changes{3.2}{2017/03/22}{Renamed}
-% The following two macros return everything before a vertical bar (\texttt{\textbar}) in an index tag.
+% These two macros return everything before a vertical bar
+% (\texttt{\textbar}) in an index tag (for sorting xrefs).
+% We do this with a delimited macro as a helper, as above.
+%
% \begin{macrocode}
\newcommand*\@nameauth@TrimTag[1]{\@nameauth@@TrimTag#1|\\}
% \end{macrocode}
@@ -6290,6 +10374,7 @@ and version 1.3 or later is part of all distributions of LaTeX version
% \begin{macro}{\@nameauth@@TrimTag}
% \changes{3.0}{2016/10/26}{Added}
% Throw out the bar and suffix, return the radix.
+%
% \begin{macrocode}
\def\@nameauth@@TrimTag#1|#2\\{#1}
% \end{macrocode}
@@ -6297,7 +10382,11 @@ and version 1.3 or later is part of all distributions of LaTeX version
%
% \begin{macro}{\@nameauth@Suffix}
% \changes{0.9}{2012/02/10}{Added}
-% The following two macros parse \meta{SNN} into a radix and a comma-delimited suffix, returning only the suffix after a comma in the argument, or nothing.
+% These two macros parse \meta{SNN} into a radix and a comma-delimited
+% suffix, returning only the suffix after a comma in the argument,\
+% or nothing. We do this with a delimited macro as a helper, but more
+% complicated this time.
+%
% \begin{macrocode}
\newcommand*\@nameauth@Suffix[1]{\@nameauth@@Suffix#1,,\\}
% \end{macrocode}
@@ -6308,7 +10397,9 @@ and version 1.3 or later is part of all distributions of LaTeX version
% \changes{1.5}{2013/02/22}{Trim spaces}
% \changes{3.0}{2016/10/26}{New test}
% \changes{3.2}{2017/03/22}{Renamed}
-% Throw out the radix; return the suffix with no leading spaces. We use this when printing the suffix.
+% Throw out the radix; return the suffix with no leading spaces.
+% Used to print the suffix.
+%
% \begin{macrocode}
\def\@nameauth@@Suffix#1,#2,#3\\{%
\ifx\\#2\\\@empty\else\trim@spaces{#2}\fi
@@ -6318,7 +10409,9 @@ and version 1.3 or later is part of all distributions of LaTeX version
%
% \begin{macro}{\@nameauth@GetSuff}
% \changes{3.2}{2017/03/22}{Added}
-% The following two macros just grab the suffix for testing if the first non-space character is an active character from \textsf{inputenc}.
+% These two macros test the suffix for a leading active Unicode
+% character. We use this for capitalization to avoid errors.
+%
% \begin{macrocode}
\newcommand*\@nameauth@GetSuff[1]{\@nameauth@@GetSuff#1,,\\}
% \end{macrocode}
@@ -6327,18 +10420,24 @@ and version 1.3 or later is part of all distributions of LaTeX version
% \begin{macro}{\@nameauth@@GetSuff}
% \changes{3.2}{2017/03/22}{Added}
% Throw out the radix; return the suffix.
+%
% \begin{macrocode}
\def\@nameauth@@GetSuff#1,#2,#3\\{#2}
% \end{macrocode}
% \end{macro}
%
-% \noindent{\normalsize\bfseries Parsing: Capitalization}
+% \subsubsection*{\hfil Parsing: Capitalization}
+% \label{page:Caps}
+%
% \begin{macro}{\@nameauth@TestToks}
-% \phantomsection
-% \label{page:CapSystem}
% \changes{3.2}{2017/03/22}{Added}
% \changes{3.5}{2020/11/23} {Fix namespace}
-% 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.
+% 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 (using \texttt{pdflatex} and
+% \texttt{latex}). Otherwise we use native Unicode.
+%
% \begin{macrocode}
\newcommand*\@nameauth@TestToks[1]
{%
@@ -6360,7 +10459,11 @@ and version 1.3 or later is part of all distributions of LaTeX version
% \changes{3.1}{2017/01/13}{Can skip test}
% \changes{3.2}{2017/03/22}{Non-suffix only}
% \changes{3.5}{2020/11/23}{Fix namespace}
-% We choose how to capitalize a letter by determining if we are running under \texttt{xelatex} or \texttt{lualatex}. We test for \cmd{\Umathchar}. Then we see if \textsf{inputenc} is loaded. We set up the comparison and pass off to \cmd{\@nameauth@TestToks}.
+% We choose how to capitalize a letter by determining if we are using
+% native Unicode (\texttt{xelatex} or \texttt{lualatex}). We test for
+% \cmd{\Umathchar}. Then we see if \textsf{inputenc} is loaded. We set up
+% the comparison and pass off to \cmd{\@nameauth@TestToks}.
+%
% \begin{macrocode}
\newcommand*\@nameauth@UTFtest[1]
{%
@@ -6372,7 +10475,7 @@ and version 1.3 or later is part of all distributions of LaTeX version
\if@nameauth@Accent
\@nameauth@UTFtrue\@nameauth@Accentfalse%
\else
- \expandafter\@nameauth@TestToks%
+ \expandafter\@nameauth@TestToks
\expandafter{\@nameauth@testarg}%
\fi
\else
@@ -6386,19 +10489,27 @@ and version 1.3 or later is part of all distributions of LaTeX version
% \begin{macro}{\@nameauth@UTFtestS}
% \changes{3.2}{2017/03/22}{Added}
% \changes{3.5}{2020/11/23}{Fix namespace}
-% This test is like the one above, but a special case when we have a suffix. We have to do a bit more in the way of expansion to get the comparison to work properly. Moreover, we only use this when the regular suffix macro is not \cmd{\@empty}.
+% This test is like the one above, but a special case when we have
+% a suffix. We have to do a bit more in the way of expansion to get
+% the comparison to work properly. Moreover, we only use this when
+% the regular suffix macro is not \cmd{\@empty}.
+%
% \begin{macrocode}
\newcommand*\@nameauth@UTFtestS[1]
{%
\expandafter\def\expandafter\@nameauth@testarg%
\expandafter{\@nameauth@GetSuff{#1}}%
% \end{macrocode}
-% This following token register assignment looks weird, but it is how we get a test that works.
+% This following token register assignment looks weird, but it is
+% how we get a test that works.
+%
% \begin{macrocode}
\expandafter\toks@%
\expandafter\expandafter\expandafter{\@nameauth@testarg}%
% \end{macrocode}
-% We take that token register and assign its value to a macro to do the test.
+% We take that token register and assign its value to a macro
+% to do the test.
+%
% \begin{macrocode}
\expandafter\def\expandafter\@nameauth@test@rg%
\expandafter{\the\toks@}%
@@ -6423,7 +10534,10 @@ and version 1.3 or later is part of all distributions of LaTeX version
% \begin{macro}{\@nameauth@Cap}
% \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.
+% These two macros cap the first letter of the argument.
+% Since they partition the argument into two segments, this can
+% break some macro arguments unless one uses \cmd{\noexpand}.
+%
% \begin{macrocode}
\newcommand*\@nameauth@Cap[1]{\@nameauth@C@p#1\\}
% \end{macrocode}
@@ -6433,6 +10547,7 @@ and version 1.3 or later is part of all distributions of LaTeX version
% \changes{3.1}{2017/01/13}{Added}
% \changes{3.2}{2017/03/22}{Renamed, use \cmd{\MakeUppercase}}
% Helper macro for the one above.
+%
% \begin{macrocode}
\def\@nameauth@C@p#1#2\\{%
\expandafter\trim@spaces\expandafter{\MakeUppercase{#1}#2}%
@@ -6442,7 +10557,10 @@ and version 1.3 or later is part of all distributions of LaTeX version
%
% \begin{macro}{\@nameauth@CapUTF}
% \changes{3.2}{2017/03/22}{Added}
-% The following two macros cap the first active Unicode letter under \textsf{inputenc}.
+% These two macros cap the first active Unicode letter when one
+% is using \textsf{inputenc} (an argument ``twice as wide'' as
+% normal, native Unicode).
+%
% \begin{macrocode}
\newcommand*\@nameauth@CapUTF[1]{\@nameauth@C@pUTF#1\\}
% \end{macrocode}
@@ -6452,6 +10570,7 @@ and version 1.3 or later is part of all distributions of LaTeX version
% \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@C@pUTF#1#2#3\\{%
\expandafter\trim@spaces\expandafter{\MakeUppercase{#1#2}#3}%
@@ -6461,7 +10580,11 @@ and version 1.3 or later is part of all distributions of LaTeX version
%
% \begin{macro}{\@nameauth@CapArgs}
% \changes{3.5}{2020/11/23}{Added}
-% Capitalize the first letter of all name arguments. Implements capitalization on demand in the body text (not the index) when not in alternate formatting. We only use this macro in the local scope of \cmd{\@nameauth@Parse}.
+% Capitalize the first letter of all name arguments. Implements
+% capitalization on demand in the body text (not the index) when not
+% in alternate formatting. We only use this macro in the local scope
+% of \cmd{\@nameauth@Parse}. Uses the foregoing macros.
+%
% \begin{macrocode}
\newcommand*\@nameauth@CapArgs[3]
{%
@@ -6472,19 +10595,23 @@ and version 1.3 or later is part of all distributions of LaTeX version
\let\csuffb\suffb%
\let\cargc\argc%
% \end{macrocode}
-% We test the first argument for active Unicode characters, then cap the first letter.
+% We test \meta{FNN} for active, non-native Unicode
+% characters, then cap the first letter.
+%
% \begin{macrocode}
\unless\ifx\arga\@empty
\def\test{#1}%
\expandafter\@nameauth@UTFtest\expandafter{\test}%
% \end{macrocode}
% Capitalize the first active Unicode character.
+%
% \begin{macrocode}
\if@nameauth@UTF
\expandafter\def\expandafter\carga\expandafter{%
\expandafter\@nameauth@CapUTF\expandafter{\test}}%
% \end{macrocode}
-% Capitalize the first character (not active Unicode).
+% Capitalize the first native Unicode character (not active).
+%
% \begin{macrocode}
\else
\expandafter\def\expandafter\carga\expandafter{%
@@ -6492,25 +10619,31 @@ and version 1.3 or later is part of all distributions of LaTeX version
\fi
\fi
% \end{macrocode}
-% We test the root surname for active Unicode characters, then cap the first letter.
+% We test \meta{SNN} for active Unicode characters,
+% then cap the first letter.
+%
% \begin{macrocode}
\def\test{#2}%
\expandafter\@nameauth@UTFtest\expandafter{\test}%
% \end{macrocode}
% Capitalize the first active Unicode character.
+%
% \begin{macrocode}
\if@nameauth@UTF
\expandafter\def\expandafter\crootb\expandafter{%
\expandafter\@nameauth@CapUTF\expandafter{\rootb}}%
% \end{macrocode}
-% Capitalize the first character (not active Unicode).
+% Capitalize the first native character (not active).
+%
% \begin{macrocode}
\else
\expandafter\def\expandafter\crootb\expandafter{%
\expandafter\@nameauth@Cap\expandafter{\rootb}}%
\fi
% \end{macrocode}
-% We test the suffix for active Unicode characters, then cap the first letter.
+% We test \meta{Affix} for active Unicode characters,
+% then cap the first letter.
+%
% \begin{macrocode}
\unless\ifx\suffb\@empty
\def\test{#2}%
@@ -6518,13 +10651,15 @@ and version 1.3 or later is part of all distributions of LaTeX version
\protected@edef\test{\@nameauth@GetSuff{#2}}%
% \end{macrocode}
% Capitalize the first active Unicode character.
+%
% \begin{macrocode}
\if@nameauth@UTF
\protected@edef\test{\@nameauth@Suffix{#2}}%
\expandafter\def\expandafter\csuffb\expandafter{%
\expandafter\@nameauth@CapUTF\expandafter{\test}}%
% \end{macrocode}
-% Capitalize the first character (not active Unicode).
+% Capitalize the first native Unicode character (not active).
+%
% \begin{macrocode}
\else
\edef\@nameauth@test{\@nameauth@Suffix{#2}}%
@@ -6533,19 +10668,23 @@ and version 1.3 or later is part of all distributions of LaTeX version
\fi
\fi
% \end{macrocode}
-% We test the final argument for active Unicode characters, then cap the first letter.
+% We test \meta{Alternate} for active Unicode characters,
+% then cap the first letter.
+%
% \begin{macrocode}
\unless\ifx\argc\@empty
\def\test{#3}%
\expandafter\@nameauth@UTFtest\expandafter{\test}%
% \end{macrocode}
% Capitalize the first active Unicode character.
+%
% \begin{macrocode}
\if@nameauth@UTF
\expandafter\def\expandafter\cargc\expandafter{%
\expandafter\@nameauth@CapUTF\expandafter{\test}}%
% \end{macrocode}
-% Capitalize the first character (not active Unicode).
+% Capitalize the first native Unicode character (not active).
+%
% \begin{macrocode}
\else
\expandafter\def\expandafter\cargc\expandafter{%
@@ -6553,7 +10692,10 @@ and version 1.3 or later is part of all distributions of LaTeX version
\fi
\fi
% \end{macrocode}
-% Let the arguments be the macros with caps.
+% Let the local arguments be the macros with caps. We cap them all
+% and let the macros sort them out because we do not know which will
+% be displayed.
+%
% \begin{macrocode}
\let\arga\carga%
\let\rootb\crootb%
@@ -6565,19 +10707,31 @@ and version 1.3 or later is part of all distributions of LaTeX version
% \end{macrocode}
% \end{macro}
%
-% \noindent{\normalsize\bfseries Parsing: Punctuation Detection and Alteration}
+% \subsubsection*{\hfil Parsing: Full Stops}
+%
% \begin{macro}{\@nameauth@TestDot}
% \changes{3.5}{2020/11/23}{Redesigned}
-% This macro, based on a snippet by \Name*[Uwe]{Lueck}, checks for a full stop at the end of its argument using the two internal helper macros below.
+% This macro, based on a snippet by \Name*[Uwe]{Lueck}, checks for
+% a full stop at the end of its argument using the two internal helper
+% macros below.
+%
% \begin{macrocode}
\newcommand*\@nameauth@TestDot[1]
{%
% \end{macrocode}
-% If no full stop is present, \texttt{\#\#1} is associated with the first \cmd{\@End.}. The second \cmd{\@End} gets absorbed as a parameter, leaving \texttt{\#\#2} empty. If a full stop is present, \texttt{\#\#2} will contain it.
+% If no full stop is present, \texttt{\#\#1} is associated with the first
+% \cmd{\@End.} The second \cmd{\@End} gets absorbed, leaving
+% \texttt{\#\#2} empty. If a full stop is present, \texttt{\#\#2}
+% will contain it.
+%
% \begin{macrocode}
\def\@nameauth@TestD@t##1.\@End##2\\{\@nameauth@TestPunct{##2}}%
% \end{macrocode}
-% The two control sequences are equal if \texttt{\#\#1} is empty (no full stop). If \texttt{\#\#1} is not empty, it sets \cmd{\@nameauth@Puncttrue}, which triggers the call to \cmd{\@nameauth@CheckDot} below.
+% The two control sequences are equal if \texttt{\#\#1} is empty
+% (no full stop). If \texttt{\#\#1} is not empty, it sets
+% \cmd{\@nameauth@Puncttrue}, which triggers the call to
+% \cmd{\@nameauth@CheckDot} below. One cannot use \cmd{\unless} below.
+%
% \begin{macrocode}
\def\@nameauth@TestPunct##1%
{%
@@ -6593,7 +10747,11 @@ and version 1.3 or later is part of all distributions of LaTeX version
% \end{macro}
%
% \begin{macro}{\@nameauth@CheckDot}
-% We assume that \cmd{\expandafter} precedes the invocation of \cmd{\@nameauth@CheckDot}, which only is called if the terminal character of the input is a period. We evaluate the lookahead \cmd{\@nameauth@token} while keeping it on the list of input tokens.
+% We assume that \cmd{\expandafter} precedes the invocation of
+% \cmd{\@nameauth@CheckDot}, which only is called if the terminal
+% character of the input is a period. We evaluate the lookahead
+% \cmd{\@nameauth@token} while keeping it on the list of input tokens.
+%
% \begin{macrocode}
\newcommand*\@nameauth@CheckDot
{\futurelet\@nameauth@token\@nameauth@EvalDot}
@@ -6601,45 +10759,62 @@ and version 1.3 or later is part of all distributions of LaTeX version
% \end{macro}
%
% \begin{macro}{\@nameauth@EvalDot}
-% If \cmd{\@nameauth@token} is a full stop, we gobble the next token. Note that we cannot have this conditional statement span more than one line.
+% If \cmd{\@nameauth@token}, the lookahead, is a full stop, we gobble
+% the next token because it is that full stop.
+%
% \begin{macrocode}
\newcommand*\@nameauth@EvalDot
{%
\let\@nameauth@stop=.%
- \ifx\@nameauth@token\@nameauth@stop\expandafter\@gobble \fi
+ \ifx\@nameauth@token\@nameauth@stop
+ \expandafter\@gobble \fi
}
% \end{macrocode}
% \end{macro}
%
+% \newpage
+%
+% \subsubsection*{\hfil Parsing: Breaking, Spaces, and Commas}
+%
% \begin{macro}{\@nameauth@AddPunct}
% \changes{3.5}{2020/11/23}{Added}
-% Here we govern whether spaces between name elements break or not, and whether to add commas or not. This all occurs in the text, not the index. The priority from highest to lowest is no commas, show commas, and always show commas. Much applies only to Western names, thus we check of \meta{FNN} is empty or not. We only use this macro in the local scope of \cmd{\@nameauth@Parse}.
+% Here we govern whether (in the text, not the index) spaces between
+% name elements break or not, and whether to add commas or not. Much
+% applies only to Western names, thus we check if \meta{FNN} is empty
+% or not. We only use this macro in \cmd{\@nameauth@Parse}.
+%
% \begin{macrocode}
\newcommand*\@nameauth@AddPunct
{%
\ifdefined\@nameauth@InParser
\def\Space{ }%
- \def\SpaceX{ }%
+ \def\SpaceW{ }%
% \end{macrocode}
-% \cmd{\SpaceX} is used for the space between a Western name and an affix, specifically tied to \cmd{\KeepAffix}. \cmd{\Space} is used for all other spaces between name elements.
+% \cmd{\SpaceW} is used for the space between a Western name and an affix,
+% specifically tied to \cmd{\KeepAffix}. \cmd{\Space} is used for all
+% other spaces between name elements.
+%
% \begin{macrocode}
\if@nameauth@NBSP \edef\Space{\nobreakspace}\fi
- \if@nameauth@NBSPX \edef\SpaceX{\nobreakspace}\fi
+ \if@nameauth@NBSPX \edef\SpaceW{\nobreakspace}\fi
% \end{macrocode}
-% Western names have a set of comma-use conventions that differ from all other name forms, so we only use the following logic if \meta{FNN} is not empty, thus, a Western name.
+% Western names have a set of comma-use conventions that differ
+% from all other name forms, so we only use the following logic
+% if \meta{FNN} is not empty, thus, a Western name.
+%
% \begin{macrocode}
\unless\ifx\arga\@empty
\if@nameauth@AlwaysComma
\def\Space{, }%
- \if@nameauth@NBSP \edef\Space{,\nobreakspace}\fi
+ \if@nameauth@NBSP\edef\Space{,\nobreakspace}\fi
\fi
\if@nameauth@ShowComma
\def\Space{, }%
- \if@nameauth@NBSP \edef\Space{,\nobreakspace}\fi
+ \if@nameauth@NBSP\edef\Space{,\nobreakspace}\fi
\fi
\if@nameauth@NoComma
\def\Space{ }%
- \if@nameauth@NBSP \edef\Space{\nobreakspace}\fi
+ \if@nameauth@NBSP\edef\Space{\nobreakspace}\fi
\fi
\fi
\fi
@@ -6647,15 +10822,20 @@ and version 1.3 or later is part of all distributions of LaTeX version
% \end{macrocode}
% \end{macro}
%
-% \noindent{\normalsize\bfseries Parsing: Name Argument Loading}
+% \subsubsection*{\hfil Parsing: Name Argument Loading}
+%
% \begin{macro}{\@nameauth@LoadArgs}
% \changes{3.5}{2020/11/23}{Added}
-% Assign name arguments to internal macros to determine name syntax. This is used in all macros that take name arguments.
+% Assign name arguments to internal macros to determine name syntax.
+% This is used in all macros that take name arguments.
+%
% \begin{macrocode}
\newcommand*\@nameauth@LoadArgs[3]
{%
% \end{macrocode}
-% We want these arguments to expand to \cmd{\@empty} (or not) when we test them.
+% We want these arguments to expand to \cmd{\@empty} (or not)
+% when we test them.
+%
% \begin{macrocode}
\protected@edef\@nameauth@A{\trim@spaces{#1}}%
\protected@edef\@nameauth@B{\@nameauth@Root{#2}}%
@@ -6663,6 +10843,7 @@ and version 1.3 or later is part of all distributions of LaTeX version
\protected@edef\@nameauth@C{\trim@spaces{#3}}%
% \end{macrocode}
% Make (usually) unique control sequence values from the name arguments.
+%
% \begin{macrocode}
\def\@nameauth@csb{\@nameauth@Clean{#2}}%
\def\@nameauth@csbc{\@nameauth@Clean{#2,#3}}%
@@ -6671,36 +10852,72 @@ and version 1.3 or later is part of all distributions of LaTeX version
% \end{macrocode}
% \end{macro}
%
-% \noindent{\normalsize\bfseries Parsing: Standard Parsing Logic}
+% \subsubsection*{\hfil Parsing: Standard Parsing Logic}
+%
% \begin{macro}{\@nameauth@Choice}
% \changes{3.5}{2020/11/23}{Added}
-% This standard logic applies to all macros that take name arguments.
+% \changes{3.7}{2023/02/03}{Access name pattern and type; redesigned to
+% optimize many macros}
+% This standard logic applies to all macros that take name arguments. Here
+% we update \cmd{\NameauthPattern},
+% \texttt{\textbackslash ifNameauthWestern}, and
+% \texttt{\textbackslash ifNameauthObsolete} to show the resulting name
+% pattern and type of name, usable in formatting hooks.
+%
% \begin{macrocode}
\newcommand\@nameauth@Choice[3]
{%
\ifx\@nameauth@A\@empty
\ifx\@nameauth@C\@empty
% \end{macrocode}
-% This decision path is for non-Western names. The \texttt{\#1} argument recurs below where \cmd{\@nameauth@SB} is present. Thus, for output to the text, the \texttt{\#1} argument must test both \cmd{\@nameauth@C} and \cmd{\@nameauth@SB}, and swap the former with the latter if necessary. For output to the index or for handling control sequences, one ignores \cmd{\@nameauth@C}.
+% This decision path is for non-Western names. The \texttt{\#1} argument
+% recurs below where \cmd{\@nameauth@SB} is present. Thus, for output
+% to the text, the \texttt{\#1} argument must test both \cmd{\@nameauth@C}
+% and \cmd{\@nameauth@SB}, and swap the former with the latter if
+% necessary. For output to the index or for handling control sequences,
+% one ignores \cmd{\@nameauth@C}.
+%
% \begin{macrocode}
+ \let\NameauthPattern\@nameauth@csb%
+ \NameauthWesternfalse \NameauthObsoletefalse%
#1%
\else
\ifx\@nameauth@SB\@empty
% \end{macrocode}
-% The \texttt{\#2} argument is only for non-Western names that use the obsolete syntax. In the \texttt{\#2} argument \cmd{\@nameauth@SB} never occurs. For indexing and control sequences, one cannot ignore the use of \cmd{\@nameauth@C} in this path.
+% The \texttt{\#2} argument is only for non-Western names that use
+% the obsolete syntax. In the \texttt{\#2} argument \cmd{\@nameauth@SB}
+% never occurs. For indexing and control sequences, one cannot ignore
+% the use of \cmd{\@nameauth@C} in this path.
+%
% \begin{macrocode}
+ \let\NameauthPattern\@nameauth@csbc%
+ \NameauthWesternfalse \NameauthObsoletetrue%
#2%
\else
% \end{macrocode}
-% But if both \cmd{\@nameauth@SB} and \cmd{\@nameauth@C} are present, we invoke the \texttt{\#1} argument instead and let it do any further testing and processing.
+% But if both \cmd{\@nameauth@SB} and \cmd{\@nameauth@C} are present,
+% we invoke the \texttt{\#1} argument instead and let it do any further
+% testing and processing.
+%
% \begin{macrocode}
+ \let\NameauthPattern\@nameauth@csb%
+ \NameauthWesternfalse \NameauthObsoletefalse%
#1%
\fi
\fi
\else
% \end{macrocode}
-% This decision path is for Western names. In those cases where one must work with name forms in the text, somewhere in the \texttt{\#3} argument one must test for \cmd{\@nameauth@C} and swap it for \cmd{\@nameauth@A}, as well as accounting for the presence or absence of \cmd{\@nameauth@SB}. Otherwise, for indexing and control sequences, one ignores \cmd{\@nameauth@C} in this path and handles \cmd{\@nameauth@SB} appropriately.
+% This decision path is for Western names. In those cases where one
+% must work with name forms in the text, somewhere in the \texttt{\#3}
+% argument one must test for \cmd{\@nameauth@C} and swap it for
+% \cmd{\@nameauth@A}, as well as accounting for the presence or absence
+% of \cmd{\@nameauth@SB}. Otherwise, for indexing and control sequences,
+% one ignores \cmd{\@nameauth@C} in this path and handles
+% \cmd{\@nameauth@SB} appropriately.
+%
% \begin{macrocode}
+ \let\NameauthPattern\@nameauth@csab%
+ \NameauthWesterntrue \NameauthObsoletefalse%
#3%
\fi
}
@@ -6709,17 +10926,23 @@ and version 1.3 or later is part of all distributions of LaTeX version
%
% \begin{macro}{\@nameauth@Flags}
% \changes{3.5}{2020/09/25}{Added}
-% Reset flags after the naming macros and \cmd{\AKA} and friends create output in the text. This is not the only place where formatting flags are reset, but the other places in the core naming engine and name parser are special-use cases designed for the use of \cmd{\JustIndex} and macros like \cmd{\PName}.
+% Reset flags after the naming macros and \cmd{\AKA} and friends create
+% output in the text. Other places in the core naming engine where flags
+% are reset are for special cases like \cmd{\JustIndex}.
+%
% \begin{macrocode}
\newcommand*\@nameauth@Flags
{%
\if@nameauth@OldReset
% \end{macrocode}
-% The \texttt{oldreset} option implies not only a difference in scope regarding how flags are reset, but it also lets the effects of \cmd{\ForgetThis} and \cmd{\SubvertThis} to pass through \cmd{\AKA} and \cmd{\AKA*}. Regardless, we only reset \texttt{\textbackslash if@nameauth@AltAKA} here due to macros like \cmd{\PName}.
+% The \texttt{oldreset} option implies not only a difference
+% in scope regarding how flags are reset, but it also lets the effects
+% of \cmd{\ForgetThis} and \cmd{\SubvertThis} to pass through \cmd{\AKA}
+% and \cmd{\AKA*}. Regardless, we only reset \texttt{\textbackslash
+% if@nameauth@AltAKA} here due to macros like \cmd{\PName}.
+%
% \begin{macrocode}
- \if@nameauth@InAKA
- \@nameauth@AltAKAfalse%
- \fi
+ \if@nameauth@InAKA\@nameauth@AltAKAfalse\fi
\@nameauth@SkipIndexfalse%
\if@nameauth@InName
\@nameauth@Forgetfalse%
@@ -6738,12 +10961,12 @@ and version 1.3 or later is part of all distributions of LaTeX version
\@nameauth@EastFNfalse%
\else
% \end{macrocode}
-% \newpage\noindent
-% The current way that the flags are reset makes them both global and more uniform, hopefully eliminating a few chances for errors that might be quite difficult to debug.
+% The current way that the flags are reset makes them both global
+% and more uniform, hopefully eliminating a few chances for errors
+% that might be quite difficult to debug.
+%
% \begin{macrocode}
- \if@nameauth@InAKA
- \global\@nameauth@AltAKAfalse%
- \fi
+ \if@nameauth@InAKA\global\@nameauth@AltAKAfalse\fi
\global\@nameauth@SkipIndexfalse%
\global\@nameauth@Forgetfalse%
\global\@nameauth@Subvertfalse%
@@ -6763,12 +10986,16 @@ and version 1.3 or later is part of all distributions of LaTeX version
% \end{macrocode}
% \end{macro}
%
-% \noindent{\normalsize\bfseries Error Detection and Debugging}
+% \subsubsection[Errors/Debugging]{Error Detection and Debugging}
+%
% \begin{macro}{\@nameauth@Error}
% \changes{3.0}{2016/10/26}{Added}
% \changes{3.01}{2016/10/27}{Fixed}
% \changes{3.5}{2020/11/23}{Fix namespace}
-% 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 malformed root/suffix pair. We provide meaningful feedback regarding these cases.
+% The \textsf{nameauth} package will halt with a meaningful error
+% when a required name argument is empty, expands to empty,
+% has an empty root in a malformed root/suffix pair.
+%
% \begin{macrocode}
\newcommand*\@nameauth@Error[2]
{%
@@ -6786,86 +11013,70 @@ and version 1.3 or later is part of all distributions of LaTeX version
% \end{macrocode}
% \end{macro}
%
-% \begin{macro}{\@nameauth@Debug}
-% \changes{3.3}{2020/02/20}{added}
-% \changes{3.5}{2020/11/23}{use index hook, optimize logic, fix namespace, use Boolean flags}
-% In this Swiss-army knife for debugging, we set up a local scope because we make changes that would otherwise affect normal \textsf{nameauth} output. We redefine \cmd{\NameauthIndex} to print an argument in the text instead of the index, and we force indexing to occur.
+% \begin{macro}{\@nameauth@IdxPageref}
+% \changes{3.3}{2020/02/20}{Added}
+% \changes{3.5}{2020/11/23}{Use index hook, optimize logic,
+% fix name space, use Boolean flags}
+% \changes{3.7}{2023/02/03}{Renamed; only show index entries;
+% add warning; optimized}
+% Here we set up a local scope because we make changes that would
+% otherwise affect normal \textsf{nameauth} output. We redefine
+% \cmd{\NameauthIndex} to print an argument in the text instead of
+% the index, and we force indexing to occur.
+%
% \begin{macrocode}
-\newcommandx*\@nameauth@Debug[3][1=\@empty, 3=\@empty]
+\newcommand*\@nameauth@IdxPageref[3]
{%
- \begingroup%
- \def\NameauthIndex##1{##1}%
- \@nameauth@DoIndextrue%
% \end{macrocode}
-% Process and load the arguments into the appropriate macros.
-% \begin{macrocode}
- \@nameauth@LoadArgs{#1}{#2}{#3}%
- \@nameauth@Error{#2}{macro \string\@nameauth@Debug}%
-% \end{macrocode}
-% \newpage\noindent
-% Below, given \cmd{\@nameauth@IdxDebugfalse} and \cmd{\@nameauth@LongIdxDebugfalse}, we produce the output of \cmd{\ShowPattern}.
-%
-% Otherwise we locally delete any tag and xref control sequences as needed. They will be restored when the scope ends. If \cmd{\ShowIdxPageref} set \cmd{\@nameauth@IdxDebugtrue} and \cmd{\@nameauth@LongIdxDebugtrue} we produce a full index entry that shows all the tags and the ``actual'' character as well as the name. If \cmd{\ShowIdxPageref*} set \cmd{\@nameauth@IdxDebugtrue} we produce a short index entry that shows only the name.
+% Warn if \cmd{\SkipIndex} was called before \cmd{\ShowIdxPageref},
+% and reset it.
%
% \begin{macrocode}
- \@nameauth@Choice%
-% \end{macrocode}
-% Non-Western names, current syntax.
-% \begin{macrocode}
- {%
- \unless\if@nameauth@IdxDebug
- \@nameauth@csb%
- \else
- \csundef{\@nameauth@csb!PN}%
- \unless\if@nameauth@LongIdxDebug
- \csundef{\@nameauth@csb!PRE}%
- \csundef{\@nameauth@csb!TAG}%
- \fi
- \IndexName[#1]{#2}[#3]%
- \fi
- }%
+ \if@nameauth@SkipIndex
+ \PackageWarning{nameauth}
+ {\string\SkipIndex precedes \string\ShowIdxPageref; check}%
+ \unless\if@nameauth@OldReset
+ \@nameauth@SkipIndexfalse%
+ \fi
+ \fi
% \end{macrocode}
-% Non-Western names, obsolete syntax.
+% Start a local scope to isolate any changes and redefine
+% \cmd{\NameauthIndex} (the index macro hook) to print
+% an entry in the text.
+%
% \begin{macrocode}
- {%
- \unless\if@nameauth@IdxDebug
- \@nameauth@csbc%
- \else
- \csundef{\@nameauth@csbc!PN}%
- \unless\if@nameauth@LongIdxDebug
- \csundef{\@nameauth@csbc!PRE}%
- \csundef{\@nameauth@csbc!TAG}%
- \fi
- \IndexName[#1]{#2}[#3]%
- \fi
- }%
+ \begingroup%
+ \def\NameauthIndex##1{##1}%
+ \@nameauth@DoIndextrue%
% \end{macrocode}
-% Western names.
+% We locally delete any tag and xref control sequences as needed.
+% They will be restored when the scope ends. If \cmd{\ShowIdxPageref}
+% set \cmd{\@nameauth@LongIdxDebugtrue} we produce a full index entry
+% that shows all the tags and the ``actual'' character as well as the
+% name. Otherwise we produce a short index entry that shows only the name.
+%
% \begin{macrocode}
- {%
- \unless\if@nameauth@IdxDebug
- \@nameauth@csab%
- \else
- \csundef{\@nameauth@csab!PN}%
- \unless\if@nameauth@LongIdxDebug
- \csundef{\@nameauth@csab!PRE}%
- \csundef{\@nameauth@csab!TAG}%
- \fi
- \IndexName[#1]{#2}[#3]%
- \fi
- }%
+ \@nameauth@Choice{}{}{}%
+ \csundef{\NameauthPattern!PN}%
+ \unless\if@nameauth@LongIdxDebug
+ \csundef{\NameauthPattern!PRE}%
+ \csundef{\NameauthPattern!TAG}%
+ \fi
+ \IndexName[#1]{#2}[#3]%
% \end{macrocode}
% We close the scope and reset the flags.
+%
% \begin{macrocode}
\endgroup%
- \global\@nameauth@IdxDebugfalse%
\global\@nameauth@LongIdxDebugfalse%
}
% \end{macrocode}
% \end{macro}
-% \newpage
%
-% \noindent{\normalsize\bfseries Core Name Engine}
+% \subsubsection{Core Name Engine}
+%
+% \subsubsection*{\hfil Argument Processing Layer}
+%
% \begin{macro}{\@nameauth@Name}
% \changes{1.5}{2013/02/22}{Reversing/caps}
% \changes{2.0}{2015/11/11}{Trim spaces; fix tags}
@@ -6878,12 +11089,19 @@ and version 1.3 or later is part of all distributions of LaTeX version
% \changes{3.0}{2016/10/26}{Redesigned}
% \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.
+% \Name*[Marc van]{Dongen} provided the original basic structure.
+% Parsing, indexing, and formatting are more modularized than
+% in earlier versions.
+%
% \begin{macrocode}
\newcommandx*\@nameauth@Name[3][1=\@empty, 3=\@empty]
{%
% \end{macrocode}
-% Both \cmd{\@nameauth@Name} and \cmd{\AKA} engage the lock below, preventing a stack overflow. Tell the formatting mechanism that it is being called from \cmd{\@nameauth@Name}.
+% Both \cmd{\@nameauth@Name} and \cmd{\AKA} engage the lock below,
+% preventing a stack overflow. Tell the formatting mechanism that
+% it is being called from
+% \cmd{\@nameauth@Name}.
+%
% \begin{macrocode}
\if@nameauth@BigLock \@nameauth@Locktrue\fi
\unless\if@nameauth@Lock
@@ -6891,10 +11109,16 @@ and version 1.3 or later is part of all distributions of LaTeX version
\@nameauth@InNametrue%
% \end{macrocode}
% Test for malformed input.
+%
% \begin{macrocode}
\@nameauth@Error{#2}{macro \string\@nameauth@name}%
% \end{macrocode}
-% 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@JustIndexfalse} and were done. Now, however, the default is a global reset to avoid undocumented behavior.
+% 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@JustIndexfalse}
+% and were done. Now, however, the default is a global reset to avoid
+% undocumented behavior.
+%
% \begin{macrocode}
\if@nameauth@JustIndex
\IndexName[#1]{#2}[#3]%
@@ -6913,10 +11137,14 @@ and version 1.3 or later is part of all distributions of LaTeX version
\fi
\else
% \end{macrocode}
-% Create or delete name cseq if directed, with deletion override. Ensure that names are printed in horizontal mode. Wrap the name with two index entries in case a page break occurs between name elements.
+% Create or delete name pattern if directed. Deletion has priority
+% because it occurs after creation. Ensure that names are printed
+% in horizontal mode. Wrap the name with two index entries in case
+% a page break occurs between them.
+%
% \begin{macrocode}
\if@nameauth@Subvert \SubvertName[#1]{#2}[#3]\fi
- \if@nameauth@Forget \ForgetName[#1]{#2}[#3]\fi
+ \if@nameauth@Forget \ForgetName[#1]{#2}[#3]\fi
\leavevmode\hbox{}%
\unless\if@nameauth@SkipIndex \IndexName[#1]{#2}[#3]\fi
\if@nameauth@MainFormat
@@ -6926,14 +11154,18 @@ and version 1.3 or later is part of all distributions of LaTeX version
\fi
\unless\if@nameauth@SkipIndex \IndexName[#1]{#2}[#3]\fi
% \end{macrocode}
-% Reset all the ``per name'' Boolean values after printing a name. The default is global.
+% Reset all the ``per name'' Boolean values after printing a name.
+% The default is global.
+%
% \begin{macrocode}
\@nameauth@Flags%
\fi
\@nameauth@Lockfalse%
\@nameauth@InNamefalse%
% \end{macrocode}
-% Close the ``locked'' branch and complete the full stop detection and removal. This conditional statement must be on one line.
+% Close the ``locked'' branch and complete the full stop detection
+% and removal.
+%
% \begin{macrocode}
\fi
\if@nameauth@Punct\expandafter\@nameauth@CheckDot\fi
@@ -6941,20 +11173,29 @@ and version 1.3 or later is part of all distributions of LaTeX version
% \end{macrocode}
% \end{macro}
%
-% \noindent{\normalsize\bfseries Core Name Engine: Syntactic Element Layer}
+% \subsubsection*{\hfil Syntactic Element Layer}
+%
% \begin{macro}{\@nameauth@Parse}
% \changes{3.0}{2016/10/26}{Added}
% \changes{3.1}{2017/01/13}{New workflow, caps}
-% \changes{3.2}{2017/03/22}{Fix alt. format, affixes, use \cmd{\MakeUppercase}}
-% \changes{3.5}{2020/11/23}{Global token regs, optimize logic, fix namespace}
-% 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@Name} and \cmd{\AKA} call this parser, which only works in a locked state.
+% \changes{3.2}{2017/03/22}{Fix alt. format, affixes,
+% use \cmd{\MakeUppercase}}
+% \changes{3.5}{2020/11/23}{Global token regs, optimize logic,
+% fix namespace}
+% 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@Name} and \cmd{\AKA} call this parser, which only
+% works in a locked state.
+%
% \begin{macrocode}
\newcommand\@nameauth@Parse[4]
{%
\if@nameauth@BigLock \@nameauth@Lockfalse\fi
\if@nameauth@Lock
% \end{macrocode}
-% Make token register copies of the current name args to be available for the hook macros.
+% Make token register copies of the current name args
+% to be available for the hook macros.
+%
% \begin{macrocode}
\if@nameauth@OldToks
\@nameauth@toksa\expandafter{#1}%
@@ -6966,33 +11207,43 @@ and version 1.3 or later is part of all distributions of LaTeX version
\global\@nameauth@toksc\expandafter{#3}%
\fi
% \end{macrocode}
-% If global caps. reversing, and commas are true, set the per-name flags true.
+% If global caps. reversing, and commas are true,
+% set the per-name flags true.
+%
% \begin{macrocode}
\if@nameauth@AllCaps \@nameauth@AllThistrue\fi
\if@nameauth@RevAll \@nameauth@RevThistrue\fi
\if@nameauth@RevAllComma \@nameauth@RevThisCommatrue\fi
% \end{macrocode}
-% Now we enter a local scope where we can use simple control strings without
-% needing to worry about collisions. We process and load the arguments into the appropriate macros.
+% Now we enter a local scope where we can use simple control
+% strings without needing to worry about collisions. We process
+% and load the arguments into the appropriate macros.
+%
% \begin{macrocode}
\begingroup%
\def\@nameauth@InParser{}%
\@nameauth@LoadArgs{#1}{#2}{#3}%
% \end{macrocode}
-% Copy the protected control sequences to local, unprotected ones for backward compatibility and readability.
+% Copy the protected control sequences to local,
+% unprotected ones.
+%
% \begin{macrocode}
\let\arga\@nameauth@A%
\let\rootb\@nameauth@B%
\let\suffb\@nameauth@SB%
\let\argc\@nameauth@C%
% \end{macrocode}
-% Capitalization on demand in the body text if not in alternate formatting.
+% Capitalization on demand in the body text
+% if not in alternate formatting.
+%
% \begin{macrocode}
\if@nameauth@DoCaps
\@nameauth@CapArgs{#1}{#2}{#3}%
\fi
% \end{macrocode}
-% We capitalize the entire surname when desired; different from above and overrides it.
+% We capitalize the entire surname when desired;
+% different from above and overrides it.
+%
% \begin{macrocode}
\if@nameauth@AllThis
\protected@edef\rootb%
@@ -7000,16 +11251,21 @@ and version 1.3 or later is part of all distributions of LaTeX version
\fi
% \end{macrocode}
% Use non-breaking spaces and commas as desired.
+%
% \begin{macrocode}
\@nameauth@AddPunct%
% \end{macrocode}
-% 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.
+% 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 optional arguments.
+%
% \begin{macrocode}
\let\SNN\rootb%
- \@nameauth@Choice%
+ \@nameauth@Choice
% \end{macrocode}
% Non-Western names, current syntax.
% We test \cmd{\argc} and \cmd{\suffb} as needed.
+%
% \begin{macrocode}
{%
\ifx\argc\@empty
@@ -7022,6 +11278,7 @@ and version 1.3 or later is part of all distributions of LaTeX version
}%
% \end{macrocode}
% Non-Western names, obsolete syntax. Here \cmd{\argc} is significant.
+%
% \begin{macrocode}
{%
\let\FNN\argc%
@@ -7030,7 +11287,9 @@ and version 1.3 or later is part of all distributions of LaTeX version
}%
% \end{macrocode}
% Western names.
-% We test for \cmd{\argc} and swap it for \cmd{\arga} and account for \cmd{\suffb}.
+% We test for \cmd{\argc} and swap it for \cmd{\arga} and
+% account for \cmd{\suffb}.
+%
% \begin{macrocode}
{%
\ifx\argc\@empty
@@ -7049,6 +11308,7 @@ and version 1.3 or later is part of all distributions of LaTeX version
}%
% \end{macrocode}
% We end the local group and reset the flags for name forms here.
+%
% \begin{macrocode}
\endgroup%
\if@nameauth@OldReset
@@ -7065,12 +11325,15 @@ and version 1.3 or later is part of all distributions of LaTeX version
% \end{macrocode}
% \end{macro}
%
-% \noindent{\normalsize\bfseries Core Name Engine: Name Display Layer}
+% \subsubsection*{\hfil Name Display Layer}
+%
% \begin{macro}{\@nameauth@NonWest}
% \changes{3.0}{2016/10/26}{Added}
% \changes{3.02}{2016/11/01}{Restrict \cmd{\ForceFN}}
% \changes{3.3}{2020/02/20}{global flag reset}
-% Arrange forms of non-Western names. We inherit macros from the parser and only use this macro in the local scope of the parser.
+% Arrange forms of non-Western names. We inherit macros from
+% the parser and only use this macro in the local scope of the parser.
+%
% \begin{macrocode}
\newcommand*\@nameauth@NonWest[1]
{%
@@ -7105,21 +11368,25 @@ and version 1.3 or later is part of all distributions of LaTeX version
% \begin{macro}{\@nameauth@West}
% \changes{3.0}{2016/10/26}{Added}
% \changes{3.3}{2020/02/20}{global flag reset}
-% Arrange forms of Western names and ``non-native'' Eastern names. We inherit macros from the parser and only use this macro in the local scope of the parser.
+% \changes{3.7}{2023/02/03}{always define local macros}
+% Arrange forms of Western names and ``non-native'' Eastern names.
+% We inherit macros from the parser and only use this macro in the
+% local scope of the parser.
+%
% \begin{macrocode}
\newcommand*\@nameauth@West[1]
{%
\ifdefined\@nameauth@InParser
\@nameauth@Form{#1}%
+ \edef\RevSpace{,\SpaceW}%
\if@nameauth@FullName
\if@nameauth@RevThis
- \@nameauth@Hook{\SNN\SpaceX\FNN}%
+ \@nameauth@Hook{\SNN\SpaceW\FNN}%
\else
\if@nameauth@RevThisComma
- \edef\RevSpace{,\SpaceX}%
\@nameauth@Hook{\SNN\RevSpace\FNN}%
\else
- \@nameauth@Hook{\FNN\SpaceX\SNN}%
+ \@nameauth@Hook{\FNN\SpaceW\SNN}%
\fi
\fi
\else
@@ -7136,32 +11403,43 @@ and version 1.3 or later is part of all distributions of LaTeX version
%
% \begin{macro}{\@nameauth@Form}
% \changes{3.5}{2020/11/23}{Added}
-% Set up the flags per the formatting rules for first, subsequent, long, and short uses. We only use this macro in the local scope of the parser.
+% Set up the flags per the formatting rules for first, subsequent, long,
+% and short uses. We only use this macro in the local scope of the parser.
+%
% \begin{macrocode}
\newcommand*\@nameauth@Form[1]
{%
\ifdefined\@nameauth@InParser
% \end{macrocode}
-% If the name does not exist yet or if the \texttt{alwaysformat} option is used, force first-use formatting, force a long name, and inhibit a short name.
+% If the name does not exist yet or if the \texttt{alwaysformat} option
+% is used, force first-use formatting, force a long name,
+% and inhibit a short name.
+%
% \begin{macrocode}
\unless\ifcsname#1\endcsname
\@nameauth@FirstFormattrue%
\@nameauth@FullNametrue%
\@nameauth@FirstNamefalse%
\else
- \if@nameauth@AlwaysFormat \@nameauth@FirstFormattrue\fi
+ \if@nameauth@AlwaysFormat\@nameauth@FirstFormattrue\fi
\fi
% \end{macrocode}
-% If we are not in \cmd{\AKA}, if a short name form is desired, inhibit a long form.
+% If we are not in \cmd{\AKA}, if a short name form is desired,
+% inhibit a long form.
+%
% \begin{macrocode}
\unless\if@nameauth@InAKA
- \if@nameauth@FirstName \@nameauth@FullNamefalse\fi
+ \if@nameauth@FirstName\@nameauth@FullNamefalse\fi
\else
% \end{macrocode}
-% If we are in \cmd{\AKA} use special formatting rules. \cmd{\AKA*} acts like \cmd{\FName}, while \cmd{\AKA} acts like \cmd{\Name*}. Both prefer using the subsequent-use hooks unless the \texttt{formatAKA} option or the \texttt{alwaysformat} option are used.
+% If we are in \cmd{\AKA} use special formatting rules. \cmd{\AKA*}
+% acts like \cmd{\FName}, while \cmd{\AKA} acts like \cmd{\Name*}.
+% Both prefer using the subsequent-use hooks unless the \texttt{formatAKA}
+% option or the \texttt{alwaysformat} option are used.
+%
% \begin{macrocode}
\if@nameauth@AltAKA
- \if@nameauth@OldAKA \@nameauth@EastFNtrue\fi
+ \if@nameauth@OldAKA\@nameauth@EastFNtrue\fi
\@nameauth@FullNamefalse%
\@nameauth@FirstNametrue%
\else
@@ -7179,19 +11457,26 @@ and version 1.3 or later is part of all distributions of LaTeX version
% \end{macrocode}
% \end{macro}
%
-% \noindent{\normalsize\bfseries Core Name Engine: Format Hook Dispatcher}
+% \subsubsection*{\hfil Format Hook Dispatcher}
+%
% \begin{macro}{\@nameauth@Hook}
% \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}
% \changes{3.5}{2020/11/23} {Fix namespace}
-% Boolean flags control which hook is called (first/subsequent use, name type). We only use this macro in the local scope of the parser.
+% Boolean flags control which hook is called (first/subsequent use,
+% name type). We only use this macro in the local scope of the parser.
+%
% \begin{macrocode}
\newcommand*\@nameauth@Hook[1]
{%
\ifdefined\@nameauth@InParser
% \end{macrocode}
-% We tell the formatting hooks that they are in the hook dispatcher to enable alternate formatting. We test the printed name form to see if it has a trailing full stop.
+% We tell the formatting hooks that they are in the hook dispatcher
+% to enable alternate formatting. We test the printed name form to see
+% if it has a trailing full stop. The flag \texttt{\textbackslash^^A
+% if@nameauth@InHook} will reset outside of the local scope in
+% \cmd{\@nameauth@Parse}.
% \begin{macrocode}
\@nameauth@InHooktrue%
\protected@edef\test{#1}%
@@ -7199,6 +11484,7 @@ and version 1.3 or later is part of all distributions of LaTeX version
\if@nameauth@MainFormat
% \end{macrocode}
% We use the formatting hooks for the main-matter system.
+%
% \begin{macrocode}
\if@nameauth@FirstFormat
\bgroup\NamesFormat{#1}\egroup%
@@ -7208,6 +11494,7 @@ and version 1.3 or later is part of all distributions of LaTeX version
\else
% \end{macrocode}
% We use the formatting hooks for the front-matter system.
+%
% \begin{macrocode}
\if@nameauth@FirstFormat
\bgroup\FrontNamesFormat{#1}\egroup%
@@ -7215,28 +11502,32 @@ and version 1.3 or later is part of all distributions of LaTeX version
\bgroup\FrontNameHook{#1}\egroup%
\fi
\fi
-% \end{macrocode}
-% We tell the formatting hooks that they are not in the hook dispatcher.
-% \begin{macrocode}
- \@nameauth@InHookfalse%
\fi
}
% \end{macrocode}
% \end{macro}
%
-% \noindent{\normalsize\bfseries Indexing Internals: Entry Formatter}
+% \subsubsection{Indexing}
+%
% \begin{macro}{\@nameauth@Index}
% \changes{0.94}{2012/02/15}{Added}
% \changes{2.0}{2015/11/11}{New tagging}
% \changes{3.3}{2020/02/20}{Support hyperref}
% \changes{3.5}{2020/11/23}{Fix namespace}
-% This is the core index mechanism. If the indexing flag is true, create an index entry, otherwise do nothing. Add any tags automatically if they exist.
+% This is the core index mechanism. If the indexing flag is true,
+% create an index entry, otherwise do nothing. Add any tags
+% automatically if they exist.
+%
% \begin{macrocode}
\newcommand*\@nameauth@Index[2]
{%
\if@nameauth@DoIndex
% \end{macrocode}
-% If an index tag exists for the entry, get it. Also create a short version of the tag without any vertical bar or trailing macro. If we are creating a cross-reference, use the short tag, otherwise use the long tag.
+% If an index tag exists for the entry, get it. Also create
+% a short version of the tag without any vertical bar or trailing macro.
+% If we are creating a cross-reference, use the short tag, otherwise
+% use the long tag.
+%
% \begin{macrocode}
\ifcsname#1!TAG\endcsname
\protected@edef\@nameauth@Tag{\csname#1!TAG\endcsname}%
@@ -7244,31 +11535,34 @@ and version 1.3 or later is part of all distributions of LaTeX version
\expandafter\@nameauth@TrimTag\expandafter{\@nameauth@Tag}}%
% \end{macrocode}
% Create entries with a sorting tag and an info tag.
+%
% \begin{macrocode}
\ifcsname#1!PRE\endcsname
\protected@edef\@nameauth@Pre{\csname#1!PRE\endcsname}%
\if@nameauth@Xref
- \protected@edef\@nameauth@IdxEntry%
+ \protected@edef\@nameauth@IdxEntry
{\@nameauth@Pre#2\@nameauth@ShortTag}%
\else
- \protected@edef\@nameauth@IdxEntry%
+ \protected@edef\@nameauth@IdxEntry
{\@nameauth@Pre#2\@nameauth@Tag}%
\fi
\else
% \end{macrocode}
% Create entries with just an info tag.
+%
% \begin{macrocode}
\if@nameauth@Xref
- \protected@edef\@nameauth@IdxEntry%
+ \protected@edef\@nameauth@IdxEntry
{#2\@nameauth@ShortTag}%
\else
- \protected@edef\@nameauth@IdxEntry%
+ \protected@edef\@nameauth@IdxEntry
{#2\@nameauth@Tag}%
\fi
\fi
\else
% \end{macrocode}
% Create entries with just a sorting tag.
+%
% \begin{macrocode}
\ifcsname#1!PRE\endcsname
\protected@edef\@nameauth@Pre{\csname#1!PRE\endcsname}%
@@ -7279,6 +11573,7 @@ and version 1.3 or later is part of all distributions of LaTeX version
\fi
% \end{macrocode}
% Create entries with no tag.
+%
% \begin{macrocode}
\expandafter\NameauthIndex\expandafter{\@nameauth@IdxEntry}%
\fi
@@ -7286,11 +11581,44 @@ and version 1.3 or later is part of all distributions of LaTeX version
% \end{macrocode}
% \end{macro}
%
-% \subsection[Prefix Macros]{User Interface Macros: Prefix Macros}
-% \noindent{\normalsize\bfseries Syntactic Formatting\,---\,Capitalization}
+% \newpage
+%
+% \subsection[User Macros: Prefixes]{For Users: Prefix Macros}
+% \label{sec:PrefixMacs}
+%
+% All prefix macros are meant to precede a particular name and only
+% affect a particular name.
+%
+% \subsubsection[Syntax]{Name Syntax}
+%
+% \subsubsection*{\hfil Commas Before Affixes}
+%
+% \begin{macro}{\ShowComma}
+% \changes{1.4}{2012/07/24}{Added}
+% Put comma between name and suffix one time.
+%
+% \begin{macrocode}
+\newcommand*\ShowComma{\@nameauth@ShowCommatrue}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\NoComma}
+% \changes{2.6}{2016/09/19}{Added}
+% Remove comma between name and suffix one time
+% (with \texttt{comma} option).
+%
+% \begin{macrocode}
+\newcommand*\NoComma{\@nameauth@NoCommatrue}
+% \end{macrocode}
+% \end{macro}
+%
+% \subsubsection*{\hfil Capitalization}
+%
% \begin{macro}{\CapThis}
% \changes{0.94}{2012/02/15}{Added}
-% Tells the root capping macro to cap the first character of all name elements.
+% Tells the root capping macro to cap the first character
+% of all name elements.
+%
% \begin{macrocode}
\newcommand*\CapThis{\@nameauth@DoCapstrue}
% \end{macrocode}
@@ -7298,27 +11626,171 @@ and version 1.3 or later is part of all distributions of LaTeX version
%
% \begin{macro}{\AccentCapThis}
% \changes{2.1}{2015/11/24}{Added}
-% Overrides the automatic test for active Unicode characters. This is a fall-back in case the automatic test for active Unicode characters fails.
+% Overrides the automatic test for active Unicode characters.
+% This is a fall-back in case the automatic test for active
+% Unicode characters does not work.
+%
% \begin{macrocode}
\newcommand*\AccentCapThis
-{%
- \@nameauth@Accenttrue%
- \@nameauth@DoCapstrue%
-}
+ {\@nameauth@Accenttrue\@nameauth@DoCapstrue}
% \end{macrocode}
% \end{macro}
%
% \begin{macro}{\CapName}
% \changes{1.5}{2013/02/22}{Added}
-% Capitalize entire required name. Overrides \cmd{\CapThis} for surnames.
+% Capitalize entire \meta{SNN}. Overrides \cmd{\CapThis} for surnames.
+%
% \begin{macrocode}
\newcommand*\CapName{\@nameauth@AllThistrue}
% \end{macrocode}
% \end{macro}
%
+% \subsubsection*{\hfil Reversing}
+%
+% \begin{macro}{\RevName}
+% \changes{1.5}{2013/02/22}{Added}
+% Reverse name order.
+%
+% \begin{macrocode}
+\newcommand*\RevName{\@nameauth@RevThistrue}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\ForceFN}
+% \changes{3.0}{2016/10/26}{Added}
+% 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}.
+%
+% \begin{macrocode}
+\newcommand*\ForceFN{\@nameauth@EastFNtrue}
+% \end{macrocode}
+% \end{macro}
+%
+% \subsubsection*{\hfil Reversing with Commas}
+%
+% \begin{macro}{\RevComma}
+% \changes{1.5}{2013/02/22}{Added}
+% Last name, comma, first name.
+%
+% \begin{macrocode}
+\newcommand*\RevComma{\@nameauth@RevThisCommatrue}
+% \end{macrocode}
+% \end{macro}
+%
+% \subsubsection*{\hfil Affixes and Breaking}
+%
+% \begin{macro}{\DropAffix}
+% \changes{3.0}{2016/10/26}{Added}
+% Suppress the affix in a long Western name.
+%
+% \begin{macrocode}
+\newcommand*\DropAffix{\@nameauth@ShortSNNtrue}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\KeepAffix}
+% \changes{1.9}{2015/07/09}{Added}
+% Trigger a name-suffix pair to be separated by
+% a non-breaking space.
+%
+% \begin{macrocode}
+\newcommand*\KeepAffix{\@nameauth@NBSPtrue}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\KeepName}
+% \changes{3.1}{2017/01/13}{Added}
+% Use non-breaking spaces between name syntactic forms.
+%
+% \begin{macrocode}
+\newcommand*\KeepName
+ {\@nameauth@NBSPtrue\@nameauth@NBSPXtrue}
+% \end{macrocode}
+% \end{macro}
+%
+% \subsubsection{Indexing}
+%
+% \begin{macro}{\SkipIndex}
+% \changes{3.1}{2017/01/13}{Added}
+% Turn off the next instance of indexing in \cmd{\Name},
+% \cmd{\FName}, and starred forms.
+%
+% \begin{macrocode}
+\newcommand*\SkipIndex{\@nameauth@SkipIndextrue}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\JustIndex}
+% \changes{3.1}{2017/01/13}{Added}
+% Makes the next call to \cmd{\Name}, \cmd{\FName},
+% and starred forms act like \cmd{\IndexName}.
+% Overrides \cmd{\SkipIndex}.
+%
+% \begin{macrocode}
+\newcommand*\JustIndex{\@nameauth@JustIndextrue}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\SeeAlso}
+% \changes{3.0}{2016/10/26}{Added}
+% 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*}.
+%
+% \begin{macrocode}
+\newcommand*\SeeAlso{\@nameauth@SeeAlsotrue}
+% \end{macrocode}
+% \end{macro}
+%
+% \subsubsection[Format/Decisions]{Formatting and Name Decisions}
+%
+% \begin{macro}{\ForceName}
+% \changes{3.1}{2017/01/13}{Added}
+% Set \cmd{\@nameauth@FirstFormat} to be true even for
+% subsequent name uses. Makes the core name engine use
+% \cmd{\NamesFormat}. Works for one name only.
+%
+% \begin{macrocode}
+\newcommand*\ForceName{\@nameauth@FirstFormattrue}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\ForgetThis}
+% \changes{3.1}{2017/01/13}{Added}
+% Have the naming engine \cmd{\@nameauth@Name}
+% call \cmd{\ForgetName} internally.
+%
+% \begin{macrocode}
+\newcommand*\ForgetThis{\@nameauth@Forgettrue}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\SubvertThis}
+% \changes{3.1}{2017/01/13}{Added}
+% Have the naming engine \cmd{\@nameauth@Name}
+% call \cmd{\SubvertName} internally.
+%
+% \begin{macrocode}
+\newcommand*\SubvertThis{\@nameauth@Subverttrue}
+% \end{macrocode}
+% \end{macro}
+%
+% \subsection[User Macros: Helpers]{For Users: Helper Macros}
+% \label{sec:Helpers}
+%
+% Helper macros do not need to precede a particular name and their effects
+% endure for multiple names. They tend to affect an entire scope. That is
+% why they usually come in pairs.
+%
+% \subsubsection[Syntax]{Name Syntax}
+%
+% \subsubsection*{\hfil Capitalization}
+%
% \begin{macro}{\AllCapsInactive}
% Turn off global surname capitalization.
% \changes{1.5}{2013/02/22}{Added}
+%
% \begin{macrocode}
\newcommand*\AllCapsInactive{\@nameauth@AllCapsfalse}
% \end{macrocode}
@@ -7326,76 +11798,145 @@ and version 1.3 or later is part of all distributions of LaTeX version
%
% \begin{macro}{\AllCapsActive}
% \changes{1.5}{2013/02/22}{Added}
-% Turn on global surname capitalization. Activates \cmd{\CapName} for every name.
+% Turn on global surname capitalization.
+% Activates \cmd{\CapName} for every name.
+%
% \begin{macrocode}
\newcommand*\AllCapsActive{\@nameauth@AllCapstrue}
% \end{macrocode}
% \end{macro}
%
-% \noindent{\normalsize\bfseries Syntactic Formatting\,---\,Reversing}
-% \begin{macro}{\RevName}
-% \changes{1.5}{2013/02/22}{Added}
-% Reverse name order.
-% \begin{macrocode}
-\newcommand*\RevName{\@nameauth@RevThistrue}
-% \end{macrocode}
-% \end{macro}
+% \subsubsection*{\hfil Reversing}
%
% \begin{macro}{\ReverseInactive}
% Turn off global name reversing.
% \changes{1.5}{2013/02/22}{Added}
+%
% \begin{macrocode}
\newcommand*\ReverseInactive{\@nameauth@RevAllfalse}
% \end{macrocode}
% \end{macro}
%
% \begin{macro}{\ReverseActive}
-% Turn on global name reversing. Activates \cmd{\RevName} for every name.
% \changes{1.5}{2013/02/22}{Added}
+% Turn on global name reversing.
+% Activates \cmd{\RevName} for every name.
+%
% \begin{macrocode}
\newcommand*\ReverseActive{\@nameauth@RevAlltrue}
% \end{macrocode}
% \end{macro}
%
-% \begin{macro}{\ForceFN}
-% 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}
+% \subsubsection*{\hfil Reversing with Commas}
+%
+% \begin{macro}{\ReverseCommaInactive}
+% \changes{1.5}{2013/02/22}{Added}
+% Turn off global ``last-name-comma-first''.
+%
% \begin{macrocode}
-\newcommand*\ForceFN{\@nameauth@EastFNtrue}
+\newcommand*\ReverseCommaInactive{\@nameauth@RevAllCommafalse}
% \end{macrocode}
% \end{macro}
%
-% \noindent{\normalsize\bfseries Syntactic Formatting\,---\,Reversing with Commas}
-% \begin{macro}{\RevComma}
+% \begin{macro}{\ReverseCommaActive}
% \changes{1.5}{2013/02/22}{Added}
-% Last name, comma, first name.
+% Turn on global ``last-name-comma-first''.
+% Activates \cmd{\RevComma} for every name. The macro
+% \cmd{\ReverseActive} takes priority over this macro
+% due to the structure of the parser.
+%
% \begin{macrocode}
-\newcommand*\RevComma{\@nameauth@RevThisCommatrue}
+\newcommand*\ReverseCommaActive{\@nameauth@RevAllCommatrue}
% \end{macrocode}
% \end{macro}
%
-% \begin{macro}{\ReverseCommaInactive}
-% Turn off global ``last-name-comma-first''.
-% \changes{1.5}{2013/02/22}{Added}
+% \subsubsection{Indexing}
+%
+% \begin{macro}{\IndexActual}
+% \changes{2.0}{2015/11/11}{Added}
+% \changes{3.5}{2020/11/23}{Use \cmd{\def}}
+% Change the ``actual'' character from the default.
+% This allows one to use, for example,
+% |\global\IndexActual{=}| in \texttt{dtx} files.
+%
% \begin{macrocode}
-\newcommand*\ReverseCommaInactive{\@nameauth@RevAllCommafalse}
+\newcommand*\IndexActual[1]{\def\@nameauth@Actual{#1}}
% \end{macrocode}
% \end{macro}
%
-% \begin{macro}{\ReverseCommaActive}
-% Turn on global ``last-name-comma-first''. Activates \cmd{\RevComma} for every name.
-% \changes{1.5}{2013/02/22}{Added}
+% \begin{macro}{\IndexInactive}
+% \changes{0.94}{2012/02/15}{Added}
+% Turn off global indexing of names.
+%
% \begin{macrocode}
-\newcommand*\ReverseCommaActive{\@nameauth@RevAllCommatrue}
+\newcommand*\IndexInactive{\@nameauth@DoIndexfalse}
% \end{macrocode}
% \end{macro}
-% \newpage
%
-% \noindent{\normalsize\bfseries Alternate Formatting}
-% \phantomsection\label{page:Hooks}
+% \begin{macro}{\IndexActive}
+% \changes{0.94}{2012/02/15}{Added}
+% Turn on global indexing of names.
+%
+% \begin{macrocode}
+\newcommand*\IndexActive{\@nameauth@DoIndextrue}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\IndexWarnVerbose}
+% \changes{3.7}{2023/02/03}{Added}
+% Turn on verbose warnings for indexing.
+%
+% \begin{macrocode}
+\newcommand*\IndexWarnVerbose{\@nameauth@Verbosetrue}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\IndexWarnTerse}
+% \changes{3.7}{2023/02/03}{Added}
+% Turn off verbose warnings for indexing.
+%
+% \begin{macrocode}
+\newcommand*\IndexWarnTerse{\@nameauth@Verbosefalse}
+% \end{macrocode}
+% \end{macro}
+%
+% \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 the
+% index contains one of the naming macros. This macro is deliberately
+% local, so one can use scoping to isolate its effects.
+%
+% \begin{macrocode}
+\newcommand*\IndexProtect
+ {\@nameauth@DoIndexfalse\@nameauth@BigLocktrue}
+% \end{macrocode}
+% \end{macro}
+%
+% \subsubsection{Formatting}
+%
+% \begin{macro}{\NamesInactive}
+% Switch to the front-matter name system.
+%
+% \begin{macrocode}
+\newcommand*\NamesInactive{\@nameauth@MainFormatfalse}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\NamesActive}
+% Switch to the main-matter name system.
+%
+% \begin{macrocode}
+\newcommand*\NamesActive{\@nameauth@MainFormattrue}
+% \end{macrocode}
+% \end{macro}
+%
+% \subsubsection{Alternate Formatting}
+%
% \begin{macro}{\AltFormatActive}
% \changes{3.1}{2017/01/13}{Added}
% Turn on alternate formatting, engage the formatting macros.
+%
% \begin{macrocode}
\newcommand*\AltFormatActive
{%
@@ -7408,6 +11949,7 @@ and version 1.3 or later is part of all distributions of LaTeX version
% \begin{macro}{\AltFormatActive*}
% \changes{3.1}{2017/01/13}{Added}
% Turn on alternate formatting, disengage the formatting macros.
+%
% \begin{macrocode}
\WithSuffix{\newcommand*}\AltFormatActive*
{%
@@ -7420,25 +11962,22 @@ and version 1.3 or later is part of all distributions of LaTeX version
% \begin{macro}{\AltFormatInactive}
% Turn off alternate formatting altogether.
% \changes{3.1}{2017/01/13}{Added}
+%
% \begin{macrocode}
\newcommand*\AltFormatInactive
-{%
- \global\@nameauth@AltFormatfalse%
- \global\@nameauth@DoAltfalse%
-}
+ {\global\@nameauth@AltFormatfalse\global\@nameauth@DoAltfalse}
% \end{macrocode}
% \end{macro}
%
% \begin{macro}{\AltOn}
% Locally turn on alternate formatting.
% \changes{3.1}{2017/01/13}{Added}
+%
% \begin{macrocode}
\newcommand*\AltOn
{%
\if@nameauth@InHook
- \if@nameauth@AltFormat
- \@nameauth@DoAlttrue%
- \fi
+ \if@nameauth@AltFormat\@nameauth@DoAlttrue\fi
\fi
}
% \end{macrocode}
@@ -7447,13 +11986,12 @@ and version 1.3 or later is part of all distributions of LaTeX version
% \begin{macro}{\AltOff}
% Locally turn off alternate formatting.
% \changes{3.1}{2017/01/13}{Added}
+%
% \begin{macrocode}
\newcommand*\AltOff
{%
\if@nameauth@InHook
- \if@nameauth@AltFormat
- \@nameauth@DoAltfalse%
- \fi
+ \if@nameauth@AltFormat\@nameauth@DoAltfalse\fi
\fi
}
% \end{macrocode}
@@ -7463,15 +12001,12 @@ and version 1.3 or later is part of all distributions of LaTeX version
% \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]
{%
\if@nameauth@InHook
- \if@nameauth@DoCaps
- \MakeUppercase{#1}%
- \else
- #1%
- \fi
+ \if@nameauth@DoCaps\MakeUppercase{#1}\else#1\fi
\else
#1%
\fi
@@ -7482,15 +12017,10 @@ and version 1.3 or later is part of all distributions of LaTeX version
% \begin{macro}{\textSC}
% \changes{3.1}{2017/01/13}{Added}
% Alternate formatting macro: small caps when active.
+%
% \begin{macrocode}
\newcommand*\textSC[1]
-{%
- \if@nameauth@DoAlt
- \textsc{#1}%
- \else
- #1%
- \fi
-}
+ {\if@nameauth@DoAlt\textsc{#1}\else#1\fi}
% \end{macrocode}
% \end{macro}
%
@@ -7498,136 +12028,39 @@ and version 1.3 or later is part of all distributions of LaTeX version
% \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]
-{%
- \if@nameauth@DoAlt
- \MakeUppercase{#1}%
- \else
- #1%
- \fi
-}
+ {\if@nameauth@DoAlt\MakeUppercase{#1}\else#1\fi}
% \end{macrocode}
% \end{macro}
%
% \begin{macro}{\textIT}
% \changes{3.1}{2017/01/13}{Added}
% Alternate formatting macro: italic when active.
+%
% \begin{macrocode}
\newcommand*\textIT[1]
-{%
- \if@nameauth@DoAlt
- \textit{#1}%
- \else
- #1%
- \fi
-}
+ {\if@nameauth@DoAlt\textit{#1}\else#1\fi}
% \end{macrocode}
% \end{macro}
%
% \begin{macro}{\textBF}
% \changes{3.1}{2017/01/13}{Added}
% Alternate formatting macro: boldface when active.
-% \begin{macrocode}
-\newcommand*\textBF[1]
-{%
- \if@nameauth@DoAlt
- \textbf{#1}%
- \else
- #1%
- \fi
-}
-% \end{macrocode}
-% \end{macro}
-%
-% \noindent{\normalsize\bfseries Syntactic Formatting\,---\,Affixes}
-% \begin{macro}{\ShowComma}
-% \changes{1.4}{2012/07/24}{Added}
-% Put comma between name and suffix one time.
-% \begin{macrocode}
-\newcommand*\ShowComma{\@nameauth@ShowCommatrue}
-% \end{macrocode}
-% \end{macro}
-%
-% \begin{macro}{\NoComma}
-% \changes{2.6}{2016/09/19}{Added}
-% Remove comma between name and suffix one time (with \texttt{comma} option).
-% \begin{macrocode}
-\newcommand*\NoComma{\@nameauth@NoCommatrue}
-% \end{macrocode}
-% \end{macro}
-%
-% \begin{macro}{\DropAffix}
-% \changes{3.0}{2016/10/26}{Added}
-% Suppress the affix in a long Western name.
-% \begin{macrocode}
-\newcommand*\DropAffix{\@nameauth@ShortSNNtrue}
-% \end{macrocode}
-% \end{macro}
-%
-% \begin{macro}{\KeepAffix}
-% \changes{1.9}{2015/07/09}{Added}
-% Trigger a name-suffix pair to be separated by a non-breaking space.
-% \begin{macrocode}
-\newcommand*\KeepAffix{\@nameauth@NBSPtrue}
-% \end{macrocode}
-% \end{macro}
-%
-% \begin{macro}{\KeepName}
-% \changes{3.1}{2017/01/13}{Added}
-% Use non-breaking spaces between name syntactic forms.
-% \begin{macrocode}
-\newcommand*\KeepName
-{%
- \@nameauth@NBSPtrue%
- \@nameauth@NBSPXtrue%
-}
-% \end{macrocode}
-% \end{macro}
-%
-% \noindent{\normalsize\bfseries Post-Processing\,---\,Main Versus Front Matter}
-% \begin{macro}{\NamesInactive}
-% Switch to the ``non-formatted'' species of names.
-% \begin{macrocode}
-\newcommand*\NamesInactive{\@nameauth@MainFormatfalse}
-% \end{macrocode}
-% \end{macro}
-%
-% \begin{macro}{\NamesActive}
-% Switch to the ``formatted'' species of names.
-% \begin{macrocode}
-\newcommand*\NamesActive{\@nameauth@MainFormattrue}
-% \end{macrocode}
-% \end{macro}
%
-% \noindent{\normalsize\bfseries Name Decisions\,---\,First/Subsequent Reference}
-% \begin{macro}{\ForgetThis}
-% \changes{3.1}{2017/01/13}{Added}
-% Have the naming engine \cmd{\@nameauth@Name} call \cmd{\ForgetName} internally.
% \begin{macrocode}
-\newcommand*\ForgetThis{\@nameauth@Forgettrue}
-% \end{macrocode}
-% \end{macro}
-%
-% \begin{macro}{\SubvertThis}
-% \changes{3.1}{2017/01/13}{Added}
-% Have the naming engine \cmd{\@nameauth@Name} call \cmd{\SubvertName} internally.
-% \begin{macrocode}
-\newcommand*\SubvertThis{\@nameauth@Subverttrue}
+\newcommand*\textBF[1]
+ {\if@nameauth@DoAlt\textbf{#1}\else#1\fi}
% \end{macrocode}
% \end{macro}
%
-% \begin{macro}{\ForceName}
-% \changes{3.1}{2017/01/13}{Added}
-% Set \cmd{\@nameauth@FirstFormat} to be true even for subsequent name uses. Works for one name only.
-% \begin{macrocode}
-\newcommand*\ForceName{\@nameauth@FirstFormattrue}
-% \end{macrocode}
-% \end{macro}
+% \subsubsection{Name Decisions}
%
% \begin{macro}{\LocalNameTest}
% \changes{3.5}{2020/11/23}{Added}
% Causes decision paths in the name decision macros to be in a local scope.
+%
% \begin{macrocode}
\newcommand*\LocalNameTest{\global\@nameauth@GlobalScopefalse}
% \end{macrocode}
@@ -7636,16 +12069,19 @@ and version 1.3 or later is part of all distributions of LaTeX version
% \begin{macro}{\GlobalNameTest}
% \changes{3.5}{2020/11/23}{Added}
% Causes decision paths in the name decision macros to have no scoping.
+%
% \begin{macrocode}
\newcommand*\GlobalNameTest{\global\@nameauth@GlobalScopetrue}
% \end{macrocode}
% \end{macro}
%
-% \noindent{\normalsize\bfseries Name Occurrence Tweaks}
% \begin{macro}{\LocalNames}
% \changes{2.3}{2016/01/05}{Added}
% \changes{2.4}{2016/03/15}{Ensure global}
-% \cmd{\LocalNames} sets |@nameauth@LocalNames| true so \cmd{\ForgetName} and \cmd{\SubvertName} do not affect both main and front matter naming systems.
+% \cmd{\LocalNames} sets |@nameauth@LocalNames| true so \cmd{\ForgetName}
+% and \cmd{\SubvertName} do not affect both main and front matter
+% name systems at once, only the current one.
+%
% \begin{macrocode}
\newcommand*\LocalNames{\global\@nameauth@LocalNamestrue}
% \end{macrocode}
@@ -7654,99 +12090,16 @@ and version 1.3 or later is part of all distributions of LaTeX version
% \begin{macro}{\GlobalNames}
% \changes{2.3}{2016/01/05}{Added}
% \changes{2.4}{2016/03/15}{Ensure global}
-% \cmd{\GlobalNames} sets |@nameauth@LocalNames| false. This restores the default behavior of \cmd{\ForgetName} and \cmd{\SubvertName}.
-% \begin{macrocode}
-\newcommand*\GlobalNames{\global\@nameauth@LocalNamesfalse}
-% \end{macrocode}
-% \end{macro}
+% \cmd{\GlobalNames} restores the default behavior of \cmd{\ForgetName}
+% and \cmd{\SubvertName}, which affect both name systems at once.
%
-% \noindent{\normalsize\bfseries Index Operations}
-% \begin{macro}{\IndexActual}
-% \changes{2.0}{2015/11/11}{Added}
-% \changes{3.5}{2020/11/23}{Use \cmd{\def}}
-% Change the ``actual'' character from the default. This allows one to use, for example, |\global\IndexActual{=}|.
-% \begin{macrocode}
-\newcommand*\IndexActual[1]{\def\@nameauth@Actual{#1}}
-% \end{macrocode}
-% \end{macro}
-%
-% \begin{macro}{\IndexInactive}
-% \changes{0.94}{2012/02/15}{Added}
-% Turn off global indexing of names.
-% \begin{macrocode}
-\newcommand*\IndexInactive{\@nameauth@DoIndexfalse}
-% \end{macrocode}
-% \end{macro}
-%
-% \begin{macro}{\IndexActive}
-% \changes{0.94}{2012/02/15}{Added}
-% Turn on global indexing of names.
-% \begin{macrocode}
-\newcommand*\IndexActive{\@nameauth@DoIndextrue}
-% \end{macrocode}
-% \end{macro}
-%
-% \begin{macro}{\SkipIndex}
-% \changes{3.1}{2017/01/13}{Added}
-% Turn off the next instance of indexing in \cmd{\Name}, \cmd{\FName}, and starred forms.
-% \begin{macrocode}
-\newcommand*\SkipIndex{\@nameauth@SkipIndextrue}
-% \end{macrocode}
-% \end{macro}
-%
-% \begin{macro}{\JustIndex}
-% \changes{3.1}{2017/01/13}{Added}
-% Makes the next call to \cmd{\Name}, \cmd{\FName}, and starred forms act like \cmd{\IndexName}. Overrides \cmd{\SkipIndex}.
-% \begin{macrocode}
-\newcommand*\JustIndex{\@nameauth@JustIndextrue}
-% \end{macrocode}
-% \end{macro}
-%
-% \begin{macro}{\SeeAlso}
-% \changes{3.0}{2016/10/26}{Added}
-% 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@SeeAlsotrue}
-% \end{macrocode}
-% \end{macro}
-%
-% \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@Debug}
+\newcommand*\GlobalNames{\global\@nameauth@LocalNamesfalse}
% \end{macrocode}
% \end{macro}
%
-% \begin{macro}{\ShowIdxPageref}
-% \changes{3.3}{2020/02/20}{Added}
-% \changes{3.5}{2020/11/23}{Fix namespace, use Boolean flags}
-% This displays (expanded, as printed) the index entry that will be generated, but not exactly what is in the \texttt{idx} file. This may be useful for debugging.
-% \begin{macrocode}
-\newcommand*\ShowIdxPageref
-{%
- \global\@nameauth@IdxDebugtrue%
- \global\@nameauth@LongIdxDebugtrue%
- \@nameauth@Debug%
-}
-% \end{macrocode}
-% \end{macro}
-%
-% \begin{macro}{\ShowIdxPageref*}
-% \changes{3.3}{2020/02/20}{Added}
-% \changes{3.5}{2020/11/23}{Fix namespace, use Boolean flags}
-% This displays a basic index entry with no tag. This may be useful for debugging.
-% \begin{macrocode}
-\WithSuffix{\newcommand*}\ShowIdxPageref*
-{%
- \global\@nameauth@IdxDebugtrue%
- \@nameauth@Debug%
-}
-% \end{macrocode}
-% \end{macro}
+% \subsubsection[Name Parser]{User-Accessible Name Parser}
+% \label{sec:NameParser}
%
% \begin{macro}{\NameParser}
% \changes{3.0}{2016/10/26}{Added}
@@ -7754,39 +12107,32 @@ and version 1.3 or later is part of all distributions of LaTeX version
% \changes{3.1}{2017/01/13}{Fix old syntax; add NBSP}
% \changes{3.2}{2017/03/22}{Fix alt. format, affixes}
% \changes{3.5}{2020/11/23}{Optimize logic}
-% 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. We only use this macro in the local scope of the parser.
+% Print a name form based on the current state of the
+% \textsf{nameauth} flags in the locked path. Used only
+% in the hook macros, within the local scope of \cmd{\@nameauth@Parse}.
+%
% \begin{macrocode}
\newcommand*\NameParser
{%
\if@nameauth@InHook
\let\SNN\rootb%
- \@nameauth@Choice%
+ \@nameauth@Choice
% \end{macrocode}
% Non-Western names.
% We test both \cmd{\argc} and \cmd{\suffb} as needed.
+%
% \begin{macrocode}
{%
- \ifx\argc\@empty
- \let\FNN\suffb%
- \else
- \let\FNN\argc%
- \fi
+ \ifx\argc\@empty \let\FNN\suffb \else \let\FNN\argc \fi
\ifx\FNN\@empty
\SNN%
\else
\if@nameauth@FullName
- \if@nameauth@RevThis
- \FNN\Space\SNN%
- \else
- \SNN\Space\FNN%
+ \if@nameauth@RevThis \FNN\Space\SNN \else \SNN\Space\FNN%
\fi
\else
\if@nameauth@FirstName
- \if@nameauth@EastFN
- \FNN%
- \else
- \SNN%
- \fi
+ \if@nameauth@EastFN \FNN \else \SNN \fi
\else
\SNN%
\fi
@@ -7796,22 +12142,15 @@ and version 1.3 or later is part of all distributions of LaTeX version
% \end{macrocode}
% Non-Western names, obsolete syntax.
% Using \cmd{\argc} in this path affects indexing.
+%
% \begin{macrocode}
{%
\let\FNN\argc%
\if@nameauth@FullName%
- \if@nameauth@RevThis
- \FNN\Space\SNN%
- \else
- \SNN\Space\FNN%
- \fi
+ \if@nameauth@RevThis \FNN\Space\SNN \else \SNN\Space\FNN \fi
\else
\if@nameauth@FirstName
- \if@nameauth@EastFN
- \FNN%
- \else
- \SNN%
- \fi
+ \if@nameauth@EastFN \FNN \else \SNN \fi
\else
\SNN%
\fi
@@ -7819,37 +12158,28 @@ and version 1.3 or later is part of all distributions of LaTeX version
}%
% \end{macrocode}
% Western names.
-% We test for \cmd{\argc} and swap it for \cmd{\arga}, and account for \cmd{\suffb}.
+% We test for \cmd{\argc} and swap it for \cmd{\arga},
+% and account for \cmd{\suffb}.
+%
% \begin{macrocode}
{%
- \ifx\argc\@empty
- \let\FNN\arga%
- \else
- \let\FNN\argc%
- \fi
+ \ifx\argc\@empty \let\FNN\arga \else \let\FNN\argc \fi
\unless\ifx\suffb\@empty
\def\SNN{\rootb\Space\suffb}%
- \if@nameauth@ShortSNN
- \let\SNN\rootb%
- \fi%
+ \if@nameauth@ShortSNN \let\SNN\rootb \fi
\fi
\if@nameauth@FullName
\if@nameauth@RevThis
- \SNN\SpaceX\FNN%
+ \SNN\SpaceW\FNN%
\else
\if@nameauth@RevThisComma
\SNN\RevSpace\FNN%
\else
- \FNN\SpaceX\SNN%
+ \FNN\SpaceW\SNN%
\fi
\fi
\else
- \if@nameauth@FirstName
- \FNN%
- \else
- \let\SNN\rootb%
- \SNN%
- \fi
+ \if@nameauth@FirstName \FNN \else \let\SNN\rootb \SNN \fi
\fi
}%
\fi
@@ -7857,171 +12187,567 @@ and version 1.3 or later is part of all distributions of LaTeX version
% \end{macrocode}
% \end{macro}
%
-% \noindent{\normalsize\bfseries Traditional Naming Interface}
+% \subsection[User Macros: Name Args]{For Users: Macros That Take Name Arguments}
+% \label{sec:UserInterface}
+%
+% The rest of the \textsf{nameauth} macros all take name arguments. They all
+% update \cmd{\NameauthPattern}, \texttt{\textbackslash ifNameauthWestern},
+% and \texttt{\textbackslash ifNameauthObsolete} when called. The file
+% \texttt{examples.tex} iterates through all possible argument variations of
+% these macros except the debugging macros, the non-printing arguments of
+% \cmd{\AKA}, and \cmd{\PName}. It thus tests for spurious spaces and any
+% possible bad output.
+%
+% \subsubsection{Basic Interface}
+%
% \begin{macro}{\Name}
% \cmd{\Name} calls \cmd{\NameauthName}, the interface hook.
+%
% \begin{macrocode}
\newcommand\Name{\NameauthName}
% \end{macrocode}
% \end{macro}
%
% \begin{macro}{\Name*}
-% \cmd{\Name*} sets up a long name reference and calls \cmd{\NameauthLName}, the interface hook.
+% \cmd{\Name*} sets up a long name reference and calls \cmd{\NameauthLName},
+% the interface hook.
+%
% \begin{macrocode}
\WithSuffix{\newcommand*}\Name*
-{%
- \@nameauth@FullNametrue%
- \NameauthLName%
-}
+ {\@nameauth@FullNametrue\NameauthLName}
% \end{macrocode}
% \end{macro}
%
% \begin{macro}{\FName}
% \changes{0.9}{2012/02/10}{Added}
-% \cmd{\FName} sets up a short name reference and calls \cmd{\NameauthFName}, the interface hook.
+% \cmd{\FName} sets up a short name reference and calls \cmd{\NameauthFName},
+% the interface hook.
+%
% \begin{macrocode}
\newcommand\FName
-{%
- \@nameauth@FirstNametrue%
- \NameauthFName%
-}
+ {\@nameauth@FirstNametrue\NameauthFName}
% \end{macrocode}
% \end{macro}
%
% \begin{macro}{\FName*}
% \cmd{\FName} and \cmd{\FName*} are identical in function.
+%
% \begin{macrocode}
\WithSuffix{\newcommand*}\FName*{\FName}
% \end{macrocode}
% \end{macro}
%
-% \noindent{\normalsize\bfseries Index Operations}
-% \begin{macro}{\IndexProtect}
+% \subsubsection{Quick Interface}
+%
+% \begin{environment}{nameauth}
+% \changes{1.6}{2013/03/10}{Environment added}
+% \changes{2.0}{2015/11/11}{Better arg handling}
+% \changes{2.41}{2016/03/17}{No local \cmd{\newtoks}}
+% \changes{3.5}{2020/11/23}{Fix namespace}
+% \changes{3.7}{2023/02/03}{Improve warnings}
+% Here we create macro shorthands. First we define a macro \cmd{\<} that
+% takes four arguments, delimited by three ampersands and \texttt{>}.
+% This macro is local to the \texttt{nameauth} environment,
+% but the shorthand macros that it creates are global.
+%
+% \begin{macrocode}
+\newenvironment{nameauth}
+{%
+ \begingroup%
+ \let\ex\expandafter%
+ \csdef{<}##1&##2&##3&##4>{%
+ \protected@edef\@arga@{\trim@spaces{##1}}%
+ \protected@edef\@larga@{L\trim@spaces{##1}}%
+ \protected@edef\@sarga@{S\trim@spaces{##1}}%
+ \protected@edef\@testb@{\trim@spaces{##2}}%
+ \protected@edef\@testd@{\trim@spaces{##4}}%
+ \@nameauth@etoksb\ex{##2}%
+ \@nameauth@etoksc\ex{##3}%
+ \@nameauth@etoksd\ex{##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 argument.
+% Redefining a shorthand creates a warning.
+%
+% \begin{macrocode}
+ \ifx\@arga@\@empty
+ \PackageError{nameauth}%
+ {environment nameauth: Macro name missing;
+ \expandafter\detokenize\expandafter{##3}}%
+ \fi
+ \@nameauth@Error{##3}{macro: \ex\zap@space\string\ \@empty##1}%
+ \ifcsname\@arga@\endcsname
+ \PackageWarning{nameauth}
+ {Environment nameauth: shorthand macro already exists}%
+ \fi
+% \end{macrocode}
+% Set up shorthands according to name form. We use \cmd{\expandafter}
+% due to \cmd{\protected@edef} in the naming macros. We begin with
+% non-Western names that use the new syntax. We use one \cmd{\ex} per
+% token because we only have one argument to expand first.
+%
+% \begin{macrocode}
+ \ifx\@testd@\@empty
+ \ifx\@testb@\@empty
+ \ex\csgdef\ex{\ex\@arga@\ex}%
+ \ex{\ex\NameauthName\ex{\the\@nameauth@etoksc}}%
+ \ex\csgdef\ex{\ex\@larga@\ex}%
+ \ex{\ex\@nameauth@FullNametrue%
+ \ex\NameauthLName\ex{\the\@nameauth@etoksc}}%
+ \ex\csgdef\ex{\ex\@sarga@\ex}%
+ \ex{\ex\@nameauth@FirstNametrue%
+ \ex\NameauthFName\ex{\the\@nameauth@etoksc}}%
+ \else
+% \end{macrocode}
+% Next we have Western names with no alternate names.
+% Here we have two arguments to expand in reverse order,
+% so we need three uses, then one use of \cmd{\ex} 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@etoksb\ex]%
+ \ex{\the\@nameauth@etoksc}}%
+ \ex\ex\ex\csgdef\ex\ex\ex{\ex\ex\ex\@larga@\ex\ex\ex}%
+ \ex\ex\ex{\ex\ex\ex\@nameauth@FullNametrue%
+ \ex\ex\ex\NameauthLName%
+ \ex\ex\ex[\ex\the\ex\@nameauth@etoksb\ex]%
+ \ex{\the\@nameauth@etoksc}}%
+ \ex\ex\ex\csgdef\ex\ex\ex{\ex\ex\ex\@sarga@\ex\ex\ex}%
+ \ex\ex\ex{\ex\ex\ex\@nameauth@FirstNametrue%
+ \ex\ex\ex\NameauthFName%
+ \ex\ex\ex[\ex\the\ex\@nameauth@etoksb\ex]%
+ \ex{\the\@nameauth@etoksc}}%
+ \fi
+ \else
+% \end{macrocode}
+% Below are ``native'' Eastern names with alternates and
+% the older syntax. We again have two arguments to expand first.
+%
+% \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@etoksc\ex}%
+ \ex[\the\@nameauth@etoksd]}%
+ \ex\ex\ex\csgdef\ex\ex\ex{\ex\ex\ex\@larga@\ex\ex\ex}%
+ \ex\ex\ex{\ex\ex\ex\@nameauth@FullNametrue%
+ \ex\ex\ex\NameauthLName%
+ \ex\ex\ex{\ex\the\ex\@nameauth@etoksc\ex}%
+ \ex[\the\@nameauth@etoksd]}%
+ \ex\ex\ex\csgdef\ex\ex\ex{\ex\ex\ex\@sarga@\ex\ex\ex}%
+ \ex\ex\ex{\ex\ex\ex\@nameauth@FirstNametrue%
+ \ex\ex\ex\NameauthFName%
+ \ex\ex\ex{\ex\the\ex\@nameauth@etoksc\ex}%
+ \ex[\the\@nameauth@etoksd]}%
+ \else
+% \end{macrocode}
+% Here are Western names with alternates. We have three arguments
+% to expand, so we have seven uses, three uses, and one use of \cmd{\ex}.
+%
+% \begin{macrocode}
+ \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@etoksb\ex\ex\ex]%
+ \ex\ex\ex{\ex\the\ex\@nameauth@etoksc\ex}%
+ \ex[\the\@nameauth@etoksd]}%
+ \ex\ex\ex\ex\ex\ex\ex\csgdef\ex\ex\ex\ex\ex\ex\ex{%
+ \ex\ex\ex\ex\ex\ex\ex\@larga@\ex\ex\ex\ex\ex\ex\ex}%
+ \ex\ex\ex\ex\ex\ex\ex{%
+ \ex\ex\ex\ex\ex\ex\ex\@nameauth@FullNametrue%
+ \ex\ex\ex\ex\ex\ex\ex\NameauthLName%
+ \ex\ex\ex\ex\ex\ex\ex[\ex\ex\ex\the\ex\ex\ex%
+ \@nameauth@etoksb\ex\ex\ex]%
+ \ex\ex\ex{\ex\the\ex\@nameauth@etoksc\ex}%
+ \ex[\the\@nameauth@etoksd]}%
+ \ex\ex\ex\ex\ex\ex\ex\csgdef\ex\ex\ex\ex\ex\ex\ex{%
+ \ex\ex\ex\ex\ex\ex\ex\@sarga@\ex\ex\ex\ex\ex\ex\ex}%
+ \ex\ex\ex\ex\ex\ex\ex{%
+ \ex\ex\ex\ex\ex\ex\ex\@nameauth@FirstNametrue%
+ \ex\ex\ex\ex\ex\ex\ex\NameauthFName%
+ \ex\ex\ex\ex\ex\ex\ex[\ex\ex\ex\the\ex\ex\ex%
+ \@nameauth@etoksb\ex\ex\ex]%
+ \ex\ex\ex{\ex\the\ex\@nameauth@etoksc\ex}%
+ \ex[\the\@nameauth@etoksd]}%
+ \fi
+ \fi\ignorespaces%
+ }\ignorespaces%
+}
+{\endgroup\ignorespaces}
+% \end{macrocode}
+% \end{environment}
+%
+% \subsubsection{Debugging Macros}
+%
+% \begin{macro}{\ShowPattern}
% \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 the index contains one of the naming macros.
+% \changes{3.7}{2023/02/03}{Redesigned}
+% This displays the pattern that the name arguments generate;
+% useful for debugging. We test for bad input, then load the argument
+% values into the appropriate macros. We determine the name type
+% and produce the output of the appropriate name control sequence.
+%
% \begin{macrocode}
-\newcommand*\IndexProtect
+\newcommandx*\ShowPattern[3][1=\@empty, 3=\@empty]
+{%
+ \@nameauth@Error{#2}{macro: \string\ShowPattern}%
+ \@nameauth@LoadArgs{#1}{#2}{#3}%
+ \@nameauth@Choice{}{}{}\NameauthPattern%
+}
+% \end{macrocode}
+% \end{macro}
+%
+% \newpage
+%
+% \begin{macro}{\ShowIdxPageref}
+% \changes{3.3}{2020/02/20}{Added}
+% \changes{3.5}{2020/11/23}{Fix name space, use Boolean flags}
+% \changes{3.7}{2023/02/03}{Use common back-end}
+% This displays (expanded, as printed) the index entry that will be
+% generated, but not exactly what is in the \texttt{idx} file.
+% Test for bad input, load the argument values into
+% the appropriate macros, then call the back-end.
+%
+% \begin{macrocode}
+\newcommandx*\ShowIdxPageref[3][1=\@empty, 3=\@empty]
+{%
+ \@nameauth@Error{#2}{macro: \string\ShowIdxPageref}%
+ \@nameauth@LoadArgs{#1}{#2}{#3}%
+ \global\@nameauth@LongIdxDebugtrue%
+ \@nameauth@IdxPageref{#1}{#2}{#3}%
+}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\ShowIdxPageref*}
+% \changes{3.3}{2020/02/20}{Added}
+% \changes{3.5}{2020/11/23}{Fix name space, use Boolean flags}
+% \changes{3.7}{2023/02/03}{Use common back-end}
+% Display a basic index entry with no tag.
+% Test for bad input, load the argument values into
+% the appropriate macros, then call the back-end.
+%
+% \begin{macrocode}
+\WithSuffix{\newcommandx*}\ShowIdxPageref*[3][1=\@empty, 3=\@empty]
+{%
+ \@nameauth@Error{#2}{macro: \string\ShowIdxPageref*}%
+ \@nameauth@LoadArgs{#1}{#2}{#3}%
+ \@nameauth@IdxPageref{#1}{#2}{#3}%
+}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\ShowNameInfo}
+% \changes{3.7}{2023/02/03}{Added}
+% Show how the name arguments are being interpreted by the
+% \textsf{nameauth} macros, but as detokenized text,
+%
+% \begin{macrocode}
+\newcommandx*\ShowNameInfo[3][1=\@empty, 3=\@empty]
+{%
+% \end{macrocode}
+% Test for bad input, then load the argument values into
+% the appropriate macros.
+%
+% \begin{macrocode}
+ \@nameauth@Error{#2}{macro: \string\ShowNameInfo}%
+ \@nameauth@LoadArgs{#1}{#2}{#3}%
+% \end{macrocode}
+% We produce what we know about the name arguments.
+% First is non-Western names using the current syntax.
+%
+% \begin{macrocode}
+ \@nameauth@Choice
+ {%
+ (SNN: \expandafter\detokenize\expandafter{\@nameauth@B})%
+ \unless\ifx\@nameauth@SB\@empty
+ \ (Affix [FNN, other]:
+ \expandafter\detokenize\expandafter{\@nameauth@SB})%
+ \fi
+ \unless\ifx\@nameauth@C\@empty
+ \ (Alt:
+ \expandafter\detokenize\expandafter{\@nameauth@C})%
+ \fi
+ }%
+% \end{macrocode}
+% Next is non-Western names using the obsolete syntax.
+%
+% \begin{macrocode}
+ {%
+ (SNN: \expandafter\detokenize\expandafter{\@nameauth@B})%
+ \unless\ifx\@nameauth@C\@empty
+ \ (Alt [FNN, other]:
+ \expandafter\detokenize\expandafter{\@nameauth@C})%
+ \fi
+ }%
+% \end{macrocode}
+%
+% \newpage \noindent
+% Finally we have Western names.
+%
+% \begin{macrocode}
+ {%
+ (FNN: \expandafter\detokenize\expandafter{\@nameauth@A})
+ (SNN: \expandafter\detokenize\expandafter{\@nameauth@B})%
+ \unless\ifx\@nameauth@SB\@empty
+ \ (Affix:
+ \expandafter\detokenize\expandafter{\@nameauth@SB})%
+ \fi
+ \unless\ifx\@nameauth@C\@empty
+ \ (Alt:
+ \expandafter\detokenize\expandafter{\@nameauth@C})%
+ \fi
+ }%
+}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\ShowNameState}
+% \changes{3.7}{2023/02/03}{Added}
+% This macro tells the user what control sequence patterns
+% exist for any given name.
+%
+% \begin{macrocode}
+\newcommandx\ShowNameState[3][1=\@empty, 3=\@empty]
{%
- \@nameauth@DoIndexfalse%
- \@nameauth@BigLocktrue%
+% \end{macrocode}
+% Create a local scope to kill any local definitions on exit.
+% Test for bad input, then load the argument values into
+% the appropriate macros.
+%
+% \begin{macrocode}
+ \begingroup%
+ \@nameauth@Error{#2}{macro: \string\NamePatterns}%
+ \@nameauth@LoadArgs{#1}{#2}{#3}%
+% \end{macrocode}
+% Parse the name arguments and determine name type. We use this method
+% instead of examining the Boolean flags because it is more efficient here.
+%
+% \begin{macrocode}
+ \@nameauth@Choice
+ {\def\@nameauth@nametype{nw}}
+ {\def\@nameauth@nametype{nw,os}}
+ {\def\@nameauth@nametype{w}}
+% \end{macrocode}
+% Check to see what control sequences exist and collect the information.
+%
+% \begin{macrocode}
+ \ifcsname\NameauthPattern!MN\endcsname
+ \def\@nameauth@mainname{main}%
+ \fi
+ \ifcsname\NameauthPattern!NF\endcsname
+ \def\@nameauth@frontname{front}%
+ \fi
+ \ifcsname\NameauthPattern!PN\endcsname
+ \edef\@nameauth@testex
+ {\csname\NameauthPattern!PN\endcsname}%
+ \ifx\@nameauth@testex\@nameauth@Exclude
+ \def\@nameauth@excl{excl}%
+ \else
+ \def\@nameauth@xref{xref}%
+ \fi
+ \fi
+ \ifcsname\NameauthPattern!PRE\endcsname
+ \def\@nameauth@pre{pretag}%
+ \fi
+ \ifcsname\NameauthPattern!TAG\endcsname
+ \def\@nameauth@tag{idxtag}%
+ \fi
+ \ifcsname\NameauthPattern!DB\endcsname
+ \def\@nameauth@db{namedb}%
+ \fi
+% \end{macrocode}
+% If either a main name or a front name exist, create a macro
+% that reflects this condition.
+%
+% \begin{macrocode}
+ \ifdefined \@nameauth@mainname \def\@nameauth@namecs{}\fi
+ \ifdefined \@nameauth@frontname \def\@nameauth@namecs{}\fi
+% \end{macrocode}
+% If an xref and an exclusion exist for a name, something went wrong.
+%
+% \begin{macrocode}
+ \ifdefined \@nameauth@xref
+ \ifdefined \@nameauth@excl
+ \PackageWarning{nameauth}
+ {Both xref and exclusion exist for \NameauthPattern}%
+ \fi
+ \fi
+% \end{macrocode}
+% Determine the state of the ``index finite state machine''.
+%
+% \begin{macrocode}
+ \ifdefined \@nameauth@namecs
+ \def\@nameauth@idxstate{2}%
+ \ifdefined \@nameauth@xref
+ \def\@nameauth@idxstate{4}%
+ \fi
+ \ifdefined \@nameauth@excl
+ \def\@nameauth@idxstate{6}%
+ \fi
+ \else
+ \def\@nameauth@idxstate{1}%
+ \ifdefined \@nameauth@xref
+ \def\@nameauth@idxstate{3}%
+ \fi
+ \ifdefined \@nameauth@excl
+ \def\@nameauth@idxstate{5}%
+ \fi
+ \fi
+% \end{macrocode}
+% Display the output.
+%
+% \begin{macrocode}
+ Pattern: {\NameauthPattern}
+ Type: {\@nameauth@nametype}
+ Index state: {\@nameauth@idxstate}
+ Systems:%
+ \ifdefined \@nameauth@mainname\ \@nameauth@mainname \fi
+ \ifdefined \@nameauth@frontname\ \@nameauth@frontname \fi
+ \ifdefined \@nameauth@xref\ \@nameauth@xref \fi
+ \ifdefined \@nameauth@excl\ \@nameauth@excl \fi
+ \ifdefined \@nameauth@pre\ \@nameauth@pre \fi
+ \ifdefined \@nameauth@tag\ \@nameauth@tag \fi
+ \ifdefined \@nameauth@db\ \@nameauth@db \fi
+ \endgroup%
}
% \end{macrocode}
% \end{macro}
%
+% \subsubsection{Indexing}
+%
% \begin{macro}{\IndexName}
% \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}
% \changes{3.1}{2017/01/13}{Better tests}
-% \changes{3.5}{2020/11/23}{New warnings, new exclusion test, optimize logic, fix namespace}
-% This creates an index entry with page references. It warns if the \cmd{\SkipIndex} prefix macro was used before it was called. It issues additional warnings if the \texttt{verbose} option is selected. It prints nothing. First we make copies of the arguments.
+% \changes{3.5}{2020/11/23}{New warnings, new exclusion test,
+% improve logic, fix namespace}
+% \changes{3.7}{2023/02/03}{Fix warnings}
+% This creates an index entry with page references. It warns if
+% the \cmd{\SkipIndex} prefix macro was used before it was called.
+% It issues additional warnings if the \texttt{verbose} option is selected.
+% It prints nothing.
+%
% \begin{macrocode}
\newcommandx*\IndexName[3][1=\@empty, 3=\@empty]
{%
% \end{macrocode}
-% Process and load the arguments into the appropriate macros.
+% Process and load the arguments into the appropriate macros;
+% test for malformed input.
+%
% \begin{macrocode}
\@nameauth@LoadArgs{#1}{#2}{#3}%
- \def\@nameauth@space{ }%
-% \end{macrocode}
-% Test for malformed input.
-% \begin{macrocode}
\@nameauth@Error{#2}{macro \string\IndexName}%
% \end{macrocode}
-% Warn if \cmd{\SkipIndex} was called before \cmd{\IndexName}, and reset it unless the \texttt{oldreset} option was used.
+% Warn if \cmd{\SkipIndex} was called before \cmd{\IndexName} and reset
+% it unless the \texttt{oldreset} option was used.
+%
% \begin{macrocode}
\if@nameauth@SkipIndex
- \PackageWarning{nameauth}%
- {\SkipIndex precedes \IndexName; check for problems}%
+ \PackageWarning{nameauth}
+ {\string\SkipIndex precedes \string\IndexName; check for issues}%
\unless\if@nameauth@OldReset
\@nameauth@SkipIndexfalse%
\fi
\fi
% \end{macrocode}
% Warn if \cmd{\SeeAlso} was called before \cmd{\IndexName} and reset it.
+%
% \begin{macrocode}
\unless\if@nameauth@OldReset
\if@nameauth@SeeAlso
\global\@nameauth@SeeAlsofalse%
- \PackageWarning{nameauth}%
- {\SeeAlso precedes \IndexName or a naming macro and was reset}%
+ \PackageWarning{nameauth}{\string\SeeAlso was reset}%
\fi
\fi
% \end{macrocode}
-% We create the appropriate index entries, calling \cmd{\@nameauth@Index} to handle sorting and tagging. We do not create an index entry for a cross-reference or exclusion.
+% Create the appropriate index entries, calling \cmd{\@nameauth@Index}
+% to handle sorting and tagging. We do not create an index entry for a
+% cross-reference or exclusion.
+%
% \begin{macrocode}
- \@nameauth@Choice%
+ \@nameauth@Choice
% \end{macrocode}
% Non-Western names.
% We ignore \cmd{\@nameauth@C} and handle \cmd{\@nameauth@SB} appropriately.
+%
% \begin{macrocode}
{%
+ \def\@nameauth@Temp{\expandafter\detokenize\expandafter{#2}}%
\ifcsname\@nameauth@csb!PN\endcsname
\if@nameauth@Verbose
- \edef\@nameauth@testex{\csname\@nameauth@csb!PN\endcsname}%
+ \edef\@nameauth@testex
+ {\csname\@nameauth@csb!PN\endcsname}%
\ifx\@nameauth@testex\@nameauth@Exclude
- \PackageWarning{nameauth}%
- {macro \IndexName: Exclusion: #2 exists}%
+ \PackageWarning{nameauth}
+ {\string\IndexName: exclusion exists \@nameauth@Temp}%
\else
- \PackageWarning{nameauth}%
- {macro \IndexName: XRef: #2 exists}%
+ \PackageWarning{nameauth}
+ {\string\IndexName: xref exists \@nameauth@Temp}%
\fi
\fi
\else
\ifx\@nameauth@SB\@empty
\@nameauth@Index{\@nameauth@csb}{\@nameauth@B}%
\else
- \@nameauth@Index{\@nameauth@csb}%
- {\@nameauth@B\@nameauth@space%
- \@nameauth@SB}%
+ \@nameauth@Index{\@nameauth@csb}
+ {\@nameauth@B\@nameauth@space\@nameauth@SB}%
\fi
\fi
}%
% \end{macrocode}
% Non-Western names, obsolete syntax.
% Using \cmd{\@nameauth@C} in this path affects indexing.
+%
% \begin{macrocode}
{%
+ \def\@nameauth@Temp{\expandafter\detokenize\expandafter{#2 #3}}%
\ifcsname\@nameauth@csbc!PN\endcsname
\if@nameauth@Verbose
- \edef\@nameauth@testex{\csname\@nameauth@csbc!PN\endcsname}%
+ \edef\@nameauth@testex
+ {\csname\@nameauth@csbc!PN\endcsname}%
\ifx\@nameauth@testex\@nameauth@Exclude
- \PackageWarning{nameauth}%
- {macro \IndexName: Exclusion: #2 #3 exists}%
+ \PackageWarning{nameauth}
+ {\string\IndexName: exclusion exists \@nameauth@Temp}%
\else
- \PackageWarning{nameauth}%
- {macro \IndexName: XRef: #2 #3 exists}%
+ \PackageWarning{nameauth}
+ {\string\IndexName: xref exists \@nameauth@Temp}%
\fi
\fi
\else
- \@nameauth@Index{\@nameauth@csbc}%
- {\@nameauth@B\@nameauth@space%
- \@nameauth@C}%
+ \@nameauth@Index{\@nameauth@csbc}
+ {\@nameauth@B\@nameauth@space\@nameauth@C}%
\fi
}%
% \end{macrocode}
% Western names.
% We ignore \cmd{\@nameauth@C} and handle \cmd{\@nameauth@SB} appropriately.
+%
% \begin{macrocode}
{%
+ \def\@nameauth@Temp{\expandafter\detokenize\expandafter{#1 #2}}%
\ifcsname\@nameauth@csab!PN\endcsname
\if@nameauth@Verbose
- \edef\@nameauth@testex{\csname\@nameauth@csab!PN\endcsname}%
+ \edef\@nameauth@testex
+ {\csname\@nameauth@csab!PN\endcsname}%
\ifx\@nameauth@testex\@nameauth@Exclude
- \PackageWarning{nameauth}%
- {macro \IndexName: Exclusion: #1 #2 exists}%
+ \PackageWarning{nameauth}
+ {\string\IndexName: exclusion exists \@nameauth@Temp}%
\else
- \PackageWarning{nameauth}%
- {macro \IndexName: XRef: #1 #2 exists}%
+ \PackageWarning{nameauth}
+ {\string\IndexName: xref exists \@nameauth@Temp}%
\fi
\fi
\else
\ifx\@nameauth@SB\@empty
- \@nameauth@Index{\@nameauth@csab}%
+ \@nameauth@Index{\@nameauth@csab}
{\@nameauth@B,\@nameauth@space\@nameauth@A}%
\else
- \@nameauth@Index{\@nameauth@csab}%
+ \@nameauth@Index{\@nameauth@csab}
{\@nameauth@B,\@nameauth@space%
\@nameauth@A,\@nameauth@space\@nameauth@SB}%
\fi
@@ -8035,92 +12761,110 @@ and version 1.3 or later is part of all distributions of LaTeX version
% \changes{3.0}{2016/10/26}{Added}
% \changes{3.1}{2017/01/13}{Better tests}
% \changes{3.3}{2020/02/20}{Global flag reset}
-% \changes{3.5}{2020/11/23}{Strict \textit{see} refs, new warnings, new exclusion test, optimize logic, fix namespace}
-% Create a cross-reference that is not already an exclusion or a cross-reference. Print nothing.
+% \changes{3.5}{2020/11/23}{Strict \textit{see} refs, new warnings,
+% new exclusion test, improve logic, fix namespace}
+% \changes{3.7}{2023/02/03}{Fix warnings}
+% Create a cross-reference that is not already an exclusion or
+% a cross-reference. Print nothing.
+%
% \begin{macrocode}
\newcommandx*\IndexRef[4][1=\@empty, 3=\@empty]
{%
% \end{macrocode}
% Process and load the arguments into the appropriate macros.
+%
% \begin{macrocode}
\@nameauth@LoadArgs{#1}{#2}{#3}%
\protected@edef\@nameauth@Target{#4}%
- \def\@nameauth@space{ }%
% \end{macrocode}
% Test for malformed input.
+%
% \begin{macrocode}
\@nameauth@Error{#2}{macro \string\IndexRef}%
\@nameauth@Xreftrue%
% \end{macrocode}
-% Warn if \cmd{\SkipIndex} was called before \cmd{\IndexName}, and reset it unless the \texttt{oldreset} option was used.
+%
+% \newpage \noindent
+% Warn if \cmd{\SkipIndex} was called before \cmd{\IndexName},
+% and reset it unless the \texttt{oldreset} option was used.
+%
% \begin{macrocode}
\if@nameauth@SkipIndex
- \PackageWarning{nameauth}%
- {\SkipIndex preceded \IndexRef; check for problems}%
+ \PackageWarning{nameauth}
+ {\string\SkipIndex preceded \string\IndexRef; check for issues}%
\unless\if@nameauth@OldReset
\@nameauth@SkipIndexfalse%
\fi
\fi
+ \@nameauth@Choice
% \end{macrocode}
-% We create either \textit{see also} entries or \textit{see} entries. The former are unrestricted with respect to names, not to extant cross-references. The latter are only created if they do not already exist as either page entries or cross-references.
-% \begin{macrocode}
- \@nameauth@Choice%
-% \end{macrocode}
-% Mononym or Eastern/ancient name, new syntax. First check if an xref or excluded, and if so, do nothing except issue warnings if so desired.
+% Non-Western name, new syntax. First check if
+% an xref or excluded, and if so, do nothing except issue
+% warnings if so desired.
+%
% \begin{macrocode}
{%
+ \def\@nameauth@Temp{\expandafter\detokenize\expandafter{#2}}%
\ifcsname\@nameauth@csb!PN\endcsname
\if@nameauth@Verbose
- \edef\@nameauth@testex{\csname\@nameauth@csb!PN\endcsname}%
+ \edef\@nameauth@testex
+ {\csname\@nameauth@csb!PN\endcsname}%
\ifx\@nameauth@testex\@nameauth@Exclude
- \PackageWarning{nameauth}%
- {macro \IndexRef: Exclusion: #2 exists}%
+ \PackageWarning{nameauth}
+ {\string\IndexRef: exclusion exists \@nameauth@Temp}%
\else
- \PackageWarning{nameauth}%
- {macro \IndexRef: XRef: #2 exists}%
+ \PackageWarning{nameauth}
+ {\string\IndexRef: xref exists \@nameauth@Temp}%
\fi
\fi
% \end{macrocode}
-% If no xref or exclusion control sequence exists, either create a \textit{see also} or a \textit{see} reference. If the latter, forbid a \textit{see} reference to an extant name unless the \texttt{oldsee} option is used; then allow, but issue a warning.
+% If no xref or exclusion exists, either create a \textit{see also}
+% or a \textit{see} reference. We permit the latter when a name exists
+% only if the \texttt{oldsee} option is used; then issue a warning.
+%
% \begin{macrocode}
\else
\ifx\@nameauth@SB\@empty
\if@nameauth@SeeAlso
- \@nameauth@Index{\@nameauth@csb}%
+ \@nameauth@Index{\@nameauth@csb}
{\@nameauth@B|seealso{\@nameauth@Target}}%
\csgdef{\@nameauth@csb!PN}{}%
\else
\unless\if@nameauth@OldSee
\unless\ifcsname\@nameauth@csb!MN\endcsname
\unless\ifcsname\@nameauth@csb!NF\endcsname
- \@nameauth@Index{\@nameauth@csb}%
+ \@nameauth@Index{\@nameauth@csb}
{\@nameauth@B|see{\@nameauth@Target}}%
\csgdef{\@nameauth@csb!PN}{}%
\else
- \PackageWarning{nameauth}%
- {macro \IndexRef: Extant name #2 stops see ref.}%
+ \PackageWarning{nameauth}
+ {\string\IndexRef: extant name;
+ no xref \@nameauth@Temp}%
\fi
\else
- \PackageWarning{nameauth}%
- {macro \IndexRef: Extant name #2 stops see ref.}%
+ \PackageWarning{nameauth}
+ {\string\IndexRef: extant name;
+ no xref \@nameauth@Temp}%
\fi
\else
\if@nameauth@Verbose
- \PackageWarning{nameauth}%
- {macro \IndexRef: Non-strict XRef #2 created}%
+ \PackageWarning{nameauth}
+ {\string\IndexRef: non-strict xref \@nameauth@Temp}%
\fi
- \@nameauth@Index{\@nameauth@csb}%
+ \@nameauth@Index{\@nameauth@csb}
{\@nameauth@B|see{\@nameauth@Target}}%
\csgdef{\@nameauth@csb!PN}{}%
\fi
\fi
% \end{macrocode}
-% \newpage\noindent
-% When the suffix is non-empty, either create a \textit{see also} or a \textit{see} reference. If the latter, forbid a \textit{see} reference to an extant name unless the \texttt{oldsee} option is used; then allow and warn.
+% When the suffix is non-empty, either create a \textit{see also}
+% or a \textit{see} reference. We permit the latter when a name exists
+% only if the \texttt{oldsee} option is used; then issue a warning.
+%
% \begin{macrocode}
\else
\if@nameauth@SeeAlso
- \@nameauth@Index{\@nameauth@csb}%
+ \@nameauth@Index{\@nameauth@csb}
{\@nameauth@B\@nameauth@space%
\@nameauth@SB|seealso{\@nameauth@Target}}%
\csgdef{\@nameauth@csb!PN}{}%
@@ -8128,24 +12872,26 @@ and version 1.3 or later is part of all distributions of LaTeX version
\unless\if@nameauth@OldSee
\unless\ifcsname\@nameauth@csb!MN\endcsname
\unless\ifcsname\@nameauth@csb!NF\endcsname
- \@nameauth@Index{\@nameauth@csb}%
+ \@nameauth@Index{\@nameauth@csb}
{\@nameauth@B\@nameauth@space%
\@nameauth@SB|see{\@nameauth@Target}}%
\csgdef{\@nameauth@csb!PN}{}%
\else
- \PackageWarning{nameauth}%
- {macro \IndexRef: Extant name #2 stops see ref.}%
+ \PackageWarning{nameauth}
+ {\string\IndexRef: extant name;
+ no xref \@nameauth@Temp}%
\fi
\else
- \PackageWarning{nameauth}%
- {macro \IndexRef: Extant name #2 stops see ref.}%
+ \PackageWarning{nameauth}
+ {\string\IndexRef: extant name;
+ no xref \@nameauth@Temp}%
\fi
\else
\if@nameauth@Verbose
- \PackageWarning{nameauth}%
- {macro \IndexRef: Non-strict XRef #2 created}%
+ \PackageWarning{nameauth}
+ {\string\IndexRef: non-strict xref \@nameauth@Temp}%
\fi
- \@nameauth@Index{\@nameauth@csb}%
+ \@nameauth@Index{\@nameauth@csb}
{\@nameauth@B\@nameauth@space%
\@nameauth@SB|see{\@nameauth@Target}}%
\csgdef{\@nameauth@csb!PN}{}%
@@ -8155,27 +12901,32 @@ and version 1.3 or later is part of all distributions of LaTeX version
\fi
}%
% \end{macrocode}
-% Eastern or ancient name, obsolete syntax. First check if an xref or excluded.
+% Eastern or ancient name, obsolete syntax. First check if an xref or excluded.
+%
% \begin{macrocode}
{%
+ \def\@nameauth@Temp{\expandafter\detokenize\expandafter{#2 #3}}%
\ifcsname\@nameauth@csbc!PN\endcsname
\if@nameauth@Verbose
- \edef\@nameauth@testex{\csname\@nameauth@csbc!PN\endcsname}%
+ \edef\@nameauth@testex
+ {\csname\@nameauth@csbc!PN\endcsname}%
\ifx\@nameauth@testex\@nameauth@Exclude
- \PackageWarning{nameauth}%
- {macro \IndexRef: Exclusion: #2 #3 exists}%
+ \PackageWarning{nameauth}
+ {\string\IndexRef: exclusion exists \@nameauth@Temp}%
\else
- \PackageWarning{nameauth}%
- {macro \IndexRef: XRef: #2 #3 exists}%
+ \PackageWarning{nameauth}
+ {\string\IndexRef: xref exists \@nameauth@Temp}%
\fi
\fi
% \end{macrocode}
-% \newpage\noindent
-% If no xref control sequence exists, either create a \textit{see also} or a \textit{see} reference. If the latter, forbid a \textit{see} reference to an extant name unless the \texttt{oldsee} option is used; then allow, but issue a warning.
+% If no xref control sequence exists, either create a \textit{see also}
+% or a \textit{see} reference. We permit the latter when a name exists
+% only if the \texttt{oldsee} option is used; then issue a warning.
+%
% \begin{macrocode}
\else
\if@nameauth@SeeAlso
- \@nameauth@Index{\@nameauth@csbc}%
+ \@nameauth@Index{\@nameauth@csbc}
{\@nameauth@B\@nameauth@space%
\@nameauth@C|seealso{\@nameauth@Target}}%
\csgdef{\@nameauth@csbc!PN}{}%
@@ -8183,24 +12934,26 @@ and version 1.3 or later is part of all distributions of LaTeX version
\unless\if@nameauth@OldSee
\unless\ifcsname\@nameauth@csbc!MN\endcsname
\unless\ifcsname\@nameauth@csbc!NF\endcsname
- \@nameauth@Index{\@nameauth@csbc}%
+ \@nameauth@Index{\@nameauth@csbc}
{\@nameauth@B\@nameauth@space%
\@nameauth@C|see{\@nameauth@Target}}%
\csgdef{\@nameauth@csbc!PN}{}%
\else
- \PackageWarning{nameauth}%
- {macro \IndexRef: Extant name #2 #3 stops see ref.}%
+ \PackageWarning{nameauth}
+ {\string\IndexRef: extant name;
+ no xref \@nameauth@Temp}%
\fi
\else
- \PackageWarning{nameauth}%
- {macro \IndexRef: Extant name #2 #3 stops see ref.}%
+ \PackageWarning{nameauth}
+ {\string\IndexRef: extant name;
+ no xref \@nameauth@Temp}%
\fi
\else
\if@nameauth@Verbose
- \PackageWarning{nameauth}%
- {macro \IndexRef: Non-strict XRef #2 #3 created}%
+ \PackageWarning{nameauth}
+ {\string\IndexRef: non-strict xref \@nameauth@Temp}%
\fi
- \@nameauth@Index{\@nameauth@csbc}%
+ \@nameauth@Index{\@nameauth@csbc}
{\@nameauth@B\@nameauth@space%
\@nameauth@C|see{\@nameauth@Target}}%
\csgdef{\@nameauth@csbc!PN}{}%
@@ -8210,27 +12963,32 @@ and version 1.3 or later is part of all distributions of LaTeX version
}%
% \end{macrocode}
% Western name, without and with affix. First check if an xref or excluded.
+%
% \begin{macrocode}
{%
+ \def\@nameauth@Temp{\expandafter\detokenize\expandafter{#1 #2}}%
\ifcsname\@nameauth@csab!PN\endcsname
\if@nameauth@Verbose
- \edef\@nameauth@testex{\csname\@nameauth@csab!PN\endcsname}%
+ \edef\@nameauth@testex
+ {\csname\@nameauth@csab!PN\endcsname}%
\ifx\@nameauth@testex\@nameauth@Exclude
- \PackageWarning{nameauth}%
- {macro \IndexRef: Exclusion: #1 #2 exists}%
+ \PackageWarning{nameauth}
+ {\string\IndexRef: exclusion exists \@nameauth@Temp}%
\else
- \PackageWarning{nameauth}%
- {macro \IndexRef: XRef: #1 #2 exists}%
+ \PackageWarning{nameauth}
+ {\string\IndexRef: xref exists \@nameauth@Temp}%
\fi
\fi
% \end{macrocode}
-% \newpage\noindent
-% If no xref control sequence exists, either create a \textit{see also} or a \textit{see} reference. If the latter, forbid a \textit{see} reference to an extant name unless the \texttt{oldsee} option is used; then allow, but issue a warning.
+% If no xref control sequence exists, either create a \textit{see also}
+% or a \textit{see} reference. We permit the latter when a name exists
+% only if the \texttt{oldsee} option is used; then issue a warning.
+%
% \begin{macrocode}
\else
\ifx\@nameauth@SB\@empty
\if@nameauth@SeeAlso
- \@nameauth@Index{\@nameauth@csab}%
+ \@nameauth@Index{\@nameauth@csab}
{\@nameauth@B,\@nameauth@space%
\@nameauth@A|seealso{\@nameauth@Target}}%
\csgdef{\@nameauth@csab!PN}{}%
@@ -8238,35 +12996,40 @@ and version 1.3 or later is part of all distributions of LaTeX version
\unless\if@nameauth@OldSee
\unless\ifcsname\@nameauth@csab!MN\endcsname
\unless\ifcsname\@nameauth@csab!NF\endcsname
- \@nameauth@Index{\@nameauth@csab}%
+ \@nameauth@Index{\@nameauth@csab}
{\@nameauth@B,\@nameauth@space%
\@nameauth@A|see{\@nameauth@Target}}%
\csgdef{\@nameauth@csab!PN}{}%
\else
- \PackageWarning{nameauth}%
- {macro \IndexRef: Extant name #1 #2 stops see ref.}%
+ \PackageWarning{nameauth}
+ {\string\IndexRef: extant name;
+ no xref \@nameauth@Temp}%
\fi
\else
- \PackageWarning{nameauth}%
- {macro \IndexRef: Extant name #1 #2 stops see ref.}%
+ \PackageWarning{nameauth}
+ {\string\IndexRef: extant name;
+ no xref \@nameauth@Temp}%
\fi
\else
\if@nameauth@Verbose
- \PackageWarning{nameauth}%
- {macro \IndexRef: Non-strict XRef #1 #2 created}%
+ \PackageWarning{nameauth}
+ {\string\IndexRef: non-strict xref \@nameauth@Temp}%
\fi
- \@nameauth@Index{\@nameauth@csab}%
+ \@nameauth@Index{\@nameauth@csab}
{\@nameauth@B,\@nameauth@space%
\@nameauth@A|see{\@nameauth@Target}}%
\csgdef{\@nameauth@csab!PN}{}%
\fi
\fi
% \end{macrocode}
-% When the suffix is non-empty, either create a \textit{see also} or a \textit{see} reference. If the latter, forbid a \textit{see} reference to an extant name unless the \texttt{oldsee} option is used; then allow and warn.
+% When the suffix is non-empty, either create a \textit{see also}
+% or a \textit{see} reference. We permit the latter when a name exists
+% only if the \texttt{oldsee} option is used; then issue a warning.
+%
% \begin{macrocode}
\else
\if@nameauth@SeeAlso
- \@nameauth@Index{\@nameauth@csab}%
+ \@nameauth@Index{\@nameauth@csab}
{\@nameauth@B,\@nameauth@space%
\@nameauth@A,\@nameauth@space%
\@nameauth@SB|seealso{\@nameauth@Target}}%
@@ -8275,25 +13038,27 @@ and version 1.3 or later is part of all distributions of LaTeX version
\unless\if@nameauth@OldSee
\unless\ifcsname\@nameauth@csab!MN\endcsname
\unless\ifcsname\@nameauth@csab!NF\endcsname
- \@nameauth@Index{\@nameauth@csab}%
+ \@nameauth@Index{\@nameauth@csab}
{\@nameauth@B,\@nameauth@space%
\@nameauth@A,\@nameauth@space%
\@nameauth@SB|see{\@nameauth@Target}}%
\csgdef{\@nameauth@csab!PN}{}%
\else
- \PackageWarning{nameauth}%
- {macro \IndexRef: Extant name #1 #2 stops see ref.}%
+ \PackageWarning{nameauth}
+ {\string\IndexRef: extant name;
+ no xref \@nameauth@Temp}%
\fi
\else
- \PackageWarning{nameauth}%
- {macro \IndexRef: Extant name #1 #2 stops see ref.}%
+ \PackageWarning{nameauth}
+ {\string\IndexRef: extant name;
+ no xref \@nameauth@Temp}%
\fi
\else
\if@nameauth@Verbose
- \PackageWarning{nameauth}%
- {macro \IndexRef: Non-strict XRef #1 #2 created}%
+ \PackageWarning{nameauth}
+ {\string\IndexRef: non-strict xref \@nameauth@Temp}%
\fi
- \@nameauth@Index{\@nameauth@csab}%
+ \@nameauth@Index{\@nameauth@csab}
{\@nameauth@B,\@nameauth@space%
\@nameauth@A,\@nameauth@space%
\@nameauth@SB|see{\@nameauth@Target}}%
@@ -8318,116 +13083,68 @@ and version 1.3 or later is part of all distributions of LaTeX version
% \changes{2.3}{2016/01/05}{New xref test}
% \changes{3.0}{2016/10/26}{Redesigned}
% \changes{3.3}{2020/02/20}{Better warnings}
-% \changes{3.5}{2020/11/23}{New warnings, new exclusion test, fix bug in old syntax, new logic, fix namespace}
-% Prevent a name from being indexed. Now, the set of macro expansions that comprise an exclusion contains one member: the value of \cmd{\@nameauth@Exclude}. Formerly, an exclusion was the set of all non-empty strings, preventing any other features from being added.
+% \changes{3.5}{2020/11/23}{New warnings, new exclusion test,
+% fix bug in old syntax, new logic, fix namespace}
+% \changes{3.7}{2023/02/03}{Fix warnings, optimized}
+% Prevent a name from being indexed by initializing a regular
+% cross-reference control sequence with the value of
+% \cmd{\@nameauth@Exclude}.
+%
% \begin{macrocode}
\newcommandx*\ExcludeName[3][1=\@empty, 3=\@empty]
{%
% \end{macrocode}
% Process and load the arguments into the appropriate macros.
+%
% \begin{macrocode}
\@nameauth@LoadArgs{#1}{#2}{#3}%
\@nameauth@Error{#2}{macro \string\ExcludeName}%
% \end{macrocode}
-% Below we parse the name arguments and create an excluded form of cross-reference, unless one already exists.
+% Parse the name arguments and create an excluded xref,
+% unless one already exists.
+%
% \begin{macrocode}
- \@nameauth@Choice%
+ \@nameauth@Choice
+ {\def\@nameauth@Temp{\expandafter\detokenize\expandafter{#2}}}
+ {\def\@nameauth@Temp{\expandafter\detokenize\expandafter{#2 #3}}}
+ {\def\@nameauth@Temp{\expandafter\detokenize\expandafter{#1 #2}}}%
% \end{macrocode}
-% Non-Western names. Verbose warnings let one know that an extant name is being excluded, but the operation is still allowed.
-% \begin{macrocode}
- {%
- \if@nameauth@Verbose
- \ifcsname\@nameauth@csb!MN\endcsname
- \PackageWarning{nameauth}%
- {macro \ExcludeName: Name: #2 exists}%
- \fi
- \ifcsname\@nameauth@csb!NF\endcsname
- \PackageWarning{nameauth}%
- {macro \ExcludeName: Name: #2 exists}%
- \fi
- \fi
-% \end{macrocode}
-% One cannot exclude an extant cross-reference or exclusion. Verbose warnings only.
+%
+% \newpage \noindent
+% Verbose warnings say that an extant name is being excluded;
+% the operation is allowed.
+%
% \begin{macrocode}
- \ifcsname\@nameauth@csb!PN\endcsname
- \if@nameauth@Verbose
- \edef\@nameauth@testex{\csname\@nameauth@csb!PN\endcsname}%
- \ifx\@nameauth@testex\@nameauth@Exclude
- \PackageWarning{nameauth}%
- {macro \ExcludeName: Exclusion: #2 exists}%
- \else
- \PackageWarning{nameauth}%
- {macro \ExcludeName: XRef: #2 exists}%
- \fi
- \fi
- \else
- \csxdef{\@nameauth@csb!PN}{\@nameauth@Exclude}%
+ \if@nameauth@Verbose
+ \ifcsname\NameauthPattern!MN\endcsname
+ \PackageWarning{nameauth}
+ {\string\ExcludeName: extant name \@nameauth@Temp}%
\fi
- }%
-% \end{macrocode}
-% Non-Western names, obsolete syntax. Verbose warnings let one know that an extant name is being excluded, but the operation is still allowed.
-% \begin{macrocode}
- {%
- \if@nameauth@Verbose
- \ifcsname\@nameauth@csbc!MN\endcsname
- \PackageWarning{nameauth}%
- {macro \ExcludeName: Name: #2 #3 exists}%
- \fi
- \ifcsname\@nameauth@csbc!NF\endcsname
- \PackageWarning{nameauth}%
- {macro \ExcludeName: Name: #2 #3 exists}%
- \fi
+ \ifcsname\NameauthPattern!NF\endcsname
+ \PackageWarning{nameauth}
+ {\string\ExcludeName: extant name \@nameauth@Temp}%
\fi
+ \fi
% \end{macrocode}
-% One cannot exclude an extant cross-reference or exclusion. Verbose warnings only.
-% \begin{macrocode}
- \ifcsname\@nameauth@csbc!PN\endcsname
- \if@nameauth@Verbose
- \edef\@nameauth@testex{\csname\@nameauth@csbc!PN\endcsname}%
- \ifx\@nameauth@testex\@nameauth@Exclude
- \PackageWarning{nameauth}%
- {macro \ExcludeName: Exclusion: #2 #3 exists}%
- \else
- \PackageWarning{nameauth}%
- {macro \ExcludeName: XRef: #2 #3 exists}%
- \fi
- \fi
- \else
- \csxdef{\@nameauth@csbc!PN}{\@nameauth@Exclude}%
- \fi
- }%
-% \end{macrocode}
-% Western names. Verbose warnings let one know that an extant name is being excluded, but the operation is still allowed.
+% One cannot exclude an extant cross-reference or exclusion.
+% Verbose warnings only.
+%
% \begin{macrocode}
- {%
+ \ifcsname\NameauthPattern!PN\endcsname
\if@nameauth@Verbose
- \ifcsname\@nameauth@csab!MN\endcsname
- \PackageWarning{nameauth}%
- {macro \ExcludeName: Name: #1 #2 exists}%
- \fi
- \ifcsname\@nameauth@csab!NF\endcsname
- \PackageWarning{nameauth}%
- {macro \ExcludeName: Name: #1 #2 exists}%
- \fi
- \fi
-% \end{macrocode}
-% One cannot exclude an extant cross-reference or exclusion. Verbose warnings only.
-% \begin{macrocode}
- \ifcsname\@nameauth@csab!PN\endcsname
- \if@nameauth@Verbose
- \edef\@nameauth@testex{\csname\@nameauth@csab!PN\endcsname}%
- \ifx\@nameauth@testex\@nameauth@Exclude
- \PackageWarning{nameauth}%
- {macro \ExcludeName: Exclusion: #1 #2 exists}%
- \else
- \PackageWarning{nameauth}%
- {macro \ExcludeName: XRef: #1 #2 exists}%
- \fi
+ \edef\@nameauth@testex
+ {\csname\NameauthPattern!PN\endcsname}%
+ \ifx\@nameauth@testex\@nameauth@Exclude
+ \PackageWarning{nameauth}
+ {\string\ExcludeName: exclusion exists \@nameauth@Temp}%
+ \else
+ \PackageWarning{nameauth}
+ {\string\ExcludeName: xref exists \@nameauth@Temp}%
\fi
- \else
- \csxdef{\@nameauth@csab!PN}{\@nameauth@Exclude}%
\fi
- }%
+ \else
+ \csxdef{\NameauthPattern!PN}{\@nameauth@Exclude}%
+ \fi
}
% \end{macrocode}
% \end{macro}
@@ -8435,160 +13152,115 @@ and version 1.3 or later is part of all distributions of LaTeX version
% \begin{macro}{\IncludeName}
% \changes{3.0}{2016/10/26}{Added}
% \changes{3.3}{2020/02/20}{Added warnings}
-% \changes{3.5}{2020/11/23}{New exclusion test, optimize logic, fix namespace}
-% This macro allows a name to be indexed once again only if it had been excluded.
+% \changes{3.5}{2020/11/23}{New exclusion test, optimize logic,
+% fix namespace}
+% \changes{3.7}{2023/02/03}{Fix warnings, optimized}
+% This macro allows a name to be indexed once again only if
+% it had been excluded.
+%
% \begin{macrocode}
\newcommandx*\IncludeName[3][1=\@empty, 3=\@empty]
{%
% \end{macrocode}
% Process and load the arguments into the appropriate macros.
+% Get the current name type, pattern, and contents if a warning
+% is needed.
+%
% \begin{macrocode}
\@nameauth@LoadArgs{#1}{#2}{#3}%
\@nameauth@Error{#2}{macro \string\IncludeName}%
- \@nameauth@Choice%
-% \end{macrocode}
-% Non-Western names.
-% \begin{macrocode}
- {%
- \ifcsname\@nameauth@csb!PN\endcsname
- \edef\@nameauth@testex{\csname\@nameauth@csb!PN\endcsname}%
- \ifx\@nameauth@testex\@nameauth@Exclude
- \global\csundef{\@nameauth@csb!PN}%
- \else
- \if@nameauth@Verbose
- \PackageWarning{nameauth}%
- {macro \IncludeName: Xref: #2 exists}%
- \fi
- \fi
- \fi
- }%
-% \end{macrocode}
-% Non-Western names, obsolete syntax.
-% \begin{macrocode}
- {%
- \ifcsname\@nameauth@csbc!PN\endcsname
- \edef\@nameauth@testex{\csname\@nameauth@csbc!PN\endcsname}%
- \ifx\@nameauth@testex\@nameauth@Exclude
- \global\csundef{\@nameauth@csbc!PN}%
- \else
- \if@nameauth@Verbose
- \PackageWarning{nameauth}%
- {macro \IncludeName: Xref: #2 #3 exists}%
- \fi
- \fi
- \fi
- }%
+ \@nameauth@Choice
+ {\def\@nameauth@Temp{\expandafter\detokenize\expandafter{#2}}}
+ {\def\@nameauth@Temp{\expandafter\detokenize\expandafter{#2 #3}}}
+ {\def\@nameauth@Temp{\expandafter\detokenize\expandafter{#1 #2}}}%
% \end{macrocode}
-% Western names.
+% Test whether the name is an exclusion or a regular xref.
+% If the former, delete its control sequence. If the latter,
+% do nothing and issue a warning.
+%
% \begin{macrocode}
- {%
- \ifcsname\@nameauth@csab!PN\endcsname
- \edef\@nameauth@testex{\csname\@nameauth@csab!PN\endcsname}%
- \ifx\@nameauth@testex\@nameauth@Exclude
- \global\csundef{\@nameauth@csab!PN}%
- \else
- \if@nameauth@Verbose
- \PackageWarning{nameauth}%
- {macro \IncludeName: Xref: #1 #2 exists}%
- \fi
+ \ifcsname\NameauthPattern!PN\endcsname
+ \edef\@nameauth@testex
+ {\csname\NameauthPattern!PN\endcsname}%
+ \ifx\@nameauth@testex\@nameauth@Exclude
+ \global\csundef{\NameauthPattern!PN}%
+ \else
+ \if@nameauth@Verbose
+ \PackageWarning{nameauth}
+ {\string\IncludeName: extant xref \@nameauth@Temp}%
\fi
\fi
- }%
+ \fi
}
% \end{macrocode}
% \end{macro}
%
% \begin{macro}{\IncludeName*}
% \changes{3.0}{2016/10/26}{Added}
-% \changes{3.5}{2020/11/23}{Optimize logic, fix namespace}
-% This macro allows any name to be indexed by voiding any exclusion or cross-reference.
+% \changes{3.5}{2020/11/23}{Improve logic, fix namespace}
+% \changes{3.7}{2023/02/03}{Optimized}
+% This macro allows any name to be indexed by voiding any exclusion or
+% cross-reference.
+%
% \begin{macrocode}
\WithSuffix{\newcommandx*}\IncludeName*[3][1=\@empty, 3=\@empty]
{%
\@nameauth@LoadArgs{#1}{#2}{#3}%
\@nameauth@Error{#2}{macro \string\IncludeName*}%
- \@nameauth@Choice%
- {\global\csundef{\@nameauth@csb!PN}}%
- {\global\csundef{\@nameauth@csbc!PN}}%
- {\global\csundef{\@nameauth@csab!PN}}%
+ \@nameauth@Choice{}{}{}%
+ \global\csundef{\NameauthPattern!PN}%
}
% \end{macrocode}
% \end{macro}
%
% \begin{macro}{\PretagName}
% \changes{2.0}{2015/11/11}{Added}
-% \changes{3.5}{2020/11/23}{New warnings, new exclusion test, optimize logic, fix namespace}
-% This creates an index entry tag that is applied before a name by \cmd{\@nameauth@Index}.
+% \changes{3.5}{2020/11/23}{New warnings, new exclusion test,
+% improve logic, fix namespace}
+% \changes{3.7}{2023/02/03}{Fix warnings, optimized}
+% This creates an index entry tag that is applied before a name
+% by \cmd{\@nameauth@Index}.
+%
% \begin{macrocode}
\newcommandx*\PretagName[4][1=\@empty, 3=\@empty]
{%
% \end{macrocode}
% Process and load the arguments into the appropriate macros.
+%
% \begin{macrocode}
\@nameauth@LoadArgs{#1}{#2}{#3}%
\@nameauth@Error{#2}{macro \string\PretagName}%
% \end{macrocode}
% Sort only when permitted.
+% Get the current name type, pattern, and contents if a warning
+% is needed.
+%
% \begin{macrocode}
\if@nameauth@Pretag
- \@nameauth@Choice%
+ \@nameauth@Choice
+ {\def\@nameauth@Temp{\expandafter\detokenize\expandafter{#2}}}
+ {\def\@nameauth@Temp{\expandafter\detokenize\expandafter{#2 #3}}}
+ {\def\@nameauth@Temp{\expandafter\detokenize\expandafter{#1 #2}}}%
% \end{macrocode}
-% Non-Western names. Verbose warnings let us know if we are sorting either exclusions or cross-references. The former will be ignored. The latter will be used.
-% \begin{macrocode}
- {%
- \ifcsname\@nameauth@csb!PN\endcsname
- \if@nameauth@Verbose
- \edef\@nameauth@testex{\csname\@nameauth@csb!PN\endcsname}%
- \ifx\@nameauth@testex\@nameauth@Exclude
- \PackageWarning{nameauth}%
- {macro \PretagName: tagging exclusion: #2}%
- \else
- \PackageWarning{nameauth}%
- {macro \PretagName: tagging xref: #2}%
- \fi
- \fi
- \fi
- \csgdef{\@nameauth@csb!PRE}{#4\@nameauth@Actual}%
- }%
-% \end{macrocode}
-% Non-Western names, obsolete syntax. Verbose warnings let us know if we are sorting either exclusions or cross-references. The former will be ignored. The latter will be used.
-% \begin{macrocode}
- {%
- \ifcsname\@nameauth@csbc!PN\endcsname
- \if@nameauth@Verbose
- \edef\@nameauth@testex{\csname\@nameauth@csbc!PN\endcsname}%
- \ifx\@nameauth@testex\@nameauth@Exclude
- \PackageWarning{nameauth}%
- {macro \PretagName: tagging exclusion: #2 #3}%
- \else
- \PackageWarning{nameauth}%
- {macro \PretagName: tagging xref: #2 #3}%
- \fi
- \fi
- \fi
- \csgdef{\@nameauth@csbc!PRE}{#4\@nameauth@Actual}%
- }%
-% \end{macrocode}
-% Western names. Verbose warnings let us know if we are sorting either exclusions or cross-references. The former will be ignored. The latter will be used.
+% Create the sort tag. Verbose warnings let us know if we are
+% sorting either exclusions or cross-references.
+%
% \begin{macrocode}
- {%
- \ifcsname\@nameauth@csab!PN\endcsname
- \if@nameauth@Verbose
- \edef\@nameauth@testex{\csname\@nameauth@csab!PN\endcsname}%
- \ifx\@nameauth@testex\@nameauth@Exclude
- \PackageWarning{nameauth}%
- {macro \PretagName: tagging exclusion: #1 #2}%
- \else
- \PackageWarning{nameauth}%
- {macro \PretagName: tagging xref: #1 #2}%
- \fi
- \fi
+ \if@nameauth@Verbose
+ \edef\@nameauth@testex
+ {\csname\NameauthPattern!PN\endcsname}%
+ \ifx\@nameauth@testex\@nameauth@Exclude
+ \PackageWarning{nameauth}
+ {\string\PretagName: tag exclusion \@nameauth@Temp}%
+ \else
+ \PackageWarning{nameauth}
+ {\string\PretagName: tag xref \@nameauth@Temp}%
\fi
- \csgdef{\@nameauth@csab!PRE}{#4\@nameauth@Actual}%
- }%
+ \fi
+ \csgdef{\NameauthPattern!PRE}{#4\@nameauth@Actual}%
\else
- \PackageWarning{nameauth}%
- {macro \PretagName: deactivated}%
+ \PackageWarning{nameauth}
+ {\string\PretagName: deactivated}%
\fi
}
% \end{macrocode}
@@ -8598,74 +13270,48 @@ and version 1.3 or later is part of all distributions of LaTeX version
% \changes{1.2}{2012/02/25}{Added}
% \changes{1.9}{2015/07/09}{Fix cs collisions}
% \changes{2.0}{2015/11/11}{Redesign tagging}
-% \changes{3.5}{2020/11/23}{New warnings, new exclusion test, optimize logic, fix namespace}
-% This creates an index entry tag for a name that is not either an exclusion or a cross-reference.
+% \changes{3.5}{2020/11/23}{New warnings, new exclusion test,
+% improve logic, fix namespace}
+% \changes{3.7}{2023/02/03}{Optimized}
+% This creates an index entry tag for a name that is not either
+% an exclusion or a cross-reference.
+%
% \begin{macrocode}
\newcommandx*\TagName[4][1=\@empty, 3=\@empty]
{%
% \end{macrocode}
% Process and load the arguments into the appropriate macros.
+% Get the current name type, pattern, and contents if a warning
+% is needed.
+%
% \begin{macrocode}
\@nameauth@LoadArgs{#1}{#2}{#3}%
\@nameauth@Error{#2}{macro \string\TagName}%
- \@nameauth@Choice%
+ \@nameauth@Choice
+ {\def\@nameauth@Temp{\expandafter\detokenize\expandafter{#2}}}
+ {\def\@nameauth@Temp{\expandafter\detokenize\expandafter{#2 #3}}}
+ {\def\@nameauth@Temp{\expandafter\detokenize\expandafter{#1 #2}}}%
% \end{macrocode}
-% Non-Western names.
-% \begin{macrocode}
- {%
- \ifcsname\@nameauth@csb!PN\endcsname
- \if@nameauth@Verbose
- \edef\@nameauth@testex{\csname\@nameauth@csb!PN\endcsname}%
- \ifx\@nameauth@testex\@nameauth@Exclude
- \PackageWarning{nameauth}%
- {macro \TagName: not tagging exclusion: #2}%
- \else
- \PackageWarning{nameauth}%
- {macro \TagName: not tagging xref: #2}%
- \fi
- \fi
- \else
- \csgdef{\@nameauth@csb!TAG}{#4}%
- \fi
- }%
-% \end{macrocode}
-% Non-Western names, obsolete syntax.
-% \begin{macrocode}
- {%
- \ifcsname\@nameauth@csbc!PN\endcsname
- \if@nameauth@Verbose
- \edef\@nameauth@testex{\csname\@nameauth@csbc!PN\endcsname}%
- \ifx\@nameauth@testex\@nameauth@Exclude
- \PackageWarning{nameauth}%
- {macro \TagName: not tagging exclusion: #2 #3}%
- \else
- \PackageWarning{nameauth}%
- {macro \TagName: not tagging xref: #2 #3}%
- \fi
- \fi
- \else
- \csgdef{\@nameauth@csbc!TAG}{#4}%
- \fi
- }%
-% \end{macrocode}
-% Western names.
+% Verbose warnings let us know if we are sorting either
+% exclusions or cross-references. Do not create a tag if
+% that is the case; otherwise, create a tag.
+%
% \begin{macrocode}
- {%
- \ifcsname\@nameauth@csab!PN\endcsname
- \if@nameauth@Verbose
- \edef\@nameauth@testex{\csname\@nameauth@csab!PN\endcsname}%
- \ifx\@nameauth@testex\@nameauth@Exclude
- \PackageWarning{nameauth}%
- {macro \TagName: not tagging exclusion: #1 #2}%
- \else
- \PackageWarning{nameauth}%
- {macro \TagName: not tagging xref: #1 #2}%
- \fi
+ \ifcsname\NameauthPattern!PN\endcsname
+ \if@nameauth@Verbose
+ \edef\@nameauth@testex
+ {\csname\NameauthPattern!PN\endcsname}%
+ \ifx\@nameauth@testex\@nameauth@Exclude
+ \PackageWarning{nameauth}
+ {\string\TagName: no tag, exclusion \@nameauth@Temp}%
+ \else
+ \PackageWarning{nameauth}
+ {\string\TagName: no tag, xref \@nameauth@Temp}%
\fi
- \else
- \csgdef{\@nameauth@csab!TAG}{#4}%
\fi
- }%
+ \else
+ \csgdef{\NameauthPattern!TAG}{#4}%
+ \fi
}
% \end{macrocode}
% \end{macro}
@@ -8674,35 +13320,37 @@ and version 1.3 or later is part of all distributions of LaTeX version
% \changes{1.2}{2012/02/25}{Added}
% \changes{1.9}{2015/07/09}{Global undef, no cs collisions}
% \changes{2.0}{2015/11/11}{Redesign tagging}
-% \changes{3.5}{2020/11/23}{Optimize logic, fix namespace}
+% \changes{3.5}{2020/11/23}{Improve logic, fix namespace}
+% \changes{3.7}{2023/02/03}{Optimized}
% This deletes an index tag.
+%
% \begin{macrocode}
\newcommandx*\UntagName[3][1=\@empty, 3=\@empty]
{%
\@nameauth@LoadArgs{#1}{#2}{#3}%
\@nameauth@Error{#2}{macro \string\UntagName}%
- \@nameauth@Choice%
- {\global\csundef{\@nameauth@csb!TAG}}%
- {\global\csundef{\@nameauth@csbc!TAG}}%
- {\global\csundef{\@nameauth@csab!TAG}}%
+ \@nameauth@Choice{}{}{}%
+ \global\csundef{\NameauthPattern!TAG}%
}
% \end{macrocode}
% \end{macro}
%
-% \noindent{\normalsize\bfseries Name Info Data Set: ``Text Tags''}
+% \subsubsection{Name Data Tags}
+%
% \begin{macro}{\NameAddInfo}
% \changes{2.4}{2016/03/15}{Added}
-% \changes{3.5}{2020/11/23}{Optimize logic, fix namespace}
-% This creates a macro that expands to information associated with a given name, similar to an index tag, but usable in the body text.
+% \changes{3.5}{2020/11/23}{Improve logic, fix namespace}
+% \changes{3.7}{2023/02/03}{Optimized}
+% 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]
{%
\@nameauth@LoadArgs{#1}{#2}{#3}%
\@nameauth@Error{#2}{macro \string\NameAddInfo}%
- \@nameauth@Choice%
- {\csgdef{\@nameauth@csb!DB}{#4}}%
- {\csgdef{\@nameauth@csbc!DB}{#4}}%
- {\csgdef{\@nameauth@csab!DB}{#4}}%
+ \@nameauth@Choice{}{}{}%
+ \csgdef{\NameauthPattern!DB}{#4}%
}
% \end{macrocode}
% \end{macro}
@@ -8711,21 +13359,20 @@ and version 1.3 or later is part of all distributions of LaTeX version
% \changes{2.4}{2016/03/15}{Added}
% \changes{3.1}{2017/01/13}{Short macro}
% \changes{3.3}{2020/02/20}{Lock added}
-% \changes{3.5}{2020/11/23}{Optimize logic, fix namespace}
+% \changes{3.5}{2020/11/23}{Improve logic, fix namespace}
+% \changes{3.7}{2023/02/03}{Optimized}
% This prints the information created by \cmd{\NameAddInfo} if it exists.
+%
% \begin{macrocode}
\newcommandx*\NameQueryInfo[3][1=\@empty, 3=\@empty]
{%
\unless\if@nameauth@BigLock
\@nameauth@LoadArgs{#1}{#2}{#3}%
\@nameauth@Error{#2}{macro \string\NameQueryInfo}%
- \@nameauth@Choice%
- {\ifcsname\@nameauth@csb!DB\endcsname
- \csname\@nameauth@csb!DB\endcsname\fi}%
- {\ifcsname\@nameauth@csbc!DB\endcsname
- \csname\@nameauth@csbc!DB\endcsname\fi}%
- {\ifcsname\@nameauth@csab!DB\endcsname
- \csname\@nameauth@csab!DB\endcsname\fi}%
+ \@nameauth@Choice{}{}{}%
+ \ifcsname\NameauthPattern!DB\endcsname
+ \csname\NameauthPattern!DB\endcsname%
+ \fi
\fi
}
% \end{macrocode}
@@ -8733,297 +13380,173 @@ and version 1.3 or later is part of all distributions of LaTeX version
%
% \begin{macro}{\NameClearInfo}
% \changes{2.4}{2016/03/15}{Added}
-% \changes{3.5}{2020/11/23}{Optimize logic, fix namespace}
+% \changes{3.5}{2020/11/23}{Improve logic, fix namespace}
+% \changes{3.7}{2023/02/03}{Optimized}
% This deletes a text tag. It has the same structure as \cmd{\UntagName}.
+%
% \begin{macrocode}
\newcommandx*\NameClearInfo[3][1=\@empty, 3=\@empty]
{%
\@nameauth@LoadArgs{#1}{#2}{#3}%
\@nameauth@Error{#2}{macro \string\NameClearInfo}%
- \@nameauth@Choice%
- {\global\csundef{\@nameauth@csb!DB}}%
- {\global\csundef{\@nameauth@csbc!DB}}%
- {\global\csundef{\@nameauth@csab!DB}}%
+ \@nameauth@Choice{}{}{}%
+ \global\csundef{\NameauthPattern!DB}%
}
% \end{macrocode}
% \end{macro}
-% \BigBlank
-% \newpage
%
-% \noindent{\normalsize\bfseries Name Decisions}
+% \subsubsection{Name Decisions}
+%
% \begin{macro}{\IfMainName}
% \changes{2.3}{2016/01/05}{Added}
-% \changes{3.5}{2020/11/23}{Optimize logic, fix namespace, local or global scope}
-% This macro expands one path if a main matter name exists, or else the other. The state of \texttt{\textbackslash if@nameauth@GlobalScope} determines whether or not the paths are in a local scope.
+% \changes{3.5}{2020/11/23}{Improve logic, fix namespace,
+% local or global scope}
+% \changes{3.7}{2023/02/03}{Optimized}
+% This macro expands one path if a main matter name exists, or else the
+% other. The state of \texttt{\textbackslash if@nameauth@GlobalScope}
+% determines whether or not the paths are in a local scope. First we
+% load the arguments into the standard macros, check for error, and
+% get the current name pattern.
+%
% \begin{macrocode}
\newcommandx\IfMainName[5][1=\@empty, 3=\@empty]
{%
\@nameauth@LoadArgs{#1}{#2}{#3}%
\@nameauth@Error{#2}{macro \string\IfMainName}%
- \@nameauth@Choice%
- {%
- \ifcsname\@nameauth@csb!MN\endcsname
- \if@nameauth@GlobalScope
- #4%
- \else
- {#4}%
- \fi
- \else
- \if@nameauth@GlobalScope
- #5%
- \else
- {#5}%
- \fi
- \fi
- }%
- {%
- \ifcsname\@nameauth@csbc!MN\endcsname
- \if@nameauth@GlobalScope
- #4%
- \else
- {#4}%
- \fi
- \else
- \if@nameauth@GlobalScope
- #5%
- \else
- {#5}%
- \fi
- \fi
- }%
- {%
- \ifcsname\@nameauth@csab!MN\endcsname
- \if@nameauth@GlobalScope
- #4%
- \else
- {#4}%
- \fi
- \else
- \if@nameauth@GlobalScope
- #5%
- \else
- {#5}%
- \fi
- \fi
- }%
-}
+ \@nameauth@Choice{}{}{}%
+% \end{macrocode}
+% Take this path if the pattern exists.
+%
+% \begin{macrocode}
+ \ifcsname\NameauthPattern!MN\endcsname
+ \if@nameauth@GlobalScope #4\else {#4}\fi
+ \else
+% \end{macrocode}
+% Take this path if the pattern does not exist.
+%
+% \begin{macrocode}
+ \if@nameauth@GlobalScope #5\else {#5}\fi
+ \fi
+}%
% \end{macrocode}
% \end{macro}
%
% \begin{macro}{\IfFrontName}
% \changes{2.3}{2016/01/05}{Added}
-% \changes{3.5}{2020/11/23}{Optimize logic, fix namespace, local or global scope}
-% This macro expands one path if a front matter name exists, or else the other. The state of \texttt{\textbackslash if@nameauth@GlobalScope} determines whether or not the paths are in a local scope.
+% \changes{3.5}{2020/11/23}{Improve logic, fix namespace,
+% local or global scope}
+% \changes{3.7}{2023/02/03}{Optimized}
+% This macro expands one path if a front matter name exists, or else the
+% other. The state of \texttt{\textbackslash if@nameauth@GlobalScope}
+% determines whether or not the paths are in a local scope. First we
+% load the arguments into the standard macros, check for error, and
+% get the current name pattern.
+%
% \begin{macrocode}
\newcommandx\IfFrontName[5][1=\@empty, 3=\@empty]
{%
\@nameauth@LoadArgs{#1}{#2}{#3}%
\@nameauth@Error{#2}{macro \string\IfFrontName}%
- \@nameauth@Choice%
- {%
- \ifcsname\@nameauth@csb!NF\endcsname
- \if@nameauth@GlobalScope
- #4%
- \else
- {#4}%
- \fi
- \else
- \if@nameauth@GlobalScope
- #5%
- \else
- {#5}%
- \fi
- \fi
- }%
- {%
- \ifcsname\@nameauth@csbc!NF\endcsname
- \if@nameauth@GlobalScope
- #4%
- \else
- {#4}%
- \fi
- \else
- \if@nameauth@GlobalScope
- #5%
- \else
- {#5}%
- \fi
- \fi
- }%
- {%
- \ifcsname\@nameauth@csab!NF\endcsname
- \if@nameauth@GlobalScope
- #4%
- \else
- {#4}%
- \fi
- \else
- \if@nameauth@GlobalScope
- #5%
- \else
- {#5}%
- \fi
- \fi
- }%
+ \@nameauth@Choice{}{}{}%
+% \end{macrocode}
+% Take this path if the pattern exists.
+%
+% \begin{macrocode}
+ \ifcsname\NameauthPattern!NF\endcsname
+ \if@nameauth@GlobalScope #4\else {#4}\fi
+ \else
+% \end{macrocode}
+% Take this path if the pattern does not exist.
+%
+% \begin{macrocode}
+ \if@nameauth@GlobalScope #5\else {#5}\fi
+ \fi
}
% \end{macrocode}
% \end{macro}
+%
% \newpage
%
% \begin{macro}{\IfAKA}
% \changes{2.3}{2016/01/05}{Added}
% \changes{2.4}{2016/03/15}{Test for excluded}
% \changes{3.0}{2016/10/26}{Redesigned}
-% \changes{3.5}{2020/11/23}{New exclusion test, optimize logic, fix namespace, local or global scope}
-% This macro expands one path if a cross-reference exists, another if it does not exist, and a third if it is excluded. The state of \texttt{\textbackslash if@nameauth@GlobalScope} determines whether or not the paths are in a local scope.
+% \changes{3.5}{2020/11/23}{New exclusion test, optimize logic,
+% fix namespace, local or global scope}
+% \changes{3.7}{2023/02/03}{Optimized}
+% This macro expands one path if a cross-reference exists, another if
+% it does not exist, and a third if it is excluded. The state of
+% \texttt{\textbackslash if@nameauth@GlobalScope} determines whether or not
+% the paths are in a local scope. First we load the arguments into
+% the standard macros, check for error, and get the current name pattern.
+%
% \begin{macrocode}
\newcommandx\IfAKA[6][1=\@empty, 3=\@empty]
{%
\@nameauth@LoadArgs{#1}{#2}{#3}%
\@nameauth@Error{#2}{macro \string\IfAKA}%
+ \@nameauth@Choice{}{}{}%
+ \ifcsname\NameauthPattern!PN\endcsname
+ \edef\@nameauth@testex
+ {\csname\NameauthPattern!PN\endcsname}%
% \end{macrocode}
-% For each class of name we test first if a cross-reference exists, then if it is excluded.
+% Take this path if the pattern is an exclusion.
+%
% \begin{macrocode}
- \@nameauth@Choice%
- {%
- \ifcsname\@nameauth@csb!PN\endcsname
- \edef\@nameauth@testex{\csname\@nameauth@csb!PN\endcsname}%
- \ifx\@nameauth@testex\@nameauth@Exclude
- \if@nameauth@GlobalScope
- #6%
- \else
- {#6}%
- \fi
- \else
- \if@nameauth@GlobalScope
- #4%
- \else
- {#4}%
- \fi
- \fi
+ \ifx\@nameauth@testex\@nameauth@Exclude
+ \if@nameauth@GlobalScope #6\else {#6}\fi
\else
- \if@nameauth@GlobalScope
- #5%
- \else
- {#5}%
- \fi
- \fi
- }%
- {%
- \ifcsname\@nameauth@csbc!PN\endcsname
- \edef\@nameauth@testex{\csname\@nameauth@csbc!PN\endcsname}%
- \ifx\@nameauth@testex\@nameauth@Exclude
- \if@nameauth@GlobalScope
- #6%
- \else
- {#6}%
- \fi
- \else
- \if@nameauth@GlobalScope
- #4%
- \else
- {#4}%
- \fi
- \fi
- \else
- \if@nameauth@GlobalScope
- #5%
- \else
- {#5}%
- \fi
- \fi
- }%
- {%
- \ifcsname\@nameauth@csab!PN\endcsname
- \edef\@nameauth@testex{\csname\@nameauth@csab!PN\endcsname}%
- \ifx\@nameauth@testex\@nameauth@Exclude
- \if@nameauth@GlobalScope
- #6%
- \else
- {#6}%
- \fi
- \else
- \if@nameauth@GlobalScope
- #4%
- \else
- {#4}%
- \fi
- \fi
- \else
- \if@nameauth@GlobalScope
- #5%
- \else
- {#5}%
- \fi
+% \end{macrocode}
+% Take this path if the pattern exists.
+%
+% \begin{macrocode}
+ \if@nameauth@GlobalScope #4\else {#4}\fi
\fi
- }%
+ \else
+% \end{macrocode}
+% Take this path if the pattern does not exist.
+%
+% \begin{macrocode}
+ \if@nameauth@GlobalScope #5\else {#5}\fi
+ \fi
}
% \end{macrocode}
% \end{macro}
%
-% \noindent{\normalsize\bfseries Changing Name Decisions}
% \begin{macro}{\ForgetName}
% \changes{1.9}{2015/07/09}{Global undef}
% \changes{2.3}{2016/01/05}{Global or local}
-% \changes{3.5}{2020/11/23}{Optimize logic, fix namespace}
+% \changes{3.5}{2020/11/23}{Improve logic, fix namespace}
+% \changes{3.7}{2023/02/03}{Optimized}
% This undefines a control sequence to force a ``first use''.
+%
% \begin{macrocode}
\newcommandx*\ForgetName[3][1=\@empty, 3=\@empty]
{%
% \end{macrocode}
% Process and load the arguments into the appropriate macros.
+%
% \begin{macrocode}
\@nameauth@LoadArgs{#1}{#2}{#3}%
\@nameauth@Error{#2}{macro \string\ForgetName}%
% \end{macrocode}
-% Now we parse the arguments, undefining the control sequences either by current name type (via |@nameauth@MainFormat|) or completely (toggled by |@nameauth@LocalNames|).
-% \begin{macrocode}
- \@nameauth@Choice%
-% \end{macrocode}
-% Non-Western names.
-% \begin{macrocode}
- {%
- \if@nameauth@LocalNames
- \if@nameauth@MainFormat
- \global\csundef{\@nameauth@csb!MN}%
- \else
- \global\csundef{\@nameauth@csb!NF}%
- \fi
- \else
- \global\csundef{\@nameauth@csb!MN}%
- \global\csundef{\@nameauth@csb!NF}%
- \fi
- }%
-% \end{macrocode}
-% Non-Western names, obsolete syntax.
-% \begin{macrocode}
- {%
- \if@nameauth@LocalNames
- \if@nameauth@MainFormat
- \global\csundef{\@nameauth@csbc!MN}%
- \else
- \global\csundef{\@nameauth@csbc!NF}%
- \fi
- \else
- \global\csundef{\@nameauth@csbc!MN}%
- \global\csundef{\@nameauth@csbc!NF}%
- \fi
- }%
-% \end{macrocode}
-% Western names.
+% Now we parse the arguments, destroying the control sequences either
+% by current name system type or completely. |@nameauth@LocalNames| toggles
+% current system or both, while we select the type of name with
+% |@nameauth@MainFormat|.
+%
% \begin{macrocode}
- {%
- \if@nameauth@LocalNames
- \if@nameauth@MainFormat
- \global\csundef{\@nameauth@csab!MN}%
- \else
- \global\csundef{\@nameauth@csab!NF}%
- \fi
+ \@nameauth@Choice{}{}{}%
+ \if@nameauth@LocalNames
+ \if@nameauth@MainFormat
+ \global\csundef{\NameauthPattern!MN}%
\else
- \global\csundef{\@nameauth@csab!MN}%
- \global\csundef{\@nameauth@csab!NF}%
+ \global\csundef{\NameauthPattern!NF}%
\fi
- }%
+ \else
+ \global\csundef{\NameauthPattern!MN}%
+ \global\csundef{\NameauthPattern!NF}%
+ \fi
}
% \end{macrocode}
% \end{macro}
@@ -9032,67 +13555,39 @@ and version 1.3 or later is part of all distributions of LaTeX version
% \changes{0.9}{2012/02/10}{Added}
% \changes{2.3}{2016/01/05}{Global or local}
% \changes{3.1}{2017/01/13}{Fix old syntax}
-% \changes{3.5}{2020/11/23}{Optimize logic, fix namespace}
+% \changes{3.5}{2020/11/23}{Improve logic, fix namespace}
+% \changes{3.7}{2023/02/03}{Optimized}
% This defines a control sequence to force a ``subsequent use''.
+%
% \begin{macrocode}
\newcommandx*\SubvertName[3][1=\@empty, 3=\@empty]
{%
\@nameauth@LoadArgs{#1}{#2}{#3}%
\@nameauth@Error{#2}{macro \string\SubvertName}%
% \end{macrocode}
-% Now we parse the arguments, defining the control sequences either locally by section type or globally. |@nameauth@LocalNames| toggles the local or global behavior, while we select the type of name with |@nameauth@MainFormat|.
-% \begin{macrocode}
- \@nameauth@Choice%
-% \end{macrocode}
-% Non-Western names.
-% \begin{macrocode}
- {%
- \if@nameauth@LocalNames
- \if@nameauth@MainFormat
- \csgdef{\@nameauth@csb!MN}{}%
- \else
- \csgdef{\@nameauth@csb!NF}{}%
- \fi
- \else
- \csgdef{\@nameauth@csb!MN}{}%
- \csgdef{\@nameauth@csb!NF}{}%
- \fi
- }%
-% \end{macrocode}
-% Non-Western names, obsolete syntax.
-% \begin{macrocode}
- {%
- \if@nameauth@LocalNames
- \if@nameauth@MainFormat
- \csgdef{\@nameauth@csbc!MN}{}%
- \else
- \csgdef{\@nameauth@csbc!NF}{}%
- \fi
- \else
- \csgdef{\@nameauth@csbc!MN}{}%
- \csgdef{\@nameauth@csbc!NF}{}%
- \fi
- }%
-% \end{macrocode}
-% Western names.
+% Now we parse the arguments, defining the control sequences either
+% by current name system type or completely. |@nameauth@LocalNames| toggles
+% current system or both, while we select the type of name with
+% |@nameauth@MainFormat|.
+%
% \begin{macrocode}
- {%
- \if@nameauth@LocalNames
- \if@nameauth@MainFormat
- \csgdef{\@nameauth@csab!MN}{}%
- \else
- \csgdef{\@nameauth@csab!NF}{}%
- \fi
+ \@nameauth@Choice{}{}{}%
+ \if@nameauth@LocalNames
+ \if@nameauth@MainFormat
+ \csgdef{\NameauthPattern!MN}{}%
\else
- \csgdef{\@nameauth@csab!MN}{}%
- \csgdef{\@nameauth@csab!NF}{}%
+ \csgdef{\NameauthPattern!NF}{}%
\fi
- }%
+ \else
+ \csgdef{\NameauthPattern!MN}{}%
+ \csgdef{\NameauthPattern!NF}{}%
+ \fi
}
% \end{macrocode}
% \end{macro}
%
-% \noindent{\normalsize\bfseries Alternate Names}
+% \subsubsection{Pseudonyms}
+%
% \begin{macro}{\AKA}
% \changes{1.26}{2012/04/24}{Fix affixes}
% \changes{1.5}{2013/02/22}{Reversing/caps}
@@ -9105,12 +13600,16 @@ and version 1.3 or later is part of all distributions of LaTeX version
% \changes{3.1}{2017/01/13}{Can skip index}
% \changes{3.3}{2020/02/20}{Global flag reset}
% \changes{3.5}{2020/11/23}{Fix namespace}
-% \cmd{\AKA} prints an alternate name and creates index cross-references. It prevents multiple generation of cross-references and suppresses double periods.
+% \cmd{\AKA} prints an alternate name and creates index cross-references.
+%
% \begin{macrocode}
\newcommandx*\AKA[5][1=\@empty, 3=\@empty, 5=\@empty]
{%
% \end{macrocode}
-% Prevent entering \cmd{\AKA} via itself or \cmd{\@nameauth@Name}. Prevents and resets \cmd{\JustIndex}. Tell the formatting system that \cmd{\AKA} is running.
+% Prevent entering \cmd{\AKA} via itself or \cmd{\@nameauth@Name}.
+% Prevents and resets \cmd{\JustIndex}. Tell the formatting system
+% that \cmd{\AKA} is running.
+%
% \begin{macrocode}
\if@nameauth@BigLock
\@nameauth@Locktrue%
@@ -9125,50 +13624,54 @@ and version 1.3 or later is part of all distributions of LaTeX version
\fi
% \end{macrocode}
% Test for malformed input.
+%
% \begin{macrocode}
\@nameauth@Error{#2}{macro \string\AKA}%
\@nameauth@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.
+% 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@edef\@nameauth@Ai{\trim@spaces{#1}}%
\protected@edef\@nameauth@Bi{\@nameauth@Root{#2}}%
\protected@edef\@nameauth@Si{\@nameauth@Suffix{#2}}%
\@nameauth@Parse{#3}{#4}{#5}{!PN}%
- \def\@nameauth@space{ }%
% \end{macrocode}
-% \newpage\noindent
-% Create an index cross-reference based on the arguments.
+% \noindent Create an index cross-reference based on the arguments.
+%
% \begin{macrocode}
\unless\if@nameauth@SkipIndex
\ifx\@nameauth@Ai\@empty
\ifx\@nameauth@Si\@empty
\IndexRef[#3]{#4}[#5]{\@nameauth@Bi}%
\else
- \IndexRef[#3]{#4}[#5]%
- {\@nameauth@Bi\@nameauth@space%
- \@nameauth@Si}%
+ \IndexRef[#3]{#4}[#5]
+ {\@nameauth@Bi\@nameauth@space\@nameauth@Si}%
\fi
\else
\ifx\@nameauth@Si\@empty
- \IndexRef[#3]{#4}[#5]%
+ \IndexRef[#3]{#4}[#5]
{\@nameauth@Bi,\@nameauth@space\@nameauth@Ai}%
\else
- \IndexRef[#3]{#4}[#5]%
- {\@nameauth@Bi,\@nameauth@space%
+ \IndexRef[#3]{#4}[#5]
+ {\@nameauth@Bi,\@nameauth@space
\@nameauth@Ai,\@nameauth@space\@nameauth@Si}%
\fi
\fi
\fi
% \end{macrocode}
% Reset all the ``per name'' Boolean values. The default is global.
+%
% \begin{macrocode}
\@nameauth@Flags%
\@nameauth@Lockfalse%
\@nameauth@InAKAfalse%
% \end{macrocode}
-% Close the ``locked'' branch and call the full stop detection. This conditional statement must be on one line.
+% Close the ``locked'' branch and call the full stop detection.
+% This conditional statement must be on one line.
+%
% \begin{macrocode}
\fi
\if@nameauth@Punct\expandafter\@nameauth@CheckDot\fi
@@ -9178,7 +13681,9 @@ and version 1.3 or later is part of all distributions of LaTeX version
%
% \begin{macro}{\AKA*}
% \changes{0.9}{2012/02/10}{Added}
-% This starred form sets a Boolean to print only the alternate name argument, if that exists, and calls \cmd{\AKA}.
+% This starred form sets a Boolean to print only the alternate name argument,
+% if that exists, and calls \cmd{\AKA}.
+%
% \begin{macrocode}
\WithSuffix{\newcommand*}\AKA*{\@nameauth@AltAKAtrue \AKA}
% \end{macrocode}
@@ -9188,12 +13693,15 @@ and version 1.3 or later is part of all distributions of LaTeX version
% \changes{2.3}{2016/01/05}{Work with hooks}
% \changes{3.1}{2017/01/13}{Can skip index}
% \changes{3.5}{2020/11/23}{Warning and flag resets added}
+% \changes{3.7}{2023/02/03}{Fix warnings}
% \cmd{\PName} is a convenience macro that calls \cmd{\NameauthName}, then \cmd{\AKA}.
+%
% \begin{macrocode}
\newcommandx*\PName[5][1=\@empty,3=\@empty,5=\@empty]
{%
% \end{macrocode}
% If we used \cmd{\JustIndex}, we ignore and reset its flag to false.
+%
% \begin{macrocode}
\if@nameauth@OldReset
\@nameauth@JustIndexfalse%
@@ -9201,7 +13709,9 @@ and version 1.3 or later is part of all distributions of LaTeX version
\global\@nameauth@JustIndexfalse%
\fi
% \end{macrocode}
-% If we used \cmd{\SkipIndex}, we reset the flag of \cmd{\SeeAlso} and activate \cmd{\SkipIndex}for both \cmd{\NameauthName} and \cmd{\AKA}.
+% If we used \cmd{\SkipIndex}, we reset the flag of \cmd{\SeeAlso} and
+% activate \cmd{\SkipIndex} for both \cmd{\NameauthName} and \cmd{\AKA}.
+%
% \begin{macrocode}
\if@nameauth@SkipIndex
\unless\if@nameauth@OldReset
@@ -9210,7 +13720,10 @@ and version 1.3 or later is part of all distributions of LaTeX version
\NameauthName[#1]{#2} (\SkipIndex\AKA[#1]{#2}[#3]{#4}[#5])%
\else
% \end{macrocode}
-% Otherwise, if we used \cmd{\SeeAlso} we set the flag of \cmd{\SeeAlso} false for \cmd{\NameauthName} and true for \cmd{\AKA}. The ``normal'' case after that is trivial.
+% Otherwise, if we used \cmd{\SeeAlso} we set the flag of \cmd{\SeeAlso}
+% false for \cmd{\NameauthName} and true for \cmd{\AKA}. The ``normal''
+% case after that is trivial.
+%
% \begin{macrocode}
\if@nameauth@SeeAlso
\@nameauth@SeeAlsofalse\NameauthName[#1]{#2}
@@ -9221,11 +13734,13 @@ and version 1.3 or later is part of all distributions of LaTeX version
\fi
\fi
% \end{macrocode}
-% Warn if \cmd{\SkipIndex} remains in effect (potentially due to the \texttt{oldreset} option). Normally, this state should not occur.
+% Warn if \cmd{\SkipIndex} remains in effect (potentially due to
+% the \texttt{oldreset} option). Normally, this state should not occur.
+%
% \begin{macrocode}
\if@nameauth@SkipIndex
- \PackageWarning{nameauth}%
- {\SkipIndex still active after \PName; check for problems}%
+ \PackageWarning{nameauth}
+ {\string\SkipIndex still active after \string\PName; check}%
\fi
}
% \end{macrocode}
@@ -9233,146 +13748,21 @@ and version 1.3 or later is part of all distributions of LaTeX version
%
% \begin{macro}{\PName*}
% This sets up a long name reference and calls \cmd{\PName}.
+%
% \begin{macrocode}
\WithSuffix{\newcommand*}\PName*{\@nameauth@FullNametrue \PName}
% \end{macrocode}
% \end{macro}
%
-% \noindent{\normalsize\bfseries Quick Interface}
-% \begin{environment}{nameauth}
-% \changes{1.6}{2013/03/10}{Environment added}
-% \changes{2.0}{2015/11/11}{Better arg handling}
-% \changes{2.41}{2016/03/17}{No local \cmd{\newtoks}}
-% \changes{3.5}{2020/11/23}{Fix namespace}
-% The \texttt{nameauth} environment creates macro shorthands. First we define a control sequence \cmd{\<} that takes four parameters, delimited by three ampersands and \texttt{>}. This macro is defined only within the \texttt{nameauth} environment, but the shorthand macros that it creates are globally defined.
-% \begin{macrocode}
-\newenvironment{nameauth}{%
- \begingroup%
- \let\ex\expandafter%
- \csdef{<}##1&##2&##3&##4>{%
- \protected@edef\@arga@{\trim@spaces{##1}}%
- \protected@edef\@larga@{L\trim@spaces{##1}}%
- \protected@edef\@sarga@{S\trim@spaces{##1}}%
- \protected@edef\@testb@{\trim@spaces{##2}}%
- \protected@edef\@testd@{\trim@spaces{##4}}%
- \@nameauth@etoksb\ex{##2}%
- \@nameauth@etoksc\ex{##3}%
- \@nameauth@etoksd\ex{##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 argument. Redefining a shorthand creates a warning.
-% \begin{macrocode}
- \ifx\@arga@\@empty
- \PackageError{nameauth}%
- {environment nameauth: Control sequence missing}%
- \fi
- \@nameauth@Error{##3}{environment nameauth}%
- \ifcsname\@arga@\endcsname
- \PackageWarning{nameauth}%
- {environment nameauth: Shorthand macro already exists}%
- \fi
-% \end{macrocode}
-% Set up shorthands according to name form. We have to use \cmd{\ex}, not the \(\epsilon\)-\TeX{} way, due to \cmd{\protected@edef} in the naming macros.
-% \newpage
-%
-% We begin with mononyms and non-Western names that use the new syntax. We use one \cmd{\ex} per token because we only have one argument to expand first.
-% \begin{macrocode}
- \ifx\@testd@\@empty
- \ifx\@testb@\@empty
- \ex\csgdef\ex{\ex\@arga@\ex}%
- \ex{\ex\NameauthName\ex{\the\@nameauth@etoksc}}%
- \ex\csgdef\ex{\ex\@larga@\ex}%
- \ex{\ex\@nameauth@FullNametrue%
- \ex\NameauthLName\ex{\the\@nameauth@etoksc}}%
- \ex\csgdef\ex{\ex\@sarga@\ex}%
- \ex{\ex\@nameauth@FirstNametrue%
- \ex\NameauthFName\ex{\the\@nameauth@etoksc}}%
- \else
-% \end{macrocode}
-% 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{\ex} 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@etoksb\ex]%
- \ex{\the\@nameauth@etoksc}}%
- \ex\ex\ex\csgdef\ex\ex\ex{\ex\ex\ex\@larga@\ex\ex\ex}%
- \ex\ex\ex{\ex\ex\ex\@nameauth@FullNametrue%
- \ex\ex\ex\NameauthLName%
- \ex\ex\ex[\ex\the\ex\@nameauth@etoksb\ex]%
- \ex{\the\@nameauth@etoksc}}%
- \ex\ex\ex\csgdef\ex\ex\ex{\ex\ex\ex\@sarga@\ex\ex\ex}%
- \ex\ex\ex{\ex\ex\ex\@nameauth@FirstNametrue%
- \ex\ex\ex\NameauthFName%
- \ex\ex\ex[\ex\the\ex\@nameauth@etoksb\ex]%
- \ex{\the\@nameauth@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{\ex} 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@etoksc\ex}%
- \ex[\the\@nameauth@etoksd]}%
- \ex\ex\ex\csgdef\ex\ex\ex{\ex\ex\ex\@larga@\ex\ex\ex}%
- \ex\ex\ex{\ex\ex\ex\@nameauth@FullNametrue%
- \ex\ex\ex\NameauthLName%
- \ex\ex\ex{\ex\the\ex\@nameauth@etoksc\ex}%
- \ex[\the\@nameauth@etoksd]}%
- \ex\ex\ex\csgdef\ex\ex\ex{\ex\ex\ex\@sarga@\ex\ex\ex}%
- \ex\ex\ex{\ex\ex\ex\@nameauth@FirstNametrue%
- \ex\ex\ex\NameauthFName%
- \ex\ex\ex{\ex\the\ex\@nameauth@etoksc\ex}%
- \ex[\the\@nameauth@etoksd]}%
- \else
-% \end{macrocode}
-% \newpage\noindent
-% Here are Western names with alternates. We have three arguments to expand, so we have seven, three, and one respective use of \cmd{\ex}.
-% \begin{macrocode}
- \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@etoksb\ex\ex\ex]%
- \ex\ex\ex{\ex\the\ex\@nameauth@etoksc\ex}%
- \ex[\the\@nameauth@etoksd]}%
- \ex\ex\ex\ex\ex\ex\ex\csgdef\ex\ex\ex\ex\ex\ex\ex{%
- \ex\ex\ex\ex\ex\ex\ex\@larga@\ex\ex\ex\ex\ex\ex\ex}%
- \ex\ex\ex\ex\ex\ex\ex{%
- \ex\ex\ex\ex\ex\ex\ex\@nameauth@FullNametrue%
- \ex\ex\ex\ex\ex\ex\ex\NameauthLName%
- \ex\ex\ex\ex\ex\ex\ex[\ex\ex\ex\the\ex\ex\ex%
- \@nameauth@etoksb\ex\ex\ex]%
- \ex\ex\ex{\ex\the\ex\@nameauth@etoksc\ex}%
- \ex[\the\@nameauth@etoksd]}%
- \ex\ex\ex\ex\ex\ex\ex\csgdef\ex\ex\ex\ex\ex\ex\ex{%
- \ex\ex\ex\ex\ex\ex\ex\@sarga@\ex\ex\ex\ex\ex\ex\ex}%
- \ex\ex\ex\ex\ex\ex\ex{%
- \ex\ex\ex\ex\ex\ex\ex\@nameauth@FirstNametrue%
- \ex\ex\ex\ex\ex\ex\ex\NameauthFName%
- \ex\ex\ex\ex\ex\ex\ex[\ex\ex\ex\the\ex\ex\ex%
- \@nameauth@etoksb\ex\ex\ex]%
- \ex\ex\ex{\ex\the\ex\@nameauth@etoksc\ex}%
- \ex[\the\@nameauth@etoksd]}%
- \fi
- \fi\ignorespaces%
- }\ignorespaces%
-}{\endgroup\ignorespaces}
-% \end{macrocode}
-% \end{environment}
% \Finale
% \endinput
%</package>
-%<*examples>
-%<<examplesvb
-\documentclass[oneside]{article}
-%
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-% Backward compatibility for older distributions of LaTeX.
-%
-% Include the iftex package only if it exists. If the iftex
-% package is older than 2019, include additional packages
-% that aid using multiple LaTeX engines.
+%<*compat>
+%<<compatvb
+
+% This snippet assists backward compatibility for older
+% distributions of LaTeX and compatibility for multiple
+% LaTeX engines. It is not a standalone document.
%
\IfFileExists{iftex.sty}{\usepackage{iftex}}{}
\unless\ifdefined\RequireTUTeX
@@ -9380,10 +13770,7 @@ and version 1.3 or later is part of all distributions of LaTeX version
\usepackage{ifluatex}
\usepackage{ifpdf}
\fi
-%
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-% Compatibility for multiple LaTeX engines.
-%
+
\ifxetex
\usepackage{fontspec}
\usepackage{polyglossia}
@@ -9409,1133 +13796,803 @@ and version 1.3 or later is part of all distributions of LaTeX version
\usepackage{lmodern}
\fi
\fi
-%
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-% Remainder of package inclusions
-%
+
+%compatvb
+%</compat>
+%<*examples>
+%<<examplesvb
+
+\documentclass[oneside]{article}
+
+\input{compat.tex} % Included with nameauth; needed only if
+% compiling on multiple TeX distros or LaTeX engines.
+
\usepackage[textwidth=137mm,textheight=237mm,
- right=25mm,marginparwidth=39mm,nohead]{geometry}
-\usepackage{booktabs}
-\usepackage{colortbl}
+ right=40mm,marginparwidth=40mm]{geometry}
\usepackage{index}
-\usepackage{nameauth}[2021/02/27]
-\usepackage{verbatim}
+\usepackage{nameauth}[2023/02/03]
+\usepackage[inline]{enumitem}
+\usepackage{fancyvrb}
+
+% Define fancyvrb defaults.
+\fvset{gobble=2,numbers=left,fontsize=\small}
+
\usepackage{xcolor}
-\colorlet{grey}{black!7!white}
\usepackage[colorlinks=true]{hyperref}
%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-% We set up indexing, put margin paragraphs on the left,
-% and set up the counter for line numbering in verbatim
-% environments.
+% Set up indexing and put margin paragraphs on the left.
%
\makeindex
\newindex{per}{rdx}{rnd}{Index of Persons}
\renewcommand\NameauthIndex{\index[per]}
\reversemarginpar
-\newcounter{VerbLine}
-%
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-% Global definitions of conditionals for examples
-% For Scipio Africanus
-\newif\ifSkipGens
-\newif\ifNoGens
-\newif\ifSkipAgnomen
-\newif\ifNoAgnomen
-% For Thomas Jefferson
-\newif\ifGenitive
-\newif\ifDoGen
-% For George Washington/Mustafa Kemal
-\newif\ifNoTag
-% For William Shakespeare
-\newif\ifSpecialFN
-\newif\ifSpecialSN
-\newif\ifRevertSN
-% For advanced hooks
-\newif\ifFbox
-\newif\ifFirstCap
-\newif\ifInHook
-\Fboxtrue
-\newif\ifCaps
%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-% Global definitions of macros for examples
-% For Scipio Africanus
-\newcommand*\SCIPi{\ifNoGens
- Publius\else Publius Cornelius\fi}
-\newcommand*\SCIPii{\ifNoAgnomen
- Scipio\else Scipio Africanus\fi}
-\newcommand*\ScipioOnly{\SkipAgnomentrue\Scipio}
-\newcommand*\CSA{\ifNoGens\ifNoAgnomen
- Scipio\else
- Scipio Africanus\fi
- \else\ifNoAgnomen
- Cornelius Scipio\else
- Cornelius Scipio Africanus\fi\fi}
-\ExcludeName[Publius]{\noexpand\CSA}
-% For Thomas Jefferson
-\newcommand\JEFF{\ifDoGen\textSC{Jefferson's}\else\textSC{Jefferson}\fi}
-% For William Shakespeare
-\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}
+% Global definitions of conditionals for examples and
+% Global definitions of macros for examples could occur
+% here, but we put those instead in the sections where
+% they appear.
%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-% We include a few macros from ltxdoc.cls and doc.sty.
-% These are copyright by the LaTeX dev team.
-%
-\makeatletter
-\DeclareRobustCommand\meta[1]{%
- \ensuremath\langle
- \ifmmode \expandafter \nfss@text \fi
- {%
- \meta@font@select
- \edef\meta@hyphen@restore
- {\hyphenchar\the\font\the\hyphenchar\font}%
- \hyphenchar\font\m@ne
- \language\l@nohyphenation
- #1\/%
- \meta@hyphen@restore
- }\ensuremath\rangle
-}
-\def\meta@font@select{\itshape}
-\def\cmd#1{\cs{\expandafter\cmd@to@cs\string#1}}
-\def\cmd@to@cs#1#2{\char\number`#2\relax}
-\DeclareRobustCommand\cs[1]{\texttt{\char`\\#1}}
-\providecommand\marg[1]{%
- {\ttfamily\char`\{}\meta{#1}{\ttfamily\char`\}}}
-\providecommand\oarg[1]{%
- {\ttfamily[}\meta{#1}{\ttfamily]}}
-\providecommand\parg[1]{%
- {\ttfamily(}\meta{#1}{\ttfamily)}}
-\makeatother
-%
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-% We establish name shorthands. Note the heavy use of \noexpand
-% in the macro arguments below. This is intrinsic to the proper
-% function of such arguments (advanced alternate formatting).
+% Create name shorthands. Note the use of \noexpand
+% in the macro arguments below.
%
\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 & >
- \< OScipio & Publius & \noexpand\CSA & >
- \< Shak & \noexpand\WM & \noexpand\SHK & >
- \< Sutorius & Quintus & \noexpand\SUTOR & >
- \< Wash & George & Washington & >
+ \< Doug & Frederick & Douglass & >
+ \< Bailey & Betsey & Bailey & >
+\end{nameauth}
+
+\begin{nameauth}
+ \< Wash & George & Washington & >
+ \< Aris & & Aristotle & >
+ \< Plato & & Plato & >
+ \< Aeth & & Æthelred, II & >
+ \< Sun & & Sun, Yat-sen & >
+ \< Linc & Abraham & Lincoln & >
+ \< MLK & Martin Luther & King, Jr. & >
+ \< Soto & Hernando & de Soto & >
+ \< Goethe & J.W. von & Goethe & >
+ \< Patton & George S. & Patton, Jr. & >
+ \< Ike & Dwight D. & Eisenhower & >
+\end{nameauth}
+
+\begin{nameauth}
+ \< Luth & Martin & \noexpand\textSC{Luther} & >
+ \< Cath & Catherine \noexpand\AltCaps{d}e'
+ & \noexpand\textSC{Medici} & >
+\end{nameauth}
+
+\begin{nameauth}
+ \< Jeff & Thomas &
+ \noexpand\textSC{Jefferson}\noexpand\GEN{} & >
+\end{nameauth}
+
+\begin{nameauth}
+ \< Scipio & \noexpand\SCIPi & \noexpand\SCIPii & >
+ \< TGrac & \noexpand\TSemp & Gracchus & >
+\end{nameauth}
+
+\begin{nameauth}
+ \< OScipio & Lucius & \noexpand\CSB & > % O for Oxford
\end{nameauth}
+
+\begin{nameauth}
+ \< Shak & \noexpand\WM & \noexpand\SHK & >
+\end{nameauth}
+
+\begin{nameauth}
+ \< deSmet & Pierre-Jean &
+ \noexpand\Fbox{\noexpand\AltCaps{d}e~Smet} & >
+\end{nameauth}
+
%
% We could add name info database tags (text tags) either
% in the preamble or in the document environment. We will do
% the latter in this example file.
%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-% Below we establish sort tags for names. We also can do that
-% later on in the body text. Note again the consistent use of
-% \noexpand with alternate formatting.
+% Below we establish sort tags for names.
%
-\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[Publius]{\noexpand\CSA}{Cornelius 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}
-%
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-% We set up line numbering in verbatim environments.
-%
-\makeatletter
-\newcommand*\ClearNum{\def\verbatim@processline{\the\verbatim@line\par}}
-\newcommand*\StartNum{\setcounter{VerbLine}{0}\def\verbatim@processline{\stepcounter{VerbLine}\leavevmode\llap{\footnotesize\normalfont\theVerbLine\quad}\the\verbatim@line\par}}
-\newcommand*\ContinueNum{\def\verbatim@processline{\stepcounter{VerbLine}\leavevmode\llap{\footnotesize\normalfont\theVerbLine\quad}\the\verbatim@line\par}}
-\makeatother
-%
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-% The default verbatim format is no line numbers.
-% We add title, author, and date.
-%
-\ClearNum
-\title{\bfseries Longer Examples}
-\author{Charles P. Schaum}
-\date{2021/02/27}
+% Sort these names under: US Presidents.
+\PretagName[George]{Washington}{US Presidents!Washington, George}
+\PretagName[Abraham]{Lincoln}{US Presidents!Lincoln, Abraham}
-\begin{document}
-\maketitle
+% Sort these names under: Philosophers.
+\PretagName{Aristotle}{Philosophers!Aristotle}
+\PretagName{Plato}{Philosophers!Plato}
-\phantomsection
-\pdfbookmark[1]{\contentsname}{toc}
-\tableofcontents
-\newpage
-
-\section{Particles}
+% Sort these names under: Black Americans, famous.
+\PretagName[Frederick]{Douglass}
+ {Black Americans, famous!Douglass, Frederick}
+\PretagName[Betsey]{Bailey}
+ {Black Americans, famous!Bailey, Betsey}
+\PretagName[Martin Luther]{King, Jr.}
+ {Black Americans, famous!King, Martin Luther, Jr.}
-First we use variants with the \meta{Alternate} argument:
+% Sort these names under: Europeans, historical.
+\PretagName{Æthelred, II}{Europeans, historical!Aethelred 2}
+\PretagName[Hernando]{de Soto}
+ {Europeans, historical!de Soto, Hernando}
-\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}
-
- \smallskip
- \begin{tabular}{ll}\toprule
- \cmd{\Dem[I Soter]} & \Dem[I Soter]\\
- \rowcolor{grey}%
- \cmd{\LDem} & \LDem\\
- \cmd{\Dem} & \Dem\\\bottomrule
- \end{tabular}
- \end{quote}
-
-\begingroup%
-\makeatletter
-\renewcommand*\NamesFormat[1]{%
- \begingroup%
- \protected@edef\temp{\endgroup%
- {#1\noexpand\NameQueryInfo
- [\unexpanded\expandafter{\the\@nameauth@toksa}]
- {\unexpanded\expandafter{\the\@nameauth@toksb}}
- [\unexpanded\expandafter{\the\@nameauth@toksc}]%
- }%
- }%
- \temp%
-}
-\makeatother
-For a more automated approach, we use ``text tags'':
+\PretagName{Vlad, Ţepeş}{Vlad Tepes} % for accented names
-\begin{quote}\small
-\ContinueNum
-\begin{verbatim}
-\makeatletter
-\makeatletter
-\renewcommand*\NamesFormat[1]{%
- \begingroup%
- \protected@edef\temp{\endgroup%
- {#1\noexpand\NameQueryInfo
- [\unexpanded\expandafter{\the\@nameauth@toksa}]
- {\unexpanded\expandafter{\the\@nameauth@toksb}}
- [\unexpanded\expandafter{\the\@nameauth@toksc}]%
- }%
- }%
- \temp%
-}
-\makeatother
-\end{verbatim}
-
-\smallskip
- \begin{tabular}{ll}\toprule
- \cmd{\ForgetThis}\cmd{\Dem} & \ForgetThis\Dem\\
- \rowcolor{grey}%
- \cmd{\LDem} & \LDem\\
- \cmd{\Dem} & \Dem\\\bottomrule
- \end{tabular}
-\end{quote}
-\endgroup
+\PretagName[Konrad]{\noexpand\textSC{Zuse}}{Zuse, Konrad}
+\PretagName[Ada]{\noexpand\textIT{Lovelace}}{Lovelace, Ada}
+\PretagName[Charles]{\noexpand\textBF{Babbage}}
+ {Babbage, Charles}
+\PretagName{\noexpand\textUC{Kanade}, Takeo}{Kanade Takeo}
-\vfil
-\noindent And now for something completely different\dots
+\PretagName[Martin]{\noexpand\textSC{Luther}}{Luther, Martin}
+\PretagName[Catherine \noexpand\AltCaps{d}e']
+ {\noexpand\textSC{Medici}}{Medici, Catherine de}
- We mention the Electric Boogaloo\index{Boogaloo, Electric}
- by \Name{Ollie~\& Jerry}.\\
+\PretagName[Thomas]{\noexpand\textSC{Jefferson}\noexpand\GEN{}}
+ {Jefferson, Thomas}
-\noindent The index references made here will put:
+\PretagName[Greta]{\noexpand\textSC{Garbo}}{Garbo, Greta}
+\PretagName{\noexpand\textSC{Misora}, Hibari}{Misora Hibari}
+\PretagName[Heinz]{\noexpand\textSC{R\"uhmann}}{Ruehmann, Heinz}
+\PretagName[Heinrich Wilhelm]{\noexpand\textSC{R\"uhmann}}
+ {Ruehmann, Heinrich Wilhelm}
- ``Boogaloo, Electric'' in the main index
-
- and ``\ShowIdxPageref*{Ollie~\& Jerry}'' in the index of names.
-\newpage
+\PretagName[\noexpand\SCIPi]{\noexpand\SCIPii}
+ {Scipio Africanus}
+\PretagName[\noexpand\TSemp]{Gracchus}
+ {Gracchus, Tiberius Sempronius}
-\section{Roman Names}
+\PretagName[Lucius]{\noexpand\CSB}{Cornelius Scipio Barbatus}
- We define all macros and conditionals used in naming macro arguments in the preamble. We use \cmd{\noexpand} in the naming macro arguments to prevent error. Since we do not use \cmd{\CapThis} in the examples below, we skip alternate formatting for simplicity, yet we still recommend it:
- \begin{quote}\small
- \StartNum
- \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}
-\begin{nameauth}
- \< Scipio & \noexpand\SCIPi & \noexpand\SCIPii & >
-\end{nameauth}
-\PretagName[\noexpand\SCIPi]{\noexpand\SCIPii}{Scipio Africanus}\end{verbatim}
- \end{quote}
-
- We begin a new scope below, redefining the formatting hooks, which affect only names printed in the text. If the local Boolean flags are false, one gets longer name forms. If the flags are true, one gets shorter forms. This approach allows the global state of the flags to be false by default, meaning that one need not remember to set any of them true in the preamble. That results in one less thing to remember, and one less problem to fix.
-\begingroup
-\renewcommand*\NamesFormat[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
- \ContinueNum
- \begin{verbatim}
-\renewcommand*\NamesFormat[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}\end{verbatim}
- \end{quote}
+\PretagName[\noexpand\WM]{\noexpand\SHK}
+ {Shakespeare, William}
+\PretagName[Robert]{\textSC{Burns}}{Burns, Robert}
- The index always shows the name determined by the global state of \cmd{\NoGens} and \cmd{\NoAgnomen}, which we set up as false, meaning a maximally long name form. In the body text we have:
- \begin{quote}\small
- \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}
+\PretagName[Pierre-Jean]%
+ {\noexpand\Fbox{\noexpand\AltCaps{d}e~Smet}}%
+ {de~Smet, Pierre-Jean}
+%
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+% Below we establish some index tags for names.
+%
+\TagName[George S.]{Patton, Jr.}{, general}
+\TagName{Vlad, II}{ Dracul}
+\TagName{Vlad, III}{ Dracula}
+\IndexRef{Dracula}{Vlad III}
+\TagName[Thomas]{\noexpand\textSC{Jefferson}\noexpand\GEN{}}
+ {, pres.}
+\TagName[\noexpand\TSemp]{Gracchus}{, consul}
+\TagName[Lucius]{\noexpand\CSB}{, consul}
- Below we show more information about popular name forms by way of comparison with scholarly name forms.\medskip
+%
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%
- The \textit{Oxford Classical Dictionary} and other scholarly sources index according to the \textit{nomen}. That approach moves the \textit{nomen} from \meta{FNN} to \meta{SNN}.
+\title{\bfseries Collected Examples}
+\author{Charles P. Schaum}
+\date{2023/02/03}
- The two methods do not clash \textit{per se} in the text, but they make incompatible index entries. In this case, since we have indexed \ScipioOnly\ under the popular form above, we use \cmd{\ExcludeName} to exclude the scholarly form below.
+\begin{document}
+\maketitle
- In the document preamble we define the following Boolean flags and macros. We use a nested conditional in \meta{SNN}. The default still is to show all names so that they can be indexed that way:
- \begin{quote}\small
- \StartNum
- \begin{verbatim}
-\newif\ifSkipGens % These flags remain the same as above.
-\newif\ifNoGens
-\newif\ifSkipAgnomen
-\newif\ifNoAgnomen
-\global\def\CSA{\ifNoGens\ifNoAgnomen
- Scipio\else
- Scipio Africanus\fi
- \else\ifNoAgnomen
- Cornelius Scipio\else
- Cornelius Scipio Africanus\fi\fi}
-\ExcludeName[Publius]{\noexpand\CSA}
-\begin{nameauth}
- \< OScipio & Publius & \noexpand\CSA & > % O for Oxford
-\end{nameauth}
-\PretagName[Publius]{\noexpand\CSA}{Cornelius Scipio Africanus}\end{verbatim}
- \end{quote}
-
- We keep the same formatting macros that we defined above. By the way, these formatting macros could work with regular names as well as Roman names, e.g., \LDem, because they have no side effects.
-
- The scholarly form of Roman names has a different name pattern, so it is not compatible with the popular version. Nevertheless, we show what the index entries would be in a normal \LaTeX\ document without hyperlinks:
- \begin{quote}\small\IndexActual{@}
- \textbf{Simplified Name Patterns:}\\
- Scholarly: \texttt{\ShowPattern[Publius]{\noexpand\CSA}}\\
- \setbox0\hbox{Scholarly:}\hbox to \wd0{Popular:\hfill} \texttt{\ShowPattern[\noexpand\SCIPi]{\noexpand\SCIPii}}\\
-
- \textbf{Full Index Entries:}
- \UntagName[Publius]{\noexpand\CSA}
- \UntagName[\noexpand\SCIPi]{\noexpand\SCIPii}\\
- Scholarly:\\ \hbox{}\quad\texttt{\ShowIdxPageref[Publius]{\noexpand\CSA}}\\
- Popular:\\ \hbox{}\quad\texttt{\ShowIdxPageref[\noexpand\SCIPi]{\noexpand\SCIPii}}
- \TagName[Publius]{\noexpand\CSA}{\string|hyperpage}
- \TagName[\noexpand\SCIPi]{\noexpand\SCIPii}{\string|hyperpage}\\
-
- \textbf{Basic Index Entries:}\\
- \UntagName[Publius]{\noexpand\CSA}
- Scholarly:\\ \hbox{}\quad\ShowIdxPageref*[Publius]{\noexpand\CSA}\\
- Popular:\\ \hbox{}\quad\ShowIdxPageref*[\noexpand\SCIPi]{\noexpand\SCIPii}
- \end{quote}
-
- Below we compare some differences between the scholarly and popular forms, and how to get equivalent forms in the text while understanding that they would be two separate forms in the index.
- \begin{center}\small
- \begin{tabular}{p{0.51\textwidth}@{\ \ }l}
- \multicolumn{2}{l}{\textbf{First use:}}\\
- scholarly:\dotfill \cmd{\OScipio} & \OScipio\\
- popular:\dotfill \cmd{\Scipio} & \ForgetThis\Scipio\\[2ex]
-
- \multicolumn{2}{l}{\textbf{Subsequent use:}}\\
- scholarly:\dotfill \cmd{\OScipio} & \OScipio\\
- scholarly:\dotfill \cmd{\SkipGenstrue}\cmd{\OScipio} & \SkipGenstrue\OScipio\\
- popular:\dotfill \cmd{\Scipio} & \SkipGenstrue\Scipio\\[2ex]
-
- \multicolumn{2}{l}{\textbf{Subsequent use, full, no \textit{agnomen}:}}\\
- scholarly:\dotfill \cmd{\SkipAgnomentrue}\cmd{\LOScipio} & \SkipAgnomentrue\LOScipio\\
- popular:\dotfill \cmd{\SkipAgnomentrue}\cmd{\LScipio} & \SkipAgnomentrue\LScipio\\[2ex]
-
- \multicolumn{2}{l}{\textbf{Subsequent use, shortest forms:}}\\
- scholarly:\dotfill \cmd{\SkipAgnomentrue}\cmd{\OScipio} & \SkipAgnomentrue\OScipio\\
- \hfill\cmd{\SkipGenstrue}\cmd{\SkipAgnomentrue}\cmd{\OScipio} & \SkipGenstrue\SkipAgnomentrue\OScipio\\
- popular:\dotfill \cmd{\SkipAgnomentrue}\cmd{\Scipio\ } & \SkipAgnomentrue\Scipio\\[2ex]
-
- \multicolumn{2}{l}{\textbf{Subsequent use, personal name:}}\\
- scholarly:\dotfill \cmd{\SOScipio} & \SOScipio\\
- popular:\dotfill \cmd{\SScipio} & \SScipio\\
- popular:\dotfill \cmd{\SkipGenstrue}\cmd{\SScipio} & \SkipGenstrue\SScipio
- \end{tabular}
- \end{center}
- \endgroup
+\phantomsection
+\pdfbookmark[1]{\contentsname}{toc}
+\tableofcontents
\newpage
-\section{Inflected Name Forms}
+\section{Minimal Example}
-\begingroup
-Below we use alternate formatting, sort index entries, and set up a cross-reference, then redefine the hook macros locally.
-\AltFormatActive
- \renewcommand*\NamesFormat[1]{\ifGenitive\DoGentrue\fi#1\global\Genitivefalse}
- \renewcommand*\MainNameHook[1]{\ifGenitive\DoGentrue\fi\AltOff#1\global\Genitivefalse}
- \begin{quote}\small
- \StartNum
- \begin{verbatim}
-\begin{nameauth}
- \< Jeff & Thomas & \noexpand\JEFF & >
-\end{nameauth}
-\PretagName[Thomas]{\noexpand\JEFF}{Jefferson, Thomas}
-\TagName[Thomas]{\noexpand\JEFF}{, president}
-\renewcommand*\NamesFormat[1]
- {\ifGenitive\DoGentrue\fi#1\global\Genitivefalse}
-\renewcommand*\MainNameHook[1]
- {\ifGenitive\DoGentrue\fi\AltOff#1\global\Genitivefalse}
+\begin{enumerate*}
+ \item[\textbf{1.}] \Doug\ rose to eminence by sheer force
+ of character and talents that neither slavery nor caste
+ proscription could crush.
+ \item[\textbf{2.}] \Doug's early life is perhaps the most
+ complete indictment of the slave system ever presented at
+ the bar of public opinion.
+ \item[\textbf{3.}] \Doug\ was born in February, l8l7. His
+ earliest memories centered around the cabin of his
+ grandmother, \Bailey.\\
+\end{enumerate*}
+\index{example, minimal}
-Consider \Genitivetrue\Jeff\ legacy. More on \Jeff\ later.
-\Genitivetrue\Jeff\ reputation has declined in recent decades.
-\end{verbatim}
+\ForgetName[Frederick]{Douglass}
+\ForgetName[Betsey]{Bailey}
+\noindent
+\begin{enumerate*}
+ \item[\textbf{2.}] \Doug's early life is perhaps the most
+ complete indictment of the slave system ever presented at
+ the bar of public opinion.
+ \item[\textbf{3.}] \Doug\ was born in February, l8l7. His
+ earliest memories centered around the cabin of his
+ grandmother, \Bailey.
+ \item[\textbf{1.}] \Doug\ rose to eminence by sheer force
+ of character and talents that neither slavery nor caste
+ proscription could crush.
+\end{enumerate*}
- \smallskip
- Consider \Genitivetrue\Jeff\ legacy. More on \Jeff\ later.
- \Genitivetrue\Jeff\ reputation has declined in recent decades.
- \end{quote}
-\AltFormatInactive
-\endgroup
-\newpage
+\section{Multiple Indexes}
-\section{Example Reference Work}
+The Electric Boogaloo\index{Boogaloo, Electric}\\ % main index
+was created by \Name{Ollie~\& Jerry}. % name index
+\index{indexes, multiple}
-Below we use alternate formatting, sort index entries, set up a cross-reference, and define a reference article macro:
+\section{Index Categories}
-\AltFormatActive
-\PretagName[Greta]{\textSC{Garbo}}{Garbo, Greta}
-\PretagName{\textSC{Misora}, Hibari}{Misora Hibari}
-\PretagName[Heinz]{\textSC{Rühmann}}{Ruehmann, Heinz}
-\PretagName[Heinrich Wilhelm]{\textSC{Rühmann}}%
- {Ruehmann, Heinrich Wilhelm}
-\IndexRef[Heinrich Wilhelm]{\textSC{Rühmann}}%
- {\textSC{Rühmann}, Heinz}%
-\newcommand{\RefArticle}[3]{%
- \def\check{#2}%
- \ifx\check\empty
- \noindent\ForgetThis#1\ #3
- \else
- \noindent\ForgetThis#1\ #2\ #3
- \fi
-}
-\begin{quote}\small
-\StartNum
-\begin{verbatim}
-\AltFormatActive
-\PretagName[Greta]{\textSC{Garbo}}{Garbo, Greta}
-\PretagName{\textSC{Misora}, Hibari}{Misora Hibari}
-\PretagName[Heinz]{\textSC{Rühmann}}{Ruehmann, Heinz}
-\PretagName[Heinrich Wilhelm]{\textSC{Rühmann}}%
- {Ruehmann, Heinrich Wilhelm}
-\IndexRef[Heinrich Wilhelm]{\textSC{Rühmann}}%
- {\textSC{Rühmann}, Heinz}%
-\newcommand{\RefArticle}[3]{%
- \def\check{#2}%
- \ifx\check\empty
- \noindent\ForgetThis#1\ #3
- \else
- \noindent\ForgetThis#1\ #2\ #3
- \fi
-}
-\end{verbatim}
-\end{quote}
+\subsection{Famous Black Americans}
-\cmd{\RefArticle} prints only the first and third arguments if the second is empty, else it prints all three. We determine what those arguments mean by including specific naming macros. That includes using \cmd{\RevComma} for Western names, but not for Eastern ones.
+\ForgetThis\Name[Frederick]{Douglass} rose to eminence by sheer
+force of character and talents that neither slavery nor caste
+proscription could crush. Circumstances made
+\Name[Frederick]{Douglass} a slave, but they could not prevent
+him from becoming a freeman and a leader among mankind.\\
-\begin{quote}\small
-\ContinueNum
-\begin{verbatim}
-\RefArticle
- {\RevComma\Name[Greta]{\textSC{Garbo}}}
- {}
- {(18 September 1905\,--\,15 April 1990) was a Swedish
- film actress during the 1920s and 1930s.}
+We also celebrate \MLK, then \MLK.
-\RefArticle
- {\Name{\textSC{Misora}, Hibari}}
- {}
- {(W: ``\RevName\Name*{\textSC{Misora}, Hibari}'';
- 29 May 1937\,--\,24 June 1989) was a Japanese singer
- and actress noted for her positive message.}
+\subsection{Patres Patriae}
-\RefArticle
- {\RevComma\Name[Heinrich Wilhelm]{\textSC{Rühmann}}}
- {``\SubvertThis\ForceName\FName[Heinz]{\textSC{Rühmann}}''}
- {(7 March 1902\,--\,3 October 1994) was a German actor
- in over 100 films.}
-\AltFormatInactive
-\end{verbatim}
-\end{quote}
+We mention President \Wash; again, \Wash.
+Family and close friends called him \SWash.\\
-\begin{quote}\small
-\RefArticle
- {\RevComma\Name[Greta]{\textSC{Garbo}}}
- {}
- {(18 September 1905\,--\,15 April 1990) was a Swedish
- film actress during the 1920s and 1930s.}
+\TagName[George]{Washington}{!as general}
+We can reminisce about \LWash[General].
+\UntagName[George]{Washington}
-\RefArticle
- {\Name{\textSC{Misora}, Hibari}}
- {}%
- {(W: ``\RevName\Name*{\textSC{Misora}, Hibari}'';
- 29 May 1937\,--\,24 June 1989) was a Japanese singer
- and actress noted for her positive message.}
+When speaking of \Linc, we can refer to \LLinc[Abe].
-\RefArticle
- {\RevComma\Name[Heinrich Wilhelm]{\textSC{Rühmann}}}
- {``\SubvertThis\ForceName\FName[Heinz]{\textSC{Rühmann}}''}
- {(7 March 1902\,--\,3 October 1994) was a German actor
- in over 100 films.}
-\end{quote}
+\subsection{Philosophers}
-\AltFormatInactive
-\newpage
+Among philosophers we consider \Plato\ and \Aris.
-\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}
-\documentclass{beamer}
-\usepackage{nameauth}
-\mode<presentation>
-\beamerdefaultoverlayspecification{<+->}
+\subsection{Historical Figures}
-\begin{document}
+We ponder about \Aeth, then \Aeth.
+We speak of \Sun, then \Sun.
+We note \Soto, then just \Soto.
+\CapThis\Soto{} starts a sentence.
-\begin{frame}{Move Text Without Retyping Names}
- \begin{itemize}\footnotesize
- \item<1-> Original\ForgetName[George]{Washington}%
- \ForgetName[George]{Washington's}\\
- This version of \Name[Ulysses S.]{Grant} changes.
- \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}\\
- This version of \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}
+\subsection{Further Discussion}
-\end{document}
-\end{verbatim}
-\IndexName[George]{Washington}
-\IndexName[Ulysses S.]{Grant}
-\end{quote}
+\TagName[George]{Washington}{!as general}
+\TagName[Dwight D.]{Eisenhower}{!as general}
+\LWash, \LPatton, and \LIke\ were high-ranking generals.\\
-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
+\TagName[Dwight D.]{Eisenhower}{!as president}
+\UntagName[George]{Washington}
+\Wash\ and \Ike\ also were US presidents.
-\section{Hooks: Intro}
-\label{sec:Hooksi}
+\small
+% Instead of pre-tagging Ike we do the following:
+\index[per]{US Presidents!other|see{Eisenhower, Dwight D., president}}
-Here we show 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}
+\section{More Complex Hooks}
+
+% First save main- and front-matter hooks. Then change
+% first-use hooks for both main matter and front matter.
\let\OldFormat\NamesFormat
+\let\OldFrontNames\FrontNamesFormat
+
\renewcommand*\NamesFormat[1]{\textbf{#1}\unless\ifinner
\marginpar{\raggedleft\scriptsize #1}\fi}
-\PretagName{Vlad, Ţepeş}{Vlad Tepes} % for accented names
-\TagName{Vlad, II}{ Dracul} % for index information
-\TagName{Vlad, III}{ Dracula}
-\end{verbatim}
+\renewcommand*\FrontNamesFormat[1]{\textit{#1}\unless\ifinner
+ \marginpar{\raggedleft\scriptsize #1}\fi}
+\index{complex hooks, intro}
-\medskip Within the document after the preamble:
-\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)
+The new format (front matter):\NamesInactive
+
+\Name{Vlad, III}[III Dracula], known as
+\IndexRef{Vlad, Ţepeş}{Vlad III}\SubvertThis\Name*{Vlad, Ţepeş}
+(\Name*{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}
+
+The new format (main matter):\NamesActive
\Name{Vlad, III}[III Dracula], known as
-\AKA{Vlad III}{Vlad, Ţepeş} (the Impaler)
+\IndexRef{Vlad, Ţepeş}{Vlad III}\SubvertThis\Name*{Vlad, Ţepeş}
+(\Name*{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 \cmd{\NamesFormat} and we get:
-\begin{itemize}
- \item \cmd{\ForgetThis}\cmd{\Name\{Vlad, III\}[III Dracula]}\dotfill \ForgetThis\Name{Vlad, III}[III Dracula]
- \item \cmd{\Name*\{Vlad, III\}}\dotfill \Name*{Vlad, III}
- \item \cmd{\Name\{Vlad, III\}}\dotfill \Name{Vlad, III}
-\end{itemize}
-We also set up the cross-reference \cmd{\IndexRef\{Dracula\}\{Vlad III\}}\IndexRef{Dracula}{Vlad III}.
-\newpage
+\let\FrontNamesFormat\OldFrontNames
-\section{Hooks: Life Dates}
-\label{sec:Hooksii}
-\begingroup
-Here we add name conditionals and ``text tags'' to add information to names when desired. The example \cmd{\NamesFormat} below adds a text tag to the first occurrences of main-matter names.
+We are back in the old format.
-Below we use the three token registers available in \textsf{nameauth} to use the name conditional macros. In \cmd{\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 \cmd{\AKA}. We also use a different formatting for the naming macros on the one hand and \cmd{\AKA} on the other:
+in the front matter we see: \NamesInactive
+\ForgetThis\Name{Vlad, III}[III Dracula],
+\Name*{Vlad, III}, and \Name{Vlad, III}.
-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 have to use \cmd{\AKA}. We use \cmd{\ForceName} as needed with \cmd{\AKA}. In the document preamble we set up the following:
-\begin{quote}\small
-\StartNum
-\begin{verbatim}
-\newif\ifNoTag
-\makeatletter
-\renewcommand*\NamesFormat[1]{\begingroup%
- \protected@edef\temp{\endgroup\textsc{#1}%
- \unless\ifNoTag
- \if@nameauth@InName
- {\bfseries\noexpand\NameQueryInfo
- [\unexpanded\expandafter{\the\@nameauth@toksa}]
- {\unexpanded\expandafter{\the\@nameauth@toksb}}
- [\unexpanded\expandafter{\the\@nameauth@toksc}]}\fi
- \if@nameauth@InAKA
- {\normalfont\noexpand\NameQueryInfo
- [\unexpanded\expandafter{\the\@nameauth@toksa}]
- {\unexpanded\expandafter{\the\@nameauth@toksb}}
- [\unexpanded\expandafter{\the\@nameauth@toksc}]}\fi
- \fi}\temp\global\NoTagfalse%
-}
-\makeatother
-\let\FrontNamesFormat\NamesFormat
-\end{verbatim}
-\end{quote}
-\makeatletter
-\renewcommand*\NamesFormat[1]{\begingroup%
- \protected@edef\temp{\endgroup\textsc{#1}%
- \unless\ifNoTag
- \if@nameauth@InName
- {\bfseries\noexpand\NameQueryInfo
- [\unexpanded\expandafter{\the\@nameauth@toksa}]
- {\unexpanded\expandafter{\the\@nameauth@toksb}}
- [\unexpanded\expandafter{\the\@nameauth@toksc}]}\fi
- \if@nameauth@InAKA
- {\normalfont\noexpand\NameQueryInfo
- [\unexpanded\expandafter{\the\@nameauth@toksa}]
- {\unexpanded\expandafter{\the\@nameauth@toksb}}
- [\unexpanded\expandafter{\the\@nameauth@toksc}]}\fi
- \fi}\temp\global\NoTagfalse}%
-\makeatother
-\let\FrontNamesFormat\NamesFormat
+in the main matter we see: \NamesActive
+\ForgetThis\Name{Vlad, III}[III Dracula],
+\Name*{Vlad, III}, and \Name{Vlad, III}.
-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.
+\section{Life Dates in Hooks}
-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}
+% Add data tags to names.
\NameAddInfo[George]{Washington}{ (1732--99)}
\NameAddInfo[Mustafa]{Kemal}{ (1881--1938)}
-\NameAddInfo{Atatürk}{ (in 1934, a special surname)}
-\IndexRef{Atatürk}{Kemal, Mustafa}
-\pagebreak
+\NameAddInfo{Atat\"urk}{ (in 1934, a special surname)}
-Now we begin with the first example, which, after all the setup, looks deceptively simple, but highly reusable without extra work:
-\begin{quote}\small
-\ContinueNum
-\begin{verbatim}
-\ForgetThis\Wash held office 1789--97.
-No tags: \Wash.\\
-First use, dates suppressed: \NoTagtrue\ForgetThis\Wash.\\
-Subsequent use with format and dates: \ForceName\Wash.
-\end{verbatim}
-
-\smallskip
-\ForgetThis\Wash\ held office 1789--97.\\
-No tags: \Wash.\\
-First use, dates suppressed: \NoTagtrue\ForgetThis\Wash.\\
-Subsequent use with format and dates: \ForceName\Wash.
-\end{quote}
+% Ensure that Atat\"urk is a cross-reference that
+% has no page entries in the index.
+\IndexRef{Atat\"urk}{Kemal, Mustafa}
-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:
+% Manually suppress data tag in ``first'' reference
+\newif\ifNoTag
-\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}
+% Redesign formatting hook to usually print a tag
+% only in ``first'' reference. On exit, It resets
+% the flag that suppresses tags, making that flag
+% work only once per name use.
-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@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@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}
+\renewcommand*\NamesFormat[1]
+{%
+ #1%
+ \ifcsname\NameauthPattern!DB\endcsname
+ \unless\ifNoTag
+ \expandafter\csname\NameauthPattern!DB\endcsname%
+ \fi
+ \global\NoTagfalse%
+ \fi
+}
-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
+\ForgetThis\Name[George]{Washington} held office as the first US
+president from 1789 to 1797. \Name[George]{Washington} was the only
+president whose term in office was completely in the eighteenth
+century. If we need to trigger the first use hook at some point,
+we can suppress dates and get an automatic long reference via:
+\NoTagtrue\ForgetThis\Name[George]{Washington}. Or we can trigger
+the first-use hook in a subsequent name use and still have dates:
+\ForceName\Name[George]{Washington}.
+\index{life dates}
+
+We can add name info tags to names used only as cross-
+references. For example, \Name[Mustafa]{Kemal} was granted
+the name \Name{Atat\"urk}. We mention \Name[Mustafa]{Kemal}
+and \Name{Atat\"urk} again. Likewise, we can trigger a
+first use, but with no data tag tag:
+\NoTagtrue\ForgetThis\Name{Atat\"urk}.
+
+\section{Alternate Formatting}
-We change the look of the page reference just to see if it works. Since we are in a local scope, note the use of \cmd{\global}:
+\AltFormatActive
+\renewcommand*\NamesFormat{}
+\renewcommand*\MainNameHook{\AltOff}
-\begin{quote}\small
-\ContinueNum
-\begin{verbatim}
-\global\def\fett#1{\textbf{\sffamily #1}}
-\TagName[Mustafa]{Kemal}{|fett}
-\end{verbatim}
-\end{quote}
-\global\def\fett#1{\textbf{\sffamily #1}}
-\TagName[Mustafa]{Kemal}{|fett}
+\noindent
+\ForgetThis\Name[Konrad]{\noexpand\textSC{Zuse}};
+\Name[Konrad]{\noexpand\textSC{Zuse}}\\
+\ForgetThis\Name[Ada]{\noexpand\textIT{Lovelace}};
+\Name[Ada]{\noexpand\textIT{Lovelace}}\\
+\ForgetThis\Name[Charles]{\noexpand\textBF{Babbage}};
+\Name[Charles]{\noexpand\textBF{Babbage}}\\
+\ForgetThis\Name{\noexpand\textUC{Kanade}, Takeo};
+\Name{\noexpand\textUC{Kanade}, Takeo}
+\index{formatting, alternate}
+
+\renewcommand*\MainNameHook{\sffamily\AltOff}
+
+\ForgetThis\Luth\ was a leading figure in the Protestant
+Reformation. \Luth\ believed that one is declared
+righteous in a forensic sense by divine grace through faith
+created by the Holy Spirit via the Gospel and the Sacraments.
+
+\ForgetThis\Cath\ was not only Queen of France in her own right,
+but she also guided the reigns of her three sons.
+\CapThis\LCath[\noexpand\AltCaps{d}e']
+was blamed for the St.\ Bartholomew's Day massacre that saw the
+murder of thousands of Huguenots.
+\index{formatting, alternate}
+
+\section{Grammatical Inflections in Names}
-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:
+\newif\ifGenitive
+\newif\ifDoGenitive
-\makeatletter
-\renewcommand*\NamesFormat[1]{%
- \let\ex\expandafter%
- \textsc{#1}%
- \if@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@toksa\ex\ex\ex]%
- \ex\ex\ex{\ex\the\ex\@nameauth@toksb\ex}%
- \ex[\the\@nameauth@toksc]%
- \fi\fi
- \if@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@toksa\ex\ex\ex]%
- \ex\ex\ex{\ex\the\ex\@nameauth@toksb\ex}%
- \ex[\the\@nameauth@toksc]%
- \fi\fi
- \global\NoTagfalse}
-\makeatother
-\begin{quote}\small
-\ContinueNum
-\begin{verbatim}
-\newif\ifNoTag
-\makeatletter
-\renewcommand*\NamesFormat[1]{%
- \let\ex\expandafter%
- \textsc{#1}%
- \if@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@toksa\ex\ex\ex]%
- \ex\ex\ex{\ex\the\ex\@nameauth@toksb\ex}%
- \ex[\the\@nameauth@toksc]%
- \fi\fi
- \if@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@toksa\ex\ex\ex]%
- \ex\ex\ex{\ex\the\ex\@nameauth@toksb\ex}%
- \ex[\the\@nameauth@toksc]%
- \fi\fi
- \global\NoTagfalse}
-\makeatother
-\end{verbatim}
+\newcommand*\GEN{\ifDoGenitive\textSC{'s}\fi}
-\smallskip
-With \cmd{\Name}:\\
-\ForgetThis\Name[Mustafa]{Kemal} was granted the name
-\ForgetThis\Name{Atatürk}. We mention \Name[Mustafa]{Kemal}
-and \Name{Atatürk} again.
+\renewcommand*\NamesFormat[1]
+ {\ifGenitive\DoGenitivetrue\fi#1\global\Genitivefalse}
+\renewcommand*\MainNameHook[1]
+ {\ifGenitive\DoGenitivetrue\fi\AltOff#1\global\Genitivefalse}
-First use, no tag: \NoTagtrue\ForgetThis\Name{Atatürk}.\bigskip
+Consider \Genitivetrue\Jeff\ legacy as the author of the
+colonies' Declaration of Independence and his impact as third
+president of the United States. \Jeff\ was a complex historical
+figure whose actions defy a consistent moral compass both in
+public policy and in personal affairs.
+\index{inflections, grammatical}
-With \cmd{\AKA}:\\
-\makeatletter\@nameauth@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.
+\section{Sample Reference Work I}
-First use, no tag: \NoTagtrue\ForceName\AKA[Mustafa]{Kemal}{Atatürk}.
-\end{quote}
+% Make a cross-reference from a variant name form to the
+% form of the head-words
-Now we end the scope.
-\endgroup
-\newpage
+\IndexRef[Heinrich Wilhelm]{\noexpand\textSC{R\"uhmann}}
+ {\noexpand\textSC{R\"uhmann}, Heinz}
-\section{Hooks: Advanced}
-\label{sec:Hooksiii}
-\AltFormatActive
-In this section we invoke \cmd{\AltFormatActive} and create several scopes containing respective examples. Some macros in this section normally should be defined in a document preamble. We define them locally and ensure that names do not use them when they are undefined. This is not best practices, but it makes sense for this manual's need for multiple redefinitions.
+% Define the formatting hooks. Since we use the `altformat'
+% option, alternate formatting is turned off in later
+% name uses.
-\begin{center}\bfseries Continental Format: User-Defined\end{center}
-\phantomsection
-\begingroup
-The user must implement this final step. We use \cmd{\AltFormatActive}, then redefine \cmd{\MainNameHook} to have small caps on by default in the index and first uses in the text, then off in subsequent uses in the text:
-\begin{quote}\small
-\StartNum
-\begin{verbatim}
+\renewcommand*\NamesFormat{}
\renewcommand*\MainNameHook{\AltOff}
-\let\FrontNameHook\MainNameHook
-\end{verbatim}
-\end{quote}
-\renewcommand*\MainNameHook{\AltOff}
-\let\FrontNameHook\MainNameHook
-Usually, we set up the names and any related macros in the preamble:
-\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}
+% Typeset head-words with a slanted font.
-Likewise in the preamble, we must ensure that these names are sorted properly in the index. When sorting names, be sure to use \cmd{\noexpand} as well:
-\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}
+\newcommand{\RefArticle}[3]
+{%
+ \def\check{#2}%
+ \ifx\check\empty
+ \noindent\ForgetThis\textsl{#1}\ #3
+ \else
+ \noindent\ForgetThis\textsl{#1}\ #2\ #3
+ \fi\medskip
+}
-\begin{center}
-\small\noindent\begin{tabular}{llll}\toprule
- First & Next & Long & Short \\\midrule
- \cmd{\Adams} & \cmd{\Adams} & \cmd{\LAdams} & \cmd{\SAdams}\\
- \Adams & \Adams & \LAdams & \SAdams\\
- \rowcolor{grey}\cmd{\SDJR} & \cmd{\SDJR} & \cmd{\LSDJR} & \cmd{\SSDJR}\\
- \rowcolor{grey}\SDJR & \SDJR & \LSDJR & \SSDJR\\
- \cmd{\HAR} & \cmd{\HAR} & \cmd{\LHAR} & \cmd{\SHAR}\\
- \HAR & \HAR & \LHAR & \SHAR\\
- \rowcolor{grey}\cmd{\Mencius} & \cmd{\Mencius} & \cmd{\LMencius} & \cmd{\SMencius}\\
- \rowcolor{grey}\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. Just \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.
- \item One must include all the macros in the name arguments.
-\end{itemize}
-
-\makeatletter\@nameauth@AKAFormattrue\makeatother
-With the \texttt{formatAKA} option we refer to \Mencius\ as \AKA{\noexpand\textSC{Mencius}}{\noexpand\textSC{Meng}, Ke} and \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@AKAFormatfalse\makeatother
-\endgroup
+\index{reference work}
+\RefArticle
+ {\RevComma\Name[Greta]{\noexpand\textSC{Garbo}}}
+ {}
+ {(18 September 1905\,--\,15 April 1990) was a Swedish
+ film actress during the 1920s and 1930s.
+ \Name[Greta]{\noexpand\textSC{Garbo}}\dots}
-\begin{center}\bfseries Rolling Your Own: Basic\end{center}
-\phantomsection
-\begingroup
-Here we set out on the path to custom formatting by using package features that have been implemented already. When redesigning formatting hooks, we recommend using \cmd{\AltFormatActive} or the \texttt{altformat} option to enable alternate formatting and prevent \cmd{\CapThis} from breaking custom formatting macros.
+\RefArticle
+ {\Name{\noexpand\textSC{Misora}, Hibari}}
+ {(W:\,``\RevName\Name*{\noexpand\textSC{Misora}, Hibari}'';}
+ {29 May 1937\,--\,24 June 1989) was a Japanese singer
+ and actress noted for her positive message.
+ \Name{\noexpand\textSC{Misora}, Hibari}\dots}
+
+\RefArticle
+ {\RevComma\Name[Heinz]{\noexpand\textSC{R\"uhmann}}}
+ {(\SubvertThis\ForceName
+ \FName[Heinrich Wilhelm]{\noexpand\textSC{R\"uhmann}};}
+ {7 March 1902\,--\,3 October 1994) was a German actor
+ in over 100 films.
+ \Name[Heinz]{\noexpand\textSC{R\"uhmann}}\dots}
+
+\section{Roman Names: Student Reference}
+
+% Global Boolean flags need to be defined only once.
+\newif\ifNoPraenomen
+\newif\ifNoCognomen
+\newif\ifNoGens
+\newif\ifNoAgnomen
-We recommend examining the internal package flag \cmd{\@nameauth@DoAlt}, which activates alternate formatting, \cmd{\@nameauth@DoCaps}, which handles capitalization, and finally \cmd{\@nameauth@InHook}, which is true when the formatting hooks are called. If you create your own macros, they will look similar.
+% Local Boolean flags need to be defined only once.
+\newif\ifXPrae
+\newif\ifXCogn
+\newif\ifXGens
+\newif\ifXAgno
-Normally we define a macro for use in name arguments in the document preamble in order to ensure that it is always defined:
-\begin{quote}\small
-\StartNum
-\begin{verbatim}
-\makeatletter
-\newcommand*\Fbox[1]{%
- \if@nameauth@DoAlt\protect\fbox{#1}\else#1\fi
+% Name variant macros need to be defined uniquely for each
+% name. First is Scipio. Second is Gracchus.
+
+\newcommand*\SCIPi
+{%
+ \ifXGens Publius\else
+ \ifXPrae Cornelius\else
+ Publius Cornelius%
+ \fi
+ \fi
}
-\makeatother
-\end{verbatim}
-\end{quote}
-\makeatletter
-\newcommand*\Fbox[1]{%
- \if@nameauth@DoAlt\protect\fbox{#1}\else#1\fi
+
+\newcommand*\SCIPii
+{%
+ \ifXAgno Scipio\else
+ Scipio Africanus%
+ \fi
}
-\makeatother
-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}
-\renewcommand*\MainNameHook{\AltOff}
-\let\FrontNameHook\MainNameHook
+\newcommand*\TSemp
+{%
+ \ifXGens Tiberius\else
+ \ifXPrae Sempronius\else
+ Tiberius Sempronius%
+ \fi
+ \fi
+}
-When sorting names, be sure to use \cmd{\noexpand} as shown previously:
-\begin{quote}\small
-\ContinueNum
-\begin{verbatim}
-\begin{nameauth}
- \< deSmet & Pierre-Jean &
- \noexpand\Fbox{\noexpand\AltCaps{d}e~Smet} & >
-\end{nameauth}
+% We add the name data tag.
+\NameAddInfo[\noexpand\TSemp]{Gracchus}
+ { (consul, 177 \textsc{bc})}
-\PretagName[Pierre-Jean]%
- {\noexpand\Fbox{\noexpand\AltCaps{d}e~Smet}}%
- {de~Smet, Pierre-Jean}
-\end{verbatim}
-\end{quote}
+% Although it is helpful to set everything up
+% In the preamble, it is not absolutely necessary.
+% Here we define the simpler set of formatting hooks
+% for Scipio, although the complex hooks will work
+% for both equally as well.
-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.
+\renewcommand*\NamesFormat[1]
+{%
+ \ifNoPraenomen\XPraetrue\fi%
+ \ifNoGens\XGenstrue\fi%
+ \ifNoCognomen\XCogntrue\fi%
+ \ifNoAgnomen\XAgnotrue\fi%
+ #1%
+ \global\NoPraenomenfalse%
+ \global\NoGensfalse%
+ \global\NoCognomenfalse%
+ \global\NoAgnomenfalse%
+}
-\begin{center}\small
-\begin{tabular}{rll}\toprule
- First & \cmd{\deSmet} & \deSmet\\
- \rowcolor{grey}Next & \cmd{\deSmet} & \deSmet\\
- Long & \cmd{\LdeSmet} & \LdeSmet\\
- \rowcolor{grey}Short & \cmd{\SdeSmet} & \SdeSmet\\
- & \cmd{\CapThis}\cmd{\deSmet} & \CapThis\deSmet\\
- \rowcolor{grey} & \cmd{\ForceName}\cmd{\CapThis}\cmd{\deSmet} & \ForceName\CapThis\deSmet\\\bottomrule
-\end{tabular}
-\end{center}
+\renewcommand*\MainNameHook[1]
+{%
+ \ifNoPraenomen\XPraetrue\fi%
+ \ifNoGens\XGenstrue\fi%
+ \ifNoCognomen\XCogntrue\fi%
+ \ifNoAgnomen\XAgnotrue\fi%
+ #1%
+ \global\NoPraenomenfalse%
+ \global\NoGensfalse%
+ \global\NoCognomenfalse%
+ \global\NoAgnomenfalse%
+}
-With \cmd{\CapThis}\cmd{\deSmet}: \CapThis\deSmet. \cmd{\ForceName}\cmd{\CapThis}\cmd{\deSmet}: \ForceName\CapThis\deSmet.\medskip
+\index{Roman names, student}
+\Scipio\ was born around 236 \textsc{bc} into the
+Scipiones branch of the Cornelii clan.
+\NoAgnomentrue\Scipio\ rose to military fame during the
+Second Punic War. Thereafter he was known as \Scipio.
+He flourished during the Egyptian reigns of
+\Name{Ptolemy, IV}[IV Philopator] and
+\Name{Ptolemy, V}[V Epiphanes], and the Syrian
+reigns of \Name{Seleucus, III}[III Ceraunus] and
+\Name{Antiochus, III}[III the Great].
+
+% We make no change to \MainNameHook, but we do
+% change \NamesFormat to display any extant
+% name data tags.
-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, but those features appear only in the text.
-\endgroup
+\renewcommand*\NamesFormat[1]
+{%
+ \ifNoPraenomen\XPraetrue\fi%
+ \ifNoGens\XGenstrue\fi%
+ \ifNoCognomen\XCogntrue\fi%
+ \ifNoAgnomen\XAgnotrue\fi%
+ #1%
+ \ifcsname\NameauthPattern!DB\endcsname
+ \expandafter\csname\NameauthPattern!DB\endcsname%
+ \fi
+ \global\NoPraenomenfalse%
+ \global\NoGensfalse%
+ \global\NoCognomenfalse%
+ \global\NoAgnomenfalse%
+}
-\begin{center}\bfseries Rolling Your Own: Intermediate\end{center}
-\phantomsection
-\begingroup
-``Intermediate'' and ``advanced'' refer to the way that formatting hooks were designed before version 3.1. The user-accessible \cmd{\NameParser} builds a printed name from the internal, locally-scoped macros \cmd{\FNN}, \cmd{\SNN}, \cmd{\rootb} and \cmd{\suffb}.
+\TGrac\ served as tribune of the plebs in 184 \textsc{bc}.
+\NoGenstrue\STGrac\ was elected praetor for 180 \textsc{bc},
+after which he was appointed governor of Hispania Citerior.
+serving with the rank of proconsul. In 177 \textsc{bc},
+he was elected consul, again in 163 \textsc{bc}.
-We create a hook that can ignore the output of \cmd{\@nameauth@Name}, which is the \texttt{\#1} in the hook dispatcher's code \cmd{\bgroup}\meta{Hook}\texttt{\{\#1\}}\cmd{\egroup}:
-\begin{quote}\small
- \cmd{\renewcommand*}\meta{FirstHook}\texttt{[1]\{\dots}\cmd{\NameParser}\texttt{\dots\}}
-\end{quote}
+\section{Roman Names: Scholarly Work}
-With the \texttt{altformat} option or \cmd{\AltFormatActive} we can design a subsequent-use hook that deactivates formatting inside of it:
-\begin{quote}\small
- \cmd{\renewcommand*}\meta{SubsequentHook}\texttt{[1]\{\dots}\cmd{\AltOff}\cmd{\NameParser}\texttt{\dots\}}
-\end{quote}
+% Name variant macros need to be defined
+% uniquely for each name.
-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
- \cmd{\renewcommand*}\meta{Hook}\texttt{[1]\{\dots}\cmd{\AltOn}\cmd{\NameParser}\texttt{\dots\}}
-\end{quote}
+\newcommand*\CSB
+{%
+ \ifXGens
+ \ifXAgno Scipio\else
+ Scipio Barbatus\fi
+ \else
+ \ifXCogn Cornelius\else
+ \ifXAgno Cornelius Scipio\else
+ Cornelius Scipio Barbatus%
+ \fi
+ \fi
+ \fi
+}
+
+\index{Roman names, scholar}
+\OScipio\ was born around 337 \textsc{bc} into the
+Scipiones branch of the Cornelii clan, one of the large
+patrician clans. \NoGenstrue\NoAgnomentrue\OScipio\ was
+one of the two elected consuls in 298 \textsc{bc}
+and served during the Third Samnite War.
+\section{Reference Work II}
+
+% Boolean flags; the first sets up headwords and the second
+% indicates that a non-Western form should not be reversed.
+\newif\ifHeadword
+\newif\ifAncientName
+
+% Sorting and tagging the names:
+
+% Adding name information:
+\NameAddInfo{Aristotle}{ (384--322 \textsc{bc})}
+\NameAddInfo[Charles]{\noexpand\textBF{Babbage}}{ (1791--1871)}
+\NameAddInfo{\noexpand\textUC{Kanade}, Takeo}{ (1945-- )}
+\NameAddInfo[Ada]{\noexpand\textIT{Lovelace}}
+ { (Augusta Ada King, Countess of Lovelace
+ [née Byron]; 1815--52)}
+
+% Redefining the formatting hooks:
\makeatletter
-\renewcommand*\NamesFormat[1]{%
- \RevertSNfalse\SpecialFNfalse\SpecialSNfalse#1%
- \unless\ifinner\marginpar{%
- \footnotesize\raggedleft%
- \@nameauth@FullNametrue%
- \@nameauth@FirstNamefalse%
- \@nameauth@EastFNfalse%
- \SpecialFNtrue\SpecialSNfalse%
- \NameParser}%
- \fi\global\RevertSNfalse}
-\renewcommand*\MainNameHook[1]{%
- \AltOff\SpecialFNfalse\SpecialSNtrue#1%
- \unless\ifinner
- \unless\ifRevertSN
- \marginpar{%
- \footnotesize\raggedleft%
- \@nameauth@FullNamefalse%
- \@nameauth@FirstNamefalse%
- \@nameauth@EastFNfalse%
- \SpecialFNfalse\SpecialSNfalse%
- \NameParser}%
+\renewcommand\NamesFormat[1]
+{%
+ \ifHeadword
+ \ifNameauthWestern
+ \@nameauth@RevThisCommatrue%
+ \bfseries \NameParser%
+ \normalfont%
+ \ifcsname\NameauthPattern!DB\endcsname
+ \expandafter\csname\NameauthPattern!DB\endcsname%
+ \fi
+ \else
+ \bgroup%
+ \bfseries \NameParser%
+ \unless\ifAncientName
+ \normalfont; W:\AltOff\space
+ \@nameauth@RevThistrue \NameParser%
+ \fi
+ \normalfont%
+ \ifcsname\NameauthPattern!DB\endcsname
+ \expandafter\csname\NameauthPattern!DB\endcsname%
+ \fi
+ \egroup%
\fi
- \fi\global\RevertSNfalse}
+ \else
+ \NameParser%
+ \fi
+ \global\Headwordfalse%
+ \global\AncientNamefalse%
+}
\makeatother
-We begin in the document preamble by defining a series of conditionals and macros whose default expansion produces the index entry, yet whose other expansions occur only in the formatting hooks. Then we create a name that is composed only of macros, using \cmd{\noexpand} with \cmd{\WM} and \cmd{\SHK}. We use \cmd{\PretagName} to sort the names. \cmd{\Revert} is used to print a last name without a margin note.
-\begin{quote}\small
-\StartNum
-\begin{verbatim}
+\renewcommand\MainNameHook{\AltOff}
+
+% Define related macros:
+\newcommand\Headword{\Headwordtrue\ForgetThis}
+\renewcommand{\RefArticle}[2]
+{%
+ \noindent\Headword #1 #2%
+ \medskip
+}
+\index{reference work}
+
+\RefArticle{\AncientNametrue\Name{Aristotle}}{was the first to offer
+a system of logic, most notably syllogistic logic, that would
+become the basis for discrete states and circuitry of
+digital computers. \Name{Aristotle}\dots}
+
+\RefArticle{\Name[Charles]{\noexpand\textBF{Babbage}}}{designed and
+built the Difference Engine and began work on the Analytical
+Engine. \Name[Charles]{\noexpand\textBF{Babbage}}\dots}
+
+\RefArticle{\Name{\noexpand\textUC{Kanade}, Takeo}}{is one of the
+foremost pioneers in the field of computer vision.
+\Name{\noexpand\textUC{Kanade}, Takeo}\dots}
+
+\RefArticle{\Name[Ada]{\noexpand\textIT{Lovelace}}}{collaborated with
+\Name*[Charles]{\noexpand\textBF{Babbage}}* and wrote what some
+consider to be the first computer program for the Analytical
+Engine. \Name[Ada]{\noexpand\textIT{Lovelace}}\dots}
+\index{reference work}
+
+\section{Marginalia}
+
+% Global Boolean flags need to be defined only once.
\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}
-\begin{nameauth}
- \< Shak & \noexpand\WM & \noexpand\SHK & >
-\end{nameauth}
+% Name variant macros need to be defined
+% uniquely for each name.
-\PretagName[\noexpand\WM]{\noexpand\SHK}{Shakespeare, William}
-\PretagName[Robert]{\textSC{Burns}}{Burns, Robert}
-\end{verbatim}
-\end{quote}
+% For a long name, we want to use ``William'' in the text
+% and ``Wm.'' in the margin.
+
+\newcommand*\WM
+{%
+ \ifSpecialFN Wm.\else
+ William\fi
+}
-Below we define the two formatting hooks that structure the ways in which these macros can expand when printed in the text. \cmd{\NamesFormat} allows only the canonical name via \cmd{\RevertSNfalse}, \cmd{\SpecialFNfalse}, and \cmd{\SpecialSNfalse}. We print the canonical name in the body text. If allowed, 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.
+% The first surname use will be ``Shakespeare'', but ``the
+% Bard'' thereafter. We allow for alternate caps.
+% We can get ``Shakespeare'' thereafter by toggling a flag.
+
+\newcommand*\SHK
+{%
+ \ifRevertSN
+ \textSC{Shakespeare}\else
+ \ifSpecialSN
+ \noexpand\AltCaps{t}he Bard\else
+ \textSC{Shakespeare}%
+ \fi
+ \fi
+}
+
+% Here is how we toggle that flag.
+
+\newcommand*\Revert{\RevertSNtrue}
+
+% The ``first-use'' hook prints a name, then tries
+% to insert a margin note using a different name form
+% and the user-accessible parser. Finally it resets
+% the reversion flag, which is only effective in the
+% ``subsequent-use'' hook. Note how macros in the
+% name arguments take the role of what the internal
+% Boolean flags might otherwise handle.
-\begin{quote}\small
-\ContinueNum
-\begin{verbatim}
\makeatletter
-\renewcommand*\NamesFormat[1]{%
- \RevertSNfalse\SpecialFNfalse\SpecialSNfalse#1%
- \unless\ifinner\marginpar{%
- \footnotesize\raggedleft%
- \@nameauth@FullNametrue%
- \@nameauth@FirstNamefalse%
- \@nameauth@EastFNfalse%
- \SpecialFNtrue\SpecialSNfalse%
- \NameParser}%
- \fi\global\RevertSNfalse}
-\renewcommand*\MainNameHook[1]{%
- \AltOff\SpecialFNfalse\SpecialSNtrue#1%
+\renewcommand*\NamesFormat[1]
+{%
+ \RevertSNfalse\SpecialFNfalse\SpecialSNfalse%
+ #1%
\unless\ifinner
- \unless\ifRevertSN
- \marginpar{%
+ \marginpar
+ {%
\footnotesize\raggedleft%
- \@nameauth@FullNamefalse%
- \@nameauth@FirstNamefalse%
- \@nameauth@EastFNfalse%
- \SpecialFNfalse\SpecialSNfalse%
- \NameParser}%
+ \SpecialFNtrue\SpecialSNfalse%
+ \NameParser%
+ }%
+ \fi
+ \global\RevertSNfalse%
+}
+
+\renewcommand*\MainNameHook[1]
+{%
+ \AltOff\SpecialFNfalse\SpecialSNtrue%
+ #1%
+ \unless\ifinner
+ \unless\ifRevertSN
+ \marginpar
+ {%
+ \footnotesize\raggedleft%
+ \SpecialFNfalse\SpecialSNfalse%
+ \NameParser%
+ }%
\fi
- \fi\global\RevertSNfalse}
+ \fi
+ \global\RevertSNfalse%
+}
\makeatother
-\end{verbatim}
-\smallskip
-\Shak\ \cmd{\Shak} is the national poet of England in much the same way that \Name[Robert]{\textSC{Burns}} \cmd{\Name[Robert]\{}\cmd{\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
+\index{special uses}
+\ForgetThis\Shak\ is the national poet of England
+in much the same way that \Name[Robert]{\textSC{Burns}}
+is that of Scotland. With the latter's rise of influence
+in the 1800s, \Revert\Shak\ became known as ``\Shak''.
-\begin{center}\bfseries Rolling Your Own: Advanced\end{center}
-\phantomsection
-\begingroup
-Here is how formatting hooks were designed before version 3.0. Updating older hooks may be helpful, but is not necessary. 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 mitigate errors. In the preamble, three flags replace package internals.\footnote{The internal flag \texttt{\textbackslash @nameauth@DoAlt} activates formatting, \cmd{\CapThis} sets \texttt{\textbackslash @nameauth@DoCaps} true, and \texttt{\textbackslash @nameauth@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@DoAlt
-\newif\ifFirstCap% Replaces \@nameauth@DoCaps
-\newif\ifInHook% Replaces \@nameauth@InHook
-\Fboxtrue
-\end{verbatim}
-\end{quote}
+\section{Customization, Easy}
-\newcommand*\Fbox[1]{\ifFbox\protect\fbox{#1}\else#1\fi}
-Also in the preamble, the formatting macro is like what we have seen, except it refers to \texttt{\textbackslash ifFbox}:\footnote{We define \cmd{\Fbox} locally because it has multiple definitions, but are very careful where we use names with it.}
-\begin{quote}\small
-\ContinueNum
-\begin{verbatim}
+\makeatletter
\newcommand*\Fbox[1]{%
- \ifFbox\protect\fbox{#1}\else#1\fi
+ \if@nameauth@DoAlt\protect\fbox{#1}\else#1\fi
}
-\end{verbatim}
-\end{quote}
+\makeatother
-\renewcommand*\AltCaps[1]{%
- \ifInHook
- \ifFirstCap\MakeUppercase{#1}\else#1\fi
- \else
- #1%
- \fi
+\renewcommand*\NamesFormat{}
+\renewcommand*\FrontNamesFormat{}
+\renewcommand*\MainNameHook{\AltOff}
+\renewcommand*\FrontNameHook{\AltOff}
+
+\index{customization, easy}
+\deSmet\ was a Jesuit missionary who arrived in North
+America in 1821 at the age of twenty, after a year of seminary
+education. \CapThis\deSmet\ was ordained in 1827 and worked
+among American Indian nations after 1837. We can show the forms
+\LdeSmet\ and \SdeSmet.
+
+\section{Customization, Complicated}
+
+\newif\ifFbox % Replaces \if@nameauth@DoAlt
+\newif\ifFirstCap % Replaces \if@nameauth@DoCaps
+\newif\ifInHook % Replaces \if@nameauth@InHook
+\Fboxtrue % Replaces \AltFormatActive
+
+% Alternate formatting macro definition
+\renewcommand*\Fbox[1]{%
+ \ifFbox\protect\fbox{#1}\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}
+
+% Redefinition of \AltCaps and \CapThis
\renewcommand*\AltCaps[1]{%
\ifInHook
\ifFirstCap\MakeUppercase{#1}\else#1\fi
@@ -10543,303 +14600,496 @@ Our new \cmd{\AltCaps} works like the built-in version, except it does not use t
#1%
\fi
}
-\end{verbatim}
-\end{quote}
-
\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
-\ContinueNum
-\begin{verbatim}
+
+\index{customization, complicated}
+\ForgetThis\deSmet\ was a Jesuit missionary who arrived in North
+America in 1821 at the age of twenty, after a year of seminary
+education. \CapThis\deSmet\ was ordained in 1827 and worked
+among American Indian nations after 1837. We can show the forms
+\LdeSmet\ and \SdeSmet.
+
+\newif\ifCaps % Replaces \if@nameauth@DoAlt
+\Capstrue % Replaces \AltFormatActive
+
+% Alternate formatting macro definition
+\renewcommand*\textSC[1]{\ifCaps\textsc{#1}\else#1\fi}
+
+% Redefinition of \AltCaps and \CapThis
+\renewcommand*\AltCaps[1]{%
+ \ifInHook
+ \ifFirstCap\MakeUppercase{#1}\else#1\fi
+ \else
+ #1%
+ \fi
+}
\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 \cmd{\NamesFormat}, from scratch:
-\begin{quote}\small
-\ContinueNum
-\begin{verbatim}
\renewcommand*\NamesFormat[1]
- {\InHooktrue\NameParser\global\FirstCapfalse}
-\end{verbatim}
-\end{quote}
+ {\InHooktrue#1\global\FirstCapfalse}
-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}
+ {\Capsfalse\InHooktrue#1\global\FirstCapfalse}
-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}
-\end{quote}
-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}\small
-\begin{tabular}{rll}\toprule
- First & \cmd{\deSmet} & \ForgetThis\deSmet\\
- \rowcolor{grey}Next & \cmd{\deSmet} & \deSmet\\
- Long & \cmd{\LdeSmet} & \LdeSmet\\
- \rowcolor{grey}Short & \cmd{\SdeSmet} & \SdeSmet\\
- & \cmd{\CapThis}\cmd{\deSmet} & \CapThis\deSmet\\
- \rowcolor{grey} & \cmd{\ForceName}\cmd{\CapThis}\cmd{\deSmet} & \ForceName\CapThis\deSmet\\\bottomrule
-\end{tabular}
-\end{center}
-
-With \cmd{\CapThis}\cmd{\deSmet}: \CapThis\deSmet. \cmd{\ForceName}\cmd{\CapThis}\cmd{\deSmet}: \ForceName\CapThis\deSmet.\medskip
-
-We can reuse 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:
-\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*\MainNameHook[1]
-{%
- \Capsfalse\InHooktrue\NameParser%
- \global\FirstCapfalse%
-}
-\let\FrontNameHook\MainNameHook
-\end{verbatim}
-\end{quote}
+\ForgetThis\Luth\ was a leading figure in the Protestant
+Reformation. \Luth\ believed that one is declared
+righteous in a forensic sense by divine grace through faith
+created by the Holy Spirit via the Gospel and the Sacraments.
-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\\
- \rowcolor{grey}\ForgetThis\SDJR & \SDJR & \LSDJR & \SSDJR\\
- \ForgetThis\HAR & \HAR & \LHAR & \SHAR\\
- \rowcolor{grey}\ForgetThis\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. Just \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}
-
-We now close the scope of this current example and resume normal formatting.
-\endgroup
-\AltFormatInactive
-\newpage
+\ForgetThis\Cath\ was not only Queen of France in her own right,
+but she also guided the reigns of her three sons.
+\CapThis\LCath[\noexpand\AltCaps{d}e']
+was blamed for the St.\ Bartholomew's Day massacre that saw the
+murder of thousands of Huguenots.
-\section{Customization}
-
-Assuming 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.
+\renewcommand*\NamesFormat{}
+\newcommand*\FrontNamesFormat{}
+\renewcommand*\MainNameHook{}
+\renewcommand*\FrontNameHook{}
-All these macros are set by default to \cmd{\@nameauth@Name}, the internal name parser. \cmd{\Name}, or an unmodified shorthand, calls \cmd{\NameauthName}. \cmd{\Name*}, or an L-shorthand, sets \cmd{\@nameauth@FullNametrue}, then calls \cmd{\NameauthLName}. \cmd{\FName}, or an S-shorthand, sets \cmd{\@nameauth@FirstNametrue}, then calls \cmd{\NameauthFName}. One should not modify \cmd{\Name} and \cmd{\FName} directly.
+\section{Customization, Complete}
-We use features of \textsf{xargs}. Below we introduce formatting that is additional to, inter-operative with, yet distinct from the formatting hooks:
-\begin{quote}\small
-\StartNum
-\begin{verbatim}
\makeatletter
+
+% Change the general-case name macro to show
+% a name in a framed, colored box.
+
\newcommandx*\MyName[3][1=\@empty, 3=\@empty]{%
\global\@nameauth@toksa\expandafter{#1}%
\global\@nameauth@toksb\expandafter{#2}%
\global\@nameauth@toksc\expandafter{#3}%
- \hbox to 4em{Normal: \hfill}%
\fcolorbox{black}{gray!25!white}{\@nameauth@Name[#1]{#2}[#3]}%
}
+
+% Likewise change the macro for when names are forced long.
\newcommandx*\MyLName[3][1=\@empty, 3=\@empty]{%
\global\@nameauth@toksa\expandafter{#1}%
\global\@nameauth@toksb\expandafter{#2}%
\global\@nameauth@toksc\expandafter{#3}%
- \hbox to 4em{Long: \hfill}%
\fcolorbox{black}{green!25!white}{\@nameauth@Name[#1]{#2}[#3]}%
}
+
+% Likewise change the macro when personal names are desired.
\newcommandx*\MyFName[3][1=\@empty, 3=\@empty]{%
\global\@nameauth@toksa\expandafter{#1}%
\global\@nameauth@toksb\expandafter{#2}%
\global\@nameauth@toksc\expandafter{#3}%
- \hbox to 4em{Short: \hfill}%
\fcolorbox{black}{yellow!25!white}{\@nameauth@Name[#1]{#2}[#3]}%
}
\makeatother
-\renewcommand*\NamesFormat[1]
- {\hbox to 9em{\hfil\scshape#1\hfil}}
-\renewcommand*\MainNameHook[1]{\hbox to 9em{\hfil#1\hfil}}
+
+% Change the formatting hooks, but do not use alternate.
+% formatting, which is separate from that above.
+\renewcommand*\NamesFormat[1]{\scshape#1}
+\renewcommand*\MainNameHook[1]{#1}
+
+% Change the naming macro hooks.
\renewcommand*\NameauthName{\MyName}
\renewcommand*\NameauthLName{\MyLName}
\renewcommand*\NameauthFName{\MyFName}
-\end{verbatim}
+
+\index{customization, insane}
+\ForgetThis\Name[Adolf]{Harnack} was a theologian who stressed
+the Fatherhood of God and the brotherhood of man.
+\Name[Adolf]{Harnack} flourished in the early twentieth
+century. We also produce \Name*[Adolf]{Harnack} and
+\FName[Adolf]{Harnack}.
+\AltFormatInactive
\makeatletter
-\newcommandx*\MyName[3][1=\@empty, 3=\@empty]{%
- \global\@nameauth@toksa\expandafter{#1}%
- \global\@nameauth@toksb\expandafter{#2}%
- \global\@nameauth@toksc\expandafter{#3}%
- \hbox to 4em{Normal: \hfill}%
- \fcolorbox{black}{gray!25!white}{\@nameauth@Name[#1]{#2}[#3]}%
-}
-\newcommandx*\MyLName[3][1=\@empty, 3=\@empty]{%
- \global\@nameauth@toksa\expandafter{#1}%
- \global\@nameauth@toksb\expandafter{#2}%
- \global\@nameauth@toksc\expandafter{#3}%
- \hbox to 4em{Long: \hfill}%
- \fcolorbox{black}{green!25!white}{\@nameauth@Name[#1]{#2}[#3]}%
-}
-\newcommandx*\MyFName[3][1=\@empty, 3=\@empty]{%
- \global\@nameauth@toksa\expandafter{#1}%
- \global\@nameauth@toksb\expandafter{#2}%
- \global\@nameauth@toksc\expandafter{#3}%
- \hbox to 4em{Short: \hfill}%
- \fcolorbox{black}{yellow!25!white}{\@nameauth@Name[#1]{#2}[#3]}%
-}
+\renewcommand*\NameauthName{\@nameauth@Name}
+\renewcommand*\NameauthLName{\@nameauth@Name}
+\renewcommand*\NameauthFName{\@nameauth@Name}
\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
-\cmd{\ForgetName[Adolf]\{Harnack\}}\ForgetName[Adolf]{Harnack}\\[1ex]
-\begin{tabular}{@{}rl}
- \cmd{\Harnack} & \Harnack\\
- \cmd{\LHarnack[Adolf von]} & \LHarnack[Adolf von]\\
- \cmd{\Harnack} & \Harnack\\
- \cmd{\SHarnack} & \SHarnack\\
-\end{tabular}
-\end{quote}
-\newpage
+\renewcommand*\NamesFormat{}
+\renewcommand*\MainNameHook{}
\section{\protect\LaTeX\ Engines}
-We use \texttt{american} for the language; one should use one's own. We use Latin Modern. We could load \textsf{tikz} using \texttt{\textbackslash ifDoTikZ} to avoid crashing some \texttt{dvi} viewers in a \texttt{dvi}-only workflow.
+We use \texttt{american} for the language; one should use one's own.
+We use Latin Modern. We could load \textsf{tikz} using
+\texttt{\textbackslash ifDoTikZ} to avoid crashing some \texttt{dvi}
+viewers in a \texttt{dvi}-only workflow.
+\index{\protect\LaTeX\ engines}
\begin{quote}\small
-\StartNum
-\begin{verbatim}
-\IfFileExists{iftex.sty}{\usepackage{iftex}}{}
-\unless\ifdefined\RequireTUTeX
- \usepackage{ifxetex}
- \usepackage{ifluatex}
- \usepackage{ifpdf}
-\fi
+\begin{Verbatim}
+ \IfFileExists{iftex.sty}{\usepackage{iftex}}{}
+ \unless\ifdefined\RequireTUTeX
+ \usepackage{ifxetex}
+ \usepackage{ifluatex}
+ \usepackage{ifpdf}
+ \fi
-\newif\ifDoTikZ % If dvi-only workflow
-\ifxetex
- \usepackage{fontspec}
- \usepackage{polyglossia}
- \setdefaultlanguage{american} % Use own language
- \usepackage{tikz}
- \DoTikZtrue % If dvi-only workflow
-\else
- \ifluatex
- \ifpdf
- \usepackage{fontspec}
- \usepackage{polyglossia}
- \setdefaultlanguage{american} % Use own language
- \usepackage{tikz}
- \DoTikZtrue % If dvi-only workflow
+ \newif\ifDoTikZ % Is loading TikZ okay?
+
+ \ifxetex
+ \usepackage{fontspec}
+ \usepackage{polyglossia}
+ \setdefaultlanguage{american} % Use own language
+ \usepackage{tikz}
+ \DoTikZtrue % PDF: yes TikZ okay.
+ \else
+ \ifluatex
+ \ifpdf
+ \usepackage{fontspec}
+ \usepackage{polyglossia}
+ \setdefaultlanguage{american} % Use own language
+ \usepackage{tikz}
+ \DoTikZtrue % PDF: yes TikZ okay.
+ \else
+ \IfFileExists{utf8-2018.def}{}
+ {\usepackage[utf8]{inputenc}}
+ \usepackage[TS1,T1]{fontenc}
+ \usepackage[american]{babel} % Use own language
+ \usepackage{lmodern}
+ % Perhaps add \usepackage{tikz} with caveats.
+ \fi
\else
\IfFileExists{utf8-2018.def}{}
- {\usepackage[utf8]{inputenc}}
+ {\usepackage[utf8]{inputenc}}
\usepackage[TS1,T1]{fontenc}
- \usepackage[american]{babel} % Use own language
+ \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
- \usepackage{tikz} % If dvi-only workflow
- \DoTikZtrue % If dvi-only workflow
+ \ifpdf
+ \usepackage{tikz}
+ \DoTikZtrue % PDF: yes TikZ okay.
+ \fi
\fi
\fi
-\fi
-\end{verbatim}
+\end{Verbatim}
\end{quote}
-\newpage
-In the body text we can use something like the test below for:
+\newpage
-\begin{center}\fbox{\ifxetex doing \texttt{pdf} things\else \ifpdf doing \texttt{pdf} things\else doing \texttt{dvi} things\fi\fi}\end{center}
+In the body text we can use something like the test below for:\quad
+\fbox{\ifxetex doing \texttt{pdf} things\else
+ \ifpdf doing \texttt{pdf} things\else
+ doing \texttt{dvi} things\fi
+ \fi}
\begin{quote}\small
-\begin{verbatim}
-\ifxetex
- doing \texttt{pdf} things
-\else
- \ifpdf
+\begin{Verbatim}
+ \ifxetex
doing \texttt{pdf} things
\else
- doing \texttt{dvi} things
+ \ifpdf
+ doing \texttt{pdf} things
+ \else
+ doing \texttt{dvi} things
+ \fi
\fi
-\fi\end{verbatim}
+\end{Verbatim}
\end{quote}
-The following equivalent conditional statements can help a macro or just the body text to work under multiple engines:
+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
+\begin{Verbatim}
+ \ifxetex xelatex%
\else
- \ifpdf pdflatex%
- \else latex (dvi)%
+ \ifluatex
+ \ifpdf lualatex (pdf)%
+ \else lualatex (dvi)%
+ \fi
+ \else
+ \ifpdf pdflatex%
+ \else latex (dvi)%
+ \fi
\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)%
+\end{Verbatim}
+
+\begin{Verbatim}
+ \unless\ifxetex
+ \unless\ifluatex
+ \ifpdf pdflatex%
+ \else latex (dvi)%
+ \fi
+ \else
+ \ifpdf lualatex (pdf)%
+ \else lualatex (dvi)%
+ \fi
\fi
+ \else xelatex%
\fi
-\else xelatex%
-\fi
-\end{verbatim}
+\end{Verbatim}
\end{quote}
+
+\section{Miscellaneous Tests: Spaces}
+
+Here we test to see if any unwanted spaces exist in macros that take name arguments.
+If everything is OK, two vertical bars should either immediately precede and follow
+the arguments, or have no space between them. This section also tests if all possible
+argument combinations work in most macros that take name arguments.
+We disable indexing here.\\
+\IndexInactive
+
+\hbox to 0.7\textwidth{\Verb+\Name[FNN]{SNN,Affix}[Alternate]+\dotfill
+ |\Name[FNN]{SNN,Affix}[Alternate]|}\par
+\hbox to 0.7\textwidth{\Verb+\Name*[FNN]{SNN,Affix}+\dotfill
+ |\Name*[FNN]{SNN,Affix}|}\par
+\hbox to 0.7\textwidth{\Verb+\DropAffix\Name*[FNN]{SNN,Affix}+\dotfill
+ |\DropAffix\Name*[FNN]{SNN,Affix}|}\par
+\hbox to 0.7\textwidth{\Verb+\Name[FNN]{SNN,Affix}+\dotfill
+ |\Name[FNN]{SNN,Affix}|}\par
+\hbox to 0.7\textwidth{\Verb+\FName[FNN]{SNN,Affix}[Alternate]+\dotfill
+ |\FName[FNN]{SNN,Affix}[Alternate]|}\par
+\hbox to 0.7\textwidth{\Verb+\FName[FNN]{SNN,Affix}+\dotfill
+ |\FName[FNN]{SNN,Affix}|}\medskip
+
+\hbox to 0.7\textwidth{\Verb+\Name{SNN,Affix}[Alternate]+\dotfill
+ |\Name{SNN,Affix}[Alternate]|}\par
+\hbox to 0.7\textwidth{\Verb+\Name*{SNN,Affix}+\dotfill
+ |\Name*{SNN,Affix}|}\par
+\hbox to 0.7\textwidth{\Verb+\Name{SNN,Affix}+\dotfill
+ |\Name{SNN,Affix}|}\par
+\hbox to 0.7\textwidth{\Verb+\FName{SNN,Affix}+\dotfill
+ |\FName{SNN,Affix}|}\par
+\hbox to 0.7\textwidth{\Verb+\ForceFN\FName{SNN,Affix}[Alternate]+\dotfill
+ |\ForceFN\FName{SNN,Affix}[Alternate]|}\par
+\hbox to 0.7\textwidth{\Verb+\ForceFN\FName{SNN,Affix}+\dotfill
+ |\ForceFN\FName{SNN,Affix}|}\medskip
+
\newpage
+\hbox to 0.7\textwidth{\Verb+\ForgetThis\Name{SNN}[Alternate]+\dotfill
+ |\ForgetThis\Name{SNN}[Alternate]|}\par
+\hbox to 0.7\textwidth{\Verb+\Name*{SNN}[Alternate]+\dotfill
+ |\Name*{SNN}[Alternate]|}\par
+\hbox to 0.7\textwidth{\Verb+\Name{SNN}[Alternate]+\dotfill
+ |\Name{SNN}[Alternate]|}\par
+\hbox to 0.7\textwidth{\Verb+\FName{SNN}[Alternate]+\dotfill
+ |\FName{SNN}[Alternate]|}\par
+\hbox to 0.7\textwidth{\Verb+\ForceFN\FName{SNN}[Alternate]+\dotfill
+ |\ForceFN\FName{SNN}[Alternate]|}\medskip
+
+\hbox to 0.7\textwidth{\Verb+\IndexName[FNN]{SNN,Affix}[Alternate]+\dotfill
+ |\IndexName[FNN]{SNN,Affix}[Alternate]|}\par
+\hbox to 0.7\textwidth{\Verb+\IndexName[FNN]{SNN,Affix}+\dotfill
+ |\IndexName[FNN]{SNN,Affix}|}\par
+\hbox to 0.7\textwidth{\Verb+\IndexName{SNN,Affix}[Alternate]+\dotfill
+ |\IndexName{SNN,Affix}[Alternate]|}\par
+\hbox to 0.7\textwidth{\Verb+\IndexName{SNN,Affix}+\dotfill
+ |\IndexName{SNN,Affix}|}\par
+\hbox to 0.7\textwidth{\Verb+\IndexName{SNN}[Alternate]+\dotfill
+ |\IndexName{SNN}[Alternate]|}\medskip
+
+\hbox to 0.7\textwidth{\Verb+\IndexRef[FNN]{SNN,Affix}[Alternate]{Target}+\dotfill
+ |\IndexRef[FNN]{SNN,Affix}[Alternate]{Target}|}\par
+\hbox to 0.7\textwidth{\Verb+\IndexRef[FNN]{SNN,Affix}{Target}+\dotfill
+ |\IndexRef[FNN]{SNN,Affix}{Target}|}\par
+\hbox to 0.7\textwidth{\Verb+\IndexRef{SNN,Affix}[Alternate]{Target}+\dotfill
+ |\IndexRef{SNN,Affix}[Alternate]{Target}|}\par
+\hbox to 0.7\textwidth{\Verb+\IndexRef{SNN,Affix}{Target}+\dotfill
+ |\IndexRef{SNN,Affix}{Target}|}\par
+\hbox to 0.7\textwidth{\Verb+\IndexRef{SNN}[Alternate]{Target}+\dotfill
+ |\IndexRef{SNN}[Alternate]{Target}|}\medskip
+
+\hbox to 0.7\textwidth{\Verb+\ExcludeName[FNN]{SNN,Affix}[Alternate]+\dotfill
+ |\ExcludeName[FNN]{SNN,Affix}[Alternate]|}\par
+\hbox to 0.7\textwidth{\Verb+\ExcludeName[FNN]{SNN,Affix}+\dotfill
+ |\ExcludeName[FNN]{SNN,Affix}|}\par
+\hbox to 0.7\textwidth{\Verb+\ExcludeName{SNN,Affix}[Alternate]+\dotfill
+ |\ExcludeName{SNN,Affix}[Alternate]|}\par
+\hbox to 0.7\textwidth{\Verb+\ExcludeName{SNN,Affix}+\dotfill
+ |\ExcludeName{SNN,Affix}|}\par
+\hbox to 0.7\textwidth{\Verb+\ExcludeName{SNN}[Alternate]+\dotfill
+ |\ExcludeName{SNN}[Alternate]|}\medskip
+
+\hbox to 0.7\textwidth{\Verb+\IncludeName[FNN]{SNN,Affix}[Alternate]+\dotfill
+ |\IncludeName[FNN]{SNN,Affix}[Alternate]|}\par
+\hbox to 0.7\textwidth{\Verb+\IncludeName[FNN]{SNN,Affix}+\dotfill
+ |\IncludeName[FNN]{SNN,Affix}|}\par
+\hbox to 0.7\textwidth{\Verb+\IncludeName{SNN,Affix}[Alternate]+\dotfill
+ |\IncludeName{SNN,Affix}[Alternate]|}\par
+\hbox to 0.7\textwidth{\Verb+\IncludeName{SNN,Affix}+\dotfill
+ |\IncludeName{SNN,Affix}|}\par
+\hbox to 0.7\textwidth{\Verb+\IncludeName{SNN}[Alternate]+\dotfill
+ |\IncludeName{SNN}[Alternate]|}\medskip
+
+\hbox to 0.7\textwidth{\Verb+\IncludeName*[FNN]{SNN,Affix}[Alternate]+\dotfill
+ |\IncludeName*[FNN]{SNN,Affix}[Alternate]|}\par
+\hbox to 0.7\textwidth{\Verb+\IncludeName*[FNN]{SNN,Affix}+\dotfill
+ |\IncludeName*[FNN]{SNN,Affix}|}\par
+\hbox to 0.7\textwidth{\Verb+\IncludeName*{SNN,Affix}[Alternate]+\dotfill
+ |\IncludeName*{SNN,Affix}[Alternate]|}\par
+\hbox to 0.7\textwidth{\Verb+\IncludeName*{SNN,Affix}+\dotfill
+ |\IncludeName*{SNN,Affix}|}\par
+\hbox to 0.7\textwidth{\Verb+\IncludeName*{SNN}[Alternate]+\dotfill
+ |\IncludeName*{SNN}[Alternate]|}\medskip
+
+\hbox to 0.7\textwidth{\Verb+\PretagName[FNN]{SNN,Affix}[Alternate]{Sort}+\dotfill
+ |\PretagName[FNN]{SNN,Affix}[Alternate]{Sort}|}\par
+\hbox to 0.7\textwidth{\Verb+\PretagName[FNN]{SNN,Affix}{Sort}+\dotfill
+ |\PretagName[FNN]{SNN,Affix}{Sort}|}\par
+\hbox to 0.7\textwidth{\Verb+\PretagName{SNN,Affix}[Alternate]{Sort}+\dotfill
+ |\PretagName{SNN,Affix}[Alternate]{Sort}|}\par
+\hbox to 0.7\textwidth{\Verb+\PretagName{SNN,Affix}{Sort}+\dotfill
+ |\PretagName{SNN,Affix}{Sort}|}\par
+\hbox to 0.7\textwidth{\Verb+\PretagName{SNN}[Alternate]{Sort}+\dotfill
+ |\PretagName{SNN}[Alternate]{Sort}|}\medskip
+
+\hbox to 0.7\textwidth{\Verb+\TagName[FNN]{SNN,Affix}[Alternate]{Tag}+\dotfill
+ |\TagName[FNN]{SNN,Affix}[Alternate]{Tag}|}\par
+\hbox to 0.7\textwidth{\Verb+\TagName[FNN]{SNN,Affix}{Tag}+\dotfill
+ |\TagName[FNN]{SNN,Affix}{Tag}|}\par
+\hbox to 0.7\textwidth{\Verb+\TagName{SNN,Affix}[Alternate]{Tag}+\dotfill
+ |\TagName{SNN,Affix}[Alternate]{Tag}|}\par
+\hbox to 0.7\textwidth{\Verb+\TagName{SNN,Affix}{Tag}+\dotfill
+ |\TagName{SNN,Affix}{Tag}|}\par
+\hbox to 0.7\textwidth{\Verb+\TagName{SNN}[Alternate]{Tag}+\dotfill
+ |\TagName{SNN}[Alternate]{Tag}|}\medskip
+
+\hbox to 0.7\textwidth{\Verb+\UntagName[FNN]{SNN,Affix}[Alternate]+\dotfill
+ |\UntagName[FNN]{SNN,Affix}[Alternate]|}\par
+\hbox to 0.7\textwidth{\Verb+\UntagName[FNN]{SNN,Affix}+\dotfill
+ |\UntagName[FNN]{SNN,Affix}|}\par
+\hbox to 0.7\textwidth{\Verb+\UntagName{SNN,Affix}[Alternate]+\dotfill
+ |\UntagName{SNN,Affix}[Alternate]|}\par
+\hbox to 0.7\textwidth{\Verb+\UntagName{SNN,Affix}+\dotfill
+ |\UntagName{SNN,Affix}|}\par
+\hbox to 0.7\textwidth{\Verb+\UntagName{SNN}[Alternate]+\dotfill
+ |\UntagName{SNN}[Alternate]|}\medskip
+
+\hbox to 0.7\textwidth{\Verb+\NameAddInfo[FNN]{SNN,Affix}[Alternate]{Info}+\dotfill
+ |\NameAddInfo[FNN]{SNN,Affix}[Alternate]{Info}|}\par
+\hbox to 0.7\textwidth{\Verb+\NameAddInfo[FNN]{SNN,Affix}{Info}+\dotfill
+ |\NameAddInfo[FNN]{SNN,Affix}{Info}|}\par
+\hbox to 0.7\textwidth{\Verb+\NameAddInfo{SNN,Affix}[Alternate]{Info}+\dotfill
+ |\NameAddInfo{SNN,Affix}[Alternate]{Info}|}\par
+\hbox to 0.7\textwidth{\Verb+\NameAddInfo{SNN,Affix}{Info}+\dotfill
+ |\NameAddInfo{SNN,Affix}{Info}|}\par
+\hbox to 0.7\textwidth{\Verb+\NameAddInfo{SNN}[Alternate]{Info}+\dotfill
+ |\NameAddInfo{SNN}[Alternate]{Info}|}\medskip
+
+\hbox to 0.7\textwidth{\Verb+\NameQueryInfo[FNN]{SNN,Affix}[Alternate]+\dotfill
+ |\NameQueryInfo[FNN]{SNN,Affix}[Alternate]|}\par
+\hbox to 0.7\textwidth{\Verb+\NameQueryInfo[FNN]{SNN,Affix}+\dotfill
+ |\NameQueryInfo[FNN]{SNN,Affix}|}\par
+\hbox to 0.7\textwidth{\Verb+\NameQueryInfo{SNN,Affix}[Alternate]+\dotfill
+ |\NameQueryInfo{SNN,Affix}[Alternate]|}\par
+\hbox to 0.7\textwidth{\Verb+\NameQueryInfo{SNN,Affix}+\dotfill
+ |\NameQueryInfo{SNN,Affix}|}\par
+\hbox to 0.7\textwidth{\Verb+\NameQueryInfo{SNN}[Alternate]+\dotfill
+ |\NameQueryInfo{SNN}[Alternate]|}\medskip
+
+\newpage
+
+\hbox to 0.7\textwidth{\Verb+\NameClearInfo[FNN]{SNN,Affix}[Alternate]+\dotfill
+ |\NameClearInfo[FNN]{SNN,Affix}[Alternate]|}\par
+\hbox to 0.7\textwidth{\Verb+\NameClearInfo[FNN]{SNN,Affix}+\dotfill
+ |\NameClearInfo[FNN]{SNN,Affix}|}\par
+\hbox to 0.7\textwidth{\Verb+\NameClearInfo{SNN,Affix}[Alternate]+\dotfill
+ |\NameClearInfo{SNN,Affix}[Alternate]|}\par
+\hbox to 0.7\textwidth{\Verb+\NameClearInfo{SNN,Affix}+\dotfill
+ |\NameClearInfo{SNN,Affix}|}\par
+\hbox to 0.7\textwidth{\Verb+\NameClearInfo{SNN}[Alternate]+\dotfill
+ |\NameClearInfo{SNN}[Alternate]|}\medskip
+
+\hbox to 0.7\textwidth{\Verb+\ForgetName[FNN]{SNN,Affix}[Alternate]+\dotfill
+ |\ForgetName[FNN]{SNN,Affix}[Alternate]|}\par
+\hbox to 0.7\textwidth{\Verb+\ForgetName[FNN]{SNN,Affix}+\dotfill
+ |\ForgetName[FNN]{SNN,Affix}|}\par
+\hbox to 0.7\textwidth{\Verb+\ForgetName{SNN,Affix}[Alternate]+\dotfill
+ |\ForgetName{SNN,Affix}[Alternate]|}\par
+\hbox to 0.7\textwidth{\Verb+\ForgetName{SNN,Affix}+\dotfill
+ |\ForgetName{SNN,Affix}|}\par
+\hbox to 0.7\textwidth{\Verb+\ForgetName{SNN}[Alternate]+\dotfill
+ |\ForgetName{SNN}[Alternate]|}\medskip
+
+\Verb+\LocalNames+\LocalNames\par
+\hbox to 0.7\textwidth{\Verb+\SubvertName[FNN]{SNN,Affix}[Alternate]+\dotfill
+ |\SubvertName[FNN]{SNN,Affix}[Alternate]|}\par
+\hbox to 0.7\textwidth{\Verb+\SubvertName[FNN]{SNN,Affix}+\dotfill
+ |\SubvertName[FNN]{SNN,Affix}|}\par
+\hbox to 0.7\textwidth{\Verb+\SubvertName{SNN,Affix}[Alternate]+\dotfill
+ |\SubvertName{SNN,Affix}[Alternate]|}\par
+\hbox to 0.7\textwidth{\Verb+\SubvertName{SNN,Affix}+\dotfill
+ |\SubvertName{SNN,Affix}|}\par
+\hbox to 0.7\textwidth{\Verb+\SubvertName{SNN}[Alternate]+\dotfill
+ |\SubvertName{SNN}[Alternate]|}\par
+\Verb+\GlobalNames+\GlobalNames\medskip
+
+\hbox to 0.7\textwidth{\Verb+\IfMainName[FNN]{SNN,Affix}[Alternate]{Y}{N}+\dotfill
+ |\IfMainName[FNN]{SNN,Affix}[Alternate]{Y}{N}|}\par
+\hbox to 0.7\textwidth{\Verb+\IfMainName[FNN]{SNN,Affix}{Y}{N}+\dotfill
+ |\IfMainName[FNN]{SNN,Affix}{Y}{N}|}\par
+\hbox to 0.7\textwidth{\Verb+\IfMainName{SNN,Affix}[Alternate]{Y}{N}+\dotfill
+ |\IfMainName{SNN,Affix}[Alternate]{Y}{N}|}\par
+\hbox to 0.7\textwidth{\Verb+\IfMainName{SNN,Affix}{Y}{N}+\dotfill
+ |\IfMainName{SNN,Affix}{Y}{N}|}\par
+\hbox to 0.7\textwidth{\Verb+\IfMainName{SNN}[Alternate]{Y}{N}+\dotfill
+ |\IfMainName{SNN}[Alternate]{Y}{N}|}\medskip
+
+\hbox to 0.7\textwidth{\Verb+\IfFrontName[FNN]{SNN,Affix}[Alternate]{Y}{N}+\dotfill
+ |\IfFrontName[FNN]{SNN,Affix}[Alternate]{Y}{N}|}\par
+\hbox to 0.7\textwidth{\Verb+\IfFrontName[FNN]{SNN,Affix}{Y}{N}+\dotfill
+ |\IfFrontName[FNN]{SNN,Affix}{Y}{N}|}\par
+\hbox to 0.7\textwidth{\Verb+\IfFrontName{SNN,Affix}[Alternate]{Y}{N}+\dotfill
+ |\IfFrontName{SNN,Affix}[Alternate]{Y}{N}|}\par
+\hbox to 0.7\textwidth{\Verb+\IfFrontName{SNN,Affix}{Y}{N}+\dotfill
+ |\IfFrontName{SNN,Affix}{Y}{N}|}\par
+\hbox to 0.7\textwidth{\Verb+\IfFrontName{SNN}[Alternate]{Y}{N}+\dotfill
+ |\IfFrontName{SNN}[Alternate]{Y}{N}|}\medskip
+
+\hbox to 0.7\textwidth{\Verb+\SeeAlso\IndexRef[FNN]{SNN,Affix}{Target}+\dotfill
+ |\SeeAlso\IndexRef[FNN]{SNN,Affix}{Target}|}\par
+\hbox to 0.7\textwidth{\Verb+\ExcludeName{SNN,Affix}+\dotfill
+ |\ExcludeName{SNN,Affix}|}\par
+\hbox to 0.7\textwidth{\Verb+\IfAKA[FNN]{SNN,Affix}[Alternate]{Y}{N}{X}+\dotfill
+ |\IfAKA[FNN]{SNN,Affix}[Alternate]{Y}{N}{X}|}\par
+\hbox to 0.7\textwidth{\Verb+\IfAKA[FNN]{SNN,Affix}{Y}{N}{X}+\dotfill
+ |\IfAKA[FNN]{SNN,Affix}{Y}{N}{X}|}\par
+\hbox to 0.7\textwidth{\Verb+\IfAKA{SNN,Affix}[Alternate]{Y}{N}{X}+\dotfill
+ |\IfAKA{SNN,Affix}[Alternate]{Y}{N}{X}|}\par
+\hbox to 0.7\textwidth{\Verb+\IfAKA{SNN,Affix}{Y}{N}{X}+\dotfill
+ |\IfAKA{SNN,Affix}{Y}{N}{X}|}\par
+\hbox to 0.7\textwidth{\Verb+\IfAKA{SNN}[Alternate]{Y}{N}{X}+\dotfill
+ |\IfAKA{SNN}[Alternate]{Y}{N}{X}|}\medskip
+
+\hbox to \textwidth{\Verb+\AKA[FNN1]{SNN1,Affix1}[FNN2]{SNN2,Affix2}[Alternate2]+\dotfill
+ |\AKA[FNN1]{SNN1,Affix1}[FNN2]{SNN2,Affix2}[Alternate2]|}\par
+\hbox to \textwidth{\Verb+\AKA[FNN1]{SNN1,Affix1}[FNN2]{SNN2,Affix2}+\dotfill
+ |\AKA[FNN1]{SNN1,Affix1}[FNN2]{SNN2,Affix2}|}\par
+\hbox to \textwidth{\Verb+\DropAffix\AKA[FNN1]{SNN1,Affix1}[FNN2]{SNN2,Affix2}+\dotfill
+ |\DropAffix\AKA[FNN1]{SNN1,Affix1}[FNN2]{SNN2,Affix2}|}\par
+\hbox to \textwidth{\Verb+\AKA*[FNN1]{SNN1,Affix1}[FNN2]{SNN2,Affix2}[Alternate2]+\dotfill
+ |\AKA*[FNN1]{SNN1,Affix1}[FNN2]{SNN2,Affix2}[Alternate2]|}\par
+\hbox to \textwidth{\Verb+\AKA*[FNN1]{SNN1,Affix1}[FNN2]{SNN2,Affix2}+\dotfill
+ |\AKA*[FNN1]{SNN1,Affix1}[FNN2]{SNN2,Affix2}|}\medskip
+
+\hbox to \textwidth{\Verb+\AKA[FNN1]{SNN1,Affix1}{SNN3,Affix3}[Alternate3]+\dotfill
+ |\AKA[FNN1]{SNN1,Affix1}{SNN3,Affix3}[Alternate3]|}\par
+\hbox to \textwidth{\Verb+\AKA[FNN1]{SNN1,Affix1}{SNN3,Affix3}+\dotfill
+ |\AKA[FNN1]{SNN1,Affix1}{SNN3,Affix3}|}\par
+\hbox to \textwidth{\Verb+\AKA*[FNN1]{SNN1,Affix1}{SNN3,Affix3}+\dotfill
+ |\AKA*[FNN1]{SNN1,Affix1}{SNN3,Affix3}|}\par
+\hbox to \textwidth{\Verb+\ForceFN\AKA*[FNN1]{SNN1,Affix1}{SNN3,Affix3}[Alternate3]+\dotfill
+ |\ForceFN\AKA*[FNN1]{SNN1,Affix1}{SNN3,Affix3}[Alternate3]|}\par
+\hbox to \textwidth{\Verb+\ForceFN\AKA*[FNN1]{SNN1,Affix1}{SNN3,Affix3}+\dotfill
+ |\ForceFN\AKA*[FNN1]{SNN1,Affix1}{SNN3,Affix3}|}\medskip
+
+\hbox to \textwidth{\Verb+\AKA[FNN1]{SNN1,Affix1}{SNN4}[Alternate4]+\dotfill
+ |\AKA[FNN1]{SNN1,Affix1}{SNN4}[Alternate4]|}\par
+\hbox to \textwidth{\Verb+\AKA*[FNN1]{SNN1,Affix1}{SNN4}[Alternate4]+\dotfill
+ |\AKA*[FNN1]{SNN1,Affix1}{SNN4}[Alternate4]|}\par
+\hbox to \textwidth{\Verb+\ForceFN\AKA*[FNN1]{SNN1,Affix1}{SNN4}[Alternate4]+\dotfill
+ |\ForceFN\AKA*[FNN1]{SNN1,Affix1}{SNN4}[Alternate4]|}\medskip
+
\phantomsection
\addcontentsline{toc}{section}{Index of Persons}
\printindex[per]
@@ -10850,6 +15100,7 @@ The following equivalent conditional statements can help a macro or just the bod
\printindex
\end{document}
+
%examplesvb
%</examples>
\endinput
generated by cgit v1.2.3 (git 2.39.1) at 2024-11-19 17:44:32 +0000