diff options
author | Norbert Preining <norbert@preining.info> | 2025-02-07 03:04:18 +0000 |
---|---|---|
committer | Norbert Preining <norbert@preining.info> | 2025-02-07 03:04:18 +0000 |
commit | 34739835e3cbf8d262d3fff2edeb26697096123c (patch) | |
tree | 9d30ca37fb24261a6e69d6be82c4d12faa25e0f4 /macros | |
parent | d90b64f941e0dd2e3082a7701f7842833ccbca84 (diff) |
CTAN sync 202502070304
Diffstat (limited to 'macros')
16 files changed, 7453 insertions, 6486 deletions
diff --git a/macros/latex/contrib/enumitem/README.md b/macros/latex/contrib/enumitem/README.md index ac4eab75c4..9ac7d4760c 100644 --- a/macros/latex/contrib/enumitem/README.md +++ b/macros/latex/contrib/enumitem/README.md @@ -1,4 +1,4 @@ -## Enumitem 3.10 +## Enumitem 3.11 This package provides most of the flexibility you may want to customize the three basic list environments (`enumerate`, `itemize` and @@ -8,6 +8,8 @@ syntax. ### Latest changes ``` +3.11 2025-02-06 + Revert a fix 3.10 2025-01-19 - A couple of fixes: \value* in ref=, a more robust resume*. 3.9 2019-06-20 @@ -40,4 +42,4 @@ Repository: https://github.com/jbezos/enumitem ________ Javier Bezos --- http://www.texnia.com -2025/01/19 +2025/02/06 diff --git a/macros/latex/contrib/enumitem/enumitem.pdf b/macros/latex/contrib/enumitem/enumitem.pdf Binary files differindex ad3d2e24a3..cf76ffe5b3 100644 --- a/macros/latex/contrib/enumitem/enumitem.pdf +++ b/macros/latex/contrib/enumitem/enumitem.pdf diff --git a/macros/latex/contrib/enumitem/enumitem.sty b/macros/latex/contrib/enumitem/enumitem.sty index 7150a22f85..c1099f2a49 100644 --- a/macros/latex/contrib/enumitem/enumitem.sty +++ b/macros/latex/contrib/enumitem/enumitem.sty @@ -10,7 +10,7 @@ % ~~~~~~~ \NeedsTeXFormat{LaTeX2e} -\ProvidesPackage{enumitem}[2025/01/19 v3.10 Customized lists] +\ProvidesPackage{enumitem}[2025/02/06 v3.11 Customized lists] % Notes % ~~~~~ @@ -223,12 +223,6 @@ \csname @list\romannumeral\the\count@\endcsname}{}% \fi} -\def\enit@nolabelenum#1#2{% - \enit@error{Label undefined}% - {The current class doesn't define some labels\MessageBreak - for 'enumerate'. You have to do it yourself, as\MessageBreak - explained in the manual.}} - % +=============================+ % | KEYS | % +=============================+ @@ -1397,11 +1391,6 @@ \csname label\@enumctr\endcsname {\usecounter\@enumctr \let\enit@calc\z@ - \expandafter\ifx\expandafter\@undefined\@itemlabel - \enit@nolabelenum - \else\expandafter\ifx\expandafter\relax\@itemlabel - \enit@nolabelenum - \fi\fi \def\makelabel##1{\enit@align{\enit@format{##1}}}% \enit@preset{#2}{#1}{#4}% \enit@normlabel\@itemlabel\@itemlabel diff --git a/macros/latex/contrib/enumitem/enumitem.tex b/macros/latex/contrib/enumitem/enumitem.tex index 35a290b3c5..ad58775198 100644 --- a/macros/latex/contrib/enumitem/enumitem.tex +++ b/macros/latex/contrib/enumitem/enumitem.tex @@ -56,7 +56,7 @@ suggestions go to \href{http://www.texnia.com/enumitem.html}% {\texttt{http://www.texnia.com/enumitem.html}}.}} -\date{Version 3.10\\2025/01/19} +\date{Version 3.11\\2025/02/06} \IfFileExists{enumitem.sty}{\usepackage{enumitem}}{} \IfFileExists{layouts.sty}{\usepackage{layouts}}{} diff --git a/macros/latex/contrib/nameauth/Makefile b/macros/latex/contrib/nameauth/Makefile index 44d46cbfeb..ab7626e375 100644 --- a/macros/latex/contrib/nameauth/Makefile +++ b/macros/latex/contrib/nameauth/Makefile @@ -1,22 +1,25 @@ -# Copyright (C) 2023 by Charles P. Schaum <charles[dot]schaum@comcast.net> -# ------------------------------------------------------------------- +# Copyright (C) 2025 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: +# 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 # -# and version 1.3 or later is part of all distributions of LaTeX -# version 2005/12/01 or later. +# and version 1.3 or later is part of all distributions +# of LaTeX version 2005/12/01 or later. # -# ------------------------------------------------------------------- +# This work includes all source and generated files +# described as such in README.md, included herein. +# +# ----------------------------------------------- # # Usage: # # Delete all generated files, do clean build on -# POSIX-compliant systems, WSL, or Cygwin. +# POSIX--compliant systems, WSL, or Cygwin. # # make # @@ -31,7 +34,7 @@ # # Install/remove supplied files into the user's texmf tree. # These targets only work in a POSIX environment and do not -# install from WSL or Cygwin into a Windows wnvironment +# install from WSL or Cygwin into a Windows environment # They have not been tested on MikTeX for Linux. # # make inst @@ -48,6 +51,10 @@ # make install # make uninstall # +# Add options if needed, such as +# +# make ADDOPTS="--synctex=1" +# # Compile examples file with pdflatex. # # make examples @@ -82,7 +89,9 @@ # # make distclean # -# Regenerate files from the dtx file if needed. +# Regenerate files from the dtx file if needed. This target +# does not build the package. It is handy when editing the +# dtx to work on README.md, examples.tex, and the like. # # make unpack # @@ -97,14 +106,44 @@ # # make zip # -# ------------------------------------------------------------------- +# ----------------------------------------------- +# +# Programs necessary to execute this make file: +# +# POSIX Build Utilities +# bash +# make +# sed +# zip +# TeX Distro Programs +# pdflatex +# pdftex +# kpsewhich +# makeindex +# +# ----------------------------------------------- # -# Programs minimally necessary to execute this make file: +# Recommended prerequisites, primary tier: # -# make bash pdflatex kpsewhich -# makeindex zip pdftex +# TeX Distro Programs +# xelatex +# lualatex +# dvilualatex +# latex +# ltxfileinfo +# dvipdfmx +# +# ----------------------------------------------- +# +# Recommended prerequisites, secondary tier: +# +# POSIX Build Utilities +# dvipdf +# TeX Distro Programs +# pdfjam +# +# ----------------------------------------------- # -# ------------------------------------------------------------------- # # Assign most variables in this section. Here we determine what @@ -123,7 +162,7 @@ SHELL = bash PWD = $(shell pwd) -# LaTeX engines to use for building th package and for typesetting +# LaTeX engines to use for building the package and for typesetting # the examples file and testing files; below is the default. # One can choose from latex, pdflatex, xelatex, lualatex, dvilualatex. @@ -160,7 +199,7 @@ ifeq ($(strip $(TESTENGINE)$(EXT)),) $(error Cannot find $(TESTENGINE). Please check your installation.") endif -# Get Package pversion info; check if not available in some environments. +# Get package version info; check if not available in some environments. # Create a zip file name that will not cause problems, e.g., in Windows. DOVERSION := $(shell command -v ltxfileinfo 2> /dev/null) @@ -188,11 +227,11 @@ PDFJAM := $(shell command -v pdfjam 2> /dev/null) # Build options are in this variable. -BUILDOPTS = -recorder -interaction=nonstopmode +BUILDOPTS = --recorder --interaction=nonstopmode # Test and example options are in this variable. -TESTOPTS = -interaction=nonstopmode +TESTOPTS = --interaction=nonstopmode # Add options with this variable, e.g.: make ADDOPTS="--synctex=1" @@ -201,7 +240,7 @@ ADDOPTS ?= # Core options for generating the sty file and included files # the normal way. Alternate is via make unpack. -COREOPTS = -shell-escape -recorder -interaction=batchmode +COREOPTS = --shell-escape --recorder --interaction=batchmode # Local, system-wide tex tree @@ -218,7 +257,7 @@ UTREE = $(shell kpsewhich$(EXT) --var-value TEXMFHOME) # Default make target is the package release and its dependencies. # When building, erase all generated files to make a fresh build. -release : distclean package +release : distclean package clean # Use this recipe to make the package without removing all prior files. @@ -253,12 +292,13 @@ tests : @echo "Test files have been made successfully." testout : test01_01.pdf \ + test05_01.pdf \ test07_01.pdf test07_02.pdf \ test09_01.pdf \ test11_01.pdf test11_02.pdf test11_03.pdf test11_04.pdf \ test11_05.pdf test11_06.pdf test11_07.pdf test11_08.pdf \ test11_09.pdf test11_10.pdf \ - test13_01.pdf test13_02.pdf test13_03.pdf test13_04.pdf + test13_01.pdf test13_02.pdf # Regardless of what engine is used for tests, one must use the # build engine (pdflatex) to extract the tests. @@ -346,6 +386,7 @@ unpack : clean : rm -f $(NAME).{aux,glo,gls,idx,rdx,ilg,ind,rnd,toc} rm -f $(NAME).{dvi,fls,hd,log,out,tmp} + rm -f manhook.tmp nullhook.tmp rm -f $(NAME).synctex.gz rm -f $(NAME).'synctex(busy)' rm -f $(NAME).dtx.aux @@ -460,4 +501,3 @@ zip : release compat.tex,examples.tex,$(NAME).pdf,README.md} rm $(NAME) @echo "Zip file has been made successfully." - diff --git a/macros/latex/contrib/nameauth/README.md b/macros/latex/contrib/nameauth/README.md index dbcf3b3971..d6c4d3acf6 100644 --- a/macros/latex/contrib/nameauth/README.md +++ b/macros/latex/contrib/nameauth/README.md @@ -1,254 +1,225 @@ -# 1. 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 instances. -# 2. Files in Zip Archive +# 2 Installing a Distro Package -The following files are included in the archive that is uploaded to CTAN: +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 Obtaining from CTAN + +## 3.1 Getting the Package Archive + +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. The following files are included in the archive that is uploaded to CTAN: | Filename | Description | | :------------- | :------------------------- | +| *Source* | | | `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 | +| *Generated* | | | `compat.tex` | compatibility module | | `examples.tex` | example file | -| `nameauth.pdf` | package documentation | | `README.md` | this file | +| *Built* | | +| `nameauth.pdf` | package documentation | -# 3. Installing a Distro Package +## 3.2 Determining the Installation type -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.2.1 Read `Makefile` First -# 4. Installing from CTAN +`Makefile` has an extensive comment on usage, as well as other helpful comments. It lists all required programs needed to use the GNU make file for installation in a POSIX-compliant environment, such as GNU/Linux, various BSDs, MacOS, and WSL or Cygwin on Windows. -## 4.1 Getting the Package Archive +Minimum required programs include `bash` or an equivalent shell (for which one must edit `Makefile`), and `make`, plus a TeX distribution. To distribute the package, one also requires at least `sed`, and `zip`. -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. +### 3.2.2 POSIX Cases -## 4.2 Using GNU make +If one is using a TeX distribution in a POSIX environment (MacOS, Linux distro, BSD, etc.) and has the required programs listed in `Makefile`, one may do one of the following: -### 4.2.1 Read the File +1. Use GNU make to build and install. **Section 4.1** -**Please inspect the included `Makefile` before using it.** +2. Build and install manually. **Section 4.2** -`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 the 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. +### 3.2.3 Windows Cases -### 4.2.2 Prepare to Install, No Building +Windows offers the largest number of possibilities: -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: +* Cygwin offers a POSIX environment and its own TeX distribution. Avoid installing another TeX distro via WSL or Windows native. **Section 4.1** - make unpack +* WSL offers a POSIX environment and its own TeX distribution. Avoid installing another TeX distro via Cygwin or Windows native. **Section 4.1** -This target only unpacks the supplied generated files from `nameauth.dtx`. It does not try to create the documentation. One will have the following files now: +* Use `make` within either Cygwin or WSL to build this package for native Windows TeX distributions MikTeX or TeXlive. Install needed build components in either Cygwin or WSL, alongside either MikTeX or TeXlive, but not both distros. Avoid installing another TeX distro in either Cygwin or WSL. -| 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 can use `make` to build this package. **Section 4.1.1** -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. + * Installation must be manual. **Section 4.2.2** -### 4.2.3 Specific Build Cases: Program Extensions +* Directly using native Windows TeX distributions (MikTeX or TeXlive) -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 MikTeX and TeXlive. + All building and installation must be manual. **Section 4.2** -When using the TeX distros built in to Cygwin and WSL exclusively, one can treat it basically as a POSIX-compliant environment. +* Other POSIX environments running under DOS, Windows, and other systems have not been tested and are not supported. -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 prerequisite programs are installed. Installation, however, must be manual. +* `Makefile` contains tests that will mitigate some issues: -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. + * If a `.exe` extension is needed by programs used in the building process, that is detected automatically. -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. + * If `ltxfileinfo` does not exist, the make process will produce a zip file that avoids potential problems in Windows. -* 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. + * If `dvipdf` from Ghostscript is installed, the make process will use that. Otherwise it will fall back to `dvipdfmx`. -* Make will test if `dvipdf` from Ghostscript is installed and use that. Otherwise it will fall back to `dvipdfmx`. + * If `pdfjam` is installed, the make process uses it. Otherwise, it will instruct the user to proceed manually. **Section 6.2.3** -* 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. + * When installing, the make process will check if the path to the install directory exists. If it does not, it will produce an error message and exit. -* 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). + If this error message occurs, which is more likely in 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). -Here is a table showing the feasibility of a few scenarios: +Here is a table showing the feasibility of a few scenarios. Any case that is not mentioned below has not been tested and is not recommended. -| Platform | TeX Distro Platform | Make builds pkg/zip | Make installs package | -| :------- | :------------------ | :----------------------------- | :------------------------------ | -| POSIX | POSIX | Yes<sup>1</sup> | Yes | -| Cygwin | Cygwin (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 | Cygwin and Windows | Not tested; not recommended | Not tested; not recommended | -| WSL | WSL Linux 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 | WSL and Windows | Not tested; not recommended | Not tested; not recommended | -| WSL/Cyg | WSL and Cygwin | Not tested; not recommended | Not tested; not recommended | -| GNUWin | any (Windows) | Not tested; not recommended | Not tested; not recommended | +| Build Env. | TeX Distro Platform | Make builds pkg/zip | Make installs package | +| :--------- | :------------------ | :----------------------------- | :------------------------------ | +| POSIX | POSIX | Yes<sup>1</sup> | Yes | +| Cygwin | Cygwin (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 | +| WSL | WSL Linux 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 | -<sup>1</sup> All dependencies must be met. Bear in mind MacOS quirks. +<sup>1</sup> All dependencies must be met. Bear in mind possible MacOS issues. <sup>2</sup> Installs only to Cygwin environment; not to Windows environment. -<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. +<sup>3</sup> The `make images` target using `pdfjam` likely will not work as desired. **Section 6.2.3 Images** <sup>4</sup> Neither `ltxfileinfo` nor `kpsewhich` will give useful results; do a manual install. <sup>5</sup> Installs only to WSL Linux distro environment; not to Windows environment. -### 4.2.4 Building the Package +# 4 Building and Installing -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`. +Regarding command line options longer than one letter, the programs included with major TeX distributions, except for `pdfjam`, use either single dashes or GNU-style double dashes. -### 4.2.5 Installation +Here, for the sake of consistency, we use the GNU convention of single dashes with one-letter options and double dashes for longer options. -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. +## 4.1 GNU `make` for Building and Installation -Assuming that one has a use case where one can use GNU make, one can choose the following: +### 4.1.1 Build -* Type `make inst` to install the package files in the user's personal TDS-compliant directory tree. +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`. To add more options, use, e.g.: `make ADDOPTS="--synctex=1"`. -* 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. +There is a make target, `make unpack`, that does not build the package. It only regenerates files from `nameauth.dtx`. - If, for some reason, this fails, do a manual install (below). +### 4.1.2 Install -Note that these make targets depend on `package`, which does not do a clean build. If one desires a clean build that is followed by an install, use `make release inst` or `make release install`. +Currently, `Makefile` only installs into POSIX environments. -### 4.2.6 Removal +For individual use, one must have a TDS-compliant tree set up in order for installation to work. For more info in setting up those trees, see **Section 4.2.3** for the individual case and **Section 4.2.4** for the site-wide case. + +For site-wide use, one must be able to get root privileges via `sudo`. + +* Type `make inst` to install the package files in the user's personal TDS-compliant directory tree. + +* Type `make install` to install the package files in the site-wide, local TDS-compliant directory tree. The user will be prompted for the `sudo` password. + +### 4.1.3 Remove 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. +* Type `make uninstall` to remove the package files in the site-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. One can delete them manually. -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.2 Manual Building and Installation -## 4.3 Manual Method +Unlike the case with the supplied `Makefile`, which automates adding extensions, in certain cases using Windows TeX distros, one may have to add the ".exe" extension to the programs. -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.2.1 Build -### 4.3.1 Prepare to Install, No Building +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: -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: + pdflatex --shell-escape --recorder --interaction=batchmode nameauth.dtx - pdftex nameauth.dtx + a. We see the following main files: -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: + `Makefile`, `cat01.pdf`, `beamer01.pdf`, `beamer02.pdf`, `beamer03.pdf`, `nameauth.dtx`, `compat.tex`, `examples.tex`, `nameauth.pdf`, `README.md`, `nameauth.ins`, and `nameauth.sty`. -| 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 | + b. We also see the following temporary files: -One may skip past building to **4.3.3 Installation Prerequisites** below. + `nameauth.aux`, `nameauth.fls`, `nameauth.glo`, `nameauth.hd`, `nameauth.idx`, `nameauth.log`, `nameauth.out`, `nameauth.tmp`, and `nameauth.toc`. -### 4.3.2 Building the Package +2. Generate the TOC and cross-references within the documentation: -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 --recorder --interaction=nonstopmode nameauth.dtx + +3. Generate the index and glossary files using `makeindex`: - pdflatex --shell-escape --recorder --interaction=batchmode nameauth.dtx + makeindex -q -s gglo.ist -o nameauth.gls nameauth.glo + makeindex -q -s gind.ist -o nameauth.ind nameauth.idx - Now we should have the following files: + This adds three files: `nameauth.gls`, `nameauth.ilg`, and `nameauth.ind`. -| 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 | +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 - In addition, we have the following temporary files: + The list of files now looks like: | 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 | +| | | | `nameauth.aux` | auxiliary file | | `nameauth.fls` | shows files read | | `nameauth.glo` | raw glossary entries | -| `nameauth.hd ` | | +| `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 | +| `manhook.tmp` | snippet with manual's fmt | +| `nullhook.tmp | snippet with default format | +| | | +| `nameauth.gls` | typeset glossary entries | +| `nameauth.ilg` | `makeindex` log file | +| `nameauth.ind` | typeset index entries | -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 +### 4.2.2 General Install Info 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 instructions below conform generally to a Unix-like system. There are some cases under Windows where this method may not work. For other non-POSIX systems, one will have to know the appropriate procedures and documentation as needed for those cases, which are not covered here. 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 +### 4.2.3 Install for a User -`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: +`TEXMFHOME` is an environment (shell) 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 +* `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. @@ -268,13 +239,13 @@ Quite often, `$TEXMFHOME` is equivalent to `$HOME/texmf`. The dollar sign in fro | | | | `$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). +Create the directories in the left-hand column, or the equivalent. For manual installation, 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 +### 4.2.4 Install Site-Wide -`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: +`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 +* `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: @@ -294,33 +265,33 @@ See the [TeX FAQ](https://www.texfaq.org/FAQ-what-TDS). We can understand the fo | | | | `$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). +Create the directories in the left-hand column. For manual installation, move or copy the files in the right-hand column to their respective directories in the left-hand column. Change file ownership as needed. 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 +# 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, being designed with that in mind. -* 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 is built only with `pdflatex` for the sake of its design elements. The examples and tests can be built with any LaTeX engine. -* 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, both current and 2017) and Windows 10 (MikTeX using shells from both Cygwin and WSL). Using TL 2017, this release was tested on the full manuscript of the published volume, *Breath of God, Yet Work of Man: Scripture, Philosophy, Dialogue, and Conflict*, with Dr. Albert B. Collver III. -* This release was tested on Linux (Pop! OS; vanilla TL 2023 and 2017) and Windows 10 (MikTeX using shells from 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 the current vanilla TL on Pop! OS. See also [this page](https://tug.org/texlive/debian.html) for Debian-based systems. For Arch-based systems, the AUR has a package that takes care of dependencies. -* The CTAN release was created with vanilla TL 2023 on Pop! OS. The most recent `equivs` file was used to meet package equivalences. See also [this page](https://tug.org/texlive/debian.html). - -* TeXlive 2023 and TL 2017 are managed on Pop! OS using [tl-switch](https://github.com/ServusCarolus/tl-switch). +* TeXlive versions 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 +# 6 Examples / Testing + +The file `examples.tex` also includes `compat.tex`; they should be in the same directory when compiled. The examples document 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. It also includes other material and tests. -The file `examples.tex`, also includes `compat.tex`; they should be in the same directory when compiled. The examples document 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. It also includes other material and tests. +In addition to this file, a special run of `nameauth.dtx` that defines the macro `\NameauthDoTestFiles` will generate many separate test files. They are not included in the package archive by default. -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 then can copy the files from the TDS-compliant source dir and optionally, the documentation directory as well, or unpack the CTAN zip file into the test directory and build the package. -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 Using GNU `make` -## 6.1 GNU make: Examples, Tests, Images +### 6.1.1 Examples * Use the default: `make examples`. @@ -328,144 +299,145 @@ To test `nameauth`, either test the files right after installing, or create a ne * 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 + make examples ENGINE=xelatex + make examples ENGINE=lualatex + make examples ENGINE=dvilualatex + make examples ENGINE=latex -* To generate additional test files, type `make tests`. +* To add more options, use, e.g.: - This will produce many test files numbered by chapter and example within that chapter from the `nameauth.dtx` file. By default it will compile all of the test files using `pdflatex`. + make examples ADDOPTS="--synctex=1" -* If one wants to change engines and re-test the files, type `make testclean`. +### 6.1.2 Tests -* One can add the value of ENGINE: +This will produce many test files numbered by chapter and example within that chapter from the `nameauth.dtx` file. By default it will compile all of the test files using `pdflatex`. - make tests ENGINE=xelatex - make tests ENGINE=lualatex - make tests ENGINE=dvilualatex - make tests ENGINE=latex +* To generate test files, type `make tests`. -* If, for some reason, one wanted to make the manual illustrations (usually not required), one would type `make images`. +* If one wants to change engines and re-test the files, type `make testclean`. -## 6.2 Manual Method +* One can add the value of ENGINE: -### 6.2.1 Examples + make tests ENGINE=xelatex + make tests ENGINE=lualatex + make tests ENGINE=dvilualatex + make tests ENGINE=latex -Compile `examples.tex`. In the following command lines, one may substitute `latex`, `xelatex`, `lualatex`, and `dvilualatex` for `pdflatex`. +* To add more options, use, e.g.: - pdflatex --interaction=nonstopmode examples - pdflatex --interaction=nonstopmode examples - makeindex -o examples.ind examples.idx + make tests ADDOPTS="--synctex=1" -This next line is needed because the `index` package makes an index of persons. +### 6.1.3 Manual Illustrations - makeindex -o examples.rnd examples.rdx +Four manual illustrations are based on included tests. If, for some reason, one wanted to create those illustrations (usually not required), one would type `make images`. -These lines complete the indexes and TOC. +## 6.2 Manual Method - pdflatex --interaction=nonstopmode examples - pdflatex --interaction=nonstopmode examples +### 6.2.1 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. +* Compile `examples.tex`. - dvipdfmx examples + In the following command lines, one may substitute `latex`, `xelatex`, `lualatex`, and `dvilualatex` for `pdflatex`. -If one changes LaTeX engines, one first must remove all of the auxiliary files. + pdflatex --interaction=nonstopmode examples + pdflatex --interaction=nonstopmode examples + makeindex -o examples.ind examples.idx -### 6.2.2 Tests +* This next line is needed because the `index` package makes an index of persons. -Generate the test files in the following manner from the `dtx`: + makeindex -o examples.rnd examples.rdx - pdflatex "\def\NameauthDoTestFiles{}\input{nameauth.dtx}" +* These lines complete the indexes and TOC. -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 examples + pdflatex --interaction=nonstopmode examples - pdflatex --interaction=nonstopmode test01-01 - pdflatex --interaction=nonstopmode test01-01 - makeindex -o test01-01.ind test01-01.idx +* Another step is used only with `latex` and `dvilualatex`. -This next line is needed only for `test07-01.tex` because the `index` package is used for an index of persons. + 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. - makeindex -o test07-01.rnd test07-01.rdx + dvipdfmx examples -These lines complete the indexes and TOC. +If one changes LaTeX engines, one first must remove all of the auxiliary files. - pdflatex --interaction=nonstopmode test01-01 - pdflatex --interaction=nonstopmode test01-01 +### 6.2.2 Tests -This step is used only when using `latex` and `dvilualatex`. +* Generate the test files in the following manner from the `dtx`: - dvipdfmx test01-01 + pdflatex "\def\NameauthDoTestFiles{}\input{nameauth.dtx}" -If one changes LaTeX engines, one first must remove all of the auxiliary files. +* Compile the test files. -### 6.2.3 Images + 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. -If, for some reason, one wants to make the manual illustrations (usually not required), this would be the default procedure: + pdflatex --interaction=nonstopmode test01-01 + pdflatex --interaction=nonstopmode test01-01 + makeindex -o test01-01.ind test01-01.idx -Generate the test files in the following manner from the `dtx`: +* This next line is needed only for `test07-01.tex` because the `index` package is used for an index of persons. - pdflatex "\def\NameauthDoTestFiles{}\input{nameauth.dtx}" + makeindex -o test07-01.rnd test07-01.rdx -Compile the test files: +* These lines complete the indexes and TOC. - 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 test01-01 + pdflatex --interaction=nonstopmode test01-01 - 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 +* This step is used only when using `latex` and `dvilualatex`. - 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 + dvipdfmx test01-01 -# 7. Additional Notes +If one changes LaTeX engines, one first must remove all of the auxiliary files. -Version 4.0 switches from `xargs` and `suffix` to `xparse`. Should any modifications still require `xargs` and `suffix`, one can use the `oldargs` package option. -Improvements in version 4.0 include: +### 6.2.3 Images -* Change to `xparse`, which increases power and flexibility going forward. +Four manual illustrations are based on included tests. If, for some reason, one wanted to make the manual illustrations (usually not required), this would be the default procedure: -* Further changes to the manual that make it more readable and consistent. +* Generate the test files in the following manner from the `dtx`: -Version 3.7 remains here: [style](https://www.tug.org/svn/texlive/branches/branch2022.final/Master/texmf-dist/tex/latex/nameauth/), [docs](https://www.tug.org/svn/texlive/branches/branch2022.final/Master/texmf-dist/doc/latex/nameauth/), and [source](https://www.tug.org/svn/texlive/branches/branch2022.final/Master/texmf-dist/source/latex/nameauth/). + pdflatex "\def\NameauthDoTestFiles{}\input{nameauth.dtx}" -Improvements in version 3.7 include: +* Compile the test files: -* Rejection of stale assumptions that had built up over time, based either on initial ignorance or on features that have since changed in LaTeX. + 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 -* The examples file contains some tests that used to be in the documentation. + 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 -* Major rewrite of documentation. +* Split and convert the files. If `pdfjam` is not available, one would have to use other programs to do this. -* The table of contents better frflects scope and sequence. + 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 -* The package itself has been reorganized to follow the same scope and sequence as the documentation. +# 7 Additional Notes -* Several macros have been optimized, leading to simpler and cleaner designs that are easier to debug. Additional bug fixes ensure stability, +Starting from version 4.0 we switched from `xargs` and `suffix` to `xparse`. Should any modifications still require `xargs` and `suffix`, one can use the `oldargs` package option. -* Name arguments shown in package warnings are detokenized in order to prevent potential errors. +Version 3.7 remains here: [style](https://www.tug.org/svn/texlive/branches/branch2022.final/Master/texmf-dist/tex/latex/nameauth/), [docs](https://www.tug.org/svn/texlive/branches/branch2022.final/Master/texmf-dist/doc/latex/nameauth/), and [source](https://www.tug.org/svn/texlive/branches/branch2022.final/Master/texmf-dist/source/latex/nameauth/). -# 8. Copyright +# 8 Copyright -Copyright (C) 2024 by Charles P. Schaum <charles[dot]schaum@comcast.net> +Copyright (C) 2025 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: +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: - [https://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. +and version 1.3 or later is part of all distributions +of LaTeX version 2005/12/01 or later. +This work includes all source and generated files +described as such in this file, README.md. diff --git a/macros/latex/contrib/nameauth/beamer01.pdf b/macros/latex/contrib/nameauth/beamer01.pdf Binary files differindex 52dc34c841..cd60e0ad9e 100644 --- a/macros/latex/contrib/nameauth/beamer01.pdf +++ b/macros/latex/contrib/nameauth/beamer01.pdf diff --git a/macros/latex/contrib/nameauth/beamer02.pdf b/macros/latex/contrib/nameauth/beamer02.pdf Binary files differindex 093b6b1eaf..c76eac7443 100644 --- a/macros/latex/contrib/nameauth/beamer02.pdf +++ b/macros/latex/contrib/nameauth/beamer02.pdf diff --git a/macros/latex/contrib/nameauth/beamer03.pdf b/macros/latex/contrib/nameauth/beamer03.pdf Binary files differindex 4a337f45cc..8ad0825858 100644 --- a/macros/latex/contrib/nameauth/beamer03.pdf +++ b/macros/latex/contrib/nameauth/beamer03.pdf diff --git a/macros/latex/contrib/nameauth/cat01.pdf b/macros/latex/contrib/nameauth/cat01.pdf Binary files differindex f4587eadb4..96ef09262d 100644 --- a/macros/latex/contrib/nameauth/cat01.pdf +++ b/macros/latex/contrib/nameauth/cat01.pdf diff --git a/macros/latex/contrib/nameauth/nameauth.dtx b/macros/latex/contrib/nameauth/nameauth.dtx index 6c7589aa3e..648b147e1d 100644 --- a/macros/latex/contrib/nameauth/nameauth.dtx +++ b/macros/latex/contrib/nameauth/nameauth.dtx @@ -1,274 +1,250 @@ % \iffalse meta-comment % -% Copyright (C) 2024 by Charles P. Schaum <charles[dot]schaum@comcast.net> -% ------------------------------------------------------- +% Copyright (C) 2025 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: +% 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: % -% https://www.latex-project.org/lppl.txt +% http://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. +% and version 1.3 or later is part of all distributions +% of LaTeX version 2005/12/01 or later. +% +% This work includes all source and generated files +% described as such in README.md, included herein. +% +% ----------------------------------------------- % %<*internal> \iffalse %</internal> %<*readme> %<<readmevb -# 1. 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 instances. -# 2. Files in Zip Archive +# 2 Installing a Distro Package + +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 Obtaining from CTAN + +## 3.1 Getting the Package Archive -The following files are included in the archive that is uploaded to CTAN: +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. The following files are included in the archive that is uploaded to CTAN: | Filename | Description | | :------------- | :------------------------- | +| *Source* | | | `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 | +| *Generated* | | | `compat.tex` | compatibility module | | `examples.tex` | example file | -| `nameauth.pdf` | package documentation | | `README.md` | this file | +| *Built* | | +| `nameauth.pdf` | package documentation | -# 3. Installing a Distro Package +## 3.2 Determining the Installation type -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.2.1 Read `Makefile` First -# 4. Installing from CTAN +`Makefile` has an extensive comment on usage, as well as other helpful comments. It lists all required programs needed to use the GNU make file for installation in a POSIX-compliant environment, such as GNU/Linux, various BSDs, MacOS, and WSL or Cygwin on Windows. -## 4.1 Getting the Package Archive +Minimum required programs include `bash` or an equivalent shell (for which one must edit `Makefile`), and `make`, plus a TeX distribution. To distribute the package, one also requires at least `sed`, and `zip`. -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. +### 3.2.2 POSIX Cases -## 4.2 Using GNU make +If one is using a TeX distribution in a POSIX environment (MacOS, Linux distro, BSD, etc.) and has the required programs listed in `Makefile`, one may do one of the following: -### 4.2.1 Read the File +1. Use GNU make to build and install. **Section 4.1** -**Please inspect the included `Makefile` before using it.** +2. Build and install manually. **Section 4.2** -`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 the 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. +### 3.2.3 Windows Cases -### 4.2.2 Prepare to Install, No Building +Windows offers the largest number of possibilities: -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: +* Cygwin offers a POSIX environment and its own TeX distribution. Avoid installing another TeX distro via WSL or Windows native. **Section 4.1** - make unpack +* WSL offers a POSIX environment and its own TeX distribution. Avoid installing another TeX distro via Cygwin or Windows native. **Section 4.1** -This target only unpacks the supplied generated files from `nameauth.dtx`. It does not try to create the documentation. One will have the following files now: +* Use `make` within either Cygwin or WSL to build this package for native Windows TeX distributions MikTeX or TeXlive. Install needed build components in either Cygwin or WSL, alongside either MikTeX or TeXlive, but not both distros. Avoid installing another TeX distro in either Cygwin or WSL. -| 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 can use `make` to build this package. **Section 4.1.1** -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. + * Installation must be manual. **Section 4.2.2** -### 4.2.3 Specific Build Cases: Program Extensions +* Directly using native Windows TeX distributions (MikTeX or TeXlive) -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 MikTeX and TeXlive. + All building and installation must be manual. **Section 4.2** -When using the TeX distros built in to Cygwin and WSL exclusively, one can treat it basically as a POSIX-compliant environment. +* Other POSIX environments running under DOS, Windows, and other systems have not been tested and are not supported. -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 prerequisite programs are installed. Installation, however, must be manual. +* `Makefile` contains tests that will mitigate some issues: -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. + * If a `.exe` extension is needed by programs used in the building process, that is detected automatically. -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. + * If `ltxfileinfo` does not exist, the make process will produce a zip file that avoids potential problems in Windows. -* 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. + * If `dvipdf` from Ghostscript is installed, the make process will use that. Otherwise it will fall back to `dvipdfmx`. -* Make will test if `dvipdf` from Ghostscript is installed and use that. Otherwise it will fall back to `dvipdfmx`. + * If `pdfjam` is installed, the make process uses it. Otherwise, it will instruct the user to proceed manually. **Section 6.2.3** -* 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. + * When installing, the make process will check if the path to the install directory exists. If it does not, it will produce an error message and exit. -* 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). + If this error message occurs, which is more likely in 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). -Here is a table showing the feasibility of a few scenarios: +Here is a table showing the feasibility of a few scenarios. Any case that is not mentioned below has not been tested and is not recommended. -| Platform | TeX Distro Platform | Make builds pkg/zip | Make installs package | -| :------- | :------------------ | :----------------------------- | :------------------------------ | -| POSIX | POSIX | Yes<sup>1</sup> | Yes | -| Cygwin | Cygwin (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 | Cygwin and Windows | Not tested; not recommended | Not tested; not recommended | -| WSL | WSL Linux 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 | WSL and Windows | Not tested; not recommended | Not tested; not recommended | -| WSL/Cyg | WSL and Cygwin | Not tested; not recommended | Not tested; not recommended | -| GNUWin | any (Windows) | Not tested; not recommended | Not tested; not recommended | +| Build Env. | TeX Distro Platform | Make builds pkg/zip | Make installs package | +| :--------- | :------------------ | :----------------------------- | :------------------------------ | +| POSIX | POSIX | Yes<sup>1</sup> | Yes | +| Cygwin | Cygwin (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 | +| WSL | WSL Linux 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 | -<sup>1</sup> All dependencies must be met. Bear in mind MacOS quirks. +<sup>1</sup> All dependencies must be met. Bear in mind possible MacOS issues. <sup>2</sup> Installs only to Cygwin environment; not to Windows environment. -<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. +<sup>3</sup> The `make images` target using `pdfjam` likely will not work as desired. **Section 6.2.3 Images** <sup>4</sup> Neither `ltxfileinfo` nor `kpsewhich` will give useful results; do a manual install. <sup>5</sup> Installs only to WSL Linux distro environment; not to Windows environment. -### 4.2.4 Building the Package +# 4 Building and Installing -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`. +Regarding command line options longer than one letter, the programs included with major TeX distributions, except for `pdfjam`, use either single dashes or GNU-style double dashes. -### 4.2.5 Installation +Here, for the sake of consistency, we use the GNU convention of single dashes with one-letter options and double dashes for longer options. -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. +## 4.1 GNU `make` for Building and Installation -Assuming that one has a use case where one can use GNU make, one can choose the following: +### 4.1.1 Build -* Type `make inst` to install the package files in the user's personal TDS-compliant directory tree. +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`. To add more options, use, e.g.: `make ADDOPTS="--synctex=1"`. + +There is a make target, `make unpack`, that does not build the package. It only regenerates files from `nameauth.dtx`. -* 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). +### 4.1.2 Install -Note that these make targets depend on `package`, which does not do a clean build. If one desires a clean build that is followed by an install, use `make release inst` or `make release install`. +Currently, `Makefile` only installs into POSIX environments. -### 4.2.6 Removal +For individual use, one must have a TDS-compliant tree set up in order for installation to work. For more info in setting up those trees, see **Section 4.2.3** for the individual case and **Section 4.2.4** for the site-wide case. + +For site-wide use, one must be able to get root privileges via `sudo`. + +* Type `make inst` to install the package files in the user's personal TDS-compliant directory tree. + +* Type `make install` to install the package files in the site-wide, local TDS-compliant directory tree. The user will be prompted for the `sudo` password. + +### 4.1.3 Remove 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). +* Type `make uninstall` to remove the package files in the site-wide, local TDS-compliant directory tree. The user will be prompted for the `sudo` password. -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. +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. One can delete them manually. -## 4.3 Manual Method +## 4.2 Manual Building and Installation -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. +Unlike the case with the supplied `Makefile`, which automates adding extensions, in certain cases using Windows TeX distros, one may have to add the ".exe" extension to the programs. -### 4.3.1 Prepare to Install, No Building +### 4.2.1 Build -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: +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: - pdftex nameauth.dtx + pdflatex --shell-escape --recorder --interaction=batchmode 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: + a. We see the following main files: -| 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 | + `Makefile`, `cat01.pdf`, `beamer01.pdf`, `beamer02.pdf`, `beamer03.pdf`, `nameauth.dtx`, `compat.tex`, `examples.tex`, `nameauth.pdf`, `README.md`, `nameauth.ins`, and `nameauth.sty`. -One may skip past building to **4.3.3 Installation Prerequisites** below. + b. We also see the following temporary files: -### 4.3.2 Building the Package + `nameauth.aux`, `nameauth.fls`, `nameauth.glo`, `nameauth.hd`, `nameauth.idx`, `nameauth.log`, `nameauth.out`, `nameauth.tmp`, and `nameauth.toc`. -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: +2. Generate the TOC and cross-references within the documentation: -| 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 | + 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 three files: `nameauth.gls`, `nameauth.ilg`, and `nameauth.ind`. + +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 - In addition, we have the following temporary files: + The list of files now looks like: | 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 | +| | | | `nameauth.aux` | auxiliary file | | `nameauth.fls` | shows files read | | `nameauth.glo` | raw glossary entries | -| `nameauth.hd ` | | +| `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 | +| `manhook.tmp` | snippet with manual's fmt | +| `nullhook.tmp | snippet with default format | +| | | +| `nameauth.gls` | typeset glossary entries | +| `nameauth.ilg` | `makeindex` log file | +| `nameauth.ind` | typeset index entries | -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 +### 4.2.2 General Install Info 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 instructions below conform generally to a Unix-like system. There are some cases under Windows where this method may not work. For other non-POSIX systems, one will have to know the appropriate procedures and documentation as needed for those cases, which are not covered here. 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 +### 4.2.3 Install for a User -`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: +`TEXMFHOME` is an environment (shell) 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 +* `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. @@ -288,13 +264,13 @@ Quite often, `$TEXMFHOME` is equivalent to `$HOME/texmf`. The dollar sign in fro | | | | `$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). +Create the directories in the left-hand column, or the equivalent. For manual installation, 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 +### 4.2.4 Install Site-Wide -`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: +`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 +* `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: @@ -314,181 +290,182 @@ See the [TeX FAQ](https://www.texfaq.org/FAQ-what-TDS). We can understand the fo | | | | `$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 +Create the directories in the left-hand column. For manual installation, move or copy the files in the right-hand column to their respective directories in the left-hand column. Change file ownership as needed. 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). -* `Makefile` has been upgraded to handle more special cases and not to do unexpected or bad things in those cases, especially on Windows. +# 5 More on Package Building -* 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 package and manual build on current and older TeX distributions, being designed with that in mind. -* 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`. +* The documentation is built only with `pdflatex` for the sake of its design elements. The examples and tests can be built with any LaTeX engine. -* This release was tested on Linux (Pop! OS; vanilla TL 2023 and 2017) and Windows 10 (MikTeX using shells from 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. +* This release was tested on Linux (Pop! OS; vanilla TL, both current and 2017) and Windows 10 (MikTeX using shells from both Cygwin and WSL). Using TL 2017, this release was tested on the full manuscript of the published volume, *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 2023 on Pop! OS. The most recent `equivs` file was used to meet package equivalences. See also [this page](https://tug.org/texlive/debian.html). +* The CTAN release was created with the current vanilla TL on Pop! OS. See also [this page](https://tug.org/texlive/debian.html) for Debian-based systems. For Arch-based systems, the AUR has a package that takes care of dependencies. -* TeXlive 2023 and TL 2017 are managed on Pop! OS using [tl-switch](https://github.com/ServusCarolus/tl-switch). +* TeXlive versions 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 +# 6 Examples / Testing -The file `examples.tex`, also includes `compat.tex`; they should be in the same directory when compiled. The examples document 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. It also includes other material and tests. +The file `examples.tex` also includes `compat.tex`; they should be in the same directory when compiled. The examples document 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. It also includes other material and tests. -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. +In addition to this file, a special run of `nameauth.dtx` that defines the macro `\NameauthDoTestFiles` will generate many separate test files. They are not included in the package archive by default. -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. +To test `nameauth`, either test the files right after installing, or create a new testing directory. One then can copy the files from the TDS-compliant source dir and optionally, the documentation directory as well, or unpack the CTAN zip file into the test directory and build the package. -## 6.1 GNU make: Examples, Tests, Images +## 6.1 Using GNU `make` + +### 6.1.1 Examples * Use the default: `make examples`. * If one wants to change engines and re-test the file, type `make exclean`. * 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 - -* 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. By default it will compile all of the test files using `pdflatex`. - -* If one wants to change engines and re-test the files, type `make testclean`. -* One can add the value of ENGINE: - - make tests ENGINE=xelatex - make tests ENGINE=lualatex - make tests ENGINE=dvilualatex - make tests ENGINE=latex + make examples ENGINE=xelatex + make examples ENGINE=lualatex + make examples ENGINE=dvilualatex + make examples ENGINE=latex -* If, for some reason, one wanted to make the manual illustrations (usually not required), one would type `make images`. +* To add more options, use, e.g.: -## 6.2 Manual Method + make examples ADDOPTS="--synctex=1" -### 6.2.1 Examples +### 6.1.2 Tests -Compile `examples.tex`. In the following command lines, one may substitute `latex`, `xelatex`, `lualatex`, and `dvilualatex` for `pdflatex`. +This will produce many test files numbered by chapter and example within that chapter from the `nameauth.dtx` file. By default it will compile all of the test files using `pdflatex`. - pdflatex --interaction=nonstopmode examples - pdflatex --interaction=nonstopmode examples - makeindex -o examples.ind examples.idx +* To generate test files, type `make tests`. -This next line is needed because the `index` package makes an index of persons. +* If one wants to change engines and re-test the files, type `make testclean`. - makeindex -o examples.rnd examples.rdx +* One can add the value of ENGINE: -These lines complete the indexes and TOC. + make tests ENGINE=xelatex + make tests ENGINE=lualatex + make tests ENGINE=dvilualatex + make tests ENGINE=latex - pdflatex --interaction=nonstopmode examples - pdflatex --interaction=nonstopmode examples +* To add more options, use, e.g.: -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. + make tests ADDOPTS="--synctex=1" - dvipdfmx examples +### 6.1.3 Manual Illustrations -If one changes LaTeX engines, one first must remove all of the auxiliary files. +Four manual illustrations are based on included tests. If, for some reason, one wanted to create those illustrations (usually not required), one would type `make images`. -### 6.2.2 Tests +## 6.2 Manual Method + +### 6.2.1 Examples -Generate the test files in the following manner from the `dtx`: +* Compile `examples.tex`. - pdflatex "\def\NameauthDoTestFiles{}\input{nameauth.dtx}" + In the following command lines, one may substitute `latex`, `xelatex`, `lualatex`, and `dvilualatex` for `pdflatex`. -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 examples + pdflatex --interaction=nonstopmode examples + makeindex -o examples.ind examples.idx - pdflatex --interaction=nonstopmode test01-01 - pdflatex --interaction=nonstopmode test01-01 - makeindex -o test01-01.ind test01-01.idx +* This next line is needed because the `index` package makes an index of persons. -This next line is needed only for `test07-01.tex` because the `index` package is used for an index of persons. + makeindex -o examples.rnd examples.rdx - makeindex -o test07-01.rnd test07-01.rdx +* These lines complete the indexes and TOC. -These lines complete the indexes and TOC. + pdflatex --interaction=nonstopmode examples + pdflatex --interaction=nonstopmode examples - pdflatex --interaction=nonstopmode test01-01 - pdflatex --interaction=nonstopmode test01-01 +* Another step is used only with `latex` and `dvilualatex`. -This step is used only when using `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 test01-01 + dvipdfmx examples If one changes LaTeX engines, one first must remove all of the auxiliary files. -### 6.2.3 Images +### 6.2.2 Tests -If, for some reason, one wants to make the manual illustrations (usually not required), this would be the default procedure: +* Generate the test files in the following manner from the `dtx`: -Generate the test files in the following manner from the `dtx`: + pdflatex "\def\NameauthDoTestFiles{}\input{nameauth.dtx}" - pdflatex "\def\NameauthDoTestFiles{}\input{nameauth.dtx}" +* Compile the test files. -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 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 + pdflatex --interaction=nonstopmode test01-01 + pdflatex --interaction=nonstopmode test01-01 + makeindex -o test01-01.ind test01-01.idx - 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 +* This next line is needed only for `test07-01.tex` because the `index` package is used for an index of persons. -# 7. Additional Notes + makeindex -o test07-01.rnd test07-01.rdx -Version 4.0 switches from `xargs` and `suffix` to `xparse`. Should any modifications still require `xargs` and `suffix`, one can use the `oldargs` package option. +* These lines complete the indexes and TOC. -Improvements in version 4.0 include: + pdflatex --interaction=nonstopmode test01-01 + pdflatex --interaction=nonstopmode test01-01 -* Change to `xparse`, which increases power and flexibility going forward. +* This step is used only when using `latex` and `dvilualatex`. -* Further changes to the manual that make it more readable and consistent. + dvipdfmx test01-01 -Version 3.7 remains here: [style](https://www.tug.org/svn/texlive/branches/branch2022.final/Master/texmf-dist/tex/latex/nameauth/), [docs](https://www.tug.org/svn/texlive/branches/branch2022.final/Master/texmf-dist/doc/latex/nameauth/), and [source](https://www.tug.org/svn/texlive/branches/branch2022.final/Master/texmf-dist/source/latex/nameauth/). +If one changes LaTeX engines, one first must remove all of the auxiliary files. -Improvements in version 3.7 include: -* Rejection of stale assumptions that had built up over time, based either on initial ignorance or on features that have since changed in LaTeX. +### 6.2.3 Images + +Four manual illustrations are based on included tests. If, for some reason, one wanted to make the manual illustrations (usually not required), this would be the default procedure: + +* Generate the test files in the following manner from the `dtx`: + + pdflatex "\def\NameauthDoTestFiles{}\input{nameauth.dtx}" -* The examples file contains some tests that used to be in the documentation. +* Compile the test files: -* Major rewrite of documentation. + 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 -* The table of contents better frflects scope and sequence. + 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 -* The package itself has been reorganized to follow the same scope and sequence as the documentation. +* Split and convert the files. If `pdfjam` is not available, one would have to use other programs to do this. -* Several macros have been optimized, leading to simpler and cleaner designs that are easier to debug. Additional bug fixes ensure stability, + 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 -* Name arguments shown in package warnings are detokenized in order to prevent potential errors. +# 7 Additional Notes -# 8. Copyright +Starting from version 4.0 we switched from `xargs` and `suffix` to `xparse`. Should any modifications still require `xargs` and `suffix`, one can use the `oldargs` package option. -Copyright (C) 2024 by Charles P. Schaum <charles[dot]schaum@comcast.net> +Version 3.7 remains here: [style](https://www.tug.org/svn/texlive/branches/branch2022.final/Master/texmf-dist/tex/latex/nameauth/), [docs](https://www.tug.org/svn/texlive/branches/branch2022.final/Master/texmf-dist/doc/latex/nameauth/), and [source](https://www.tug.org/svn/texlive/branches/branch2022.final/Master/texmf-dist/source/latex/nameauth/). + +# 8 Copyright + +Copyright (C) 2025 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: +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: - [https://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. +and version 1.3 or later is part of all distributions +of LaTeX version 2005/12/01 or later. +This work includes all source and generated files +described as such in this file, README.md. %readmevb %</readme> %<*internal> @@ -507,17 +484,20 @@ version 2005/12/01 or later. This is a generated file. -Copyright (C) 2024 by Charles P. Schaum <charles[dot]schaum@comcast.net> +Copyright (C) 2025 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: +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: 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. +and version 1.3 or later is part of all distributions +of LaTeX version 2005/12/01 or later. + +This work includes all source and generated files +described as such in README.md, included herein. \endpreamble @@ -559,73 +539,72 @@ and version 1.3 or later is part of all distributions of LaTeX version %<package>\NeedsTeXFormat{LaTeX2e}[2005/12/01] %<package>\ProvidesPackage{nameauth} %<*package> - [2024/02/09 4.0 Name authority mechanism for consistency in text and index] + [2025/02/04 4.1 Name authority mechanism for consistency in text and index] %</package> % %<*driver> -%^^A %%%%%%%%%%%%% Stuff Needed in the Document Preamble %%%%%%%%%%%%%%%%% +%^^A %%%%%%%%%%%%%%%%%%%%%%% Start of Preamble %%%%%%%%%%%%%%%%%%%%%%%%%% \documentclass[11pt]{ltxdoc} -%^^A %%%%% General layout %%%%% + +%^^A @@@@@ General Document Layout @@@@@ %^^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} + textheight=239.4mm,textwidth=138mm, + right=20mm,marginparwidth=40mm, + marginparsep=4mm,nohead]{geometry} %^^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 Redefine emphasis in the body text because italic has dedicated uses. -\let\oldemph\emph -\let\emph\textbf -%^^A %%%%% Detecting LaTeX engine used %%%%% +%^^A @@@@@ Detecting LaTeX engine used @@@@@ %^^A Since we only use pdflatex to make the documentation, -%^^A this section is not as much of a big deal as it used to be. -%^^A We still use these macros for some detection examples. - +%^^A We only use these macros for some detection examples. %^^A We need etoolbox for this functionality. \usepackage{etoolbox} -%^^A Provide a macro to check against latex versions and set a flag. +%^^A Provide a macro to check latex versions and define a macro. %^^A This must be done in the document preamble. -%^^A We use the date 2018/10/05 because that is when unicode +%^^A We use the date 2018/10/05 because that is when Unicode %^^A processing changed for the better. %^^A We use the date 2018/04/30 because that is when xparse %^^A added the ! modifier. \makeatletter - \@ifl@t@r\fmtversion{2018/10/05}{\def\nameauthltx{}}{} - \@ifl@t@r\fmtversion{2018/04/30}{\def\nameauthxp{}}{} + \@ifl@t@r\fmtversion{2018/10/05}{\newcommand\nameauthltx{}}{} + \@ifl@t@r\fmtversion{2018/04/30}{\newcommand\nameauthxp{}}{} \makeatother -%^^A %%%%% Set up fonts and typography %%%%% -%^^A Again, this is specific to our use of pdflatex. +%^^A @@@@@ Set up fonts and typography @@@@@ + %^^A We do not load inputenc unless we are using an old distro. \IfFileExists{utf8-2018.def}{}{\usepackage[utf8]{inputenc}} -\usepackage[LGR,TS1,T1]{fontenc} +\usepackage[TS1,T1]{fontenc} + +%^^A We load the Latin Modern font. +\usepackage{lmodern} + +%^^A Load the dangerous bend symbol. +\usepackage{manfnt} %^^A We load textcomp for backward compatibility. \usepackage{textcomp} -%^^A We demonstrate hyphenation only with English and German. -%^^A Otherwise we don't hyphenate any other languages. -\usepackage[ngerman,latin,polutonikogreek,american]{babel} +%^^A Use babel for languages. +\usepackage[main=american, ngerman, latin, polutonikogreek]{babel} +\newcommand\DE[1]{{\itshape\foreignlanguage{ngerman}{#1}}} \newcommand\de[1]{\foreignlanguage{ngerman}{#1}} +\newcommand{\LA}[1]{{\itshape\foreignlanguage{latin}{#1}}} \newcommand{\la}[1]{\foreignlanguage{latin}{#1}} \newcommand{\el}[1]{\foreignlanguage{polutonikogreek}{#1}} -%^^A The Latin Modern font gives us the glyphs that we need. -\usepackage{lmodern} +%^^A Use this in Greek text. +\edef\nbsp{~} %^^A This bit is for an example that involves accents and names. \usepackage{newunicodechar} @@ -633,20 +612,67 @@ and version 1.3 or later is part of all distributions of LaTeX version \DeclareTextSymbol{\textlongs}{TS1}{115} \newunicodechar{ſ}{\textlongs} -%^^A Load the dangerous bend symbol and microtypography.. -\usepackage{manfnt} +%^^A Use microtypography. \usepackage{microtype} %^^A Do not automatically put extra space after a full stop. \frenchspacing -%^^A %%%%% Set up specific document elements %%%%% +%^^A Redefine emphasis in the body text because italic has dedicated uses. +\let\oldemph\emph +\let\emph\textbf + +\let\Title\textit + + +%^^A ----- Font debugging; only for developer use ----- + +%^^A These two macros help track down changes to font sizes. +%^^A They can be used only one time each. +\let\savegraf\everypar +\makeatletter +\newcommand\FontDebugStart +{%^^A + \let\oldep\everypar%^^A + \newtoks\everypar%^^A + \oldep{\the\everypar \llap{%^^A + \hbox to \marginparwidth {\f@size\hfill}}}%^^A +} +\newcommand\FontDebugStop +{%^^A + \let\oldep\savegraf%^^A + \oldep{\the\everypar}%^^A +} +\makeatother + + +%^^A @@@@@ Set up specific document elements @@@@@ + + +%^^A ----- Names, the reason for it all ----- + +%^^A Include specifically the current version of the package. +\usepackage{\jobname}[2025/02/04] + +%^^A Set up the ``actual'' character +\IndexActual{=} + + +%^^A ----- Vertical space ----- + +%^^A Define negative skip values. +\newcommand\negsmallskip{\vspace{-\smallskipamount}} +\newcommand\negmedskip{\vspace{-\medskipamount}} +\newcommand\negbigskip{\vspace{-\bigskipamount}} + %^^A ----- TOC and index ----- %^^A Two-column TOC \usepackage[toc]{multitoc} +\newcommand\TOCbreak{\addtocontents{toc}{\protect\goodbreak}} + %^^A Include an index \usepackage{makeidx} @@ -656,22 +682,19 @@ and version 1.3 or later is part of all distributions of LaTeX version \CodelineIndex \RecordChanges + %^^A ----- Color and graphical diagram elements ----- %^^A Color helps categorize information. \usepackage{xcolor} -\colorlet{nared}{red!60!black} -\colorlet{nagreen}{green!35!black} -\colorlet{nablue}{blue!50!black} -\colorlet{nabrown}{brown!50!black} -\colorlet{naslate}{cyan!45!black} -\colorlet{nagrey}{black!7!white} +\colorlet{nared}{red!80!black} +\colorlet{nagrey}{white!93!black} %^^A Use color for yes/no indicators in 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} +\newcommand\NO{{%^^A + \color{white!80!black}\lower 0.075ex\hbox{\rule{1.5ex}{1.5ex}}}} +\newcommand\YES{{%^^A + \color{black}\lower 0.075ex\hbox{\rule{1.5ex}{1.5ex}}}} %^^A Diagrams \usepackage{tikz} @@ -680,25 +703,38 @@ and version 1.3 or later is part of all distributions of LaTeX version %^^A Set basic format for tcolorboxes drawn by TikZ. \tcbset{fonttitle=\bfseries\sffamily,box align=top,lower separated=false} + %^^A ----- Hyperlinks and URLs ----- %^^A Have documentation with hyperlinks \usepackage[numbered]{hypdoc} %^^A Change URL color -\hypersetup{urlcolor=violet} +\hypersetup{urlcolor=purple} -%^^A ----- Tables, lists, quotes, center ----- + +%^^A ----- Tables, lists, quote, center ----- \usepackage{booktabs} \usepackage{colortbl} -\usepackage[inline]{enumitem} +%^^A Margin note in a table +\newcommand\tmarg[2][white] +{%^^A + \llap + {%^^A + \colorbox{#1}{\hbox to 0.8\marginparwidth{\strut\hfill #2}}%^^A + \qquad\qquad%^^A + }%^^A +} + +\usepackage{enumitem} \setlist{rightmargin=\leftmargin,itemsep=0pt} -%^^A Make default font small for quote and center environments -\apptocmd{\quote}{\small}{}{} -\apptocmd{\center}{\small}{}{} +%^^A Make default font small for Quote and Center environments +\newenvironment{Quote}{\begin{quote}\small}{\end{quote}} +\newenvironment{Center}{\begin{center}\small}{\end{center}} + %^^A ----- Verbatim environments ----- @@ -708,96 +744,58 @@ and version 1.3 or later is part of all distributions of LaTeX version %^^A Define fancyvrb defaults. \fvset{gobble=2,numbers=left,fontsize=\small} -%^^A ----- Font debugging; only for dev use ----- - -%^^A These two macros help track down any unintended changes to font sizes. -%^^A One can use these only once each. -\let\savegraf\everypar -\makeatletter -\newcommand\FontDebugStart -{%^^A - \let\oldep\everypar%^^A - \newtoks\everypar%^^A - \oldep{\the\everypar \llap{\color{red}\hbox to \marginparwidth {\f@size\hfill}}}%^^A -} -\newcommand\FontDebugStop -{%^^A - \let\oldep\savegraf%^^A - \oldep{\the\everypar}%^^A -} -\makeatother %^^A ----- Various text elements ----- -%^^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\Same - {\Info{Same name patterns\break and index entries\break as above.}} - -%^^A Show a name pattern in margin. -\newcommand*\PatInfo[1] +\NewDocumentCommand{\Info}{s O{0ex} m} {%^^A \unless\ifinner - {%^^A - \marginpar - {\raggedleft\footnotesize Name Pattern(s):\hfill\break - \ttfamily#1}%^^A - }%^^A + \begingroup%^^A + \microtypesetup{activate=false}%^^A + \IfBooleanTF{#1} + {\leavevmode\marginpar{\raggedleft\footnotesize#3}} + {%^^A + \vspace{\dimexpr#2\relax}%^^A + \marginpar{\raggedleft\footnotesize#3}%^^A + \vspace{\dimexpr-#2\relax}%^^A + }%^^A + \endgroup%^^A \fi } -%^^A Show a basic index entry info in margin. -\newcommand*\IdxInfo[1] +%^^A Show name patterns in margin. +\NewDocumentCommand{\PatInfo}{s O{0ex} m} {%^^A - \unless\ifinner - {%^^A - \marginpar{\raggedleft\footnotesize Basic Index:\hfill\break#1}%^^A - }%^^A - \fi + \IfBooleanTF{#1} + {\Info*{Name Pattern(s):\hfill\break{\ttfamily #3}}} + {\Info[#2]{Name Pattern(s):\hfill\break{\ttfamily #3}}}%^^A } %^^A Show both name patterns and index entries in margin. -\newcommand*\BothInfo[2] +\NewDocumentCommand{\BothInfo}{s O{0ex} m m} {%^^A - \unless\ifinner - {%^^A - \marginpar{%^^A - \raggedleft\footnotesize Name Pattern(s):\hfill\break%^^A - {\ttfamily#1}\break%^^A - \raggedleft\footnotesize Basic Index:\hfill\break#2%^^A - }%^^A - }%^^A - \fi + \IfBooleanTF{#1} + {\Info*{Name Pattern(s):\hfill\break{\ttfamily #3}%^^A + \break Basic Index:\hfill\break #4}} + {\Info[#2]{Name Pattern(s):\hfill\break{\ttfamily #3}%^^A + \break Basic Index:\hfill\break #4}}%^^A } %^^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 + \begin{center} + \normalsize%^^A + \tcbox[colback=nagrey]{Back to \hyperlink{TOC}{Table of Contents}} + \end{center} } %^^A Print a high-visibility callout that can have an optional title. \newenvironment{InfoBox}[1][] {%^^A + \begin{quote}\negmedskip\normalsize%^^A \def\titulus{#1}%^^A - \medskip%^^A \ifx\titulus\empty \begin{tcolorbox}[colback=white,colframe=red!90!black]%^^A \else @@ -805,13 +803,13 @@ and version 1.3 or later is part of all distributions of LaTeX version adjusted title={\bfseries\hfil #1}]%^^A \fi } -{\end{tcolorbox}\medskip} +{\end{tcolorbox}\end{quote}} -%^^A Print a callout that can have an optional title. +%^^A Print a one-cell callout that can have an optional title. \newenvironment{SyntaxBox}[1][] {%^^A + \begin{quote}\negmedskip\normalsize%^^A \def\titulus{#1}%^^A - \begingroup\medskip \ifx\titulus\empty \begin{tcolorbox}[colback=white,colframe=darkgray]%^^A \begin{tabular}{@{}l@{}} @@ -821,61 +819,66 @@ and version 1.3 or later is part of all distributions of LaTeX version \begin{tabular}{@{}l@{}} \fi } -{\end{tabular}\end{tcolorbox}\medskip\endgroup} +{\end{tabular}\end{tcolorbox}\end{quote}} %^^A Print a two-cell callout that can have an optional title. \newenvironment{SyntaxBoxii}[1][] {%^^A + \begin{quote}\negmedskip\normalsize%^^A \def\titulus{#1}%^^A \ifx\titulus\empty \begin{tcolorbox}[colback=white,colframe=darkgray]%^^A - \begingroup\begin{tabular}{@{}ll@{}} + \begin{tabular}{@{}ll@{}} \else \begin{tcolorbox}[colback=white,colframe=darkgray, adjusted title={\bfseries\hfil #1}]%^^A - \begingroup\begin{tabular}{@{}ll@{}} + \begin{tabular}{@{}ll@{}} \fi } -{\end{tabular}\endgroup\end{tcolorbox}\medskip} +{\end{tabular}\end{tcolorbox}\end{quote}} %^^A Print a quote and the source. - \renewcommand{\hrulefill}{% - \leavevmode\leaders\hrule height 1.5pt\hfill\kern0pt } + \leavevmode\leaders\hrule height 1.5pt\hfill\kern0pt} -\newenvironment{Quote}[1] +\newenvironment{Quotation}[2] {%^^A - \def\QuoteName{#1}%^^A - \vfill\noindent\hfil\hbox to 0.9\textwidth{\hrulefill} - \begin{quote}} -{\negmedskip\end{quote}\begin{quote}\hfill---\QuoteName\end{quote}} + \vfill%^^A + \begingroup%^^A + \small\noindent\hrulefill + \begin{quote}%^^A + \newcommand\QuoteName{#1}%^^A + \newcommand\QuotePub{#2}} +{\par\negbigskip\hbox{}\hfill---\ForgetThis\QuoteName%^^A + \unless\ifx\QuotePub\empty \\\hbox{}\hfill\QuotePub\fi + \end{quote}%^^A + \endgroup%^^A +} -%^^A Used for one or more examples +%^^A Used for many examples \newenvironment{Block} -{%^^A - \begin{quote} - \setlist{rightmargin=0pt,leftmargin=0pt,topsep=0ex,itemsep=0pt}%^^A - \begin{itemize}\item[] -} -{\end{itemize}\end{quote}} +{\begin{Quote}\microtypesetup{activate=false}} +{\end{Quote}} + +%^^A Used to show when macros may need to be global. +\newcommand\Global{\Info*{\small\cmd{\global}}} %^^A Warning repeated throughout the manual \newcommand\NameArgWarning {%^^A \begin{InfoBox}%^^A - When a macro occurs in a name argument appearing in both text - and index, fix any concerns about macro expansion by using - \cmd{\noexpand} before that macro. + Address any concerns about expansion of macros in name arguments + by using \cmd{\noexpand} before those macros. \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 + \quad\tcbox[boxsep=0.2ex,colback=nagrey] + {\textls[-20]{\hyperlink{State #2}{Stay in State #2}}}%^^A }%^^A } @@ -883,46 +886,43 @@ and version 1.3 or later is part of all distributions of LaTeX version {%^^A \parbox{0.685\textwidth}{#1\dotfill}%^^A \lower 2ex\hbox{%^^A - \quad\tcbox[boxsep=0.2ex]{\textls[30]{Go to State #2}}%^^A + \quad\tcbox[boxsep=0.2ex,colback=nagrey] + {\textls[30]{\hyperlink{State #2}{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}} +\newcommand\UseL{\leavevmode\hbox to 5em{Long use:\hfill}} +\newcommand\UseS{\leavevmode\hbox to 5em{Short use:\hfill}} \newcommand\UseB{\leavevmode\hbox to 5em{\hfill}} - -%^^A ----- Names, the reason for it all ----- - -%^^A Include specifically the current version of the package. -\usepackage{\jobname}[2024/02/09] - -%^^A Set up the ``actual'' character -\IndexActual{=} - -%^^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} +\newcommand\UseI{\leavevmode\hbox to 5em{Index:\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} +\TagName[Lost]{Name}{ \S|Orphan{perdit}} +\TagName{foo\Name {bar}}{ \S|hyperpage} + +%^^A Define macros to differentiate name arguments. +\newcommand\nri{} +\newcommand\nrii{} %^^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 tags for all names just below, especially in a dtx file, where the +%^^A vertical bars are active. \begin{nameauth} \< Aeth & & Æthelred, II & > \< Aris & & Aristotle & > \< Bailey & Betsey & Bailey & > + \< Bradley & Omar N. & Bradley & > \< Carter & J.E. & Carter, Jr. & > + \< CatoE & Marcus Porcius & Cato, the Elder & > + \< CatoEi & Marcus & Porcius Cato the Elder & > + \< CatoY & Marcus Porcius & Cato, the Younger & > + \< CatoYi & Marcus Porcius & Cato the Younger & > \< Cicero & M.T. & Cicero & > \< Confucius & & Confucius & > \< Dagb & & Dagobert & I > @@ -935,7 +935,14 @@ and version 1.3 or later is part of all distributions of LaTeX version \< AltDuBois & W.E.B. & DuBois & > \< Einstein & Albert & Einstein & > \< Eliz & & Elizabeth, I & > + \< Faisal & & Faisal, bin Abdulaziz & > \< Fukuyama & & \noexpand\textUC{Fukuyama} & Takeshi > + \ifdefined\nameauthltx + \< Ghazali & & Ghazāli & > + \else + \< Ghazali & & Ghazali & > + \fi + \< JLF & Jean de & La Fontaine & > \< JWG & J.W. von & Goethe & > \< TGrac & \noexpand\TSemp & Gracchus & > \< Harnack & Adolf & Harnack & > @@ -954,6 +961,7 @@ and version 1.3 or later is part of all distributions of LaTeX version \noexpand\textSC{Medici} & > \< Miyazaki & & Miyazaki, Hayao & > \< MSens & & Miyazaki, Hayao & Sensei > + \< Molnar & Frenec & Molnár & > \< Noguchi & Hideyo & Noguchi & > \< Patton & George S. & Patton, Jr. & > \< Plato & & Plato & > @@ -961,6 +969,8 @@ and version 1.3 or later is part of all distributions of LaTeX version \< JayR & J.D. & Rockefeller, IV & Jay > \< Scipio & \noexpand\SCIPi & \noexpand\SCIPii & > \< OScipio & Lucius & \noexpand\CSB & > + \< Senecai & Lucius Annaeus & Seneca\nri & > + \< Senecaii & Lucius Annaeus & Seneca\nrii & > \< Shak & \noexpand\WM & \noexpand\SHK & > \< Striet & John & \noexpand\de{Strietelmeier} & > \< Sun & & Sun, Yat-sen & > @@ -968,7 +978,6 @@ and version 1.3 or later is part of all distributions of LaTeX version \< KempW & Thomas & à~Kempis & > \< Tyson & Mike & Tyson & > \< Iron & Mike & Tyson & Iron Mike > - \< VBuren & Martin & Van Buren & > \< Wash & George & Washington & > %^^A We use the next row as an example in the docs. %^^A \< White & E.\,B. & White & > @@ -976,8 +985,18 @@ and version 1.3 or later is part of all distributions of LaTeX version \< Yosh & & Yoshida & Shigeru > \end{nameauth} -%^^A Add sort tags here for those needing them. +%^^A Exclude names form from the index. +%^^A We index them without the comma. +\ExcludeName[Marcus Porcius]{Cato, the Elder} +\ExcludeName[Marcus Porcius]{Cato, the Younger} +%^^A Add a name tag. We usually do this in +%^^A the running text below, but we do it here too. +\NameAddInfo{Faisal, bin Abdulaziz}{ Al Saud} + +%^^A Add index sorting tags here for names needing them. +%^^A That includes active Unicode, spaces, Roman numerals, +%^^A and macros in names. \PretagName{Æthelred, II}{Aethelred 2} \PretagName[Thomas]{à~Kempis}{Akempis, Thomas} \PretagName{Antiochus, III}{Antiochus 3} @@ -991,6 +1010,7 @@ and version 1.3 or later is part of all distributions of LaTeX version \PretagName[Giovanni]{d'Andrea}{Dandrea, Giovanni} \PretagName{Demetrius, I}{Demetrius 1} +\PretagName[Walter]{de la Mare}{delaMare, Walter} \PretagName[Jacques]{De~Pamele}{Depamele, Jacques} \PretagName[Charles-Louis]{de Secondat}{deSecondat, Charles} \PretagName[Pierre-Jean]{\noexpand\Fbox{\noexpand\AltCaps{d}e~Smet}} @@ -1001,21 +1021,27 @@ and version 1.3 or later is part of all distributions of LaTeX version \PretagName[W.E.B.]{Du~Bois}{DuBois, William} \PretagName{du~Cange}{Ducange} \PretagName[Charles]{du~Fresne}{Dufresne, Charles} +\PretagName[S.J.]{Du Toit}{DuToit, Stephanus} \PretagName{Elizabeth, I}{Elizabeth 1} \PretagName{\noexpand\textUC{Fukuyama}}[Takeshi]{Fukuyama Takeshi} \PretagName[Greta]{\noexpand\textSC{Garbo}}{Garbo, Greta} +\ifdefined\nameauthltx \PretagName{Ghazāli}{Ghazali} +\fi \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[Jean de]{La Fontaine}{LaFontaine, Jean de} +\PretagName[Manuel Antonio]{Las Heras}{LasHeras, Manuel} +\PretagName[Pierre]{L'Enfant}{LEnfant, Pierre} \PretagName[Ada]{\noexpand\textIT{Lovelace}}{Lovelace, Ada} \PretagName[Martin]{\noexpand\textSC{Luther}}{Luther, Martin} @@ -1034,39 +1060,53 @@ and version 1.3 or later is part of all distributions of LaTeX version {Ruehmann, Heinrich Wilhelm} \PretagName[Heinz]{\noexpand\textSC{R\"uhmann}}{Ruehmann, Heinz} +\PretagName[Lucius Annaeus]{Seneca\nri}{Seneca, Lucius Annaeus 1} +\PretagName[Lucius Annaeus]{Seneca\nrii}{Seneca, Lucius Annaeus 2} \PretagName{Seleucus, III}{Seleucus 3} \PretagName[\noexpand\SCIPi]{\noexpand\SCIPii}{Scipio Africanus} \PretagName[Lucius]{\noexpand\CSB}{Cornelius Scipio Barbatus} \PretagName[\noexpand\WM]{\noexpand\SHK}{Shakespeare, William} \PretagName{\textit{Snellius}}{Snellius} \PretagName[John]{\noexpand\de{Strietelmeier}}{Strietelmeier, John} +\PretagName[John]{\unexpanded{\noexpand\de{Strietelmeier}}} + {Strietelmeier, John} \PretagName{Thomas, à~Kempis}{Thomas Akempis} +\PretagName[Martin]{Van Buren}{VanBuren, Martin} +\PretagName[Daisy]{Ver Boven}{VerBoven, Daisy} \PretagName{Vlad, {\c T}epe{\c s}}{Vlad Tepes} \PretagName[E.\,B.]{White}{White, Elwyn} +\PretagName[Otto]{Zur Linde}{ZurLinde, Otto} \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{Attila, the Hun}{|hyperpage} \TagName[W.H.]{Auden}{|hyperpage} \TagName[Charles]{\noexpand\textBF{Babbage}}{|hyperpage} \TagName[Betsey]{Bailey}{|hyperpage} +\TagName[Omar N.]{Bradley}{|hyperpage} \TagName[Leonard]{Bernstein}{|hyperpage} \TagName{Bernard, of Clairvaux}{|hyperpage} \TagName{Bo\"ethius}{|hyperpage} +\TagName[Anic. Manl.]{Severinus Boethius}{|hyperpage} +\TagName[Max]{Born}{|hyperpage} +\TagName[Bernhard ten]{Brink}{|hyperpage} +\TagName[Ferris]{Bueller}{ \S|hyperpage} \TagName[Robert]{\textSC{Burns}}{|hyperpage} \TagName[Julius]{Caesar}{, imperator|hyperpage} \TagName[Rudolph]{Carnap}{|hyperpage} \TagName[J.E.]{Carter, Jr.}{, pres.|hyperpage} +\TagName[Marcus]{Porcius Cato the Elder}{|hyperpage} +\TagName[Marcus Porcius]{Cato the Younger}{|hyperpage} \TagName[Charlie]{Chaplin}{|hyperpage} \TagName[Charles W.]{Chesnutt}{|hyperpage} \TagName[M.T.]{Cicero}{|hyperpage} @@ -1079,6 +1119,7 @@ and version 1.3 or later is part of all distributions of LaTeX version \TagName{Dagobert}[I]{\ddag, king|hyperpage} \TagName[Sammy]{Davis,Jr.}{|hyperpage} \TagName[Giovanni]{d'Andrea}{|hyperpage} +\TagName[Walter]{de la Mare}{|hyperpage} \TagName{Demetrius, I}{ Soter, king|hyperpage} \TagName[Jacques]{De~Pamele}{|hyperpage} \TagName[Pierre-Jean] @@ -1088,6 +1129,7 @@ and version 1.3 or later is part of all distributions of LaTeX version \TagName[Frederick]{Douglass}{|hyperpage} \TagName[W.E.B.]{Du~Bois}{|hyperpage} \TagName[Charles]{du~Fresne}{|hyperpage} +\TagName[S.J.]{Du Toit}{|hyperpage} \TagName[Albert]{Einstein}{|hyperpage} \TagName[Dwight D.]{Eisenhower}{, pres.|hyperpage} @@ -1095,6 +1137,9 @@ and version 1.3 or later is part of all distributions of LaTeX version \TagName[Leif]{Erikson}{|hyperpage} \TagName[Robin]{Fairbairns}{|hyperpage} +\TagName{Faisal, bin Abdulaziz}{ Al Saud, king|hyperpage} +\TagName[Francisco de]{Figueroa}{|hyperpage} +\TagName[Cameron]{Frye}{ \S|hyperpage} \TagName{\noexpand\textUC{Fukuyama}}[Takeshi]{\ddag|hyperpage} \TagName[Greta]{\noexpand\textSC{Garbo}}{|hyperpage} @@ -1111,6 +1156,7 @@ and version 1.3 or later is part of all distributions of LaTeX version \TagName[Lafcadio]{Hearn}{|hyperpage} \TagName{Hermogenes}{|hyperpage} \TagName{Henry}[VIII]{, king|hyperpage} +\TagName[Herbert]{Hoover}{, pres.|hyperpage} \TagName[Bob]{Hope}{|hyperpage} \TagName[Hubert H.]{Humphrey}{, v.p.|hyperpage} @@ -1124,7 +1170,10 @@ and version 1.3 or later is part of all distributions of LaTeX version \TagName{Kim, Jong Un}{|hyperpage} \TagName[Martin Luther]{King, Jr.}{|hyperpage} +\TagName[Jean de]{La Fontaine}{|hyperpage} \TagName{Lao-tzu}{|hyperpage} +\TagName[Manuel Antonio]{Las Heras}{|hyperpage} +\TagName[Pierre]{L'Enfant}{|hyperpage} \TagName[Clive Staples]{Lewis}{|hyperpage} \TagName[Abraham]{Lincoln}{, pres.|hyperpage} \TagName[Frenec]{Liszt}{\dag|hyperpage} @@ -1153,6 +1202,7 @@ and version 1.3 or later is part of all distributions of LaTeX version \TagName[Sandra Day]{O'Connor}{, justice|hyperpage} \TagName[Heiko]{Oberdiek}{|hyperpage} +\TagName[M.S.]{Omartian}{|hyperpage} \TagName[George S.]{Patton, Jr.}{|hyperpage} \TagName[Lucius]{Sergius Paulus}{|hyperpage} @@ -1172,6 +1222,8 @@ and version 1.3 or later is part of all distributions of LaTeX version \TagName{Saul, of Tarsus}{|hyperpage} \TagName[Robert]{Schlicht}{|hyperpage} \TagName{Seleucus, III}{ Ceraunus, king|hyperpage} +\TagName[Lucius Annaeus]{Seneca\nri}{ (the Elder)|hyperpage} +\TagName[Lucius Annaeus]{Seneca\nrii}{ (the Younger)|hyperpage} \TagName[\noexpand\SCIPi]{\noexpand\SCIPii}{|hyperpage} \TagName[Lucius]{\noexpand\CSB}{, consul|hyperpage} \TagName[\noexpand\WM]{\noexpand\SHK}{|hyperpage} @@ -1195,6 +1247,7 @@ and version 1.3 or later is part of all distributions of LaTeX version \TagName[Martin]{Van Buren}{, pres.|hyperpage} \TagName[Publius]{Vegetius Renatus}{|hyperpage} +\TagName[Daisy]{Ver Boven}{|hyperpage} \TagName[Jesse]{Ventura}{|hyperpage} \TagName{Vlad, II}{ Dracul|hyperpage} \TagName{Vlad, III}{ Dracula|hyperpage} @@ -1202,9 +1255,11 @@ and version 1.3 or later is part of all distributions of LaTeX version \TagName[George]{Washington}{, pres.|hyperpage} \TagName[Alan]{Watts}{|hyperpage} +\TagName[Marcus]{Welby,M.D.}{ \S|hyperpage} \TagName[E.\,B.]{White}{|hyperpage} \TagName{William, I}{, king |hyperpage} \TagName{William, the Conqueror}{|hyperpage} +\TagName[John]{Wyche}{|hyperpage} \TagName{Yamaha, Torakusu}{|hyperpage} \TagName{Yamaha Corp.}{|hyperpage} @@ -1212,18 +1267,20 @@ and version 1.3 or later is part of all distributions of LaTeX version \TagName{Yoshida}[Shigeru]{\ddag, PM|hyperpage} \TagName[Caspar]{Ziegler}{|hyperpage} - +\TagName[Otto]{Zur Linde}{|hyperpage} \TagName[Konrad]{\noexpand\textSC{Zuse}}{|hyperpage} \begin{document} \DocInput{\jobname.dtx} \end{document} +%^^A %%%%%%%%%%%%%%%%%%%%%%% End of Preamble %%%%%%%%%%%%%%%%%%%%%%%%%% %</driver> % \fi +%^^A %%%%%%%%%%%%%%%%%%%%%%% Start of Document %%%%%%%%%%%%%%%%%%%%%%%%%% % -%^^A %%%%%%%%%%%%%%%%%%%%%%% Error Correction %%%%%%%%%%%%%%%%%%%%%%%%%%%% +%^^A @@@@@ Error Correction @@@@@ % -% \CheckSum{3388} +% \CheckSum{3779} % % \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 @@ -1242,21 +1299,17 @@ and version 1.3 or later is part of all distributions of LaTeX version % Right brace \} Tilde \~} % % \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{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}{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.5}{2020/11/23}{Update and merge most included files into \texttt{dtx} file} % \changes{3.7}{2023/02/03}{Major updates to all files} -% \changes{4.0}{2024/02/09}{Improve manual, \texttt{Readme.md}, \texttt{compat.tex}} +% \changes{4.0}{2024/02/09}{Update included files} +% \changes{4.1}{2025/02/04}{Update included files} +% +% +%^^A @@@@@ Administrative Setup @@@@@ % % \GetFileInfo{\jobname.dtx} % @@ -1269,20 +1322,24 @@ and version 1.3 or later is part of all distributions of LaTeX version % \egroup, \else, \endcsname, \endgroup, \endinput, % \ExecuteOptions, \expandafter, \fi, \futurelet, % \global, \hbox, \if, \ifcsname, \ifx, \ignorespaces, -% \index, \itshape, \leavevmode, \let, \newcommand, -% \NewDocumentCommand, \newenvironment, \newif, -% \nobreakspace, \PackageError, \PackageWarning, +% \ignorespacesafterend, \index, \itshape, \leavevmode, +% \let, \newcommand, \NewDocumentCommand, \newenvironment, +% \newif, \nobreakspace, \PackageError, \PackageWarning, % \ProcessOptions, \relax, \renewcommand, % \RequirePackage, \scshape, \textbackslash, \uppercase} % -%^^A %%%%%%%%%%%%%%% Macros That Must Be Defined Here %%%%%%%%%%%%%%%%%%%% % -%^^A Lengths to size tcboxes +%^^A @@@@@ Items Defined Here, or Stuff Doesn't Work @@@@@ +% +%^^A ----- Lengths ----- % % \newlength{\nameboxi} % \newlength{\nameboxii} % \newlength{\nameboxiii} % +% +%^^A ----- Conditionals ----- +% %^^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). @@ -1294,7 +1351,7 @@ and version 1.3 or later is part of all distributions of LaTeX version % \newif\ifGenitive % \newif\ifDoGenitive % -%^^A For the Cornelii Scipiones +%^^A For the Cornelii Scipiones and Gracchi % \newif\ifNoPraenomen % \newif\ifNoGens % \newif\ifNoCognomen @@ -1313,14 +1370,8 @@ and version 1.3 or later is part of all distributions of LaTeX version % \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 ----- Macros in Names ----- % %^^A For Thomas Jefferson % \newcommand*\GEN{\ifDoGenitive\textSC{'s}\fi} @@ -1336,11 +1387,7 @@ and version 1.3 or later is part of all distributions of LaTeX version % } % % \newcommand*\SCIPii -% {^^A -% \ifXAgno Scipio\else -% Scipio Africanus^^A -% \fi -% } +% {\ifXAgno Scipio\else Scipio Africanus\fi} % %^^A For Gracchus % \newcommand*\TSemp @@ -1356,23 +1403,19 @@ and version 1.3 or later is part of all distributions of LaTeX version % \newcommand*\CSB % {^^A % \ifXGens -% \ifXAgno Scipio\else -% Scipio Barbatus\fi +% \ifXAgno Scipio\else Scipio Barbatus\fi % \else % \ifXCogn Cornelius\else % \ifXAgno Cornelius Scipio\else % Cornelius Scipio Barbatus^^A % \fi -% \fi +% \fi\noindent % \fi % } % %^^A For William Shakespeare % \newcommand*\WM -% {^^A -% \ifSpecialFN Wm.\else -% William\fi -% } +% {\ifSpecialFN Wm.\else William\fi} % % \newcommand*\SHK % {^^A @@ -1387,7 +1430,27 @@ and version 1.3 or later is part of all distributions of LaTeX version % % \newcommand*\Revert{\RevertSNtrue} % -%^^A %%%%%%%%%%%%%%%%%%%%%%%%%% Title Page %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +% +%^^A ----- Name Format Standards ----- +% +%^^A Redefine and save name formatting for this manual. +% \begin{VerbatimOut}{manhook.tmp} +% \renewcommand*\FrontNamesFormat{\color{violet}\sffamily} +% \renewcommand*\FrontNameHook{\color{darkgray}\sffamily} +% \renewcommand*\NamesFormat{\color{blue}\sffamily} +% \renewcommand*\MainNameHook{\sffamily} +% \end{VerbatimOut} +% +% \begin{VerbatimOut}{nullhook.tmp} +% \renewcommand*\FrontNamesFormat{} +% \renewcommand*\FrontNameHook{} +% \renewcommand*\NamesFormat{} +% \renewcommand*\MainNameHook{} +% \end{VerbatimOut} +% +% \input{manhook.tmp} +% +%^^A @@@@@ Title Page @@@@@ % % \title{\textsf{nameauth} --- Name authority mechanism\\ % for consistency in text and index^^A @@ -1396,14 +1459,13 @@ and version 1.3 or later is part of all distributions of LaTeX version % \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 instances. % \end{abstract} % -%^^A %%%%%%%%%%%%%%%%%%%%%%%%%%%%%% TOC %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +% +%^^A @@@@@ Table of Contents @@@@@ % % \begingroup % \small @@ -1411,29 +1473,34 @@ and version 1.3 or later is part of all distributions of LaTeX version % \tableofcontents % \endgroup % -% \begin{InfoBox}[Disclaimer] -% This manual mentions names of historical figures both living and deceased. We intend to use all names herein with respect, for teaching purposes only, and never express or imply any disrespect or bias. -% \end{InfoBox} % -% \begin{InfoBox}[Compatibility] -% Starting with version 4.0, \textsf{nameauth} uses \textsf{xparse} for starred macros and name arguments. Benefits include better macro design, more control over arguments, less code duplication, and better customization. -% \begin{itemize} -% \item Use with a pre-2017 \TeX\ distribution might cause occasional errors. See also Sections~\ref{sec:FinalOptargs}, \ref{sec:ChangeParse} and~\ref{sec:CompatON}. -% \item Older user customizations using \textsf{xargs} may still work with the \texttt{oldargs} option. See Sections~\ref{sec:OptionCompat} and~\ref{sec:ChangeParse}. -% \end{itemize} -% If one should require version 3.7, see section 7 of \texttt{README.md}. -% \end{InfoBox} +%^^A ----- Paragraph Skip ----- +%^^A Changed from initial 0pt plus 1pt +% \setlength{\parskip}{2.5pt plus 0.5pt minus 0.5pt} % -% \begin{InfoBox}[Fair Use] -% Other works quoted herein either are in the public domain or they are copyrighted works cited under the terms of fair use, to which the present author claims no copyright. The purpose is to show the power of words and names. -% \end{InfoBox} +% \subsection*{Disclaimer} % -% \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.}^^A -% \index{creatives, quotes of\noexpand\string|hyperpage} -% \end{Quote} +% This manual mentions names of historical figures both living and deceased. We intend to use all names herein with respect, for teaching purposes only, and never to express or imply any disrespect or bias. +% +% \subsection*{Fair Use} +% +% Works quoted herein either are in the public domain or they are under copyright, but cited under the terms of fair use. The transformative purpose is to show the evocative power of words and names. +% +% \subsection*{Thanks} +% +% 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 \LA{In memoriam} \Name[Robin]{Fairbairns}\\[1ex] +% He was very kind when I first uploaded \textsf{nameauth}, and gracious thereafter as well. +% +% \begin{Quotation}{\Wash} +% {Farewell Address (1796)} +% I have already intimated to you the danger of parties in the State, with particular reference to the founding of them on geographical discriminations. Let me now take a more comprehensive view, and warn you in the most solemn manner against the baneful effects of the spirit of party generally. +% +% This spirit, unfortunately, is inseparable from our nature, having its root in the strongest passions of the human mind. It exists under different shapes in all governments, more or less stifled, controlled, or repressed; but, in those of the popular form, it is seen in its greatest rankness, and is truly their worst enemy. +% +% \textls[5]{The alternate domination of one faction over another, sharpened by the spirit of revenge, natural to party dissension, which in different ages and countries has perpetrated the most horrid enormities, 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.} +% \index{politicians, quotes of\noexpand\string|hyperpage} +% \end{Quotation} % % \newpage % @@ -1442,46 +1509,48 @@ and version 1.3 or later is part of all distributions of LaTeX version % \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. Books can contain hundreds of names and index entries. The \textsf{nameauth} package assists academic and business writing to minimize the work of managing many names: -% +% A \emph{name authority} (Section~\ref{sec:NameAuthority}) is a canonical list of names to which variant names refer. Books can have hundreds of names and index entries. The \textsf{nameauth} package assists academic and business writing: % \begin{itemize} -% \item Automate the display and formatting of names. +% \item Automate the syntax 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 Make decisions relating to names. +% % \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 Use culturally appropriate name forms in the text and index. +% +% \item Do not force users to use any particular naming convention. +% % \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 similar information in \textit{The Chicago Manual of Style} (15\textsuperscript{th} ed., Chicago: Chicago UP, 2003, 309f., 755f.) or newer editions; referenced as [\hypertarget{Chicago}{Chicago}]. +% Indexing rules are based on \Name[Nancy C.]{Mulvany}, \Title{Indexing Books} (Chicago: University of Chicago Press, 1994). All references [\hypertarget{Mulvany}{Mulvany}] refer to this edition.\footnote{Compare \Title{The Chicago Manual of Style} (15\textsuperscript{th} ed., Chicago: Chicago UP, 2003, 309f., 755f.) or newer editions. All references [\hypertarget{Chicago}{Chicago}] refer to this edition.} % % \subsection{Simple Example} -% \label{sec:QuickExample} -% \begingroup -% \renewcommand{\NamesFormat}{} -% \renewcommand{\MainNameHook}{} % -% 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, use only the default \textsf{nameauth} options, and create no extra formatting for names (cf. Section~\ref{sec:Formatting}). +% \input{nullhook.tmp} % -% The \texttt{nameauth} environment (Section~\ref{sec:QuickUIStart}) in the preamble 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. -% -% We use \cmd{\Forgetname} (Section~\ref{sec:NameControl}) in Group 2 to ``forget'' about the names in Group 1. When we reorder the statements, the names change form automatically. +% Using the default \textsf{nameauth} options and formatting hooks (not the general formatting used in this manual; cf. Section~\ref{sec:Formatting}), we show how names change automatically when we reorder statements by African-American author \Name[Charles W.]{Chesnutt}[Charles Waddell].\footnote{\Name[Charles W.]{Chesnutt}, \Title{Frederick Douglass} (Boston: Small, Maynard, 1899). See also \href{https://docsouth.unc.edu/neh/chesnutt/summary.html} {\bfseries this web page}.} % +% The \texttt{nameauth} environment (Section~\ref{sec:QuickUIStart}) resembles a \texttt{tabular} with four columns. In column one we define name shorthands. Columns two and three hold the names. We leave column four empty. \cmd{\ForgetName} (Section~\ref{sec:NameControl}) used before Group~2 lets us ``start over'' with the names by forgetting their patterns. +%^^A % \ifdefined\NameauthDoTestFiles \edef\NameauthTestFile{test01_01.tex}\else % \edef\NameauthTestFile{\jobname.tmp}\fi -% +%^^A % \begin{VerbatimOut}{\NameauthTestFile} % \documentclass{article} % \input{compat.tex} % Included with nameauth; example file aids % % compatibility across different LaTeX versions and engines. % \usepackage{makeidx} % \usepackage{nameauth} -% \usepackage[inline]{enumitem} % \makeindex % % \begin{nameauth} @@ -1492,152 +1561,342 @@ and version 1.3 or later is part of all distributions of LaTeX version % % \begin{document} % -% \textbf{Group 1}\\ -% \begin{enumerate*} -% \item[\textbf{1.}] \Doug\ rose to eminence by sheer force +% \textbf{Group 1} +% \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 +% \item[\textbf{3.}] \Doug\ was born in February, 1817. His % earliest memories centered around the cabin of his % grandmother, \Bailey. -% \end{enumerate*} +% \end{enumerate} % -% \textbf{Group 2}\\ +% \textbf{Group 2} (Statement order changed.) % \ForgetName[Frederick]{Douglass} % \ForgetName[Betsey]{Bailey} -% \begin{enumerate*} +% \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 +% \item[\textbf{3.}] \Doug\ was born in February, 1817. His % earliest memories centered around the cabin of his % grandmother, \Bailey. -% \item[\textbf{1.}] \Doug\ rose to eminence by sheer force +% \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{enumerate} % % \printindex % \end{document} % \end{VerbatimOut} +%^^A +% \begin{Quote} +% \VerbatimInput[gobble=0,lastline=15]{\NameauthTestFile} % -% \begin{quote} -% \VerbatimInput[gobble=0]{\NameauthTestFile} +% \newpage +% +% \VerbatimInput[gobble=0,firstline=16]{\NameauthTestFile} % -% \textbf{Group 1}\\ -% \begin{enumerate*} -% \item[\textbf{1.}] \Doug\ rose to eminence by sheer force +% \textbf{Group 1} +% \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 +% \item[\textbf{3.}] \Doug\ was born in February, 1817. His % earliest memories centered around the cabin of his % grandmother, \Bailey. -% \end{enumerate*} +% \end{enumerate} % -% \textbf{Group 2}\\ +% \textbf{Group 2} (Statement order changed.) % \ForgetName[Frederick]{Douglass} % \ForgetName[Betsey]{Bailey} -% \begin{enumerate*} +% \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 +% \item[\textbf{3.}] \Doug\ was born in February, 1817. His % earliest memories centered around the cabin of his % grandmother, \Bailey. -% \item[\textbf{1.}] \Doug\ rose to eminence by sheer force +% \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} -% -% \endgroup -% -% \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.\negmedskip^^A -% \index{north star, concept of\noexpand\string|hyperpage}^^A -% \index{civil rights leaders, quotes of\noexpand\string|hyperpage} +% \end{enumerate} % \end{Quote} % +% The goal of this example is to suggest that, if one has a project typeset using \LaTeX, it takes a lot of time and attention to ensure the proper appearance of names. If a unit of text gets moved somewhere else, the knock-on effect could involve re-examining many names to see if their forms are acceptable. Our mission is to automate the editing process to a degree and let names take care of themselves. +% % \newpage % % \subsection{How To Use the Manual} -% \label{sec:ManualUse} +% +% \input{manhook.tmp} % % This manual tries to support various learning styles by using layout, colors, shapes, and similar ordering of both document sections and package code. % % \subsubsection*{\hfil Macro Argument Types} -% \vspace{-4ex} % +% \negbigskip % \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} +% \tcbox{\bfseries Mandatory args in black} % -% \begin{tcolorbox}[colback=white,colframe=nared, -% adjusted title={\bfseries\hfil [Optional Arguments]}] -% \centering This manual shows optional arguments in dark red. -% \end{tcolorbox} +% \tcbox[colback=white]{\color{nared}\bfseries Optional args in dark red} % \end{multicols} % % \subsubsection*{\hfil Scope and Sequence} % -% The table of contents indicates what topics are covered, the simpler and frequent to the complex and infrequent. Later topics require knowledge from multiple sections. The end of each major section includes a return link to the table of contents. +% The table of contents goes from simpler, frequently-used features to more complex, infrequent ones. The end of each major section has a return link to the \hyperlink{TOC}{TOC}. Thus, as the section numbers increase in the lists below, so does the complexity. +% \begin{center} +% \begin{tabular}{ll} +% General concepts: & +% \ref{sec:QuickStart}, \ref{sec:Indexing}, \ref{sec:DataTags}, +% \ref{sec:FormatChoice}, \ref{sec:NameAuthority}\\ +% Multilingual: & +% \ref{sec:Lang}, \ref{sec:AdvancedFormat}\\ +% Details and debugging: & +% \ref{sec:PkgOptions}, \ref{sec:Priorities}, +% \ref{sec:NamePedantic}, \ref{sec:Debugging}, +% \ref{sec:OldStuff}\\ +% \end{tabular} +% \end{center} % % \subsubsection*{\hfil Key Concepts} % -% Starting in Section~\ref{sec:BasicStart}, we use debugging macros to show \emph{name control patterns} in the margins (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 in order to illustrate the things for which one should look when debugging. +% Starting in Section~\ref{sec:BasicStart}, \emph{name patterns} appear in the margin (overview in Section~\ref{sec:NamePatterns}), which are key to how names work in \textsf{nameauth}. Through Section~\ref{sec:RomanScholari} \emph{basic index entries} appear in the margin to show how macro arguments and index entries relate. Thereafter, we use margin notes less due to greater complexity. % -% \subsubsection*{\hfil Special Signs} +% \subsubsection*{\hfil Special Signs and Typography} +% +% \begin{itemize} +% \item[\ \ ]We highlight {\NamesFormat{First Uses}} and {\MainNameHook{Later Uses}} of names (Sections~\ref{sec:Formatting}--\ref{sec:NameControl}). +% \end{itemize} % -% \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{InfoBox} +% \VerbatimInput[gobble=0,numbers=none,fontsize=\small]{manhook.tmp} +% \end{InfoBox} % % \begin{itemize} -% \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[\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\)]The\Warn{} ``dangerous bend'' shows where caution -% is needed. +% +% \item[\dbend]The ``dangerous bend'' shows where extra caution is needed. % \end{itemize} % -% \subsubsection*{\hfil Example Files} +% \begin{Quotation}{\Doug} +% {speech at Rochester, NY, 1852)} +% You profess to believe that ``of one blood God made all nations of men to dwell on the face of the earth''\,---\,and hath commanded all men, everywhere, to love one another\,---\,yet you notoriously hate (and glory in your hatred!) all men whose skins are not colored like your own. +% \index{civil rights leaders, quotes of\noexpand\string|hyperpage} +% \end{Quotation} % -% The files \texttt{examples.tex} and \texttt{compat.tex} are located with this manual. For generating package testing files, see \texttt{README.md}, also located with this manual. +% \newpage % -% \vfill +% \subsubsection*{\hfil General Advice} % -% \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} +% \begin{itemize} +% \item See \texttt{README.md} for details about package development and testing. +% +% \item Both \texttt{compat.tex} and \texttt{examples.tex} contain useful information. They are located with this manual. +% +% \item Do not put naming macros withing a macro defined with \cmd{\edef}. +% +% \item Naming macros can be arguments of a macro defined with \cmd{\edef}. +% +% \item In \texttt{dtx} files, it can be simpler to put the \texttt{nameauth} environment and initial tagging macros in the \texttt{<driver>} part. Yet \cmd{\newif} statements must occur in the ``commented part''. +% \end{itemize} +% +% We summarize some issues related to backward compatibility, which \textsf{nameauth} takes quite seriously as a partner to those who want to preserve their publications. +% \begin{itemize} +% \item Starting with version 4.0, \textsf{nameauth} has used \textsf{xparse} for starred macros and name arguments, which offers many benefits. +% +% \item Users of \TeX\ distribution before 2018 might encounter unexpected or undefined behavior. To mitigate them, see Sections~\ref{sec:FinalOptargs}, \ref{sec:Unicode}f., \ref{sec:CompatON}, and~\ref{sec:FullCustomize}. See also \texttt{compat.tex}. +% +% \item Older customizations using \textsf{xargs} may still work with the \texttt{oldargs} option. See Section~\ref{sec:OptionCompat} and \texttt{examples.tex}. It includes additional code snippets that deal with compatibility. If one should require \textsf{nameauth} version 3.7, see section 7 of \texttt{README.md}. +% \item To use older \TeX\ distributions (2018 and before), one must include the \textsf{textcomp} package for backward compatibility. +% +% \item If users need to preserve older \TeX\ distributions in order to maintain publications for reprint, they are encouraged to view and modify \texttt{compat.tex}, then \cmd{\input} it into the preambles of their projects. +% \end{itemize} +% +% \begin{Quotation}{\Name{Aristotle}} +% {\Title{Politics} (post-338 \textsc{bc})} +% Man is by nature a social animal; an individual who is unsocial +% naturally and not accidentally is either beneath our notice or more +% than human. Society is something that precedes the individual. Anyone +% who either cannot lead the common life or is so self-sufficient as not +% to need to, and therefore does not partake of society, is either a +% beast or a god. +% \index{philosophers, quotes of\noexpand\string|hyperpage} +% \end{Quotation} % % \newpage % % \subsection{Basic Concepts} % -% This section introduces fundamental concepts needed by package users. -% The rest of the manual requires these to be understood. +% \subsubsection{Name Ambiguity} +% +% \subsubsection*{\hfil Culture resolves ambiguity.} +% +% Western culture often includes forenames followed by a surname and an optional affix. Exceptions can include patronyms like \Name[Leif]{Erikson} and \Name{Llywelyn, ap Gruffudd}, as well as ancient and royal names.\footnote{Indexed here under \Name[Leif]{Erikson} and \Name{Llywelyn, ap Gruffudd}. See \href{https://www.theindexer.org/wp-content/uploads/2020/07/welsh-personal-names.pdf} {\bfseries this document} on Welsh names.} +% Due to the conventions taught to them, Western readers might misinterpret the following names: +% +% \begin{Block} +% \begin{tabular}{llll} +% Forenames: & +% \ForceName\SubvertThis\FName[M.T.]{Cicero}[Marcus Tullius] & +% Surname: & +% \ForceName\Name[M.T.]{Cicero}\\[0.5ex] +% +% Forename: & +% \ForceName\SubvertThis\Name{Pontius, Pilate} & +% Surname: & +% \ForceName\ForceFN\FName{Pontius, Pilate}\\[0.5ex] +% +% Forename: & +% \ForceName\SubvertThis\Name{Jesus, Christ} & +% Surname: & +% \ForceName\ForceFN\FName{Jesus, Christ} +% \end{tabular} +% \end{Block} +% +% Yet these names have meanings that cannot be known \emph{as signs in themselves} apart from their native cultural setting. That reveals the following information: +% +% \begin{Block} +% \begin{tabular}{cllll} +% \LA{Praenomen}: +% \SubvertThis\FName[M.T.]{Cicero}[Marcus] & +% \LA{Nomen}: & +% +% \SubvertThis\FName[M.T.]{Cicero}[Tullius] & +% \LA{Cognomen}: & +% \Name[M.T.]{Cicero}\\[0.5ex] +% +% \meta{empty} & +% \LA{Nomen}: & +% \SubvertThis\Name{Pontius, Pilate} & +% \LA{Cognomen}: & +% \ForceFN\FName{Pontius, Pilate}[Pilatus]\\[0.5ex] +% +% \hfil \meta{empty} & +% Name: & +% \SubvertThis\Name{Jesus, Christ} & +% Sobriquet: & +% \ForceFN\FName{Jesus, Christ} +% \end{tabular} +% \end{Block} +% +% Roman names have a forename, a clan name, and one or more names that can denote branch families, nicknames, etc. Forenames (\LA{praenomina}) do not carry great weight; the clan name (\LA{nomen}) is of most importance. The clan name of \Name[M.T.]{Cicero} actually is \FName[M.T.]{Cicero}[Tullius]. In English, he used to be known as \IndexRef{Tully}{Cicero, M.T.}\Name{Tully}. \Name*{Pontius, Pilate} has no forename. \Name{Pontius, Pilate} is a clan name. The ``nickname'' (\LA{cognomen}) \ForceFN\FName{Pontius, Pilate}[Pilatus] refers to skill with the \LA{pilum}, a barbed spear. The name \Name*{Jesus, Christ} comes from \el{Ἰησοῦς ὁ\nbsp Χριστός}, from Hebrew \textit{Y'shua ha-Mashiach}, ``Joshua the Anointed One''. +% +% \subsubsection*{\hfil \textbf{We embrace ambiguity.}} +% +% \IndexRef{Pilate}{Pontius Pilate} +% The market determines usage, whether general or scholarly (Section~\ref{sec:Romani}).\footnote{For an example of a resource that tries to span both the popular and the scholarly, see John Bartlett, \Title{Bartlett's Familiar Quotations}, 16\textsuperscript{th} ed., ed. Justin Kaplan (Boston: Little, Brown, 1991).} +% Here we represent \Name[M.T.]{Cicero} as a Western name and both \ForceFN\FName{Pontius, Pilate} and \ForceFN\FName{Jesus, Christ} as Non-Western names. \Name[M.T.]{Cicero} is indexed by his \LA{cognomen}; \ForceFN\FName{Pontius, Pilate} by his \LA{nomen}.\footnote{\cmd{\IndexRef\{Pilate\}\{Pontius Pilate\}} makes ``Pilate \dots\ \textit{see} Pontius Pilate'', a cross-reference that guides Western readers from the expected index entry to the entry used here (Section~\ref{sec:IndexRef}).} +% \begin{itemize} +% \item Western Index Entry:\smallskip +% +% \begingroup\small +% \begin{tabular}{p{2.2cm}p{4.2cm}p{2.5cm}}\toprule +% \rowcolor{nagrey}\bfseries Text & +% \bfseries Macro / Arguments & \bfseries Index\\ +% \Name*[M.T.]{Cicero} & \cmd{\Name[M.T.]\{Cicero\}} & +% \ShowIdxPageref*{}\\\bottomrule +% \end{tabular} +% \endgroup\medskip +% +% \item Non-Western Index Entries:\smallskip +% +% \begingroup\small +% \begin{tabular}{p{2.2cm}p{4.2cm}p{2.5cm}}\toprule +% \rowcolor{nagrey}\bfseries Text & +% \bfseries Macro / Arguments & \bfseries Index\\ +% \Name*{Pontius, Pilate} & +% \cmd{\Name\{Pontius, Pilate\}} & +% \ShowIdxPageref*{}\\ +% \rowcolor{nagrey}\Name*{Jesus, Christ} & +% \cmd{\Name\{Jesus, Christ\}} & +% \ShowIdxPageref*{}\\\bottomrule +% \end{tabular} +% \endgroup +% \end{itemize} +% +% \newpage +% +% Name forms in the text can be changed independently of their index entries. This is necessary for cases like Hungarian names, Roman names, or when a publisher wants to use Western index entry forms with Eastern names. +% +% For example, the Hungarian name \RevName\Name[Frenec]{Liszt}\dag\ has the index entry ``\ShowIdxPageref*{}''. We used the macro arguments for Western names to get the correct index entry, but we reversed the name in the text via |\RevName\Name[Frenec]{Liszt}|. \IndexRef[Franz]{Liszt}{Liszt, Frenec}\Name[Franz]{Liszt} is his equivalent German name, cross-referenced to the Hungarian form. +% +% \subsubsection*{\hfil \textbf{Name arguments determine index entries.}} +% +% The way that one encodes names using macro arguments primarily determines the form of the index entry\,—\,not the mutable form in the text. This is the key reason to use \textsf{nameauth} over manual methods. We do not index the names below, but we show how the index entries would appear: +% \IndexInactive +% \begin{itemize} +% \item Western Index Entries:\smallskip +% +% \begingroup\small +% \begin{tabular}{p{2.2cm}p{5.6cm}p{2.7cm}}\toprule +% \rowcolor{nagrey}\bfseries Text & +% \bfseries Macro / Arguments & \bfseries Index\\ +% \Name[First]{Last, Affix} & |\Name[First]{Last, Affix}| & +% \ShowIdxPageref*[First]{Last, Affix}\\ +% \Name[First]{Last, Affix} & |\Name[First]{Last, Affix}| & +% \ShowIdxPageref*[First]{Last, Affix}\\ +% \Name[First]{Last} & |\Name[First]{Last}| & +% \ShowIdxPageref*[First]{Last}\\ +% \Name[First]{Last} & |\Name[First]{Last}| & +% \ShowIdxPageref*[First]{Last}\\ +% \RevName\Name*[First]{Last} & |\RevName\Name*[First]{Last}| & +% \ShowIdxPageref*[First]{Last}\\\bottomrule +% \end{tabular} +% \endgroup\medskip +% +% \item Non-Western Index Entries:\smallskip +% +% \begingroup\small +% \begin{tabular}{p{2.2cm}p{5.6cm}p{2.7cm}}\toprule +% \rowcolor{nagrey}\bfseries Text & +% \bfseries Macro / Arguments & \bfseries Index\\ +% \Name{Family, Person} & |\Name{Family, Person}| & +% \ShowIdxPageref*{Family, Person}\\ +% \Name{Family, Person} & |\Name{Family, Person}| & +% \ShowIdxPageref*{Family, Person}\\ +% \RevName\Name*{Family, Person} & +% |\RevName\Name*{Family, Person}| & +% \ShowIdxPageref*{Family, Person}\\ +% \Name{Person, Affix} & |\Name{Person, Affix}| & +% \ShowIdxPageref*{Person, Affix}\\ +% \Name{Person, Affix} & |\Name{Person, Affix}| & +% \ShowIdxPageref*{Person, Affix}\\ +% \Name{Person} & |\Name{Person}| & +% \ShowIdxPageref*{Person}\\\bottomrule +% \end{tabular} +% \endgroup +% \end{itemize} +% \IndexActive +% +% \subsubsection*{\hfil \textbf{Name complexity creates \textsf{nameauth} complexity.}} +% +% We might take names for granted until we have to consider them, use them in multicultural contexts, index them, and so on. Even if one does not use the \textsf{nameauth} package, one cannot escape this complexity. +% +% The process of making \textsf{nameauth} became the means by which the present author learned about both the many intricate and fascinating complexities of names and the complexities of \LaTeX. One hopes that this package might facilitate accurate and respectful cross-cultural use of names in quality publications. +% +% \begin{Quotation}{\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. +% \index{scientists, quotes of\noexpand\string|hyperpage} +% \end{Quotation} +% +% \newpage % % \subsubsection{Name Arguments} % \label{sec:NameArgs} % -% Below we show how familiar categories of names map to name arguments in the appropriate macros, as defined by the current syntax. We use the excellent advice in [\hyperlink{Mulvany}{Mulvany}, 152--82] and [\hyperlink{Chicago}{Chicago}], adapting them for use in \LaTeX. -% \medskip -% % \begingroup\small % \setbox0\hbox{Family / clan name\ } % \global\setlength{\nameboxi}{\wd0} @@ -1647,9 +1906,21 @@ and version 1.3 or later is part of all distributions of LaTeX version % \global\setlength{\nameboxiii}{\wd0} % \endgroup % -% \noindent\begin{tcolorbox}[colframe=naslate, -% adjusted title={\large Western Name: -% \oarg{FNN}\marg{SNN, Affix}\oarg{Alternate}}] +% We describe the general form of names according to the current \textsf{nameauth} syntax.\footnote{Adopted from [\hyperlink{Mulvany}{Mulvany}, 152--82] and [\hyperlink{Chicago}{Chicago}].} +% Mandatory and optional \emph{macro arguments} aid a natural-language approach. They are subordinate to \emph{required and optional name elements}, shown by black and red text. Issues with final optional arguments are covered in Section~\ref{sec:FinalOptargs}. +% +% \newcommand*\WestSyntax{Western Names: \cmd{\Name}\oarg{FNN}^^A +% \marg{SNN{\color{nared}\textbf{,}Affix}}^^A +% \oarg{{\color{nared}Alternate}}} +% \newcommand*\EastSyntax{``Native'' Eastern Names: +% \cmd{\Name}\marg{SNN\textbf{,}Affix}^^A +% \oarg{{\color{nared}Alternate}}} +% \newcommand*\AncientSyntax{Ancient / Royal Names: +% \cmd{\Name}\marg{SNN{\color{nared}\textbf{,}Affix}}^^A +% \oarg{{\color{nared}Alternate}}} +% +% \subsubsection*{\hfil \protect\WestSyntax} +% \begin{tcolorbox}[colframe=gray] % \centering\small^^A %^^A % \tcbox[equal height group=A,on line,tikznode,colback=white, @@ -1658,66 +1929,75 @@ and version 1.3 or later is part of all distributions of LaTeX version % \textit{baptismal name}\\ % \textit{Christian name}\\ % \textit{multiple names}\\ -% \textit{praenomen}\footnotemark}\hfill^^A +% (\LA{prae})\LA{nomen}\footnotemark}\hfill^^A %^^A % \tcbox[equal height group=A,on line,tikznode,colback=white, -% adjusted title={\bfseries\sffamily Surname(s):\meta{SNN}}] +% adjusted title={\centering\bfseries\sffamily +% Surname(s):\meta{SNN}}] % {\hbox to \nameboxii {\hfil Family name:\hfil}\\ % \textit{of father, mother}\\ % \textit{ancestor, vocation}\\ % \textit{origin, region}\\ -% \textit{nomen\,/\,cognomen}\\ +% \LA{nomen\,/\,cognomen}\\ % \textit{patronym}}\hfill^^A %^^A % \tcbox[equal height group=A,on line,tikznode,colback=white,colframe=nared, -% adjusted title={\bfseries\sffamily Qualifier:\meta{Affix}}] +% adjusted title={\centering\bfseries\sffamily +% Qualifier:\meta{Affix}}] % {\hbox to \nameboxiii {\hfil Sobriquet\,/\,title:\hfil}\\ % \textit{Sr., Jr., III\dots}\\ % \textit{notable attribute}\\ -% \textit{origin, region}} +% \textit{origin, region}\\ +% \LA{agnomen}} % % \begin{tcolorbox}[colback=white,colframe=nared, -% adjusted title={\bfseries\sffamily Alias:\meta{Alternate}}] -% \centering Replaces \meta{FNN} only in the text. +% adjusted title={\centering\bfseries\sffamily +% Alias:\meta{Alternate}}] +% \centering Replaces \meta{FNN} only in the text, not in the index. % \end{tcolorbox} % % \end{tcolorbox} -% \footnotetext{There are several ways of handling the Roman \textit{tria +% \footnotetext{There are several ways of handling the Roman \LA{tria % nomina}. See Section~\ref{sec:Romani}.} % -% \begin{tcolorbox}[colframe=naslate, -% adjusted title={\large ``Native'' Eastern Name}: -% \marg{SNN, Affix}\oarg{Alternate}] +% \subsubsection*{\hfil \protect\EastSyntax} +% +% \begin{tcolorbox}[colframe=gray] % \centering\small^^A %^^A % \tcbox[equal height group=B,on line,tikznode,colback=white, -% adjusted title={\bfseries\sffamily Family:\meta{SNN}}] +% adjusted title={\centering\bfseries\sffamily +% Family:\meta{SNN}}] % {\hbox to \nameboxi {\hfil Family\,/\,clan name\hfil}}\hfill^^A %^^A % \tcbox[equal height group=B,on line,tikznode,colback=white, -% adjusted title={\bfseries\sffamily Personal:\meta{Affix}}] +% adjusted title={\centering\bfseries\sffamily +% Personal:\meta{Affix}}] % {\hbox to \nameboxii {\hfil Usually one name\hfil}}\hfill^^A %^^A % \tcbox[equal height group=B,on line,tikznode,colback=white,colframe=nared, -% adjusted title={\bfseries\sffamily Alias:\meta{Alternate}}] +% adjusted title={\centering\bfseries\sffamily +% Alias:\meta{Alternate}}] % {\hbox to \nameboxiii {\hfil Replaces \meta{Affix}\hfil}\\ % only in text.\footnotemark} % \end{tcolorbox} % \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={\large Royal/Medieval/Ancient Name}: -% \marg{SNN, Affix}\oarg{Alternate}] +% \subsubsection*{\hfil \protect\AncientSyntax} +% +% \begin{tcolorbox}[colframe=gray] % \centering\small^^A %^^A % \tcbox[equal height group=C,on line,tikznode,colback=white, -% adjusted title={\bfseries\sffamily Personal:\meta{SNN}}] +% adjusted title={\centering\bfseries\sffamily +% Personal:\meta{SNN}}] % {\hbox to \nameboxi {\hfil Given name(s)\hfil}\\ % \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}}] +% adjusted title={\centering\bfseries\sffamily +% Qualifier:\meta{Affix}}] % {\hbox to \nameboxii {\hfil Sobriquet\,/\,title:\hfil}\\ % \textit{Sr., Jr., III\dots}\\ % \textit{notable attribute}\\ @@ -1725,7 +2005,8 @@ and version 1.3 or later is part of all distributions of LaTeX version % \textit{patronym}}\hfill^^A %^^A % \tcbox[equal height group=C,on line,tikznode,colback=white,colframe=nared, -% adjusted title={\bfseries\sffamily Alias:\meta{Alternate}}] +% adjusted title={\centering\bfseries\sffamily +% Alias:\meta{Alternate}}] % {\hbox to \nameboxiii {\hfil Replaces \meta{Affix}\hfil}\\ % only in text.\footnotemark} % \end{tcolorbox} @@ -1734,150 +2015,21 @@ and version 1.3 or later is part of all distributions of LaTeX version % % \newpage % -% \subsubsection{Name Ambiguity} -% -% \begin{itemize} -% \item \textbf{Name forms are ambiguous.} -% -% In Western culture, one often sees forenames followed by a surname. Patronyms, as in \Name[Leif]{Erikson} and \Name{Llywelyn, ap Gruffudd}, and other exceptions exist.\footnote{Indexed here under \Name[Leif]{Erikson} and \Name{Llywelyn, ap Gruffudd}. See also \href{https://www.theindexer.org/wp-content/uploads/2020/07/welsh-personal-names.pdf} {\bfseries this document} on indexing Welsh names.} -% Some readers might assume the following: -% -% \begin{center} -% \renewcommand\NamesFormat{\color{blue}\sffamily} -% \renewcommand\MainNameHook{\color{blue}\sffamily} -% \begin{tabular}{lll}\toprule -% \rowcolor{nagrey}\bfseries Forename & \bfseries Forename & \bfseries Surname\\ -% \SubvertThis\FName[M.T.]{Cicero}[Marcus] & -% \FName[M.T.]{Cicero}[Tullius] & -% \Name[M.T.]{Cicero}\\\midrule -% \rowcolor{nagrey}\bfseries Forename & & \bfseries Surname\\ -% \SubvertThis\Name{Pontius, Pilate} & & -% \ForceFN\FName{Pontius, Pilate}\\ -% \SubvertThis\Name{Jesus, Christ} & & -% \ForceFN\FName{Jesus, Christ}\\\bottomrule -% \end{tabular} -% \end{center} -% -% Even though all these initial assumptions are false, Western naming conventions tend to dominate the general readership market and, \textit{mutatis mutandis}, they affect the use and indexing of names. -% -% \item \textbf{Cultural context resolves ambiguity.} -% -% Here we see how the names above have meaning in their proper context. The words themselves \textit{as signs} do not offer the as many clues about their meaning until the signs become part of a cultural landscape. -% -% \begin{center} -% \renewcommand\NamesFormat{\sffamily} -% \renewcommand\MainNameHook{\sffamily} -% \begin{tabular}{lll}\toprule -% \rowcolor{nagrey}\bfseries Personal Name & -% \bfseries Clan Name & \bfseries Branch Family or Nickname\\ -% \SubvertThis\FName[M.T.]{Cicero}[Marcus] & -% \FName[M.T.]{Cicero}[Tullius] & -% \Name[M.T.]{Cicero}\\ -% & \SubvertThis\Name{Pontius, Pilate} & -% \ForceFN\FName{Pontius, Pilate}\\\midrule -% \rowcolor{nagrey}\bfseries Personal Name & & \bfseries Sobriquet\\ -% \SubvertThis\Name{Jesus, Christ} & & -% \ForceFN\FName{Jesus, Christ}\\\bottomrule -% \end{tabular} -% \end{center} -% -% \item \textbf{This package embraces such ambiguities.} -% -% Roman \textit{praenomina} did not have the same significance as Western forenames.\footnote{See \href{https://en.wikipedia.org/wiki/Praenomen}{Wikipedia}. Roman names in particular are sensitive to the historical and political development of Rome and its empire, the history of Roman families and culture, as well as other factors.} -% Yet the family name (\textit{nomen}) of the man we call \Name[M.T.]{Cicero} is \FName[M.T.]{Cicero}[Tullius]. In English, he used to be known as \IndexRef{Tully}{Cicero, M.T.}\Name{Tully}. In this manual we choose the popular case for the \textit{cognomen} \Name[M.T.]{Cicero} as a Western surname. Scholarly publications can take at least two different approaches (see Section~\ref{sec:Romani}). -% -% The name \Name*{Pontius, Pilate} has no personal name, which fits with Roman naming trends. \Name{Pontius, Pilate} is a clan name. Most texts and inscriptions favor the \textit{cognomen} \ForceFN\FName{Pontius, Pilate}[Pilatus], denoting martial prowess. -% -% \Name*{Jesus, Christ} is a name derived from Greek \el{Ἰησοῦς Χριστός}, from \textit{Y'shua ha-Mashiach}, Joshua the Anointed One. The personal name is \Name{Jesus, Christ}. Other added names are titles or descriptors. -% -% \item \textbf{Macros can modify names in the text to fit cultural norms.} -% -% Name forms in the text are independent of their index entries. This is necessary for special cases like Hungarian names. Thus, a text oriented to Hungarian readers can talk about \RevName\Name[Frenec]{Liszt}\dag\ (\IndexRef[Franz]{Liszt}{Liszt, Frenec}\Name[Franz]{Liszt}) in the body text, but he can be indexed as \ShowIdxPageref*[Frenec]{Liszt}. One can do something similar with East Asian names, if Western index entries are required. -% -% \item \textbf{Name arguments determine index entry forms.} -% -% The way that one puts names into macro name arguments absolutely determines the entry form in the index:\medskip -% -% \begingroup\IndexInactive\footnotesize -% \renewcommand\NamesFormat{} -% \renewcommand\MainNameHook{} -% \begin{tabular}{l@{\ }l@{\ }l}\toprule -% \rowcolor{nagrey}\bfseries Printed Name & -% \bfseries Macro and Arguments & \bfseries Western Index Entry\\ -% \Name[Person]{Family, Affix} & |\Name[Person]{Family, Affix}| & -% \ShowIdxPageref*[Person]{Family, Affix}\\ -% \Name[Person]{Family} & |\Name[Person]{Family}| & -% \ShowIdxPageref*[Person]{Family}\\ -% \RevName\Name*[Person]{Family} & |\RevName%| & -% \ShowIdxPageref*[Person]{Family}\\ -% & |\Name[Person]{Family}|\\\midrule -% \rowcolor{nagrey}\bfseries Printed Name & -% \bfseries Macro and Arguments & \bfseries Nonwestern Index Entry\\ -% \Name{Family, Person} & |\Name{Family, Person}| & -% \ShowIdxPageref*{Family, Person}\\ -% \RevName\Name*{Family, Person} & |\RevName%| & -% \ShowIdxPageref*{Family, Person}\\ -% & |\Name{Family, Person}|\\ -% \Name{Person, Affix} & |\Name{Person, Affix}| & -% \ShowIdxPageref*{Person, Affix}\\ -% \Name{Person} & |\Name{Person}| & -% \ShowIdxPageref*{Person}\\\bottomrule -% \end{tabular}\IndexActive -% \endgroup\bigskip -% -% The following choices reflect non-scholarly English-language books. Later sections will show different ways to encode name arguments for scholarly works or non-English books. -% -% \begin{center}\footnotesize -% \renewcommand\NamesFormat{\sffamily} -% \renewcommand\MainNameHook{\sffamily} -% \begin{tabular}{lll}\toprule -% \rowcolor{nagrey}\bfseries Printed Name & -% \bfseries Macro and Arguments & \bfseries Western Index Entry\\ -% \ForgetThis\Name[M.T.]{Cicero} & \cmd{\Name[M.T.]\{Cicero\}} & -% \ShowIdxPageref*[M.T.]{Cicero}\\\midrule -% \rowcolor{nagrey}\bfseries Printed Name & -% \bfseries Macro and Arguments & \bfseries Nonwestern Index Entry\\ -% \ForgetThis\Name{Pontius, Pilate} & \cmd{\Name\{Pontius, Pilate\}} & -% \ShowIdxPageref*{Pontius, Pilate}\\ -% \ForgetThis\Name{Jesus, Christ} & \cmd{\Name\{Jesus, Christ\}} & -% \ShowIdxPageref*{Jesus, Christ}\\\bottomrule -% \end{tabular} -% \end{center} -% -% \item \textbf{Name complexity creates \textsf{nameauth} complexity.} -% -% We might take names for granted until we have to consider them, use them in multicultural contexts, index them, and so on. Even if one does not use the \textsf{nameauth} package, one cannot escape this complexity. -% -% Indeed, it is only through the process of making \textsf{nameauth} that the present author became aware of the many intricate and fascinating complexities of names. The hope is that this package might facilitate accurate and respectful cross-cultural use of names in quality publications. -% \end{itemize} -% -% \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.\negmedskip^^A -% \index{politicians, quotes of\noexpand\string|hyperpage} -% \end{Quote} -% -% \newpage -% % \subsection{Basic Interface} % \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}), making this section critical to using and mastering \textsf{nameauth}. -% +% The description of macro arguments in this section applies to all \textsf{nameauth} macros that take name arguments (Sections~\ref{sec:NameArgs}, \ref{sec:NameArgMacros}, and~\ref{sec:FinalOptargs}), making this section critical to using and mastering \textsf{nameauth}. Here are some general tips: % \begin{itemize} -% \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 If the required argument \meta{SNN} is empty, \textsf{nameauth} issues a package error, even when the \meta{Affix} part of an \meta{SNN}\textbf{,}\meta{Affix} pair is not empty. Macros that take null arguments (Section~\ref{sec:NullArgs}) are the exception. +% % \item Extra spaces around each argument are stripped. -% \item Include name arguments consistently to have consistent -% index entries. -% \item For all name forms, see Section~\ref{sec:FinalOptargs} regarding -% final optional arguments. +% +% \item Include name arguments consistently to have consistent index entries. % \end{itemize} % % \subsubsection{Western Names} % -% \begin{tcolorbox}[colframe=naslate]\centering +% \begin{tcolorbox}[colframe=gray]\centering % \begin{tabular}{l@{ }c@{ }c@{ }c} % & Required & Required \meta{SNN} & Optional\\ % & \meta{FNN} & optional \meta{Affix} & (text only)\\[1ex] @@ -1891,127 +2043,137 @@ and version 1.3 or later is part of all distributions of LaTeX version % {\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}} & +% {\normalsize\bfseries\marg{SNN\color{nared}\textbf{,}Affix}} & % \tcbox[equal height group=D,colback=white,tikznode, % left=1mm,right=1mm,valign=center] % {\normalsize\bfseries\oarg{\color{nared}Alternate}} % \end{tabular} -% \end{tcolorbox}\medskip -% -% \noindent -% Within \textsf{nameauth}, Western names have distinct features: +% \end{tcolorbox} % % \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: +% \item Western names must use the \meta{FNN} argument. +% +% \item They require a comma to delimit any affixes (Section~\ref{sec:Affix}). +% +% \item They use \meta{Alternate} to swap with \meta{FNN} in the text. +% +% \item They have Western name patterns (Section~\ref{sec:NamePatterns}) and index entries: % \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} % % \subsubsection*{\hfil Full, Last, and First Names} % -% \cmd{\Name} prints first uses of names long, then short thereafter. \cmd{\Name*} ensures a long form. Both \cmd{\FName} and \cmd{\FName*} print long names in first uses, then just a forename in later uses.\footnote{The intent is that one can just add an \texttt{F} to either \cmd{\Name} or \cmd{\Name*}.} -% The affix in a surname only appears in long name instances. +% \cmd{\Name} prints first uses of names long, then short thereafter. \cmd{\Name*} ensures a long form. Both \cmd{\FName} and \cmd{\FName*} print long names in first uses, then just a forename in later uses. The intent is that one can just add an \texttt{F} to either \cmd{\Name} or \cmd{\Name*}. The affix in a surname only appears in long name instances. % -% \begin{Block} -% \vspace{3.5ex} -% \BothInfo{\ShowPattern[George]{Washington}\break +% \BothInfo[5ex]{\ShowPattern[George]{Washington}\break % \ShowPattern[George S.]{Patton, Jr.}} % {\ShowIdxPageref*[George]{Washington}\break % \ShowIdxPageref*[George S.]{Patton, Jr.}} -% \vspace{-3.5ex} +% \begin{Block} % \ForgetName[George]{Washington} % \FUse \Name [George]{Washington}\dotfill^^A -% |\Name [George]{Washington}|\break -% \LUse \Name*[George]{Washington}\dotfill^^A -% |\Name*[George]{Washington}|\break +% |\Name [George]{Washington}|\\ +% \UseL \Name*[George]{Washington}\dotfill^^A +% |\Name*[George]{Washington}|\\ % \LUse \Name [George]{Washington}\dotfill^^A -% |\Name [George]{Washington}|\break -% \LUse \FName[George]{Washington}\dotfill^^A +% |\Name [George]{Washington}|\\ +% \UseS \FName[George]{Washington}\dotfill^^A % |\FName[George]{Washington}| % \end{Block} % % \begin{Block} % \FUse \Name [George S.]{Patton, Jr.}\dotfill^^A -% |\Name [George S.]{Patton, Jr.}|\break -% \LUse \Name*[George S.]{Patton, Jr.}\dotfill^^A -% |\Name*[George S.]{Patton, Jr.}|\break +% |\Name [George S.]{Patton, Jr.}|\\ +% \UseL \Name*[George S.]{Patton, Jr.}\dotfill^^A +% |\Name*[George S.]{Patton, Jr.}|\\ % \LUse \Name [George S.]{Patton, Jr.}\dotfill^^A -% |\Name [George S.]{Patton, Jr.}|\break -% \LUse \FName[George S.]{Patton, Jr.}\dotfill^^A +% |\Name [George S.]{Patton, Jr.}|\\ +% \UseS \FName[George S.]{Patton, Jr.}\dotfill^^A % |\FName[George S.]{Patton, Jr.}| % \end{Block} % -% \subsubsection*{\hfil Affixes and Alternate Forms} +% \newpage % -% In a long name instance, \cmd{\DropAffix} drops the affix from a Western surname. The \meta{Alternate} argument appears only in long names or forename-only names in the text. Otherwise, the automatic shortening of names will display only a short surname. +% \subsubsection*{\hfil Affixes and Alternate Forms} % +% Here we use prefix macros to change name forms (Section~\ref{sec:ListPrefix}). In a long name instance, \cmd{\DropAffix} drops the affix from a Western surname. The \meta{Alternate} argument appears only in long names or forename-only names in the text. Otherwise, the automatic shortening of names will display only a short surname. % \begin{itemize} -% \item Drop the affix in a long name instance (forced by \cmd{\Name*}): -% \BothInfo{\ShowPattern[George S.]{Patton, Jr.}\break +% \item Drop the affix in a first- or long use (\cmd{\Name*}): +% \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}} % \begin{Block} -% \FUse \ForgetThis\DropAffix\Name*[George S.]{Patton, Jr.}\\ -% \UseB |\DropAffix\Name*[George S.]{Patton, Jr.}|\\ -% \LUse \DropAffix\Name*[George S.]{Patton, Jr.}\\ +% \FUse \ForgetThis\DropAffix\Name[George S.]{Patton, Jr.}\\ +% \UseB |\DropAffix\Name[George S.]{Patton, Jr.}|\\ +% \UseL \DropAffix\Name*[George S.]{Patton, Jr.}\\ % \UseB |\DropAffix\Name*[George S.]{Patton, Jr.}| % \end{Block} % -% \item Use an alternate forename in a long- or forename instance: +% \item To force the printing of only \meta{Affix} in the subsequent use of a Roman name, see the use of \cmd{\ForceAffix} in Section~\ref{sec:RomanGeneral}. +% +% \item Use an alternate forename in a first- or long use: % \begin{Block} % \FUse \Name[J.D.]{Rockefeller, IV}[John Davison]\\ % \UseB |\Name[J.D.]{Rockefeller, IV}[John Davison]|\\ -% \LUse \FName[George S.]{Patton, Jr.}[George]\\ -% \UseB |\FName[George S.]{Patton, Jr.}[George]| +% \UseL \Name*[J.D.]{Rockefeller, IV}[John Davison]\\ +% \UseB |\Name*[J.D.]{Rockefeller, IV}[John Davison]| +% \end{Block} +% +% \item Use an alternate forename in a forename-only use (\cmd{\FName}): +% \begin{Block} +% \UseS \FName[George S.]{Patton, Jr.}[George]\dotfill^^A +% |\FName[George S.]{Patton, Jr.}[George]|\\ +% \UseS \FName[J.D.]{Rockefeller, IV}[Jay]\dotfill^^A +% |\FName[J.D.]{Rockefeller, IV}[Jay]| % \end{Block} % % \item Drop the affix and alter the forenames: % \begin{Block} -% \FUse \ForgetThis\DropAffix\Name*[J.D.]{Rockefeller, IV}[Jay]\\ -% \UseB |\DropAffix\Name*[J.D.]{Rockefeller, IV}[Jay]|\\ -% \LUse \DropAffix\Name*[J.D.]{Rockefeller, IV}[Jay]\\ +% \FUse \ForgetThis\DropAffix\Name[J.D.]{Rockefeller, IV}[Jay]\\ +% \UseB |\DropAffix\Name[J.D.]{Rockefeller, IV}[Jay]|\\ +% \UseL \DropAffix\Name*[J.D.]{Rockefeller, IV}[Jay]\\ % \UseB |\DropAffix\Name*[J.D.]{Rockefeller, IV}[Jay]| % \end{Block} % % \item Use multiple alternate forenames for the same person: % \begin{Block} -% \FUse \Name [Clive Staples]{Lewis}\\ -% \UseB |\Name [Clive Staples]{Lewis}|\\ -% \LUse \Name*[Clive Staples]{Lewis}[C.S.]\\ -% \UseB |\Name*[Clive Staples]{Lewis}[C.S.]|\\ -% \LUse \FName[Clive Staples]{Lewis}[Jack]\\ -% \UseB |\FName[Clive Staples]{Lewis}[Jack]| +% \FUse \Name [Clive Staples]{Lewis}\dotfill^^A +% |\Name [Clive Staples]{Lewis}|\\ +% \UseL \Name*[Clive Staples]{Lewis}[C.S.]\dotfill^^A +% |\Name*[Clive Staples]{Lewis}[C.S.]|\\ +% \UseS \FName[Clive Staples]{Lewis}[Jack]\dotfill^^A +% |\FName[Clive Staples]{Lewis}[Jack]| % \end{Block} % \end{itemize} +% \smallskip % % \begin{InfoBox} -% 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}. For example: +% All names should be sorted in the index by their longest unique forms. Convert Roman numerals to Arabic in order to avoid sorting the numbers alphabetically. See Sections~\ref{sec:IndexSort}, \ref{sec:IndexInitials}, and~\ref{sec:VarNames}.\smallskip % -% \begin{center} +% \begin{Center} % |\PretagName[J.D.]{Rockefeller, IV}{Rockefeller, John D 4}| -% \end{center} +% \end{Center} % \end{InfoBox} % -% \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.^^A -% \index{politicians, quotes of\noexpand\string|hyperpage} -% \end{Quote} +% \begin{Quotation}{\Name[W.H.]{Auden}} +% {\Title{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. +% \index{creatives, quotes of\noexpand\string|hyperpage} +% \end{Quotation} % % \newpage % % \subsubsection[Reversed Western]{Reversed Western Names} % -% \begin{tcolorbox}[colframe=naslate]\centering +% \begin{tcolorbox}[colframe=gray]\centering % \begin{tabular}{l@{ }c@{ }c@{ }c} % & Required & Required \meta{SNN} & Optional\\ % & \meta{FNN} & no \meta{Affix} & (text only)\\[1ex] @@ -2030,58 +2192,64 @@ and version 1.3 or later is part of all distributions of LaTeX version % left=1mm,right=1mm,valign=center] % {\normalsize\bfseries\oarg{\color{nared}Alternate}} % \end{tabular} -% \end{tcolorbox}\medskip +% \end{tcolorbox} % -% \noindent -% Reversed Western names (Section~\ref{sec:RevNames}) have these features: +% \begin{itemize} +% \item Names must use the \meta{FNN} argument. They do not use \meta{Affix}.\footnote{This prevents strange name forms. Using \cmd{\DropAffix} (Section~\ref{sec:Affix}) will not help.} +% +% \item They use \meta{Alternate} to swap with \meta{FNN} in the text. % +% \item They have Western name patterns and index entries: % \begin{itemize} -% \item They must use the first optional \meta{FNN} argument. -% \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}). +% \item[] \meta{SNN}, \meta{FNN} +% \end{itemize} +% +% \item They do not work with the obsolete syntax (Section~\ref{sec:Obsolete}). % \end{itemize} % % \subsubsection*{\hfil Starting with Western Name Forms} % -% 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\}}.} +% Reversed Western forms (as with Hungarian and other names) start out as Western names before we put them into reverse order. They retain Western index entries [\hyperlink{Mulvany}{Mulvany}, 166]. Without being reversed, they look like:\footnote{Regarding the margin note that shows name patterns, with \texttt{pdflatex} and \texttt{latex} using \textsf{inputenc} and \textsf{fontenc}, in \texttt{\ShowPattern[Frenec]{Molnár}} the glyphs \texttt{Ãą} correspond to \cmd{\IeC\{\textbackslash\textquotesingle a\}}.} % -% \begin{Block} -% \BothInfo{\ShowPattern[Frenec]{Molnár}\break +% \BothInfo[5ex]{\ShowPattern[Frenec]{Molnár}\break % \ShowPattern[Hideyo]{Noguchi}} % {\ShowIdxPageref*[Hideyo]{Noguchi}\break % \ShowIdxPageref*[Frenec]{Molnár}} -% \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]| +% \begin{Block} +% \FUse \Name[Frenec]{Molnár}\dotfill^^A +% |\Name[Frenec]{Molnár}|\\ +% \LUse \Name[Frenec]{Molnár}\dotfill^^A +% |\Name[Frenec]{Molnár}|\\ +% \FUse \Name[Hideyo]{Noguchi}\dotfill^^A +% |\Name[Hideyo]{Noguchi}|\\ +% \LUse \Name[Hideyo]{Noguchi}\dotfill^^A +% |\Name[Hideyo]{Noguchi}|\\ +% \UseL \Name*[Hideyo]{Noguchi}[Doctor]\dotfill^^A +% |\Name*[Hideyo]{Noguchi}[Doctor]| % \end{Block} % -% \subsubsection*{\hfil Using the Reversing Macros} +% \subsubsection*{\hfil Using the Reversing and Other Macros} % -% \noindent We use the prefix macros \cmd{\RevName} and optionally \cmd{\CapName} (Section~\ref{sec:SelectOver}) to print either a Hungarian or ``non-native'' Eastern name in the text while keeping Western forms in the index: +% We use \cmd{\RevName} and optionally \cmd{\CapName} (Section~\ref{sec:AllCaps}) to print reversed names in the text without changing the Western forms of their index entries. They function well in context, not arbitrarily: % % \begin{Block} -% \LUse\Same \RevName\Name*[Frenec]{Molnár}\dag\\ -% \UseB |\RevName\Name*[Frenec]{Molnár}\dag|\\ -% \LUse \RevName\Name [Frenec]{Molnár}\dag\\ -% \UseB |\RevName\Name [Frenec]{Molnár}\dag|\\ -% \LUse \CapName\RevName\Name*[Hideyo]{Noguchi}[Sensei]\dag\\ -% \UseB |\CapName\RevName\Name*[Hideyo]{Noguchi}[Sensei]\dag|\\ -% \LUse \CapName\RevName\Name [Hideyo]{Noguchi}[Sensei]\dag\\ -% \UseB |\CapName\RevName\Name [Hideyo]{Noguchi}[Sensei]\dag| +% \FUse \ForgetThis\RevName\Name[Frenec]{Molnár}\dag\\ +% \UseB |\RevName\Name[Frenec]{Molnár}\dag|\\ +% \LUse \RevName\Name[Frenec]{Molnár}\dag\\ +% \UseB |\RevName\Name[Frenec]{Molnár}\dag|\\ +% \FUse \ForgetThis\CapName\RevName\Name[Hideyo]{Noguchi}[Sensei]\dag\\ +% \UseB |\CapName\RevName\Name[Hideyo]{Noguchi}[Sensei]\dag|\\ +% \LUse \CapName\RevName\Name[Hideyo]{Noguchi}[Sensei]\dag\\ +% \UseB |\CapName\RevName\Name[Hideyo]{Noguchi}[Sensei]\dag|\\ +% \UseL \CapName\RevName\Name*[Hideyo]{Noguchi}[Sensei]\dag\\ +% \UseB |\CapName\RevName\Name*[Hideyo]{Noguchi}[Sensei]\dag| % \end{Block} % -% These macros, as is the case with many \textsf{nameauth} macros, work properly in context, not arbitrarily. \emph{They always have Western index entries,} regardless of how they appear in the text. -% -% \subsubsection{Eastern Names} +% \newpage % -% All nonwestern 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 +% \subsubsection[Eastern Names]{``Native'' Eastern Names} % -% \begin{tcolorbox}[colframe=naslate]\centering +% \begin{tcolorbox}[colframe=gray]\centering % \begin{tabular}{l@{ }c@{ }c} % & Required \meta{SNN} & Optional\\ % & required \meta{Affix} & (text only)\\[1ex] @@ -2092,61 +2260,64 @@ and version 1.3 or later is part of all distributions of LaTeX version % \cmd{\FName}} & % \tcbox[equal height group=D,colback=white,tikznode, % left=1mm,right=1mm,valign=center] -% {\normalsize\bfseries\marg{SNN, Affix}} & +% {\normalsize\bfseries\marg{SNN\textbf{,}Affix}} & % \tcbox[equal height group=D,colback=white,tikznode, % left=1mm,right=1mm,valign=center] % {\normalsize\bfseries\oarg{\color{nared}Alternate}} % \end{tabular} -% \end{tcolorbox}\medskip -% -% \noindent -% These features denote ``native'' Eastern names in \textsf{nameauth} (Sections~\ref{sec:Eastern}, \ref{sec:RevNames}): +% \end{tcolorbox} % % \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 nonwestern form: \meta{SNN Affix}. -% \item Names with the form \meta{SNN, Affix} can use the \meta{Alternate} -% argument to swap \meta{Affix} with \meta{Alternate}. -% \item They have nonwestern name patterns and index entry forms. +% +% \item They use instead the \meta{SNN\textbf{,}Affix} arguments. +% +% \item They can swap \meta{Alternate} and \meta{Affix} in the text.\footnote{We discourage the obsolete syntax (Section~\ref{sec:Obsolete}) because \meta{Alternate} does not work with it.} +% +% \item They have Non-Western name patterns and index entries: +% \begin{itemize} +% \item[] \meta{SNN} \meta{Affix} +% \end{itemize} +% +% \item If name order is reversed in the text with \cmd{\RevName}, these names retain Non-Western index entries. % \end{itemize} % -% \subsubsection*{\hfil ``Native'', Reversible Eastern Name Forms} +% \subsubsection*{\hfil Starting with 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}} +% \BothInfo[5ex]{\ShowPattern{Miyazaki, Hayao}} % {\ShowIdxPageref*{Miyazaki, Hayao}} -% \vspace{-3.5ex} -% \ForgetName {Miyazaki, Hayao} -% \FUse \Name {Miyazaki, Hayao}\dotfill |\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}| +% \begin{Block} +% \ForgetName{Miyazaki, Hayao} +% \FUse \Name{Miyazaki, Hayao}\dotfill |\Name{Miyazaki, Hayao}|\\ +% \LUse \Name{Miyazaki, Hayao}\dotfill |\Name{Miyazaki, Hayao}|\\ +% \UseL \Name*{Miyazaki, Hayao}[Sensei]\dotfill |\Name*{Miyazaki, Hayao}[Sensei]|\\ +% \UseS \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}): +% \subsubsection*{\hfil Using the Reversing and Other Macros} +% +% The reversing macros produce a Western name ordering in the text. One must use \cmd{\ForceFN} with \cmd{\FName} (Section~\ref{sec:FName}) to print just a personal name: % % \begin{Block} -% \LUse\Same \ForceFN\FName{Miyazaki, Hayao}\dotfill^^A -% |\ForceFN\FName{Miyazaki, Hayao}|\\ -% \LUse \CapName\Name*{Miyazaki, Hayao}[Sensei]\dotfill^^A -% |\CapName\Name*{Miyazaki, Hayao}[Sensei]|\\ -% \LUse \ForceFN\FName{Miyazaki, Hayao}[Sensei]\dotfill^^A -% |\ForceFN\FName{Miyazaki, Hayao}[Sensei]|\\ -% \LUse \RevName\Name*{Miyazaki, Hayao}[Mr.]\dotfill^^A -% |\RevName\Name*{Miyazaki, Hayao}[Mr.]| +% \FUse \ForgetThis\RevName\Name{Miyazaki, Hayao}\\ +% \UseB |\RevName\Name{Miyazaki, Hayao}|\\ +% \UseS \ForceFN\FName{Miyazaki, Hayao}\\ +% \UseB |\ForceFN\FName{Miyazaki, Hayao}|\\ +% \UseL \RevName\Name*{Miyazaki, Hayao}[Mr.]\\ +% \UseB |\RevName\Name*{Miyazaki, Hayao}[Mr.]|\\ +% \UseL \CapName\Name*{Miyazaki, Hayao}[Sensei]\\ +% \UseB |\CapName\Name*{Miyazaki, Hayao}[Sensei]|\\ +% \UseS \ForceFN\FName{Miyazaki, Hayao}[Sensei]\\ +% \UseB |\ForceFN\FName{Miyazaki, Hayao}[Sensei]| % \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.} -% % \newpage % -% \subsubsection[Ancient Names]{Royal, Medieval, and Ancient Names} +% \subsubsection[Ancient Names]{Royal or Ancient Names} % -% \begin{tcolorbox}[colframe=naslate]\centering +% \begin{tcolorbox}[colframe=gray]\centering % \begin{tabular}{l@{ }c@{ }c} % & Required \meta{SNN} & Optional,\\ % & optional \meta{Affix} & special\\[1ex] @@ -2157,76 +2328,157 @@ and version 1.3 or later is part of all distributions of LaTeX version % \cmd{\FName}} & % \tcbox[equal height group=D,colback=white,tikznode, % left=1mm,right=1mm,valign=center] -% {\normalsize\bfseries\marg{SNN\color{nared}, Affix}} & +% {\normalsize\bfseries\marg{SNN\color{nared}\textbf{,}Affix}} & % \tcbox[equal height group=D,colback=white,tikznode, % left=1mm,right=1mm,valign=center] % {\normalsize\bfseries\oarg{\color{nared}Alternate}} % \end{tabular} -% \end{tcolorbox}\medskip -% -% \noindent -% These features denote royal, medieval, and ancient names in \textsf{nameauth}, grouped under the general rubric of ``nonwestern'' name forms: +% \end{tcolorbox} % % \begin{itemize} % \item They must \emph{leave empty} the \meta{FNN} argument. -% \item They use either the \meta{SNN, Affix} arguments or just \meta{SNN}. -% \item Their index entries take the nonwestern 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 nonwestern name patterns and index entry forms. -% \item One generally does not reverse these names (Section~\ref{sec:RevNames}). +% +% \item They use either the \meta{SNN\textbf{,}Affix} arguments or just \meta{SNN}. +% +% \item Their index entries take Non-Western forms: +% \begin{itemize} +% \item[] \meta{SNN} \meta{Affix} +% \item[] \meta{SNN} +% \end{itemize} +% +% \item Names with \meta{SNN\textbf{,}Affix} can swap \meta{Alternate} and \meta{Affix} in the text. +% +% \item Names with \meta{SNN} should not use \meta{Alternate}.\footnote{That would produce the obsolete syntax (Section~\ref{sec:Obsolete}).} % \end{itemize} % % \subsubsection*{\hfil No School Like the Old School} % % \begin{itemize} -% \item \cmd{\FName} normally prints \meta{SNN} to avoid nonsense names -% in the text. -% \BothInfo{\ShowPattern{Elizabeth, I}\break +% \item \cmd{\FName} normally prints \meta{SNN} to avoid mistakes. +% \BothInfo*{\ShowPattern{Elizabeth, I}\break % \ShowPattern{John, Eriugena}\break % \ShowPattern{Aristotle}} % {\ShowIdxPageref*{Elizabeth, I}\break % \ShowIdxPageref*{John, Eriugena}\break % \ShowIdxPageref*{Aristotle}} % \begin{Block} -% \FUse \Name {Elizabeth, I}\dotfill |\Name {Elizabeth, I}|\\ -% \LUse \Name {Elizabeth, I}\dotfill |\Name {Elizabeth, I}|\\ -% \LUse \FName{Elizabeth, I}\dotfill |\FName{Elizabeth, I}| +% \FUse \ForgetThis\Name{Elizabeth, I}\dotfill |\Name{Elizabeth, I}|\\ +% \LUse \Name{Elizabeth, I}\dotfill |\Name{Elizabeth, I}|\\ +% \UseS \FName{Elizabeth, I}\dotfill |\FName{Elizabeth, I}| % \end{Block} % % \item Here we work with titles and sobriquets: % \begin{Block} % \FUse \ForgetThis\Name{Elizabeth, I}[I ``Gloriana'']\\ -% \UseB |\ForgetThis\Name{Elizabeth, I}[I ``Gloriana'']|\\ -% \LUse \ForceFN\FName{Elizabeth, I}[Gloriana]\\ +% \UseB |\Name{Elizabeth, I}[I ``Gloriana'']|\\ +% \UseS \ForceFN\FName{Elizabeth, I}[Gloriana]\\ % \UseB |\ForceFN\FName{Elizabeth, I}[Gloriana]| % \end{Block} % -% \item Here we show a non-royal: +% \item In long name references, a space always occurs between \meta{SNN} and \meta{Affix} or \meta{SNN} and \meta{Alternate}. When a sobriquet begins with a comma, semicolon, etc., use name tags (Sections~\ref{sec:Complexity} and~\ref{sec:DataTags}): +% \begingroup\begin{itemize} +% \item Avoid forms like the following: +% +% \item[] {\small \Name{Attila, the Hun}[, the Scourge of God]\\ +% |\Name{Attila, the Hun}[, the Scourge of God]|} +% +% \item Use instead something like: +% +% \item[] {\small \NameAddInfo{Attila, the Hun}{, the Scourge of God}^^A +% \ForgetThis\Name{Attila, the Hun}\NameQueryInfo{}\\ +% \Name{Attila, the Hun}\NameQueryInfo{}\\ +% |\NameAddInfo{Attila, the Hun}{, the Scourge of God}|\\ +% |\ForgetThis\Name{Attila, the Hun}\NameQueryInfo{}|\\ +% |\Name{Attila, the Hun}\NameQueryInfo{}|} +% \end{itemize}\endgroup +% +% \newpage +% +% \item Here we show a non-royal, medieval name: % \begin{Block} -% \FUse \Name {John, Eriugena}[Scotus Eriugena]\\ -% \UseB |\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}| +% \FUse \Name{John, Eriugena}[Scotus Eriugena]\\ +% \UseB |\Name{John, Eriugena}[Scotus Eriugena]|\\ +% \UseL \Name*{John, Eriugena}\dotfill |\Name*{John, Eriugena}|\\ +% \LUse \Name{John, Eriugena}\dotfill |\Name{John, Eriugena}| % \end{Block} % -% \item These are nonsensical name forms: +% \item Context matters; do not reverse names or force affixes arbitrarily: % \begin{Block} -% \LUse \ForceFN\FName{Elizabeth, I}\dotfill |\ForceFN\FName{Elizabeth, I}|\\ -% \LUse \RevName\Name*{John, Eriugena}\dotfill |\RevName\Name*{John, Eriugena}| +% \UseS \ForceFN\FName{Elizabeth, I}\dotfill^^A +% |\ForceFN\FName{Elizabeth, I}|\\ +% \UseL \RevName\Name*{John, Eriugena}\dotfill^^A +% |\RevName\Name*{John, Eriugena}| % \end{Block} % -% \item The trivial case: +% \item Here is the trivial case: % \begin{Block} % \FUse \Name{Aristotle}\dotfill |\Name{Aristotle}|\\ % \LUse \Name{Aristotle}\dotfill |\Name{Aristotle}| % \end{Block} % \end{itemize} % +% \subsubsection[Selecting Types]{More about Selecting Name Types} +% \label{sec:SelectingTypes} +% +% \ExcludeName{Leif, Erikson} +% \ExcludeName[Pontius]{Pilate} +% How does one decide from among these name forms? Some choices are fairly obvious and standardized. Others depend on one's culture and publication standards. +% \begin{itemize} +% \item Dealing with patronyms can vary according to one's culture. +% \PatInfo[4ex]{\ShowPattern[Leif]{Erikson}\break +% \ShowPattern{Leif, Erikson}} +% \begin{itemize} +% \item To index under the patronym, use a Western form: +% \begin{Block} +% \ForgetThis\Name[Leif]{Erikson}\dotfill|\Name[Leif]{Erikson}|\\ +% \Name[Leif]{Erikson}\dotfill|\Name[Leif]{Erikson}|\\ +% \FName[Leif]{Erikson}\dotfill|\FName[Leif]{Erikson}|\\ +% Index: \ShowIdxPageref*[Leif]{Erikson} +% \end{Block} +% +% \item To index under the personal name, use a Non-Western form: +% \begin{Block} +% \Name{Leif, Erikson}\dotfill|\Name{Leif, Erikson}|\\ +% \Name{Leif, Erikson}\dotfill|\Name{Leif, Erikson}|\\ +% \ForceFN\FName{Leif, Erikson}\dotfill^^A +% |\ForceFN\FName{Leif, Erikson}|\\ +% Index: \ShowIdxPageref*{Leif, Erikson} +% \end{Block} +% \end{itemize} +% +% \item Roman names are quite challenging (Sections~\ref{sec:Romani}f.). +% \PatInfo[4ex]{\ShowPattern[M.T.]{Cicero}\break +% \ShowPattern[Pontius]{Pilate}\break +% \ShowPattern{Pontius,Pilate}} +% \begin{itemize} +% \item Common Western usage draws on popular name forms: +% \begin{Block} +% \ForgetThis\Name[M.T.]{Cicero}\dotfill|\Name[M.T.]{Cicero}|\\ +% \Name[M.T.]{Cicero}\dotfill|\Name[M.T.]{Cicero}|\\ +% Index: \ShowIdxPageref*[M.T.]{Cicero} +% \end{Block} +% +% \item That segues into names indexed by \LA{cognomen}: +% \begin{Block} +% \Name[Pontius]{Pilate}\dotfill|\Name[Pontius]{Pilate}|\\ +% \Name[Pontius]{Pilate}\dotfill|\Name[Pontius]{Pilate}|\\ +% Index: \ShowIdxPageref*[Pontius]{Pilate} +% \end{Block} +% +% \item Yet other approaches can index by \LA{nomen}: +% \begin{Block} +% \ForgetThis\Name{Pontius,Pilate}\dotfill^^A +% |\Name{Pontius,Pilate}|\\ +% \Name{Pontius,Pilate}\dotfill|\Name{Pontius,Pilate}|\\ +% \ForceFN\FName{Pontius,Pilate}\dotfill^^A +% |\ForceFN\FName{Pontius,Pilate}|\\ +% Index: \ShowIdxPageref*{Pontius,Pilate} +% \end{Block} +% \end{itemize} +% \end{itemize} +% +% There are ways to display a name using one form, while indexing under another, starting in Section~\ref{sec:NameMedieval}. The quick interface discussed in the next section can make these choices easier to implement and change, if needed. One should consult a style guide or in-house guidelines to help choose the proper name forms. +% % \newpage % % \subsection{Quick Interface} @@ -2247,8 +2499,7 @@ and version 1.3 or later is part of all distributions of LaTeX version % \end{SyntaxBox} % % In this context, \meta{arg1} becomes the root of three new macros per name: -% -% \begin{quote} +% \begin{Quote} % \begin{tabular}{@{\quad}l@{\ same as: }ll} % \texttt{\textbackslash}\meta{arg1} & % \cmd{\Name\ }\oarg{arg2}\marg{arg3}\oarg{arg4} \\ @@ -2259,45 +2510,59 @@ and version 1.3 or later is part of all distributions of LaTeX version % \cmd{\FName}\oarg{arg2}\marg{arg3}\oarg{arg4} & % {\color{nared} |%| S for \textit{short}} \\ % \end{tabular} -% \end{quote} +% \end{Quote} % -% 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: +% 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 with the basic interface: % % \begin{SyntaxBox} % \cmd{\begin\{nameauth\}}\\ % \hspace{2em}\cmd{\<} \meta{arg1} \texttt{\&} % \meta{\color{nared}FNN} \texttt{\&} -% \meta{SNN\color{nared}, Affix} \texttt{\&} +% \meta{SNN\color{nared}\textbf{,}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. % -% 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} +% \Info*{\small\dbend}Package warnings 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} % \begin{Verbatim} % \begin{nameauth} % \< White & E.B. & White & > % version 1 % \< White & E.\,B. & White & > % version 2 % \end{nameauth} % \end{Verbatim} -% \end{quote} +% \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.} +% \BothInfo*{\ShowPattern[E.\,B.]{White}} +% {\ShowIdxPageref*[E.\,B.]{White}}^^A +% \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 \textsf{nameauth} an intended warning will appear: \texttt{Shorthand macro already exists.}} % -% 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}. +% 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 (articles and prepositions), which are discussed in greater detail in Section~\ref{sec:NameParticles}. % % \newpage % % 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} +% \begin{Quote} +% \JustIndex\Wash^^A +% \JustIndex\Lewis^^A +% \JustIndex\Patton^^A +% \JustIndex\JRIV^^A +% \JustIndex\Soto^^A +% \JustIndex\JLF^^A +% \JustIndex\JWG^^A +% \JustIndex\Noguchi^^A +% \JustIndex\Molnar^^A +% \JustIndex\Miyazaki^^A +% \JustIndex\Eliz^^A +% \JustIndex\Aeth^^A +% \JustIndex\Eriugena^^A +% \JustIndex\Aris^^A % \begin{Verbatim} % \begin{nameauth} % % Western Name Forms @@ -2309,8 +2574,8 @@ and version 1.3 or later is part of all distributions of LaTeX version % \< JRIV & J.D. & Rockefeller, IV & > % % Western Name Forms with Particles % \< Soto & Hernando & de Soto & > +% \< JLF & Jean de & La Fontaine & > % \< JWG & J.W. von & Goethe & > -% \< VBuren & Martin & Van Buren & > % % Reversed Western Forms % \< Noguchi & Hideyo & Noguchi & > % \< Molnar & Frenec & Molnár & > @@ -2326,14 +2591,15 @@ and version 1.3 or later is part of all distributions of LaTeX version % \< MSens & & Miyazaki, Hayao & Sensei > % \end{nameauth} % \end{Verbatim} -% \end{quote} +% \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} +% \begin{Center} +% \BothInfo[4ex]{\ShowPattern[George]{Washington}} +% {\ShowIdxPageref*[George]{Washington}} % \begin{tabular}{rll}\toprule % \rowcolor{nagrey}^^A -% \bfseries Output & & \bfseries Macro\\ +% \bfseries Text & & \bfseries Macro / Arguments\\ % % \Wash & Quick: & \cmd{\Wash}\\ % & Basic: & @@ -2344,7 +2610,7 @@ and version 1.3 or later is part of all distributions of LaTeX version % \rowcolor{nagrey}^^A % & Basic: & % \cmd{\Name*}\texttt{[George]\{Washington\}}\\ -% +% % \SWash & Quick: & \cmd{\SWash}\\ % & Basic: & % \cmd{\FName}\texttt{[George]\{Washington\}}\\ @@ -2353,154 +2619,181 @@ and version 1.3 or later is part of all distributions of LaTeX version % \ForgetThis\Wash & Quick: & \cmd{\ForgetThis}\cmd{\Wash}\\ % \rowcolor{nagrey}^^A % & Basic: & -% \cmd{\ForgetName}\texttt{[George]\{Washington\}}\\ +% \cmd{\ForgetName}^^A +% \texttt{[George]\{Washington\}}\\ % \rowcolor{nagrey}^^A % & & % \cmd{\Name}\texttt{[George]\{Washington\}}\\ % -% \ForgetThis\Wash & Quick: & \cmd{\ForgetThis}\cmd{\Wash}\\ +% \rowcolor{nagrey}^^A +% & & \emph{---\,OR\,---}\\ +% \rowcolor{nagrey}^^A % & Basic: & % \cmd{\ForgetThis}^^A % \cmd{\Name}\texttt{[George]\{Washington\}}\\ % -% \rowcolor{nagrey}^^A % \SubvertThis\Wash & Quick: & \cmd{\SubvertThis}\cmd{\Wash}\\ -% \rowcolor{nagrey}^^A % & Basic: & -% \cmd{\SubvertName}\texttt{[George]\{Washington\}}\\ -% \rowcolor{nagrey}^^A +% \cmd{\SubvertName}^^A +% \texttt{[George]\{Washington\}}\\ % & & % \cmd{\Name}\texttt{[George]\{Washington\}}\\ % -% \SubvertThis\Wash & Quick: & \cmd{\SubvertThis}\cmd{\Wash}\\ +% & & \emph{---\,OR\,---}\\ % & Basic: & -% \cmd{\SubvertThis}\cmd{\Name}\texttt{[George]\{Washington\}}\\ +% \cmd{\SubvertThis}\cmd{\Name}^^A +% \texttt{[George]\{Washington\}}\\ % % \rowcolor{nagrey}^^A -% \JustIndex\Wash(unseen in text) & Quick: & \cmd{\JustIndex}\cmd{\Wash}\\ +% \JustIndex\Wash(unseen in text) & Quick: & +% \cmd{\JustIndex}\cmd{\Wash}\\ % \rowcolor{nagrey}^^A % & Basic: & -% \cmd{\IndexName}\texttt{[George]\{Washington\}}\\\bottomrule +% \cmd{\IndexName}^^A +% \texttt{[George]\{Washington\}}\\\bottomrule % \end{tabular} -% \end{center} +% \end{Center} % % \newpage % % \subsubsection[Name Variants]{Quick Name Variant Overview} % -% After setting up the previous \texttt{nameauth} environment, we use the resulting name shorthands. Below we show more ``prefix macros'' that affect name forms in the text. We hide the use of \cmd{\ForgetThis} (Section~\ref{sec:NameControl}), which creates first instances. -% +% After setting up the previous \texttt{nameauth} environment, we use the resulting name shorthands. Below we show more prefix macros that affect name forms in the text (Section~\ref{sec:ListPrefix}). We hide the use of \cmd{\ForgetThis} (Section~\ref{sec:NameControl}), which makes the \textsf{nameauth} logic ``forget'' that a name exists, creating a first-use instance. % \begin{itemize} % \item Western Names: \hfill Sections~\ref{sec:Naming}, % \ref{sec:FName} -% \BothInfo{\ShowPattern[George]{Washington}\break -% \ShowPattern[George S.]{Patton, Jr.}\break -% \ShowPattern[J.D.]{Rockefeller, IV}\break -% \ShowPattern[Clive Staples]{Lewis}\break -% \ShowPattern[Hideyo]{Noguchi}\break -% \ShowPattern{Miyazaki, Hayao}} -% {\ShowIdxPageref*[George]{Washington}\break -% \ShowIdxPageref*[George S.]{Patton, Jr.}\break -% \ShowIdxPageref*[J.D.]{Rockefeller, IV}\break -% \ShowIdxPageref*[Clive Staples]{Lewis}\break -% \ShowIdxPageref*[Hideyo]{Noguchi}\break -% \ShowIdxPageref*{Miyazaki, Hayao}} +% \BothInfo*{\ShowPattern[George]{Washington}} +% {\ShowIdxPageref*[George]{Washington}} % \begin{Block} % \FUse \ForgetThis\Wash \dotfill \cmd{\Wash}\\ -% \LUse \LWash \dotfill \cmd{\LWash}\\ +% \UseL \LWash \dotfill \cmd{\LWash}\\ % \LUse \Wash \dotfill \cmd{\Wash}\\ -% \LUse \SWash \dotfill \cmd{\SWash} +% \UseS \SWash \dotfill \cmd{\SWash} % \end{Block} % % \item Nicknames and Affixes: \hfill Sections~\ref{sec:FName}, % \ref{sec:Affix} +% \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}} % \begin{Block} -% \FUse \ForgetThis\DropAffix\Patton \dotfill \cmd{\DropAffix}\cmd{\Patton}\\ -% \LUse \LPatton \dotfill \cmd{\LPatton}\\ +% \FUse \ForgetThis\DropAffix\Patton \dotfill^^A +% \cmd{\DropAffix}\cmd{\Patton}\\ +% \UseL \LPatton \dotfill \cmd{\LPatton}\\ +% \UseL \DropAffix\LPatton \dotfill \cmd{\DropAffix}\cmd{\LPatton}\\ +% \UseL \DropAffix\LPatton[George]\dotfill^^A +% \cmd{\DropAffix}\cmd{\LPatton[George]}\\ % \LUse \Patton \dotfill \cmd{\Patton}\\ -% \LUse \DropAffix\LPatton \dotfill \cmd{\DropAffix}\cmd{\LPatton}\\ -% \LUse \DropAffix\LPatton[George]\dotfill^^A -% \cmd{\DropAffix}\cmd{\LPatton[George]}\\ -% \LUse \SPatton\dotfill \cmd{\SPatton}\\ -% \LUse \SPatton[George]\dotfill \cmd{\SPatton[George]} +% \UseS \SPatton\dotfill \cmd{\SPatton}\\ +% \UseS \SPatton[George]\dotfill \cmd{\SPatton[George]} % \end{Block} % % \begin{Block} % \FUse \ForgetThis\JRIV[John Davison]\dotfill^^A -% \cmd{\JRIV[John Davison]}\\ -% \LUse \LJRIV \dotfill \cmd{\LJRIV}\\ -% \LUse \DropAffix\LJRIV[Jay]\dotfill \cmd{\DropAffix}\cmd{\LJRIV[Jay]} +% \cmd{\JRIV[John Davison]}\\ +% \UseL \LJRIV \dotfill \cmd{\LJRIV}\\ +% \UseL \DropAffix\LJRIV[Jay]\dotfill^^A +% \cmd{\DropAffix}\cmd{\LJRIV[Jay]}\\ +% \LUse \JRIV \dotfill \cmd{\JRIV} % \end{Block} % % \begin{Block} % \FUse \ForgetThis\Lewis\dotfill \cmd{\Lewis}\\ -% \LUse \LLewis[C.S.]\dotfill \cmd{\LLewis[C.S.]}\\ -% \LUse \LLewis[Jack]\dotfill \cmd{\LLewis[Jack]}\\ -% \LUse \SLewis\dotfill \cmd{\SLewis}\\ -% \LUse \SLewis[Jack]\dotfill \cmd{\SLewis[Jack]}\\ -% \LUse \LCSL\dotfill \cmd{\LCSL}\\ -% \LUse \SCSL\dotfill \cmd{\SCSL} +% \UseL \LLewis[C.S.]\dotfill \cmd{\LLewis[C.S.]}\\ +% \UseL \LLewis[Jack]\dotfill \cmd{\LLewis[Jack]}\\ +% \UseS \SLewis\dotfill \cmd{\SLewis}\\ +% \UseS \SLewis[Jack]\dotfill \cmd{\SLewis[Jack]}\\ +% \UseL \LCSL\dotfill \cmd{\LCSL}\\ +% \UseS \SCSL\dotfill \cmd{\SCSL} % \end{Block} % -% \item ``Native'' Eastern Names: \hfill Section~\ref{sec:Eastern} +% \item Non-Western (``Native'' Eastern) Names: \hfill Sections~\ref{sec:Eastern}, \ref{sec:AllCaps}, \ref{sec:RevNames} +% \BothInfo*{\ShowPattern{Miyazaki, Hayao}} +% {\ShowIdxPageref*{Miyazaki, Hayao}} % \begin{Block} -% \FUse \ForgetThis\CapName\Miyazaki\dotfill \cmd{\CapName}\cmd{\Miyazaki}\\ -% \LUse \CapName\LMiyazaki\dotfill \cmd{\CapName}\cmd{\LMiyazaki}\\ +% \FUse \ForgetThis\CapName\Miyazaki\dotfill^^A +% \cmd{\CapName}\cmd{\Miyazaki}\\ +% \UseL \CapName\LMiyazaki\dotfill \cmd{\CapName}\cmd{\LMiyazaki}\\ % \LUse \CapName\Miyazaki\dotfill \cmd{\CapName}\cmd{\Miyazaki}\\ -% \LUse \RevName\LMiyazaki\dotfill \cmd{\RevName}\cmd{\LMiyazaki}\\ -% \LUse \RevName\LMiyazaki[Mr.]\dotfill \cmd{\RevName}\cmd{\LMiyazaki[Mr.]}\\ -% \LUse \SMiyazaki\dotfill \cmd{\SMiyazaki}\\ -% \LUse \ForceFN\SMiyazaki\dotfill \cmd{\ForceFN}\cmd{\SMiyazaki} +% \UseL \RevName\LMiyazaki\dotfill \cmd{\RevName}\cmd{\LMiyazaki}\\ +% \UseL \RevName\LMiyazaki[Mr.]\dotfill^^A +% \cmd{\RevName}\cmd{\LMiyazaki[Mr.]}\\ +% \UseS \SMiyazaki\dotfill \cmd{\SMiyazaki}\\ +% \UseS \ForceFN\SMiyazaki\dotfill \cmd{\ForceFN}\cmd{\SMiyazaki} % \end{Block} % -% \item Reversed Western Names: \hfill Section~\ref{sec:RevNames} +% \item Reversed Western Names: \hfill Sections~\ref{sec:AllCaps}, \ref{sec:RevNames} +% \BothInfo*{\ShowPattern[Hideyo]{Noguchi}} +% {\ShowIdxPageref*[Hideyo]{Noguchi}} % \begin{Block} % \FUse \ForgetThis\Noguchi\dotfill \cmd{\Noguchi}\\ -% \LUse \LNoguchi\dotfill \cmd{\LNoguchi}\\ -% \LUse \LNoguchi[Doctor]\dotfill \cmd{\LNoguchi[Doctor]}\\ -% \LUse \SNoguchi\dotfill \cmd{\SNoguchi}\\ -% \LUse \RevName\LNoguchi\dag\dotfill \cmd{\RevName}\cmd{\LNoguchi}\cmd{\dag}\\ -% \LUse \CapName\RevName\LNoguchi\dag\dotfill^^A -% \cmd{\CapName}\cmd{\RevName}\cmd{\LNoguchi}\cmd{\dag}\\ -% \LUse \CapName\Noguchi\dag\dotfill \cmd{\CapName}\cmd{\Noguchi}\cmd{\dag} +% \UseL \LNoguchi\dotfill \cmd{\LNoguchi}\\ +% \UseL \LNoguchi[Doctor]\dotfill \cmd{\LNoguchi[Doctor]}\\ +% \UseS \SNoguchi\dotfill \cmd{\SNoguchi}\\ +% \UseL \RevName\LNoguchi\dag\dotfill^^A +% \cmd{\RevName}\cmd{\LNoguchi}\cmd{\dag}\\ +% \UseL \CapName\RevName\LNoguchi\dag\dotfill^^A +% \cmd{\CapName}\cmd{\RevName}\cmd{\LNoguchi}\cmd{\dag}\\ +% \LUse \CapName\Noguchi\dag\dotfill^^A +% \cmd{\CapName}\cmd{\Noguchi}\cmd{\dag} % \end{Block} % +% \newpage +% % \item Western Names Reversed by Surname: \hfill Section \ref{sec:LastFirst} +% \BothInfo*{\ShowPattern[George]{Washington}} +% {\ShowIdxPageref*[George]{Washington}} % \begin{Block} -% \FUse \ForgetThis\RevComma\LWash\dotfill \cmd{\RevComma}\cmd{\LWash}\\ -% \LUse \RevComma\LWash\dotfill \cmd{\RevComma}\cmd{\LWash} +% \FUse \ForgetThis\RevComma\Wash\dotfill \cmd{\RevComma}\cmd{\Wash}\\ +% \UseL \RevComma\LWash\dotfill \cmd{\RevComma}\cmd{\LWash} % \end{Block} % -% \item Particles: \hfill Section~\ref{sec:NameParticles} -% \BothInfo{\ShowPattern[Hernando]{de~Soto}\break -% \ShowPattern{Aristotle}\break -% \ShowPattern{Æthelred, II}\break -% \ShowPattern{John, Eriugena}} -% {\ShowIdxPageref*[Hernando]{de~Soto}\break -% \ShowIdxPageref*{Aristotle}\break -% \ShowIdxPageref*{Æthelred, II}\break -% \ShowIdxPageref*{John, Eriugena}} +% \item Particles, English usage: \hfill Section~\ref{sec:NameParticles} +% \BothInfo*{\ShowPattern[Hernando]{de~Soto}} +% {\ShowIdxPageref*[Hernando]{de~Soto}} % \begin{Block} % \FUse \ForgetThis\Soto\dotfill \cmd{\Soto}\\ -% \LUse \Soto\dotfill \cmd{\Soto}\\ % \LUse \CapThis\Soto\dotfill \cmd{\CapThis}\cmd{\Soto} % \end{Block} % -% \item Royal and Medieval Names: \hfill Section~\ref{sec:NameMedieval} +% \item Particles, Non-English usage: \hfill Section~\ref{sec:NameParticles} +% \BothInfo*{\ShowPattern[Jean de]{La Fontaine}\break +% \ShowPattern[J.W. von]{Goethe}} +% {\ShowIdxPageref*[Jean de]{La Fontaine}\break +% \ShowIdxPageref*[J.W. von]{Goethe}} +% \begin{Block} +% \FUse \ForgetThis\JLF\dotfill \cmd{\JLF}\\ +% \LUse \JLF\dotfill \cmd{\JLF}\\ +% \FUse \ForgetThis\JWG[Joh. Wolfgang v.]\dotfill^^A +% |\JWG[Joh. Wolfgang v.]|\\ +% \LUse \JWG\dotfill \cmd{\JWG} +% \end{Block} +% +% \item Royal, Medieval, and Ancient Names: \hfill Sections~\ref{sec:NameMedieval}, \ref{sec:NameAncient} +% \BothInfo*{\ShowPattern{Æthelred, II}\break +% \ShowPattern{John, Eriugena}\break +% \ShowPattern{Aristotle}} +% {\ShowIdxPageref*{Æthelred, II}\break +% \ShowIdxPageref*{John, Eriugena}\break +% \ShowIdxPageref*{Aristotle}} % \begin{Block} % \FUse \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\}}.}\dotfill \cmd{\Aeth}\\ +% {Regarding the margin note with name patterns, with +% \texttt{pdflatex} and \texttt{latex} using \textsf{inputenc} +% and \textsf{fontenc}, in \texttt{\ShowPattern{Æthelred, II}} +% the glyphs \texttt{ÃĘ} correspond to \cmd{\IeC\{}\cmd{\AE\}}.}^^A +% \dotfill \cmd{\Aeth}\\ % \LUse \Aeth\dotfill \cmd{\Aeth}\\ -% \LUse \LAeth[II, ``Unræd'']\dotfill |\LAeth[II, ``Unræd'']| +% \UseL \LAeth[II, ``Unræd'']\dotfill |\LAeth[II, ``Unræd'']| % \end{Block} % % \begin{Block} % \FUse \ForgetThis\Eriugena[Scotus Eriugena]\dotfill^^A -% \cmd{\Eriugena[Scotus Eriugena]}\\ -% \LUse \LEriugena\dotfill \cmd{\LEriugena}\\ +% \cmd{\Eriugena[Scotus Eriugena]}\\ +% \UseL \LEriugena\dotfill \cmd{\LEriugena}\\ % \LUse \Eriugena\dotfill \cmd{\Eriugena} % \end{Block} % @@ -2511,284 +2804,257 @@ and version 1.3 or later is part of all distributions of LaTeX version % \end{itemize} % % \subsubsection[\protect\textit{Alternate} Field] -% {\protect\meta{Alternate} Name Field Tips} +% {\protect\meta{Alternate} Name Field} % \label{sec:ArgIV} % % 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{itemize} -% \item They share identical name control patterns -% (Section~\ref{sec:NamePatterns}). -% \BothInfo{\ShowPattern[Clive Staples]{Lewis}\break +% \item They share identical name patterns (Section~\ref{sec:NamePatterns}). +% \BothInfo*{\ShowPattern[Clive Staples]{Lewis}\break % \ShowPattern{Miyazaki, Hayao}} % {\ShowIdxPageref*[Clive Staples]{Lewis}\break % \ShowIdxPageref*{Miyazaki, Hayao}} % \begin{Block} % \ForgetName{Miyazaki, Hayao}\ForgetName[Clive Staples]{Lewis} -% \FUse \MSens\dotfill \cmd{\MSens}\\ -% \LUse \Miyazaki\dotfill \cmd{\Miyazaki}\\ % \FUse \CSL\dotfill \cmd{\CSL}\\ -% \LUse \Lewis\dotfill \cmd{\Lewis} +% \LUse \Lewis\dotfill \cmd{\Lewis}\\ +% \FUse \MSens\dotfill \cmd{\MSens}\\ +% \LUse \Miyazaki\dotfill \cmd{\Miyazaki} % \end{Block} % -% \item Usually, one leaves \meta{arg4} empty and adds alternate names in -% brackets as needed: \LLewis[C.S.] \cmd{\LLewis[C.S.]} +% \item Usually, one leaves \meta{arg4} empty and adds alternate names in brackets as needed: \LLewis[C.S.] \cmd{\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 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 \LCSL[Jack] -% \cmd{\LCSL[Jack]} and \LMSens[Sensei] \cmd{\LMSens[Sensei]}. -% The reason why these macro versions produce undesired output is because -% \meta{arg4} permanently populates \meta{Alternate}. +% \item Failure to keep track of such macros creates output like \LCSL[Jack] \cmd{\LCSL[Jack]} and \LMSens[Sensei] \cmd{\LMSens[Sensei]}. The \meta{arg4} content populates \meta{Alternate}; the text in brackets is just text. % -% \item Remember that \meta{arg4} can be used for the obsolete -% syntax, as mentioned previously, but we do not cover that here. +% \item Remember that \meta{arg4} can be used for the obsolete syntax, as mentioned previously, but we do not cover that here. % \end{itemize} % -% \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.\negmedskip^^A -% \index{scientists, quotes of\noexpand\string|hyperpage} -% \end{Quote} -% % \newpage % % \subsection{Select Macro Overview} -% \label{sec:SelectOver} % % \subsubsection[With Name Args]{Macros with Name Arguments} % \label{sec:NameArgMacros} % -% All macros that take name arguments (Section~\ref{sec:NameArgs}) can have final optional arguments (Section~\ref{sec:FinalOptargs}) and update \cmd{\NameauthPattern} (Section~\ref{sec:DataTemp}). The \meta{xref args} are the same as \meta{name args} for a cross-reference to a \meta{target} (Section~\ref{sec:IndexRef}). -% \begin{center} +% Macros that take name arguments (Section~\ref{sec:NameArgs}) can have final optional arguments (Section~\ref{sec:FinalOptargs}) and update \cmd{\NameauthPattern} (Section~\ref{sec:NamePatterns}). The \meta{xref args} are the same as \meta{name args} for a cross-reference to a \meta{target} (Section~\ref{sec:IndexRef}). For more on null arguments, see Section~\ref{sec:NullArgs}. +% \begin{Center} % \begin{tabular}{lrcll}\toprule % \rowcolor{nagrey}^^A -% \llap{\colorbox{nagrey}{\hbox to 2.65cm{\strut\hfill}}\qquad\qquad}^^A +% \tmarg[nagrey]{}^^A % Optional Prefix & Macro & Star & Arguments & \\ % -% \llap{\colorbox{white}{\hbox to 2.65cm{\strut\hfill Naming}}\qquad\qquad}^^A +% \tmarg{Print a name}^^A % \meta{prefix macros} & % \cmd{\Name} & \texttt{*} & \meta{name args} & \\ -% \llap{\colorbox{white}{\hbox to 2.65cm{\strut\hfill}}\qquad\qquad}^^A +% \tmarg{}^^A % \meta{prefix macros} & % \cmd{\FName} & \texttt{*} & \meta{name args} & \\ % % \rowcolor{nagrey}^^A -% \llap{\colorbox{nagrey}{\hbox to 2.65cm{\strut\hfill Page entry}}\qquad\qquad}^^A -% \cmd{\SeeAlso} & \cmd{\IndexName} & & -% \meta{name args} & \\ +% \tmarg[nagrey]{Page entry}^^A +% only \cmd{\SeeAlso} & \cmd{\IndexName} & & \meta{name args} & \\ % \rowcolor{nagrey}^^A -% \llap{\colorbox{nagrey}{\hbox to 2.65cm{\strut\hfill Only cross-ref}}\qquad\qquad}^^A -% \cmd{\SeeAlso} & \cmd{\IndexRef} & & +% \tmarg[nagrey]{Only cross-reference}^^A +% only \cmd{\SeeAlso} & \cmd{\IndexRef} & & % \meta{xref args} & \meta{target}\\ % -% \llap{\colorbox{white}{\hbox to 2.65cm{\strut\hfill Stop page entry}}\qquad\qquad}^^A -% & \cmd{\ExcludeName} & & -% \meta{name args} & \\ -% \llap{\colorbox{white}{\hbox to 2.65cm{\strut\hfill Allow page entry}}\qquad\qquad}^^A -% & \cmd{\IncludeName} & -% \texttt{*} & \meta{name args} & \\ +% \tmarg{Stop page entry}^^A +% & \cmd{\ExcludeName} & & \meta{name args} & \\ +% \tmarg{Allow page entry}^^A +% & \cmd{\IncludeName} & \texttt{*} & \meta{name args} & \\ % % \rowcolor{nagrey}^^A -% \llap{\colorbox{nagrey}{\hbox to 2.65cm{\strut\hfill Sort index}}\qquad\qquad}^^A -% & \cmd{\PretagName} & & \meta{name args} & -% \meta{sort key} \\ +% \tmarg[nagrey]{Sort index}^^A +% & \cmd{\PretagName} & & \meta{name args} & \meta{sort key} \\ % \rowcolor{nagrey}^^A -% \llap{\colorbox{nagrey}{\hbox to 2.65cm{\strut\hfill Make index tag}}\qquad\qquad}^^A -% & \cmd{\TagName} & & \meta{name args} & -% \meta{tag} \\ +% \tmarg[nagrey]{Make index tag}^^A +% & \cmd{\TagName} & & \meta{name args} & \meta{tag} \\ % \rowcolor{nagrey}^^A -% \llap{\colorbox{nagrey}{\hbox to 2.65cm{\strut\hfill Delete index tag}}\qquad\qquad}^^A +% \tmarg[nagrey]{Delete index tag}^^A % & \cmd{\UntagName} & & \meta{name args} & \\ % -% \llap{\colorbox{white}{\hbox to 2.65cm{\strut\hfill Make name tag}}\qquad\qquad}^^A -% & \cmd{\NameAddInfo} & & -% \meta{name args} & \meta{tag} \\ -% \llap{\colorbox{white}{\hbox to 2.65cm{\strut\hfill Show name tag}}\qquad\qquad}^^A -% & \cmd{\NameQueryInfo} & & -% \meta{name args} & \\ -% \llap{\colorbox{white}{\hbox to 2.65cm{\strut\hfill Delete name tag}}\qquad\qquad}^^A -% & \cmd{\NameClearInfo} & & -% \meta{name args} & \\ +% \tmarg{Make name tag}^^A +% & \cmd{\NameAddInfo} & & \meta{name args} & \meta{tag} \\ +% \tmarg{Show name tag}^^A +% & \cmd{\NameQueryInfo} & & \meta{name args} & or null argument \\ +% \tmarg{Delete name tag}^^A +% & \cmd{\NameClearInfo} & & \meta{name args} & \\ % % \rowcolor{nagrey}^^A -% \llap{\colorbox{nagrey}{\hbox to 2.65cm{\strut\hfill Delete name cs}}\qquad\qquad}^^A +% \tmarg[nagrey]{Delete name pattern}^^A % & \cmd{\ForgetName} & & \meta{name args} & \\ % \rowcolor{nagrey}^^A -% \llap{\colorbox{nagrey}{\hbox to 2.65cm{\strut\hfill Create name cs}}\qquad\qquad}^^A -% & \cmd{\SubvertName} & & -% \meta{name args} & \\ -% -% \llap{\colorbox{white}{\hbox to 2.65cm{\strut\hfill Name cs tests}}\qquad\qquad}^^A -% & \cmd{\IfMainName} & & -% \meta{name args} & \marg{y}\marg{n}\\ -% \llap{\colorbox{white}{\hbox to 2.65cm{\strut\hfill}}\qquad\qquad}^^A -% & \cmd{\IfFrontName} & & \meta{name args} & -% \marg{y}\marg{n}\\ -% \llap{\colorbox{white}{\hbox to 2.65cm{\strut\hfill}}\qquad\qquad}^^A +% \tmarg[nagrey]{Create name pattern}^^A +% & \cmd{\SubvertName} & & \meta{name args} & \\ +% +% \tmarg{Name pattern tests}^^A +% & \cmd{\IfMainName} & & \meta{name args} & \marg{y}\marg{n}\\ +% \tmarg{}^^A +% & \cmd{\IfFrontName} & & \meta{name args} & \marg{y}\marg{n}\\ +% \tmarg{}^^A % & \cmd{\IfAKA} & & \meta{name args} & \marg{y}\marg{n}\marg{x}\\ % % \rowcolor{nagrey}^^A -% \llap{\colorbox{nagrey}{\hbox to 2.65cm{\strut\hfill Debugging}}\qquad\qquad}^^A -% & \cmd{\ShowPattern} & & \meta{name args} & \\ +% \tmarg[nagrey]{Debugging}^^A +% & \cmd{\ShowPattern} & & \meta{name args} & or null argument \\ % \rowcolor{nagrey}^^A -% \llap{\colorbox{nagrey}{\hbox to 2.65cm{\strut\hfill}}\qquad\qquad}^^A -% & \cmd{\ShowIdxPageref} & \texttt{*} & \meta{name args} & \\ +% \tmarg[nagrey]{}^^A +% & \cmd{\ShowIdxPageref} & \texttt{*} +% & \meta{name args} & or null argument \\ % \rowcolor{nagrey}^^A -% \llap{\colorbox{nagrey}{\hbox to 2.65cm{\strut\hfill}}\qquad\qquad}^^A -% & \cmd{\ShowNameInfo} & & \meta{name args} & \\ +% \tmarg[nagrey]{}^^A +% & \cmd{\ShowNameInfo} & & \meta{name args} & or null argument \\ % \rowcolor{nagrey}^^A -% \llap{\colorbox{nagrey}{\hbox to 2.65cm{\strut\hfill}}\qquad\qquad}^^A -% & \cmd{\ShowNameState} & & \meta{name args} &\\\bottomrule +% \tmarg[nagrey]{}^^A +% & \cmd{\ShowNameState} & \texttt{*} +% & \meta{name args} & or null argument \\\bottomrule % \end{tabular} -% \end{center} +% \end{Center} % -% Optional prefix macros are shown in the next subsection. Not shown above are \cmd{\AKA}, \cmd{\AKA*}, \cmd{\PName}, and \cmd{\PName*} (Section~\ref{sec:AKA}). +% Regarding prefix macros, see Section~\ref{sec:ListPrefix}. Not shown above are \cmd{\AKA}, \cmd{\AKA*}, \cmd{\PName}, and \cmd{\PName*} (Section~\ref{sec:AKA}). They have their own rules. % -% \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.^^A -% \index{politicians, quotes of\noexpand\string|hyperpage} -% \end{Quote} +% \begin{Quotation}{\ForgetThis\Miyazaki} +% {Proposal for \Title{Princess Mononoke} (c. 1994)} +% We depict hatred, but it is to depict that there are more important +% things. We depict a curse, to depict the joy of liberation. +% \index{creatives, quotes of\noexpand\string|hyperpage} +% \end{Quotation} % % \newpage % % \subsubsection{Prefix Macros} +% \label{sec:ListPrefix} % % 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{itemize}[rightmargin=0em] -% \item Capitalization in the Text\negmedskip -% \begin{itemize}[leftmargin=6.5em]\small +% \item Capitalization in the text: +% \begin{itemize}[leftmargin=6.9em]\small % \item[\cmd{\CapName}] Capitalize entire \meta{SNN}. Overrides \cmd{\CapThis}. % \item[\cmd{\CapThis}] Capitalize first letter of all name components. % \item[\cmd{\AccentCapThis}] Fallback when Unicode detection cannot be done. % \end{itemize} % -% \item Reversing in the Text\negmedskip -% \begin{itemize}[leftmargin=6.5em]\small +% \item Reversing names in the text: +% \begin{itemize}[leftmargin=6.9em]\small % \item[\cmd{\RevName}] Reverse order of any name. Overrides \cmd{\RevComma} % \item[\cmd{\RevComma}] Reverse only Western names to \meta{SNN}, \meta{FNN}. % \end{itemize} % -% \item Commas in the Text\negmedskip -% \begin{itemize}[leftmargin=6.5em]\small +% \item Use of commas before Western affixes in the text: +% \begin{itemize}[leftmargin=6.9em]\small % \item[\cmd{\ShowComma}] Add comma between \meta{SNN} and \meta{Affix}. % \item[\cmd{\NoComma}] No comma between \meta{SNN} and \meta{Affix}. Overrides \cmd{\ShowComma}. % \end{itemize} % -% \item Name Breaks in the Text\negmedskip -% \begin{itemize}[leftmargin=6.5em]\small +% \item Name breaks in the text: +% \begin{itemize}[leftmargin=6.9em]\small % \item[\cmd{\DropAffix}] Drop affix only for a long Western name instance. -% \item[\cmd{\KeepAffix}] Insert non-breaking space (NBSP) between \meta{SNN}, \meta{FNN/Affix}. +% \item[\cmd{\KeepAffix}] Insert non-breaking space between \meta{SNN}, \meta{FNN/Affix}. % \item[\cmd{\KeepName}] Insert NBSP between all name elements. Overrides \cmd{\KeepAffix}. % \end{itemize} % -% \item Forcing Name Forms via Control Sequence\negmedskip -% \begin{itemize}[leftmargin=6.5em]\small +% \item Forcing name forms in the text by deleting or creating patterns: +% \begin{itemize}[leftmargin=6.9em]\small % \item[\cmd{\ForgetThis}] Force first name instance. Negates \cmd{\SubvertThis}. % \item[\cmd{\SubvertThis}] Force subsequent name instance. % \end{itemize} % -% \item Forcing Name Forms via Boolean Flags\negmedskip -% \begin{itemize}[leftmargin=6.5em]\small +% \item Forcing other name forms: +% \begin{itemize}[leftmargin=6.9em]\small % \item[\cmd{\ForceName}] Force first-use formatting hooks. -% \item[\cmd{\ForceFN}] Print \meta{Affix}/\meta{Alternate} in nonwestern short forms. +% \item[\cmd{\ForceAffix}] Print only the affix of a Western name (Section~\ref{sec:RomanGeneral}). +% \item[\cmd{\ForceFN}] Print \meta{Affix} or \meta{Alternate} in a Non-Western short name. % \end{itemize} % -% \item Indexing\negmedskip -% \begin{itemize}[leftmargin=6.5em]\small +% \item Indexing: +% \begin{itemize}[leftmargin=6.9em]\small % \item[\cmd{\SeeAlso}] For \cmd{\IndexName}, \cmd{\AKA}, and \cmd{\PName}; make a \textit{see also} xref. -% \item[\cmd{\SkipIndex}] For naming macros; do not create index entry (once). -% \item[\cmd{\JustIndex}] For naming macros; index only (once); negated by \cmd{\AKA}, \cmd{\PName}. -% \end{itemize} +% \item[\cmd{\SkipIndex}] For naming macros; do not create index entry. +% \item[\cmd{\JustIndex}] For naming macros; index only; negated by \cmd{\AKA}, \cmd{\PName}. % \end{itemize} % -% \noindent Some important notes include: -% -% \begin{itemize} -% \item Prefix macros stack:\\[0.4ex] +% \item Prefix macros can ``stack'' their effects:\\[0.4ex] % \CapThis\RevName\SkipIndex\Name[bar]{foo}\dotfill^^A % |\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 via \cmd{\JustIndex}. -% \item Even after using \cmd{\JustIndex}, several name form modifiers are reset. -% This prevents errors when handling the next name. -% \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. -% \end{itemize} % -% \noindent Macros that do not take name arguments include prefix macros (Section~\ref{sec:PrefixMacs}), helper macros (Section~\ref{sec:Helpers}), most internal package macros, and formatting macros (Sections~\ref{sec:Formatting} and~\ref{sec:AdvancedFormat}). +% \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 via \cmd{\JustIndex}. % -% \newpage +% \item Even after using \cmd{\JustIndex}, several name form modifiers are reset. This prevents errors when handling the next name. +% +% \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. +% \end{itemize} % % \subsection{Names and Complexity} % \label{sec:Complexity} % -% The \textsf{nameauth} package allows levels of complexity when representing names. Already, we have seen this example above: +% The \textsf{nameauth} package allows levels of complexity when representing names. Previously, we have seen this example: % % \begin{Block} % \LEliz[I ``Gloriana'']\dotfill |\LEliz[I ``Gloriana'']| % \end{Block} % -% We can display the same thing with different macros. This next example does not offer more features; it only offers more complexity: +% We can display the same name form using different macros. This next example does not offer more features; it only presents more complexity: % % \begin{Block} % \LEliz\ ``\ForceFN\SEliz[Gloriana]''\dotfill^^A % |\LEliz\ ``\ForceFN\SEliz[Gloriana]''| % \end{Block} % -% The next example offers more features and better automation. Based on Section~\ref{sec:NameAncient} we use name tags and change the formatting hooks to match this manual's conventions. The key here is that \emph{we make a few key changes once,} which then govern many appearances of names: -% +% The next example offers more features and better automation. Based on Section~\ref{sec:NameAncient} (cf.~\ref{sec:Formatting}), we use name tags and adapt the formatting hooks to this manual's conventions. We make key changes once, which govern names thereafter: % \begingroup -% \begin{quote} +% \begin{Quote} % \begin{Verbatim} -% \NameAddInfo{Elizabeth, I}{ ``Gloriana''} +% \makeatletter +% \NameAddInfo{Elizabeth, I}{\if@nameauth@InHook{ }\fi``Gloriana''} +% \makeatother % \renewcommand*\NamesFormat[1] -% { -% \color{blue}\sffamily #1 -% \ifcsname\NameauthPattern!DB\endcsname -% \expandafter\csname\NameauthPattern!DB\endcsname -% \fi -% } +% {\color{blue}\sffamily #1\NameQueryInfo{}} % \renewcommand*\MainNameHook{\sffamily} % \end{Verbatim} -% \end{quote} +% \end{Quote} % -% \NameAddInfo{Elizabeth, I}{ ``Gloriana''} +% \makeatletter +% \NameAddInfo{Elizabeth, I}{\if@nameauth@InHook{ }\fi``Gloriana''} +% \makeatother % \renewcommand*\NamesFormat[1] -% {^^A -% \color{blue}\sffamily #1^^A -% \ifcsname\NameauthPattern!DB\endcsname -% \expandafter\csname\NameauthPattern!DB\endcsname^^A -% \fi -% } +% {\color{blue}\sffamily#1\NameQueryInfo{}} % \renewcommand*\MainNameHook{\sffamily} % \begin{Block} +% \BothInfo[1ex]{\ShowPattern{}}{\ShowIdxPageref*{}} % \FUse \ForgetThis\LEliz\dotfill |\ForgetThis\LEliz|\\ -% \LUse \LEliz\dotfill |\LEliz|\\ -% \LUse \Eliz\dotfill |\Eliz| +% \UseL \LEliz\dotfill |\LEliz|\\ +% \LUse \Eliz\dotfill |\Eliz|\\ +% \UseB \NameQueryInfo{}\dotfill |\NameQueryInfo{}| % \end{Block} % \endgroup % -% Section~\ref{sec:NameParticles} shows a similar trade-off between simplicity and automation with an 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 In \textsf{nameauth}, names are nouns that have state and modifiers. -% \item In \textsf{nameauth}, names are verbs capable of changing their environment. -% \item There are trade-offs between ease of use and automation. -% \item Simple examples often are not easy to automate. -% \item Automation works best with a few key changes. -% \item Most use-cases can be as simple as Section~\ref{sec:QuickExample}. -% \item Use the simple approach unless a complex approach is needed. +% \begin{itemize}[leftmargin=1em,rightmargin=0em,itemsep=0.2ex] +% \item Names are nouns with changeable states. +% \begin{itemize}[rightmargin=1em] +% \item \meta{FNN} and \meta{Alternate} can change easily in the text. +% +% \item Changing \meta{Affix} depends on the name type. +% +% \item Changing \meta{SNN} needs \cmd{\noexpand} with a macro that changes only in the formatting hooks (Section~\ref{sec:AltFormat}). % \end{itemize} -% \end{InfoBox} % +% \item Names also are verbs that affect their environment. +% +% \item There are design trade-offs: +% \begin{itemize} +% \item Simple examples are easy to write, but they can require subtle, ongoing changes of repetitive macros. +% +% \item Automation shifts the work to a complex, one-time setup that hides complexity thereafter. +% \end{itemize} +% +% \item Use a simple approach unless otherwise needed. +% \end{itemize} +% \end{InfoBox} % \ReturnLink % % \newpage @@ -2796,33 +3062,42 @@ and version 1.3 or later is part of all distributions of LaTeX version % \section{Package Options} % \label{sec:PkgOptions} % -% There are many options for use in \textsf{nameauth}, which can be divided into specific areas of functionality. These range from defaults that make conforming to certain standards easier to backward compatibility with old versions. The expected syntax follows: +% The \textsf{nameauth} options range from standards compliance, control, and appearance to backward compatibility with old versions. Thus: % % \begin{SyntaxBox} -% \cmd{\usepackage[}\meta{\(option_1\)}\texttt{,}\meta{\(option_2\)}^^A -% \texttt{,}\dots\texttt{,}\meta{\(option_n\)}\texttt{]\{nameauth\}} +% \cmd{\usepackage[}\meta{\(option_1\)}\textbf{,}\meta{\(option_2\)}^^A +% \textbf{,}\dots\textbf{,}\meta{\(option_n\)}\texttt{]\{nameauth\}} % \end{SyntaxBox} % -% 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. -% -% 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. +% We discuss package options according to the structure of this package. Section~\ref{sec:Priorities} shows the priority of options and related macros. Default options are in \emph{boldface} and need not be invoked. Other options are in \emph{\color{nared} dark red} and must be invoked explicitly. Many options work with macros offering finer control. % % \subsection{Name Grammar and Syntax} % -% \subsubsection[Affix Commas]{Show/Hide Affix Commas} +% \subsubsection*{\hfil Syntax Warnings} +% +% \begin{tabular}{p{0.22\textwidth}p{0.6\textwidth}} +% \leavevmode\color{nared}\quad\texttt{strictsyntax} & +% \leavevmode\color{nared}Show warnings when the obsolete syntax appears.\medskip\\ +% \end{tabular} +% +% \noindent Disabled by default, this option helps one to avoid using the obsolete syntax. +% +% \subsubsection*{\hfil Show/Hide Affix Commas} % % \begin{tabular}{p{0.22\textwidth}p{0.6\textwidth}} % \quad\bfseries\texttt{nocomma} & -% \bfseries Modern standards: Suppress commas between surnames and -% affixes.\smallskip\\ +% \bfseries Modern standards: Suppress commas between Western surnames +% and affixes.\smallskip\\ % \leavevmode\color{nared}\quad\texttt{comma} & -% \leavevmode\color{nared}Older standards: Retain commas between surnames -% and affixes.\medskip\\ +% \leavevmode\color{nared}Older standards: Retain commas between Western +% surnames and affixes.\medskip\\ % \end{tabular} % -% \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}. +% \BothInfo[2.5ex]{\ShowPattern[J.E.]{Carter, Jr.}} +% {\ShowIdxPageref*[J.E.]{Carter, Jr.}}^^A +% \noindent These options do not affect the index. The default \texttt{nocomma} option lets us produce, e.g., \Name*[J.E.]{Carter, Jr.} (\FName[J.E.]{Carter, Jr.}[Jimmy]). The \texttt{comma} option produces \ShowComma\Name*[J.E.]{Carter, Jr.}. For equivalent macros, see Section~\ref{sec:Affix}. % -% \subsubsection[Surname in Caps]{Capitalize Entire Surnames} +% \subsubsection*{\hfil Capitalize Entire Surnames} % % \begin{tabular}{p{0.22\textwidth}p{0.6\textwidth}} % \quad\bfseries\texttt{normalcaps} & @@ -2834,7 +3109,7 @@ and version 1.3 or later is part of all distributions of LaTeX version % % \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}). % -% \subsubsection{Reverse Name Order} +% \subsubsection*{\hfil Reverse Name Order} % % \begin{tabular}{p{0.22\textwidth}p{0.6\textwidth}} % \quad\bfseries\texttt{notreversed} & @@ -2842,17 +3117,17 @@ and version 1.3 or later is part of all distributions of LaTeX version % and the other macros.\smallskip\\ % \leavevmode\color{nared}\quad\texttt{allreversed} & % \leavevmode\color{nared}Print all name forms in ``smart'' reverse order; -% Western as nonwestern, and vice versa.\smallskip\\ +% 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\\ +% \leavevmode\color{nared}Print all Western names as +% ``Surname, Forenames''.\medskip\\ % \end{tabular} % % \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. % % \subsection{Indexing} % -% \subsubsection{Toggle Indexing} +% \subsubsection*{\hfil Toggle Indexing} % % \begin{tabular}{p{0.22\textwidth}p{0.6\textwidth}} % \quad\bfseries\texttt{index} & @@ -2861,14 +3136,16 @@ and version 1.3 or later is part of all distributions of LaTeX version % \leavevmode\color{nared}Suppress indexing of names.\medskip\\ % \end{tabular} % +%^^A ----- Recompile Point ----- %^^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. +%^^A auxiliary files before compiling this file. % % \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}. +% 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. +% +% \Info*{\small\dbend}Using \texttt{noindex} and \cmd{\IndexInactive} prevents index tags until \cmd{\IndexActive} is called, as explained in Section~\ref{sec:GeneralIndex}. For indexing feature priority, see Section~\ref{sec:Priorities}. % -% \subsubsection{Toggle Index Sorting} +% \subsubsection*{\hfil Toggle Index Sorting} % % \begin{tabular}{p{0.22\textwidth}p{0.6\textwidth}} % \quad\bfseries\texttt{pretag} & @@ -2877,9 +3154,9 @@ and version 1.3 or later is part of all distributions of LaTeX version % \leavevmode\color{nared}Do not create sort keys.\medskip\\ % \end{tabular} % -% \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 might be needed with, e.g., \texttt{xindy}. See Section~\ref{sec:IndexSort}. +% \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. See Section~\ref{sec:IndexSort}. % -% \subsubsection{Verbose Warnings} +% \subsubsection*{\hfil Verbose Warnings} % % \begin{tabular}{p{0.22\textwidth}p{0.6\textwidth}} % \leavevmode\color{nared}\quad\texttt{verbose} & @@ -2888,18 +3165,15 @@ and version 1.3 or later is part of all distributions of LaTeX version % % \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. % -% \addtocontents{toc}{\protect\goodbreak} -% -% \subsection[Formatting]{Formatting and Name Control Sequences} +% \subsection[Formatting]{Formatting and Name Patterns} % -% 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. +% Formatting, in its simplest form, is typographic post-processing of a name in the body text. In its complex forms, formatting can affect the syntactic form of a name in both the body text and the index. % -% \subsubsection[Choose System]{Choose Formatting System} +% \subsubsection*{\hfil Choose Formatting System} % % \begin{tabular}{p{0.22\textwidth}p{0.6\textwidth}} % \bfseries\quad\texttt{mainmatter} & -% \bfseries Start with ``main-matter names'' and formatting hooks \normalfont -% (Section~\ref{sec:PostProcess}).\smallskip\\ +% \bfseries Start with ``main-matter names'' and formatting hooks. \normalfont(Section~\ref{sec:Formatting})\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\\ @@ -2911,14 +3185,13 @@ and version 1.3 or later is part of all distributions of LaTeX version % the first use of a name with \cmd{\Name}.\medskip\\ % \end{tabular} % -% \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 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}. % -% The \texttt{alwaysformat} option forces ``first use'' hooks globally in both naming systems. Its use is limited in current versions of \textsf{nameauth}. +% The \texttt{alwaysformat} option forces ``first use'' hooks globally in both name systems. It is of limited usefulness in current versions of \textsf{nameauth}. % % 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. % -% \subsubsection[Predefined Hooks]{Predefined Formatting Hooks} -% \label{sec:PostProcess} +% \subsubsection*{\hfil Predefined Formatting Hooks} % % \begin{tabular}{p{0.22\textwidth}p{0.6\textwidth}} % \quad\bfseries\texttt{noformat} & @@ -2936,19 +3209,21 @@ and version 1.3 or later is part of all distributions of LaTeX version % \end{tabular} % % \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. +% See also Robert Bringhurst, \Title{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 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.} +% The following macros govern the way that names in the text appear. Two name 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 approach contributed to some ``cargo-cult'' programming, hopefully remedied.} % These hooks do not affect the index. Changes to the formatting hooks normally apply within the scope where they occur: -% % \begin{itemize} % \item \cmd{\NamesFormat} formats first uses of main-matter names. +% % \item \cmd{\MainNameHook} formats subsequent uses of main-matter names. +% % \item \cmd{\FrontNamesFormat} formats first uses of front-matter names. +% % \item \cmd{\FrontNameHook} formats subsequent uses of front-matter names. % \end{itemize} % -% 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. +% Sections \ref{sec:Formatting} and~\ref{sec:AdvancedFormat}f. 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} % @@ -2959,9 +3234,7 @@ and version 1.3 or later is part of all distributions of LaTeX version % default.\medskip\\ % \end{tabular} % -% \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. +% \noindent A built-in framework provides an alternate formatting mechanism that can be used for European or ``Continental'' standads in German, French, and so on. These standards often format surnames, both in the text and in the index. See Section~\ref{sec:AltFormat}. % % \subsection[Scope of Decisions]{Change Scope of Name Decision Macros} % @@ -2971,15 +3244,17 @@ and version 1.3 or later is part of all distributions of LaTeX version % scope.\medskip\\ % \end{tabular} % -% \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. +% \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. Note that names tracked by \textsf{nameauth} within such decision paths are global with respect to their values. % % \subsection{Version Compatibility} % \label{sec:OptionCompat} % +% These options can introduce undocumented behavior. They exist only for backward compatibility to help users cope with this author's ignorance as development changed to better fit the problem domain.\medskip +% % \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}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). @@ -3002,15 +3277,13 @@ and version 1.3 or later is part of all distributions of LaTeX version % \textsf{xparse} because of its advantages.\medskip\\ % \end{tabular} % -% Using these options may increase the chance of undocumented behavior.\footnote{Previously, the prefix macros and mechanisms for long and short names used Boolean flags locally. With continued use of this package, it became clear that such local scope 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.} -% They are included for the sake of approximate backward compatibility with older documents, illustrated by the following table: -% +% The following table shows how one gets approximate backward compatibility: % \begin{center} % \begin{tabular}{lll}\toprule % \rowcolor{nagrey}^^A % \bfseries Version & \bfseries Needed Options & \bfseries Possible Options \\ % -% 2.6 & \ttfamily oldreset,oldtoks,oldsee, & \ttfamily oldargs \\ +% \(\le2.6\) & \ttfamily oldreset,oldtoks,oldsee, & \ttfamily oldargs \\ % & \ttfamily oldAKA,oldpass & \\ % % \rowcolor{nagrey}^^A @@ -3024,22 +3297,29 @@ and version 1.3 or later is part of all distributions of LaTeX version % 3.5--3.7 & \ttfamily & \ttfamily oldargs \\\bottomrule % \end{tabular} % \end{center} -% % \ReturnLink % -% \begin{Quote}{\ForgetThis\MLK[Dr. Martin Luther], \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.^^A -% \index{civil rights leaders, quotes of\noexpand\string|hyperpage}^^A +% \begin{AltFormatZone} +% \begin{Quotation}{\Luth} +% {\Title{\de{Von der Freiheit eines Christenmenschen}} (1520)} +% \de{Eyn Chriſten menſch iſt eyn freyer herr / +% u\raise 0.25ex\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.} +% +% (A Christian person is a free lord, above all things, and subject to +% no one. A Christian person is a willing servant of all things and is +% subject to everyone.) % \index{theologians, quotes of\noexpand\string|hyperpage} -% \end{Quote} +% \end{Quotation} +% \end{AltFormatZone} % % \newpage % % \section{Feature Priority} % \label{sec:Priorities} % -% \begin{center} +% \begin{Center} % \begin{tabular}{llll}\toprule % \bfseries Indexing & \bfseries Capitalization & % \bfseries Reversing & \bfseries Name Forms,\\ @@ -3052,65 +3332,57 @@ and version 1.3 or later is part of all distributions of LaTeX version % \cmd{\IndexActive} & \cmd{\AllCapsInactive} & \cmd{\ReverseActive}\\ % \cmd{\IndexInactive} & \cmd{\AllCapsActive} & \cmd{\ReverseInactive}\\[1ex] % -% \rowcolor{black!6!white} -% \cmd{\JustIndex} & \cmd{\CapName} & \cmd{\RevName} & \cmd{\SubvertThis}\\ -% \rowcolor{black!6!white} -% & & & \cmd{\ForceName}\\ -% \rowcolor{black!6!white} -% & & & \cmd{\NoComma}\\[1ex] +% \rowcolor{white!95!black} +% \cmd{\JustIndex} & \cmd{\CapName} & \cmd{\RevName} & \cmd{\NoComma}\\ +% \rowcolor{white!95!black} +% & & & \cmd{\SubvertThis}\\ +% \rowcolor{white!95!black} +% & & & \cmd{\ForceAffix}\\ +% \rowcolor{white!95!black} +% & & & \cmd{\ForceName}\\[1ex] % -% \rowcolor{black!12!white} +% \rowcolor{white!90!black} % \cmd{\SkipIndex} & \cmd{\AccentCapThis} & % \ttfamily\bfseries allrevcomma & \cmd{\KeepName}\\ -% \rowcolor{black!12!white} +% \rowcolor{white!90!black} % & & \cmd{\RevCommaActive} & \cmd{\ForceFN}\\ -% \rowcolor{black!12!white} -% & & \cmd{\RevCommaInactive} & \cmd{\ShowComma}\\[1ex] -% -% \rowcolor{black!18!white} +% \rowcolor{white!90!black} +% & & \cmd{\RevCommaInactive} & \ttfamily\bfseries showcomma\\ +% \rowcolor{white!90!black} +% & & & \cmd{\ShowComma}\\ +% \rowcolor{white!90!black} +% & & & \ttfamily\bfseries nocomma\\[1ex] +% +% \rowcolor{white!85!black} % \cmd{\SeeAlso} & \cmd{\CapThis} & \cmd{\RevComma} & % \cmd{\KeepAffix}\\\bottomrule % \end{tabular} -% \end{center} +% \end{Center} % % Above we see the relative priority of package options and their related 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 have the ability to 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 complex interaction between -% \cmd{\SkipIndex} and \cmd{\JustIndex}. It it is best to use \cmd{\SkipIndex} -% and \cmd{\JustIndex} only before a naming macro that can print to the text. -% \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} +% \item Lighter-colored rows show higher priority. Darker-colored rows show lower priority. Higher-priority options and macros have the ability to 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 complex interaction between \cmd{\SkipIndex} and \cmd{\JustIndex}. It it is best to use \cmd{\SkipIndex} and \cmd{\JustIndex} only before a naming macro that can print to the text. % +% \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. +% +% \item[] 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. +% +% \item[] Also, \cmd{\JustIndex} resets the effects of \cmd{\ForgetThis} and \cmd{\SubvertThis} because those prefix macros (Section~\ref{sec:ListPrefix}) should precede only naming macros that produce output in the text. +% +% \item[] Although \cmd{\JustIndex} does not override the caps and reversing macros and options, it prevents anything related to displaying a name. +% \end{itemize} % \ReturnLink % % \newpage % % \section{Naming Macros} +% \label{sec:NamePedantic} % % 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. % @@ -3118,43 +3390,40 @@ and version 1.3 or later is part of all distributions of LaTeX version % \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, +% \cmd{\Name} displays and indexes names. It prints the full name at the first occurrence, then usually just \meta{SNN} thereafter. % \DescribeMacro{\Name*} -% then usually just the \meta{SNN} argument thereafter. \cmd{\Name*} always prints the full name: +% \cmd{\Name*} always prints the full name: % % \begin{SyntaxBox} -% \cmd{\Name\ }\oarg{FNN}\marg{SNN|,| Affix}\oarg{Alternate}\\ -% \cmd{\Name*}\oarg{FNN}\marg{SNN|,| Affix}\oarg{Alternate} +% \cmd{\Name\ }\oarg{FNN}\marg{SNN\textbf{,}Affix}\oarg{Alternate}\\ +% \cmd{\Name*}\oarg{FNN}\marg{SNN\textbf{,}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} +% In the body text only, 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} % \begin{Verbatim} % \begin{nameauth} % \< Einstein & Albert & Einstein & > % \< Carter & J.E. & Carter, Jr. & > -% \< Confucius & & Confucius & > % \< Miyazaki & & Miyazaki, Hayao & > % \< Eliz & & Elizabeth, I & > +% \< Confucius & & Confucius & > % \end{nameauth} % \end{Verbatim} -% \end{quote} +% \end{Quote} % % \ForgetName[Albert]{Einstein}\ForgetName[J.E.]{Carter, Jr.} -% \begin{center} -% \vspace{3ex} -% \BothInfo{\ShowPattern[Albert]{Einstein}\break +% \begin{Center} +% \BothInfo[2.6ex]{\ShowPattern[Albert]{Einstein}\break % \ShowPattern[J.E.]{Carter, Jr.}\break -% \ShowPattern{Confucius}\break % \ShowPattern{Miyazaki, Hayao}\break -% \ShowPattern{Elizabeth, I}} +% \ShowPattern{Elizabeth, I}\break +% \ShowPattern{Confucius}} % {\ShowIdxPageref*[Albert]{Einstein}\break % \ShowIdxPageref*[J.E.]{Carter, Jr.}\break -% \ShowIdxPageref*{Confucius}\break % \ShowIdxPageref*{Miyazaki, Hayao}\break -% \ShowIdxPageref*{Elizabeth, I}} -% \vspace{-3ex} +% \ShowIdxPageref*{Elizabeth, I}\break +% \ShowIdxPageref*{Confucius}} % \begin{tabular}{ll}\toprule % \rowcolor{nagrey}^^A % \Name [Albert]{Einstein} & |\Name [Albert]{Einstein}| or |\Einstein|\\ @@ -3169,25 +3438,29 @@ and version 1.3 or later is part of all distributions of LaTeX version % \Carter & |\Name [J.E.]{Carter, Jr.}| or |\Carter|\\ % % \rowcolor{nagrey}^^A -% \Confucius & |\Name {Confucius}| or |\Confucius|\\ -% \rowcolor{nagrey}^^A -% \Confucius & |\Name {Confucius}| or |\Confucius|\\ -% % \ForgetThis\Name {Miyazaki, Hayao} & % |\Name {Miyazaki, Hayao}| or |\Miyazaki|\\ +% \rowcolor{nagrey}^^A % \Name*{Miyazaki, Hayao}[Sensei] & |\Name*{Miyazaki, Hayao}[Sensei]|\\ +% \rowcolor{nagrey}^^A % \Name {Miyazaki, Hayao} & |\Name {Miyazaki, Hayao}| or |\Miyazaki|\\ % -% \rowcolor{nagrey}^^A % \ForgetThis\Eliz & |\Name {Elizabeth, I}| or |\Eliz|\\ -% \rowcolor{nagrey}^^A % \Name*{Elizabeth, I} & |\Name*{Elizabeth, I}| or |\LEliz|\\ +% \Name {Elizabeth, I} & |\Name {Elizabeth, I}| or |\Eliz|\\ +% % \rowcolor{nagrey}^^A -% \Name {Elizabeth, I} & |\Name {Elizabeth, I}| or |\Eliz|\\\bottomrule +% \ForgetThis\Confucius & |\Name {Confucius}| or |\Confucius|\\ +% \rowcolor{nagrey}^^A +% \Confucius & |\Name {Confucius}| or |\Confucius|\\\bottomrule % \end{tabular} -% \end{center} -% -% With the quick interface, the best way to get alternate names follows patterns like ``\LCarter[James Earl]'' |\LCarter[James Earl]| and ``\LMiyazaki[Sensei]'' |\LMiyazaki[Sensei]|. The alternate forename is not shown in subsequent short name instances e.g., ``\Carter[James Earl]'' |\Carter[James Earl]|. Thus, one must use either long-name instances or forename instances to see the alternate names. +% \end{Center} +% With the quick interface, the usual way to use alternate names is by appending them in brackets: +% \begin{Block} +% \LCarter[James Earl]\dotfill |\LCarter[James Earl]|\\ +% \LMiyazaki[Sensei]\dotfill |\LMiyazaki[Sensei]| +% \end{Block} +% Otherwise, one can populate the final field in the \texttt{nameauth} environment, with several caveats (Section~\ref{sec:ArgIV}). Alternate names appear only in long name forms or short name forms described in the next section. % % \newpage % @@ -3197,28 +3470,30 @@ and version 1.3 or later is part of all distributions of LaTeX version % \DescribeMacro{\FName} % \cmd{\FName} and its synonym \cmd{\FName*} print personal names only in subsequent name uses. % \DescribeMacro{\FName*} -% That means when a name control sequence does not exist, they print long name forms because it is a first use of a name. +% That means when a name pattern 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. +% 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 approach was implemented before the quick interface was developed. % % \begin{SyntaxBox} -% \cmd{\FName\ }\oarg{FNN}\marg{SNN|,| Affix}\oarg{Alternate}\\ -% \cmd{\FName*}\oarg{FNN}\marg{SNN|,| Affix}\oarg{Alternate} +% \cmd{\FName\ }\oarg{FNN}\marg{SNN\textbf{,}Affix}\oarg{Alternate}\\ +% \cmd{\FName*}\oarg{FNN}\marg{SNN\textbf{,}Affix}\oarg{Alternate} % \end{SyntaxBox} % -% These forename instance macros will permit all name types, but the normal behavior prints forenames only with Western names. With nonwestern names only \meta{SNN} is printed. This is designed to prevent Western writers from causing unintended offense in Eastern contexts. It also prevents the display of nonsense names in the context of ancient and royal names. +% These forename instance 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 unintended offense in Eastern contexts. It also prevents the display of nonsense forms in the context of ancient and royal names. % % \DescribeMacro{\ForceFN} % 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}. -% -% \begin{center} -% \vspace{3ex} -% \PatInfo{\ShowPattern[Albert]{Einstein}\break +% \begin{Center} +% \BothInfo[2.5ex]{\ShowPattern[Albert]{Einstein}\break % \ShowPattern[J.E.]{Carter, Jr.}\break -% \ShowPattern{Confucius}\break % \ShowPattern{Miyazaki, Hayao}\break -% \ShowPattern{Elizabeth, I}} -% \vspace{-3ex} +% \ShowPattern{Elizabeth, I}\break +% \ShowPattern{Confucius}} +% {\ShowIdxPageref*[Albert]{Einstein}\break +% \ShowIdxPageref*[J.E.]{Carter, Jr.}\break +% \ShowIdxPageref*{Miyazaki, Hayao}\break +% \ShowIdxPageref*{Elizabeth, I}\break +% \ShowIdxPageref*{Confucius}} % \begin{tabular}{ll}\toprule % \rowcolor{nagrey}^^A % \SEinstein & |\FName[Albert]{Einstein}| or |\SEinstein|\\ @@ -3227,8 +3502,6 @@ and version 1.3 or later is part of all distributions of LaTeX version % & or |\SCarter[Jimmy]|\\ % % \rowcolor{nagrey}^^A -% \FName{Confucius} & |\FName{Confucius}| or |\SConfucius |\\ -% % \FName{Miyazaki, Hayao} & |\FName{Miyazaki, Hayao}| or |\SMiyazaki|\\ % % \rowcolor{nagrey}^^A @@ -3236,67 +3509,95 @@ and version 1.3 or later is part of all distributions of LaTeX version % \rowcolor{nagrey}^^A % & or |\ForceFN\SMiyazaki|\\ % +% \rowcolor{nagrey}^^A % \ForceFN\FName{Miyazaki, Hayao}[Sensei] & % |\ForceFN\FName{Miyazaki, Hayao}[Sensei]|\\ +% \rowcolor{nagrey}^^A % & or |\ForceFN\SMiyazaki[Sensei]|\\ % -% \rowcolor{nagrey}^^A % \SEliz & |\FName{Elizabeth, I}| or |\SEliz|\\ -% \ForceFN\SEliz[Good Queen Bess] & -% |\ForceFN\SEliz[Good Queen Bess]|\\\bottomrule +% \ForceFN\SEliz[Gloriana] & +% |\ForceFN\FName{Elizabeth, I}[Gloriana]|\\ +% & or |\ForceFN\SEliz[Gloriana]|\\ +% +% \rowcolor{nagrey}^^A +% \FName{Confucius} & |\FName{Confucius}| or |\SConfucius |\\\bottomrule % \end{tabular} -% \end{center} +% \end{Center} % % 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.\negmedskip^^A +% \begin{Quotation}{\Eliz} +% {speech to Parliament, 1586} +% As for me, I see no such great cause why I should either be +% fond to live or fear to die. I have had good experience of this +% world, and I know what it is to be a subject and what to be a +% sovereign. Good neighbors I have had, and I have met with bad; +% and in trust I have found treason. % \index{politicians, quotes of\noexpand\string|hyperpage} -% \end{Quote} +% \end{Quotation} +% +% \newpage % % \subsection{Technical Details} -% \label{sec:TechDetails} % % \subsubsection[Final Optargs]{Final Optional Arguments} % \label{sec:FinalOptargs} % -% Macros that take name arguments (see also Section~\ref{sec:NameArgMacros}) sometimes use a final optional argument. Using these arguments with the current syntax gives: -% -% \begin{center}\IndexInactive\footnotesize +% Macros that take name arguments using the current syntax (see also Section~\ref{sec:NameArgMacros}) can have a final optional argument. We do not index the names below in this manual, but we show how the index entries would appear: +% \begingroup +% \IndexInactive % \renewcommand\NamesFormat{} % \renewcommand\MainNameHook{} -% \begin{tabular}{l@{\ }l@{\ }l}\toprule -% \rowcolor{nagrey}\bfseries Printed Name & -% \bfseries Macro and Arguments & \bfseries Western Index Entry\\ -% \ForgetThis\Name[Person]{Family, Affix}[Alias] & |\Name[Person]{Family, Affix}[Alias]| & -% \ShowIdxPageref*[Person]{Family, Affix}\\ -% \ForgetThis\Name[Person]{Family}[Alias] & |\Name[Person]{Family}[Alias]| & -% \ShowIdxPageref*[Person]{Family}\\ -% \RevName\Name*[Person]{Family}[Alias] & |\RevName%| & -% \ShowIdxPageref*[Person]{Family}\\ -% & |\Name[Person]{Family}[Alias]|\\\midrule -% \rowcolor{nagrey}\bfseries Printed Name & -% \bfseries Macro and Arguments & \bfseries Nonwestern Index Entry\\ -% \ForgetThis\Name{Family, Person}[Alias] & |\Name{Family, Person}[Alias]| & +% \begin{itemize} +% \item Western Index Entries:\smallskip +% +% \begingroup\footnotesize +% \begin{tabular}{p{2.2cm}p{6.13cm}p{2.35cm}}\toprule +% \rowcolor{nagrey}\bfseries Text & +% \bfseries Macro / Arguments & \bfseries Index\\ +% \Name*[First]{Last, Affix}[Alias] & +% |\Name*[First]{Last, Affix}[Alias]| & +% \ShowIdxPageref*[First]{Last, Affix}\\ +% \Name*[First]{Last}[Alias] & +% |\Name*[First]{Last}[Alias]| & +% \ShowIdxPageref*[First]{Last}\\ +% \RevName\Name*[First]{Last}[Alias] & +% |\RevName\Name*[First]{Last}[Alias]| & +% \ShowIdxPageref*[First]{Last}\\\bottomrule +% \end{tabular} +% \endgroup\smallskip +% +% \item Non-Western Index Entries:\smallskip +% +% \begingroup\footnotesize +% \begin{tabular}{p{2.2cm}p{6.13cm}p{2.35cm}}\toprule +% \rowcolor{nagrey}\bfseries Text & +% \bfseries Macro / Arguments & \bfseries Index\\ +% \Name*{Family, Person}[Alias] & +% |\Name*{Family, Person}[Alias]| & % \ShowIdxPageref*{Family, Person}\\ -% \RevName\Name*{Family, Person}[Alias] & |\RevName%| & +% \RevName\Name*{Family, Person}[Alias] & +% |\RevName\Name*{Family, Person}[Alias]| & % \ShowIdxPageref*{Family, Person}\\ -% & |\Name{Family, Person}[Alias]|\\ -% \ForgetThis\Name{Person, Affix}[Alias] & |\Name{Person, Affix}[Alias]| & +% \Name*{Person, Affix}[Alias] & +% |\Name*{Person, Affix}[Alias]| & % \ShowIdxPageref*{Person, Affix}\\\bottomrule -% \end{tabular}\IndexActive -% \end{center} +% \end{tabular} +% \endgroup +% \end{itemize} +% \endgroup % -% Since May 2018, \textsf{xparse} offers two approaches that have their own pros and cons. Below \cmd{\Namei} works the same as \textsf{nameauth}. \cmd{\Nameii} takes the alternate route. If one builds this package with a \LaTeX\ distro from before 2018, \cmd{\Nameii} will not appear, and \cmd{\Namei} will work like \cmd{\Nameii} in newer versions. It was for the sake of stability and consistency that \textsf{nameauth} used \textsf{xargs} and \textsf{suffix} in its early days. Now that all the issues with \textsf{xparse} have been addressed, the latter is the best choice going forward. +% Since May 2018, \textsf{xparse} either can ignore spaces before final optional arguments, or it can see those spaces as significant. Below \cmd{\Namei} ignores these spaces, the default for \textsf{nameauth}. \cmd{\Nameii} sees these spaces as significant.\footnote{Before May 2018, \cmd{\Namei} worked like \cmd{\Nameii} does now. This manual checks for the appropriate changes and mitigates errors. Currently, \textsf{xparse} is just as stable as \textsf{xargs} and \textsf{suffix}.} +% The default advantages of \cmd{\Namei} outweigh those of \cmd{\Nameii}. Section~\ref{sec:FullCustomize} shows how one can change these defaults via advanced customization. There are no ``perfect'' choices, only trade-offs. % -% \begin{quote} +% \begin{Quote} % \begin{Verbatim} % \NewDocumentCommand {\Namei}{O{} m O{}} -% {\def\Opt{#3}\ifx\Opt\empty #1\ #2\else \Opt\ #2\fi} +% {\providecommand\Opt{#3}\ifx\Opt\empty #1\ #2\else \Opt\ #2\fi} % % Cannot use this definition before May 2018. % \NewDocumentCommand{\Nameii}{O{} m !O{}} -% {\def\Opt{#3}\ifx\Opt\empty #1\ #2\else \Opt\ #2\fi} +% {\providecommand\Opt{#3}\ifx\Opt\empty #1\ #2\else \Opt\ #2\fi} % % |\Namei: | \Namei[Person1]{Family1} [something1]\\[1ex] % |\Nameii:| \Nameii[Person2]{Family2} [something2] @@ -3304,134 +3605,207 @@ and version 1.3 or later is part of all distributions of LaTeX version % % \ifdefined\nameauthxp%^^A % \NewDocumentCommand {\Namei}{O{} m O{}} -% {\def\Opt{#3}\ifx\Opt\empty #1\ #2\else \Opt\ #2\fi} +% {\providecommand\Opt{#3}\ifx\Opt\empty #1\ #2\else \Opt\ #2\fi} % \NewDocumentCommand{\Nameii}{O{} m !O{}} -% {\def\Opt{#3}\ifx\Opt\empty #1\ #2\else \Opt\ #2\fi} +% {\providecommand\Opt{#3}\ifx\Opt\empty #1\ #2\else \Opt\ #2\fi} % |\Namei: | \Namei[Person1]{Family1} [something1]\\[1ex] % |\Nameii:| \Nameii[Person2]{Family2} [something2]%^^A % \else % \NewDocumentCommand {\Namei}{O{} m O{}} -% {\def\Opt{#3}\ifx\Opt\empty #1\ #2\else \Opt\ #2\fi} +% {\providecommand\Opt{#3}\ifx\Opt\empty #1\ #2\else \Opt\ #2\fi} % |\Namei: | \Namei[Person1]{Family1} [something1]\\[1ex] % |\Nameii:| (\LaTeX\ too old)%^^A % \fi -% \end{quote} -% +% \end{Quote} % \begin{itemize} -% \item \cmd{\Namei} ignores spaces between the mandatory argument and the final optional argument. +% \item What happens when we ignore these spaces (\cmd{\Namei})? % \begin{itemize} -% \item Subsequent text in brackets will be interpreted as a name argument, even if unintended. -% \item Yet we avoid errors from unintended spaces when using alternate names and the obsolete syntax. +% \item Subsequent text in brackets always becomes a name argument. +% \item We avoid errors arising from unintended spaces. +% \item This follows standard \LaTeX\ behavior. % \end{itemize} % -% \item \cmd{\Nameii} treats spaces between the mandatory argument and the final optional argument as significant. +% \item What happens when these spaces are significant (\cmd{\Nameii})? % \begin{itemize} -% \item Subsequent text in brackets will be seen as a name argument only if no spaces occur between the mandatory argument and final optional argument. -% \item Yet when using alternate names and the obsolete syntax, with unintended spaces we could ``lose'' names from the arguments and see unwanted results in the text. +% \item Spaces that follow the required argument prevent the final optional argument from being seen as such. +% \item Unintended spaces could ``orphan'' final optional arguments. % \end{itemize} % \end{itemize} % -% In the next example we show the default approach of \textsf{nameauth} in practice using the basic name interface. \cmd{\ForgetName} (Section~\ref{sec:NameControl}) lets us simulate first instances of names, even if they have appeared already. +% \newpage % -% \begin{quote} -% \ForgetName[Albert]{Einstein} \ForgetName{Miyazaki, Hayao} +% The default behavior can cause problems when using interpolated text in square brackets following a name. We show this using both name interfaces. We simulate first instances of names (Section~\ref{sec:NameControl}), and we suppress name formatting. +% +% \begingroup % \renewcommand\NamesFormat{} % \renewcommand\MainNameHook{} -% +% \ForgetName[Albert]{Einstein} +% \ForgetName{Miyazaki, Hayao} % \begin{itemize} -% \item[We want:] ``Albert Einstein [then] said''; -% ``Miyazaki Hayao [apparently] said''. -% \item[Also:] ``Einstein [then] said''; -% ``Miyazaki [apparently] said''. -% \item[Macros:] |``\Name[Albert]{Einstein} [then] said'';|\\ -% |``\Name{Miyazaki, Hayao} [apparently] said''.| -% \item[We get:] ``\Name[Albert]{Einstein} [then] said''; -% ``\Name{Miyazaki, Hayao} [apparently] said''. -% \item[Repeat:] ``\Name[Albert]{Einstein} [then] said''; -% ``\Name{Miyazaki, Hayao} [apparently] said''. -% \end{itemize} -% -% \ForgetName[Albert]{Einstein} \ForgetName{Miyazaki, Hayao} -% \begin{itemize} -% \item Add explicit spaces:\\ -% ``\Name[Albert]{Einstein}\ [then] said''; -% ``\Name {Miyazaki, Hayao}\ [apparently] said''.\\ -% |``\Name[Albert]{Einstein}\ [then] said'';|\\ -% |``\Name {Miyazaki, Hayao}\ [apparently] said''.| -% \item Add curly braces:\\ -% ``\Name[Albert]{Einstein}{} [then] said''; -% ``\Name{Miyazaki, Hayao}{} [apparently] said''.\\ -% |``\Name[Albert]{Einstein}{} [then] said'' and|\\ -% |``\Name{Miyazaki, Hayao}{} [apparently] said''.| -% \end{itemize} -% \end{quote} +% \item We expect to see the following text: +% \BothInfo*{\ShowPattern[Albert]{Einstein}\break +% \ShowPattern{Miyazaki, Hayao}} +% {\ShowIdxPageref*[Albert]{Einstein}\break +% \ShowIdxPageref*{Miyazaki, Hayao}} +% \begin{Block}\textls[7]{^^A +% Albert Einstein [first] spoke about physics. +% Miyazaki Hayao [then] spoke about animation. +% Einstein [again] spoke about physics. +% Miyazaki [later] spoke about film.} +% \end{Block} % -% Now we show how the \textsf{nameauth} default argument handling works with the quick naming interface: +% \item We use these macros and get poor results: +% \begin{Verbatim}[numbers=none] +% \Name[Albert]{Einstein} [first] spoke about physics. +% \Name{Miyazaki, Hayao} [then] spoke about animation. +% \Name[Albert]{Einstein} [again] spoke about physics. +% \Name{Miyazaki, Hayao} [later] spoke about film. +% \end{Verbatim} +% \begin{Block}\textls[7]{^^A +% \Name[Albert]{Einstein} [first] spoke about physics. +% \Name{Miyazaki, Hayao} [then] spoke about animation. +% \Name[Albert]{Einstein} [again] spoke about physics. +% \Name{Miyazaki, Hayao} [later] spoke about film.} +% \end{Block} % -% \begin{quote} -% \begin{Verbatim} +% \ForgetName[Albert]{Einstein} +% \ForgetName{Miyazaki, Hayao} +% \item We add explicit spaces or curly braces to get correct results: +% \begin{Verbatim}[numbers=none] +% \Name[Albert]{Einstein}\ [first] spoke about physics. +% \Name{Miyazaki, Hayao}\ [then] spoke about animation. +% \Name[Albert]{Einstein}{} [again] spoke about physics. +% \Name{Miyazaki, Hayao}{} [later] spoke about film. +% \end{Verbatim} +% \begin{Block}\textls[7]{^^A +% \Name[Albert]{Einstein}\ [first] spoke about physics. +% \Name{Miyazaki, Hayao}\ [then] spoke about animation. +% \Name[Albert]{Einstein}{} [again] spoke about physics. +% \Name{Miyazaki, Hayao}{} [later] spoke about film.} +% \end{Block} +% \end{itemize} +% \begin{Quote} +% \begin{Verbatim}[numbers=none] % \begin{nameauth} % \< Einstein & Albert & Einstein & > % \< Miyazaki & & Miyazaki, Hayao & > % \end{nameauth} % \end{Verbatim} -% \end{quote} -% -% \begin{quote} -% \renewcommand\NamesFormat{} -% \renewcommand\MainNameHook{} -% -% \ForgetName[Albert]{Einstein} \ForgetName{Miyazaki, Hayao} +% \end{Quote} +% \ForgetName[Albert]{Einstein} +% \ForgetName{Miyazaki, Hayao} % \begin{itemize} -% \item[We want:] ``Albert Einstein [then] said''; -% ``Miyazaki Hayao [apparently] said''. -% \item[Also:] ``Einstein [then] said''; -% ``Miyazaki [apparently] said''. -% \item[Macros:] |``\Einstein [then] said'';|\\ -% |``\Miyazaki [apparently] said''.| -% \item[We get:] ``\Einstein [then] said''; -% ``\Miyazaki [apparently] said''. -% \item[Repeat:] ``\Einstein [then] said''; -% ``\Miyazaki [apparently] said''. -% \end{itemize} -% -% \ForgetName[Albert]{Einstein} \ForgetName{Miyazaki, Hayao} -% \begin{itemize} -% \item Add explicit spaces:\\ -% ``\Einstein\ [then] said''; -% ``\Miyazaki\ [apparently] said''.\\ -% |``\Einstein\ [then] said'' and|\\ -% |``\Miyazaki\ [apparently] said''.| -% \item Add curly braces:\\ -% ``\Einstein{} [then] said''; -% ``\Miyazaki{} [apparently] said''.\\ -% |``\Einstein{} [then] said'' and|\\ -% |``\Miyazaki{} [apparently] said''.| +% \item We expect to see the same text as above. +% +% \item We use these macros and get poor results: +% \begin{Verbatim}[numbers=none] +% \Einstein [first] spoke about physics. +% \Miyazaki [then] spoke about animation. +% \Einstein [again] spoke about physics. +% \Miyazaki [later] spoke about film. +% \end{Verbatim} +% \begin{Block}\textls[7]{^^A +% \Einstein [first] spoke about physics. +% \Miyazaki [then] spoke about animation. +% \Einstein [again] spoke about physics. +% \Miyazaki [later] spoke about film.} +% \end{Block} +% +% \ForgetName[Albert]{Einstein} +% \ForgetName{Miyazaki, Hayao} +% \item We add explicit spaces or curly braces to get correct results: +% \begin{Verbatim}[numbers=none] +% \Einstein\ [first] spoke about physics. +% \Miyazaki\ [then] spoke about animation. +% \Einstein{} [again] spoke about physics. +% \Miyazaki{} [later] spoke about film. +% \end{Verbatim} +% \begin{Block}\textls[7]{^^A +% \Einstein\ [first] spoke about physics. +% \Miyazaki\ [then] spoke about animation. +% \Einstein{} [again] spoke about physics. +% \Miyazaki{} [later] spoke about film.} +% \end{Block} % \end{itemize} -% \end{quote} +% \endgroup % -% Section~\ref{sec:ChangeParse} shows how one can customize and change argument handling, addressing some of the same issues and caveats illustrated above. +% \subsubsection[Affixes]{Affixes Need Commas} +% \label{sec:Affix} % -% \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.\negmedskip^^A -% \index{creatives, quotes of\noexpand\string|hyperpage} -% \end{Quote} +% A comma is not a required name element unless used in an \meta{SNN\textbf{,}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. % -% \newpage +% When a comma appears in a required name argument, each member of the \meta{SNN\textbf{,}Affix} pair is treated as a separate argument. Thus, we say that the comma delimits or segments the name argument. Spaces around the comma are ignored. See Section~\ref{sec:Noexpand} for more information when using macros in name arguments. +% \begin{InfoBox} +% Regarding an \meta{SNN\textbf{,}Affix} pair, avoid error by applying macros to \meta{SNN} and \meta{Affix} as if they were independent arguments. +% \end{InfoBox} % -% \subsubsection[Name Arg Caveats]{Name Argument Caveats} +% \begin{Center} +% \BothInfo[2ex]{\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}} +% \ForgetName{Sun, Yat-sen} +% \begin{tabular}{ll}\toprule +% \rowcolor{nagrey}^^A +% \bfseries Text & \bfseries Macro / Arguments\\ +% \Name[Oskar]{Hammerstein, II} & |\Name[Oskar]{Hammerstein, II}|\\ +% \Name[Oskar]{Hammerstein, II} & |\Name[Oskar]{Hammerstein, II}|\\ +% +% \rowcolor{nagrey}^^A +% \ForgetThis\Name{Louis, XIV} & |\Name{Louis, XIV}|\\ +% \rowcolor{nagrey}^^A +% \Name{Louis, XIV} & |\Name{Louis, XIV}|\\ +% +% \Name{Sun, Yat-sen} & |\Name{Sun, Yat-sen}|\\ +% \Name{Sun, Yat-sen} & |\Name{Sun, Yat-sen}|\\\bottomrule +% \end{tabular} +% \end{Center} +% +% \BothInfo[1.2ex]{\ShowPattern[Oskar]{Hammerstein}[II]} +% {\ShowIdxPageref*[Oskar]{Hammerstein}[II]} +% Western names with affixes must use \meta{SNN\textbf{,}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]}. +% +% \DescribeMacro{\KeepAffix} +% 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. +% +% \DescribeMacro{\DropAffix}\leavevmode +% If \cmd{\DropAffix} precedes only a Western name, it will suppress the affix after the surname in a first or long instance. We get ``\DropAffix\Name*[Oskar]{Hammerstein, II}'' From |\DropAffix\Name*[Oskar]{Hammerstein, II}|. +% +% With Non-Western names, the \meta{Affix} in the \meta{SNN\textbf{,}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}. +% +% \Info*{\small\cmd{\ForceAffix}} Since the macro \cmd{\ForceAffix}, which prints only the affix of subsequent-use Western names, has such a narrow intended use, we cover it in Section~\ref{sec:RomanGeneral}. +% +% \DescribeMacro{\ShowComma} +% In a long name form, \cmd{\ShowComma} forces the display of a comma between a Western name and its affix. +% \DescribeMacro{\NoComma} +% 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. +% \medskip +% +% \BothInfo[2.5ex]{\ShowPattern[George S.]{Patton, Jr.}} +% {\ShowIdxPageref*[George S.]{Patton, Jr.}} +% \begin{tabular}{@{}lll} +% With comma: & \ShowComma\LPatton & |\ShowComma\LPatton|\\[1ex] +% No comma: & \NoComma\LPatton & |\NoComma\LPatton|\\ +% \end{tabular} +% \medskip +% +% 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{Trimming Spaces} % % To get consistent index entries, all \textsf{nameauth} macros that take name arguments trim extra spaces around each name argument, shown in gray below: -% \begin{quote} -% \def\gbox{\colorbox{nagrey}{\strut\quad\strut}} +% \begin{Quote} +% \newcommand\gbox{\colorbox{nagrey}{\strut\ \ \strut}} +% \bfseries % \cmd{\Name}\texttt{[}\gbox\meta{\color{nared}FNN}\gbox\texttt{]}^^A % \texttt{\{}\gbox\meta{SNN}\gbox\texttt{\color{nared},}\gbox^^A % \meta{\color{nared}Affix}\gbox\texttt{\}}^^A % \texttt{[}\gbox\meta{\color{nared}Alternate}\gbox\texttt{]} -% \end{quote} +% \end{Quote} % We show this in practice while suppressing name formatting: -% +% ^^A % \begin{VerbatimOut}{\jobname.tmp} % No spaces:\\ % \fbox{\strut\Name*[Martin Luther]{King,Jr.}} @@ -3443,27 +3817,24 @@ and version 1.3 or later is part of all distributions of LaTeX version % \fbox{\strut\Name [ Martin Luther ]{ King , Jr. }} % \fbox{\strut\FName[ Martin Luther ]{ King , Jr. }} % \end{VerbatimOut} -% -% \begin{quote} +%^^A +% \begin{Quote} % \VerbatimInput[gobble=0]{\jobname.tmp} % \renewcommand*\NamesFormat{} % \renewcommand*\MainNameHook{} % -% \vspace{3ex} -% \BothInfo{\ShowPattern[Martin Luther]{King, Jr.}\break +% \BothInfo[3ex]{\ShowPattern[Martin Luther]{King, Jr.}\break % \ShowPattern[ Martin Luther ]{ King , Jr. }} % {\ShowIdxPageref*[Martin Luther]{King, Jr.}\break % \ShowIdxPageref*[ Martin Luther ]{ King , Jr. }} -% \vspace{-3ex} % \input{\jobname.tmp} -% \end{quote} +% \end{Quote} % % We resume name formatting to show names that look the same, but are different. Non-breaking spaces, explicit spaces, thin spaces, and macros that expand to spaces \emph{are not trimmed}. They produce different name patterns, shown below: -% -% \begin{center}\IndexInactive +% \begin{Center}\IndexInactive % \begin{tabular}{lll}\toprule % \rowcolor{nagrey}^^A -% \bfseries Output & \bfseries Macro & \bfseries Name Pattern\\ +% \bfseries Text & \bfseries Macro / Arguments & \bfseries Name Pattern\\ % % \Name{foo~bar} & |\Name{foo~bar}| & \ttfamily\ShowPattern{foo~bar} \\ % @@ -3473,485 +3844,785 @@ and version 1.3 or later is part of all distributions of LaTeX version % \Name{foo\space bar} & |\Name{foo\space bar}| & % \ttfamily\ShowPattern{foo\space bar} \\\bottomrule % \end{tabular}\IndexActive -% \end{center} +% \end{Center} % -% Name patterns, not name appearance, determine if names are the same (Section~\ref{sec:NamePatterns}). There may be cases where one might leverage that point. +% For more on uniqueness, see Sections~\ref{sec:NamePatterns} and~\ref{sec:Unique}. Names with macros in their arguments must be sorted with \cmd{\PretagName} (Section~\ref{sec:IndexSort}). % -% \subsubsection{Full Stop Detection} +% \subsubsection{Formatting Initials} +% +% 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 does little good. If a style guide requires spaces, try thin spaces and sorting as below: +% +% \begin{Block} +% \BothInfo[3.5ex]{\ShowPattern[E.\,B.]{White}} +% {\ShowIdxPageref*[E.\,B.]{White}} +% \begin{Verbatim} +% \PretagName[E.\,B.]{White}{White, Elwyn} +% \begin{nameauth} +% \< White & E.\,B. & White & > +% \end{nameauth} +% \end{Verbatim} +% +% \large +% \renewcommand*\NamesFormat{} +% \renewcommand*\MainNameHook{} +% \begin{tabular}{ll} +% Thin spaces & +% \vrule width 1pt\LWhite[E.\vrule width 1pt\,\vrule width 1ptB.\vrule width 1pt\ \vrule width 1pt]\vrule width 1pt\\\hline +% Normal spaces & +% \vrule width 1pt\LWhite[E.\vrule width 1pt\ \vrule width 1ptB.\vrule width 1pt\ \vrule width 1pt]\vrule width 1pt\\ +% \end{tabular} +% \end{Block} +% +% We used \cmd{\PretagName} to sort this name as: ``White, Elwyn'' to ensure that his index entry is sorted properly. (Section~\ref{sec:IndexInitials}). % -% Western names tend to use full stops in various cases, including the following: +% \subsubsection{Name Breakpoints} % +% \DescribeMacro{\KeepName} +% In longer name forms, \cmd{\KeepName} turns spaces \emph{between} all visible name elements into non-breaking spaces. This macro does not alter spaces \emph{within} name elements with multiple names, such as French and German forenames, as well as Spanish surnames. \cmd{\KeepName} works with all name types. +% \BothInfo[5ex]{\ShowPattern[Sandra Day]{O'Connor}} +% {\ShowIdxPageref*[Sandra Day]{O'Connor}} % \begin{itemize} -% \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. +% \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} % -% If name contains a full stop at the end, followed by a full stop in the text. the \textsf{nameauth} macros try to prevent two adjacent full stops. All macros that take name arguments and print names in the text check if the printed name ends with a full stop. They also check the lookahead token for a full stop. If both cases are true, they gobble the lookahead token. +% \subsubsection{Full Stop Detection} % -% \newpage +% Names may use full stops in some cases, including the following: +% \begin{itemize} +% \item When forenames are abbreviated as initials: \LJRIV\ is \SJRIV. +% \BothInfo{\ShowPattern[George S.]{Patton, Jr.}\break +% \ShowPattern[J.D.]{Rockefeller, IV}\break +% \ShowPattern[Marcus]{Welby,M.D.}} +% {\ShowIdxPageref*[George S.]{Patton, Jr.}\break +% \ShowIdxPageref*[J.D.]{Rockefeller, IV}\break +% \ShowIdxPageref*[Marcus]{Welby,M.D.}} % -% We show this behavior in the example below. \cmd{\ForgetName} (Section~\ref{sec:NameControl}) lets us simulate the first instances of names. The table tells us whether or not the full stop on the lookahead token is gobbled, why that is the case, as well as the output of the name in the text and its correlating source. +% \item After affixes: ``Jr''. (junior), ``Sr''. (senior), ``d.\,Ä.'' (\DE{der Ältere}), ``d.\,J.'' (\DE{der Jüngere}) etc.: \LPatton. % -% \begin{quote} +% \item In some contexts, after degrees like ``M.D.'' (\LA{Medicinae Doctor}), J.D. (\LA{Juris Doctor}), Ph.D. (\LA{Philosophiae Doctor}), etc.: \Name[Marcus]{Welby,M.D.}. +% \end{itemize} +% +% The printed names above end with a full stop, and a full stop follows them in the text. The \textsf{nameauth} macros that print names in the text check if the name ends with a full stop. If that is true, and if the lookahead token contains a full stop, they gobble the lookahead token. Below we see how this works in greater detail: +% \begin{Quote} % \begin{Verbatim} % \begin{nameauth} % \< MLK & Martin Luther & King, Jr. & > % \end{nameauth} % \end{Verbatim} -% \end{quote} +% \end{Quote} +% \negbigskip % % \ForgetName[Martin Luther]{King, Jr.} +% \BothInfo[5.5ex]{\ShowPattern[Martin Luther]{King, Jr.}} +% {\ShowIdxPageref*[Martin Luther]{King, Jr.}} +% \begin{itemize}[leftmargin=3cm]\small +% \item[Full stop gobbled:] First use of a name; the last name element has a full stop and is followed by one: +% \Name[Martin Luther]{King, Jr.}.\\ +% |\Name[Martin Luther]{King, Jr.}.| or |\MLK.| +% +% \item[Full stop gobbled:] Long use of a name; the last name element has a full stop and is followed by one: +% \LMLK.\\ +% |\Name*[Martin Luther]{King, Jr.}.| or |\LMLK.| +% +% \item[Full stop gobbled:] Using \meta{alternate} with long Western names will not affect the last element: +% \LMLK[Dr. M.L.].\\ +% |\Name*[Martin Luther]{King, Jr.}[Dr. M.L.].|\\ +% or |\LMLK[Dr. M.L.].| +% +% \item[Full stop gobbled:] Using \meta{alternate} with short Western names will affect the last element: +% \SMLK[Dr. M.L.].\\ +% |\FName[Martin Luther]{King, Jr.}[Dr. M.L.].|\\ +% or |\SMLK[Dr. M.L.].| +% +% \item[Full stop remains:] Affix drops in subsequent uses: +% \MLK.\\ +% |\Name[Martin Luther]{King, Jr.}.| or |\MLK.| +% +% \item[Full stop remains:] Affix forced to drop in first or long uses: +% \DropAffix\LMLK.\\ +% |\DropAffix\Name*[Martin Luther]{King, Jr.}.|\\ +% or |\DropAffix\LMLK.| +% \end{itemize} % -% \begin{center} +% Curly braces can defeat full stop detection and create a new, unique name (Section~\ref{sec:Unique}), similar to using spaces between a name and a full stop: +% \ExcludeName[Martin Luther]{King, {Jr.}} +% \ExcludeName[Martin Luther]{King, {Jr}.} +% +% \BothInfo[5ex]{\ShowPattern[Martin Luther]{King, Jr.}\break +% \ShowPattern[Martin Luther]{King, {Jr.}}\break +% \ShowPattern[Martin Luther]{King, {Jr}.}} +% {\ShowIdxPageref*[Martin Luther]{King, Jr.}\break +% \ShowIdxPageref*[Martin Luther]{King, {Jr.}}\break +% \ShowIdxPageref*[Martin Luther]{King, {Jr}.}} +% \begin{itemize}[leftmargin=3cm]\small +% \item[Full stop remains:] The whole name is within a group, but the full stop is outside of the group: +% {\Name*[Martin Luther]{King, Jr.}}.\\ +% |{\Name*[Martin Luther]{King, Jr.}}.| or |{\LMLK}.| +% +% \item[Full stop gobbled:] Both name and full stop are in the group: +% {\LMLK.}\\ +% |{\Name*[Martin Luther]{King, Jr.}.}| or |{\LMLK.}| +% +% \item[Full stop remains:] Grouping tokens in \meta{Affix} create a new name, break full stop detection (full stop in group): +% \Name*[Martin Luther]{King, {Jr.}}.\\ +% |\Name*[Martin Luther]{King, {Jr.}}.| +% +% \item[Full stop gobbled:] Grouping tokens in \meta{Affix} create a new name, do not break detection (full stop outside of group): +% \Name*[Martin Luther]{King, {Jr}.}.\\ +% |\Name*[Martin Luther]{King, {Jr}.}.| +% +% \item[Full stop remains:] There is intervening space between the name and the full stop: +% \Name*[Martin Luther]{King, Jr.} .\\ +% |\Name*[Martin Luther]{King, Jr.} .| +% +% \item[Full stop gobbled:] Shorthands ignore spaces after them: +% \LMLK .\\ +% |\LMLK .| +% +% \item[Full stop remains:] Shorthands with optional arguments do not ignore intervening space: +% \LMLK[Dr. M.L.] .\\ +% |\LMLK[Dr. M.L.] .| +% \end{itemize} +% +% It is rare to see initials in Eastern names or ancient names. Nevertheless, if one had a Non-Western name form that terminated with a full stop, similar rules would apply. We demonstrate this below, but do not index the names: +% \IndexInactive +% \begin{itemize}[leftmargin=3cm]\small +% \item[Full stop gobbled:] First use of a name; the last name element has a full stop and is followed by one: +% \Name{Full, Stop.}.\\ +% |\Name{Full, Stop.}.| +% +% \item[Full stop gobbled:] Long use of a name; the last name element has a full stop and is followed by one: +% \Name*{Full, Stop.}.\\ +% |\Name*{Full, Stop.}.| +% +% \item[Full stop gobbled:] Using \meta{alternate} with long Non-Western names will affect the last element: +% \Name*{Full, Non-Stop}[Cessation.].\\ +% |\Name*{Full, Non-Stop}[Cessation.].| +% \end{itemize} +% \IndexActive +% +% In the other cases for Non-Western names, the full stop would not be gobbled because it would not terminate the displayed name. +% +% \begin{Quotation}{\MLK[Dr. Martin Luther]} +% {\Title{Stride Towards Freedom} (1958)} +% 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. +% \IndexName{Jesus, Christ} +% \index{civil rights leaders, quotes of\noexpand\string|hyperpage} +% \index{theologians, quotes of\noexpand\string|hyperpage} +% \end{Quotation} +% +% \subsubsection[Macros in Name Args]{Macros in Name Arguments} +% +% As we discuss specialized topics like language-specific needs and advanced formatting, we will encounter macros in name arguments with greater frequency. It would be good to get some general tips on how to handle such macros. +% +% \begin{itemize} +% \item Missing square brackets or curly braces can cause errors like ``\texttt{Paragraph ended}'' and ``\texttt{Missing} \meta{grouping token} \texttt{inserted.}'' +% +% \item Alternate formatting (Section~\ref{sec:AltFormat}) helps to avoid potential problems, e.g., when using \cmd{\CapThis}. +% +% \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}. \Title{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}. +% +% \item Below we show general aspects of scoping to apply them to this package: +%^^A +% \begin{VerbatimOut}{\jobname.tmp} +% \newif\ifCondA +% \newcommand\MacroA{} +% \begingroup +% \newif\ifCondB +% \global\newif\ifCondC +% \global\newcommand\MacroB{} +% \newcommand\MacroC{\def\MacroD{}} +% \global\MacroC +% \global\CondAtrue +% \endgroup +% +% \begin{itemize}[rightmargin=0pt] +% \item \ifdefined\CondAtrue +% \texttt{\textbackslash ifCondA} is defined globally.\else +% \texttt{\textbackslash ifCondA} is not defined.\fi +% +% \item \ifdefined\MacroA +% \cmd{\MacroA} is defined globally.\else +% \cmd{\MacroA} is not defined.\fi +% +% \item \ifdefined\CondBtrue +% \texttt{\textbackslash ifCondB} is defined globally.\else +% \texttt{\textbackslash ifCondB} is defined locally.\fi +% +% \item \ifdefined\CondCtrue +% \texttt{\textbackslash ifCondC} is defined globally. \else +% \texttt{\textbackslash ifCondC} is defined locally. \fi +% No \cmd{\global}\cmd{\newif} allowed. +% +% \item \ifdefined\MacroB \cmd{\MacroB} is defined globally. \else +% \cmd{\MacroB} is defined locally. \fi +% No \cmd{\global}\cmd{\newcommand} allowed. +% +% \item \ifdefined\MacroC \cmd{\MacroC} is defined globally.\else +% \cmd{\MacroC} is defined locally.\fi +% +% \item \ifdefined\MacroD \cmd{\MacroD} is defined globally. \else +% \cmd{\MacroD} is defined locally. \fi +% The \cmd{\global} before \cmd{\MacroB} affects the \cmd{\def} inside \cmd{\MacroC}. +% +% \item \ifCondA \texttt{\textbackslash ifCondA} is true due +% to \cmd{\global}. \else +% \texttt{\textbackslash ifCondA} is false. \fi +% Global assignment works, not global instantiation. +% \end{itemize} +% \end{VerbatimOut} +%^^A +% \begin{Quote} +% \VerbatimInput[gobble=0,lastline=10]{\jobname.tmp} +% +% \input{\jobname.tmp} +% \end{Quote} +% \end{itemize} +% +% \begin{InfoBox} +% Any macro that is used in the argument of a naming macro must be defined in all scopes in which that name is used. The name patterns themselves are global, but macros in name arguments are not guaranteed to be so. +% \end{InfoBox} +% +% \newpage +% +% \subsubsection[Unicode, General]{Active Unicode Characters} +% \label{sec:Unicode} +% +% Both \texttt{xelatex} and \texttt{lualatex} support Unicode natively. Using the \textsf{fontenc} package with the \texttt{T1} option allows \texttt{latex} and \texttt{pdflatex} to use many Unicode characters via active characters that ``secretly'' invoke macros. Use \cmd{\PretagName} to sort names with these characters (Section~\ref{sec:IndexSort}). +% +% Below we group characters that are supported in \texttt{pdflatex} without additional modification by accents and diacritical marks. We align similar letters, so that one gets a better idea of what letters take what accents. +% +% \newcommand\SP[1]{\phantom{#1}} +% \newcommand\Cell[1]{\hbox to 1.1em {\hfil#1\hfil}} +% \begin{center}\large % \begin{tabular}{ll}\toprule % \rowcolor{nagrey}^^A -% \bfseries Full Stop Gobbled & \bfseries Long Name Form, First Use\\ -% Dr. \Name[Martin Luther]{King, Jr.}. & -% |Dr. \Name[Martin Luther]{King, Jr.}.| \\ +% \bfseries Capitals & \strut\\ % -% \rowcolor{nagrey}^^A -% \bfseries Full Stop Gobbled & \bfseries Force Long Name Form \\ -% Dr. \Name*[Martin Luther]{King, Jr.}. & -% |Dr. \Name*[Martin Luther]{King, Jr.}.| \\ -% Dr. \LMLK. & -% |Dr. \LMLK.| \\ +% acute & \Cell{Á}\Cell{Ć}\Cell{ }\Cell{É}\Cell{Ǵ}\Cell{H}\Cell{Í}^^A +% \Cell{J}\Cell{K}\Cell{Ĺ}\Cell{Ń}\Cell{Ó}\Cell{Ŕ}\Cell{Ś}^^A +% \Cell{ }\Cell{Ú}\Cell{ }\Cell{Ý}\Cell{Ź}\strut\\ % % \rowcolor{nagrey}^^A -% \bfseries Full Stop Gobbled & \bfseries Alternate FNN with Initials \\ -% \FName[Martin Luther]{King, Jr.}[M.L.]. & -% |\FName[Martin Luther]{King, Jr.}[M.L.].| \\ -% \SMLK[M.L.]. & -% |\SMLK[M.L.].| \\ +% grave & \Cell{À}\Cell{ }\Cell{ }\Cell{È}\Cell{ }\Cell{ }\Cell{Ì}^^A +% \Cell{ }\Cell{ }\Cell{ }\Cell{ }\Cell{Ò}\Cell{ }\Cell{ }^^A +% \Cell{ }\Cell{Ù}\Cell{ }\Cell{ }\Cell{ }\strut\\ % -% \rowcolor{nagrey}^^A -% \bfseries Full Stop Remains & \bfseries Affix Auto-Drops \\ -% Dr. \Name[Martin Luther]{King, Jr.}. & -% |Dr. \Name[Martin Luther]{King, Jr.}.| \\ +% circumflex & \Cell{Â}\Cell{Ĉ}\Cell{ }\Cell{Ê}\Cell{Ĝ}\Cell{Ĥ}\Cell{Î}^^A +% \Cell{Ĵ}\Cell{ }\Cell{ }\Cell{ }\Cell{Ô}\Cell{ }\Cell{Ŝ}^^A +% \Cell{ }\Cell{Û}\Cell{Ŵ}\Cell{Ŷ}\Cell{ }\strut\\ % % \rowcolor{nagrey}^^A -% \bfseries Full Stop Remains & \bfseries Force Affix to Drop \\ -% \DropAffix\Name*[Martin Luther]{King, Jr.}. & -% |\DropAffix\Name*[Martin Luther]{King, Jr.}.| \\ -% \DropAffix \LMLK. & -% |\DropAffix \LMLK.| \\\bottomrule -% \end{tabular} -% \end{center} -% -% \subsubsection[Grouping, Spaces]{Grouping and Spaces} -% \label{sec:GroupSpace} +% tilde & \Cell{Ã}\Cell{ }\Cell{ }\Cell{ }\Cell{ }\Cell{ }\Cell{Ĩ}^^A +% \Cell{ }\Cell{ }\Cell{ }\Cell{Ñ}\Cell{Õ}\Cell{ }\Cell{ }^^A +% \Cell{ }\Cell{Ũ}\Cell{ }\Cell{ }\Cell{ }\strut\\ % -% 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: +% diaeresis\footnotemark +% & \Cell{Ä}\Cell{ }\Cell{ }\Cell{Ë}\Cell{ }\Cell{ }\Cell{Ï}^^A +% \Cell{ }\Cell{ }\Cell{ }\Cell{ }\Cell{Ö}\Cell{ }\Cell{ }^^A +% \Cell{ }\Cell{Ü}\Cell{ }\Cell{Ÿ}\Cell{ }\strut\\ % -% \IndexInactive -% \begin{center} -% \begin{tabular}{lllll}\toprule % \rowcolor{nagrey}^^A -% & \bfseries Macro & \bfseries Result & \bfseries Name Pattern & \bfseries Type\\ +% cedilla & \Cell{ }\Cell{Ç}\Cell{ }\Cell{ }\Cell{Ģ}\Cell{ }\Cell{ }^^A +% \Cell{ }\Cell{Ķ}\Cell{Ļ}\Cell{Ņ}\Cell{ }\Cell{Ŗ}\Cell{Ş}^^A +% \Cell{Ţ}\Cell{ }\Cell{ }\Cell{ }\Cell{ }\strut\\ % -% 1 & |\Name[one]{two}| & \Name[one]{two} & -% \ttfamily\ShowPattern[one]{two} & Western\\ +% macron & \Cell{Ā}\Cell{ }\Cell{ }\Cell{Ē}\Cell{Ḡ}\Cell{ }\Cell{Ī}^^A +% \Cell{ }\Cell{ }\Cell{ }\Cell{ }\Cell{Ō}\Cell{ }\Cell{ }^^A +% \Cell{ }\Cell{Ū}\Cell{Ǣ}\Cell{Ȳ}\Cell{ }\strut\\ % % \rowcolor{nagrey}^^A -% 2 & |\Name[{one}]{{t}w{o}}| & \Name[{one}]{{t}w{o}} & -% \ttfamily\ShowPattern[{one}]{{t}w{o}} & Western\\ +% breve & \Cell{Ă}\Cell{ }\Cell{ }\Cell{ }\Cell{Ğ}\Cell{ }\Cell{Ĭ}^^A +% \Cell{ }\Cell{ }\Cell{ }\Cell{ }\Cell{Ŏ}\Cell{ }\Cell{ }^^A +% \Cell{ }\Cell{Ŭ}\Cell{ }\Cell{ }\Cell{ }\strut\\ % -% 3 & |\Name{{one}, two}| & \Name{{one}, two} & -% \ttfamily\ShowPattern{{one}, two} & nonwestern\\ +% dot/dotless & \Cell{Ḃ}\Cell{Ċ}\Cell{ }\Cell{Ė}\Cell{Ġ}\Cell{ }\Cell{İ}^^A +% \Cell{ }\Cell{ }\Cell{ }\Cell{ }\Cell{ }\Cell{ }\Cell{ }^^A +% \Cell{ }\Cell{ }\Cell{ }\Cell{ }\Cell{Ż}\strut\\ % % \rowcolor{nagrey}^^A -% 4 & |\Name{{one}, {two}}| & \Name{{one}, {two}} & -% \ttfamily\ShowPattern{{one}, {two}} & nonwestern\\ +% ogonek & \Cell{Ą}\Cell{ }\Cell{ }\Cell{Ę}\Cell{ }\Cell{ }\Cell{Į}^^A +% \Cell{ }\Cell{ }\Cell{ }\Cell{ }\Cell{Ǫ}\Cell{ }\Cell{ }^^A +% \Cell{ }\Cell{Ų}\Cell{ }\Cell{ }\Cell{ }\strut\\ % -% 5 & |\Name{{one, two}}| & \Name{{one, two}} & -% \ttfamily\ShowPattern{{one, two}} & abnormal\\\bottomrule +% caron & \Cell{Ǎ}\Cell{Č}\Cell{Ď}\Cell{Ě}\Cell{Ǧ}\Cell{ }\Cell{Ǐ}^^A +% \Cell{ }\Cell{Ǩ}\Cell{Ľ}\Cell{Ň}\Cell{Ǒ}\Cell{Ř}\Cell{Š}^^A +% \Cell{Ť}\Cell{Ǔ}\Cell{ }\Cell{ }\Cell{Ž}\strut\\ +% +% \rowcolor{nagrey}^^A +% various & \Cell{Å}\Cell{Æ}\Cell{Ð}(eth)\Cell{Đ}(D stroke)\Cell{IJ}^^A +% \Cell{Ł}\Cell{Ŋ}\Cell{Ø}\Cell{Œ}\Cell{Ő}\Cell{Ů}\Cell{Ű}^^A +% \Cell{Ș}\Cell{Ț}\Cell{Þ}\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} % -% These names have different patterns and different index entries, even if they look similar in the text (Sections~\ref{sec:NamePatterns}, \ref{sec:IndexSort}). Similar issues pertain to grouping used with alternate formatting (Section~\ref{sec:AltFormat}). Consistency is key. -% -% The grouping used in name~5 creates an abnormality . Here we illustrate that with the output of \cmd{\ShowNameInfo} (Section~\ref{sec:DebuggingMacros}). Normally, the comma should delimit or segment the argument into two names: -% -% \begin{quote} -% |\Name{one, two} | \ShowNameInfo{one, two}\\ -% |\Name{{one, two}}| \ShowNameInfo{{one, two}} -% \end{quote} -% \IndexActive -% -% Curly braces can change the lookahead token and defeat punctuation detection (as well as create a new, unique name). Using spaces between a name and a full stop can have a similar effect. The next table shows us several actions that allow or inhibit full stop detection. We se ethe results of each action, the action taken, and both output and source related to that action. -% -% \begin{center} +% \begin{center}\large % \begin{tabular}{ll}\toprule % \rowcolor{nagrey}^^A -% \bfseries Full Stop Remains & \bfseries Not Contained in Group \\ -% Dr. {\Name*[Martin Luther]{King, Jr.}}. & -% |Dr. {\Name*[Martin Luther]{King, Jr.}}.| \\ -% Dr. {\LMLK}. & -% |Dr. {\LMLK}.| \\ +% \bfseries Lowercase & \strut\\ % -% \rowcolor{nagrey}^^A -% \bfseries Full Stop Gobbled & \bfseries Contained in Group \\ -% Dr. {\Name*[Martin Luther]{King, Jr.}.} & -% |Dr. {\Name*[Martin Luther]{King, Jr.}.}| \\ -% Dr. {\LMLK.} & -% |Dr. {\LMLK.}| \\ +% acute & \Cell{á}\Cell{ć}\Cell{ }\Cell{é}\Cell{ǵ}\Cell{ }\Cell{í}^^A +% \Cell{ }\Cell{ }\Cell{ĺ}\Cell{ń}\Cell{ó}\Cell{ŕ}\Cell{ś}^^A +% \Cell{ }\Cell{ú}\Cell{ }\Cell{ý}\Cell{ź}\strut\\ % % \rowcolor{nagrey}^^A -% \bfseries Full Stop Remains & \bfseries Grouped in Affix; New Name \\ -% Dr. \SkipIndex\Name*[Martin Luther]{King, {Jr.}}. & -% |Dr. \Name*[Martin Luther]{King, {Jr.}}.| \\ +% grave & \Cell{à}\Cell{ }\Cell{ }\Cell{è}\Cell{ }\Cell{ }\Cell{ì}^^A +% \Cell{ }\Cell{ }\Cell{ }\Cell{ }\Cell{ò}\Cell{ }\Cell{ }^^A +% \Cell{ }\Cell{ù}\Cell{ }\Cell{ }\Cell{ }\strut\\ +% +% circumflex & \Cell{â}\Cell{ĉ}\Cell{ }\Cell{ê}\Cell{ĝ}\Cell{ĥ}\Cell{î}^^A +% \Cell{ĵ}\Cell{ }\Cell{ }\Cell{ }\Cell{ô}\Cell{ }\Cell{ŝ}^^A +% \Cell{ }\Cell{û}\Cell{ŵ}\Cell{ŷ}\Cell{ } \strut\\ % % \rowcolor{nagrey}^^A -% \bfseries Full Stop Gobbled & \bfseries Not Grouped in Affix; New Name \\ -% Dr. \SkipIndex\Name*[Martin Luther]{King, {Jr}.}. & -% |Dr. \Name*[Martin Luther]{King, {Jr}.}.| \\ +% tilde & \Cell{ã}\Cell{ }\Cell{ }\Cell{ }\Cell{ }\Cell{ }\Cell{ĩ}^^A +% \Cell{ }\Cell{ }\Cell{ }\Cell{ñ}\Cell{õ}\Cell{ }\Cell{ }^^A +% \Cell{ }\Cell{ũ}\Cell{ }\Cell{ }\Cell{ }\strut\\ +% +% diaeresis & \Cell{ä}\Cell{ }\Cell{ }\Cell{ë}\Cell{ }\Cell{ }\Cell{ï}^^A +% \Cell{ }\Cell{ }\Cell{ }\Cell{ }\Cell{ö}\Cell{ }\Cell{ }^^A +% \Cell{ }\Cell{ü}\Cell{ }\Cell{ÿ}\Cell{ }\strut\\ % % \rowcolor{nagrey}^^A -% \bfseries Full Stop Remains & \bfseries Intervening Space \\ -% Dr. \Name*[Martin Luther]{King, Jr.} . & -% |Dr. \Name*[Martin Luther]{King, Jr.} .| \\ +% cedilla & \Cell{ }\Cell{ç}\Cell{ }\Cell{ }\Cell{ģ}\Cell{ }\Cell{ }^^A +% \Cell{ }\Cell{ķ}\Cell{ļ}\Cell{ņ}\Cell{ }\Cell{ŗ}\Cell{ş}^^A +% \Cell{ţ}\Cell{ }\Cell{ }\Cell{ }\Cell{ }\strut\\ +% +% macron & \Cell{ā}\Cell{ }\Cell{ }\Cell{ē}\Cell{ḡ}\Cell{ }\Cell{ī}^^A +% \Cell{ }\Cell{ }\Cell{ }\Cell{ }\Cell{ō}\Cell{ }\Cell{ }^^A +% \Cell{ }\Cell{ū}\Cell{ǣ}\Cell{ȳ}\Cell{ }\strut\\ % % \rowcolor{nagrey}^^A -% \bfseries Full Stop Gobbled & \bfseries After Shorthand \\ -% Dr. \LMLK . & -% |Dr. \LMLK .| \\ +% breve & \Cell{ă}\Cell{ }\Cell{ }\Cell{ }\Cell{ğ}\Cell{h}\Cell{ĭ}^^A +% \Cell{ }\Cell{ }\Cell{ }\Cell{ }\Cell{ŏ}\Cell{ }\Cell{ }^^A +% \Cell{ }\Cell{ŭ}\Cell{ }\Cell{ }\Cell{ }\strut\\ +% +% dot/dotless & \Cell{ḃ}\Cell{ċ}\Cell{ }\Cell{ė}\Cell{ġ}\Cell{ }\Cell{ı}^^A +% \Cell{ }\Cell{ }\Cell{ }\Cell{ }\Cell{ }\Cell{ }\Cell{ }^^A +% \Cell{ }\Cell{ }\Cell{ }\Cell{ }\Cell{ż}\strut\\ % % \rowcolor{nagrey}^^A -% \bfseries Full Stop Remains & \bfseries After Shorthand with Optional Argument \\ -% Dr. \LMLK[M.L.] . & -% |Dr. \LMLK[M.L.] .| \\ +% ogonek & \Cell{ą}\Cell{ }\Cell{ }\Cell{ę}\Cell{ }\Cell{ }\Cell{į}^^A +% \Cell{ }\Cell{ }\Cell{ }\Cell{ }\Cell{ǫ}\Cell{ }\Cell{ }^^A +% \Cell{ }\Cell{ų}\Cell{ }\Cell{ }\Cell{ }\strut\\ +% +% caron & \Cell{ǎ}\Cell{č}\Cell{ď}\Cell{ě}\Cell{ǧ}\Cell{ }\Cell{ǐ}^^A +% \Cell{ǰ}\Cell{ǩ}\Cell{ľ}\Cell{ň}\Cell{ǒ}\Cell{ř}\Cell{š}^^A +% \Cell{ť}\Cell{ǔ}\Cell{ }\Cell{ }\Cell{ž}\strut\\ % % \rowcolor{nagrey}^^A -% \bfseries Fixed; Space Removed & \\ -% Dr. \LMLK[M.L.]. & -% |Dr. \LMLK[M.L.].| \\\bottomrule +% various & \Cell{å}\Cell{æ}\Cell{ð}\Cell{đ}\Cell{ij}\Cell{ł}\Cell{ŋ}^^A +% \Cell{ø}\Cell{œ}\Cell{ő}\Cell{ů}\Cell{ű}\Cell{ș}\Cell{ß}^^A +% \Cell{ț}\Cell{þ}\hspace{5.5em}\strut\\\bottomrule % \end{tabular} % \end{center} % -% \subsubsection{Formatting Initials} +% More Unicode characters can be made available when using fonts with TS1 glyphs (pages 455--463 in \Title{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} for more information. % -% This can be 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. +% When using a font with TS1 glyphs, the following preamble snippet is an example of how one might add more Unicode characters, such as a long s (\LA{s-medialis}): +% \begin{Quote} +% \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} % -% Fighting with one's editor does little good. If a style guide requires spaces, try thin spaces. The quick interface simplifies the task. Below we use no formatting: +% In Congreſs, July 4, 1776 +% \end{Verbatim} % -% \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} +% In Congreſs, July 4, 1776 +% \end{Quote} +% +% \subsubsection[Unicode, Fragility]{Fragility of Active Unicode} +% +% This topic can affect different issues: +% \begin{enumerate} +% \item \cmd{\CapThis} does not cause errors because we check for an active Unicode character at the beginning of a name element. Macros in name arguments may need alternate formatting. See also Sections~\ref{sec:CapParticles} and~\ref{sec:AltCaps}. +% +% \item In older \TeX\ distributions, names with active Unicode characters could expand differently in the index if the indexing macros were written first to the \texttt{aux} file. This wasmitigated since 2018. +% +% \item If some of the macros represented by active characters get redefined, then both the names and their patterns that contain such characters may change unexpectedly, affecting both text and index. +% \end{enumerate} +% +% \TeX\ macros that partition their arguments can break active Unicode characters quite easily, as we show here with this delimited macro: +% \begin{Quote} +% \begin{Verbatim}[numbers=none] +% \def\Breaker#1#2#3!{<#1#2><#3>} +% \def\Atsign{@} +% \def\AtAt{\Atsign\Atsign} % \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{Quote} +% The macro \cmd{\Breaker} will take an arbitrary stream of tokens as an argument until it terminates with a bang, which is a delimiter. It puts the first token in |#1|. The second goes in |#2|, while the third gets everything up to the bang. +% \begin{Center} +% \def\Breaker#1#2#3!{<#1#2><#3>} +% \def\Atsign{@} +% \def\AtAt{\Atsign\Atsign} +% \begin{tabular}{llll}\toprule +% \rowcolor{nagrey}^^A +% \bfseries Argument & \bfseries Macro & \bfseries Engine & \bfseries Result\\ +% +% |abcde| & |\Breaker abcde!| & (any) & \Breaker abcde!\\ +% |{æ}bcde| & |\Breaker {æ}bcde!| & (any) & \Breaker {æ}bcde!\\ +% |\ae bcde| & |\Breaker \ae bcde!| & (any) & \Breaker \ae bcde!\\ +% |a\AtAt bcde| & |\Breaker a\AtAt bcde!| & (any) & \Breaker a\AtAt bcde!\\ +% +% \rowcolor{nagrey}^^A +% |æbcde| & |\Breaker æbcde!| & \texttt{xelatex} & <æb><cde>\\ +% \rowcolor{nagrey}^^A +% |æbcde| & |\Breaker æbcde!| & \texttt{lualatex} & <æb><cde>\\ +% |æbcde| & |\Breaker æbcde!| & \texttt{pdflatex} & \Breaker æbcde!\\ +% |æbcde| & |\Breaker æbcde!| & \texttt{latex} & \Breaker æbcde!\\ +% \bottomrule % \end{tabular} -% \end{minipage} -% \end{quote} +% \end{Center} % -% 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 entry order (Section~\ref{sec:IndexInitials}). +% Here is why the first two glyphs, or the first macro and glyph, are grouped together in |#1#2| below, and how this affects \textsf{nameauth}: +% \begin{itemize} +% \item The letter \texttt{a} is one argument, and \texttt{b} is the second. +% \item Since \texttt{\{æ\}} is in a group, it is one argument, and \texttt{b} is the second. +% \item The macro \cmd{\ae} also is one argument that prints æ, and \texttt{b} is the second. +% \item The letter \texttt{a} is one argument, and \cmd{\AtAt} is one argument that prints @@. But if it were evaluated or written to a file at some point during its expansion, for the purposes of name arguments in \textsf{nameauth}, something unexpected could occur. +% \item Both \texttt{xelatex} and \texttt{lualatex} treat the Unicode letter \texttt{æ} as one argument, with \texttt{b} as the second. +% \item In \texttt{latex} and \texttt{pdflatex}, however, \texttt{æ} is an active Unicode control sequence that uses two arguments all by itself. It fills up |#1#2|. The rest of the input is in |#3|. +% \item Any active Unicode character 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 \}}. +% \end{itemize} +% +% 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, use \cmd{\AltCaps} (Section~\ref{sec:AltFeatures}). % % \ReturnLink % +% \begin{Quotation}{\Linc} +% {\Title{Gettysburg Address} (19 November 1863)} +% Four score and seven years ago our fathers brought forth on this +% continent, a new nation, conceived in Liberty, and dedicated to the +% proposition that all men are created equal. +% +% Now we are engaged in a great civil war, testing whether that nation, +% or any nation so conceived and so dedicated, can long endure. We are met +% on a great battle-field of that war. We have come to dedicate a portion +% of that field, as a final resting place for those who here gave their +% lives that that nation might live. It is altogether fitting and proper +% that we should do this. +% +% But, in a larger sense, we can not dedicate\,---\,we can not +% consecrate\,---\,we can not hallow\,---\,this ground. The brave men, +% living and dead, who struggled here, have consecrated it, far above our +% poor power to add or detract. The world will little note, nor long +% remember what we say here, but it can never forget what they did here. +% It is for us the living, rather, to be dedicated here to the unfinished +% work which they who fought here have thus far so nobly advanced. It is +% rather for us to be here dedicated to the great task remaining before +% us\,---\,that from these honored dead we take increased devotion to that +% cause for which they gave the last full measure of devotion\,---\,that +% we here highly resolve that these dead shall not have died in +% vain\,---\,that this nation, under God, shall have a new birth of +% freedom\,---\,and that government of the people, by the people, for the +% people, shall not perish from the earth. +% \index{politicians, quotes of\noexpand\string|hyperpage} +% \end{Quotation} +% +% \newpage +% % \section{Language Topics} % \label{sec:Lang} % -% Here we cover technical issues related to the use of names in various languages and cultures. Specifically, we show how they should be represented in English, but this material can apply to other language standards as well. +% Here we cover technical issues related to the use of names in various languages and cultures. We draw on material from Sections~\ref{sec:DataTagHooks} and~\ref{sec:Formatting}. We also make use of the debugging macros in the next section. Although we show how non-English names are represented in English, this material can apply to other language standards. % % \subsection[Active Characters]{Caveats with Active Characters} % -% Active characters affect name patterns and index sorting, depending on the \LaTeX\ engine being used. We use \cmd{\PretagName} (Section~\ref{sec:IndexSort}; cf.~\ref{sec:Unicode}) to get correct sorting and \cmd{\SkipIndex} (Section~\ref{sec:IdxPrefix}) to suppress bogus index entries: -% -% \newpage +% When using active characters, specific characters have been given the category code of a macro or control sequence in order to represent them in the classical regime of \textsf{latex} and \textsf{pdflatex}. Active characters and macros generate different names, even though the output on the page looks the same. % +% Active characters affect name patterns and index sorting, depending on the \LaTeX\ engine being used. One finds more technical details on the matter in Section~\ref{sec:Unicode}. We use \cmd{\PretagName} (Section~\ref{sec:IndexSort}) to get correct sorting and \cmd{\SkipIndex} (Section~\ref{sec:IdxPrefix}) to suppress bogus index entries: % \begin{enumerate}\small % \item \Name*{Æthelred, II}\dotfill |\Name*{Æthelred, II}| -% \PatInfo{\ShowPattern{Æthelred, II} \textrm{(1)}\break +% \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)}} -% \item[] We have seen this name earlier, as the formatting shows.\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\}}.} +% +% \item[] We have seen this name earlier, as the formatting shows.\footnote{Regarding the margin note that shows name patterns, 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\}}. The active Unicode character is being detokenized and its control sequence is interpreted as two glyphs. This is a result of using \textsf{inputenc} and \textsf{fontenc}.} +% % \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[] 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 ë. It cannot have the same index entry as \Name{Bo\"ethius} above. +% % \item \SkipIndex\Name{Bo{\"e}thius}\dotfill |\SkipIndex\Name{Bo{\"e}thius}| -% \item[] Yet another different name by virtue of grouping tokens (Section~\ref{sec:GroupSpace}). The index entry for this one is again different. +% +% \item[] Yet another different name by virtue of grouping tokens (Section~\ref{sec:Unique}). The index entry for this one is again different. % \end{enumerate} % +% \begin{Quotation}{\Name{Bo\"ethius}\IndexRef[Anic. Manl.]{Severinus Boethius}{Bo\"ethius} (\Name[Anic. Manl.]{Severinus Boethius})} +% {\Title{On the Consolation of Philosophy} IV.III (523 \textsc{ad})} +% For since good and bad, and likewise reward and punishment, are contraries, it necessarily follows that, corresponding to all that we see accrue as reward of the good, there is some penalty attached as punishment of evil. As, then, righteousness itself is the reward of the righteous, so wickedness itself is the punishment of the unrighteous. +% \index{theologians, quotes of\noexpand\string|hyperpage} +% \index{philosophers, quotes of\noexpand\string|hyperpage} +% \end{Quotation} +% \newpage +% % \subsection{Hyphenation} +% \label{sec:HyphNames} % -% In modern English, names can be hyphenated to reflect their cultural origins. With \textsf{nameauth}, one can handle such names by using default hyphenation, optional hyphens, or packages like \textsf{babel} and \textsf{polyglossia}. -% \IndexName[John]{\noexpand\de{Strietelmeier}} +% Unlike English standards up to the middle twentieth century, modern English conventions encourage that names of non-English origin can and should be hyphenated to reflect their cultural origins. For example, even with place names, modern English prefers German \emph{Mainz} over the older English form \emph{Mayence}. With \textsf{nameauth}, one can accommodate names from different cultures by using optional hyphens or packages like \textsf{babel} and \textsf{polyglossia}. % % \subsubsection*{\hfil Default Hyphenation} % -% Here\PatInfo{\ShowPattern[John]{Strietelmeier}} we use the default hyphenation. Using \cmd{\textls} from \textsf{microtype} we get the name to break badly. We use \cmd{\SkipIndex} to omit this version from the index. +% \PatInfo*{\ShowPattern[John]{Strietelmeier}}^^A +% Here we show potential issues that can arise when dealing with default English hyphenation. We get the name of a deceased, yet long-time, influential professor at Valparaiso University whose last name is of German origin, to hyphenate poorly.\footnote{Not shown in these examples, we use \cmd{\textls} from \textsf{microtype} to ensure bad breaks. We omit all forms of this name from the index except for \cmd{\Name[John]\{}\cmd{\noexpand}\cmd{\de\{Strietelmeier\}\}} because we use \textsf{babel}-related macros.} +% \begin{Quote} +% \begin{Verbatim} +% In English, some names come from other cultures. Names like +% \Name[John]{Strietelmeier} can break badly in some cases. +% \end{Verbatim} % -% \begin{VerbatimOut}{\jobname.tmp} +% \IndexName[John]{\noexpand\de{Strietelmeier}} % \textls[20]{In English, some names come from other cultures. -% Names like \SkipIndex\Name[John]{Strietelmeier} -% can break badly in some cases.} -% \end{VerbatimOut} -% -% \begin{quote} -% \VerbatimInput[gobble=0]{\jobname.tmp} -% -% \input{\jobname.tmp} -% \end{quote} +% Names like \SkipIndex\Name[John]{Strietelmeier} can break badly +% in some cases.} +% \end{Quote} % % \subsubsection*{\hfil Discretionary Hyphens} % -% We\PatInfo{\ShowPattern[John]{Strie\-tel\-meier}} create a different name from that above. One must use the discretionary hyphens consistently in the macro arguments. We use \cmd{\Name[John]\{Strie\textbackslash-tel\textbackslash-meier\}} to omit this version from the index. We see that it breaks properly. +% \PatInfo*{\ShowPattern[John]{Strie\-tel\-meier}}^^A +% We now use a different name from the name above. Even though it may look the same in the text, using discretionary hyphens will cause it to have a different index entry. As a result, one must use discretionary hyphens consistently in the macro arguments to avoid creating different names and index entries. Nevertheless, this name breaks properly.\footnote{Here again, we omit \cmd{\Name[John]\{Strie\textbackslash-tel\textbackslash-meier\}} from the index.} +% \begin{Quote} +% \begin{Verbatim} +% In English, some names come from other cultures. Names like +% \Name[John]{Strie\-tel\-meier} can break badly in some cases. +% \end{Verbatim} % -% \begin{VerbatimOut}{\jobname.tmp} +% \IndexName[John]{\noexpand\de{Strietelmeier}} % \textls[20]{In English, some names come from other cultures. % Names like \SkipIndex\Name[John]{Strie\-tel\-meier} % can break badly in some cases.} -% \end{VerbatimOut} -% -% \begin{quote} -% \VerbatimInput[gobble=0]{\jobname.tmp} -% -% \input{\jobname.tmp} -% \end{quote} +% \end{Quote} % % \subsubsection*{\hfil Language Packages} % -% Here\PatInfo{\textls[-5]{\ShowPattern[John]{\de{Strietelmeier}}}} we use an approach with macros in name arguments that can be applied to \textsf{babel} and \textsf{polyglossia}. This approach has issues that we discuss in Sections~\ref{sec:NameParticles}, \ref{sec:AltFormat}, and elsewhere, showing how to prevent errors. +% \Info*{Name patterns and index entries are too big for the margin.}^^A +% Here we use macros in name arguments that can work with either \textsf{babel} or \textsf{polyglossia}.\footnote{For best results, one should consult the documentation for \textsf{babel} and \textsf{polyglossia}.} +% This approach has some caveats when using the macro \cmd{\CapThis}. 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}). Related issues appear in Sections~\ref{sec:NameParticles} and \ref{sec:Noexpand}, showing ways to mitigate possible errors. % % \NameArgWarning % -% 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}): -% -% \begin{VerbatimOut}{\jobname.tmp} -% \textls[20]{In English, some names come from other cultures. -% Names like \Striet\ or \Name[John]{\noexpand\de{Strietelmeier}} -% break badly in some cases.} -% \end{VerbatimOut} -% -% \begin{quote} -% \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} -% \VerbatimInput[gobble=0,firstnumber=10]{\jobname.tmp} -% -% \input{\jobname.tmp} -% \end{quote} -% -% \subsection{Affixes Need Commas} -% \label{sec:Affix} -% \negmedskip +% \newpage % -% \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.^^A -% \end{InfoBox} +% \ifdefined\NameauthDoTestFiles \edef\NameauthTestFile{test05_01.tex}\else +% \edef\NameauthTestFile{\jobname.tmp}\fi +%^^A +% \begin{VerbatimOut}{\NameauthTestFile} +% \documentclass{article} % -% 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. +% \newcommand\nolangs{} % Do not load the language packages via compat.tex +% \input{compat.tex} % Included with nameauth for compatibility. % -% 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 delimits or segments the name argument. Spaces around the comma are ignored. See Section~\ref{sec:Noexpand} for more information when using macros in name arguments. Below we see the basics of commas in name arguments. +% \ifloadbabel % Defined in compat.tex +% % For any LaTeX format; compat.tex makes \loadbabel true +% % only for use with dvilualatex, pdflatex, and latex. % -% \begin{center} -% \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} -% \ForgetName{Sun, Yat-sen} -% \begin{tabular}{ll}\toprule -% \rowcolor{nagrey}^^A -% \Name[Oskar]{Hammerstein, II} & |\Name[Oskar]{Hammerstein, II}|\\ -% \rowcolor{nagrey}^^A -% \Name[Oskar]{Hammerstein, II} & |\Name[Oskar]{Hammerstein, II}|\\ -% -% \Name{Louis, XIV} & |\Name{Louis, XIV}|\\ -% \Name{Louis, XIV} & |\Name{Louis, XIV}|\\ -% -% \rowcolor{nagrey}^^A -% \Name{Sun, Yat-sen} & |\Name{Sun, Yat-sen}|\\ -% \rowcolor{nagrey}^^A -% \Name{Sun, Yat-sen} & |\Name{Sun, Yat-sen}|\\\bottomrule -% \end{tabular} -% \end{center} +% \usepackage[main=american,ngerman]{babel} +% \usepackage[babel=true]{microtype} % if desired % -% Western names with affixes must use \meta{SNN,Affix},^^A -% \PatInfo{\ShowPattern[Oskar]{Hammerstein}[II]} never the obsolete syntax, which is meant for nonwestern 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]}. +% % Convenience macros, classical babel approach +% \newcommand{\de}[1]{\foreignlanguage{ngerman}{#1}} % -% \DescribeMacro{\KeepAffix} -% 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. +% \else +% % For XeLaTeX and LuaLaTeX; compat.tex makes \loadbabel +% % false by default, which is the historic behavior. +% % Currently, one also can use babel with these engines. +% \usepackage{polyglossia} +% \setdefaultlanguage[variant=american]{english} +% \setotherlanguage[variant=german, spelling=new]{german} +% \usepackage{microtype} % if desired +% +% % Convenience macros, not using babel-equivalent macros +% \newcommand{\de}[1]{\textgerman{#1}} +% \fi % -% \DescribeMacro{\KeepName} -% In longer name forms, \cmd{\KeepName} turns spaces \emph{between} all visible name elements into non-breaking spaces. +% % Other setup +% \usepackage{nameauth} % -% \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} +% \begin{nameauth} +% \< Striet & John & \noexpand\de{Strietelmeier} & > +% \end{nameauth} % -% This macro does not alter spaces \emph{within} name elements with multiple names, such as French and German forenames, as well as Spanish surnames. \cmd{\KeepName} works with all name types. +% \PretagName[John]{\noexpand\de{Strietelmeier}} +% {Strietelmeier, John} % -% \DescribeMacro{\DropAffix} -% If \cmd{\DropAffix} precedes only a Western name, it will suppress the affix after the surname in a first or long instance. We get ``\DropAffix\Name*[Oskar]{Hammerstein, II}'' From |\DropAffix\Name*[Oskar]{Hammerstein, II}|. +% \begin{document} % -% With nonwestern 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}. +% In English, some names come from other cultures. Names like +% \Striet\ or \Name[John]{\noexpand\de{Strietelmeier}} can +% break badly in some cases. % -% \DescribeMacro{\ShowComma} -% In a long name form, \cmd{\ShowComma} forces the display of a comma between a Western name and its affix. -% \DescribeMacro{\NoComma} -% 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. +% \end{document} +% \end{VerbatimOut} +%^^A +% \begin{Quote} +% \VerbatimInput[gobble=0]{\NameauthTestFile} +% \end{Quote} % -% \begin{center} -% \begin{tabular}{ll}\toprule -% \rowcolor{nagrey}^^A -% \ShowComma\LPatton & |\ShowComma\LPatton|\\ -% \NoComma\LPatton & |\NoComma\LPatton|\\\bottomrule -% \end{tabular} -% \end{center} +% The name pattern is: +% \texttt{\ShowPattern[John]{\noexpand\de{Strietelmeier}}}. +% The example above gives us the following: +% \begin{Quote} +% \textls[20]{In English, some names come from other cultures. Names like +% \Striet\ or \Name[John]{\noexpand\de{Strietelmeier}} can +% break badly in some cases.} +% \end{Quote} % -% 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}). +% \newpage % -% \subsection[Eastern Names, Name Caps] -% {Eastern Names and Family Names in All Caps} +% \subsection{Eastern Names} % \label{sec:Eastern} % -% Proper Eastern names, included with ancient and medieval forms in the broader group of nonwestern names, are encoded using comma-delimited syntax (compare the obsolete syntax in Section~\ref{sec:Obsolete}). They have nonwestern index entries: \meta{SNN} \meta{Affix} (no comma between name elements). The current syntax permits alternate names; the obsolete does not. +% Proper Eastern names are encoded using comma-delimited syntax. They have Non-Western index entries: \meta{SNN} \meta{Affix} (no comma between name elements). The current syntax permits alternate names; the obsolete syntax does not (Section~\ref{sec:Obsolete}). % % \begin{SyntaxBox} -% \cmd{\Name}\marg{SNN, Affix}\oarg{Alternate} +% \cmd{\Name}\marg{SNN\textbf{,}Affix}\oarg{Alternate} % \end{SyntaxBox} % -% Even in some academic texts, one sees nonwestern 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. +% \BothInfo*{\ShowPattern{Sun, Yat-sen}} +% {\ShowIdxPageref*{Sun, Yat-sen}} +% Even in some academic texts, one sees Non-Western names encoded with Western forms.\footnote{\textls[-5]{Jaroslav Pelikan, \Title{The Christian Tradition}, 5 vols. (Chicago: Chicago UP, 1971--1989); Immanuel Geiss, \Title{\de{Personen: Die biographische Dimension der Weltgeschichte}}, \de{Geschichte Griffbereit} vol. 2 (Munich: Wissen Media Verlag, 2002).} As of writing, \href{https://www.nndb.com/}{\bfseries NNDB} sorts \Name{Kim, Jong Un} under U, not K. That prioritizes accesibility over accuracy. This is not the publisher's fault; it is a market reality.} +% 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}| ensures correct forms of the name \Name*{Sun, Yat-sen} in the text and the index. We get both cross-cultural sensitivity and scholarly accuracy. +% +% \subsection{Names in All Caps} +% \label{sec:AllCaps} % % \DescribeMacro{\AllCapsActive} -% Certain contexts call for one's entire family name to be capitalized. This differs +% Some contexts capitalize one's entire family name. This differs from the way in which initial letter capitalization is handled (Section~\ref{sec:NameParticles}). % \DescribeMacro{\AllCapsInactive} -% from the way in which initial letter capitalization is handled (Section~\ref{sec:NameParticles}). In addition to the \texttt{allcaps} package option +% In addition to the \texttt{allcaps} package option (Section~\ref{sec:PkgOptions}), % \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}. -% -% 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. -% \medskip +% \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 using macros in both the text and index, see Sections~\ref{sec:AltFormat} and~\ref{sec:AdvCustomize}. % -% \begin{center} +% \Global Both \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{Center} +% \BothInfo[2.5ex]{\ShowPattern[Hideyo]{Noguchi}\break +% \ShowPattern{Miyazaki, Hayao}} +% {\ShowIdxPageref*[Hideyo]{Noguchi}\break +% \ShowIdxPageref*{Miyazaki, Hayao}} % \begin{tabular}{ll}\toprule % \rowcolor{nagrey}^^A +% \bfseries Text & \bfseries Macro\\ % \LNoguchi & |\LNoguchi| \\ % -% \CapName\LNoguchi & |\CapName\LNoguchi}|\\ -% % \rowcolor{nagrey}^^A +% \CapName\LNoguchi & |\CapName\LNoguchi|\\ +% % \LMiyazaki & |\LMiyazaki| \\ % +% \rowcolor{nagrey}^^A % \CapName\LMiyazaki & |\CapName\LMiyazaki|\\\bottomrule % \end{tabular} -% \end{center} -% \vspace{-14ex} -% \BothInfo{\ShowPattern[Hideyo]{Noguchi}\break -% \ShowPattern{Miyazaki, Hayao}} -% {\ShowIdxPageref*[Hideyo]{Noguchi}\break -% \ShowIdxPageref*{Miyazaki, Hayao}} -% \vspace{14ex} +% \end{Center} % % \subsection{Reversed Names} % \label{sec:RevNames} % -% Sometimes a publisher expects Western-style index entries. Sometimes certain names have specific forms in the index, The reversing option and macros can adapt forms in the text to the index entries required in such cases. +% Sometimes a publisher expects Western-style index entries. Sometimes certain names need to have specific forms in the index, The reversing macros can adapt forms in the text to required Western index entries. % % \DescribeMacro{\ReverseActive} % 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 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. \emph{Reversing only affects long name forms,} which is why we show only long names below. In this manual, reversed Western forms are shown with a dagger (\dag). +% These macros do not affect the index. They work also with \cmd{\AKA} and friends. \emph{Reversing only affects long name forms,} which is why we show only long names below. % -% 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. +% \Global Both \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. % -% \begin{center} -% \vspace{3ex} -% \BothInfo{\ShowPattern[Hideyo]{Noguchi}\break \ShowPattern{Miyazaki, Hayao}} -% {\ShowIdxPageref*[Hideyo]{Noguchi}\break \ShowIdxPageref*{Miyazaki, Hayao}} -% \vspace{-3ex} +% Unwanted results that may arise from reversing names depend more on the context than on the syntactic forms of the names themselves. This is the crux of how \textsf{nameauth} deals with ambiguity across cultures. +% +% \begin{SyntaxBox}[Reversing Western Names] +% \cmd{\RevName}\cmd{\Name}\oarg{FNN}\marg{SNN}\oarg{Alternate} +% \end{SyntaxBox} +% +% 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}. This name has a Western index entry. +% \BothInfo[-7.5ex]{\ShowPattern{}}{\ShowIdxPageref*{}} +% +% \BothInfo[5ex]{\ShowPattern[Hideyo]{Noguchi}} +% {\ShowIdxPageref*[Hideyo]{Noguchi}} +% \begin{Center} % \begin{tabular}{ll}\toprule % \rowcolor{nagrey}^^A -% \bfseries Output & \bfseries Macro \\ +% \bfseries Text & \bfseries Macro / Arguments\\ % % \LNoguchi & |\LNoguchi| \\ % \LNoguchi[Doctor] & |\LNoguchi[Doctor]| \\ -% \strut Bad result: \fbox{\LNoguchi[Sensei]} & |\LNoguchi[Sensei]| \\ % % \rowcolor{nagrey}^^A +% \strut Unwanted result: \LNoguchi[Sensei] & +% |\LNoguchi[Sensei]| \\ +% % \RevName\LNoguchi\dag & |\RevName\LNoguchi\dag| \\ +% +% \RevName\LNoguchi[Sensei]\dag & |\RevName\LNoguchi[Sensei]| \\ +% % \rowcolor{nagrey}^^A -% \strut Bad result: \fbox{\RevName\LNoguchi[Doctor]} & |\RevName\LNoguchi[Doctor]| \\ +% \strut Unwanted result: \RevName\LNoguchi[Doctor] & |\RevName\LNoguchi[Doctor]| \\\bottomrule +% \end{tabular} +% \end{Center} +% \smallskip +% +% \begin{SyntaxBox}[Reversing Eastern Names] +% \cmd{\RevName}\cmd{\Name}\marg{SNN\textbf{,}Affix}\oarg{Alternate} +% \end{SyntaxBox} +% +% The index entry of this name form looks like \meta{SNN} \meta{FNN} (no comma). This name has a Non-Western index entry. \emph{Reversing ancient names functions the same way, but often produces nonsensical name forms.} +% +% \BothInfo[5ex]{\ShowPattern{Miyazaki, Hayao}} +% {\ShowIdxPageref*{Miyazaki, Hayao}} +% \begin{Center} +% \begin{tabular}{ll}\toprule % \rowcolor{nagrey}^^A -% \RevName\LNoguchi[Sensei]\dag & |\RevName\LNoguchi[Sensei]| \\ +% \bfseries Text & \bfseries Macro / Arguments\\ % % \LMiyazaki & |\LMiyazaki| \\ % \LMiyazaki[Sensei] & |\LMiyazaki[Sensei]| \\ -% \strut Bad result: \fbox{\LMiyazaki[Mr.]} & |\LMiyazaki[Mr.]| \\ % % \rowcolor{nagrey}^^A +% \strut Unwanted result: \LMiyazaki[Mr.] & |\LMiyazaki[Mr.]| \\ +% % \RevName\LMiyazaki & |\RevName\LMiyazaki| \\ -% \rowcolor{nagrey}^^A % \RevName\LMiyazaki[Mr.] & |\RevName\LMiyazaki[Mr.]| \\ +% % \rowcolor{nagrey}^^A -% \strut Bad result: \fbox{\RevName\LMiyazaki[Sensei]} & +% \strut Unwanted result: \RevName\LMiyazaki[Sensei] & % |\RevName\LMiyazaki[Sensei]| \\\bottomrule % \end{tabular} -% \end{center} -% \negmedskip -% -% \begin{SyntaxBox}[Reversing Western Names] -% \cmd{\RevName}\cmd{\Name}\oarg{FNN}\marg{SNN}\oarg{Alternate} -% \end{SyntaxBox} -% -% 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}. This name has a Western index entry. -% -% \begin{SyntaxBox}[Reversing Eastern Names] -% \cmd{\RevName}\cmd{\Name}\marg{SNN, Affix}\oarg{Alternate} -% \end{SyntaxBox} -% -% The index entry of this name form looks like \meta{SNN} \meta{FNN} (no comma). This name has a nonwestern index entry. -% -% \begin{InfoBox} -% Reversing ancient names works the same as reversing Eastern names. The problem is that, in most cases, one produces a nonsense name. -% \end{InfoBox} -% \negmedskip +% \end{Center} % % \subsection[Listing by Surname]{Listing Western names by Surname} % \label{sec:LastFirst} @@ -3961,122 +4632,200 @@ and version 1.3 or later is part of all distributions of LaTeX version % \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. % -% 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. +% \Global Both \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} -% \begin{tabular}{lll}\toprule -% \rowcolor{nagrey}^^A -% \Name*[Oskar]{Hammerstein, II} & -% \RevComma\Name*[Oskar]{Hammerstein, II} & change\\ -% \rowcolor{nagrey}^^A -% \LNoguchi & \RevComma\LNoguchi & change\\ +% \newpage % -% \LAeth & \RevComma\LAeth & no change\\ -% \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 +% \begin{itemize} +% \item Western names change to reversed comma form: +% \PatInfo*{\ShowPattern[Oskar]{Hammerstein, II}\break % \ShowPattern[Hideyo]{Noguchi}\break % \ShowPattern{Æthelred,II}\break % \ShowPattern{Sun, Yat-sen}} -% \vspace{12ex} +% +% \begin{tabular}{p{3.7cm}l} +% \Name*[Oskar]{Hammerstein, II} & +% \RevComma\Name*[Oskar]{Hammerstein, II} \\ +% \LNoguchi & \RevComma\LNoguchi \\ +% \end{tabular} +% +% \item Non-Western names do not change: +% +% \begin{tabular}{p{3.7cm}l} +% \LAeth & \RevComma\LAeth \\ +% \Name*{Sun, Yat-sen} & \RevComma\Name*{Sun, Yat-sen}\\ +% \end{tabular} +% \end{itemize} % % \subsection{Particles in Names} % \label{sec:NameParticles} % -% 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. +% Particles usually are articles and prepositions grouped either with forenames or surnames. They can refer to places, noble houses, and so on. % -% \subsubsection{Standard Rules} +% In modern usage, particles have crossed into other languages and cultures. The same particles may be handled differently, depending on their source language. Users should consult style guides. See also Section~\ref{sec:RealAltEx}. % -% According to [\hyperlink{Mulvany}{Mulvany}, 152–82], one may treat name particles in the following way: +% \begin{InfoBox} +% One must sort names with particles in \meta{SNN} using \cmd{\PretagName} (Section~\ref{sec:IndexSort}), often by removing spaces in the sort key. +% \end{InfoBox} % +% \subsubsection{Standard Rules} +% +% Here we show how [\hyperlink{Mulvany}{Mulvany}, 152--82] handles name particles, thus pertaining to naming macro arguments. This list is not exhaustive. % \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. Capitalization may vary. -% \item \textit{Le}, \textit{La}, and \textit{L'} always are capitalized -% unless preceded by \textit{de}. -% \item Modern Romance languages keep particles with the surname. -% \item German and medieval Romance languages keep particles with forenames. -% \item Modern Welsh, Irish, and Scots names often merge particles with -% surnames: FitzRoy or Fitzroy; O'Leary; McDonald, MacLeish. -% \end{itemize} +% \item \emph{Afrikaans and English variants:} Particles go in \meta{SNN}. These can include \textit{de}, \textit{de la}, \textit{d'}, \textit{von}, \textit{van}, and \textit{ten}. Capitalization of particles may vary, but \textit{Du} usually is capitalized, yet one sees, e.g., ``\AKA[Charles]{du~Fresne}{du~Cange}'', ``\CapThis\AKA[Charles]{du~Fresne}{du~Cange}'', and even ``\textsf{Ducange}''. \textit{Le}, \textit{La}, and \textit{L'} are capitalized unless preceded by \textit{de}. +% +% \BothInfo[4.5ex]{\ShowPattern[S.J.]{Du Toit}\break +% \ShowPattern[Martin]{Van Buren}\break +% \ShowPattern[Pierre]{L'Enfant}\break +% \ShowPattern[Walter]{de la Mare}\break +% \ShowPattern[Hernando]{de~Soto}} +% {\ShowIdxPageref*[S.J.]{Du Toit}\break +% \ShowIdxPageref*[Martin]{Van Buren}\break +% \ShowIdxPageref*[Pierre]{L'Enfant}\break +% \ShowIdxPageref*[Walter]{de la Mare}\break +% \ShowIdxPageref*[Hernando]{de~Soto}} +% \begin{Block} +% \Name[S.J.]{Du Toit}[Stephanus Johannes]\\ +% |\Name[S.J.]{Du Toit}[Stephanus Johannes]|\\ +% \Name[S.J.]{Du Toit}\dotfill^^A +% |\Name[S.J.]{Du Toit}|\\[1ex] +% \ForgetThis\Name[Martin]{Van Buren}\dotfill^^A +% |\Name[Martin]{Van Buren}|\\ +% \Name[Martin]{Van Buren}\dotfill^^A +% |\Name[Martin]{Van Buren}|\\[1ex] +% \Name[Pierre]{L'Enfant}\dotfill^^A +% |\Name[Pierre]{L'Enfant}|\\ +% \Name[Pierre]{L'Enfant}\dotfill^^A +% |\Name[Pierre]{L'Enfant}|\\[1ex] +% \Name[Walter]{de la Mare}\dotfill^^A +% |\Name[Walter]{de la Mare}|\\ +% \Name[Walter]{de la Mare}\dotfill^^A +% |\Name[Walter]{de la Mare}|\\ +% \CapThis\Name[Walter]{de la Mare}\dotfill^^A +% |\CapThis\Name[Walter]{de la Mare}|\\[1ex] +% \ForgetThis\Name[Hernando]{de~Soto}\dotfill^^A +% |\Name[Hernando]{de~Soto}|\\ +% \Name[Hernando]{de~Soto}\dotfill^^A +% |\Name[Hernando]{de~Soto}|\\ +% \CapThis\Name[Hernando]{de~Soto}\dotfill^^A +% |\CapThis\Name[Hernando]{de~Soto}| +% \end{Block} % -% \begin{center} -% \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} -% \begin{tabular}{lll}\toprule -% \rowcolor{nagrey}^^A -% \bfseries Body Text & \bfseries Index & \bfseries Macro \\ +% \item \emph{Dutch:} Particles go in \meta{FNN}, except for \textit{ver}, which goes in \meta{SNN}. +% \BothInfo*{\ShowPattern[Bernhard ten]{Brink}\break +% \ShowPattern[Daisy]{Ver Boven}} +% {\ShowIdxPageref*[Bernhard ten]{Brink}\break +% \ShowIdxPageref*[Daisy]{Ver Boven}} +% \begin{Block} +% \Name[Bernhard ten]{Brink}\dotfill^^A +% |\Name[Bernhard ten]{Brink}|\\ +% \Name[Bernhard ten]{Brink}\dotfill^^A +% |\Name[Bernhard ten]{Brink}|\\[1ex] +% \Name[Daisy]{Ver Boven}\dotfill^^A +% |\Name[Daisy]{Ver Boven}|\\ +% \Name[Daisy]{Ver Boven}\dotfill^^A +% |\Name[Daisy]{Ver Boven}| +% \end{Block} % -% \ForgetThis\VBuren & \ShowIdxPageref*[Martin]{Van Buren} & -% \cmd{\ForgetThis}\cmd{\VBuren} \\ -% \VBuren & \ShowIdxPageref*[Martin]{Van Buren} & \cmd{\VBuren} \\ +% \item \emph{French:} If the surname has an article (or contracted article) plus preposition, the particles go in \meta{SNN}. Otherwise, prepositions by themselves go in \meta{FNN}. +% \BothInfo*{\ShowPattern[Jean de]{La Fontaine}} +% {\ShowIdxPageref*[Jean de]{La Fontaine}} +% \begin{Block} +% \ForgetThis\Name[Jean de]{La Fontaine}\dotfill^^A +% |\Name[Jean de]{La Fontaine}|\\ +% \Name[Jean de]{La Fontaine}\dotfill^^A +% |\Name[Jean de]{La Fontaine}| +% \end{Block} % -% \rowcolor{nagrey}^^A -% \ForgetThis\Soto & \ShowIdxPageref*[Hernando]{de~Soto} & -% \cmd{\ForgetThis}\cmd{\Soto} \\ -% \rowcolor{nagrey}^^A -% \CapThis\Soto & \ShowIdxPageref*[Hernando]{de~Soto} & -% \cmd{\CapThis}\cmd{\Soto} \\ +% \item \emph{German:} If the surname has an article (or contracted article), optionally plus a preposition, the particles go in \meta{SNN}. Otherwise, the particles (usually just prepositions) go in \meta{FNN}. +% \BothInfo[3ex]{\ShowPattern[J.W. von]{Goethe}\break +% \ShowPattern[Otto]{Zur Linde}} +% {\ShowIdxPageref*[J.W. von]{Goethe}\break +% \ShowIdxPageref*[Otto]{Zur Linde}} +% \begin{Block} +% \ForgetThis\Name[J.W. von]{Goethe}[Johann Wolfgang v.]\\ +% |\Name[J.W. von]{Goethe}[Johann Wolfgang v.]|\\ +% \Name[J.W. von]{Goethe}\dotfill^^A +% |\Name[J.W. von]{Goethe}|\\[1ex] +% \Name[Otto]{Zur Linde}\dotfill^^A +% |\Name[Otto]{Zur Linde}|\\ +% \Name[Otto]{Zur Linde}\dotfill^^A +% |\Name[Otto]{Zur Linde}| +% \end{Block} % -% \ForgetThis\JWG & \ShowIdxPageref*[J.W. von]{Goethe} & -% \cmd{\ForgetThis}\cmd{\JWG}\\ +% \item \emph{Modern Italian:} Particles go in \meta{SNN}. % -% \JWG & \ShowIdxPageref*[J.W. von]{Goethe} & \cmd{\JWG}\\\bottomrule -% \end{tabular} -% \end{center} +% \item \emph{Medieval Italian:} Particles usually go in \meta{FNN}. +% +% \item \emph{Portuguese:} Particles go in \meta{FNN}. +% +% \item \emph{Romanian:} Particles go in \meta{SNN}, except for \textit{de}, which goes in \meta{FNN}. +% +% \item \emph{Scandinavian languages:} Particles go in \meta{FNN} if they are of Scandinavian, Dutch, or German origin, except for the Dutch particle \textit{de} and particles of other origin, which go in \meta{SNN}. +% +% \item \emph{Spanish:} If the surname has an article, it goes in \meta{SNN}. Otherwise, particles go in \meta{FNN}. Compound surnames are indexed by their first element, including names connected by \textit{y} (and). +% \BothInfo[0.5ex]{\ShowPattern[Francisco de]{Figueroa}\break +% \ShowPattern[Manuel Antonio]{Las Heras}} +% {\ShowIdxPageref*[Francisco de]{Figueroa}\break +% \ShowIdxPageref*[Manuel Antonio]{Las Heras}} +% \begin{Block} +% \Name[Francisco de]{Figueroa}\dotfill^^A +% |\Name[Francisco de]{Figueroa}|\\ +% \Name[Francisco de]{Figueroa}\dotfill^^A +% |\Name[Francisco de]{Figueroa}|\\[1ex] +% \Name[Manuel Antonio]{Las Heras}\dotfill^^A +% |\Name[Manuel Antonio]{Las Heras}|\\ +% \Name[Manuel Antonio]{Las Heras}\dotfill^^A +% |\Name[Manuel Antonio]{Las Heras}| +% \end{Block} +% +% \item \emph{Modern Welsh, Irish, and Scots contexts:} names often merge particles with surnames: FitzRoy or Fitzroy; O'Leary; McDonald, MacLeish. +% \end{itemize} % % \subsubsection{Non-Breaking Spaces} % -% 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. +% Despite the macros in Section~\ref{sec:Affix}, names with particles present their own challenges. We recommend inserting a tilde (active character equivalent to \cmd{\nobreakspace}) or Unicode NBSP as needed to prevent bad breaks (see also Sections~\ref{sec:IndexSort}). Here the quick interface helps greatly. % % \subsubsection{Look-Alike Particles} % % 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. % % \subsubsection[Capitalizing]{Capitalizing Particles} +% \label{sec:CapParticles} % % \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.,: +% In English, names like \LSoto\ have their particles in the \meta{SNN} argument: \Soto. At the beginning of a sentence, one must capitalize the name: % % \begin{itemize} -% \item[] \CapThis\Soto\ was a famous Spanish explorer. -% \item[] |\CapThis\Soto\ was a famous Spanish explorer.|\medskip -% -% \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[] \CapThis\Soto\ was a famous Spanish explorer. +% \item[] |\CapThis\Soto\ was a famous Spanish explorer.| +% \end{itemize} % -% \item Section~\ref{sec:NonstandardCaps} applies \cmd{\CapThis} -% to nonstandard names and indexing. +% 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 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. +% Section~\ref{sec:NonstandardCaps} applies \cmd{\CapThis} to names that have nonstandard capitalization. Section~\ref{sec:AltFormat} explains how to avoid potential problems with \cmd{\CapThis} when using macros in name arguments. 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} +% The macro \cmd{\CapName} overrides the \meta{SNN} created by \cmd{\CapThis}, effectively nullifying its effects. It is unlikely that the two macros would be used together,so this should not present a problem. % % \DescribeMacro{\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 and not needed. +% Before \textsf{nameauth} used automatic Unicode detection, \cmd{\AccentCapThis} placed before \cmd{\CapThis} handled Unicode. It remains only for backward compatibility. % % \subsection{Medieval Names} % \label{sec:NameMedieval} % -% 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\}}.} +% Medieval (and some ancient) names present some interesting difficulties, often based on the expected standards of the context in which they are used: +% \begin{itemize} +% \item Some publications present medieval names as Western names due to common convention. That also is reflected in index styles. % -% \begin{quote} +% \item Scholarly publications (sometimes) do not sacrifice details for the sake of convention. This makes their indexes more unfamiliar to the general reader. One might create cross-references from common forms to scholarly forms using \cmd{\IndexRef}, as explained in Section~\ref{sec:IndexRef}. +% \end{itemize} +% +% The design of \textsf{nameauth} helps users implement both approaches when needed, even though the two approaches are not compatible with each other. Indeed, we show both common and scholarly approaches in this manual. The trade-off for flexibility means that users have to put more work into designing how they address this complexity. That is why the manual provides so many examples. +% +% In the following preamble snippet we illustrate how some different approaches may work, and how, even in one document, they can be made to play nicely with each other. Yet we should emphasize that, in general, a document will not use both common and scholarly approaches. We show the ``worst-case'' scenario in order to demonstrate how much easier the normal cases can be.\footnote{Regarding the margin note that shows name patterns, in \texttt{\ShowPattern{Thomas, à~Kempis}} the glyphs \texttt{Ãă} correspond to \cmd{\IeC\{}\texttt{\textbackslash\textquotesingle a\}}. This is a result of using \textsf{inputenc} and \textsf{fontenc}.} +%^^A +% ^^A +% \begin{Quote} % \begin{Verbatim} % \PretagName{Thomas, à~Kempis}{Thomas Akempis} % medieval % \PretagName[Thomas]{à~Kempis}{Akempis, Thomas} % Western @@ -4084,6 +4833,9 @@ and version 1.3 or later is part of all distributions of LaTeX version % % We do not index an alternate medieval form % \ExcludeName{Thomas, \`a~Kempis} % +% \end{Verbatim} +% +% \begin{Verbatim} % % If we did use the alternate form, we would sort it as % \PretagName{Thomas, \`a~Kempis}{Thomas Akempis} % @@ -4097,213 +4849,618 @@ and version 1.3 or later is part of all distributions of LaTeX version % \end{Verbatim} % \ExcludeName{Thomas,\`a~Kempis} % \IndexRef[Thomas]{à~Kempis}{Thomas à~Kempis} -% \end{quote} +% \end{Quote} % +% Below we illustrate different name forms using statements numbered from 1 to 10. The marginal information pertains as indicated to those respective numbered statements to show important differences among the name forms. % \begin{itemize} % \item Medieval form: \cmd{\KempMed} -% \BothInfo{\ShowPattern{Thomas, à~Kempis}\hfill \textrm{(1--4, 7)}\break +% \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 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). +% \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 \DE{von Kempen}. +% +% \item ``\KempMed'' |\KempMed| is indexed as ``\ShowIdxPageref*{Thomas, à~Kempis}''. +% +% \item ``\CapThis\ForceFN\SKempMed'' |\CapThis\ForceFN\SKempMed| can start a sentence, but such usage would be infrequent. +% +% \item We use \cmd{\PretagName} (Section~\ref{sec:IndexSort}) to sort the name according to the expected collating sequence: +% +% \item[] |\PretagName{Thomas, à~Kempis}{Thomas Akempis}| % \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|. +% \item ``\Name{Thomas,\`a~Kempis}'' is a different name with a different pattern, about which the next section goes into some detail. +% +% \item We used \cmd{\ExcludeName} (Section~\ref{sec:IdxFine}) before using the alternate form to keep it from generating a duplicate index entry. +% +% \item We index the canonical form here with \JustIndex\KempMed +% |\JustIndex\KempMed|. % \end{enumerate} % % \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}| +% \item ``\KempW'' is a Western name form with the index entry: ``\ShowIdxPageref*[Thomas]{à~Kempis}''. +% +% \item ``\CapThis\KempW'' appears by using |\CapThis\KempW|. We refer to ``\SKempW'' via |\SKempW|. We get the same breadth of usage as the Non-Western forms, but the index entries differ, as do the specific ways of using the names. +% +% \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: \JustIndex\KempMed +% |\JustIndex\KempMed|. +% +% \item[] To prevent the name from appearing before ``\texttt{aardvark}'' in the index, we remove extra spaces to get the proper sorting between ``\texttt{ajar}'' and ``\texttt{alkaline}'': +% +% \item[] |\PretagName[Thomas]{à~Kempis}{Akempis, Thomas}| % \end{enumerate} % \end{itemize} % +% \subsection{Ancient Names} +% \label{sec:NameAncient} +% +% \begingroup ^^A Local format hook redefinition +% +% Ancient names are fluid regarding the meaning and use of affixes. Certain scholarly contexts add more information to a name when it is first introduced. How do we handle that? We use information from the latter sections mentioned below. First we manually add affixes to a standard name: +% \begin{itemize} +% \item We use \cmd{\PretagName} (Section~\ref{sec:IndexSort}) to sort especially Roman numerals in the index. For example: +% \PatInfo[1ex]{\ShowPattern{Antiochus, IV}!PRE} +% \item[] \cmd{\PretagName\{Antiochus, IV\}\{Antiochus 4\}} +% +% \item We use \cmd{\TagName} (Section~\ref{sec:IndexTag}) to ensure that added information is displayed in the index: +% \PatInfo[1ex]{\ShowPattern{Antiochus, IV}!TAG} +% \item[] \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 information in the text, e.g.: +% \end{itemize} +% \begin{Block} +% \negmedskip +% \PatInfo[3ex]{\ShowPattern{Antiochus, IV}!MN} +% \Name{Antiochus, IV}[IV Epiphanes]\dotfill +% \cmd{\Name\ \{Antiochus, IV\}[IV Epiphanes]}\\ +% \Name*{Antiochus, IV}\dotfill \cmd{\Name*\{Antiochus, IV\}}\\ +% \Name{Antiochus, IV}\dotfill \cmd{\Name\ \{Antiochus, IV\}} +% \end{Block} +% +% 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} +% \begin{Verbatim} +% \PretagName{Demetrius, I}{Demetrius 1} +% \TagName{Demetrius, I}{ Soter, king} +% \begin{nameauth} +% \< Dem & & Demetrius, I & > +% \end{nameauth} +% \end{Verbatim} +% \end{Quote} +% +% \negbigskip +% \begin{Block} +% \BothInfo[1.3ex]{\ShowPattern{Demetrius, I}!PRE\break +% \ShowPattern{Demetrius, I}!TAG\break +% \ShowPattern{Demetrius, I}!MN} +% {\ShowIdxPageref*{Demetrius, I}} +% \Dem[I Soter]\dotfill|\Dem[I Soter]|\\ +% \LDem\dotfill|\LDem|\\ +% \Dem\dotfill|\Dem| +% \end{Block} +% +% Below, instead of manually using \meta{Alternate}, we use a more complex initial setup that automates tags via in first-use formatting hooks (Section~\ref{sec:DataTagHooks}). We also show that we can still have manual changes, here with \textsf{babel} and a macro \cmd{\el} that we made for using Greek, which is part of this manual's preamble: +% \begin{Quote} +% \begin{Verbatim}[firstnumber=last] +% \NameAddInfo{Demetrius, I}{ Soter} +% \renewcommand*\NamesFormat[1] +% {\color{blue}\sffamily#1\NameQueryInfo{}} +% \renewcommand*\MainNameHook{\sffamily} +% \end{Verbatim} +% \end{Quote} +% +% \NameAddInfo{Demetrius, I}{ Soter} +% \renewcommand*\NamesFormat[1] +% {\color{blue}\sffamily#1\NameQueryInfo{}} +% \renewcommand*\MainNameHook{\sffamily} +% +% \begin{Block} +% \BothInfo[3.2ex]{\ShowPattern{Demetrius, I}!DB} +% {\ShowIdxPageref*{Demetrius, I}} +% \ForgetThis\Dem\dotfill|\ForgetThis\Dem|\\ +% \LDem\dotfill|\LDem|\\ +% \Dem\dotfill|\Dem|\\ +% \LDem[I \noexpand \el{Σωτήρ}]\dotfill|\LDem[I \noexpand \el{|^^A +% \textsf{\el{Σωτήρ}}|}]| +% \end{Block} +% +% The full index entry for both cases of \Dem\ in a normal document would look like: +% \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 \cmd{\ForgetName} or \cmd{\ForgetThis}, shows the most information. A long instance of an extant name shows less info, and a short instance shows the least. +% \endgroup^^A Local format hook redefinition +% +% \subsection{Roman Names I} +% \label{sec:Romani} +% +% In this section we take a simple approach. Later on we will useh macros in the arguments (Section~\ref{sec:Romanii}). Roman names consist of the following elements: +% \begin{itemize} +% \item A personal name (\LA{praenomen}) +% +% \item A clan name (\LA{nomen}) +% +% \item An epithet or nickname (\LA{cognomen}) +% \end{itemize} +% +% The \LA{cognomen} can denote a branch family in a larger clan. Affixed to that, one might see additional names (\LA{agnomina}). In ancient Rome, the \LA{nomen} was most important, helping to structure +% \href{https://en.wikipedia.org/wiki/Patrician_(ancient_Rome)}{Roman society}. +% \href{https://en.wikipedia.org/wiki/Roman_naming_conventions}{Naming conventions} changed over time. +% \href{https://en.wikipedia.org/wiki/Praenomen}{\LA{Praenomina}} also have their own history. +% One finds a +% \href{https://www.youtube.com/watch?v=RMLb1jVl_Uo}{helpful video} on the YouTube channel PolýMATHY by \Name[Luke]{Ranieri}. We \emph{do not use} the method where Roman names are indexed using recognizable mononyms.\footnote{Justo L. González, \Title{The Story of Christianity}, 2 vols. (San Francisco: Harper, 1984). [\hyperlink{Mulvany}{Mulvany}] does not advise using such a method, which is ill-suited for \textsf{nameauth}.} +% +% \subsubsection[General Reference]{General Reference Materials} +% \label{sec:RomanGeneral} +% +% The basic approach uses Western name forms, but with some modifications. One often sees this method when indexing well-known Romans.\footnote{Philip J. Adler, \Title{World Civilizations}, 3rd ed. (Belmont, Calif.: Thomson/Wadsworth, 2003).} +% +% \subsubsection*{\hfil Names without \LA{Agnomina}} +% +% \BothInfo*{\ShowPattern[Julius]{Caesar}[Gaius Julius]\break +% \ShowPattern[Pontius]{Pilate}} +% {\ShowIdxPageref*[Julius]{Caesar}[Gaius Julius]\break +% \ShowIdxPageref*[Pontius]{Pilate}} +% Below we have the \LA{nomen} in \meta{FNN}, the \LA{cognomen} in \meta{SNN}, and we add the \LA{praenomen} with the \LA{nomen} in \meta{Alternate} as needed: +% \begin{Block} +% \Name[Julius]{Caesar}[Gaius Julius]\dotfill |\Name[Julius]{Caesar}[Gaius Julius]|\\ +% \Name*[Julius]{Caesar}\dotfill |\Name*[Julius]{Caesar}|\\ +% \Name[Julius]{Caesar}\dotfill |\Name[Julius]{Caesar}| +% \end{Block} +% +% If indexing according to the \LA{cognomen}, perhaps use a Western name, where the \LA{nomen} is in \meta{FNN} and the \LA{cognomen} in \meta{SNN}: +% \begin{Block} +% \Name*[Pontius]{Pilate}\dotfill |\Name*[Pontius]{Pilate}| +% \end{Block} +% +% \BothInfo*{\ShowPattern{Pontius, Pilate}} +% {\ShowIdxPageref*{}} +% In Section~\ref{sec:SelectingTypes} we mentioned that some Roman names could have Non-Western forms, especially those without \LA{praenomina}. They would be indexed according to the \LA{nomen}, which we see in some scholarly resources (Section~\ref{sec:RomanScholari}). +% \begin{Block} +% \ForgetName{Pontius, Pilate} +% \Name{Pontius, Pilate}\dotfill |\Name{Pontius, Pilate}|\\ +% \ForceFN\FName{Pontius, Pilate}\dotfill |\ForceFN\FName{Pontius, Pilate}| +% \end{Block} +% +% \begin{Quotation}{\Name[Julius]{Caesar}} +% {\Title{\la{De bello gallico}} 3.16.6 (58--49 \textsc{bc})} +% \la{Fere libenter homines, id quod volunt, credunt.} +% +% (In general, people willingly believe what they want [to believe].) +% \index{Romans, quotes of\noexpand\string|hyperpage} +% \end{Quotation} +% +% \newpage +% +% \subsubsection*{\hfil Names with \LA{Agnomina}: Tags} +% +% We can use index ``pre-tags'' and tags (Sections~\ref{sec:IndexSort} and~\ref{sec:IdxIdent}) to sort and differentiate names in the index. We also can use name tags (Section~\ref{sec:DataTags}) for \LA{agnomina}. Yet Romans tended to use and pass down a relatively small set of names over many generations. +% +% By defining empty macros \cmd{\nri}, \cmd{\nrii}, \cmd{\nriii}\dots, we can disambiguate identical names. We use \cmd{\nr} (number) followed by Roman numerals to avoid collisions with, for example, the dotless \i. When put at the tail of name arguments, they avoid the need to use either \cmd{\noexpand} or alternate formatting. We can reuse these macros with many different names. +% +% This approach solves most issues in the text. If we need specific index forms, we could index under alternate names, as we do on the next page. With a nod to Section~\ref{sec:DataTagHooks}, we automate the first use of a name to display the name tag. In a normal \LaTeX\ file, we would see the following results: +%^^A +% \begin{VerbatimOut}{\jobname.tmp} +% \newcommand\nri{} +% \newcommand\nrii{} +% +% \begin{nameauth} +% \< Senecai & Lucius Annaeus & Seneca\nri & > +% \< Senecaii & Lucius Annaeus & Seneca\nrii & > +% \end{nameauth} +% +% \renewcommand*\NamesFormat[1] +% {\color{blue}\sffamily#1\NameQueryInfo{}} +% +% \PretagName[Lucius Annaeus]{Seneca\nri}{Seneca, Lucius Annaeus 1} +% \PretagName[Lucius Annaeus]{Seneca\nrii}{Seneca, Lucius Annaeus 2} +% \TagName[Lucius Annaeus]{Seneca\nri}{ (the Elder)} +% \TagName[Lucius Annaeus]{Seneca\nrii}{ (the Younger)} +% \NameAddInfo[Lucius Annaeus]{Seneca\nri}{ the Elder} +% \NameAddInfo[Lucius Annaeus]{Seneca\nrii}{ the Younger} +% +% We can differentiate between +% \Senecai\ and \Senecaii; +% \Senecai \NameQueryInfo{} and \Senecaii \NameQueryInfo{}. +% +% Their full index entries are:\\ +% \ShowIdxPageref[Lucius Annaeus]{Seneca\nri}\\ +% \ShowIdxPageref[Lucius Annaeus]{Seneca\ii} +% \end{VerbatimOut} +%^^A +% \begin{Quote} +% \VerbatimInput[gobble=0]{\jobname.tmp} +% +% \Info[2.5ex]{Name patterns and index entries are too big for the margin.} +% \renewcommand*\NamesFormat[1] +% {\color{blue}\sffamily#1\NameQueryInfo{}}^^A +% \NameAddInfo[Lucius Annaeus]{Seneca\nri}{ the Elder}^^A +% \NameAddInfo[Lucius Annaeus]{Seneca\nrii}{ the Younger}^^A +%^^A +% We can differentiate between +% \Senecai\ and \Senecaii; +% \Senecai \NameQueryInfo{} and \Senecaii \NameQueryInfo{}. +% +% \IndexActual{@} +% \TagName[Lucius Annaeus]{Seneca\nri}{ (the Elder)} +% \TagName[Lucius Annaeus]{Seneca\nrii}{ (the Younger)} +% Their full index entries are:\\ +% \ShowIdxPageref[Lucius Annaeus]{Seneca\nri}\\ +% \ShowIdxPageref[Lucius Annaeus]{Seneca\nrii} +% \TagName[Lucius Annaeus]{Seneca\nri}{, the Elder\string|hyperpage} +% \TagName[Lucius Annaeus]{Seneca\nrii}{, the Younger\string|hyperpage} +% \end{Quote} +% +% \begin{Quotation}{\Scipio} +% {attr. by \Name[Titus]{Livius}, +% \Title{\la{Ab urbe condita}} B 30 (27--9 \textsc{bc})} +% \la{Bellum parate, quoniam pacem pati non potuistis.} +% +% (Prepare for war, for it seems that you are unable to tolerate peace.) +% \index{Romans, quotes of\noexpand\string|hyperpage} +% \end{Quotation} +% +% +% \subsubsection*{\hfil Names with \LA{Agnomina}: \meta{Affix}} +% +% \DescribeMacro{\ForceAffix} In subsequent uses of a Western name, the prefix macro \cmd{\ForceAffix} allows one to print just \meta{Affix} by itself. \cmd{\ForceFN} has a similar use with Non-Western names. +% \begin{InfoBox} +% Where formatting hooks also change syntactic name forms (Section~\ref{sec:AdvancedFormat}f.), that could interfere with \cmd{\ForceFN} and \cmd{\ForceAffix}. +% \end{InfoBox} +% +% We move \LA{agnomina} into the \meta{Affix} field. The \LA{agnomen} drops automatically in the text for subsequent name uses, but we get potentially undesirable index entries: +% \begin{itemize} +% \item[] The text has: +% |\Name[|\meta{praenomen}| |\meta{nomen}|]{|^^A +% \meta{cognomen}\textbf{,}\meta{agnomen}|}| +% \item[] In the index we get: +% \ShowIdxPageref*[\meta{praenomen} \meta{nomen}] +% {\meta{cognomen}, \meta{agnomen}} +% \item[] In the index we want: +% \ShowIdxPageref*[\meta{praenomen} \meta{nomen}] +% {\meta{cognomen} \meta{agnomen}} +% \end{itemize} +% We avoid this problem by using \cmd{\ExcludeName} for names that have \LA{agnomina} in \meta{Affix}. We index different name forms, as in the next example: +% \begin{Quote} +% \begin{Verbatim} +% \begin{nameauth} +% \< CatoY & Marcus Porcius & Cato, the Younger & > +% \< CatoYi & Marcus Porcius & Cato the Younger & > +% \end{nameauth} +% \renewcommand*\NamesFormat[1] +% {\color{blue}\sffamily#1\NameQueryInfo{}} +% \ExcludeName[Marcus Porcius]{Cato, the Younger} +% \makeatletter +% \NameAddInfo[Marcus Porcius]{Cato, the Younger} +% {\if@nameauth@InHook\ (Uticensis, 94--45\ % +% {\rmfamily\textsc{bc}})\else Uticensis\fi} +% \makeatother +% +% \JustIndex\CatoYi +% \CatoY\ is known as \CatoY\ \ForceAffix\CatoY, to distinguish him +% from his great-grandfather. His names include \SCatoY[Marcus] +% (\textit{praenomen}), \SCatoY[Porcius] (\textit{nomen}, one of the +% Porcia clan), and \CatoY, the \textit{cognomen} by which he is best +% known. His other \textit{agnomen}, \NameQueryInfo{}, means he was +% born in Utica. +% \JustIndex\CatoYi He is indexed as: \ShowIdxPageref*{} +% \end{Verbatim} +% +% \Info*{Name patterns and index entries are too big for the margin.}^^A +% \renewcommand*\NamesFormat[1] +% {\color{blue}\sffamily#1\NameQueryInfo{}}^^A +% \makeatletter^^A +% \NameAddInfo[Marcus Porcius]{Cato, the Younger} +% {\if@nameauth@InHook\ (Uticensis, 94--45\ % +% {\rmfamily\textsc{bc}})\else Uticensis\fi}^^A +% \makeatother^^A +% \JustIndex\CatoYi^^A +% \CatoY\ is known as \CatoY\ \ForceAffix\CatoY, to distinguish him +% from his great-grandfather. His names include \SCatoY[Marcus] +% (\textit{praenomen}), \SCatoY[Porcius] (\textit{nomen}, one of the +% Porcia clan), and \CatoY, the \textit{cognomen} by which he is best +% known. His other \textit{agnomen}, \NameQueryInfo{}, means he was +% born in Utica. +% \JustIndex\CatoYi He is indexed as: \ShowIdxPageref*{} +% \end{Quote} +% +% \begin{Quotation}{\Name[Publius]{Vegetius Renatus}} +% {\Title{\la{De re militari}} (c. 390 \textsc{ad})} +% Igitur qui desiderat pacem, praeparet bellum. +% +% (Accordingly, the person who would desire peace prepares for war.)^^A +% \index{Romans, quotes of\noexpand\string|hyperpage} +% \end{Quotation} +% +% \newpage +% +% \subsubsection{Scholarly Works} +% \label{sec:RomanScholari} +% +% The \Title{Oxford Classical Dictionary} and other scholarly sources index according to the \LA{nomen}. That approach moves the \LA{nomen} from \meta{FNN} to \meta{SNN}, making this indexing method incompatible with the previous section: +% \begin{itemize} +% \item[] Index: \ShowIdxPageref*[\meta{praenomen}]{\meta{nomen} \meta{cognomen} \meta{agnomen}} +% \item[] Macro: |\IndexName[|\meta{praenomen}|]{|\meta{nomen} \meta{cognomen} \meta{agnomen}|}| +% \end{itemize} +% +% \BothInfo*{\ShowPattern[Lucius]{Sergius Paulus}} +% {\ShowIdxPageref*{}} +% By putting the \LA{nomen} and \LA{cognomen} into \meta{SNN}, with the \LA{praenomen} in \meta{FNN} and \LA{agnomina} in name tags, we can take a basic approach to these names.\footnote{Cf. Paul L. Maier, \Title{In the Fullness of Time: A Historian Looks at Christmas, Easter, and the Early Church}, revised ed. (San Francisco: Harper, 1991).} +% \begin{Block} +% \Name[Lucius]{Sergius Paulus}\dotfill |\Name[Lucius]{Sergius Paulus}|\\ +% \Name[Lucius]{Sergius Paulus}\dotfill |\Name[Lucius]{Sergius Paulus}| +% \end{Block} +% +% If one is indexing according to the \LA{cognomen}, one must index by an alternate name. This also allows for greater flexibility. +% \begin{itemize} +% \item Use this naming approach, seen in Section~\ref{sec:RomanGeneral}: +% +% \item[] |\Name[|\meta{praenomen}| |\meta{nomen}|]{|^^A +% \meta{cognomen}\textbf{,}\meta{agnomen}|}| +% +% \item[] This allows the standard \textsf{nameauth} logic to handle changes of name forms, as well as the use of \cmd{\ForceAffix}. +% +% \item Use \cmd{\ExcludeName} for every name that should not appear in the index. +% +% \item Use \cmd{\IndexName} or \cmd{\JustIndex} as needed: +% +% \item[] |\IndexName[|\meta{praenomen}|]{|^^A +% \meta{nomen} \meta{cognomen} \meta{agnomen}|}| +% \end{itemize} +% \begin{Quote} +% \begin{Verbatim} +% \begin{nameauth} +% \< CatoE & Marcus Porcius & Cato, the Elder & > +% \< CatoEi & Marcus & Porcius Cato the Elder & > +% \end{nameauth} +% \ExcludeName[Marcus Porcius]{Cato, the Elder} +% +% \JustIndex\CatoEi +% \DropAffix\CatoE\ (234--149 \textsc{bc}) is known as +% \CatoE{} \ForceAffix\CatoE, among other sobriquets. +% His \textit{praenomen} is \SCatoE[Marcus]. His +% \textit{nomen} is \SCatoE[Porcius], a member of the +% Porcia clan. His \textit{cognomen} is \CatoE. +% \JustIndex\CatoEi +% Index: \ShowIdxPageref*{} +% \end{Verbatim} +% +% \Info*{Name patterns and index entries too large for margin.}^^A +% \JustIndex\CatoEi^^A +% \DropAffix\CatoE\ (234--149 \textsc{bc}) is known as +% \CatoE{} \ForceAffix\CatoE, among other sobriquets. +% His \textit{praenomen} is \SCatoE[Marcus]. His +% \textit{nomen} is \SCatoE[Porcius], a member of the +% Porcia clan. His \textit{cognomen} is \CatoE. +% \JustIndex\CatoEi +% Index: \ShowIdxPageref*{} +% \end{Quote} +% % \ReturnLink % % \newpage % -% \addtocontents{toc}{\protect\goodbreak} % \section{Debugging} % \label{sec:Debugging} % -% From this point onward, concepts that we introduced earlier will mesh together in complex ways, starting with indexing. Name patterns govern those interactions, illustrated by debugging macros. We explain what the debugging macros communicate, then we describe the macros. +% Name patterns\,---\,generally unique macros based on names that usually expand to the empty string\,---\,govern interactions in \textsf{nameauth}. We take a deep dive here because name patterns greatly impact the remainder of the manual. We start to show index entries in the body text instead of the margin due to their complexity. % -% \leavevmode^^A -% \PatInfo{\ShowPattern[George]{Washington}\\ -% \ShowPattern{Miyazaki, Hayao}} -% Previously, we have seen simple name patterns displayed in the margin, which look like the examples to the left of this paragraph. Now we show full name patterns, which indicate the ``system'' or data set to which they belong. Name patterns are control sequences that usually expand to the empty string. -% They look like this:\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.} +% \subsection{Null Arguments} +% \label{sec:NullArgs} % -% \begin{quote} -% \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 tag\\ -% \ShowPattern[Schuyler]{Colfax}!DB & name tag\\ -% \end{tabular} -% \end{quote} -% \negmedskip +% All macros that evaluate name arguments (Section~\ref{sec:NameArgMacros}) leave information about the last name that was evaluated. Since version 4.1, some macros that take name arguments also can have a \emph{null argument.} That occurs when the \marg{SNN\textbf{,}Affix} argument is empty. Instead of creating a package error (the normal case), \emph{all macro arguments are ignored} and the macro uses the persistent information from the last name arguments that were evaluated: +% +% \begin{Block} +% Using the example \Name{Confucius}, the following are equivalent:\\ +% \ShowPattern{}\dotfill |\ShowPattern{}|\\ +% \ShowPattern[this]{}[that]\dotfill |\ShowPattern[this]{}[that]| +% \end{Block} +% \begin{itemize} +% \item \cmd{\@nameauth@LoadArgs} isolates each name element, removes surrounding spaces, generates possible name patterns, and saves token registers (page~\pageref{page:NameauthLoadArgs} and following). +% +% \item \cmd{\@nameauth@Choice} determines the name type, then sets flags and selects a pattern according to that name type. Then it executes its arguments. +% +% \item The macro \cmd{\NameauthPattern} that expresses both the name and its type is covered in Section~\ref{sec:NamePatterns}. +% +% \item The flags |\ifNameauthWestern| and |\ifNameauthObsolete| that express the name type are discussed in Section~\ref{sec:SpecialUses}. +% \end{itemize} +% +% The macros that use both name arguments and null arguments include: +% +% \begin{multicols}{2} +% \begin{Block} +% \setbox0\hbox{.3} +% \begin{itemize} +% \item[\S~\ref{sec:DebuggingMacros}] \cmd{\ShowPattern} +% +% \item[\S~\ref{sec:DebuggingMacros}] \cmd{\ShowIdxPageref} +% +% \item[\S~\ref{sec:DebuggingMacros}] \cmd{\ShowIdxPageref*} +% +% \item[\S~\ref{sec:DebuggingMacros}] \cmd{\ShowNameInfo} +% +% \item[\S~\ref{sec:DebuggingMacros}] \cmd{\ShowNameState} +% +% \item[\S~\ref{sec:DebuggingMacros}] \cmd{\ShowNameState*} +% +% \item[\S~\ref{sec:DataTags}\hbox to \wd0{\hfill}] \cmd{\NameQueryInfo} +% \end{itemize} +% \end{Block} +% \end{multicols} % % \begin{InfoBox} -% From this point onward, we show index entries in the body text instead of the margin due to their increasing complexity. +% No \textsf{nameauth} macros that take null arguments change name information; they only display information. This avoids errors. % \end{InfoBox} -% \negmedskip +% +% \begin{Quotation}{\ForgetThis\Name{Maimonides}} +% {\Title{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. +% \index{theologians, quotes of\noexpand\string|hyperpage} +% \index{philosophers, quotes of\noexpand\string|hyperpage} +% \end{Quotation} % % \subsection[Name Patterns]{Name Pattern Overview} % \label{sec:NamePatterns} % -% Below we show 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 prevents any collisions with extant macros: -% -% \begin{center} +% \DescribeMacro{\NameauthPattern} +% All macros that evaluate name arguments (Section~\ref{sec:NameArgMacros}) globally assign to \cmd{\NameauthPattern} a value that corresponds to the last-used name. The \meta{Alternate} argument only affects patterns when using the obsolete syntax (Section~\ref{sec:Obsolete}). +% \begin{Center} % \begin{tabular}{lll}\toprule % \rowcolor{nagrey}^^A -% \bfseries Macro Arguments & \bfseries Patterns & \bfseries Name Type\\ +% \bfseries Macro Name Arguments & \bfseries Name Patterns & \bfseries Name Type\\ % % \oarg{FNN}\marg{SNN} & -% :\meta{FNN}!\meta{SNN} & Western\\ +% \meta{FNN}!\meta{SNN} & Western\\ % \oarg{FNN}\marg{SNN}\oarg{Alt} & -% :\meta{FNN}!\meta{SNN} & Western\\ -% \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\\ +% \meta{FNN}!\meta{SNN} & Western\\ +% \oarg{FNN}\marg{SNN\textbf{,}Affix} & +% \meta{FNN}!\meta{SNN},\meta{Affix} & Western\\ +% \oarg{FNN}\marg{SNN\textbf{,}Affix}\oarg{Alt} & +% \meta{FNN}!\meta{SNN},\meta{Affix} & Western\\ % % \rowcolor{nagrey}^^A -% \hphantom{\oarg{FNN}}\marg{SNN, Affix} & -% :\meta{SNN},\meta{Affix} & nonwestern\\ +% \hphantom{\oarg{FNN}}\marg{SNN\textbf{,}Affix} & +% \meta{SNN},\meta{Affix} & Non-Western\\ +% \rowcolor{nagrey}^^A +% \hphantom{\oarg{FNN}}\marg{SNN\textbf{,}Affix}\oarg{Alt} & +% \meta{SNN},\meta{Affix} & Non-Western\\ % \rowcolor{nagrey}^^A -% \hphantom{\oarg{FNN}}\marg{SNN, Affix}\oarg{Alt} & -% :\meta{SNN},\meta{Affix} & nonwestern\\ -% % \hphantom{\oarg{FNN}}\marg{SNN}\oarg{Alt} & -% :\meta{SNN},\meta{Alt} & old syntax\\ -% +% \meta{SNN},\meta{Alt} & old syntax\\ % \rowcolor{nagrey}^^A % \hphantom{\oarg{FNN}}\marg{SNN} & -% :\meta{SNN} & nonwestern\\\bottomrule +% \meta{SNN} & Non-Western\\\bottomrule % \end{tabular} -% \end{center} -% -% \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}). +% \end{Center} % -% The name category logic is provided by \cmd{\@nameauth@Choice}, which determines the type of name (Western or nonwestern) 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}. +% In the case of the name \LWash, we get a basic Western name pattern: \texttt{\ShowPattern[George]{Washington}}. For this pattern to be useful to \textsf{nameauth}, the internal macros add extra bits to it, which we can demonstrate various ways. +% Below we test manually whether or not various patterns relating to \Wash, \Name{Tully}, \LEliz, and \CatoY\ exist. After that, we shall unpack the meaning of these patterns and their affixes (\texttt{!MN, !NF, !PN, !PRE, !TAG, !DB}). +% \IndexName[Marcus Porcius]{Cato the Younger} +%^^A +% \begin{VerbatimOut}{\jobname.tmp} +% \newcommand\Defined[3]{\ifcsdef{#1}{#2}{#3}} +% +% \begin{enumerate}[itemsep=0pt] +% \item The main-matter name \Wash\ +% \Defined{George!Washington!MN}{exists}{is undefined}. +% \item The front-matter name \Wash\ +% \Defined{George!Washington!NF}{exists}{is undefined}. +% \item The index cross-reference \Name{Tully} +% \Defined{Tully!PN}{exists}{is undefined}. +% \item The index sort tag for \Eliz\ +% \Defined{Elizabeth,I!PRE}{is: \csuse{Elizabeth,I!PRE}} +% {is undefined.} +% \item The index tag for \Wash\ +% \Defined{George!Washington!TAG}{is: \csuse{George!Washington!TAG}} +% {is undefined.} +% \item The name tag for \Wash\ +% \Defined{George!Washington!DB}{is: \csuse{George!Washington!DB}} +% {is undefined.} +% \item The name \CatoY\ is +% \Defined{MarcusPorcius!Cato,theYounger!PN} +% {excluded\csuse{MarcusPorcius!Cato,theYounger!PN}} +% {in another state.} +% \end{enumerate} +% \end{VerbatimOut} +%^^A +% \begin{Quote} +% \VerbatimInput[gobble=0]{\jobname.tmp} % -% Below are name patterns generated from name elements. We mark reversed Western names with a dagger (\dag) and names using the obsolete syntax with a double dagger (\ddag). We show that name patterns depend on name arguments, not on the appearance of a name. The obsolete nonwestern syntax and the current syntax share the same patterns. +% \input{\jobname.tmp} +% \end{Quote} % -% \begin{center} +% This demonstrates the basic functioning of \textsf{nameauth}. The base name pattern always has an affix that tells what kind of name or related element it is, and in what context it belongs. Basic name patterns correlate with consistent index entries; printed name forms may vary. Western name patterns have a bang and a comma; Non-Western name patterns have a comma or nothing. +% \begin{Center} % \begin{tabular}{lll}\toprule % \rowcolor{nagrey}^^A -% \bfseries Body Text & \bfseries \cmd{\ShowPattern} & \bfseries Macro\\ +% \bfseries Text & \bfseries Basic Pattern & \bfseries Macro / Arguments\\ % -% \Harnack[Adolf von] & \texttt{\ShowPattern[Adolf]{Harnack}} & +% \Harnack[Adolf von] & \texttt{\NameauthPattern} & % \cmd{\Harnack[Adolf von]}\\ -% \LHarnack & \texttt{\ShowPattern[Adolf]{Harnack}} & +% \LHarnack & \texttt{\NameauthPattern} & % \cmd{\LHarnack}\\ % % \rowcolor{nagrey}^^A -% \ForgetThis\Patton & \texttt{\ShowPattern[George S.]{Patton, Jr.}} & +% \ForgetThis\Patton & \texttt{\NameauthPattern} & % \cmd{\ForgetThis}\cmd{\Patton}\\ % \rowcolor{nagrey}^^A -% \DropAffix\LPatton & \texttt{\ShowPattern[George S.]{Patton, Jr.}} & +% \DropAffix\LPatton & \texttt{\NameauthPattern} & % \cmd{\DropAffix}\cmd{\LPatton}\\ % -% \ForgetThis\Noguchi & \texttt{\ShowPattern[Hideyo]{Noguchi}} & +% \ForgetThis\Noguchi & \texttt{\NameauthPattern} & % \cmd{\ForgetThis}\cmd{\Noguchi}\\ -% \RevName\LNoguchi\dag & \texttt{\ShowPattern[Hideyo]{Noguchi}} & +% \RevName\LNoguchi\dag & \texttt{\NameauthPattern} & % \cmd{\RevName}\cmd{\LNoguchi}\cmd{\dag}\\ % % \rowcolor{nagrey}^^A -% \ForgetThis\Yamt & \texttt{\ShowPattern{Yamamoto,Isoroku}} & +% \ForgetThis\Yamt & \texttt{\NameauthPattern} & % \cmd{\ForgetThis}\cmd{\Yamt}\\ % \rowcolor{nagrey}^^A -% \RevName\LYamt & \texttt{\ShowPattern{Yamamoto,Isoroku}} & +% \RevName\LYamt & \texttt{\NameauthPattern} & % \cmd{\RevName}\cmd{\LYamt}\\ % -% \Name{Henry,VIII} & \texttt{\ShowPattern{Henry,VIII}} & +% \Name{Henry,VIII} & \texttt{\NameauthPattern} & % \cmd{\Name\{Henry,VIII\}}\\ -% \Name*{Henry}[VIII]\ddag & \texttt{\ShowPattern{Henry,VIII}} & +% \Name*{Henry}[VIII]\ddag & \texttt{\NameauthPattern} & % \cmd{\Name*\{Henry\}[VIII]}\cmd{\ddag}\\ % % \rowcolor{nagrey}^^A -% \Dem[I Soter] & \texttt{\ShowPattern{Demetrius,I}} & \cmd{\Dem[I Soter]}\\ +% \Dem[I Soter] & \texttt{\NameauthPattern} & \cmd{\Dem[I Soter]}\\ % \rowcolor{nagrey}^^A -% \LDem & \texttt{\ShowPattern{Demetrius,I}} & \cmd{\LDem}\\ +% \LDem & \texttt{\NameauthPattern} & \cmd{\LDem}\\ % -% \ForgetThis\Aris & \texttt{\ShowPattern{Aristotle}} & -% \cmd{\ForgetThis}\cmd{\Aris}\\ -% \Aris & \texttt{\ShowPattern{Aristotle}} & -% \cmd{\Aris}\\\bottomrule +% \ForgetThis\Aris & \texttt{\NameauthPattern} & +% \cmd{\ForgetThis}\cmd{\Aris}\\\bottomrule % \end{tabular} -% \end{center} +% \end{Center} % -% 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. Nonwestern 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} +% Six suffixes are added to name patterns to create six ``systems'' or data sets. Regarding their IDs, shown below, see also page~\pageref{page:NameState}. The \texttt{!MN} and \texttt{!NF} systems control name formatting. Macros in Section~\ref{sec:AKA} use the \texttt{!PN} system with formatting. Indexing involves the \texttt{!PN}, \texttt{!PRE}, and \texttt{!TAG} systems. Name tags use the \texttt{!DB} system. +% \begin{Center} % \begin{tabular}{llll}\toprule % \rowcolor{nagrey}^^A -% \bfseries Description & \bfseries Pattern & \bfseries ID & \bfseries Example\\ +% \bfseries Description & \bfseries ID & \bfseries Pattern & \bfseries Notes\\ % -% Front-matter names & \meta{pattern}\texttt{!NF} & -% front & \texttt{\ShowPattern[Adolf]{Harnack}{!NF}}\\ +% Main-matter names & main & \meta{pattern}\texttt{!MN} & +% expands to empty string\\ % -% \rowcolor{nagrey}^^A -% Main-matter names & \meta{pattern}\texttt{!MN} & main & -% \texttt{\ShowPattern[Hideyo]{Noguchi}{!MN}}\\ +% Front-matter names & front & \meta{pattern}\texttt{!NF} & +% expands to empty string\\ % -% Index cross-refs & \meta{pattern}\texttt{!PN} & -% xref & \texttt{\ShowPattern{Yamamoto, Isoroku}{!PN}}\\ +% Index cross-refs & xref & \meta{pattern}\texttt{!PN} & +% expands to empty string\\ % % \rowcolor{nagrey}^^A -% Exclusions & \meta{pattern}\texttt{!PN} & -% excl & (like xref, special value)\\ +% Exclusions & excl & \meta{pattern}\texttt{!PN} & +% expands to exclusion value\\ % -% Index sort tags & \meta{pattern}\texttt{!PRE} & pretag & -% \texttt{\ShowPattern{Henry, VIII}{!PRE}}\\ +% Index sort tags & pretag & \meta{pattern}\texttt{!PRE} & +% expands to tag value\\ % -% \rowcolor{nagrey}^^A -% Index data tags & \meta{pattern}\texttt{!TAG} & -% idxtag & \texttt{\ShowPattern{Demetrius, I}{!TAG}}\\ +% Index tags & idxtag & \meta{pattern}\texttt{!TAG} & +% expands to tag value\\ % -% Name data tags & \meta{pattern}\texttt{!DB} & namedb & -% \texttt{\ShowPattern{Aristotle}{!DB}}\\\bottomrule +% Name tags & namedb & \meta{pattern}\texttt{!DB} & +% expands to tag value\\\bottomrule % \end{tabular} -% \end{center} -% -% Next we see what macros write patterns to what systems. \cmd{\IndexName} does not generate a name pattern. This lets cross-references determine the index control logic. +% \end{Center} % -% \begin{center} +% Next we see how certain macros write patterns to systems, indicated by black boxes. \cmd{\IndexName} does not generate a name pattern; it only creates an index page entry, depending on the cross-references that control the index logic. +% \begin{Center} % \begin{tabular}{lcccccc}\toprule[1pt] % \bfseries Macros & \bfseries \ttfamily \,!NF\, & \bfseries \ttfamily \,!MN\, & % \bfseries \ttfamily \,!PN\, & \bfseries \ttfamily !PRE & @@ -4318,434 +5475,603 @@ and version 1.3 or later is part of all distributions of LaTeX version % \cmd{\ExcludeName} & \NO & \NO & \YES & \NO & \NO & \NO\\ % \cmd{\IncludeName} \cmd{\IncludeName*} & \NO & \NO & \YES & % \NO & \NO & \NO\\\midrule +% \cmd{\IndexName} & \NO & \NO & \NO & \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} +% \end{Center} +% +% \subsection{Name Uniqueness} +% \label{sec:Unique} +% +% We disable indexing for the examples below. Grouping tokens \texttt{\bfseries\{\,\}} do not appear in the text, but they do appear in the name patterns. The same goes for non-printing macros, such as \cmd{\empty}. Thus, all names below are unique, as the ``first-use'' color shows. Even if they look alike in the text, they have different name patterns and different index entries. See also Sections~\ref{sec:NamePatterns}, \ref{sec:Noexpand}, and~\ref{sec:IndexSort}. +% \newcommand\MyType +% {\dotfill\ifNameauthWestern Western name \else Non-Western name\fi} +% \begin{enumerate}\IndexInactive +% \item \Name[one]{two} +% |\Name[one]{two}|\\ +% Pattern: \texttt{\ShowPattern{}} \MyType +% +% \item \Name[{one}]{{two}} +% |\Name[{one}]{{two}}|\footnote{The grouping tokens for the mandatory argument remain, while those of the optional argument go away. This ia a function of the \textsf{xparse} package. If one plugs the arguments directly into \cmd{\@nameauth@LoadArgs} and \cmd{\@nameauth@Choice}, they are not expanded unevenly. Still, the benefits of \textsf{xparse} outweigh the downsides. The takeaway here is to check the name pattern when debugging.}\\ +% Pattern: \texttt{\ShowPattern{}} \MyType +% +% \item \Name[one]{\empty two} +% |\Name[one]{\empty two}|\\ +% Pattern: \texttt{\ShowPattern{}} \MyType +% +% \item \Name{one, two} +% |\Name{one, two}|\\ +% Pattern: \texttt{\ShowPattern{}} \MyType +% +% \item \Name{{one}, {two}} +% |\Name{{one}, {two}}|\\ +% Pattern: \texttt{\ShowPattern{}} \MyType +% +% \item \Name{{one, two}} +% |\Name{{one, two}}|\\ +% Pattern: \texttt{\ShowPattern{}} \dotfill(Malformed \meta{SNN}) +% \end{enumerate}\IndexActive +% \negmedskip +% \begin{InfoBox} +% In \meta{SNN\textbf{,}Affix} apply macros seperately to \meta{SNN} and \meta{Affix}. +% \end{InfoBox} +% +% There are several ways to make different names out of otherwise identical names. They vary in complexity. Among the methods we have: +% \begin{itemize} +% \item Index tags (\cmd{\TagName}, Section~\ref{sec:IdxIdent}) can create different index entries for otherwise identical names. This requires keeping track of the context and where one changes those tags. % -% \subsection{Indexing: States} +% \item Non-printing tokens and macros in name arguments help one to assign unique patterns for similar index and name tags (Sections~~\ref{sec:IdxIdent} and~\ref{sec:DataTags}). This requires one to sort names with \cmd{\PretagName} (Section~\ref{sec:IndexSort}). +% +% \item If such macros are at the leading edge of a name instead of the trailing edge, or if any macros might expand differently at different times, one may need to use \cmd{\noexpand} and alternate formatting (Section~\ref{sec:Noexpand}). +% \end{itemize} +% +% \NameArgWarning +% +% \newpage +% +% \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.\medskip +% Six distinct ``states'' describe any name pattern with respect to page entries and cross-references in the index. While it may seem odd to discuss this here, this information relates directly to \cmd{\ShowNameState}, and these states are not reflected \emph{as such} by the indexing macros. They are derived from a matrix of Boolean flags and control sequences, serving more as a useful debugging mnemonic for package users. Below we show what these states mean.\medskip % % \begin{tcolorbox} % [colback=white,colframe=darkgray, -% adjusted title={\bfseries\hfil State 1: No Name Information Present}] +% adjusted title={\bfseries\hfil \hypertarget{State 1}{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} +% \medskip % % \begin{tcolorbox} % [colback=white,colframe=darkgray, -% adjusted title={\bfseries\hfil State 2: Only a Name Pattern Exists}] +% adjusted title={\bfseries\hfil \hypertarget{State 2}{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} -% -% \begin{Quote}{\Name[Mark]{Twain}, \textit{The Innocents Abroad} (1869)} -% Virtue never has been as respectable as money.^^A -% \index{creatives, quotes of\noexpand\string|hyperpage} -% \end{Quote} +% \medskip % % \begin{tcolorbox} % [colback=white,colframe=darkgray, -% adjusted title={\bfseries\hfil State 3: Only an Xref Pattern Exists}] +% adjusted title={\bfseries\hfil \hypertarget{State 3}{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} +% \medskip % % \begin{tcolorbox} % [colback=white,colframe=darkgray, -% adjusted title={\bfseries\hfil State 4: Both Name and +% adjusted title={\bfseries\hfil \hypertarget{State 4}{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} +% \medskip % % \begin{tcolorbox} % [colback=white,colframe=darkgray, -% adjusted title={\bfseries\hfil State 5: Only an Exclusion Exists}] +% adjusted title={\bfseries\hfil \hypertarget{State 5}{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{Quote}{\Name[W.H.]{Auden}, \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.^^A -% \index{creatives, quotes of\noexpand\string|hyperpage} -% \end{Quote} +% \medskip % % \begin{tcolorbox} % [colback=white,colframe=darkgray, -% adjusted title={\bfseries\hfil State 6: Both Name Pattern and +% adjusted title={\bfseries\hfil \hypertarget{State 6}{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} % \end{tcolorbox} % +% \subsection{Using \texttt{\textbackslash noexpand}} +% \label{sec:Noexpand} +% +% The natural-language approach of \textsf{nameauth}, combined with requirements of indexing, requires strict control over macro expansion. We use \cmd{\noexpand} in name arguments for the following reasons: +% \begin{itemize} +% \item A name uses the hyphenation of a foreign language via macros in name arguments. +% +% \item Name elements change within the local scope of formatting hooks, but remain uniform globally when generating index entries. This is the crux of alternate formatting (Section~\ref{sec:AltFormat}). +% +% \item A name specifically uses the alternate form of \cmd{\CapThis} via alternate formatting (Section~\ref{sec:AltCaps}). +% +% \item There is a possibility that macros in name arguments might expand unpredictably in different situations, resulting in spurious index entries and name pattern tests failing in some cases. +% \end{itemize} +% +% If a macro is undefined, even putting \cmd{\noexpand} before it will cause an error unless the macro is detokenized or verbatim. To avoid some errors, one can apply macros separately to \meta{SNN} and \meta{Affix}: +% \begin{Quote} +% |\Name{\noexpand\MyMacro{|\meta{SNN}|},\noexpand\MyMacro{|\meta{Affix}|}}| +% \end{Quote} +% +% \begin{Quotation}{\Einstein} +% {Letter to \Name[Max]{Born}, 4 December 1928} +% \de{Die Quantenmechanik ist sehr achtunggebietend. Aber eine innere +% Stimme sagt mir, daß das noch nicht der wahre Jakob ist. Die Theorie +% liefert viel, aber dem Geheimnis des Alten bringt sie uns kaum näher. +% Jedenfalls bin ich überzeugt, daß der nicht würfelt.} +% +% (Quantum mechanics is quite significant. But an inner voice tells me +% that it is not yet the right [path]. The theory delivers much, but +% it brings us hardly any closer to the secret of the Ancient of Days. +% In any case, I am convinced that He does not throw dice.) +% \index{scientists, quotes of\noexpand\string|hyperpage} +% \end{Quotation} +% +% \newpage +% % \subsection{Debugging Macros} % \label{sec:DebuggingMacros} % +% These macros never grant users access to the full internal name patterns used by \textsf{nameauth}, but they do query those patterns. These macros help users identify how their intent to use the naming and other macros correlates with what the macros are seeing as input and how they are functioning. +% % \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: +% Although \cmd{\NameauthPattern} is useful in hooks when you want the pattern of the last name evaluated, \cmd{\ShowPattern} offers both that function, when called with a null argument, as well as the ability to display any pattern according to the name arguments provided to it: % % \begin{SyntaxBox} -% \cmd{\ShowPattern}\oarg{FNN}\marg{SNN|,| Affix}\oarg{Alternate} +% \cmd{\ShowPattern}\oarg{FNN}\marg{SNN\textbf{,}Affix}\oarg{Alternate}\\ +% \cmd{\ShowPattern\{\}} % \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}. +% \begin{itemize} +% \item Let us refer to the name \LAeth. \cmd{\ShowPattern\{\}} now gives us the pattern: \ShowPattern{}. \cmd{\NameauthPattern} also: \NameauthPattern.\footnote{This again is due to using \textsf{inputenc} and \textsf{fontenc}.} +% +% \item |\ShowPattern[Hernando]{de~Soto}| prints: \ShowPattern[Hernando]{de~Soto}\JustIndex\Soto. Since the name arguments were evaluated, now \cmd{\ShowPattern\{\}} gives us the pattern: \ShowPattern{}. +% +% \item Section~\ref{sec:NameArgMacros} lists all the macros that change the current name pattern. +% \end{itemize} % % \DescribeMacro{\ShowIdxPageref} -% \cmd{\ShowIdxPageref} displays a full index entry in the text as if it were only a page entry, not a cross-reference. +% \cmd{\ShowIdxPageref} shows how macro arguments generate an index page reference, regardless of whether or not that page reference or cross-reference actually exists. Internally, it puts the indexing mechanism into a state that will print a full page reference in the text. % % \begin{SyntaxBox} -% \cmd{\ShowIdxPageref\ }\oarg{FNN}\marg{SNN|,| Affix}\oarg{Alternate} +% \cmd{\ShowIdxPageref\ }\oarg{FNN}\marg{SNN\textbf{,}Affix}\oarg{Alternate}\\ +% \cmd{\ShowIdxPageref\{\}} % \end{SyntaxBox} % -% 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 a sort tag (Section~\ref{sec:IndexSort}), we get the following: -% -% \begin{quote} -% |\PretagName[Hernando]{de~Soto}{Desoto, Hernando}| -% -% \IndexActual{@}\UntagName[Hernando]{de~Soto} -% |\ShowIdxPageref[Hernando]{de~Soto}|\\ -% \ShowIdxPageref[Hernando]{de~Soto} -% \end{quote} +% Index styles, \cmd{\PretagName}, and \cmd{\TagName} affect the output of \cmd{\ShowIdxPageref}. Active characters and macros appear as they would be printed in the text, not as they may be represented in the \texttt{idx} file. One should check that too when debugging. % -% We could not create index entries within the quote above in this \texttt{dtx} file because we changed \cmd{\IndexActual}. A \texttt{dtx} file uses a different default for \cmd{\IndexActual} (see Section~\ref{sec:IndexTag}). Here we get instead: +% In a normal \LaTeX\ document, for example, if we mention \LSoto\ after setting up a sort tag (Section~\ref{sec:IndexSort}), we get the following: +% \begin{Quote} +% \IndexActual{@} +% \UntagName[Hernando]{de~Soto} +% \ShowIdxPageref{} % -% \begin{quote} % |\PretagName[Hernando]{de~Soto}{Desoto, Hernando}|\\ -% \verb+\TagName[Hernando]{de~Soto}{\string|hyperpage}+ +% |\ShowIdxPageref[Hernando]{de~Soto}| +% \end{Quote} % -% \TagName[Hernando]{de~Soto}{\string|hyperpage} +% A \texttt{dtx} file uses a different default for \cmd{\IndexActual} (Section~\ref{sec:IndexSort}). Since we tag all names in this \texttt{dtx} file with \cmd{\TagName} to have hyperlinked index page references (Section~\ref{sec:IndexTag}), we instead have here: +% \begin{Quote} % \IndexActual{=} -% |\ShowIdxPageref[Hernando]{de~Soto}|\\ -% \ShowIdxPageref[Hernando]{de~Soto} -% \end{quote} +% \TagName[Hernando]{de~Soto}{\string|hyperpage} +% \ShowIdxPageref{} +% +% |\ShowIdxPageref[Hernando]{de~Soto}| +% \end{Quote} +% +% \newpage % % \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} +% \cmd{\ShowIdxPageref*}\oarg{FNN}\marg{SNN\textbf{,}Affix}\oarg{Alternate}\\ +% \cmd{\ShowIdxPageref*\{\}} % \end{SyntaxBox} % % Regardless of whether we have a normal \LaTeX\ document or a \texttt{dtx} file, we get:\JustIndex\Soto -% -% \begin{quote} +% \begin{Quote} % |\ShowIdxPageref*[Hernando]{de~Soto}|\\ -% \ShowIdxPageref*[Hernando]{de~Soto} -% \end{quote} +% \ShowIdxPageref*{} +% \end{Quote} % % \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. +% Here we can see how the macros that take name arguments interpret them. We can check our intent against what the package actually sees as input. When we use a null argument, \cmd{\ShowNameInfo} uses the token registers that contain the arguments of the last name arguments that were evaluated. % % \begin{SyntaxBox} -% \cmd{\ShowNameInfo}\oarg{FNN}\marg{SNN|,| Affix}\oarg{Alternate} +% \cmd{\ShowNameInfo}\oarg{FNN}\marg{SNN\textbf{,}Affix}\oarg{Alternate}\\ +% \cmd{\ShowNameInfo\{\}} % \end{SyntaxBox} % -% 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}. -% +% Next we use \cmd{\ShowNameInfo} to illustrate detokenized name arguments from a number of names. This approach both prevents potential errors and discloses macros in name arguments. The ``Affix*'' and ``Alt*'' designations have an asterisk because, while those are the syntactic terms that describe name macro arguments, those terms do not describe the exact cultural meaning of their contents. % \begin{itemize}\small -% \item \Name*[J.E.]{Carter, Jr.}[James Earl]\dotfill^^A +% \item \Name*[J.E.]{Carter, Jr.}[James Earl]\dotfill^^A % |\Name*[J.E.]{Carter, Jr.}[James Earl]| -% \item[] |\ShowNameInfo[J.E.]{Carter, Jr.}[James Earl]|:\\ -% \ShowNameInfo[J.E.]{Carter, Jr.}[James Earl] +% \item[] \ShowNameInfo{} % -% \item \Name*{Miyazaki, Hayao}[Sensei]\dotfill^^A +% \item \Name*{Miyazaki, Hayao}[Sensei]\dotfill^^A % |\Name*{Miyazaki, Hayao}[Sensei]| -% \item[] |\ShowNameInfo{Miyazaki, Hayao}[Sensei]|:\\ -% \ShowNameInfo{Miyazaki, Hayao}[Sensei] +% \item[] \ShowNameInfo{} % -% \item \Name*{Elizabeth, I}[I, ``Gloriana'']\dotfill^^A +% \item \Name*{Elizabeth, I}[I, ``Gloriana'']\dotfill^^A % |\Name*{Elizabeth, I}[I, ``Gloriana'']| -% \item[] |\ShowNameInfo{Elizabeth, I}[I, ``Gloriana'']|:\\ -% \ShowNameInfo{Elizabeth, I}[I, ``Gloriana''] +% \item[] \ShowNameInfo{} % -% \item \Name*{Henry}[VIII]\ddag\dotfill |\Name*{Henry}[VIII]\ddag| -% \item[] |\ShowNameInfo{Henry}[VIII]| (obsolete syntax):\\ -% \ShowNameInfo{Henry}[VIII] +% \item \Name*{Henry}[VIII]\ddag\dotfill |\Name*{Henry}[VIII]\ddag| +% \item[] \ShowNameInfo{} % -% \item \Name*{Confucius}\dotfill |\Name*{Confucius}| -% \item[] |\ShowNameInfo{Confucius}|:\\ -% \ShowNameInfo{Confucius} +% \item \Name*{Confucius}\dotfill |\Name*{Confucius}| +% \item[] \ShowNameInfo{} % \end{itemize} % -% For the following examples we activate alternate formatting -% (Section~\ref{sec:AltFormat}), which permits typesetting more complex name forms seen in European academic writing. This use of small caps may generate harmless font substitution warnings. +% \NameArgWarning % -% \AltFormatActive -% \begin{itemize}\small -% \item \ForgetThis\LStriet\\ -% |\ForgetThis\Name[John]{\noexpand\de{Strietelmeier}| -% \item[] |\ShowNameInfo[John]{\noexpand\de{Strietelmeier}}|:\\ -% \ShowNameInfo[John]{\noexpand\de{Strietelmeier}} -% -% \item \Cath\\ -% |\Name[Catherine \noexpand\AltCaps{d}e']{\noexpand\textSC{Medici}}| -% \item[] |\ShowNameInfo[Catherine \noexpand\AltCaps{d}e']|\\ -% |{\noexpand\textSC{Medici}}|:\\ -% \ShowNameInfo[Catherine \noexpand\AltCaps{d}e']{\noexpand\textSC{Medici}} -% -% \item \Luth\\ -% |\Name[Martin]{\noexpand\textSC{Luther}}| -% \item[] |\ShowNameInfo[Martin]{\noexpand\textSC{Luther}}|:\\ -% \ShowNameInfo[Martin]{\noexpand\textSC{Luther}} -% -% \item Using \cmd{\noexpand} before macros in name arguments ``fixates'' them, ensuring consistency (important for name patterns and the index): -% \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}} +% When using macros in name arguments, \cmd{\ShowNameInfo} may give different results, depending on the use of \cmd{\noexpand} and the name interface. Macros in name arguments may be displayed with trailing spaces because \textsf{nameauth} uses \cmd{\protected@edef} when parsing name elements. We show how to mitigate these issues. In the following name examples, we assume that the \cmd{\de} macro was defined to use \textsf{babel}, as in Section~\ref{sec:HyphNames}. +% \begin{itemize}\footnotesize +% \item The macro in these arguments expands, which can change name patterns. +% \item[] \ShowNameInfo[John]{\de{Strietelmeier}}\\ +% |\ShowNameInfo[John]{\de{Strietelmeier}}| +% +% \item The macro in these arguments stays consistent due to \cmd{\noexpand}. +% \item[] \ShowNameInfo[John]{\noexpand\de{Strietelmeier}}\\ +% |\ShowNameInfo[John]{\noexpand\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{Quote} +% \begin{Verbatim} +% \begin{nameauth} +% \< Striet & John & \noexpand\de{Strietelmeier} & > +% \end{nameauth} +% \NameAddInfo[John]{\noexpand\de{Strietelmeier}} +% {professor} +% \end{Verbatim} +% \end{Quote} +% +% \NameAddInfo[John]{\noexpand\de{Strietelmeier}} +% {professor} % \begin{itemize} -% \item |\ShowNameInfo{\noexpand\SomeUndefinedMacro}| -% \item[] \ShowNameInfo{\noexpand\SomeUndefinedMacro} -% \end{itemize} +% \item \ForgetThis \Striet\dotfill \cmd{\Striet}\\ +% With the first use of the name, we note the info. +% \begin{itemize} +% \item \NameQueryInfo{}\dotfill |\NameQueryInfo{}| +% \item \ShowPattern{}\dotfill |\ShowPattern{}| +% \item \ShowNameInfo{}\dotfill |\ShowNameInfo{}| +% \end{itemize} +% +% \item \Striet\dotfill \cmd{\Striet}\\ +% The name is repeated; the same pattern recurs. +% \begin{itemize} +% \item \NameQueryInfo{}\dotfill |\NameQueryInfo{}| +% \item \ShowPattern{}\dotfill |\ShowPattern{}| +% \item \ShowNameInfo{}\dotfill |\ShowNameInfo{}| +% \end{itemize} +% +% \item \Name[John]{\noexpand\de{Strietelmeier}}\dotfill^^A +% |\Name[John]{\noexpand\de{Strietelmeier}}|\\ +% We use the same name again, but with the basic interface. +% The name pattern still works, but \cmd{\ShowNameInfo} +% expands the arguments after pulling them from the internal +% token registers. We no longer refer to these registers for +% use in customization in order to avoid errors. +% \begin{itemize}\footnotesize +% \item \NameQueryInfo{}\dotfill |\NameQueryInfo{}| +% \item \ShowPattern{}\dotfill |\ShowPattern{}| +% \item \ShowNameInfo{}\\ +% |\ShowNameInfo{}| +% \end{itemize} +% +% \item \Name[John]{\noexpand\de{Strietelmeier}}\dotfill^^A +% |\Name[John]{\noexpand\de{Strietelmeier}}|\\ +% This expansion is hidden when using full name arguments everywhere. +% \begin{itemize} +% \item \NameQueryInfo[John]{\noexpand\de{Strietelmeier}}\\ +% |\NameQueryInfo[John]{\noexpand\de{Strietelmeier}}| +% \item \ShowPattern[John]{\noexpand\de{Strietelmeier}}\\ +% |\ShowPattern[John]{\noexpand\de{Strietelmeier}}| +% \item \ShowNameInfo[John]{\noexpand\de{Strietelmeier}}\\ +% |\ShowNameInfo[John]{\noexpand\de{Strietelmeier}}| +% \end{itemize} % \end{itemize} -% \AltFormatInactive -% \negbigskip % -% \NameArgWarning +% Thus, we rely on \cmd{\NameauthPattern} for name-related information instead of re-parsing name arguments. That is how recent versions of \cmd{\NameQueryInfo} work, simplifying the use of name tags in formatting hooks (Sections~\ref{sec:DataTags} and~\ref{sec:DataTagHooks}). +% +% \newpage +% +% Below we activate alternate formatting (Section~\ref{sec:AltFormat}) and use name forms seen in European academic writing. +% \begin{AltFormatZone} +% \begin{itemize} +% \item \ForgetThis \Cath +% \item[] \ShowNameInfo{} +% +% \item \ForgetThis \Luth +% \item[] \ShowNameInfo{} +% \end{itemize} +% \end{AltFormatZone} % % \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: +% With these macros we can see in plain text the name pattern, the name type, the current index state of the name, +% \DescribeMacro{\ShowNameState*} +% and all the systems with which its pattern is associated. The un-starred form prints the information in one long line of text. The starred form prints five shorter lines of text, each ending with |\par|. As with other macros in this section, these macros can have null arguments. % % \begin{SyntaxBox} -% \cmd{\ShowNameState}\oarg{FNN}\marg{SNN|,| Affix}\oarg{Alternate} +% \cmd{\ShowNameState}\oarg{FNN}\marg{SNN\textbf{,}Affix}\oarg{Alternate}\\ +% \cmd{\ShowNameState\{\}}\\[1ex] +% \cmd{\ShowNameState*}\oarg{FNN}\marg{SNN\textbf{,}Affix}\oarg{Alternate}\\ +% \cmd{\ShowNameState*\{\}} % \end{SyntaxBox} -% -% \cmd{\ShowNameState} produces a line of text with the following information: -% -% \begin{itemize} -% \item Base name pattern, the base control pattern that -% \textsf{nameauth} sees. This would be the output of \cmd{\ShowPattern}. -% \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 :] nonwestern (regardless of whether it is reversed)\\ -% current syntax -% \item[nw,os :] nonwestern name, obsolete syntax (Section~\ref{sec:Obsolete}) +% Here is the key to understanding the output of these macros: +% \begin{itemize}[leftmargin=4.3em] +% \item[Pattern:] The base name pattern shown by \cmd{\NameauthPattern}. +% +% \item[Type:] The category of the name; how the name arguments were parsed: +% \begin{itemize}[leftmargin=4.6em] +% \item[w :] Western name +% \item[nw :] Non-Western name, current syntax +% \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[State:] The index state, as defined in Section~\ref{sec:RuleStates}: +% \begin{itemize}[leftmargin=4.6em] % \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:] All the control systems (Section~\ref{sec:NamePatterns}) that the name pattern inhabits, including front matter, main matter, cross-references, excluded cross-references, index sorting tags, index tags, and name database tags: +% \begin{itemize}[leftmargin=4.6em] % \item[systems :] front, main, xref, excl, pretag, idxtag, namedb. % \end{itemize} % \end{itemize} -% -% In the next example we show names in indexing states from one to six, and we illustrate all name types and many of the control systems. All extant names have index tags due to being used in a \texttt{dtx} file with the \textsf{ltxdoc} class and the \textsf{hypdoc} package (Section~\ref{sec:SpecialTag}). Otherwise, names need not always have a control pattern in the \texttt{idxtag} system. -% +% We begin by showing info about some unused names that will not appear in the index. We add margin notes using \cmd{\ShowNameState*}, while using \cmd{\ShowNameState} in the body text. % \begin{itemize} -% \item Some yet unused name:\dotfill |\ShowNameState{Not Seen, Yet}|\\ -% \ShowNameState{Not Seen, Yet} +% \item |\ShowNameState[Hieronymus]{Bosch}|\\ +% \ShowNameState[Hieronymus]{Bosch} +% \Info[-11.5ex]{\ShowNameState*{}} +% \item |\ShowNameState{Tamerlane}|\\ +% \ShowNameState{Tamerlane} +% \Info[-7.5ex]{\ShowNameState*{}} +% \end{itemize} % -% \item New and extant names: +% \newpage +% +% Now we display the info for new and extant names in the text.\footnote{In a \texttt{dtx} file, with the \textsf{ltxdoc} class and \textsf{hypdoc} package, we tag all names in the index with hyperlinks (Section~\ref{sec:SpecialTag}). Otherwise, names need not have a pattern in the \texttt{idxtag} system.} % \begin{itemize} % \item \Name*[Rudolph]{Carnap}\dotfill |\Name*[Rudolph]{Carnap}|\\ -% \ShowNameState[Rudolph]{Carnap} +% \ShowNameState{} +% \Info[-9ex]{\ShowNameState*{}} % % \item \Name*{Henry, VIII}\dotfill |\Name*{Henry, VIII}|\\ -% \ShowNameState{Henry, VIII} -% -% \item \Name*{Henry}[VIII]\ddag\dotfill |\Name*{Henry}[VIII]\ddag|\\ -% \ShowNameState{Henry}[VIII] -% -% \item \Name*{Thomas, à~Kempis}\dotfill |\Name*{Thomas, à~Kempis}|\\ -% \ShowNameState{Thomas, à~Kempis} +% \ShowNameState{} +% \Info[-5.5ex]{\ShowNameState*{}} +% +% \item \NamesInactive\Name*{Henry}[VIII]\ddag\NamesActive \dotfill^^A +% |\NamesInactive|\\ +% \hbox{}\hfill|\Name*{Henry}[VIII]\ddag|\\ +% \hbox{}\hfill|\NamesActive|\\ +% \ShowNameState{} +% \Info[-7.5ex]{\ShowNameState*{}} +% +% \item \Name*{Thomas, à~Kempis}\dotfill |\Name*{Thomas, à~Kempis}| +% \item[] \ShowNameState{}\footnote{This again is due to using \textsf{inputenc} and \textsf{fontenc}.} +% \Info[-8ex]{\ShowNameState*{}} % \end{itemize} -% -% \item Name used only in xref:\dotfill^^A -% |\IndexRef{Sun King}{Louis XIV}|\IndexRef{Sun King}{Louis XIV}\\ -% \ShowNameState{Sun King} -% -% \item Name used after xref exists:\\ -% \Name*{Sun King}\dotfill |\Name*{Sun King}|\\ +% Here is a name used only in a cross-reference:\footnote{Here we should populate the name arguments because the name has not appeared in the text.} +% \begin{itemize} +% \item |\IndexRef{Sun King}{Louis XIV}|\IndexRef{Sun King}{Louis XIV}\\ % \ShowNameState{Sun King} -% -% \item Unused name excluded from index:\dotfill^^A -% \ExcludeName{Santa, Claus}|\ExcludeName{Santa, Claus}|\\ +% \Info[-7ex]{\ShowNameState*{}} +% \end{itemize} +% Next is a name displayed after a cross-reference exists:\footnote{If the name is printed and \cmd{\ShowNameState} follows immediately, we can use a null argument.} +% \begin{itemize} +% \item \Name*{Sun King}\dotfill |\Name*{Sun King}|\\ +% \ShowNameState{} +% \Info[-7.5ex]{\ShowNameState*{}} +% \end{itemize} +% The following is an unused name excluded from the index:\footnote{Here we should populate the name arguments because the name has not appeared in the text.} +% \begin{itemize} +% \item |\ExcludeName{Santa, Claus}|\ExcludeName{Santa, Claus}\\ % \ShowNameState{Santa, Claus} -% -% \item Previously excluded name gets used:\\ -% \Name*{Thomas,\`a~Kempis}\dotfill |\Name*{Thomas,\`a~Kempis}|\\ -% \ShowNameState{Thomas,\`a~Kempis} +% \Info[-7.5ex]{\ShowNameState*{}} +% \end{itemize} +% Finally we have a previously excluded name used in the text:\footnote{If the name is printed and \cmd{\ShowNameState} follows immediately, we can use a null argument.} +% \begin{itemize} +% \item \Name{Santa, Claus}\dotfill |\Name{Santa, Claus}|\\ +% \ShowNameState{} +% \Info[-7.5ex]{\ShowNameState*{}} % \end{itemize} -% \negbigskip % -% \ReturnLink\smallskip +% \ReturnLink % -% \AltFormatActive -% \begin{Quote}{\ForgetThis\Luth\break -% \hbox{}\hfill \textit{\de{Von der Freiheit eines Christenmenschen}} (1520)} -% \de{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.} -% -% (A Christian person is a free lord, above all things, and subject to no one. A Christian person is a willing servant of all things and is subject to -% everyone.)^^A -% \index{theologians, quotes of\noexpand\string|hyperpage} -% \end{Quote} -% \AltFormatInactive +% \begin{Quotation}{\Name[L.M.]{Montgomery}} +% {\Title{Anne of Green Gables}, C 5 (1908)} +% 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. +% \index{creatives, quotes of\noexpand\string|hyperpage} +% \index{Rose, references to\noexpand\string|hyperpage} +% \end{Quotation} % % \newpage % % \section{Indexing Macros} % \label{sec:Indexing} -% \IndexWarnVerbose % -% Indexing pulls together all the concepts from the previous sections, yet applies them to the index. In this section we enable (and trigger) verbose index warnings. +% This section draws on what we have seen so far and applies that knowledge to creating indexes of names via the \textsf{nameauth} package macros, not indexing in general. % -% \subsection[General Control]{General Indexing Control} +% \subsection{General Control} % \label{sec:GeneralIndex} % +% Before we get to the topics of index entries and cross-references, we cover those macros that globally affect the indexing of names. +% % \subsubsection{Toggle Indexing} % % \DescribeMacro{\IndexInactive} % \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. They do not affect indexing apart from \textsf{nameauth}. -% +% \cmd{\IndexActive} enables indexing. These can be used throughout the document. They do not affect indexing apart from \textsf{nameauth} names. % \begin{itemize} -% \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}. +% \item \cmd{\IndexInactive} broadly suppresses \cmd{\IndexName}, \cmd{\IndexRef}, and the indexing components of naming macros, \cmd{\AKA}, and \cmd{\PName}. +% +% \item For a fine degree of control, see Section~\ref{sec:IdxFine}. % \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 (Section~\ref{sec:Priorities}). Use \cmd{\global} to force a global effect. +% \Global \cmd{\IndexActive} 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. % % \subsubsection{Multiple Indexes} % % \DescribeMacro{\NameauthIndex} -% \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. -% \vspace{3ex} -% \Info{\hrule\strut Test indexing rules:\break +% \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 redefine this hook for use with multiple indexes. Below we use the \textsf{index} package to do this. +% \Info[4ex]{\hrule\strut Here we test indexing rules:\break % \Name{Yamaha, Torakusu}\label{page:Idx1}\break % create index entry:\break -% \cmd{\IndexName}\break -% \texttt{\{Nippon Gakki\}}\IndexName{Nippon Gakki}\strut\hrule} -% \vspace{-3ex} -% +% \cmd{\IndexName}\texttt{\{Nippon Gakki\}}\IndexName{Nippon Gakki}\strut\hrule} +%^^A % \ifdefined\NameauthDoTestFiles \edef\NameauthTestFile{test07_01.tex}\else % \edef\NameauthTestFile{\jobname.tmp}\fi -% +%^^A % \begin{VerbatimOut}{\NameauthTestFile} % \documentclass{article} -% \input{compat.tex} % Included with nameauth; example file aids -% % compatibility across different LaTeX versions and engines. +% \input{compat.tex} % Included with nameauth for compatibility. % % \usepackage{makeidx} % Must have for defining \seealso macro. % \usepackage{index} @@ -4756,8 +6082,8 @@ and version 1.3 or later is part of all distributions of LaTeX version % \renewcommand*\NameauthIndex{\index[per]} % % \begin{document} -% The Electric Boogaloo\index{Boogaloo, Electric}\\ % main index -% was created by \Name{Ollie~\& Jerry}. % name index +% The Electric Boogaloo\index{Boogaloo, Electric} % main index +% was created by \Name{Ollie~\& Jerry}. % name index % % \printindex[per] % Shows the entry: Ollie & Jerry, 1 % @@ -4765,49 +6091,39 @@ and version 1.3 or later is part of all distributions of LaTeX version % \printindex % Shows the entry: Boogaloo, Electric, 1 % \end{document} % \end{VerbatimOut} -% -% \begin{quote} +%^^A +% \begin{Quote} % \VerbatimInput[gobble=0]{\NameauthTestFile} -% \end{quote} +% \end{Quote} +% +% \newpage % % \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). +% 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. -% -% \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. +% To disable verbose warnings, use \cmd{\IndexWarnTerse}. To enable verbose warnings, use the \texttt{verbose} option or \cmd{\IndexWarnVerbose}. +% +% \Global \cmd{\IndexWarnVerbose} 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. -% % One can use \cmd{\IndexProtect} right before \cmd{\printindex} to protect the index against bogus output. For example: -% -% \vspace{4ex} -% \Info{\hrule\strut Test indexing rules:\break +% \Info[4ex]{\hrule\strut Here we test indexing rules:\break % \Name{Yamaha, Torakusu}\label{page:Idx2}\strut\hrule} -% \vspace{-4ex} % \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. +% \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 of \LaTeX\ and \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.\footnote{We add the index tag \S\ to this example to show that it is a made-up name.} % \end{itemize} % % \subsection{Page Entries} @@ -4817,25 +6133,20 @@ and version 1.3 or later is part of all distributions of LaTeX version % 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. % % \begin{SyntaxBox} -% \cmd{\IndexName}\oarg{FNN}\marg{SNN|,| Affix}\oarg{Alternate} +% \cmd{\IndexName}\oarg{FNN}\marg{SNN\textbf{,}Affix}\oarg{Alternate} % \end{SyntaxBox} % -% 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 nonwestern syntax (Section~\ref{sec:Obsolete}). Indexing follows [\hyperlink{Mulvany}{Mulvany}, 152--82]. The points below deal with macros explained in Section~\ref{sec:IdxPrefix}. -% +% 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 guidelines in [\hyperlink{Mulvany}{Mulvany}, 152--82]. The following points also deal with macros explained in Section~\ref{sec:IdxPrefix}. % \begin{itemize} -% \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}. +% \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} % % \subsection{Cross-References} @@ -4849,98 +6160,86 @@ and version 1.3 or later is part of all distributions of LaTeX version % 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} +% \phantom{\cmd{\SeeAlso}}\cmd{\IndexRef}\oarg{FNN}\marg{SNN^^A +% \textbf{,}Affix}\oarg{Alt.}\marg{Target}\\ +% \cmd{\SeeAlso}\cmd{\IndexRef}\oarg{FNN}\marg{SNN^^A +% \textbf{,}Affix}\oarg{Alt.}\marg{Target} % \end{SyntaxBox} % % Although it might be redundant to point this out, in practice, when using \cmd{\IndexName} and \cmd{\IndexRef}, one might forget that the latter has four arguments, at least two of which are required. Missing text and bad xrefs can result. -% % \begin{itemize} -% \item Define \textit{see} references \emph{before} making any -% \cmd{\Name} entries for them. -% \vspace{-1ex} -% \Info{\hrule\strut Test indexing rules:\break +% \item Define \textit{see} references \emph{before} making any \cmd{\Name} entries for them. +% +% \Info[-2ex]{\hrule\strut Here we 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}\strut\hrule} -% \vspace{1ex} -% \item Define \textit{see also} references \emph{after} all -% \cmd{\Name} instances to the respective names have been created. +% +% \item Define \textit{see also} references \emph{after} all \cmd{\Name} instances 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}. +% +% \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 pattern, unless one uses the \texttt{oldsee} option. See Section~\ref{sec:RuleStates} for a state diagram that explains this in detail. A page entry usually correlates with a name pattern, but that may not always be the case. We check for a control sequence (name pattern). +% +% \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}. +% +% \item To manage multiple sub-entries, see Section~\ref{sec:CatSub}. % \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: +% \newpage % -% \begin{quote} -% \vspace{3ex} -% \Info{\strut\footnotesize Name Pattern(s):\hfill -% \break\ttfamily\ShowPattern{Sun King}!PN} -% \vspace{-3ex} +% \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} +% \PatInfo[3.5ex]{\ShowPattern{Sun King}!PN} % \begin{tabular}{ll} % 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} +% \end{Quote} % % \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} +% \begin{Quote} % \begin{tabular}{ll} % source: & |\IndexRef{bar}{baz; foo}|\\[0.5ex] % index: & bar, \textit{see} baz; foo\\ % \end{tabular} -% \end{quote} -% -% \newpage +% \end{Quote} % % \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. +% The index control logic for cross-references can establish fine-grained control that excludes individual names. We trade more macros for more automation. % % \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} +% \cmd{\ExcludeName}\oarg{FNN}\marg{SNN\textbf{,}Affix}\oarg{Alternate} % \end{SyntaxBox} % -% Unlike \cmd{\IndexInactive} and \cmd{\IndexActive}, which prevent and permit all indexing, \cmd{\ExcludeName} only excludes a specific name from being printed as a page entry 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: -% +% Unlike \cmd{\IndexInactive} and \cmd{\IndexActive}, which affect all \textsf{nameauth} indexing, \cmd{\ExcludeName} only excludes a specific name from being printed as a page entry 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: +%^^A % \begin{VerbatimOut}{\jobname.tmp} % \ExcludeName{Mr. Baseball} % In this example we cannot get page entries for % \Name{Mr. Baseball}, the nickname of % \Name[Bob]{Uecker}, because it was excluded. % \end{VerbatimOut} -% -% \begin{quote} -% \vspace{3ex} -% \PatInfo{\ShowPattern{Mr. Baseball}!PN\break +%^^A +% \begin{Quote} +% \PatInfo[4ex]{\ShowPattern{Mr. Baseball}!PN\break % \ShowPattern[Bob]{Uecker}!MN} -% \vspace{-3ex} % \VerbatimInput[gobble=0]{\jobname.tmp} % % \input{\jobname.tmp} -% \end{quote} +% \end{Quote} % % \DescribeMacro{\IncludeName} % Use the following macros to break a few indexing rules. They remove protections used for exclusion and cross-referencing. @@ -4948,18 +6247,14 @@ and version 1.3 or later is part of all distributions of LaTeX version % They have the same syntax as \cmd{\ExcludeName}: % % \begin{SyntaxBox} -% \cmd{\IncludeName\ }\oarg{FNN}\marg{SNN|,| Affix}\oarg{Alternate}\\ -% \cmd{\IncludeName*}\oarg{FNN}\marg{SNN|,| Affix}\oarg{Alternate} +% \cmd{\IncludeName\ }\oarg{FNN}\marg{SNN\textbf{,}Affix}\oarg{Alternate}\\ +% \cmd{\IncludeName*}\oarg{FNN}\marg{SNN\textbf{,}Affix}\oarg{Alternate} % \end{SyntaxBox} % % \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 entries to a name in the index that had been used as a cross-reference. % -% 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. -% \vspace{3ex} -% \Info{\hrule\strut Test indexing rules:\break -% \Name{Yamaha, Torakusu}\label{page:Idx4}\strut\hrule} -% \vspace{-3ex} -% +% Analogously, \cmd{\ForgetName} (Section~\ref{sec:NameControl}) removes name 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}). +%^^A % \begin{VerbatimOut}{\jobname.tmp} % \begin{itemize} % \item \Name*{Mr. Baseball} is @@ -4990,23 +6285,23 @@ and version 1.3 or later is part of all distributions of LaTeX version % {\meta{an xref}}{\meta{a name}}{\meta{excluded}}. % \end{itemize} % \end{VerbatimOut} -% -% \begin{quote} +%^^A +% \begin{Quote} +% \Info[3ex]{\hrule\strut Here we test indexing rules:\break +% \Name{Yamaha, Torakusu}\label{page:Idx4}\strut\hrule} % \VerbatimInput[gobble=0]{\jobname.tmp} -% +% % \input{\jobname.tmp} -% \end{quote} +% \end{Quote} % -% Cross-references get more protection than exclusions: -% \vspace{-1ex} -% \PatInfo{\ShowPattern[J.D.]{Rockefeller, IV}!MN\break +% Cross-references get more protection than exclusions: +% \PatInfo[3ex]{\ShowPattern[J.D.]{Rockefeller, IV}!MN\break % \ShowPattern[Jay]{Rockefeller}!PN\break % \ShowPattern[Jay]{Rockefeller}!MN} -% \vspace{1ex} % \begin{VerbatimOut}{\jobname.tmp} % \begin{itemize} % \item \DropAffix\LJRIV[Jay] was indexed as -% ``\ShowIdxPageref*[J.D.]{Rockefeller, IV}. +% ``\ShowIdxPageref*[J.D.]{Rockefeller, IV}.'' % % \item We create the % xref\IndexRef[Jay]{Rockefeller}{Rockefeller, J.D., IV}. @@ -5023,12 +6318,12 @@ and version 1.3 or later is part of all distributions of LaTeX version % and create page entries. % \end{itemize} % \end{VerbatimOut} -% -% \begin{quote} +%^^A +% \begin{Quote} % \VerbatimInput[gobble=0]{\jobname.tmp} -% +% % \input{\jobname.tmp} -% \end{quote} +% \end{Quote} % % \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 entries to be made for the other sub-entries of that name or for the name itself. See Section~\ref{sec:CatSub}. @@ -5041,11 +6336,9 @@ and version 1.3 or later is part of all distributions of LaTeX version % % \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. -% \vspace{3ex} -% \Info{\hrule\strut Test indexing rules:\break +%^^A +% \Info[3ex]{\hrule\strut Here we test indexing rules:\break % \Name{Nippon Gakki}\label{page:Idx5}\strut\hrule} -% \vspace{-3ex} -% % \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 @@ -5055,36 +6348,29 @@ and version 1.3 or later is part of all distributions of LaTeX version % \SeeAlso\IndexRef[the]{Rat Pack} % {Davis, Sammy, Jr.; Martin, Dean; Sinatra, Frank} % \end{VerbatimOut} -% -% \begin{quote} +%^^A +% \begin{Quote} % \VerbatimInput[gobble=0]{\jobname.tmp} % % \input{\jobname.tmp} -% \end{quote} +% \end{Quote} % % 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. % % \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 Unless the \texttt{oldreset} option is used, both \cmd{\IndexName} -% and \cmd{\IndexRef} issue warnings if \cmd{\SkipIndex} precedes them. -% Then, both \cmd{\IndexName} and \cmd{\IndexRef} ignore \cmd{\SkipIndex} -% and reset its flag. +% \item Unless the \texttt{oldreset} option is used, both \cmd{\IndexName} and \cmd{\IndexRef} issue warnings if \cmd{\SkipIndex} precedes them. Then, both \cmd{\IndexName} and \cmd{\IndexRef} ignore \cmd{\SkipIndex} and reset its flag. % -% \item 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. +% \item 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} % % \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} +% \begin{Center} % \begin{tabular}{lll}\toprule % \rowcolor{nagrey}^^A -% \bfseries Option & \bfseries Output & \bfseries Source\\ +% \bfseries Option & \bfseries Text & \bfseries Macros\\ % % default & \JustIndex\SWash \Wash & |\JustIndex\SWash \Wash|\\ % @@ -5099,150 +6385,188 @@ and version 1.3 or later is part of all distributions of LaTeX version % |\JustIndex\LWash \Wash|\\\bottomrule % \makeatletter\global\@nameauth@OldPassfalse\makeatother^^A % \end{tabular} -% \vspace{-16ex}\PatInfo{\ShowPattern[George]{Washington}!MN}\vspace{14ex} -% \end{center} +% \end{Center} % % There are 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} resets the flags set by \cmd{\ForgetThis} -% and \cmd{\SubvertThis}, preventing them from passing through. +% \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: -% \begin{itemize} % \phantomsection -% \Info{\hrule\strut Test indexing rules:\break -% Creating \textit{see} xref\break\footnotesize +% \Info[2ex]{\hrule\strut Here we 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}\strut\hrule} +% \begin{itemize} % \item\cmd{\JustIndex} \cmd{\SkipIndex} % \cmd{\Name\{A\}} \cmd{\Name\{B\}} +% % \item\cmd{\SkipIndex} \cmd{\JustIndex} % \cmd{\Name\{A\}} \cmd{\Name\{B\}} +% % \item\cmd{\JustIndex} \cmd{\Name\{A\}} % \cmd{\SkipIndex} \cmd{\Name\{B\}} % \end{itemize} -% \cmd{\JustIndex} takes priority with \cmd{\Name\{A\}} and passes -% \cmd{\SkipIndex} to \cmd{\Name\{B\}} -% (see also Section~\ref{sec:Priorities}). +% \item[] \cmd{\JustIndex} takes priority with \cmd{\Name\{A\}} and passes \cmd{\SkipIndex} to \cmd{\Name\{B\}} (see also Section~\ref{sec:Priorities}). +% % \item \cmd{\JustIndex} and the naming macros do not replace \cmd{\IndexRef}. % \end{itemize} % % \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 -% \begin{tabular}{rp{0.3\textwidth}p{0.5\textwidth}}\toprule -% \rowcolor{nagrey}^^A -% \bfseries Page & \bfseries Macro & \bfseries Index Result\\ +% Below we indicate what to expect regarding index rules. We do not attempt to concatenate page ranges. Previously we put names and cross-references in margin notes, indicating that we were testing the index rules. Here are the results: +% \begin{itemize}[leftmargin=2.8\parindent]\small +% \item[\emph{Page \pageref{page:Idx1}}:] +% There are no name patterns (Section~\ref{sec:NamePatterns}) for either a name or a cross-reference. Then we create the name \Name*{Yamaha, Torakusu} along with its pattern. A pair of index page entries are generated, one before and one after the name. Also on page \pageref{page:Idx1} an index page entry is created for \Name{Nippon Gakki}, whose name pattern still does not yet exist. +% \PatInfo[3ex]{\ShowPattern{Yamaha,Torakusu}!MN} +% +% \item[] +% \begin{tabular}{@{}p{0.36\textwidth}p{0.4\textwidth}} +% \emph{Macros} & \emph{Cumulative Index}\\[0.5ex] +% \cmd{\Name\{Yamaha, Torakusu\}}\par +% \cmd{\IndexName\{Nippon Gakki\}} & +% \ShowIdxPageref*{Nippon Gakki}, \pageref{page:Idx1}\par +% \ShowIdxPageref*{Yamaha, Torakusu}, \pageref{page:Idx1} +% \end{tabular} +% \medskip % -% \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}\\ +% \item[\emph{Page \pageref{page:Idx2}}:] +% The name \Name{Yamaha, Torakusu} appears again. Since a pattern exists, the short form is printed and two index page entries are generated. +% \PatInfo[3ex]{\ShowPattern{Yamaha,Torakusu}!MN} % -% \rowcolor{nagrey}^^A -% \pageref{page:Idx2} & -% \cmd{\Name\{Yamaha, Torakusu\}} & +% \item[] +% \begin{tabular}{@{}p{0.36\textwidth}p{0.4\textwidth}} +% \emph{Macros} & \emph{Cumulative Index}\\[0.5ex] +% \cmd{\Name\{Yamaha, Torakusu\}} & +% \ShowIdxPageref*{Nippon Gakki}, \pageref{page:Idx1}\par % \ShowIdxPageref*{Yamaha, Torakusu}, \pageref{page:Idx1}, -% \pageref{page:Idx2}\par -% \ShowIdxPageref*{Nippon Gakki}, \pageref{page:Idx1}\\ +% \pageref{page:Idx2}\\ +% \end{tabular} +% \medskip % -% \pageref{page:Idx3} & +% \item[\emph{Page \pageref{page:Idx3}}:] +% 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 Mr. \Name{Yamaha, Torakusu}. +%\PatInfo[3ex]{\ShowPattern{Yamaha,Torakusu}!MN\break +% \ShowPattern{Yamaha,Torakusu}!PN} +% +% \item[] +% \begin{tabular}{@{}p{0.36\textwidth}p{0.4\textwidth}} +% \emph{Macros} & \emph{Cumulative Index}\\[0.5ex] % \cmd{\SeeAlso}\cmd{\IndexRef\{Yamaha,}\par % \texttt{Torakusu\}\{Nippon Gakki\}} & +% \ShowIdxPageref*{Nippon Gakki}, \pageref{page:Idx1}\par % \ShowIdxPageref*{Yamaha, Torakusu}, \pageref{page:Idx1}, -% \pageref{page:Idx2} \textit{see also} Nippon Gakki\par -% \ShowIdxPageref*{Nippon Gakki}, \pageref{page:Idx1}\\ +% \pageref{page:Idx2} +% \textit{see also} Nippon Gakki\\ +% \end{tabular} % -% \rowcolor{nagrey}^^A -% \pageref{page:Idx4} & -% \cmd{\Name\{Yamaha, Torakusu\}} & +% \item[\emph{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. +% \PatInfo[3ex]{\ShowPattern{Yamaha,Torakusu}!MN\break +% \ShowPattern{Yamaha,Torakusu}!PN} +% +% \item[] +% \begin{tabular}{@{}p{0.36\textwidth}p{0.4\textwidth}} +% \emph{Macros} & \emph{Cumulative Index}\\[0.5ex] +% \cmd{\Name\{Yamaha, Torakusu\}} & +% \ShowIdxPageref*{Nippon Gakki}, \pageref{page:Idx1}\par % \ShowIdxPageref*{Yamaha, Torakusu}, \pageref{page:Idx1}, -% \pageref{page:Idx2} \textit{see also} Nippon Gakki\par -% \ShowIdxPageref*{Nippon Gakki}, \pageref{page:Idx1}\\ +% \pageref{page:Idx2} +% \textit{see also} Nippon Gakki\\ +% \end{tabular} +% \medskip % -% \pageref{page:Idx5} & -% \cmd{\Name\{Nippon Gakki\}} & +% \item[\emph{Page \pageref{page:Idx5}}:] +% We print the name \Name{Nippon Gakki}, bringing its name pattern into being. Even though it was the \emph{target} of an xref, that does not restrict the ability to make page entries for it. +% \PatInfo[3ex]{\ShowPattern{Yamaha,Torakusu}!MN\break +% \ShowPattern{Yamaha,Torakusu}!PN\break +% \ShowPattern{Nippon Gakki}!MN} +% +% \item[] +% \begin{tabular}{@{}p{0.36\textwidth}p{0.4\textwidth}} +% \emph{Macros} & \emph{Cumulative Index}\\[0.5ex] +% \cmd{\Name\{Nippon Gakki\}} & +% \ShowIdxPageref*{Nippon Gakki}, \pageref{page:Idx1}, +% \pageref{page:Idx5}\par % \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:Idx2} +% \textit{see also} Nippon Gakki\\ +% \end{tabular} +% \medskip % -% \rowcolor{nagrey}^^A -% \pageref{page:Idx6} & +% \label{page:Idx7} +% \item[\emph{Page \pageref{page:Idx6}}:] +% We attempt to create a \textit{see} cross-reference from \Name{Nippon Gakki} to the target \Name{Yamaha Corp.}. That fails because, unlike a \textit{see also} reference, a \textit{see} reference cannot be created when a name pattern already exists. The \textsf{nameauth} package issues a warning at this point. Yet the name \Name{Yamaha Corp.} is not created until page \pageref{page:Idx7}. +% \PatInfo[3ex]{\ShowPattern{Yamaha,Torakusu}!MN\break +% \ShowPattern{Yamaha,Torakusu}!PN\break +% \ShowPattern{Nippon Gakki}!MN}^^A +% +% \item[] +% \begin{tabular}{@{}p{0.36\textwidth}p{0.4\textwidth}} +% \emph{Macros} & \emph{Cumulative Index}\\[0.5ex] % \cmd{\IndexRef\{Nippon Gakki\}}\par \texttt{\{Yamaha Corp.\}} & +% \ShowIdxPageref*{Nippon Gakki}, \pageref{page:Idx1}, +% \pageref{page:Idx5}\par % \ShowIdxPageref*{Yamaha, Torakusu}, \pageref{page:Idx1}, -% \pageref{page:Idx2} \textit{see also} Nippon Gakki\par +% \pageref{page:Idx2} +% \textit{see also} Nippon Gakki\\ +% \end{tabular} +% \medskip +% +% \item[\emph{Page \pageref{page:Idx7}}:] +% Index entries for \Name{Nippon Gakki} and \Name{Yamaha Corp.} also include this page due to the content of this list. +% \PatInfo[3ex]{\ShowPattern{Yamaha,Torakusu}!MN\break +% \ShowPattern{Yamaha,Torakusu}!PN\break +% \ShowPattern{Nippon Gakki}!MN\break +% \ShowPattern{Yamaha Corp.}!MN}^^A +% +% \item[] +% \begin{tabular}{@{}p{0.36\textwidth}p{0.4\textwidth}} +% \emph{Macros} & \emph{Cumulative Index}\\[0.5ex] +% \cmd{\Name\{Nippon Gakki\}}\par +% \cmd{\Name\{Yamaha Corp.\}} & % \ShowIdxPageref*{Nippon Gakki}, \pageref{page:Idx1}, -% \pageref{page:Idx5}\\\bottomrule +% \pageref{page:Idx5}, \pageref{page:Idx7}\par +% \ShowIdxPageref*{Yamaha Corp.} \pageref{page:Idx7}\par +% \ShowIdxPageref*{Yamaha, Torakusu}, \pageref{page:Idx1}, +% \pageref{page:Idx2}, +% \textit{see also} Nippon Gakki\\ % \end{tabular} -% \end{center} +% \end{itemize} % -% \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} +% \begin{Quotation}{\Name[Dwight D.]{Eisenhower}} +% {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. +% \index{politicians, quotes of\noexpand\string|hyperpage} +% \end{Quotation} % -% This manual's index entries for \Name{Nippon Gakki} and \Name{Yamaha Corp.} will also include this page in addition to those shown above. +% \newpage % % \subsection[Sorting Names]{Sorting Names in the Index} % \label{sec:IndexSort} % -% 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. +% When using \texttt{makeindex}, names with characters outside the ASCII range \texttt{[A--Za--z]} need to be sorted, as do names with spaces, active characters, Roman numerals, and macros especially in the \meta{SNN} argument. We do that in \textsf{nameauth} using sort tags. For other multilingual approaches, see the respective documentation for \textsf{xindex} and \texttt{xindy}. Those details go beyond the scope of this manual. % % \subsubsection{General Approach} % % \DescribeMacro{\IndexActual} -% 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. +% 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 \Title{The Latex Companion}). % -% 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: +% 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. % -% \begin{quote} -% \vspace{4ex} -% \PatInfo{\ShowPattern{Ægidius}!PRE} -% \vspace{-4ex} +% \Global Effects of \cmd{\IndexActual} 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:\footnote{This example will generate a warning because we sort a name that does not exist.} +% \begin{Quote} % \begin{Verbatim} % \PretagName{Ægidius}{Aegidius} % @@ -5254,7 +6578,7 @@ and version 1.3 or later is part of all distributions of LaTeX version % \endgroup % Now back to \texttt{dtx} mode: \texttt{\ShowIdxPageref{Ægidius}}. % \end{Verbatim} -% +% \PatInfo[3ex]{\ShowPattern{Ægidius}!PRE} % \PretagName{Ægidius}{Aegidius} % % In a \texttt{dtx} file the ``actual'' character is \texttt{=}. @@ -5264,129 +6588,229 @@ and version 1.3 or later is part of all distributions of LaTeX version % \texttt{\IndexActual{@}\ShowIdxPageref{Ægidius}}. % \endgroup % Now back to \texttt{dtx} mode: \texttt{\ShowIdxPageref{Ægidius}}. -% \end{quote} +% \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{SyntaxBox} -% \cmd{\PretagName}\oarg{FNN}\marg{SNN|,| Affix}\oarg{Alternate}\marg{tag} +% \cmd{\PretagName}\oarg{FNN}\marg{SNN\textbf{,}Affix}\oarg{Alternate}\marg{tag} % \end{SyntaxBox} % -% \vspace{2ex} -% \PatInfo{\ShowPattern{Æthelred, II}!PRE\break +% \PatInfo[2ex]{\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} +% \begin{Quote} % \begin{Verbatim} % \PretagName{Æthelred, II}{Aethelred 2} % \PretagName[W.E.B.]{Du~Bois}{Dubois, William} % \end{Verbatim} -% \end{quote} +% \end{Quote} % -% 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. +% \newpage % -% 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: +% Every reference to \LAeth\ and \LDuBois\ is automatically tagged and sorted.\footnote{Regarding the margin note that shows name patterns, 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 unless one is using other multilingual tools like \textsf{xindex} and \texttt{xindy}. % +% 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 ``\LA{Doctor angelicus}'' (cf. Sections~\ref{sec:NameMedieval}, \ref{sec:AltFormat}). +% \Info[4ex]{Name patterns and index entries too large for margin.}^^A +%^^A % \begin{VerbatimOut}{\jobname.tmp} % \PretagName{\textit{Doctor angelicus}}{Doctor angelicus} % \IndexRef{\textit{Doctor angelicus}}{Thomas Aquinas} +% \IndexRef[Thomas]{Aquinas}{Thomas Aquinas} % % Perhaps the greatest medieval theologian was % \Name{Thomas, Aquinas}, later known as % \Name{\textit{Doctor angelicus}}. +% \SeeAlso\IndexRef{\textit{Doctor angelicus}}{Thomas Aquinas} % \end{VerbatimOut} -% -% \begin{quote} -% {\ttfamily\ShowPattern{\textit{Doctor angelicus}}!PRE\\ -% \ShowPattern{\textit{Doctor angelicus}}!PN\\ -% \ShowPattern{Thomas, Aquinas}!MN\\ -% \ShowPattern{\textit{Doctor angelicus}}!MN} -% -% \VerbatimInput[gobble=0]{\jobname.tmp} +%^^A +% \begin{Quote} +% \VerbatimInput[gobble=0,lastline=7]{\jobname.tmp} % % \IndexRef{\textit{Doctor angelicus}}{Thomas Aquinas} +% \IndexRef[Thomas]{Aquinas}{Thomas Aquinas} % % Perhaps the greatest medieval theologian was % \Name{Thomas, Aquinas}, later known as % \Name{\textit{Doctor angelicus}}. -% \end{quote} +% \end{Quote} % -% To give \Name{\textit{Doctor angelicus}} page entries and a \textit{see also} reference, we omit line~2 above, wait until the end of the body text, after both names are fully indexed, and then use: -% \fbox{\cmd{\SeeAlso}\cmd{\IndexRef\{}\cmd{\textit\{Doctor angelicus\}\}\{Thomas Aquinas\}}}. +% We make \Name{\textit{Doctor angelicus}} a \textit{see} references with no page entries. If we did want page entries and a \textit{see also} reference from \Name{\textit{Doctor angelicus}} to \Name{Thomas, Aquinas}, we would omit line~2 above, wait until the body text is complete at the the end of the document, such as before \cmd{\printindex}, and then use: +% \begin{Quote} +% \VerbatimInput[gobble=0,numbers=none,firstline=8]{\jobname.tmp} +% \end{Quote} % % \subsubsection*{\hfil Name Particles} % -% Spaces change sorting. For example, the 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}. +% Spaces change sorting. For example, the 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}. Remove spaces when sorting with \cmd{\PretagName}. % % \subsubsection*{\hfil Collating Sequences} % -% 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}. +% German \textsf{ä ö ü ß} map to English \textsf{ae oe ue ss}. Yet Norwegian \textsf{æ ø å} follow \textsf{z} in that order. One might have to create a sort tag that substitutes, e.g., \textsf{za zb zc} for \textsf{æ ø å}. Check a style guide regarding collating sequences, spaces, and sorting. This is where using other multilingual tools can be helpful. % % \subsubsection*{\hfil Alternate Formatting} % -% Additional examples starting with Section~\ref{sec:RealAltEx} deal with index sorting as it relates to alternate formatting, ``Continental'' practice, and macros in name arguments. Please ensure that such macros expand to the form desired in the index in order to get proper sorting with \cmd{\PretagName}. +% Additional examples starting with Section~\ref{sec:RealAltEx} deal with index sorting as it relates to alternate formatting, ``Continental'' practice, and macros in name arguments. % -% \begin{Quote}{\Name[Publius]{Vegetius Renatus}, \textit{De re militari} (c. 390)} -% Igitur qui desiderat pacem, praeparet bellum. +% \begin{AltFormatZone} +% \begin{Quotation}{\Shak} +% {``Julius Caesar'', Act III, Scene II (first performed 1599)} +% \textbf{Antony:} Friends, Romans, countrymen, lend me your ears;\\ +% I come to bury Caesar, not to praise him. +% \index{creatives, quotes of\noexpand\string|hyperpage} +% \end{Quotation} +% \end{AltFormatZone} % -% (Accordingly, the person who would desire peace prepares for war.)^^A -% \index{Romans, quotes of\noexpand\string|hyperpage} -% \end{Quote} +% \newpage % % \subsubsection{Sorting Initials} % \label{sec:IndexInitials} -% \negbigskip +% +% 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. +% +% 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} +% |\PretagName[J.D.]{Rockefeller, IV}{Rockefeller, John D 4}| +% \begin{itemize} +% \item The index entry is ``\ShowIdxPageref*[J.D.]{Rockefeller, IV}''. +% +% \item In the ``pretag'' we spell out the first forename and add enough of the second to get a unique sorting key. +% +% \item We turn the Roman numeral affix into an Arabic numeral so that it does not sort like letters. +% \end{itemize} +% \end{Quote} +% +% For more examples, see Sections~\ref{sec:NameMedieval}, \ref{sec:Romani}, \ref{sec:VarNames}, and all of Section~\ref{sec:AdvancedFormat}. % % \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} % -% 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. +% \subsubsection[Unicode]{Unicode Compatibility} +% \label{sec:CompatON} % -% 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: +% Here we engage how active Unicode characters affect index entries. Changes in the way that \texttt{pdflatex} and \texttt{latex} handle Unicode characters since 2018 have made indexing simpler and more intuitive, e.g. +% \begin{Center} +% \begin{tabular}{rllrll}\toprule +% \rowcolor{nagrey}^^A +% \bfseries Pre-2018 & & \bfseries Index & +% \bfseries Post-2018 & & \bfseries Index\\ % -% \begin{quote} -% |\PretagName[J.D.]{Rockefeller, IV}{Rockefeller, John D 4}| -% -% \begin{itemize} -% \item The index entry is ``\ShowIdxPageref*[J.D.]{Rockefeller, IV}''. -% -% \item In the ``pretag'' we spell out the first forename -% and add enough of the second to get a unique sorting key. +% ä & \textrightarrow & +% \texttt{\cmd{\IeC\textvisiblespace}\{\cmd{\"a}\}} & +% ä & \textrightarrow & \texttt{ä}\\ % -% \item We turn the Roman numeral affix into an Arabic numeral -% so that it does not sort like letters. -% \end{itemize} -% \end{quote} +% \rowcolor{nagrey}^^A +% æ & \textrightarrow & +% \texttt{\cmd{\IeC\textvisiblespace}\{\cmd{\ae\textvisiblespace}\}} & +% æ & \textrightarrow & \texttt{æ}\\\bottomrule +% \end{tabular} +% \end{Center} +% +% 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 problems that would generate multiple index entries. We can test for changes that can affect \textsf{nameauth}: +% \begin{enumerate} +% \item Test for the presence of \texttt{utf8-2018.def} and define a macro: +% \begin{Quote} +% \begin{Verbatim} +% \makeatletter +% \@ifl@t@r\fmtversion{2018/10/05}{\newcommand\nameauthltx{}}{} +% \makeatother +% \end{Verbatim} +% \end{Quote} +% +% \item Test for the presence of \texttt{utf8-2018.def} by checking for a file: +% \begin{Quote} +% \begin{Verbatim} +% \IfFileExists{utf8-2018.def}{do if present}{do if absent} +% \end{Verbatim} +% \end{Quote} +% +% \item Test for the version of \textsf{xparse} that allows the current function of name arguments, and define a macro: +% \begin{Quote} +% \begin{Verbatim} +% \makeatletter +% \@ifl@t@r\fmtversion{2018/04/30}{\newcommand\nameauthxp{}}{} +% \makeatother +% \end{Verbatim} +% \end{Quote} +% \end{enumerate} +% +% Before 2018, some index styles like \texttt{gind.ist} could not work with characters with macrons. Since 2018, those restrictions have been removed. To work with both old or new versions of \texttt{pdflatex} and \texttt{latex}, we can do the following: +% \begin{Quote} +% \begin{Verbatim} +% \begin{nameauth} +% \ifdefined\nameauthltx +% \< Ghazali & & Ghazāli & > +% \else +% \< Ghazali & & Ghazali & > +% \fi +% \end{nameauth} +% +% \ifdefined\nameauthltx +% \PretagName{Ghazāli}{Ghazali} +% \fi +% +% \Ghazali\ was an important Islamic philosopher. +% \end{Verbatim} +% +% \Ghazali\ was an important Islamic philosopher. +% \end{Quote} % -% 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{Debugging} +% +% If one sees multiple index entries for the same name, or if the names are not sorted correctly, either check the \texttt{idx} file or use the debugging macros (Section~\ref{sec:DebuggingMacros}). Check \textsf{nameauth} package warnings. Set the \texttt{verbose} option, which will offer a number of ``informational'' warnings that could be of assistance. +% \begin{itemize} +% \item Do naming macros always use the same arguments? +% +% \item Are there any active characters, spaces, or control sequences in the name arguments? Use \cmd{\PretagName}. +% +% \item Are active Unicode characters expanding consistently? +% +% \item Use \cmd{\ShowPattern}, \cmd{\ShowIdxPageref}, and \cmd{\ShowNameState}. +% +% \item Did \cmd{\noexpand} precede macros in name arguments? Can those macros ultimately expand differently in the index? If so, check how alternate formatting is being used. +% +% \item Is alternate formatting used consistently? Are names used within sections of alternate formatting used outside of them? +% \end{itemize} +% +% Using \cmd{\protected@edef} in macros can add spaces to index entries. The \textsf{nameauth} macros must use \cmd{\protected@edef} to work with classes that write index entries to \texttt{aux} files. One must check this in the \texttt{idx} file. We show this below: +% \begin{Quote} +% \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{Index Tags} % \label{sec:IndexTag} % -% Index data 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 that persists until one changes it with \cmd{\TagName} or destroys it with \cmd{\UntagName}. +% Index tags are information added automatically to entries created by \textsf{nameauth} macros. % \DescribeMacro{\UntagName} -% 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}: +% \cmd{\TagName} creates or changes a persistent tag. \cmd{\UntagName} deletes a tag. This information can include life dates, regnal dates, etc. 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} +% \cmd{\TagName}\oarg{FNN}\marg{SNN\textbf{,}Affix}\oarg{Alternate}\marg{tag}\\ +% \cmd{\UntagName}\oarg{FNN}\marg{SNN\textbf{,}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} +% \begin{Center} % \begin{tabular}{r|l|l|l}\toprule % & & Naming macros\\ % & \cmd{\PretagName} & \cmd{\IndexName}\\ @@ -5395,90 +6819,111 @@ and version 1.3 or later is part of all distributions of LaTeX version % & & & \cmd{\TagName}\\ % & & & \cmd{\UntagName}\\\bottomrule % \end{tabular} -% \end{center} +% \end{Center} % % Tags 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 % {\ttfamily\fbox{\textvisiblespace the Great, pope}} -% to the index entries created in the next example: -% -% \begin{quote} -% \vspace{3.5ex} -% \PatInfo{\ShowPattern{Gregory, I}!TAG\break +% to the index entry below (normal \LaTeX\ document):\IndexName{Gregory, I} +% \begin{Quote} +% \IndexInactive +% \PatInfo[3.5ex]{\ShowPattern{Gregory, I}!PRE\break +% \ShowPattern{Gregory, I}!TAG\break % \ShowPattern{Gregory, I}!MN} -% \vspace{-3.5ex} % \begin{Verbatim} +% \PretagName{Gregory, I}{Gregory 1} % \TagName{Gregory, I}{ the Great, pope} -% Pope \Name*{Gregory, I} was known as \Name*{Gregory, I} -% [the Great]. +% Pope \Name*{Gregory, I} is known as \Name*{Gregory, I} +% [the Great].\\ +% Index: \ShowIdxPageref{Gregory, I} % \end{Verbatim} % -% Pope \Name*{Gregory, I} was known as \Name*{Gregory, I} -% [the Great]. -% \end{quote} +% \IndexActual{@} +% \TagName{Gregory, I}{ the Great, pope} +% Pope \Name*{Gregory, I} is known as \Name*{Gregory, I} +% [the Great].\\ +% Index: \ShowIdxPageref{Gregory, I} +% \TagName{Gregory, I}{ the Great, pope\string|hyperpage} +% \end{Quote} +% \IndexName{Gregory, I} % % See Section~\ref{sec:NameAncient} for more ways to deal with ancient names. \cmd{\TagName} works with all names that produce index page entries. It does not work with with cross-references produced by \cmd{\IndexRef}, \cmd{\AKA}, etc. % Tags can hold different kinds of information, but they should not be 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. % -% \subsubsection[Identical Names]{Disambiguating Identical Names} +% \begin{Quotation}{\ForgetThis\Name[M.T.]{Cicero}[Marcus Tullius]} +% {\Title{\la{De oratore}} B II; C IX, \S 36 (55 \textsc{BC})} +% 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? +% \index{Romans, quotes of\noexpand\string|hyperpage} +% \end{Quotation} % -% 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: +% \newpage % -% \begin{VerbatimOut}{\jobname.tmp} -% \TagName[E.]{Humperdinck}{ (composer)} -% This refers to the classical composer: -% \Name[E.]{Humperdinck}[Engelbert]. +% \subsubsection[Identical Names]{Disambiguating Identical Names} +% \label{sec:IdxIdent} % -% \TagName[E.]{Humperdinck}{ (singer)} -% This refers to the pop singer from the 60s and 70s: -% \ForgetThis\Name[E.]{Humperdinck}[Engelbert]. -% \end{VerbatimOut} +% 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: +% \begin{Quote} +% \begin{Verbatim} +% \TagName[Engelbert]{Humperdinck}{ (composer, 1854--1921)} +% This refers to the classical German composer: +% \Name[Engelbert]{Humperdinck}. % -% \begin{quote} -% \vspace{4ex} -% \PatInfo{\ShowPattern[E.]{Humperdinck}!TAG\break -% \ShowPattern[E.]{Humperdinck}!MN} -% \vspace{-4ex} -% \VerbatimInput[gobble=0]{\jobname.tmp} +% \TagName[Engelbert]{Humperdinck}{ (singer, *1936)} +% This refers to the English singer from the 60s and 70s: +% \ForgetThis\Name[Engelbert]{Humperdinck}. +% \end{Verbatim} % -% \TagName[E.]{Humperdinck}{ (composer)\string|hyperpage} +% \TagName[Engelbert]{Humperdinck}{ (composer, 1854--1921)\string|hyperpage} % This refers to the classical composer: -% \Name[E.]{Humperdinck}[Engelbert]. +% \Name[Engelbert]{Humperdinck}. % -% \TagName[E.]{Humperdinck}{ (singer)\string|hyperpage} -% This refers to the pop singer from the 60s and 70s: -% \ForgetThis\Name[E.]{Humperdinck}[Engelbert]. -% \end{quote} +% \TagName[Engelbert]{Humperdinck}{ (singer, *1936)\string|hyperpage} +% This refers to the singer from the 60s and 70s: +% \ForgetThis\Name[Engelbert]{Humperdinck}. +% \end{Quote} +% +% The name patterns are \texttt{\ShowPattern[Engelbert]{Humperdinck}!TAG} for the index tag and \texttt{\ShowPattern[Engelbert]{Humperdinck}!MN} for the name. +% This is the least ``intrusive'' way of creating unique names but it requires one to track potential changes to the text that might change the placement of index tags relative to their names.\footnote{The name decision macros might help automate this, as might the separate name systems.} +% +% Sections~\ref{sec:Romani} and~\ref{sec:Unique} show how one can do similar things with non-printing macros in name arguments, where the names are sorted with \cmd{\PretagName} and also have index tags. This relieves one of having to keep track of otherwise identical names, because the name patterns are distinct, even if they look alike. One can go to greater lengths in Section~\ref{sec:AdvancedFormat} and its subsections. +% +% One should try to use the \textsf{nameauth} macros in a way that is arguably the most ``natural'' and has the best fit for one's use case. That is a reason why this manual contains so many different examples. See also Section~\ref{sec:Complexity}. % % \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: +% When a \meta{macro} that takes one or more arguments exists, one can use the form: % % \begin{SyntaxBox} -% \cmd{\TagName}\meta{name args}\texttt{\{\textbar}\meta{macro}\texttt{\}} +% \cmd{\TagName}\oarg{FNN}\marg{SNN\textbf{,}Affix}\oarg{Alternate}\marg{\texttt{\upshape\textbar}macro}\\ % \end{SyntaxBox} % -% When \Warn\ using the \textsf{ltxdoc} class with \textsf{hypdoc}, as in this manual, neither \textsf{nameauth} nor regular use of \cmd{\index} creates hyperlinked page entries. Index data tags in the |<driver>| section of the \texttt{dtx} file, which reads the ``commented'' part of the \texttt{dtx} file into a \texttt{document} environment, take the form: +% \begin{Quotation}{\Name{Plato}} +% {opening statement in \textit{Cratylus} (c. 388 \textsc{bc})} +% \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.^^A +% \index{philosophers, quotes of\noexpand\string|hyperpage} +% \end{Quotation} % -% \begin{quote} -% \cmd{\TagName}\meta{name args}\texttt{\{\textbar hyperpage\}} -% \end{quote} +% \newpage % -% Within the ``commented'' part of the package documentation in this \texttt{dtx} file, the vertical bar is active. Hence, we use: +% \Info*{\small\dbend}When using the \textsf{ltxdoc} class with \textsf{hypdoc}, as in this manual, neither \textsf{nameauth} nor regular use of \cmd{\index} creates hyperlinked page entries. Index data tags in the |<driver>| section of the \texttt{dtx} file, which reads the ``commented'' part of the \texttt{dtx} file into a \texttt{document} environment, take the form: +% \begin{Quote} +% \cmd{\TagName}\meta{name args}\texttt{\{\textbar hyperpage\}} +% \end{Quote} % -% \begin{quote} -% \cmd{\TagName}\meta{name args}\texttt{\{}\cmd{\noexpand}\cmd{\string\textbar hyperpage\}}\\[0.5ex] -% or\\[0.5ex] -% \cmd{\index\{}\meta{entry argument}\cmd{\noexpand}\cmd{\string \textbar hyperpage\}} -% \end{quote} +% Within the ``commented'' part of the package documentation in this \texttt{dtx} file, the vertical bar is active. Hence, in this part, we use one of these two: +% \begin{itemize} +% \item \cmd{\TagName}\meta{name args}\texttt{\{}\cmd{\string\textbar hyperpage\}} +% \item \cmd{\index\{}\meta{entry info}\cmd{\noexpand}\cmd{\string \textbar hyperpage\}} +% \end{itemize} % % 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. % -% 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}. -% -% \begin{quote} +% \Info*{\small\dbend}Next we create a special tag. Since we used lines~1--2 in this \texttt{dtx} file, we put them in the driver section to keep it simple. +% \begin{Quote} % \begin{Verbatim} % \newcommand\Orphan[2]{#1(\hyperpage{#2})} % \TagName[Lost]{Name}{\,\S|Orphan{perdit}} @@ -5486,141 +6931,159 @@ and version 1.3 or later is part of all distributions of LaTeX version % \end{Verbatim} % % \Name[Lost]{Name}\\ -% \texttt{idx} file: +% \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} -% -% \subsubsection*{\hfil Manual Breaks and Entries} -% -% The \textsf{microtype} package and its \texttt{Spacing} environment may be the best solution to fix index entries and sub-entries that break badly across columns or pages. Yet we could add manual breaks after editing is complete. -% -% 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 entries in the index, e.g.: \cmd{\index\{Doe, John\string|textbf\}}. -% -% 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} -% |\newcommand*{\EndBreak}[1]{#1\newpage}| -% \end{quote} -% -% 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: +% \end{Quote} % -% \begin{center} +% The \textsf{microtype} package and its tracking features is probably the best solution to fix index entries and sub-entries that break badly across columns or pages. Here we show how to add manual breaks, inelegant as that may be. +% \begin{itemize} +% \item Create a macro that takes an argument and appends a break: +% \item[] |\newcommand*{\EndBreak}[1]{#1\newpage}| +% \item The principle is similar to using: +% \item[] \cmd{\index\{Doe, John\string|textbf\}} +% \item The default for two column mode is \cmd{\newpage}. One might use +% \cmd{\newcolumn} with \textsf{multicol} and \textsf{idxlayout}, etc. +%\end{itemize} +% +% We use \cmd{\EndBreak} in an index tag for every index entry on the last page where such entries occur. If all instances of a name on that pagee have the same index tag, there will be no duplicate page entries, hyperlinks will work, and the index will break as indicated: +% \begin{Center} % \begin{tabular}{rll}\toprule % \rowcolor{nagrey}^^A -% \bfseries Page & \bfseries Macro & \bfseries Index Result\\ +% \bfseries Page & \bfseries Macro & \bfseries Index\\ +% +% (preamble) & |\newcommand*{\EndBreak}[1]|\\ +% & | {#1\newpage}|\\ % % 10 & \cmd{\Name\{Some, Name\}} & Some Name, 10\\ -% & \cmd{\index\{Topic\}} & Topic, 10\\ % -% \rowcolor{nagrey}^^A % 15 & \cmd{\Name\{Some, Name\}} & Some Name, 10, 15\\ -% \rowcolor{nagrey}^^A -% & \cmd{\index\{Topic\}} & Topic, 10, 15\\ % -% 18 & \cmd{\TagName\{Some, Name\textbar EndBreak\}\%} & \\ +% 18 & \cmd{\TagName\{Some, Name\textbar EndBreak\}} & \\ % & \cmd{\Name\{Some, Name\}} & -% Some Name, 10, 15, 18\meta{break}\\ -% & -% \cmd{\index\{Topic\textbar EndBreak\}} & -% Topic, 10, 15, 18\meta{break}\\\bottomrule +% Some Name, 10, 15, 18\meta{break}\\\bottomrule % \end{tabular} -% \end{center} -% -% We do not have to supply an argument to \cmd{\EndBreak} because, as with the font switching example above, the page entry 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 also can do this: +% \end{Center} % -% \begin{center} +% We do not have to supply an argument to \cmd{\EndBreak} because, as with font switching in the index, the page entry is implied. We also can intermix \textsf{nameauth} macros with manual index entries.\footnote{One may need to look at the \texttt{idx} or \texttt{ind} files to craft matching entries on the page where the break occurs. Again, this approach is probably not as good as using \textsf{microtype}.} +% Instead of using \cmd{\TagName}, we could try this: +% \begin{Center} % \begin{tabular}{rll}\toprule % \rowcolor{nagrey}^^A -% \bfseries Page & \bfseries Macro & \bfseries Index Result\\ +% \bfseries Page & \bfseries Macro & \bfseries Index\\ % -% 18 & \cmd{\SkipIndex}\cmd{\Name\{Some, Name\}\%}\hfill\hbox{} & \\ -% & \cmd{\index\{Some Name\textbar EndBreak\}}\dotfill \hbox{} & +% 18 & |\SkipIndex\Name\{Some, Name}% |\\ +% & \cmd{\index\{Some Name\textbar EndBreak\}} & % Some Name, 10, 15, 18\meta{break}\\\bottomrule % \end{tabular} -% \end{center} +% \end{Center} % % 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 discussions, such as \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 that page}. A ``quick and dirty'' version corresponding to the \cmd{\EndBreak} macro follows: -% -% \begin{quote} -% \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. +% We do not recommend breaking an index entry in the middle. There are several discussions, such as \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 that page}. Modifying \cmd{\EndBreak} above by putting \cmd{\@gobble} after \cmd{\newpage} would allow breaking an index entry in the middle, but there are no real guarantees that the new macro would work well. % % \subsection[Categories/Sub-entries]{Categories and Sub-entries} % \label{sec:CatSub} % % Indexes can have categories and sub-entries such as the following: -% % \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} +% \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} % -% To get \textsf{nameauth} to work with this structure, one must use both \cmd{\PretagName} and \cmd{\TagName}. For example, to sort a name under \meta{category}, use something like: +% To get \textsf{nameauth} to work with this structure, one uses \cmd{\PretagName} to organize names under categories. One uses \cmd{\TagName} to create sub-entrues under names. A simple mnemonic is: ``Pre stands for C'' when it comes to categories, while ``Tags are on the inside'' like sub-entries. +% +% The following syntax box shows a couple of generic examples for creating categories and sorting names under them with \cmd{\PretagName}: % % \begin{SyntaxBox} % \cmd{\PretagName}\oarg{FNN}\marg{SNN}\texttt % {\{}\meta{category 1}\texttt{!}\meta{SNN}\texttt % {, }\meta{FNN}\texttt{\}}\\ -% \cmd{\PretagName}\marg{SNN, Affix}\texttt +% \cmd{\PretagName}\marg{SNN\textbf{,}Affix}\texttt % {\{}\meta{category 1}\texttt{!}\meta{SNN} \meta{Affix}\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 something like: +% Likewise, the following syntax box shows a couple of generic examples for creating sub-entries under names with \cmd{\TagName}: % % \begin{SyntaxBox} % \cmd{\TagName}\oarg{FNN}\marg{SNN}\texttt % {\{!}\meta{name sub-entry}\texttt{\}}\\ -% \cmd{\TagName}\marg{SNN, Affix}\texttt +% \cmd{\TagName}\marg{SNN\textbf{,}Affix}\texttt % {\{!}\meta{name sub-entry}\texttt{\}} % \end{SyntaxBox} % -% One is not restricted to Western or nonwestern name arguments; the boxes above are meant just to show the basic tag formats. -% % \newpage % -% 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 entries 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}. +% \begin{itemize} +% \item If the name has no tag, \cmd{\UntagName} will +% restore the base name entry. +% +% \item \cmd{\TagName} can set up a default tag, set up or change +% sub-entries, and change back to the default tag. % -% 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 +% \item If a sub-entry of a name needs a \textit{see} reference: +% \begin{itemize} +% \item If the name has been used in the front matter or the main matter, +% use \cmd{\ForgetName} or no \textit{see} reference will be created. +% \item Pick sub-entry A with no page references. +% \item[] |\TagName[Some]{Name}{!Sub-entry A}| +% \item Create a \textit{see} reference using that sub-entry. +% \item[] |\IndexRef[Some]{Name}{Something else}| +% \item Free up the name for more references. +% \item[] |\IncludeName*[Some]{Name}| +% \item Change back to the base name entry or another sub-entry. +% \item If needed, use \cmd{\SubvertName}. +% \end{itemize} +% +% \item If a sub-entry of a name needs a \textit{see also} reference: +% \begin{itemize} +% \item Pick sub-entry B with complete page references. +% \item[] |\TagName[Some]{Name}{!Sub-entry B}| +% \item Create a \textit{see also} reference using that sub-entry. +% \item[] |\SeeAlso\IndexRef[Some]{Name}{Something else}| +% \item Free up the name for more references. +% \item[] |\IncludeName*[Some]{Name}| +% \item Change back to the base name emtry or another sub-entry. +% \end{itemize} +% +% \item Have as few levels in an index as needed. +% \end{itemize} +% +% Next, we show categories and sub-entries used in a normal \LaTeX\ document. % +% \JustIndex\Wash \JustIndex\Ike +%^^A % \ifdefined\NameauthDoTestFiles \edef\NameauthTestFile{test07_02.tex}\else % \edef\NameauthTestFile{\jobname.tmp}\fi -% +%^^A % \begin{VerbatimOut}{\NameauthTestFile} % \documentclass{article} -% \input{compat.tex} % Included with nameauth; example file aids -% % compatibility across different LaTeX versions and engines. +% \input{compat.tex} % Included with nameauth for compatibility. % \usepackage[a6paper,landscape,left=1cm,right=1cm]{geometry} % \usepackage{makeidx} % \usepackage{nameauth} % +% \newcommand*{\EndBreak}[1]{#1\newpage} +% % \makeindex % -% \newcommand*{\EndBreak}[1]{#1\newpage} +% % Sort these names under: US Generals. +% \PretagName[Omar N.]{Bradley}{US Generals!Bradley, Omar} +% \PretagName[George S.]{Patton, Jr.}{US Generals!Patton, George} % % % Sort these names under: US Presidents. % \PretagName[George]{Washington}{US Presidents!Washington, George} +% \PretagName[Dwight D.]{Eisenhower}{US Presidents!Eisenhower, Dwight D.} % \PretagName[Abraham]{Lincoln}{US Presidents!Lincoln, Abraham} % % % Sort these names under: Philosophers. @@ -5638,19 +7101,15 @@ and version 1.3 or later is part of all distributions of LaTeX version % \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 & > +% \< Bradley & Omar N. & Bradley & > % \< 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} @@ -5681,13 +7140,12 @@ and version 1.3 or later is part of all distributions of LaTeX version % % \section{Philosophers} % +% \TagName{Plato}{|EndBreak} % 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. % @@ -5695,170 +7153,267 @@ and version 1.3 or later is part of all distributions of LaTeX version % % \TagName[George]{Washington}{!as general} % \TagName[Dwight D.]{Eisenhower}{!as general} -% \LWash, \LPatton, and \LIke\ were high-ranking generals.\\ +% \LWash, \LIke, \LBradley, and \LPatton +% were high-ranking generals.\\ +% \SeeAlso\IndexRef[George]{Washington}{Eisenhower} +% \SeeAlso\IndexRef[Dwight D.]{Eisenhower}{Washington} +% \IncludeName*[George]{Washington} +% \IncludeName*[Dwight D.]{Eisenhower} % -% \TagName[Dwight D.]{Eisenhower}{!as president} % \UntagName[George]{Washington} +% \UntagName[Dwight D.]{Eisenhower} % \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}} +% \ForgetName[Omar N.]{Bradley} +% \ForgetName[George S.]{Patton, Jr.} +% \TagName[Omar N.]{Bradley}{!colleagues of} +% \TagName[George S.]{Patton, Jr.}{!colleagues of} +% \IndexRef[Omar N.]{Bradley}{Eisenhower, Patton} +% \IndexRef[George S.]{Patton, Jr.}{Bradley, Eisenhower} % -% \small % \printindex % \end{document} % \end{VerbatimOut} -% -% \begin{quote} -% \VerbatimInput[gobble=0]{\NameauthTestFile} -% \end{quote} +%^^A +% \begin{Quote} +% \VerbatimInput[gobble=0,lastline=23]{\NameauthTestFile} % % \newpage % -% Below we show only the index from this example. -% A few notable features include: +% \VerbatimInput[gobble=0,firstline=24,lastline=76]{\NameauthTestFile} % -% \begin{itemize} -% \item \Patton\ uses a regular index tag instead of a subcategory. -% That is a way to `cheat'' and get more groupings of entries -% than allowed categories. -% \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} -% \JustIndex\MLK \JustIndex\Doug \JustIndex\Aeth \JustIndex\Soto -% \JustIndex\Aris \JustIndex\Plato \JustIndex\Linc +% \newpage +% +% \VerbatimInput[gobble=0,firstline=77]{\NameauthTestFile} +% \end{Quote} % +% \JustIndex\MLK \JustIndex\Doug +% \JustIndex\Aeth \JustIndex\Soto +% \JustIndex\Aris \JustIndex\Plato +% \JustIndex\Linc \JustIndex\Wash +% \JustIndex\Ike \JustIndex\Patton \JustIndex\Bradley % \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 -% \IndexWarnTerse +% \medskip +% +% \newpage +% +% A few notable features from this example include: +% \begin{itemize} +% \item The entry categories are set up in the preamble with \cmd{\PretagName}. They do not change thereafter. +% +% \item Changes from one sub-entry to another, or back to the base name entry, occur using \cmd{\TagName} and \cmd{\UntagName}. +% +% \item We permit references to names with other sub-entries or main entries again with \cmd{\IncludeName*}. Otherwise, the creation of an xref would protect that name from further entries. +% +% \item We permit the creation of \textit{see} references in subentries of extant names by using \cmd{\ForgetName} +% \end{itemize} +% +% Obviously, the more complex an index gets, the more complex it will be to deal with the \textsf{nameauth} macros. The user must decide where the break-even point lies. % % \ReturnLink % -% \begin{Quote}{\Linc, \textit{Gettysburg Address} (19 November 1863)} -% Four score and seven years ago our fathers brought forth on this continent, a new nation, conceived in Liberty, and dedicated to the proposition that all men are created equal. \dots It is for us the living, rather, to be dedicated here to the unfinished work which they who fought here have thus far so nobly advanced. It is rather for us to be here dedicated to the great task remaining before us\,---\,that from these honored dead we take increased devotion to that cause for which they gave the last full measure of devotion\,---\,that we here highly resolve that these dead shall not have died in vain\,---\,that this nation, under God, shall have a new birth of freedom\,---\,and that government of the people, by the people, for the people, shall not perish from the earth.^^A +% \begin{Quotation}{\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. +% +% \dots And so, my fellow Americans: ask not what your country can do for you\,---\,ask what you can do for your country. +% +% My fellow citizens of the world: ask not what America will do for you, but what together we can do for the freedom of man. +% +% Finally, whether you are citizens of America or citizens of the world, ask of us here the same high standards of strength and sacrifice which we ask of you. With a good conscience our only sure reward, with history the final judge of our deeds, let us go forth to lead the land we love, asking His blessing and His help, but knowing that here on earth God's work must truly be our own. % \index{politicians, quotes of\noexpand\string|hyperpage} -% \end{Quote} +% \end{Quotation} % % \newpage % % \section{Name Tags} % \label{sec:DataTags} % -% \DescribeMacro{\NameAddInfo} -% All valid names in \textsf{nameauth} can have name tags; no restrictions exist. Unlike index tags, name 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: +% \subsection{Basics} % +% \DescribeMacro{\NameAddInfo} +% All valid names in \textsf{nameauth} can have name tags. Unlike other kinds of tags, name tags are not generated automatically with every name managed by \textsf{nameauth}. \cmd{\NameAddInfo} is \cmd{\long}, allowing for more information in the \meta{tag} argument: % \begin{SyntaxBox} -% \cmd{\NameAddInfo}\oarg{FNN}\marg{SNN|,| Affix}\oarg{Alternate}\marg{tag} +% \cmd{\NameAddInfo}\oarg{FNN}\marg{SNN\textbf{,}Affix}\oarg{Alternate}\marg{tag} % \end{SyntaxBox} % -% \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 name tag but does not print whenever \Wash\ \cmd{\Wash} is used. The name tag needs to be displayed using the helper macro below. +% \PatInfo*{\ShowPattern[George]{Washington}!DB\break +% \ShowPattern[George]{Washington}!MN}^^A +% For example, |\NameAddInfo[George]{Washington}{(1732--99)}|\NameAddInfo[George]{Washington}{(1732--99)} makes a name tag but does not print whenever \Wash\ \cmd{\Wash} is used. The name tag is displayed only by using the macro \cmd{\NameQueryInfo\{\}} \NameQueryInfo{}. +% +% When making a tag, include a leading space if \cmd{\NameQueryInfo} is used in a formatting hook (Section~\ref{sec:DataTagHooks}) and such space is desired. Otherwise avoid leading spaces. Another way uses a conditional: +% ^^A +% \begin{VerbatimOut}{\jobname.tmp} +% \makeatletter +% \NameAddInfo[George]{Washington} +% {\if@nameauth@InHook{ }\fi(1732--99)} +% \makeatother +% \end{VerbatimOut} +% ^^A +% \begin{Quote} +% \VerbatimInput[gobble=0]{\jobname.tmp} +% +% \input{\jobname.tmp} +% \end{Quote} % % \DescribeMacro{\NameQueryInfo} -% To print a name tag for a given name, we use \cmd{\NameQueryInfo}, a helper macro that prints a name tag in the name info data set: +% To print a name tag for a given name, we use \cmd{\NameQueryInfo}, either from an arbitrary set of name arguments, or from the previously-evaluated name arguments if a null argument is given. It prints a name tag from the name info data set: % % \begin{SyntaxBox} -% \cmd{\NameQueryInfo}\oarg{FNN}\marg{SNN|,| Affix}\oarg{Alternate} +% \cmd{\NameQueryInfo}\oarg{FNN}\marg{SNN\textbf{,}Affix}\oarg{Alternate}\\ +% \cmd{\NameQueryInfo\{\}} % \end{SyntaxBox} % -% \cmd{\NameQueryInfo[George]\{Washington\}} prints the name tag for \LWash: -% \NameQueryInfo[George]{Washington}. In Section~\ref{sec:DataTagHooks} and thereafter we show how one can automate the retrieval of name tags using formatting hooks, Yet therein also lies a caution: -% % \begin{itemize} -% \item When using the recommended template for a formatting hook (Section~\ref{sec:DataTemp}), one can use \cmd{\noexpand} in arguments for \cmd{\NameAddInfo}, \cmd{\NameQueryInfo}, and \cmd{\NameClearInfo} without restriction. -% -% \item 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. +% \item With name arguments, using the pattern for those arguments:\\ +% |\NameQueryInfo[George]{Washington}|\dotfill^^A +% \NameQueryInfo[George]{Washington}\JustIndex\Wash +% \PatInfo[-4ex]{\ShowPattern[George]{Washington}!DB\break +% \ShowPattern{Elizabeth, I}!MN\break +% \ShowPattern{Elizabeth, I}!DB} +% +% \item With a null argument, using the pattern from the last name used:\\ +% |\LEliz\ \NameQueryInfo{}|\dotfill^^A +% \LEliz\ \NameQueryInfo{} % \end{itemize} % -% One can insert a space at the start of a name tag; use signs like asterisks, daggers, and the like; and even create footnotes, such as footnote \addtocounter{footnote}{1}\arabic{footnote}\addtocounter{footnote}{-1} (below): +% \DescribeMacro{\NameClearInfo} +% \cmd{\NameAddInfo} will replace one name tag with another name tag, but it does not delete a tag. That is the role of \cmd{\NameClearInfo}. The syntax is: % -% \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}.}} +% \begin{SyntaxBox} +% \cmd{\NameClearInfo}\oarg{FNN}\marg{SNN\textbf{,}Affix}\oarg{Alternate} +% \end{SyntaxBox} % -% 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. +% \PatInfo*{\ShowPattern[George]{Washington}!DB\break +% \ShowPattern[George]{Washington}!MN}^^A +% We now revisit \LWash\ and his associated name tag. +%^^A +% \begin{VerbatimOut}{\jobname.tmp} +% The name tag for \Wash\ is: \NameQueryInfo{}\\ +% Clearing the tag.\NameClearInfo[George]{Washington} +% \ifcsdef{George!Washington!DB} +% {The tag exists}{The tag is gone.} % \end{VerbatimOut} -% -% \begin{quote} -% \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} +%^^A +% \begin{Quote} % \VerbatimInput[gobble=0]{\jobname.tmp} % % \input{\jobname.tmp} -% \end{quote} -% -% \newpage -% -% 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 prevents calling a naming macro. This prevents a stack overflow. |\Name*[Ulysses S.]{Grant}| would not print inside a formatting hook, although |\NameQueryInfo[Ulysses S.]{Grant}| would print. +% \end{Quote} % -% Name\Warn{} tags can call each other. To protect against a stack overflow, use Boolean flags and conditional statements. Below, \cmd{\NameQueryInfo} calls a tag that sets a Boolean flag true, which causes the \emph{other} tag to stop any recursion and exit. +% \subsection{Name Tags in Hooks} +% \label{sec:DataTagHooks} % +% \Info*{\small\dbend}When calling name tags in formatting hooks (Section~\ref{sec:Formatting}), it helps to remember that they can call other tags as well. Here we offer a quick reminder to stop potential recursion, either with Boolean flags or locally-defined macros. We show the latter below; note the extra grouping tokens: +%^^A % \begin{VerbatimOut}{\jobname.tmp} -% \newif\ifA -% \newif\ifB % \NameAddInfo{A} -% {\Atrue A \ifB Stop \else \NameQueryInfo{B} \fi \Afalse} +% {{\newcommand\A{Tag A} \A \unless\ifdefined\B \NameQueryInfo{B} \fi}} % \NameAddInfo{B} -% {\Btrue B \ifA Stop \else \NameQueryInfo{A} \fi \Bfalse} +% {{\newcommand\B{Tag B} \B \unless\ifdefined\A \NameQueryInfo{A} \fi}} +% % \begin{itemize} % \item \NameQueryInfo{A} % \item \NameQueryInfo{B} % \end{itemize} % \end{VerbatimOut} -% -% \begin{quote} +%^^A +% \begin{Quote} % \VerbatimInput[gobble=0]{\jobname.tmp} % % \input{\jobname.tmp} -% \end{quote} +% \end{Quote} % -% \DescribeMacro{\NameClearInfo} -% \cmd{\NameAddInfo} will replace one name tag with another name tag, but it does not delete a tag. That is the role of \cmd{\NameClearInfo}. The syntax is: +% With version 4.1 of \textsf{nameauth}, printing name tags in hooks has become easy. For example, we can print tags with the first use of a name. Formatting hooks are called within a local scope. They can take zero arguments, where they insert macros like font switches before a name. They also can take one argument, where they start to more complex actions (Section~\ref{sec:AdvancedFormat}). Here are two basic tips: +% \begin{itemize} +% \item Use the recommended template as a base model for custom hooks. % -% \begin{SyntaxBox} -% \cmd{\NameClearInfo}\oarg{FNN}\marg{SNN|,| Affix}\oarg{Alternate} -% \end{SyntaxBox} +% \item Keep all changes local to the formatting hooks. +% \end{itemize} +% +% Below we recommend a starter hook template that uses \cmd{\NameQueryInfo} with a null argument (Section~\ref{sec:NullArgs}) to print the tag with the first use of a name: +% \begin{Quote} +% \begin{Verbatim} +% \renewcommand*\NamesFormat[1] +% {#1\NameQueryInfo{}} +% \end{Verbatim} +% \end{Quote} +% +% Here is another example with more nuanced control: +% \begin{Quote} +% \begin{Verbatim} +% \newif\ifNoTag +% \renewcommand*\NamesFormat[1] +% {% +% #1\unless\ifNoTag\NameQueryInfo{}\fi +% \global\NoTagfalse% +% } +% \end{Verbatim} +% \end{Quote} % -% We now revisit \LWash\ and his associated name tag. \PatInfo{\ShowPattern[George]{Washington}!DB} +% We saw this next example in Section~\ref{sec:Complexity}. If the tag is in a hook, it adds a space before it. Otherwise it adds no space. The color and font switches match the conventions of this manual: +% \begin{Quote} +% \begin{Verbatim} +% \makeatletter +% \NameAddInfo{Elizabeth, I}{\if@nameauth@InHook{ }\fi``Gloriana''} +% \makeatother +% \renewcommand*\NamesFormat[1] +% {\color{blue}\sffamily #1\NameQueryInfo{}} +% \renewcommand*\MainNameHook{\sffamily} +% \end{Verbatim} +% \end{Quote} % +% \Info*{\small\dbend}Even though the core name engine has a ``locked path'' to protect against being reentrant, that does not prevent all problems. Below we show an example of a solution that will avoid halting \LaTeX\ with an error. We ensure that, if we are in a formatting hook, we will not call an infinite series of \cmd{\NameQueryInfo}. Take care to note what happens in a formatting hook, and what happens outside of a hook. +%^^A % \begin{VerbatimOut}{\jobname.tmp} -% The name tag is: \fbox{\NameQueryInfo[George]{Washington}}\quad -% Clearing data.\NameClearInfo[George]{Washington}\quad -% The name tag is empty: \fbox{\NameQueryInfo[George]{Washington}} -% \end{VerbatimOut} +% \makeatletter +% \NameAddInfo[Ulysses S.]{Grant} +% {\if@nameauth@InHook\ (term 1869--1877)\else +% eighteenth US president (1869--1877)\fi} +% \NameAddInfo[Schuyler]{Colfax} +% {\if@nameauth@InHook\ (seventeenth US vice-president)\else +% \footnote{\Name[Schuyler]{Colfax} was the seventeenth +% US vice-president during the first term (1869--1873) +% of \Name*[Ulysses S.]{Grant}, \NameQueryInfo{}.}\fi} +% \makeatother % -% \begin{quote} +% \renewcommand*\NamesFormat{} +% \renewcommand*\MainNameHook{} +% +% Let's remember \Name[Schuyler]{Colfax}.\NameQueryInfo{} +% Derived from ``scholar'', this name can occur +% as ``Skylar'' for girls and ``Skyler'' for boys. +% +% \renewcommand*\NamesFormat[1]{#1\NameQueryInfo{}} +% +% \ForgetThis\Name[Ulysses S.]{Grant} had a poor reputation among +% radical Republicans, especially the Forty-Eighters. Again we note +% \ForgetThis\Name[Schuyler]{Colfax}. +% \end{VerbatimOut} +%^^A +% \begin{Quote} +% \PatInfo[3.5ex]{\ShowPattern[Ulysses S.]{Grant}!DB\break +% \ShowPattern[Schuyler]{Colfax}!DB\break +% \ShowPattern[Schuyler]{Colfax}!MN\break +% \ShowPattern[Ulysses S.]{Grant}!MN} % \VerbatimInput[gobble=0]{\jobname.tmp} % % \input{\jobname.tmp} -% \end{quote} +% \end{Quote} +% % \ReturnLink % -% \begin{Quote}{\ForgetThis\Name{Confucius}, \textit{The Analects}, C II (475–221 \textsc{bc})} -% 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.^^A -% \index{north star, concept of\noexpand\string|hyperpage}^^A -% \index{philosophers, quotes of\noexpand\string|hyperpage} -% \end{Quote} +% \begin{Quotation}{\Name[Leonard]{Bernstein}} +% {``What Makes Opera Grand?'', \Title{Vogue} (December 1958)} +% \textls[8]{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.} +% \index{creatives, quotes of\noexpand\string|hyperpage} +% \end{Quotation} % % \newpage % @@ -5868,16 +7423,19 @@ and version 1.3 or later is part of all distributions of LaTeX version % \subsection{Basic Formatting} % \label{sec:Formatting} % -% 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: +% This section gives a basic overview. Section~\ref{sec:AdvancedFormat} explores automation and more. +% +% \negmedskip +% \subsubsection*{\hfil Syntactic Changes} +% +% Even with the default options for \textsf{nameauth} wherein no font changes occur, we can observe syntactic changes to names: % % \begingroup % \renewcommand\NamesFormat{} % \renewcommand\MainNameHook{} -% \renewcommand\FrontNamesFormat{} -% \renewcommand\FrontNameHook{} -% \begin{tcolorbox}[colframe=naslate,colback=white, +% \begin{tcolorbox}[colframe=gray,colback=white, % adjusted title={\large\hfil Syntactic Changes; -% No Formatting/Post-Processing}]\centering +% No Formatting or Post-Processing}]\centering % \begin{tabular}{llll}\toprule % \bfseries First Instance & \bfseries Macro & \bfseries Later Instance & \bfseries Macro\\\midrule % \ForgetThis\Patton & \cmd{\Patton} & \Patton & \cmd{\Patton}\\ @@ -5890,36 +7448,39 @@ and version 1.3 or later is part of all distributions of LaTeX version % \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. -% +% We can add formatting to these changes by using formatting hooks. In its basic form, this refers to font changes. In its advanced form, one can add or modify text elements, syntactic forms of names, and so on, while leaving index entries undisturbed (Section~\ref{sec:AltFormat}). Although we have encountered examples of syntactic name changes since the start of this manual, here we define that behavior formally: % \begin{itemize} % \item First instance of a name % \begin{itemize} -% \item No name control sequence exists. +% \item No name pattern exists. +% % \item A name is printed with its long form (default). +% % \item The ``first-use'' formatting hook is used (default). -% \item After the name is printed, a name control sequence is created. +% +% \item After the name is printed, a name pattern is created. % \end{itemize} +% % \item Subsequent instance of a name % \begin{itemize} -% \item A name control sequence already exists. +% \item A name pattern already exists. +% % \item A name is printed using a shorter form (default). +% % \item The ``subsequent-use'' formatting hook is used (default). % \end{itemize} % \end{itemize} % -% The parser and related macros create name forms and formats only in the text. Macros in name arguments affect both text and index (Section~\ref{sec:AltFormat}). +% \subsubsection*{\hfil Two Formatting Systems} +% +% Many books are structured with front matter that includes a table of contents, foreword, introductory 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}), linked to name patterns (Section~\ref{sec:NamePatterns}). % % \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. % -% 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. -% -% \newpage +% \Global Both \cmd{\NamesInactive} and \cmd{\NamesActive} can be used explicitly as a pair or singly within a local scope. Use \cmd{\global} to force a global effect. % % \DescribeMacro{\NamesFormat} % The main-matter system uses \cmd{\NamesFormat} to post-process first occurrences of names and @@ -5929,19 +7490,16 @@ and version 1.3 or later is part of all distributions of LaTeX version % 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. 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. Especially with the macros in this section, the naming scheme is unfortunate because package development involved some groping in the dark regarding the concepts.} -% 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: -% -% \begin{quote} +% Below we color-code the systems and ``forget'' previous name uses: +% \begin{Quote} % \ForgetName[Rudolph]{Carnap} -% \vspace{4ex} -% \PatInfo{\textrm{front-matter}\hfill\break +% \PatInfo[4ex]{\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, +% \begin{tcolorbox}[colframe=violet,colback=white, % adjusted title={\large\hfil Front-matter system: \cmd{\NamesInactive}}] % \NamesInactive % \begin{tabular}{ll} @@ -5962,289 +7520,310 @@ and version 1.3 or later is part of all distributions of LaTeX version % \Name[Nicolas]{Malebranche} & |\Name[Nicolas]{Malebranche}|\\ % \end{tabular} % \end{tcolorbox} -% \end{quote} +% \end{Quote} % % We used the \textsf{xcolor} package with the following macros: -% \begin{quote} +% \begin{Quote} % \begin{Verbatim} -% \renewcommand*\FrontNamesFormat[1]{\color{red}\sffamily #1} +% \renewcommand*\FrontNamesFormat[1]{\color{violet}\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} +% \end{Quote} % % \DescribeMacro{\ForceName} -% 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} -% \Name[Rudolph]{Carnap}^^A -% \PatInfo{\ShowPattern[Rudolph]{Carnap}!MN} -% \cmd{\Name[Rudolph]\{Carnap\}} \\[1ex] -% \ForceName\Name[Rudolph]{Carnap} +% Use this prefix macro to force ``first use'' formatting for the next \cmd{\Name}, etc., but without deleting any name patterns. See also Sections~\ref{sec:DataTagHooks}, \ref{sec:NameControl}, and~\ref{sec:AKA}. Thus: +% \begin{Block} +% \PatInfo*{\ShowPattern[Rudolph]{Carnap}!MN}^^A +% \Name[Rudolph]{Carnap}\dotfill^^A +% \cmd{\Name[Rudolph]\{Carnap\}}\\ +% \ForceName\Name[Rudolph]{Carnap}\dotfill^^A % \cmd{\ForceName}\cmd{\Name[Rudolph]\{Carnap\}} -% \end{quote} +% \end{Block} % -% Below\Info{\texttt{alwaysformat}} we simulate \texttt{alwaysformat} via package internals. Only the ``first use'' formatting hooks are used: +% \begin{InfoBox} +% In cases where formatting also changes the syntactic form of a name in addition to its typography (Section~\ref{sec:AltFormat}f.), \cmd{\ForceName} could interfere with \cmd{\ForceFN} and \cmd{\ForceAffix}. +% \end{InfoBox} % +% \Info*{\small\texttt{alwaysformat}}Below we simulate \texttt{alwaysformat} via package internals. Only the ``first use'' formatting hooks are used. This is a relic from early versions of \textsf{nameauth}. % \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 -% % \subsubsection*{\hfil Hook caveats} % -% The internal name parser determines what syntactic name elements exist and how they are constituted. It passes that information to macros that determine the form of nonwestern 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} -% \cmd{\bgroup}\meta{Hook}\texttt{\{\#1\}}\cmd{\egroup}. -% \end{quote} +% The core name engine determines what syntactic name elements exist and how they are to be displayed (Sections~\ref{sec:NullArgs} and~\ref{sec:AdvancedFormat}). The format hook dispatcher passes the name to the formatting hooks within a local scope:\footnote{We moved \cmd{\@nameauth@InHooktrue} into the immediate hook groups from the beginning of the hook dispatcher to make the logic and functionality more obvious to read.} +% \begin{itemize} +% \item[] \cmd{\bgroup}\cmd{\@nameauth@InHooktrue}\meta{Hook}\texttt{\{\#1\}}\cmd{\egroup}. +% \end{itemize} +% Due to this design, both the following achieve the same effect: +% \begin{itemize} +% \item[] \cmd{\renewcommand*}\cmd{\NamesFormat\{}\cmd{\itshape}\texttt{\}} +% \item[] \cmd{\renewcommand*}\cmd{\NamesFormat\{}\cmd{\textit}\texttt{\}} +% \end{itemize} % % 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} -% \cmd{\renewcommand*}\cmd{\NamesFormat\{}\meta{content}\texttt{\}}\\ -% \cmd{\renewcommand*}\cmd{\NamesFormat[1]\{}\meta{content}\texttt{\}} -% \end{quote} -% -% 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} -% \cmd{\renewcommand*}\cmd{\NamesFormat\{}\cmd{\itshape}\texttt{\}}\\ -% \cmd{\renewcommand*}\cmd{\NamesFormat\{}\cmd{\textit}\texttt{\}} -% \end{quote} +% \begin{itemize} +% \item[] \cmd{\renewcommand*}\cmd{\NamesFormat\{}\meta{content}\texttt{\}} +% \item[] \cmd{\renewcommand*}\cmd{\NamesFormat[1]\{}\meta{content}\texttt{\}} +% \end{itemize} +% A hook with one argument has more options than a font switch (Section~\ref{sec:SpecialUses}). To test if one is in a formatting hook, use |\if@nameauth@InHook| (Sections~\ref{sec:Complexity} and~\ref{sec:DataTags}). % % \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: -% +% 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} below, \cmd{\MainNameHook} is called instead of \cmd{\NamesFormat} because \Harnack\ occurred above. We could use \cmd{\ForgetThis} (Section~\ref{sec:NameControl}) in the footnote to change that behavior. Another way uses the front-matter system and a redefined footnote macro: +%^^A % \begin{VerbatimOut}{\jobname.tmp} % \makeatletter % \let\@oldfntext\@makefntext % \long\def\@makefntext#1{\NamesInactive\@oldfntext{#1}\NamesActive} % \makeatother % \end{VerbatimOut} -% -% \begin{quote} -% \vspace{4ex} -% \PatInfo{\ShowPattern[Adolf]{Harnack}!MN\break +%^^A +% \begin{Quote} +% \PatInfo[4ex]{\ShowPattern[Adolf]{Harnack}!MN\break % \ShowPattern[Adolf]{Harnack}!NF} -% \vspace{-4ex} % \VerbatimInput[gobble=0]{\jobname.tmp} -% \end{quote} +% \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 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: -% +% Now we see different results.\footnote{We have \Harnack\ from \cmd{\Harnack}, then \Harnack.} +% Footnote \arabic{footnote} shows the first use of a name because it is the first use in the front-matter system. Below we revert footnotes with: +%^^A % \begin{VerbatimOut}{\jobname.tmp} % \makeatletter % \let\@makefntext\@oldfntext % \makeatother % \end{VerbatimOut} -% -% \begin{quote} +%^^A +% \begin{Quote} % \VerbatimInput[gobble=0]{\jobname.tmp} -% \end{quote} +% \end{Quote} % \input{\jobname.tmp} % -% \begin{Quote}{\ForgetThis\Name[M.T.]{Cicero}[Marcus Tullius], \textit{De oratore} B II; C IX, \S 36 (55 \textsc{BC})} -% 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?^^A -% \index{Romans, quotes of\noexpand\string|hyperpage} -% \end{Quote} +% \begin{Quotation}{\Name{Confucius}} +% {\Title{The Analects}, C II (475--221 \textsc{bc})} +% 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. +% \index{philosophers, quotes of\noexpand\string|hyperpage} +% \end{Quotation} % % \newpage % % \subsection{Making Name Decisions} % \label{sec:NameControl} % -% 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}). +% The macros that switch between name systems are local (\cmd{\NamesActive} and \cmd{\NamesInactive}). Otherwise, all the macros below are \emph{global} with respect to name patterns and scoping. Unless restricted to the current name system by \cmd{\LocalNames}, they affect both name systems. % +% Creating and deleting name patterns affects syntactic name forms, formatting, index protection of cross-references (Section~\ref{sec:IndexRef}), and the outcomes of name tests (Section~\ref{sec:NameTests}). % % \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 instance of that name will display as if the name did not yet exist: +% This macro ``forgets'' a name by deleting its pattern. That forces a ``pre-first use'' state. The core name engine treats the name as a first use. Some test results change (Section~\ref{sec:NameTests}), and name protection for indexing is removed, similar to the way that \cmd{\IncludeName*} ``unprotects'' xrefs (Section~\ref{sec:IdxFine}). % % \begin{SyntaxBox} -% \cmd{\ForgetName}\oarg{FNN}\marg{SNN|,| Affix}\oarg{Alternate} +% \cmd{\ForgetName}\oarg{FNN}\marg{SNN\textbf{,}Affix}\oarg{Alternate} % \end{SyntaxBox} % -% \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 entries. -% % \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, we forget him and again have a first instance via |\ForgetThis\Einstein|: \ForgetThis\Einstein. \cmd{\ForgetThis} no longer affects the index unless one uses the \texttt{oldreset} option. +% This macro makes the name engine ``forget'' the name pattern just before the parser, printing the name as a first use, then ``remembering'' the name. This can affect some tests in formatting hooks. After knowing \Einstein, we forget him again:\footnote{\cmd{\ForgetThis} no longer affects the index unless one uses the \texttt{oldreset} option. Likewise, \cmd{\SubvertThis} no longer affects the index unless one uses the \texttt{oldreset} option.} +% \begin{Block} +% \ForgetThis\Einstein\dotfill |\ForgetThis\Einstein| +% \end{Block} % % \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}: +% This macro ``subverts'' a name by creating a name pattern. This makes the name engine handle a name as a subsequent use, changes some test results, and ``protects'' a name from being used as a \textit{see} reference, analogous to \cmd{\ExcludeName} and \cmd{\IndexRef}: % % \begin{SyntaxBox} -% \cmd{\SubvertName}\oarg{FNN}\marg{SNN|,| Affix}\oarg{Alternate} +% \cmd{\SubvertName}\oarg{FNN}\marg{SNN\textbf{,}Affix}\oarg{Alternate} % \end{SyntaxBox} % % \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. +% This macro causes the name egine to create a name pattern just before the parser, printing the name as a subsequent use. This can affect some tests in formatting hooks. \cmd{\ForgetThis} has a higher priority than \cmd{\SubvertThis} and negates it (Section~\ref{sec:Priorities}). % % \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. +% We advise users to avoid using \cmd{\ForgetThis} and \cmd{\SubvertThis} before any macro that does not print a name in the text. % \end{InfoBox} % -% \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{itemize} +% \item \DescribeMacro{\LocalNames} The helper macro \cmd{\LocalNames} restricts the macros above to the \emph{current} name system, but not to any 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}): +% \item \DescribeMacro{\GlobalNames} The helper macro \cmd{\GlobalNames} restores the effects of these macros to \emph{both name systems.} +% \end{itemize} +% +% In the next example we define a macro that reports whether or not the specific name |\Name[Charlie]{Chaplin}|\JustIndex\Name[Charlie]{Chaplin} exists. There are four outcomes: the name exists in the main matter, in the front matter, in both name systems, or it does not exist. The naming macros use the current name system. The macros on this page affect both name systems by default. +% +% \newpage % % \begin{VerbatimOut}{\jobname.tmp} -% \def\CheckChuck{{\bfseries\IfFrontName[Charlie]{Chaplin} -% {\IfMainName[Charlie]{Chaplin}{both}{front}} -% {\IfMainName[Charlie]{Chaplin}{main}{none}}}} -% \end{VerbatimOut} +% \newcommand\CheckChuck{{Name systems: +% \IfFrontName[Charlie]{Chaplin} +% {\bfseries\IfMainName[Charlie]{Chaplin}{in both}{in front}} +% {\bfseries\IfMainName[Charlie]{Chaplin}{in main}{in none}}}} % -% \begin{quote} -% \VerbatimInput[gobble=0]{\jobname.tmp} -% \end{quote} -% \input{\jobname.tmp} +% Create a name pattern in both systems\dotfill +% \SubvertName[Charlie]{Chaplin}\CheckChuck % -% \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} +% Restrict to the current (main) name system. \LocalNames % -% \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} +% Forget a name in the main-matter system\dotfill +% \ForgetName[Charlie]{Chaplin}\CheckChuck % -% \item Switch to the ``front-matter'' system and create a name. -% \PatInfo{\ShowPattern[Charlie]{Chaplin}!NF} -% If one 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} +% Restored: \Name[Charlie]{Chaplin}\dotfill\CheckChuck % -% \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} +% Switch to the front matter. \NamesInactive % -% \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} +% Forget a name in the front-matter system\dotfill +% \ForgetName[Charlie]{Chaplin}\CheckChuck % -% \item Next ``subvert'' the front-matter name to ``remember'' it again. -% Then switch to main matter: -% \begin{itemize}[rightmargin=2\leftmargin] -% \item[] |\SubvertName[Charlie]{Chaplin}|\SubvertName[Charlie]{Chaplin} -% \item[] |\CheckChuck|\dotfill \CheckChuck -% \item[] |\global\NamesActive|\global\NamesActive -% \end{itemize} +% Restored: \Name[Charlie]{Chaplin}\dotfill\CheckChuck % -% \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} +% Switch to the main matter. \NamesActive % -% \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} +% Lift name system restrictions. \GlobalNames % -% \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} +% Forget a name in both systems\dotfill +% \ForgetName[Charlie]{Chaplin}\CheckChuck +% \end{VerbatimOut} +% \begin{Quote} +% \VerbatimInput[gobble=0]{\jobname.tmp} +% +% \PatInfo[3ex]{\ShowPattern[Charlie]{Chaplin}!MN\break +% \ShowPattern[Charlie]{Chaplin}!NF} +% \input{\jobname.tmp} +% \end{Quote} % -% \subsection{Formatting and Decisions} +% \subsection{Summary} % -% We pull together information on name forms and formatting, focusing on what happens in one naming system only, since the two systems are independent. +% \begingroup +% We summarize info on name forms and formatting, using the following macros: +% \begin{Quote} +% \begin{Verbatim} +% \renewcommand*\NamesFormat[1] +% {\color{blue}\sffamily#1\NameQueryInfo{}} +% \renewcommand*\MainNameHook{\sffamily} +% \begin{nameauth} +% \< Bailey & Betsey & Bailey & > +% \< Faisal & & Faisal, bin Abdulaziz & > +% \end{nameauth} +% \NameAddInfo{Faisal, bin Abdulaziz}{ Al Saud} +% \TagName{Faisal, bin Abdulaziz}{ Al Saud, king} +% \end{Verbatim} +% \end{Quote} +% \renewcommand*\NamesFormat[1] +% {\color{blue}\sffamily#1\NameQueryInfo{}} +% \renewcommand*\MainNameHook{\sffamily} % +% Now we show the macros at work. Regarding the automatic use of the name tag in the first-use hook, see Section~\ref{sec:DataTagHooks}. +% \phantomsection % \begin{itemize}[leftmargin=3cm]\small -% \item[First Instance:] \ForgetThis\Bailey \dotfill \cmd{\Bailey}\\ -% \ForgetThis\LBailey \dotfill \cmd{\LBailey}\\ -% \ForgetThis\SBailey \dotfill \cmd{\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 Instance:] \Bailey \dotfill \cmd{\Bailey}\\ -% \LBailey \dotfill \cmd{\LBailey}\\ -% \SBailey \dotfill \cmd{\SBailey}\\ +% \item[\hypertarget{FirstI}{First Instance:}] +% \PatInfo[3ex]{\ShowPattern[Betsey]{Bailey}!MN\break +% \ShowPattern{Faisal, bin Abdulaziz}!MN} +% Name pattern created with text output. +% Index state 2, 4, or 6 (Section~\ref{sec:RuleStates}). +% Name form: long. First-use hooks. +% \item[] \ForgetThis\Bailey \dotfill \cmd{\Bailey}\\ +% \hbox{}\hfill \cmd{\LBailey}\\ +% \hbox{}\hfill \cmd{\SBailey} +% \item[] \ForgetThis\Faisal \dotfill \cmd{\Faisal}\\ +% \hbox{}\hfill \cmd{\LFaisal}\\ +% \hbox{}\hfill \cmd{\SFaisal} +% +% \item[\hypertarget{LaterI}{Later Instance:}] % No change to name pattern. Index state 2, 4, or 6. -% Name form: short. Subsequent-use hooks. -% -% \item[Forgotten:] (no output)\ForgetName[Betsey]{Bailey} \dotfill^^A -% \cmd{\ForgetName[Betsey]\{Bailey\}}\\ -% Name pattern deleted. Index state 1, 3, or 5 -% (Section~\ref{sec:RuleStates}). -% next instance usually will be a first use, e.g.: \Bailey. -% -% \item[Subverted:] (no output)\SubvertName[Betsey]{Bailey} \dotfill^^A -% \cmd{\SubvertName[Betsey]\{Bailey\}}\\ -% Name pattern created. Index state 2, 4, or 6. -% next instance usually will be a later use, e.g.: \Bailey, \LBailey, \SBailey. +% Name form: short or long. Subsequent-use hooks. +% \item[] \Bailey \dotfill^^A +% \cmd{\Bailey} +% \item[] \LBailey \dotfill^^A +% \cmd{\LBailey} +% \item[] \SBailey \dotfill^^A +% \cmd{\SBailey} +% \item[] \Faisal \dotfill^^A +% \cmd{\Faisal}\\ +% \hbox{}\hfill \cmd{\SFaisal} +% \item[] \LFaisal \dotfill^^A +% \cmd{\LFaisal} +% \item[] \ForceFN\SFaisal \dotfill^^A +% \cmd{\ForceFN}\cmd{\SFaisal} +% +% \item[Forgotten:] +% Name pattern deleted. Index state 1, 3, or 5. +% Next instance usually will be a +% \hyperlink{FirstI}{first instance}. +% \item[] (no output)\ForgetName[Betsey]{Bailey}^^A +% \dotfill \cmd{\ForgetName[Betsey]\{Bailey\}} +% \item[] (no output)\ForgetName{Faisal, bin Abdulaziz}^^A +% \dotfill |\ForgetName{Faisal, bin Abdulaziz}| +% +% \item[Subverted:] +% Name pattern created. Index state 2, 4, or 6. +% Next instance usually will be a +% \hyperlink{LaterI}{later instance}. +% \item[] (no output)\SubvertName[Betsey]{Bailey}^^A +% \dotfill \cmd{\SubvertName[Betsey]\{Bailey\}} +% \item[] (no output)\SubvertName{Faisal, bin Abdulaziz}^^A +% \dotfill |\SubvertName{Faisal, bin Abdulaziz}| % % \item[\cmd{\ForgetThis}:] -% \ForgetThis\Bailey \dotfill \cmd{\ForgetThis}\cmd{\Bailey}\\ -% \ForgetThis\LBailey \dotfill \cmd{\ForgetThis}\cmd{\LBailey}\\ -% \ForgetThis\SBailey \dotfill \cmd{\ForgetThis}\cmd{\SBailey}\\ -% Name pattern deleted, then created again. Index state 2, 4, or 6. -% Name form and format: same as first use above. next instance usually -% will be a later use, e.g.: \Bailey, \LBailey, \SBailey. +% Name pattern deleted, then created again. +% Index state 2, 4, or 6. Name form and format: +% \hyperlink{FirstI}{first instance}. +% Next instance usually will be a +% \hyperlink{LaterI}{later instance}. +% \item[] \ForgetThis\Bailey \dotfill \cmd{\ForgetThis}\cmd{\Bailey}\\ +% \hbox{}\hfill \cmd{\ForgetThis}\cmd{\LBailey}\\ +% \hbox{}\hfill \cmd{\ForgetThis}\cmd{\SBailey} +% \item[] \ForgetThis\Faisal \dotfill \cmd{\ForgetThis}\cmd{\Faisal}\\ +% \hbox{}\hfill \cmd{\ForgetThis}\cmd{\LFaisal}\\ +% \hbox{}\hfill \cmd{\ForgetThis}\cmd{\SFaisal} % % \item[\cmd{\SubvertThis}:] -% \SubvertThis\Bailey \dotfill \cmd{\SubvertThis}\cmd{\Bailey}\\ -% \SubvertThis\LBailey \dotfill \cmd{\SubvertThis}\cmd{\LBailey}\\ -% \SubvertThis\SBailey \dotfill \cmd{\SubvertThis}\cmd{\SBailey}\\ -% Name pattern created. Index state 2, 4, or 6. -% Name form and format: same as later use above. next instance usually -% will be a later use, e.g.: \Bailey, \LBailey, \SBailey. +% Name pattern created. Index state 2, 4, or 6. +% Name form and format: \hyperlink{LaterI}{later instance}. +% Next instance usually will be a +% \hyperlink{LaterI}{later instance}. +% \item[] \SubvertThis\Bailey \dotfill^^A +% \cmd{\SubvertThis}\cmd{\Bailey} +% \item[] \SubvertThis\LBailey \dotfill^^A +% \cmd{\SubvertThis}\cmd{\LBailey} +% \item[] \SubvertThis\SBailey \dotfill^^A +% \cmd{\SubvertThis}\cmd{\SBailey} +% \item[] \SubvertThis\Faisal \dotfill^^A +% \cmd{\SubvertThis}\cmd{\Faisal}\\ +% \hbox{}\hfill \cmd{\SubvertThis}\cmd{\SFaisal} +% \item[] \SubvertThis\LFaisal \dotfill^^A +% \cmd{\SubvertThis}\cmd{\LFaisal} +% \item[] \SubvertThis\ForceFN\SFaisal \dotfill^^A +% \cmd{\SubvertThis}\cmd{\ForceFN}\cmd{\SFaisal} % % \item[Format as First:] -% \ForceName\Bailey \dotfill \cmd{\ForceName}\cmd{\Bailey}\\ -% \ForceName\LBailey \dotfill \cmd{\ForceName}\cmd{\LBailey}\\ -% \ForceName\SBailey \dotfill \cmd{\ForceName}\cmd{\SBailey}\\ -% No change to name pattern. Index state 2, 4, or 6. -% Name form: short or long. Name format: First-use hooks. +% No change to name pattern. Index state 2, 4, or 6. +% Name form: short or long. Name format: First-use hooks. +% \item[] \ForceName\Bailey \dotfill^^A +% \cmd{\ForceName}\cmd{\Bailey} +% \item[] \ForceName\LBailey \dotfill^^A +% \cmd{\ForceName}\cmd{\LBailey} +% \item[] \ForceName\SBailey \dotfill^^A +% \cmd{\ForceName}\cmd{\SBailey} +% \item[] \ForceName\Faisal \dotfill^^A +% \cmd{\ForceName}\cmd{\Faisal} +% \item[] \ForceName\LFaisal \dotfill^^A +% \cmd{\ForceName}\cmd{\LFaisal} +% \item[] \ForceName\SFaisal \dotfill^^A +% \cmd{\ForceName}\cmd{\SFaisal} +% \item[] \ForceName\ForceFN\SFaisal \dotfill^^A +% \cmd{\ForceName}\cmd{\ForceFN}\cmd{\SFaisal} % \end{itemize} -% -% \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.^^A -% \index{politicians, quotes of\noexpand\string|hyperpage}^^A -% \index{Shakespearian rose, references to\noexpand\string|hyperpage} -% \end{Quote} -% -% \newpage +% \endgroup % % \subsection{Testing Name Decisions} % \label{sec:NameTests} @@ -6256,72 +7835,72 @@ and version 1.3 or later is part of all distributions of LaTeX version % 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. % % \DescribeMacro{\GlobalNameTest} -% The default behavior encapsulates the decision paths in a local scope, insulating any changes therein. +% The default behavior \emph{encapsulates the decision paths in a local scope,} insulating some 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. +% If this is not desired, use the \texttt{globaltest} option or \cmd{\GlobalNameTest}. \cmd{\LocalNameTest} will re-enable the default. Any naming macros (\cmd{\Name}, etc.) used in these paths will have global assignments associated with them, i.e., name patterns, tags, etc. % % \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: +% In order to test whether or not a ``main matter'' name pattern exists, use this long macro that can accommodate paragraph breaks: % % \begin{SyntaxBox} -% \cmd{\IfMainName}\oarg{FNN}\marg{SNN|,| Affix}\oarg{Alternate}^^A +% \cmd{\IfMainName}\oarg{FNN}\marg{SNN\textbf{,}Affix}\oarg{Alt.}^^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: -% +% For example we have not encountered |\Name[Bob]{Hope}| yet. We could do the following test that will reflect whether or not the name is present in the text: +%^^A % \begin{VerbatimOut}{\jobname.tmp} % I heard someone say: \IfMainName[Bob]{Hope} % {Bob here!} % {No Bob here.}\IndexName[Bob]{Hope} % \end{VerbatimOut} -% -% \begin{quote} +%^^A +% \begin{Quote} % \VerbatimInput[gobble=0]{\jobname.tmp} % % \input{\jobname.tmp} -% \end{quote} +% \end{Quote} % % 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: -% +%^^A % \begin{VerbatimOut}{\jobname.tmp} % \GlobalNameTest -% \def\msg{We are unsure about \LEliz} +% \providecommand\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}} +% {\providecommand\msg{We really do know of \LEliz}} +% {\providecommand\msg{We do not know of \LEliz}} % % \parbox{0.4\textwidth}{\msg} (\cmd{\GlobalNameTest}). % % \LocalNameTest -% \def\msg{We are unsure about \LEliz} +% \providecommand\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}} +% {\providecommand\msg{We really do know of \LEliz}} +% {\providecommand\msg{We do not know of \LEliz}} % % \parbox{0.4\textwidth}{\msg} (\cmd{\LocalNameTest}). % \end{VerbatimOut} +%^^A +% \begin{Quote} +% \VerbatimInput[gobble=0,lastline=7]{\jobname.tmp} % -% \begin{quote} -% \VerbatimInput[gobble=0]{\jobname.tmp} +% \VerbatimInput[gobble=0,firstline=8]{\jobname.tmp} % % \input{\jobname.tmp} -% \end{quote} -% -% \newpage +% \end{Quote} % % \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 +% \cmd{\IfFrontName}\oarg{FNN}\marg{SNN\textbf{,}Affix}\oarg{Alt.}^^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}. -% +% This macro works just like \cmd{\IfMainName}, except using the ``front matter'' name patterns 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}. +%^^A % \begin{VerbatimOut}{\jobname.tmp} % \IfFrontName[Rudolph]{Carnap} % {\IfMainName[Rudolph]{Carnap} @@ -6331,195 +7910,182 @@ and version 1.3 or later is part of all distributions of LaTeX version % {\Name[Rudolph]{Carnap} is only in main-matter text.} % {\Name[Rudolph]{Carnap} has not been mentioned.}} % \end{VerbatimOut} -% -% \begin{quote} +%^^A +% \begin{Quote} % \VerbatimInput[gobble=0]{\jobname.tmp} % % \input{\jobname.tmp} -% \end{quote} +% \end{Quote} % % \DescribeMacro{\IfAKA} % This macro tests whether or not a regular or excluded form of cross-reference control sequence exists. The syntax is: % % \begin{SyntaxBox} -% \cmd{\IfAKA}\oarg{FNN}\marg{SNN|,|Affix}\oarg{Alternate}^^A +% \cmd{\IfAKA}\oarg{FNN}\marg{SNN\textbf{,}Affix}\oarg{Alt.}^^A % \marg{y}\marg{n}\marg{excl} % \end{SyntaxBox} % -% 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}). -% +% This macro also works like \cmd{\IfMainName}, except that it has an additional \meta{excl} branch to detect names excluded by \cmd{\ExcludeName} (Section~\ref{sec:GeneralIndex}). If we do not use \cmd{\ExcludeName}, we can leave the \meta{excl} branch empty. % \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} +% \item Cross-references (the \meta{y} path) are name patterns ending in \texttt{!PN} (Section~\ref{sec:NamePatterns}). They expand to empty. % -% Based on the known facts above, below we offer some examples: +% \item Excluded names (the \meta{excl} path) have xrefs that expand to the value of \cmd{\@nameauth@Exclude}. % -% \begin{enumerate} -% \item In\PatInfo{\ShowPattern[Jesse]{Ventura}!MN\break -% \ShowPattern[James]{Janos}!PN\break -% \ShowPattern[James]{Janos}!MN} -% the text we first create an instance of 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} +% \item \cmd{\ExcludeName} creates excluded xrefs. \cmd{\IncludeName} destroys them. % -% \begin{quote} +% \item \cmd{\IndexRef}, \cmd{\AKA}, \cmd{\AKA*}, \cmd{\PName}, and \cmd{\PName*} create xrefs, which are destroyed only by \cmd{\IncludeName*}. +% \end{itemize} +% \begin{Quote} % \begin{Verbatim} % \IfAKA[James]{Janos} % {\Name*[Jesse]{Ventura} is a stage name} % {\Name*[Jesse]{Ventura} is a regular name} -% {} +% {}. % \end{Verbatim} -% \end{quote} -% -% \newpage -% -% We can combine all these macros to create a complete, unified test: -% -% \begin{quote} +% \end{Quote} +% \PatInfo*{\ShowPattern[Jesse]{Ventura}!MN\break +% \ShowPattern[James]{Janos}!PN\break +% \ShowPattern[James]{Janos}!MN}^^A +% First we mention \Name[Jesse]{Ventura} |\Name[Jesse]{Ventura}|, pro wrestler and Minnesota governor. His lesser-known legal name, +% \IndexRef[James]{Janos}{Ventura, Jesse}\Name[James]{Janos} is an +% alias: +% |\IndexRef[James]{Janos}{Ventura, Jesse}\Name[James]{Janos}|. +% The order of the macros is important. The test above says: +% \IfAKA[James]{Janos} +% {\Name*[Jesse]{Ventura} is a stage name} +% {\Name*[Jesse]{Ventura} is a regular name} +% {}. +% We also can create a complete, unified test: +% \begin{Quote} % \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 -% }% +% \IfAKA[FNN]{SNN, Affix}[Alt.] +% {It is an xref.} +% {It is a name. +% \IfFrontName[FNN]{SNN, Affix}[Alt.] +% {% It is at least in the front matter +% \IfMainName[FNN]{SNN, Affix}[Alt.] +% {It is in both front and main matter.} +% {It is only in the front matter.}% +% } +% {% It is not in the front matter. +% \IfMainName[FNN]{SNN, Affix}[Alt.] +% {It is only in the main matter.} +% {It does not exist.}% +% }% % } -% {% -% % 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 -% } +% {It is excluded.} % \end{Verbatim} -% \end{quote} -% -% \subsubsection[Applications]{Applications: Game Books, Histories, Etc.} +% \end{Quote} % -% 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: +% \subsubsection{Applications} % -% \begin{quote} +% As we have seen, we can control name forms with \cmd{\ForgetThis} and the like. Yet we also can use tests in situations where we might not know if a name has appeared, like when a name appears in a \texttt{table} or other float environment. Thus: +% \begin{Quote} % \begin{Verbatim} -% \ifMainName[Ferris]{Bueller} -% {\Name[Cameron]{Frye} is gloomy and introspective.} -% {\Name[Cameron]{Frye} is developing positive traits.} +% \IfMainName[M.S.]{Omartian} +% {\Name[M.S.]{Omartian}} +% {\Name[M.S.]{Omartian}[Michael]} produced many number-one +% records over three decades. % \end{Verbatim} -% \end{quote} % -% 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: +% \PatInfo*{\ShowPattern[M.S.]{Omartian}} +% \IfMainName[M.S.]{Omartian} +% {\Name[M.S.]{Omartian}} +% {\Name[M.S.]{Omartian}[Michael]} produced many number-one +% records over three decades. +% \end{Quote} % -% \begin{quote} -% \JustIndex\JWG^^A +% Next we recall the movie, \textit{Ferris Bueller's Day Off}. Using conditionals, we can design statements that are sensitive to the plot. +% \begin{Quote} % \begin{Verbatim} -% \ifMainName[J.W. von]{Goethe} -% {\Name[J.W. von]{Goethe}} -% {\Name[J.W. von]{Goethe}[Johann Wolfgang von]} +% This is \FName[Cameron]{Frye}. +% \IfMainName[Ferris]{Bueller} +% {He is developing positive traits.} +% {He is gloomy and introspective.} +% \Name[Ferris]{Bueller} decides to hang out with +% \FName[Cameron]{Frye}. +% \IfMainName[Ferris]{Bueller} +% {He is developing positive traits.} +% {He is gloomy and introspective.} % \end{Verbatim} -% \end{quote} % -% 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 tags to ensure that the information associated with a given name is not anachronistic. -% -% 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 tag via name testing macros: +% This is \FName[Cameron]{Frye}. +% \IfMainName[Ferris]{Bueller} +% {He is developing positive traits.} +% {He is gloomy and introspective.} +% \Name[Ferris]{Bueller} decides to hang out with +% \FName[Cameron]{Frye}. +% \IfMainName[Ferris]{Bueller} +% {He is developing positive traits.} +% {He is gloomy and introspective.} +% \end{Quote} % +% Below, we can extend the use of conditionals to name tags. This allows different facts to appear with names, depending on what other names have appeared. We forget all names beforehand and show the following example: % \begin{VerbatimOut}{\jobname.tmp} % \NameAddInfo{Saul, of Tarsus} % {\IfMainName{Jesus, Christ} % {\IfMainName[Lucius]{Sergius Paulus} -% {renamed himself \Name{Paul}, in -% honor of his patron} +% {called himself \Name{Paul}, +% perhaps 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} % -% \Name{Saul, of Tarsus} \NameQueryInfo{Saul, of Tarsus}. +% \Name{Saul, of Tarsus} \NameQueryInfo{}. % 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. % -% \Name{Saul, of Tarsus} \NameQueryInfo{Saul, of Tarsus}. +% \Name{Saul, of Tarsus} \NameQueryInfo{}. % He undertook three missionary journeys before being % sent to Rome for trial in an appeal to Caesar. % While in Cyprus, \Name{Saul, of Tarsus} converted % \Name[Lucius]{Sergius Paulus}, who became a patron. % -% \Name{Saul, of Tarsus} \NameQueryInfo{Saul, of Tarsus}. -% Under the name \Name{Paul} he wrote his letters. +% \Name{Saul, of Tarsus} \NameQueryInfo{}. +% Under the name \Name{Paul} he wrote his letters +% during his journeys and imprisonment. % \end{VerbatimOut} -% -% \begin{quote} -% \vspace{3ex} -% \PatInfo{\ShowPattern{Paul}!PN\break +%^^A +% \begin{Quote} +% \PatInfo[3ex]{\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} % % \input{\jobname.tmp} -% \end{quote} +% \end{Quote} % % \subsubsection*{\hfil Caveats} % -% Using these tests 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. +% \begin{itemize} +% \item One should check and validate test results. That is particularly true when using the tests inside macros. See \Title{The \TeX book}, 212--15. +% +% \item See Section~\ref{sec:Noexpand} regarding the use of \cmd{\noexpand} in name arguments to stabilize name patterns so that comparisons are consistent and valid. % -% 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 See also Section~\ref{sec:Unicode} regarding possible Unicode issues. This is perhaps less of an issue in modern \TeX\ distributions. % -% In addition to these points, using the \textsf{trace} package, \cmd{\show}, or \cmd{\meaning} can help one to mitigate problems. +% \item The \textsf{trace} package, along with the macros \cmd{\show} and \cmd{\meaning}, can help debug problems. +% \end{itemize} % % \newpage % % \subsubsection{Beamer Example} % -% 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. -% +% Names will change automatically in \textsf{beamer} overlays as one advances the slides unless we control them, as shown in the following example. +%^^A % \ifdefined\NameauthDoTestFiles \edef\NameauthTestFile{test09_01.tex}\else % \edef\NameauthTestFile{\jobname.tmp}\fi -% +%^^A % \begin{VerbatimOut}{\NameauthTestFile} % \documentclass{beamer} -% \input{compat.tex} % Included with nameauth; example file aids -% % compatibility across different LaTeX versions and engines. +% \input{compat.tex} % Included with nameauth for compatibility. % \usepackage[noindex]{nameauth} % % \mode<presentation> @@ -6559,18 +8125,19 @@ and version 1.3 or later is part of all distributions of LaTeX version % of the United States. % \end{enumerate} % \end{itemize} +% % \end{frame} % % \end{document} % \end{VerbatimOut} -% -% \begin{quote} +%^^A +% \begin{Quote} % \VerbatimInput[gobble=0]{\NameauthTestFile} % \IndexName[George]{Washington} % \IndexName[Ulysses S.]{Grant} -% \end{quote} +% \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. +% The overlays, numbered from one to three, keep name forms consistent by deleting name patterns for each new overlay. Otherwise, name patterns would change for each new overlay. % % \newpage % @@ -6582,7 +8149,7 @@ and version 1.3 or later is part of all distributions of LaTeX version % \end{tcolorbox} % \IndexName[George]{Washington} % \IndexName[Ulysses S.]{Grant} -% +% \bigskip % % 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. % @@ -6595,7 +8162,7 @@ and version 1.3 or later is part of all distributions of LaTeX version % % \newpage % -% 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. +% Overlay three shows how these features integrate. A presenter can design slides that determine name forms, regardless of being re-ordered. % % \begin{tcolorbox}\centering % \IfFileExists{beamer03.pdf}{\includegraphics[scale=0.6]{beamer03.pdf}} @@ -6603,63 +8170,51 @@ and version 1.3 or later is part of all distributions of LaTeX version % \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 (published 1597)} -% '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.\negmedskip^^A -% \index{creatives, quotes of\noexpand\string|hyperpage}^^A -% \index{Shakespearian rose, references to\noexpand\string|hyperpage} -% \end{Quote} -% \AltFormatInactive +% \begin{Quotation}{\Name[Theodore]{Roosevelt}} +% {Introduction, \Title{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. +% \index{politicians, quotes of\noexpand\string|hyperpage} +% \end{Quotation} % % \newpage % % \section{Name Authority Basics} +% \label{sec:NameAuthority} % % \subsection{Variant Names} % \label{sec:VarNames} % % This section explains how to manage simpler surname variants. There are several ways that \textsf{nameauth} can handle variants, in increasing levels of complexity. +% \begin{itemize}[leftmargin=2cm] +% \item[Group 1:] Use \meta{Alternate} to create variant forms, yet retain consistent index entries. This is the default function of \textsf{nameauth} seen already. % -% \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} +% \item[Group 2:] Use methods from Sections~\ref{sec:IndexPageno} and~\ref{sec:IndexRef}, and the manual approaches in Section~\ref{sec:Romani}. +% \begin{itemize} +% \item Use a particular name as a ``standard'' variant, then use other variants with a \textit{see} reference. % -% 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: +% \item Use one or more names as ``standard'' variants that refer to each other via \textit{see also} references. +% \end{itemize} +% +% \item[Group 3:] Use alternate formatting and macros in name arguments (Sections~\ref{sec:AltFormat} and~\ref{sec:Romani}). +% \end{itemize} % % \NameArgWarning % -% \subsubsection[Alternate Argument]{Variants and the Alternate Argument} +% \subsubsection[Alternate Argument]{Variants and the \protect\meta{Alternate} Argument} % % 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 an alternate name in the \texttt{nameauth} environment: -% -% \begin{quote} -% \vspace{4ex} -% \PatInfo{\ShowPattern[Mike]{Tyson}!MN} -% \vspace{-4ex} +% \begin{Quote} +% \PatInfo[4ex]{\ShowPattern[Mike]{Tyson}!MN} % \begin{Verbatim} % \begin{nameauth} % \< Tyson & Mike & Tyson & > @@ -6668,15 +8223,14 @@ and version 1.3 or later is part of all distributions of LaTeX version % % \IndexRef{Iron Mike}{Tyson, Mike} % \end{Verbatim} -% \end{quote} +% \end{Quote} % % Because \cmd{\Iron} uses the \meta{Alternate} column, all index page entries are the same as those for \cmd{\Tyson}, the canonical name. Adding the cross-reference via \cmd{\IndexRef} produces ``Iron Mike \textit{see} Tyson, Mike'' in the index. -% -% \begin{quote} -% \begin{tabular}{rlrl}\toprule +% \begin{Quote} +% \begin{tabular}{llll}\toprule % \rowcolor{nagrey}^^A -% \bfseries Output & \bfseries Macro & -% \bfseries Output & \bfseries Macro\\ +% \bfseries Text & \bfseries Macro & +% \bfseries Text & \bfseries Macro\\ % % \LIron \qquad & \cmd{\LIron} & % \LTyson[Iron Mike] & \cmd{\LTyson[Iron Mike]}\\ @@ -6686,16 +8240,15 @@ and version 1.3 or later is part of all distributions of LaTeX version % % \SIron & \cmd{\SIron} & \STyson & \cmd{\STyson}\\\bottomrule % \end{tabular} -% \end{quote} +% \end{Quote} % -% 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}). +% 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}). That probably is undesired. % -% 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: +% \newpage % -% \begin{quote} -% \vspace{4ex} -% \PatInfo{\ShowPattern{Elizabeth, I}!MN} -% \vspace{-4ex} +% We will engage with different kinds of variant names more, beginning with Section~\ref{sec:NameAncient}, Here we give a basic illustration of how one can start to manage these names just by using \meta{Alternate}. For instance: +% \begin{Quote} +% \PatInfo[4ex]{\ShowPattern{Elizabeth, I}!MN} % \begin{Verbatim} % \begin{nameauth} % \< Eliz & & Elizabeth, I & > @@ -6710,33 +8263,21 @@ and version 1.3 or later is part of all distributions of LaTeX version % % \LEliz[I, ``Gloriana''] was known also as % \ForceFN\SEliz[``Good Queen Bess'']. -% \end{quote} +% \end{Quote} % % \subsubsection[Multiple Variants]{Managing Multiple Variant Names} % -% With the second class of name variants listed above, we get into pseudonyms, aliases, and variant family names. This class is more complicated: +% With the second group of name variants listed above (relating to Sections~\ref{sec:IndexPageno} and~\ref{sec:IndexRef}), we get into pseudonyms, aliases, and variant family names. This class is more complicated for the following reasons: +% \begin{itemize} +% \item Names having separate index entries are linked together with cross-references; most of the work that interrelates these names is done with the indexing macros. % -% \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} +% \item Names that the author wants to treat as different may be seen by the \textsf{nameauth} internals as identical (Section~\ref{sec:Unique}). One can use nonprinting macros or grouping tokens in name arguments, index tagging macros, and formatting macros to create unique names (see below and Section~\ref{sec:IndexTag}). +% \end{itemize} % -% 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: +% We approach and cross the boundary between the second and third groups of names mentioned above when we deal with names that contain particles, that change capitalization, that have changing grammatical endings (Sections~\ref{sec:NameParticles}, \ref{sec:NameMedieval}, \ref{sec:NameAncient}, \ref{sec:Romani}, and~\ref{sec:RealAltEx}f.). % -% \begin{quote} +% 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} % \begin{Verbatim} % \begin{nameauth} % \< DuBois & W.E.B. & Du~Bois & > @@ -6744,226 +8285,150 @@ and version 1.3 or later is part of all distributions of LaTeX version % \end{nameauth} % \PretagName[W.E.B.]{Du~Bois}{DuBois, William} % \end{Verbatim} -% \end{quote} -% +% \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 -% some name authorities, we decide that the the canonical -% name will be: \ForgetThis\DuBois\ \cmd{\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: +% \item \PatInfo*{\ShowPattern[W.E.B.]{Du~Bois}!MN\break +% \ShowPattern[W.E.B.]{DuBois}!MN}^^A +% Based on historical research and some name authorities, we decide that the the canonical name will be: \ForgetThis\DuBois\ \cmd{\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 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.}\\[1ex] % | \IndexRef[W.E.B.]{DuBois}{Du Bois, W.E.B.}| % -% \item With the following setup we keep full stop detection, modify name -% forms, and check if the name straddles a page break in order to append -% |\JustIndex\DuBois| if needed: -% +% \item With the following setup we keep full stop detection and modify name forms. The only manual part would be to check if the name straddles a page break, then add |\JustIndex\DuBois| after the name if needed: +%^^A % \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.]. +% \VarDuBois[William E.B.]; +% \LVarDuBois; +% \SVarDuBois[William] % \end{VerbatimOut} -% -% \begin{quote} +%^^A +% \begin{Quote} % \VerbatimInput[gobble=0]{\jobname.tmp} % % \input{\jobname.tmp} -% \end{quote} -% -% \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. -% -% \begin{quote} -% \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} -% -% \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} -% -% \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.\negmedskip^^A -% \index{civil rights leaders, quotes of\noexpand\string|hyperpage} % \end{Quote} +% \end{itemize} % -% \newpage +% There are other solutions that one might envision, but they are a bit unwieldy. It does not seem practical to implement complex solutions for names unless perhaps one is using \LaTeX\ as a back-end for perhaps an XML workflow. % % \subsubsection[Nonstandard Caps]{Nonstandard Capitalization and Indexing} % \label{sec:NonstandardCaps} % -% 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: -% +% Here we look at simple nonstandard capitalization. Section~\ref{sec:AltFormat} dals with more complex examples. We consider poet \ForgetThis\Name[e.e.]{cummings}. Using the default \texttt{noformat} option, one can begin a sentence with something like: +% \BothInfo[-6ex]{\ShowPattern[e.e.]{cummings}!MN} +% {\ShowIdxPageref*[e.e.]{cummings}} +%^^A % \begin{VerbatimOut}{\jobname.tmp} % \SubvertThis\CapThis\Name[e.e.]{cummings}'s motif of the % goat-footed balloon man has underlying sexual themes that % nevertheless present a childish facade. % \end{VerbatimOut} -% -% \begin{quote} -% \vspace{4ex} -% \BothInfo{\ShowPattern[e.e.]{cummings}!MN} -% {\ShowIdxPageref*[e.e.]{cummings}} -% \vspace{-4ex} +%^^A +% \begin{Quote} % \VerbatimInput[gobble=0]{\jobname.tmp} % \renewcommand*\NamesFormat{} % \renewcommand*\MainNameHook{} % % \input{\jobname.tmp} -% \end{quote} -% -% 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}: +% \end{Quote} % +% If we want formatting and capitalization, we can do it this way: % \begin{VerbatimOut}{\jobname.tmp} % \ExcludeName[e.e.]{cummings's} -% We consider the work of \ForgetThis\Name[e.e.]{cummings}. -% \SubvertThis\CapThis\Name[e.e.]{cummings's} +% \JustIndex\Name[e.e.]{cummings} +% \ForceName\SubvertThis\CapThis\Name[e.e.]{cummings's} % motif of the goat-footed balloon man has underlying % sexual themes that nevertheless present a childish facade. % \end{VerbatimOut} -% -% \begin{quote} -% \vspace{4.5ex} -% \PatInfo{\ShowPattern[e.e.]{cummings's}} -% \vspace{-4.5ex} +%^^A +% \begin{Quote} % \VerbatimInput[gobble=0]{\jobname.tmp} +% \PatInfo{\ShowPattern[e.e.]{cummings's}!PN\break +% \ShowPattern[e.e.]{cummings's}!MN} % % \input{\jobname.tmp} -% \end{quote} -% -% 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. +% \end{Quote} % -% 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. +% In both examples above, we 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 \emph{all name elements.} Using \cmd{\ExcludeName} keeps one from having to use \cmd{\SkipIndex} every time. % % \subsubsection[Variants and Xrefs]{Variant Names and Index Cross-References} % \label{sec: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: +% \subsubsection*{\hfil Single Connections} +% +% Here we show differences among variants and cross-references. We can index variants under the canonical name or we can set up cross-references to variants. The order in which we do that is significant. +% \begin{Quote} +% \begin{Verbatim} +% \begin{nameauth} +% \< Carter & J.E. & Carter, Jr. & > +% \end{nameauth} +% \end{Verbatim} +% \end{Quote} % % \begin{enumerate} -% \vspace{5ex} -% \PatInfo{\ShowPattern[J.E.]{Carter, Jr.}!MN\hfill +% \item We use the canonical name to create page entries: +% \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)}} -% \vspace{-5ex} -% \item We use the canonical name to create page entries: -% \item[] \Name*[J.E.]{Carter, Jr.}\dotfill |\Name*[J.E.]{Carter, Jr.}| +% \item[] \LCarter[James Earl]\dotfill |\LCarter[James Earl]| % -% \item Variants that use \meta{Alternate} in the text create page -% entries under the canonical form, not the variant form: -% \item[] \DropAffix\Name*[J.E.]{Carter, Jr.}[Jimmy]\dotfill^^A -% |\DropAffix\Name*[J.E.]{Carter, Jr.}[Jimmy]| +% \item Variants that only use \meta{Alternate} in the text create page entries under the canonical form, not under the variant form: +% \item[] \DropAffix\LCarter[Jimmy]\dotfill^^A +% |\DropAffix\LCarter[Jimmy]| % \item[] |\ShowIdxPageref*[J.E.]{Carter, Jr.}[Jimmy]|\dotfill^^A % \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: +% \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 the xref will be ignored and a warning will result: % \item[] |\IndexRef[Jimmy]{Carter}{Carter, J.E., Jr.}|^^A % \IndexRef[Jimmy]{Carter}{Carter, J.E., Jr.} % -% \newpage -% -% \item No page entries will occur below because we made the -% \textit{see} reference first. Note how the alternate form is an -% independent name: -% \item[] \Name[Jimmy]{Carter}\dotfill |\Name[Jimmy]{Carter}| +% \item No page entries will occur below because we made the \textit{see} reference first. Note how the alternate form is an independent name: +% \item[] \Name[Jimmy]{Carter}\dotfill |\Name[Jimmy]{Carter}|\JustIndex\Carter % -% \item If we want to index the alternate name, we have to use the -% canonical name instead of the alternate name: -% \item[] |\IndexName[J.E.]{Carter, Jr.}| +% \item We must index the alternate name with one of the following: +% \item[] |\IndexName[J.E.]{Carter, Jr.}| +% \item[] |\JustIndex\Carter| % -% \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.: +% \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 at the end of the document, \emph{after} all uses of the alternate name: % \item[] |\SeeAlso\IndexRef[Jimmy]{Carter}{Carter, J.E., Jr.}| % \end{enumerate} % % \subsubsection*{\hfil Multiple Connections} % % Below, 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} -% \vspace{5ex} +% \item We use the canonical name to set up page entries: % \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)}} -% \vspace{-5ex} -% \item We use the canonical name to set up page entries: % \item[] \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: +% \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: % \item[] |\IndexRef{Moses, ben-Maimon}{Maimonides}|^^A % \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 entries will occur below because -% we made the xref first: +% \item We have a main name with a page entry and a ``\textit{see} reference'' to that name. No page entries will occur below because we made the xref first: % \item[] \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: +% \item Before creating \textit{see also} cross-references, we use the other alias so that all the page entries precede the cross-references: % \item[] \Name{Rambam}\dotfill |\Name{Rambam}| % -% \item All \textit{see also} references must come after all page entries. -% For example, one could put both of these macros at the end of the -% document: +% \item All \textit{see also} references must come after all page entries. For example, one could put both of these macros at the end of the document: % \item[] |\SeeAlso\IndexRef{Maimonides}{Rambam}|\\ % \SeeAlso\IndexRef{Maimonides}{Rambam}^^A % |\SeeAlso\IndexRef{Rambam}{Maimonides}|^^A @@ -6973,7 +8438,7 @@ and version 1.3 or later is part of all distributions of LaTeX version % \subsubsection*{\hfil Multiple Targets} % % There is a case where one cross-reference can point to multiple targets, such as demonstrated in the example below: -% +%^^A % \begin{VerbatimOut}{\jobname.tmp} % \PretagName{\textit{Snellius}}{Snellius} % \IndexRef{\textit{Snellius}} @@ -6982,53 +8447,49 @@ and version 1.3 or later is part of all distributions of LaTeX version % his son \Name[R.]{Snel van Royen}[Rudolph] were known % by the Latin moniker \Name{\textit{Snellius}}. % \end{VerbatimOut} -% -% \begin{quote} -% \vspace{5ex} -% \PatInfo{\ShowPattern{\textit{Snellius}}!PRE\break +%^^A +% \begin{Quote} +% \PatInfo[5ex]{\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} +% \end{Quote} % % 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. % % \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} had been typeset using \LaTeX, but then 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: -% +% Below are two names from a name authority that this author created for a translation of \Title{\la{De Diaconis et Diaconissis Veteris Ecclesiae Liber Commentarius}} by \Name[Caspar]{Ziegler}. To get valid names that one can research, here are some tips: % \begin{itemize} % \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://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}} +% {Older version of Graesse, \Title{\la{Orbis Latinus}}} % \end{itemize} +% \begin{enumerate} +% \item Vernacular names are canonical. Latin names refer to them. That holds also for place names. % -% 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: +% \item Sort vernacular names with \cmd{\PretagName} due to particles (Section~\ref{sec:IndexSort}). % -% \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 entries, 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*} +% \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}). % -% \begin{quote} -% \vspace{3.5ex} +% \item If Latin names have page entries, then place \cmd{\SeeAlso}\cmd{\IndexRef}\meta{name args} as needed at the end of the document, before \cmd{\printindex}. +% +% \item English usage requires \cmd{\CapThis} with particles in \meta{SNN} (Section~\ref{sec:NameParticles}). +% \end{enumerate} +% \begin{Quote} +% \vspace{3ex} % \BothInfo{\ShowPattern[Jacques]{De~Pamele}!MN\break % \ShowPattern[Jacobus]{Pamelius}!MN\break % \ShowPattern[Giovanni]{d'Andrea}!MN\break @@ -7049,102 +8510,115 @@ and version 1.3 or later is part of all distributions of LaTeX version % \IndexRef[Ioannes]{Andreae}{d'Andrea, Giovanni} % \Name[Ioannes]{Andreae} % \end{Verbatim} -% \end{quote} -% +% \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} +% \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}. % % \ReturnLink % +% \begin{Quotation}{\DuBois} +% {\Title{Darkwater: Voices from within the Veil} (1920)} +% In the awful cataclysm of World War, where from beating, slandering, +% and murdering us the white world turned temporarily aside to kill each +% other, we of the Darker Peoples looked on in mild amaze. +% +% \dots The fateful day came. It had to come. The cause of war is +% preparation for war; and of all that Europe has done in a century there +% is nothing that has equaled in energy, thought, and time her preparation +% for wholesale murder. The only adequate cause of this preparation was +% conquest and conquest, not in Europe, but primarily among the darker +% peoples of Asia and Africa; conquest, not for assimilation and uplift, +% but for commerce and degradation. For this, and this mainly, did Europe +% gird herself at frightful cost for war. +% \index{civil rights leaders, quotes of\noexpand\string|hyperpage} +% \end{Quotation} +% % \newpage % % \section{Advanced Formatting} % \label{sec:AdvancedFormat} % -% 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. -% -% 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. -% -% 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. +% Up to this point, formatting hooks have applied font and color changes to a parsed name, and perhaps printed a name tag. In this section we start to change the syntactic form of a name inside the formatting hooks. Below we see a general scheme of how the core name engine processes a name: % -% Before we delve into this section, below we see a general scheme of how the core name engine processes a name: +% \begin{tcolorbox}[colframe=violet!80!black,colback=white, +% adjusted title={\sffamily\bfseries Naming Macro Layer}] +% \small % -% \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) send arguments to three ``interface hooks'' that, by default, point to \cmd{\@nameauth@Name} (Section~\ref{sec:FullCustomize}). That macro is the backend for both the basic and quick interfaces.\medskip % -% 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 +% This backend handles work requested by \cmd{\JustIndex}, \cmd{\SubvertThis}, \cmd{\ForgetThis}, and \cmd{\SkipIndex}. Unless \cmd{\JustIndex} occurred, the backend then hands off the name arguments to the name parser, with either a main-matter \texttt{!MN} suffix or a front-matter \texttt{!NF} suffix. % -% \begin{tcolorbox}[colframe=naslate,colback=white, -% adjusted title={\bfseries Syntactic Element Layer}] +% \begin{tcolorbox}[colframe=blue!80!black,colback=white, +% adjusted title={\sffamily\bfseries Syntactic Element Layer}] % -% \cmd{\@nameauth@Parse}: Determine name category, capitalization, -% punctuation, elements to be used, and pass on to\dots +% The \cmd{\@nameauth@Parse} macro determines name category (Western or Non-Western), capitalization, punctuation, and name elements to be used. All needed macros are made available to the next layer. % -% \begin{tcolorbox}[colframe=nablue,colback=white, +% \begin{tcolorbox}[colframe=orange!80!black,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 +% The two main macros in this layer are \cmd{\@nameauth@NonWest} and \cmd{\@nameauth@West}. The macro \cmd{\@nameauth@Form} has rules that set Boolean flags to determine the name form to be displayed, which goes to the format hook dispatcher. % -% \begin{tcolorbox}[colframe=nared,colback=white, +% \begin{tcolorbox}[colframe=red!80!black,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. +% \cmd{\@nameauth@Hook}: Check the name to be printed for a final full stop. Check which name system we are using.\medskip % -% 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. +% Call the appropriate formatting hook, depending on whether or not the name pattern exists, and if we are in the main-matter system or the front-matter system. % % \end{tcolorbox} % % \end{tcolorbox} % -% \cmd{\@nameauth@Parse}: Make name control sequence from name pattern. +% \cmd{\@nameauth@Parse}: Create the name's pattern, a control sequence that makes the name ``exist'' for the sake of \textsf{nameauth}. % % \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. +% \cmd{\@nameauth@Name}: If the final full stop flag is true, check the lookahead token for a full stop and gobble it if needed. % % \end{tcolorbox} % +% \begin{Quotation}{\Name{Voltaire}} +% {\Title{Sept Discours en Vers sur l'Homme} (1738)} +% The secret to being a bore is to tell everything. +% \index{philosophers, quotes of\noexpand\string|hyperpage} +% \end{Quotation} +% % \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: +% \begin{InfoBox}[General Hook Redefinition] +% \VerbatimInput[gobble=0,numbers=none,fontsize=\small]{nullhook.tmp} +% \end{InfoBox} +% +% \input{nullhook.tmp} % +% \begingroup^^A Local format hook redefinition +% 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: +%^^A % \ifdefined\NameauthDoTestFiles \edef\NameauthTestFile{test11_01.tex}\else % \edef\NameauthTestFile{\jobname.tmp}\fi -% +%^^A % \begin{VerbatimOut}{\NameauthTestFile} % \documentclass{article} -% \input{compat.tex} % Included with nameauth; example file aids -% % compatibility across different LaTeX versions and engines. +% \input{compat.tex} % Included with nameauth for compatibility. % \usepackage{makeidx} % \usepackage{nameauth} % @@ -7160,13 +8634,15 @@ and version 1.3 or later is part of all distributions of LaTeX version % \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 +% \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} % +% \begin{quote} % The new format (front matter):\NamesInactive % % \Name{Vlad, III}[III Dracula], known as @@ -7199,13 +8675,18 @@ and version 1.3 or later is part of all distributions of LaTeX version % in the main matter we see: \NamesActive % \ForgetThis\Name{Vlad, III}[III Dracula], % \Name*{Vlad, III}, and \Name{Vlad, III}. +% \end{quote} % % \printindex % \end{document} % \end{VerbatimOut} +%^^A +% \begin{Quote} +% \VerbatimInput[gobble=0,lastline=38]{\NameauthTestFile} % -% \begin{quote} -% \VerbatimInput[gobble=0]{\NameauthTestFile} +% \newpage +% +% \VerbatimInput[gobble=0,firstline=39]{\NameauthTestFile} % % \let\OldFormat\NamesFormat % \let\OldFrontNames\FrontNamesFormat @@ -7247,308 +8728,28 @@ and version 1.3 or later is part of all distributions of LaTeX version % in the main matter we see: \NamesActive % \ForgetThis\Name{Vlad, III}[III Dracula], % \Name*{Vlad, III}, and \Name{Vlad, III}. -% \end{quote} -% -% 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{Name Tags in Hooks} -% \label{sec:DataTagHooks} -% -% By recalling name 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 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} -% -% \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 tags via \cmd{\NameQueryInfo}. That use has been superseded by \cmd{\NameauthPattern}, which is described in Section~\ref{sec:NamePatterns}. -% -% \newpage -% -% \subsubsection{Hook Templates} -% \label{sec:DataTemp} -% -% \begingroup ^^A Local formatting hook change -% -% \subsubsection*{\hfil Recommended Template} -% -% The hook below prints the name 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 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% -% \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} -% \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 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}]^^A -% }^^A -% }^^A -% \temp^^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} -% -% \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} -% -% \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 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 +% \end{Quote} % -% The first use of a name, or one after the use of \cmd{\ForgetName} or \cmd{\ForgetThis}, shows the most information. A long instance of an extant name shows a little less info, and a short instance shows the least. Every difference in name form corresponds with a macro in a known state. +% We redefine \cmd{\NamesFormat} and \cmd{\FrontNamesFormat} because it is more common to add extra information with the first mention of a name. % \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. We can use name tags for such dates, which can work with all name types. When used with Roman names (Section~\ref{sec:Romani}), if using name tags for dates, one would put \LA{agnomina} in \meta{Affix}. % -% 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 tags, we can do something similar here. -% -% First we must create any name 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. +% First we must create any name 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 used below have a leading space because they are printed conditionally in formatting hooks. % -% 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. +% We also define a cross-reference ``Atat\"urk''. After doing so, we use naming macros with that name, printing formatted names in the text but making no index page entries. That is a result of indexing rules in \textsf{nameauth}. % +% 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. We set aside the usual formatting of this manual. +%^^A % \ifdefined\NameauthDoTestFiles \edef\NameauthTestFile{test11_02.tex}\else % \edef\NameauthTestFile{\jobname.tmp}\fi -% +%^^A % \begin{VerbatimOut}{\NameauthTestFile} % \documentclass{article} -% \input{compat.tex} % Included with nameauth; example file aids -% % compatibility across different LaTeX versions and engines. +% \input{compat.tex} % Included with nameauth for compatibility. % \usepackage{makeidx} % \usepackage{nameauth} % @@ -7573,29 +8774,29 @@ and version 1.3 or later is part of all distributions of LaTeX version % % \renewcommand*\NamesFormat[1] % {% -% #1% -% \ifcsname\NameauthPattern!DB\endcsname -% \unless\ifNoTag -% \expandafter\csname\NameauthPattern!DB\endcsname% -% \fi -% \global\NoTagfalse% -% \fi +% #1\unless\ifNoTag\NameQueryInfo{}\fi +% \global\NoTagfalse% % } % % \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, +% \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 instance 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}. +% \NoTagtrue\ForgetThis\Name[George]{Washington}. % -% We can add name info tags to names used only as cross- +% 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} +% 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 name tag tag: % \NoTagtrue\ForgetThis\Name{Atat\"urk}. @@ -7603,174 +8804,213 @@ and version 1.3 or later is part of all distributions of LaTeX version % \printindex % \end{document} % \end{VerbatimOut} -% +%^^A % \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 +% #1\unless\ifNoTag\NameQueryInfo{}\fi +% \global\NoTagfalse^^A % } -% \renewcommand*\MainNameHook{} +%^^A +% \begin{Quote} +% \VerbatimInput[gobble=0,lastline=5]{\NameauthTestFile} % -% \begin{quote} -% \VerbatimInput[gobble=0,lastline=34]{\NameauthTestFile} -% \end{quote} +% \VerbatimInput[gobble=0,firstline=6,lastline=32]{\NameauthTestFile} +% \end{Quote} % -% 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. +% Up to now there has been a lot of setup. The payoff, however, comes in the main body text where the naming macros do not need manual additions: +% \begin{Quote} +% \VerbatimInput[gobble=0,firstline=33,lastline=44]{\NameauthTestFile} % -% \begin{quote} -% \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. % -% \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, +% If we need to trigger the first use hook at some point, % we can suppress dates and get an automatic long instance 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} +% \NoTagtrue\ForgetThis\Name[George]{Washington}. % -% 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 entries in the index: +% Or we can trigger the first-use hook in a subsequent name use +% and still have dates: \ForceName\Name[George]{Washington}. +% \end{Quote} % -% \begin{quote} -% \VerbatimInput[gobble=0,firstline=46]{\NameauthTestFile} +% Since we already have 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 entries in the index: +% \begin{Quote} +% \VerbatimInput[gobble=0,firstline=45]{\NameauthTestFile} % -% We can add name info tags to names used only as cross- +% We can add name info tags to names used only as cross-^^A % references. For example, \Name[Mustafa]{Kemal} was granted -% the name \Name{Atat\"urk}. We mention \Name[Mustafa]{Kemal} +% 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 name tag tag: +% first use, but with no name tag: % \NoTagtrue\ForgetThis\Name{Atat\"urk}. -% \end{quote} -% +% \end{Quote} % \endgroup^^A Local format hook redefinition % % \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. +% Alternate formatting is a framework that isolates local name changes in the text, especially to \meta{SNN}, from the name forms used globally in index entries. This allows some European or ``Continental'' academic formatting. +% \begin{itemize} +% \item Sections~\ref{sec:AltPossible} amd~\ref{sec:AltEnv} show how to enable and disable alternate formatting in either an activated or deactivated state. +% +% \item Section~\ref{sec:AltCaps} shows how \cmd{\CapThis} works only through its helper macro, \cmd{\AltCaps}, when alternate formatting is enabled. +% +% \item Section~\ref{sec:AltFeatures} shows how some built-in formatting macros work in formatting hooks along with the helper macros \cmd{\AltOn} and \cmd{\AltOff}. +% \end{itemize} +% +% \begin{InfoBox} +% Alternate formatting requires \cmd{\noexpand} before macros in name arguments to isolate all local changes in the formatting hooks from the global context, thus protecting index entries.\smallskip +% +% Every user-defined state change in custom macros used for alternate formatting requires two Boolean flags: one for the global state, and one for the local state.\smallskip +% +% Names that depend on alternate formatting cannot be used without it. Otherwise, one will see incorrect name forms in the text and spurious entries in the index. +% \end{InfoBox} % % \subsubsection[Enabling/Disabling]{Enabling and Disabling} +% \label{sec:AltPossible} % -% The first thing we need to know is how to enable and disable alternate formatting: +% Alternate formatting involves two separate things: capitalization and name formatting. Thus, we have two ``switches'' to manage it. The first is like the ignition switch of an automobile that either ``enables'' or ``disables'' the whole car. Alternate capitalization will work only while the auto is running. % -% \begin{center} +% The second switch is like the manual clutch pedal of an auto. When one depresses the clutch, the output of the motor does not transfer to the wheels. It is ``deactivated''; the alternate formatting macros do not format their arguments. +% +% If one lets out the clutch, the power will transfer to the wheels and the car will be ``activated'' and start moving. Such activation happens when the alternate formatting macros format their arguments. +% +% \begin{Center} % \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} -% +% \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. +% \item \emph{Enabled} means that the alternate formatting mechanism inhibits the normal behavior of \cmd{\CapThis} and permits both \cmd{\AltCaps} and the local changes in formatting hooks triggered by \cmd{\AltOn}. +% +% \item \emph{Disabled} means that \cmd{\CapThis} again works normally and alternate formatting macros (\cmd{\AltCaps}, \cmd{\AltOn}, and \cmd{\AltOff}) are inhibited. +% +% \item \emph{Activated} means that built-in alternate formatting macros like \cmd{\textSC} globally format their arguments, except when turned off in formatting hooks by \cmd{\AltOff}. +% +% \item \emph{Deactivated} means that built-in alternate formatting macros like \cmd{\textSC} globally do not format their arguments, except when turned on in formatting hooks by \cmd{\AltOn}. % \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*}. +% Both the \texttt{altformat} option and \cmd{\AltFormatActive} enable and globally activate alternate formatting. \cmd{\CapThis} works via \cmd{\AltCaps}. Built-in formatting macros will format their arguments. \cmd{\AltFormatActive} countermands \cmd{\AltFormatActive*}. % % \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}. -% -% \newpage +% The starred form \cmd{\AltFormatActive*} enables alternate formatting but leaves it in a globally deactivated state. It countermands both the \texttt{altformat} option and \cmd{\AltFormatActive}. It causes \cmd{\CapThis} to work via \cmd{\AltCaps}. Built-in formatting macros will not format their arguments. % % \DescribeMacro{\AltFormatInactive} -% This macro both disables and deactivates alternate formatting. This reverts globally to standard formatting and the normal function of \cmd{\CapThis}. -% -% Most \textsf{nameauth} 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.\medskip +% This macro both disables and deactivates alternate formatting. This reverts globally to standard formatting and the normal function of \cmd{\CapThis}. % % \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. +% These alternate formatting macros have global scope. % \end{InfoBox} -% \negmedskip % -% \subsubsection{Using \texttt{\textbackslash noexpand}} -% \label{sec:Noexpand} +% \subsubsection[Environment]{Formatting Environment} +% \label{sec:AltEnv} % -% 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. +% The sections in this manual can get complicated. Some quotations use alternate formatting. Some sections also use it, then switch back to regular formatting. % -% 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: +% Although many people will use either regular or alternate formatting, but not both, we have added environments to aid the use of text designed for alternate formatting into an arbitrary context, without worrying if the switching macros have set the proper state. +% \DescribeEnv{AltFormatZone} +% \texttt{AltFormatZone} works like \cmd{\AltFormatActive}, while \texttt{AltFormatZone*} works like \cmd{\AltFormatActive*}. +% \DescribeEnv{AltFormatZone*} +% When they exit, they disable alternate formatting. Thus, they can serve as a wrapper. % -% \begin{quote} -% |\Name{\noexpand\MyMacro{|\meta{SNN}|},\noexpand\MyMacro{|\meta{Affix}|}}| -% \end{quote} +% \DescribeMacro{\FixateFormat} +% These format environments create a local scope. \cmd{\FixateFormat} works only within \texttt{AltFormatZone} and \texttt{AltFormatZone*} to prevent the format switches from making any changes. \cmd{\FixateFormat} makes the environments the sole controller of alternate formatting within their scope. Below we show the use of \texttt{AltFormatZone} and \cmd{\FixateFormat}. Hooks do no formatting; the alternate formatting macros do that instead (Section~\ref{sec:AltFeatures}). \cmd{\SkipIndex} prevents spurious index entries: +%^^A +% \begin{VerbatimOut}{\jobname.tmp} +% \FixateFormat Format cannot be fixated here. % -% 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.\medskip +% \AltFormatActive +% \qquad \Name*[Konrad]{\noexpand\textSC{Zuse}}; +% formatting is enabled and active. % -% \NameArgWarning +% \AltFormatActive* +% \qquad \SkipIndex \Name*[Konrad]{\noexpand\textSC{Zuse}}; +% formatting is enabled and inactive. +% \AltFormatInactive \hfill Formatting disabled. % -% 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{AltFormatZone} +% Zone is active; format is not fixated. +% +% \qquad \Name*[Konrad]{\noexpand\textSC{Zuse}}; +% formatting is enabled and active. % -% \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} +% \AltFormatActive* +% \qquad \SkipIndex \Name*[Konrad]{\noexpand\textSC{Zuse}}; +% formatting is enabled and inactive. +% \end{AltFormatZone} \hfill Formatting disabled. +% +% \begin{AltFormatZone} +% \FixateFormat Format is fixated as: enabled and active. +% +% \qquad \Name*[Konrad]{\noexpand\textSC{Zuse}}; +% formatting is enabled and active. +% +% \AltFormatActive* +% \qquad \SkipIndex \Name*[Konrad]{\noexpand\textSC{Zuse}}; +% formatting is still enabled and active. +% \end{AltFormatZone} \hfill Formatting disabled. +% \end{VerbatimOut} +%^^A +% \begin{Quote} +% \VerbatimInput[gobble=0]{\jobname.tmp} +% +% \input{\jobname.tmp} +% \end{Quote} +% \ForgetName[Konrad]{\noexpand\textSC{Zuse}} % % \subsubsection[Capitalization]{Alternate Capitalization} -% \AltFormatActive +% \label{sec:AltCaps} % -% Above we referred to potential problems using \cmd{\CapThis}. When alternate formatting is enabled, \cmd{\CapThis} changes its mechanism to avoid such problems. +% \Info[1.5ex]{\hrule\strut We begin a big region of alternate formatting\strut\hrule} +% \begin{AltFormatZone} +% \FixateFormat^^A +% Previously, we referred to potential problems using \cmd{\CapThis}. When alternate formatting is enabled, \cmd{\CapThis} changes its mechanism to avoid such problems. This aspect of alternate formatting does not engage the formatting hooks. % % \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: +% 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. \cmd{\AltCaps} does not partition its argument, which avoids any problems with \cmd{\CapThis}. We describe the syntax: % % \begin{SyntaxBox} -% \cmd{\noexpand}\cmd{\AltCaps}\marg{Arg} +% \cmd{\noexpand}\cmd{\AltCaps}\marg{Argument} % \end{SyntaxBox} % -% We offer a silly example below, taking advantage of the local scope of the \texttt{quote} environment to disable indexing temporarily: +% \begin{Quote} +% \begin{Verbatim} +% \begin{nameauth} +% \< Cath & Catherine \noexpand\AltCaps{d}e' +% & \noexpand\textSC{Medici} & > +% \end{nameauth} +% \PretagName[Catherine \noexpand\AltCaps{d}e'] +% {\noexpand\textSC{Medici}}{Medici, Catherine de} % -% \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} +% \ForgetThis\Cath\ was a powerful queen of France. +% \CapThis\LCath[\noexpand\AltCaps{d}e'] +% was blamed for the St.\ Bartholomew's Day massacre. +% \end{Verbatim} % -% \begin{quote} -% \VerbatimInput[gobble=0]{\jobname.tmp} +% \ForgetThis\Cath\ was a powerful queen of France. +% \CapThis\LCath[\noexpand\AltCaps{d}e'] +% was blamed for the St.\ Bartholomew's Day massacre. +% \end{Quote} % -% \input{\jobname.tmp}^^A -% \index{Shakespearian rose, references to\noexpand\string|hyperpage} -% \end{quote} +% One major difference between formatting regimes is that, with regular formatting, \cmd{\CapThis} will cause the core name engine to capitalize every name element because we do not know which one to display. With alternate formatting, \cmd{\AltCaps} only capitalizes its argument. That causes \cmd{\CapThis} to work in a more granular way. % -% \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 +% \subsubsection{Formatting Features} +% \label{sec:AltFeatures} % % \begingroup^^A Local format hook redefinition % -% \subsubsection{Formatting Features} -% \label{sec:AltFeatures} -% \AltFormatActive +% This part of alternate formatting works within the formatting hooks. First, we show the basic concept where macros do not change between the local scope of the hooks and the global scope of the index. After that, we show where the macros do change. % % \DescribeMacro{\textSC} % Using alternate formatting can be as easy as using any one of four predefined macros. @@ -7780,9 +9020,14 @@ and version 1.3 or later is part of all distributions of LaTeX version % 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. +% \cmd{\CapName}, \cmd{\RevComma}, and \cmd{\RevName} can modify names that use these hooks, but the results appear only in the text. +% +% There are subtle differences among these macros. \cmd{\textIT} and \cmd{\textBF} use font commands to make one font change. \cmd{\textUC} makes no font changes; it just calls \cmd{\MakeUppercase}. \cmd{\textSC}, however, makes two font changes. It first makes a roman font declaration, then calls \cmd{\textsc}. This mitigates font substitution warnings. % -% 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: +% \subsubsection*{\hfil No Local Changes} % +% Here we show what happens when these formatting macros are used with \cmd{\AltFormatActive}. One should use \cmd{\noexpand} before these macros to prevent spurious index entries. Assuming that we have sorted the following names with \cmd{\PretagName} (Section~\ref{sec:IndexSort}), we get the following with this manual's formatting: +%^^A % \begin{VerbatimOut}{\jobname.tmp} % \Name[Konrad]{\noexpand\textSC{Zuse}}; % \Name[Konrad]{\noexpand\textSC{Zuse}}\\ @@ -7793,32 +9038,29 @@ and version 1.3 or later is part of all distributions of LaTeX version % \Name{\noexpand\textUC{Kanade}, Takeo}; % \Name{\noexpand\textUC{Kanade}, Takeo} % \end{VerbatimOut} -% -% \begin{quote} +%^^A +% \begin{Quote} % \VerbatimInput[gobble=0]{\jobname.tmp} % % \input{\jobname.tmp} -% \end{quote} -% -% 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. +% \end{Quote} % -% 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. +% \subsubsection*{\hfil Local Changes} % -% 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. +% Now we permit the macros above to change their output within the formatting hooks. Using \cmd{\noexpand} is necessary to avoid unwanted index entries. % -% 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 seems wont to do. +% \DescribeMacro{\AltOff}Recalling our automobile analogy, \cmd{\AltOff} is like depressing the clutch, It prevents macros like \cmd{\textSC}, \cmd{\textBF}, \cmd{\textIT}, and \cmd{\textUC} from formatting their arguments, but only within a formatting hook. % -% 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: +% \DescribeMacro{\AltOn} Likewise, \cmd{\AltOn} is like letting out the clutch. It allows macros like \cmd{\textSC}, \cmd{\textBF}, \cmd{\textIT}, and \cmd{\textUC} to format their arguments, but only within a formatting hook. The index reflects only the global state. % +% If one uses the \texttt{altformat} option, \cmd{\AltFormatActive}, or \texttt{AltFormatZone}, the formatting ``power'' goes to the formatting macros by default in both the text and the index. If we want name forms to change in the text, we can add a formatting hook that uses \cmd{\AltOff} to suppress formatting in subsequent uses of a name (even when using \cmd{\FixateFormat}), without affecting the index: +%^^A % \ifdefined\NameauthDoTestFiles \edef\NameauthTestFile{test11_03.tex}\else % \edef\NameauthTestFile{\jobname.tmp}\fi -% +%^^A % \begin{VerbatimOut}{\NameauthTestFile} % \documentclass{article} -% \input{compat.tex} % Included with nameauth; example file aids -% % compatibility across different LaTeX versions and engines. +% \input{compat.tex} % Included with nameauth for compatibility. % \usepackage{makeidx} % \usepackage[altformat]{nameauth} % @@ -7829,11 +9071,11 @@ and version 1.3 or later is part of all distributions of LaTeX version % \PretagName[Charles]{\noexpand\textBF{Babbage}} % {Babbage, Charles} % \PretagName{\noexpand\textUC{Kanade}, Takeo}{Kanade Takeo} +% \renewcommand*\MainNameHook{\AltOff} % % \begin{document} % -% \renewcommand*\MainNameHook{\AltOff} -% +% \begin{quote} % \ForgetThis\Name[Konrad]{\noexpand\textSC{Zuse}}; % \Name[Konrad]{\noexpand\textSC{Zuse}}\\ % \ForgetThis\Name[Ada]{\noexpand\textIT{Lovelace}}; @@ -7842,13 +9084,16 @@ and version 1.3 or later is part of all distributions of LaTeX version % \Name[Charles]{\noexpand\textBF{Babbage}}\\ % \ForgetThis\Name{\noexpand\textUC{Kanade}, Takeo}; % \Name{\noexpand\textUC{Kanade}, Takeo} +% \end{quote} % % \printindex % \end{document} % \end{VerbatimOut} +%^^A +% \begin{Quote} +% \VerbatimInput[gobble=0, lastline=16]{\NameauthTestFile} % -% \begin{quote} -% \VerbatimInput[gobble=0]{\NameauthTestFile} +% \VerbatimInput[gobble=0, firstline=17]{\NameauthTestFile} % % \renewcommand*\NamesFormat{} % \renewcommand*\MainNameHook{\AltOff} @@ -7861,26 +9106,20 @@ and version 1.3 or later is part of all distributions of LaTeX version % \Name[Charles]{\noexpand\textBF{Babbage}}\\ % \ForgetThis\Name{\noexpand\textUC{Kanade}, Takeo}; % \Name{\noexpand\textUC{Kanade}, Takeo} -% \end{quote} -% -% \AltFormatInactive +% \end{Quote} % \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 -% +%^^A % \begin{VerbatimOut}{\NameauthTestFile} % \documentclass{article} -% \input{compat.tex} % Included with nameauth; example file aids -% % compatibility across different LaTeX versions and engines. +% \input{compat.tex} % Included with nameauth for compatibility. % \usepackage{makeidx} % \usepackage[altformat]{nameauth} % @@ -7895,7 +9134,7 @@ and version 1.3 or later is part of all distributions of LaTeX version % \PretagName[Catherine \noexpand\AltCaps{d}e'] % {\noexpand\textSC{Medici}}{Medici, Catherine de} % -% \renewcommand*\MainNameHook{\sffamily\AltOff} +% \renewcommand*\MainNameHook{\AltOff} % % \begin{document} % @@ -7913,11 +9152,13 @@ and version 1.3 or later is part of all distributions of LaTeX version % \printindex % \end{document} % \end{VerbatimOut} -% -% \renewcommand*\MainNameHook{\sffamily\AltOff} -% \begin{quote} +%^^A +% \renewcommand*\MainNameHook{\AltOff} +% \begin{Quote} % \VerbatimInput[gobble=0]{\NameauthTestFile} % +% \newpage +% % \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 @@ -7928,37 +9169,35 @@ and version 1.3 or later is part of all distributions of LaTeX version % \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} -% -% 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: +% \end{Quote} % +% Here we keep the particle with the forename, but display them as a long reference with the surname, showing a degree of flexibility (Section~\ref{sec:NameParticles}): % \begin{itemize} % \item \parbox{0.2\textwidth}{\LCath[\noexpand\AltCaps{d}e']} % |\LCath[\noexpand\AltCaps{d}e']| +% % \item \parbox{0.2\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. +% Next we design grammatical inflections for use with alternate formatting. Perhaps this could be useful also for paradigms in a grammar book. % % 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 -% +%^^A % \ifdefined\NameauthDoTestFiles \edef\NameauthTestFile{test11_05.tex}\else % \edef\NameauthTestFile{\jobname.tmp}\fi -% +%^^A % \begin{VerbatimOut}{\NameauthTestFile} % \documentclass{article} -% \input{compat.tex} % Included with nameauth; example file aids -% % compatibility across different LaTeX versions and engines. +% \input{compat.tex} % Included with nameauth for compatibility. % \usepackage{makeidx} % \usepackage[altformat]{nameauth} % @@ -7966,7 +9205,6 @@ and version 1.3 or later is part of all distributions of LaTeX version % % \newif\ifGenitive % \newif\ifDoGenitive -% % \newcommand*\GEN{\ifDoGenitive\textSC{'s}\fi} % % \begin{nameauth} @@ -7995,53 +9233,52 @@ and version 1.3 or later is part of all distributions of LaTeX version % \printindex % \end{document} % \end{VerbatimOut} +%^^A +% \begin{Quote} +% \VerbatimInput[gobble=0,lastline=28]{\NameauthTestFile} % -% \begin{quote} -% \VerbatimInput[gobble=0]{\NameauthTestFile} +% \newpage +% +% \VerbatimInput[gobble=0,firstline=29]{\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 +% Consider \ForgetThis\Genitivetrue\Jeff\ legacy as the author of the % colonies' \textit{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} +% \end{Quote} % \endgroup^^A Local format hook redefinition % % \subsubsection{Reference Work I} +% \label{sec:RefI} % \begingroup^^A Local format hook redefinition % -% 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: -% +% 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 Western name with an alias. Some tips include: % \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 Match index entry forms to article head-words. % -% \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 Cross-reference name variants to the head-word. +% +% \item The first instance of a name displays the active alternate formatting. % % \item Deactivate alternate formatting in subsequent name instances. % -% \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}). +% \item Since some \LaTeX\ fonts do not combine small caps and boldface, we use slanted text in \cmd{\RefArticle} below. % \end{itemize} -% +%^^A % \ifdefined\NameauthDoTestFiles \edef\NameauthTestFile{test11_06.tex}\else % \edef\NameauthTestFile{\jobname.tmp}\fi -% +%^^A % \begin{VerbatimOut}{\NameauthTestFile} % \documentclass{article} -% \input{compat.tex} % Included with nameauth; example file aids -% % compatibility across different LaTeX versions and engines. +% \input{compat.tex} % Included with nameauth for compatibility. % \usepackage{makeidx} % \usepackage[altformat]{nameauth} % @@ -8071,8 +9308,8 @@ and version 1.3 or later is part of all distributions of LaTeX version % % \newcommand{\RefArticle}[3] % {% -% \def\check{#2}% -% \ifx\check\empty +% \def\Check{#2}% +% \ifx\Check\empty % \noindent\ForgetThis\textsl{#1}\ #3 % \else % \noindent\ForgetThis\textsl{#1}\ #2\ #3 @@ -8106,9 +9343,11 @@ and version 1.3 or later is part of all distributions of LaTeX version % \printindex % \end{document} % \end{VerbatimOut} +%^^A +% \begin{Quote} +% \VerbatimInput[gobble=0,lastline=25]{\NameauthTestFile} % -% \begin{quote} -% \VerbatimInput[gobble=0]{\NameauthTestFile} +% \VerbatimInput[gobble=0, firstline=26]{\NameauthTestFile} % % \IndexRef[Heinrich Wilhelm]{\noexpand\textSC{R\"uhmann}} % {\noexpand\textSC{R\"uhmann}, Heinz} @@ -8118,8 +9357,8 @@ and version 1.3 or later is part of all distributions of LaTeX version % % \newcommand{\RefArticle}[3] % {^^A -% \def\check{#2}^^A -% \ifx\check\empty +% \def\Check{#2}^^A +% \ifx\Check\empty % \noindent\ForgetThis\textsl{#1}\ #3 % \else % \noindent\ForgetThis\textsl{#1}\ #2\ #3 @@ -8147,171 +9386,55 @@ and version 1.3 or later is part of all distributions of LaTeX version % {7 March 1902\,--\,3 October 1994) was a German actor % in over 100 films. % \Name[Heinz]{\noexpand\textSC{R\"uhmann}}\dots} -% \end{quote} -% -% \endgroup^^A Local format hook redefinition -% \AltFormatInactive -% -% \begin{Quote}{\Name[L.M.]{Montgomery}, -% \textit{Anne of Green Gables}, C 5 (1908)} -% 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.^^A -% \index{creatives, quotes of\noexpand\string|hyperpage}^^A -% \index{Shakespearian rose, references to\noexpand\string|hyperpage} % \end{Quote} +% \endgroup^^A Local format hook redefinition % -% \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} -% \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} -% \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} -% -% \item Treat as ancient names, especially those with no \textit{praenomen}: -% -% \begin{quote} -% \begin{Verbatim} -% \ForgetThis\Name{Pontius, Pilate}[Pilatus]\\ -% \Name*{Pontius, Pilate}\\ -% \ForceFN\FName{Pontius, Pilate} -% \end{Verbatim} -% \ForgetThis\Name{Pontius, Pilate}[Pilatus]^^A -% \PatInfo{\ShowPattern{Pontius, Pilate}[Pilatus]!MN}\\ -% \Name*{Pontius, Pilate}\\ -% \ForceFN\FName{Pontius, Pilate}\\[1ex] -% Index: \ShowIdxPageref*{Pontius, Pilate} -% \end{quote} -% \end{itemize} -% -% 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{Quote}{\ForgetThis\Name[Julius]{Caesar}, -% \textit{\la{De bello gallico}} 3.16.6 (58–49 \textsc{bc})} -% \la{Fere libenter homines, id quod volunt, credunt.} -% -% (In general, people willingly believe what they want [to believe].)^^A -% \index{Romans, quotes of\noexpand\string|hyperpage} -% \end{Quote} +% We will revisit the topic of a reference work in Section~\ref{sec:RefII}, where we integrate custom formatting hooks into the concept. This puts the work into setup and automation instead of using macros with several arguments. % -% \newpage +% \subsection{Roman Names II} +% \label{sec:Romanii} % -% \subsubsection[Student Reference]{Student-Oriented Reference Works} -% \AltFormatActive +% \subsubsection[General Reference]{General Reference Works} +% \label{sec:RomanStudent} % % \begingroup^^A Local format hook redefinition % \renewcommand*\NamesFormat{} % \renewcommand*\MainNameHook{} % -% 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: +% In this subsection and the next, we do not use the formatting conventions of this manual and we activate alternate formatting. We focus here on reference works that treat the \LA{cognomen} as a Western surname and index according to it.\footnote{See Geiss, \Title{\de{Geschichte Griffbereit}}; Kinder and Hilgemann, \Title{\de{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}.} % -% \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. \href{https://en.wikipedia.org/wiki/Patrician_(ancient_Rome)}{This page} offers a good overview. -% The exact roles of names changed over time. \href{https://en.wikipedia.org/wiki/Roman_naming_conventions}{Another page} gives an overview of 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} +% This approach corresponds roughly with the manual approach that we saw in Section~\ref{sec:RomanGeneral}, except that we will not use \meta{Affix} to drop \LA{agnomina} and we will not use \meta{Alternate} to display variants of the \la{praenomen} and \LA{nomen}. Instead, we use macros that take advantage of alternate formatting to handle name form changes. +% \begin{Quote} % Index: \ShowIdxPageref*[\meta{praenomen} \meta{nomen}] % {\meta{cognomen} \meta{agnomen}}\\[1ex] -% Macro: |\Name[|\meta{praenomen}| |\meta{nomen}|]{|\meta{cognomen}|,| +% Macro: |\Name[|\meta{praenomen}| |\meta{nomen}|]{|\meta{cognomen} % \meta{agnomen}|}| -% \end{quote} -% -% 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: +% \end{Quote} % +% This method increases the number of macros by \emph{two per name,} one for each individual \meta{FNN} and \meta{SNN}. That might be a deal-breaker for some. The general logic used by the respective macros used in each name component follows the plan below, with the \textsf{nameauth} logic for Western names doing the rest: % \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} +% \item Display either \LA{praenomen}, \LA{nomen}, or both in \meta{FNN}. +% \item Display either \LA{cognomen}, \LA{agnomen}, or both in \meta{SNN}. % \end{itemize} % -% We accomplish this by using macros in the name arguments: -% +% We use alternate formatting and \cmd{\noexpand} in the macro arguments to ensure that index entries remain consistent. We define macros in both \meta{FNN} and \meta{SNN} that expand conditionally. We use the quick interface to define name shorthands, and we use \cmd{\PretagName} and \cmd{\TagName} as needed (cf. Section~\ref{sec:NameAncient}. In the preamble we define all macros and conditionals used in naming macro arguments to avoid errors. We use \texttt{\textbackslash ifNoGens} for the \LA{nomen} because \texttt{\textbackslash ifNoNomen} invites haplography. +% \NameArgWarning % \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 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 \emph{global} state and the name form in the index. The other reflects the \emph{local} state of the formatting hooks. % -% \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. +% \item Since we have four name \emph{components}, we need at most eight Boolean flags, two per \emph{potential change}. The logic shows longer forms when the flags are false, shorter forms when the flags are true. % \end{itemize} % -% \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. +% \newpage % % \ifdefined\NameauthDoTestFiles \edef\NameauthTestFile{test11_07.tex}\else % \edef\NameauthTestFile{\jobname.tmp}\fi -% +%^^A % \begin{VerbatimOut}{\NameauthTestFile} % \documentclass{article} -% \input{compat.tex} % Included with nameauth; example file aids -% % compatibility across different LaTeX versions and engines. +% \input{compat.tex} % Included with nameauth for compatibility. % \usepackage{makeidx} % \usepackage[altformat]{nameauth} % @@ -8329,9 +9452,7 @@ and version 1.3 or later is part of all distributions of LaTeX version % \newif\ifXGens % \newif\ifXAgno % -% % Name variant macros need to be defined uniquely for each -% % name. First is Scipio. Second is Gracchus. -% +% % Name variant macros are defined uniquely for each name. % \newcommand*\SCIPi % {% % \ifXGens Publius\else @@ -8342,11 +9463,7 @@ and version 1.3 or later is part of all distributions of LaTeX version % } % % \newcommand*\SCIPii -% {% -% \ifXAgno Scipio\else -% Scipio Africanus% -% \fi -% } +% {\ifXAgno Scipio\else Scipio Africanus\fi} % % \newcommand*\TSemp % {% @@ -8357,16 +9474,13 @@ and version 1.3 or later is part of all distributions of LaTeX version % \fi % } % -% % Quick interface definitions. The first shows -% % the concept of Roman names without extra features. -% % The second (Gracchus) adds name info tags. -% +% % Quick interface definitions. % \begin{nameauth} % \< Scipio & \noexpand\SCIPi & \noexpand\SCIPii & > % \< TGrac & \noexpand\TSemp & Gracchus & > % \end{nameauth} % -% % We add the name tag. +% % We add a name tag. % \NameAddInfo[\noexpand\TSemp]{Gracchus} % { (consul, 177 \textsc{bc})} % @@ -8377,21 +9491,14 @@ and version 1.3 or later is part of all distributions of LaTeX version % {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. -% +% % We define formatting hooks. % \renewcommand*\NamesFormat[1] % {% % \ifNoPraenomen\XPraetrue\fi% % \ifNoGens\XGenstrue\fi% % \ifNoCognomen\XCogntrue\fi% % \ifNoAgnomen\XAgnotrue\fi% -% #1% +% #1\NameQueryInfo{}% % \global\NoPraenomenfalse% % \global\NoGensfalse% % \global\NoCognomenfalse% @@ -8411,6 +9518,8 @@ and version 1.3 or later is part of all distributions of LaTeX version % \global\NoAgnomenfalse% % } % +% \begin{document} +% % \NoAgnomentrue\Scipio\ was born around 236 \textsc{bc} % into the Scipiones branch of the Cornelii clan. % \NoAgnomentrue\Scipio\ rose to military fame during the @@ -8421,26 +9530,6 @@ and version 1.3 or later is part of all distributions of LaTeX version % 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 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, @@ -8450,26 +9539,38 @@ and version 1.3 or later is part of all distributions of LaTeX version % \printindex % \end{document} % \end{VerbatimOut} +%^^A +% \begin{Quote} +% \VerbatimInput[gobble=0, lastline=19]{\NameauthTestFile} +% \end{Quote} % -% \begin{quote} -% \VerbatimInput[gobble=0, lastline=74]{\NameauthTestFile} -% \end{quote} +% \JustIndex\CatoYi +% For every name, one must define two macros. True, there can be multiple names that are alike and use the same macros, as with many a \CatoY, but then one must use \cmd{\TagName} and non-printing macros in name arguments to create unique names and index entries (Section~\ref{sec:Unique}). The Romans had a small set of acceptable names and often named fathers and sons alike. +% \begin{Quote} +% \VerbatimInput[gobble=0, firstline=20, lastline=47]{\NameauthTestFile} +% \end{Quote} % -% 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. +% \newpage +% +% If one uses \cmd{\NameQueryInfo\{\}} within formatting hooks, it is best to put a space at the beginning of a tag if space is needed, instead of in the hook. +% \begin{Quote} +% \VerbatimInput[gobble=0, firstline=48, lastline=58]{\NameauthTestFile} +% \end{Quote} % +% We reset the global Boolean flags to ensure the longest name forms in the index. Local Boolean flags revert to false outside the scope of the formatting hooks. +%^^A % \renewcommand*\NamesFormat[1] % {^^A % \ifNoPraenomen\XPraetrue\fi^^A % \ifNoGens\XGenstrue\fi^^A % \ifNoCognomen\XCogntrue\fi^^A % \ifNoAgnomen\XAgnotrue\fi^^A -% #1^^A +% #1\NameQueryInfo{}^^A % \global\NoPraenomenfalse^^A % \global\NoGensfalse^^A % \global\NoCognomenfalse^^A % \global\NoAgnomenfalse^^A % } -% % \renewcommand*\MainNameHook[1] % {^^A % \ifNoPraenomen\XPraetrue\fi^^A @@ -8482,14 +9583,12 @@ and version 1.3 or later is part of all distributions of LaTeX version % \global\NoCognomenfalse^^A % \global\NoAgnomenfalse^^A % } -% \begin{quote} -% \VerbatimInput[gobble=0, firstline=75, lastline=87]{\NameauthTestFile} +% \begin{Quote} +% \VerbatimInput[gobble=0, firstline=59, lastline=97]{\NameauthTestFile} % % \newpage % -% \VerbatimInput[gobble=0, firstline=88, lastline=110]{\NameauthTestFile} -% -% \NoAgnomentrue\Scipio\ was born around 236 \textsc{bc} +% \ForgetThis\NoAgnomentrue\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. @@ -8498,115 +9597,84 @@ and version 1.3 or later is part of all distributions of LaTeX version % \Name{Ptolemy, V}[V Epiphanes], and the Syrian % reigns of \Name{Seleucus, III}[III Ceraunus] and % \Name{Antiochus, III}[III the Great]. -% \end{quote} +% \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: +% Below we show more name variations than were shown above: % % \begin{Block} % \ForgetThis\Scipio \dotfill |\ForgetThis\Scipio|\\ % \LScipio \dotfill |\LScipio|\\ % \Scipio \dotfill |\Scipio|\\ -% \SScipio \dotfill |\SScipio|\\[2ex] +% \SScipio \dotfill |\SScipio|\\ % \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}| +% \NoPraenomentrue\SScipio \dotfill |\NoPraenomentrue\SScipio| % \end{Block} % -% In Section~\ref{sec:NameAncient}, we used name tags instead of \meta{Alternate} in the first-use formatting hook. Here we show the changes needed to add name 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. -% +% In Section~\ref{sec:NameAncient}, we used name tags instead of \meta{Alternate} in the first-use formatting hook. Here we adopt a similar approach. Since formatting hooks are local by design, whatever changes inside of them does not affect the index. +% \begin{Quote} +% \VerbatimInput[gobble=0,firstline=98]{\NameauthTestFile} % \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} -% \VerbatimInput[gobble=0,firstline=111]{\NameauthTestFile} % % \TGrac\ served as tribune of the plebs in 184 \textsc{bc}. % \TGrac\ 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} +% \end{Quote} +% +% Again we see more name variations: +% +% \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| +% \end{Block} % -% Below we show both a Roman name and a different name type working the same way with the formatting hook: +% Next we see other types of names using these same formatting hooks: % % \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] +% \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}|\\ % \ForgetThis\Dem \dotfill |\ForgetThis\Dem|\\ % \LDem \dotfill |\LDem|\\ % \Dem \dotfill |\Dem| % \end{Block} % -% \begingroup -% \renewcommand*\NamesFormat[1]{\color{blue}\sffamily #1} -% \renewcommand*\MainNameHook[1]{\sffamily #1} -% \begin{Quote}{\ForgetThis\Scipio\break -% \hbox{}\hfill attributed by \Name[Titus]{Livius} in -% \textit{\la{Ab urbe condita}} B 30 (27–9 \textsc{bc})} -% \la{Bellum parate, quoniam pacem pati non potuistis.} -% -% (Prepare for war, for it seems that you are unable to tolerate peace.)\footnote{Here we enclosed this quote in a group and redefined the formatting hooks locally.}^^A -% \index{Romans, quotes of\noexpand\string|hyperpage} -% \end{Quote} -% \endgroup +% \subsubsection[Scholarly Works]{Scholarly Reference Works} +% \label{sec:RomanScholarii} % -% \newpage +% We retain most of the code from the previous section in the example below, but we change the macros used in the name arguments, following this logic: +% \begin{itemize} +% \item Display the \LA{praenomen} in \meta{FNN}: % -% \subsubsection[Scholarly Reference]{Scholarly Reference Works} +% \item Display one of the following in \meta{SNN}: +% \begin{itemize} +% \item Only the \LA{cognomen} % -% 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: +% \item Both the \LA{cognomen} and \LA{agnomina} % -% \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} +% \item Only the \LA{nomen} % -% 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: +% \item Both the \LA{nomen} and \LA{cognomen} % -% \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} +% \item The \LA{nomen}, \LA{cognomen}, and \LA{agnomina} % \end{itemize} % \end{itemize} -% +%^^A % \ifdefined\NameauthDoTestFiles \edef\NameauthTestFile{test11_08.tex}\else % \edef\NameauthTestFile{\jobname.tmp}\fi -% +%^^A % \begin{VerbatimOut}{\NameauthTestFile} % \documentclass{article} -% \input{compat.tex} % Included with nameauth; example file aids -% % compatibility across different LaTeX versions and engines. +% \input{compat.tex} % Included with nameauth for compatibility. % \usepackage{makeidx} % \usepackage[altformat]{nameauth} % @@ -8624,14 +9692,11 @@ and version 1.3 or later is part of all distributions of LaTeX version % \newif\ifXGens % \newif\ifXAgno % -% % Name variant macros need to be defined -% % uniquely for each name. -% +% % Name variant macros are defined uniquely for each name. % \newcommand*\CSB % {% % \ifXGens -% \ifXAgno Scipio\else -% Scipio Barbatus\fi +% \ifXAgno Scipio\else Scipio Barbatus\fi % \else % \ifXCogn Cornelius\else % \ifXAgno Cornelius Scipio\else @@ -8656,10 +9721,7 @@ and version 1.3 or later is part of all distributions of LaTeX version % \ifNoGens\XGenstrue\fi% % \ifNoCognomen\XCogntrue\fi% % \ifNoAgnomen\XAgnotrue\fi% -% #1% -% \ifcsname\NameauthPattern!DB\endcsname -% \expandafter\csname\NameauthPattern!DB\endcsname% -% \fi +% #1\NameQueryInfo{}% % \global\NoPraenomenfalse% % \global\NoGensfalse% % \global\NoCognomenfalse% @@ -8677,182 +9739,178 @@ and version 1.3 or later is part of all distributions of LaTeX version % \printindex % \end{document} % \end{VerbatimOut} +%^^A +% \begin{Quote} +% \VerbatimInput[gobble=0,lastline=38]{\NameauthTestFile} % -% \begin{quote} -% \VerbatimInput[gobble=0]{\NameauthTestFile} +% \newpage +% +% \VerbatimInput[gobble=0,firstline=39]{\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} +% \end{Quote} % -% 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: +% Instead of relying on some \textsf{nameauth} features that drop some name elements 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] +% \SOScipio \dotfill |\SOScipio|\\ % \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| +% \NoGenstrue\NoAgnomentrue\OScipio \dotfill^^A +% |\NoGenstrue\NoAgnomentrue\OScipio| % \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} -% \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 +% +% \begin{AltFormatZone} +% \renewcommand*\NamesFormat[1] +% {\color{blue}\sffamily^^A +% \ifGenitive\DoGenitivetrue\fi#1^^A +% \global\Genitivefalse} +% \renewcommand*\MainNameHook[1] +% {\sffamily^^A +% \ifGenitive\DoGenitivetrue\fi\AltOff#1^^A +% \global\Genitivefalse} +% \begin{Quotation}{\Jeff} +% {letter to \Name[John]{Wyche}, 1809} +% I have often thought that nothing would do more extensive good at small expense than the establishment of a small circulating library in every county, to consist of a few well-chosen books, to be lent to the people of the country under regulations as would secure their safe return in due time. +% \index{politicians, quotes of\noexpand\string|hyperpage} +% \end{Quotation} +% \end{AltFormatZone} % % \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. % % \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. +% The user-accessible parser (Section~\ref{sec:NameParser}) is distinct from the internal name parser. Yet it only can be called within the formatting hooks, the point where the internal parser generates output. Thus, the two parsers are linked. % +% Capitalization and \meta{Alternate} swapping happen early in the parsing process before we know what name elements to display. \cmd{\NameParser} only sees the name elements after these actions are done. It displays a printed name based on the elements it sees and a matrix of Boolean flags: % \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. -% -% These flags also persist after the macro that uses name arguments exits, unlike many other flags. This allows one to poll the last macro that took naming arguments, which may or may not be the last name printed in the text. -% -% To illustrate how one might poll these flags, either in a formatting hook or after a macro that takes name arguments exits, we set up the following macros and show how the flags are set. Notice that the name type is a function solely of the name arguments used, not how the name eventually ends up printed in the text, and not based on the name control sequence. -% -% \begin{VerbatimOut}{\jobname.tmp} -% \newcommand\ShowType -% {% -% \ifNameauthWestern Western name\else -% \ifNameauthObsolete nonwestern name using obsolete syntax\else -% nonwestern name using current syntax\fi -% \fi -% } -% -% First, we begin with a Western name: +% \item When |\if@nameauth@FullName| is true: +% \begin{itemize} +% \item Name forms are long. % -% \Name*[Albert]{Einstein} is a \ShowType. +% \item If true, |\if@nameauth@ShortSNN| causes the affix of a Western surname to not be displayed. % -% Even though this name is reversed in the text, it is still Western: +% \item If true, |\if@nameauth@RevThis| causes name order to be reversed, as applicable. % -% \RevName\Name*[Frenec]{Liszt}\dag\ is a \ShowType. +% \item If true, |\if@nameauth@RevThisComma| causes a Western name to be reversed, adding a comma between \meta{SNN} and \meta{FNN} only if |\if@nameauth@RevThis| is false. +% \end{itemize} % -% Here we present the same name twice, but using the two different -% syntax versions for nonwestern names: +% \item When |\if@nameauth@FullName| is false: +% \begin{itemize} +% \item Name forms are short. % -% \Name*{Henry, VIII} is a \ShowType. +% \item If true, |\if@nameauth@ForceAffix| causes only the suffix of a Western name to print. % -% \Name*{Henry}[VIII]\ddag\ is a \ShowType. +% \item If true, |\if@nameauth@FirstName| causes only a Western forename to print. % -% Finally, even though we do not print the name, -% \IndexName{Elizabeth, I} we get a \ShowType. -% \end{VerbatimOut} +% \item If true, |\if@nameauth@FirstName| causes an Eastern personal name or an ancient sobriquet to print, but only if |\if@nameauth@EastFN| is true. +% \end{itemize} +% \end{itemize} % -% \begin{quote} -% \VerbatimInput[gobble=0]{\jobname.tmp} -% -% \newcommand\ShowType -% {%^^A -% \ifNameauthWestern Western name\else -% \ifNameauthObsolete nonwestern name using obsolete syntax\else -% nonwestern name using current syntax\fi +% \Info*{\small\texttt{\textbackslash ifNameauthWestern}\\[0.4ex] \texttt{\textbackslash ifNameauthObsolete}}^^A +% We provide an example that uses \cmd{\NameParser}, |\ifNameauthWestern|, and |\ifNameauthObsolete| (Section~\ref{sec:NamePatterns}) to show and evaluate name parts: +%^^A +% \begin{VerbatimOut}{\jobname.tmp} +% \makeatletter +% \renewcommand\MainNameHook[1]{% +% \@nameauth@FullNamefalse% +% \@nameauth@FirstNamefalse% +% \@nameauth@ForceAffixfalse% +% \@nameauth@EastFNtrue% +% \ifNameauthWestern +% Western name:\\ +% \hbox to 3.5cm {Forename: \@nameauth@FirstNametrue% +% \NameParser\hfill} +% \hbox to 3.5cm {Surname: \@nameauth@FirstNamefalse% +% \NameParser\hfill} +% Affix: \@nameauth@ForceAffixtrue \NameParser\smallskip +% \else +% \hbox to 3.5cm{Non-Western name:\hfill} +% \ifNameauthObsolete +% (obsolete syntax)\\ \hbox to 3.5cm{\hfill} \fi +% \hbox to 3.5cm {Name: \@nameauth@FirstNamefalse% +% \NameParser\hfill} +% Person/Sobriquet: \@nameauth@FirstNametrue% +% \NameParser\smallskip % \fi % } +% \makeatother % -% First, we begin with a Western name: -% -% \Name*[Albert]{Einstein} is a \ShowType. -% -% Even though this name is reversed in the text, it is still Western: -% -% \RevName\Name*[Frenec]{Liszt}\dag\ is a \ShowType. -% -% Here we present the same name twice, but using the two different -% syntax versions for nonwestern names: +% \Name[Martin]{Van Buren}\\ +% \Name[George S.]{Patton, Jr.}[George]\\ +% \Name{Miyazaki, Hayao}\\ +% \Name{Henry}[VIII]\\ +% \Name{Confucius} +% \end{VerbatimOut} +%^^A +% \begin{Quote} +% \VerbatimInput[gobble=0, lastline=13]{\jobname.tmp} % -% \Name*{Henry, VIII} is a \ShowType. +% \newpage % -% \Name*{Henry}[VIII]\ddag\ is a \ShowType. +% \VerbatimInput[gobble=0, firstline=14]{\jobname.tmp} +% \makeatletter +% \renewcommand\MainNameHook[1]{^^A +% \@nameauth@FullNamefalse^^A +% \@nameauth@FirstNamefalse^^A +% \@nameauth@ForceAffixfalse^^A +% \@nameauth@EastFNtrue^^A +% \ifNameauthWestern +% Western name:\\ +% \hbox to 3.5cm {Forename: \@nameauth@FirstNametrue^^A +% \NameParser\hfill} +% \hbox to 3.5cm {Surname: \@nameauth@FirstNamefalse^^A +% \NameParser\hfill} +% Affix: \@nameauth@ForceAffixtrue \NameParser\smallskip +% \else +% \hbox to 3.5cm{Non-Western name:\hfill} +% \ifNameauthObsolete +% (obsolete syntax)\\ \hbox to 3.5cm{\hfill} \fi +% \hbox to 3.5cm {Name: \@nameauth@FirstNamefalse^^A +% \NameParser\hfill} +% Person/Sobriquet: \@nameauth@FirstNametrue^^A +% \NameParser\smallskip +% \fi +% } +% \makeatother % -% Finally, even though we do not print the name, -% \IndexName{Elizabeth, I} we get a \ShowType. -% \end{quote} +% \Name[Martin]{Van Buren}\\ +% \Name[George S.]{Patton, Jr.}[George]\\ +% \Name{Miyazaki, Hayao}\\ +% \Name{Henry}[VIII]\\ +% \Name{Confucius} +% \end{Quote} % % \subsubsection{Reference Work II} +% \label{sec:RefII} % -% Below we revisit the idea of a reference work, leveraging the formatting hooks to format headwords, add information from name info tags: -% -% 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} -% -% \newpage -% -% If we had used \cmd{\AltFormatActive*}, where the formatting macros are enabled, but \emph{deactivated} by default, then we might want instead a first-use hook that activates the macros: -% -% \begin{SyntaxBox} -% \cmd{\renewcommand*}\meta{FirstHook}\texttt{[1]\{\dots}\cmd{\AltOn}\cmd -% {\NameParser}\texttt{\dots\}} -% \end{SyntaxBox} -% +% Below we revisit the idea of a reference work, using the formatting hooks to automate tasks instead of populating the different arguments of \cmd{\RefArticle} in Section~\ref{sec:RefI}. We shift the work from proofreading to setup. % \ifdefined\NameauthDoTestFiles \edef\NameauthTestFile{test11_09.tex}\else % \edef\NameauthTestFile{\jobname.tmp}\fi -% +%^^A % \begin{VerbatimOut}{\NameauthTestFile} % \documentclass{article} -% \input{compat.tex} % Included with nameauth; example file aids -% % compatibility across different LaTeX versions and engines. +% \input{compat.tex} % Included with nameauth for compatibility. % \usepackage{makeidx} % \usepackage[altformat]{nameauth} % % \makeindex % % % Boolean flags; the first sets up headwords and the second -% % indicates that a nonwestern form should not be reversed. +% % indicates that a Non-Western form should not be reversed. % \newif\ifHeadword % \newif\ifAncientName % @@ -8877,22 +9935,16 @@ and version 1.3 or later is part of all distributions of LaTeX version % \ifNameauthWestern % \@nameauth@RevThisCommatrue% % \bfseries \NameParser% -% \normalfont% -% \ifcsname\NameauthPattern!DB\endcsname -% \expandafter\csname\NameauthPattern!DB\endcsname% -% \fi +% \normalfont\NameQueryInfo{}% % \else -% \bgroup% +% \begingroup% % \bfseries \NameParser% % \unless\ifAncientName % \normalfont; W:\AltOff\space % \@nameauth@RevThistrue \NameParser% % \fi -% \normalfont% -% \ifcsname\NameauthPattern!DB\endcsname -% \expandafter\csname\NameauthPattern!DB\endcsname% -% \fi -% \egroup% +% \normalfont\NameQueryInfo{}% +% \endgroup% % \fi % \else % \NameParser% @@ -8906,10 +9958,7 @@ and version 1.3 or later is part of all distributions of LaTeX version % % Define related macros: % \newcommand\Headword{\Headwordtrue\ForgetThis} % \newcommand{\RefArticle}[2] -% {% -% \noindent\Headword #1 #2% -% -% } +% {\noindent\Headword #1 #2\medskip} % % \begin{document} % @@ -8927,16 +9976,34 @@ and version 1.3 or later is part of all distributions of LaTeX version % \Name{\noexpand\textUC{Kanade}, Takeo}\dots} % % \RefArticle{\Name[Ada]{\noexpand\textIT{Lovelace}}}{collaborated with -% \Name*[Charles]{\noexpand\textBF{Babbage}}* and wrote what some +% \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} +%^^A +% \begin{Quote} +% \VerbatimInput[gobble=0, lastline=17]{\NameauthTestFile} % -% \begin{quote} -% \VerbatimInput[gobble=0]{\NameauthTestFile} +% \newpage +% +% \VerbatimInput[gobble=0, firstline=18, lastline=25]{\NameauthTestFile} +% \end{Quote} +% +% The formatting hook does all the heavy lifting. If the name appears in the headword part of \cmd{\RefArticle}, the hook reverses the name with commas only if it is a Western name. Otherwise, if it is a Non-Western name, but not ancient or royal, then both the Eastern name and its Western version are displayed. Only headwords are printed in boldface. After the first name occurrence, forced by the headword part of \cmd{\RefArticle}, the name tag also is printed. +% \begin{Quote} +% \VerbatimInput[gobble=0, firstline=26, lastline=53]{\NameauthTestFile} +% \end{Quote} +% +% In Section~\ref{sec:RefI} the \cmd{\RefArticle} macro took three arguments, one of which frequently was empty, and required information like dates to be put at the front of each entry. Now \cmd{\RefArticle} simply takes two arguments: a name and some information. The rest is automated. +% \begin{Quote} +% \VerbatimInput[gobble=0, firstline=54, lastline=58]{\NameauthTestFile} +% +% \newpage +% +% \VerbatimInput[gobble=0, firstline=59]{\NameauthTestFile} % % \NameAddInfo{Aristotle}{ (384--322 \textsc{bc})} % \NameAddInfo[Charles]{\noexpand\textBF{Babbage}}{ (1791--1871)} @@ -8952,22 +10019,16 @@ and version 1.3 or later is part of all distributions of LaTeX version % \ifNameauthWestern % \@nameauth@RevThisCommatrue^^A % \bfseries \NameParser^^A -% \normalfont^^A -% \ifcsname\NameauthPattern!DB\endcsname -% \expandafter\csname\NameauthPattern!DB\endcsname^^A -% \fi +% \normalfont\NameQueryInfo{}^^A % \else -% \bgroup^^A +% \begingroup^^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 +% \normalfont\NameQueryInfo{}^^A +% \endgroup^^A % \fi % \else % \NameParser^^A @@ -8980,9 +10041,7 @@ and version 1.3 or later is part of all distributions of LaTeX version % % \newcommand\Headword{\Headwordtrue\ForgetThis} % \newcommand{\RefArticle}[2] -% {^^A -% \noindent\Headword #1 #2^^A -% } +% {\noindent\Headword #1 #2\medskip} % % \RefArticle{\AncientNametrue\Name{Aristotle}}{was the first to offer % a system of logic, most notably syllogistic logic, that would @@ -8998,10 +10057,32 @@ and version 1.3 or later is part of all distributions of LaTeX version % \Name{\noexpand\textUC{Kanade}, Takeo}\dots} % % \RefArticle{\Name[Ada]{\noexpand\textIT{Lovelace}}}{collaborated with -% \Name*[Charles]{\noexpand\textBF{Babbage}}* and wrote what some +% \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} +% \end{Quote} +% +% \begin{AltFormatZone} +% \renewcommand*\NamesFormat{\color{blue}\sffamily} +% \renewcommand*\MainNameHook{\sffamily} +% \begin{Quotation}{\Shak} +% {``Romeo and Juliet'', Act II, Scene II (published 1597)} +% `Tis but thy name that is my enemy;\\ +% Thou art thyself, though not a Montague.\\ +% What’s Montague? It is nor hand, nor foot,\\ +% Nor arm, nor face. O, be some other name\\ +% Belonging to a man.\\ +% 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. +% \index{creatives, quotes of\noexpand\string|hyperpage} +% \index{Rose, references to\noexpand\string|hyperpage} +% \end{Quotation} +% \end{AltFormatZone} % % \newpage % @@ -9009,11 +10090,10 @@ and version 1.3 or later is part of all distributions of LaTeX version % % \ifdefined\NameauthDoTestFiles \edef\NameauthTestFile{test11_10.tex}\else % \edef\NameauthTestFile{\jobname.tmp}\fi -% +%^^A % \begin{VerbatimOut}{\NameauthTestFile} % \documentclass{article} -% \input{compat.tex} % Included with nameauth; example file aids -% % compatibility across different LaTeX versions and engines. +% \input{compat.tex} % Included with nameauth for compatibility. % \usepackage{makeidx} % \usepackage[altformat]{nameauth} % @@ -9024,17 +10104,11 @@ and version 1.3 or later is part of all distributions of LaTeX version % \newif\ifSpecialSN % \newif\ifRevertSN % -% % Name variant macros need to be defined -% % uniquely for each name. -% +% % Name variant macros must be defined 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 -% } +% \newcommand*\WM{\ifSpecialFN Wm.\else William\fi} % % % The first surname use will be ``Shakespeare'', but ``the % % Bard'' thereafter. We allow for alternate caps. @@ -9052,29 +10126,18 @@ and version 1.3 or later is part of all distributions of LaTeX version % } % % % 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] % {% @@ -9119,17 +10182,24 @@ and version 1.3 or later is part of all distributions of LaTeX version % \printindex % \end{document} % \end{VerbatimOut} +%^^A +% This example further illustrates aspects of automation be it practical or not. 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. % -% 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. +% 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. This design helps to prevent spurious index entries. % -% \begin{quote} -% \VerbatimInput[gobble=0,lastline=54]{\NameauthTestFile} -% \end{quote} +% We must use \cmd{\PretagName} to sort the names in the index. \cmd{\Revert} is used to print a specific form of the surname (via the macros in the naming arguments) as well as suppressing the margin note (via the formatting hooks). Thus we show a complex interplay between syntactic name forms and typographic name formatting. +% \begin{Quote} +% \VerbatimInput[gobble=0,lastline=41]{\NameauthTestFile} +% +% \newpage % -% 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. +% \VerbatimInput[gobble=0,firstline=42, lastline=46]{\NameauthTestFile} +% \end{Quote} % -% In the hooks 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. +% Next we define the two formatting hooks that govern changes in the text. We force \cmd{\NamesFormat} to print 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. % +% Macros in the name arguments take the role usually played by internal Boolean flags. In the hooks 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. +%^^A % \makeatletter % \renewcommand*\NamesFormat[1] % {^^A @@ -9162,453 +10232,38 @@ and version 1.3 or later is part of all distributions of LaTeX version % \global\RevertSNfalse^^A % } % \makeatother -% \begin{quote} -% \VerbatimInput[gobble=0,firstline=55,lastline=96]{\NameauthTestFile} -% \end{quote} +% \begin{Quote} +% \VerbatimInput[gobble=0,firstline=47, lastline=80]{\NameauthTestFile} % -% Finally, we put all these macros to work in the text: +% \newpage % -% \begin{quote} -% \VerbatimInput[gobble=0,firstline=97]{\NameauthTestFile} +% \VerbatimInput[gobble=0,firstline=81]{\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} -% -% \endgroup^^A Local format hook redefinition -% \AltFormatInactive -% -% \ReturnLink -% -% \AltFormatActive -% \begin{Quote}{\ForgetThis\Shak\break -% \hbox{}\hfill ``Julius Caesar'', Act III, Scene II (first performed 1599)} -% \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.\negmedskip^^A -% \index{creatives, quotes of\noexpand\string|hyperpage} -% \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} -% -% \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} -% -% \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 nonwestern 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 \Name[Bob]{Hope} \cmd{\Name[Bob]\{Hope\}}; all of the forms listed create the cross-reference ``\ShowIdxPageref*[Leslie Townes]{Hope} \textit{see} \ShowIdxPageref*[Bob]{Hope}''. -% -% \begin{center}\small -% \vspace{2ex} -% \Info{\strut\footnotesize Name Pattern(s):\hfill \break -% \ttfamily \ShowPattern[Bob]{Hope}!MN\break -% \ShowPattern[Leslie Townes]{Hope}!PN} -% \vspace{-2ex} -% \begin{tabular}{ll}\toprule -% \rowcolor{nagrey}^^A -% \AKA[Bob]{Hope}[Leslie Townes]{Hope}& -% |\AKA[Bob]{Hope}[Leslie Townes]{Hope}|\\ -% -% \RevComma\AKA[Bob]{Hope}[Leslie Townes]{Hope}& -% |\RevComma\AKA[Bob]{Hope}[Leslie Townes]{Hope}|\\ -% -% \rowcolor{nagrey}^^A -% \AKA[Bob]{Hope}[Leslie Townes]{Hope}[Lester T.]& -% |\AKA[Bob]{Hope}[Leslie Townes]{Hope}[Lester T.]|\\ -% -% \AKA*[Bob]{Hope}[Leslie Townes]{Hope}& -% |\AKA*[Bob]{Hope}[Leslie Townes]{Hope}|\\ -% -% \rowcolor{nagrey}^^A -% \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 entries: -% -% \begin{quote} -% \begin{tabular}{ll} -% \ForgetThis\Name{Louis, XIV}& -% |\ForgetThis\Name{Louis, XIV}|\\ -% \Name{Lao-tzu} & |\Name{Lao-tzu}|\\ -% \Name[Lafcadio]{Hearn} & |\Name[Lafcadio]{Hearn}|\\ -% \Name[Charles]{du~Fresne}& -% |\Name[Charles]{du~Fresne}|\\ -% \end{tabular} -% \end{quote} -% Caps and reversing macros work on the arguments that are printed -% in the text. -% -% \begin{center} -% \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} -% \begin{tabular}{ll}\toprule -% \rowcolor{nagrey}^^A -% \AKA{Louis, XIV}{Sun King} & |\AKA{Louis, XIV}{Sun King}|\\ -% \rowcolor{nagrey}^^A -% \AKA{Louis, XIV}{Sun King} & |\AKA*{Louis, XIV}{Sun King}|\\ -% -% \AKA{Lao-tzu}{Li, Er} & |\AKA{Lao-tzu}{Li, Er}|\\ -% \AKA*{Lao-tzu}{Li, Er} & |\AKA*{Lao-tzu}{Li, Er}|\\ -% -% \rowcolor{nagrey}^^A -% \AKA[Charles]{du~Fresne}{du~Cange}& -% |\AKA[Charles]{du~Fresne}{du~Cange}|\\ -% \rowcolor{nagrey}^^A -% \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}|\\ -% \RevName\AKA[Lafcadio]{Hearn}{Koizumi, Yakumo}& -% |\RevName\AKA[Lafcadio]{Hearn}{Koizumi, Yakumo}|\\\bottomrule -% \end{tabular} -% \end{center} -% -% -% \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} -% \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} -% \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} -% \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} -% \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}). -% -% 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} -% \makeatletter\@nameauth@AKAFormattrue\makeatother -% \global\NamesInactive -% \begin{tabular}{>{\columncolor{nagrey}}rll} -% \rowcolor{nagrey}^^A -% & |\ForgetThis\Eliz| & |\AKA{Elizabeth,I}%|\\ -% \rowcolor{nagrey}^^A -% & & |[Good Queen]{Bess}|\\[0.5ex] -% -% Front Matter: & \ForgetThis\Eliz & -% \AKA{Elizabeth,I}[Good Queen]{Bess}\\[0.5ex] -% \global\NamesActive^^A -% \strut Main Matter: & \ForgetThis\Eliz & -% \AKA{Elizabeth, I}[Good Queen]{Bess}\\[0.5ex] -% With \cmd{\ForceName}: & & -% \ForceName\AKA{Elizabeth, I}[Good Queen]{Bess}\\ -% \end{tabular} -% \vspace{-14ex} -% \PatInfo{\ShowPattern{Elizabeth, I}!NF\break -% \ShowPattern[Good Queen]{Bess}!PN\break -% \ShowPattern{Elizabeth, I}!MN} -% \vspace{14ex} -% \end{center} -% -% 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. -% -% 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} -% \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 nonwestern 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 nonwestern 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} -% \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. -% \Fukuyama\ddag\ \cmd{\Fukuyama}\cmd{\ddag} published -% \textit{Nihon Fukuin R\=uteru Ky\=okai Shi} (History -% of the Evangelical Lutheran Church in Japan). -% \AltFormatInactive -% -% \newpage -% -% \begin{center} -% \begin{tabular}{ll}\toprule -% \rowcolor{nagrey}^^A -% \ForgetThis\Name{Henry}[VIII]\ddag & -% |\ForgetThis\Name{Henry}[VIII]\ddag|\\ -% \rowcolor{nagrey}^^A -% \Name{Henry}[VIII]\ddag & -% |\Name{Henry}[VIII]\ddag|\\ -% -% \ForgetThis\Name{Chiang}[Kai-shek]\ddag & -% |\ForgetThis\Name{Chiang}[Kai-shek]\ddag|\\ -% \Name{Chiang}[Kai-shek]\ddag & -% |\Name{Chiang}[Kai-shek]\ddag|\\ -% -% \rowcolor{nagrey}^^A -% \Dagb\ddag & |\Dagb\ddag|\\ -% \rowcolor{nagrey}^^A -% \Dagb\ddag & |\Dagb\ddag|\\ -% -% \CapName\Yosh\ddag & |\CapName\Yosh\ddag|\\ -% \CapName\RevName\LYosh\ddag & |\CapName\RevName\LYosh\ddag|\\ -% -% \rowcolor{nagrey}^^A -% & |\AltFormatActive| \AltFormatActive\\ -% \rowcolor{nagrey}^^A -% \ForgetThis\Fukuyama\ddag & |\ForgetThis\Fukuyama\ddag|\\ -% \rowcolor{nagrey}^^A -% \Fukuyama\ddag & |\Fukuyama\ddag|\\ -% \rowcolor{nagrey}^^A -% & |\AltFormatInactive| \AltFormatInactive\\\bottomrule -% \end{tabular} -% \end{center} -% -% Regardless of its flaws, the obsolete syntax shares name patterns, index tags, name tags, and index entries with the current syntax: -% -% \begin{quote} -% \begin{tabular}{@{}lll} -% Obsolete syntax: & \ForgetThis\Name{Henry}[VIII]\ddag & -% \cmd{\ForgetThis}\cmd{\Name\{Henry\}[VIII]}\cmd{\ddag}\\[1ex] -% & \ShowPattern{Henry}[VIII] & \cmd{\ShowPattern\{Henry\}[VIII]}\\[1ex] -% Current syntax: & \Name{Henry, VIII} & \cmd{\Name\{Henry, VIII\}}\\[1ex] -% & \ShowPattern{Henry, VIII} & \cmd{\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 such variants: -% \item[] \Name*{Henry, VIII}[Tudor]\dotfill \cmd{\Name*\{Henry, VIII\}[Tudor]} -% \item The proper form for the old syntax is, e.g.: -% \item[] \Name*{Henry}[VIII]\dotfill \cmd{\Name*\{Henry\}[VIII]} -% \IndexInactive -% \item Next we see malformed Western names: -% \item[] \Name[Henry]{VIII}\dotfill \cmd{\Name[Henry]\{VIII\}}\\ -% \Name[Henry]{VIII}\dotfill \cmd{\Name[Henry]\{VIII\}}\\ -% \Name*[Henry]{VIII}[Tudor]\dotfill \cmd{\Name*[Henry]\{VIII\}[Tudor]}\\ -% \Name[Henry]{VIII}[Tudor]\dotfill \cmd{\Name[Henry]\{VIII\}[Tudor]} -% \item These malformed names have the same index entry\dotfill^^A -% \ShowIdxPageref*[Henry]{VIII} -% \IndexActive -% \end{itemize} -% -% \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.\negmedskip^^A -% \index{creatives, quotes of\noexpand\string|hyperpage} % \end{Quote} +% \endgroup^^A Local format hook redefinition % -% \newpage -% -% \begingroup^^A General format hook redefinition. -% \section{Advanced Customization} +% \subsection{Advanced Customization} % \label{sec:AdvCustomize} % -% Here we discuss package internals to help users customize and add features. We set aside the common formatting in this manual and reset the formatting hooks to the default settings. We use alternate formatting for much of this section: -% -% \begin{VerbatimOut}{\jobname.tmp} -% \renewcommand*\NamesFormat{} -% \renewcommand*\FrontNamesFormat{} -% \renewcommand*\MainNameHook{\AltOff} -% \renewcommand*\FrontNameHook{\AltOff} -% \end{VerbatimOut} -% -% \begin{quote} -% \VerbatimInput[gobble=0]{\jobname.tmp} -% \end{quote} -% \input{\jobname.tmp} +% Here we discuss customization and adding features. We set aside the formatting in this manual, using alternate formatting for much of this section. % -% \AltFormatActive % \begingroup^^A Local format hook redefinition % -% \subsection{Using Package Internals} +% \subsubsection[Using Internals]{Using Package Internals} % % We start with alternate formatting (Section~\ref{sec:AltFormat}), changing the ``back-end'' macros to our custom code. Here, we need only check \texttt{\textbackslash if@nameauth@DoAlt}, which is toggled by \cmd{\AltOn} and \cmd{\AltOff}. % 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: -% +%^^A % \ifdefined\NameauthDoTestFiles \edef\NameauthTestFile{test13_01.tex}\else % \edef\NameauthTestFile{\jobname.tmp}\fi -% +%^^A % \begin{VerbatimOut}{\NameauthTestFile} % \documentclass{article} -% \input{compat.tex} % Included with nameauth; example file aids -% % compatibility across different LaTeX versions and engines. +% \input{compat.tex} % Included with nameauth for compatibility. % \usepackage{makeidx} % \usepackage[altformat]{nameauth} % @@ -9646,305 +10301,69 @@ and version 1.3 or later is part of all distributions of LaTeX version % \printindex % \end{document} % \end{VerbatimOut} -% -% \begin{quote} -% \VerbatimInput[gobble=0,lastline=13]{\NameauthTestFile} -% \end{quote} +%^^A +% \begin{Quote} +% \VerbatimInput[gobble=0,lastline=14]{\NameauthTestFile} +% \end{Quote} % % 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} -% \VerbatimInput[gobble=0,firstline=14,lastline=24]{\NameauthTestFile} -% \end{quote} +% \begin{Quote} +% \VerbatimInput[gobble=0,firstline=15,lastline=25]{\NameauthTestFile} +% \end{Quote} % % \makeatletter % \newcommand*\Fbox[1]{^^A % \if@nameauth@DoAlt\protect\fbox{#1}\else#1\fi % }^^A % \makeatother -% -% \begingroup -% \renewcommand*\NamesFormat[1]{\color{blue}\sffamily #1} -% \renewcommand*\MainNameHook[1]{\sffamily #1} -% \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.\footnote{Here we enclosed this quote in a group and redefined the formatting hooks locally.}^^A -% \index{theologians, quotes of\noexpand\string|hyperpage} -% \index{philosophers, quotes of\noexpand\string|hyperpage} -% \end{Quote} -% \endgroup -% -% \newpage +% \renewcommand*\MainNameHook{\AltOff} +% \renewcommand*\FrontNameHook{\AltOff} % % The final step is redefining the hooks, which can be quite simple: -% -% \begin{quote} -% \VerbatimInput[gobble=0,firstline=25]{\NameauthTestFile} +% \begin{Quote} +% \VerbatimInput[gobble=0,firstline=26]{\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} +% \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}} -% Alternate formatting can work with greater customization, but that 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 shows greater customization that remains compatible with package internals. -% -% 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; example file aids -% % compatibility across different LaTeX versions and engines. -% \usepackage{makeidx} -% \usepackage[altformat]{nameauth} -% -% \makeindex -% -% \newif\ifFbox % Replaces \if@nameauth@DoAlt \AltOn \AltOff -% \newif\ifFirstCap % Replaces \if@nameauth@DoCaps \AltCaps -% \newif\ifInHook % Replaces \if@nameauth@InHook hook dispatcher -% \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 -% -% % 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} -% \VerbatimInput[gobble=0,lastline=11]{\NameauthTestFile} -% \end{quote} -% -% 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} -% -% Our \cmd{\AltCaps} works like the built-in version, except it does not use the internal macros and flags. We 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 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 same macros used before now use a different ``back end'' 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} -% \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} -% -% \ifdefined\NameauthDoTestFiles \edef\NameauthTestFile{test13_03.tex}\else -% \edef\NameauthTestFile{\jobname.tmp}\fi -% -% \begin{VerbatimOut}{\NameauthTestFile} -% \documentclass{article} -% \input{compat.tex} % Included with nameauth; example file aids -% % compatibility across different LaTeX versions and 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} +% \subsubsection[Name Hooks]{Using Name Hooks} +% \label{sec:FullCustomize} % -% \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#1\global\FirstCapfalse} -% \let\FrontNamesFormat\Namesformat -% \let\FrontNameHook\MainNameHook +% \begingroup^^A Local format hook redefinition % -% We can go one step further and use our own ``back-end'' macros with other documents that were designed for the built-in macros used in alternate formatting, as the next example shows: +% One can redesign or augment the core naming macros that handle regular, long, and short names, then hook those changes into the core name engine. It should be obvious that such changes could break \textsf{nameauth} if not done carefully. These macros are set by default to \cmd{\@nameauth@Name}, the internal name parser. +% \begin{itemize} +% \item \DescribeMacro{\NameauthName}\cmd{\Name}, or an unmodified shorthand, calls \cmd{\NameauthName}. % -% \begin{quote} -% \VerbatimInput[gobble=0]{\NameauthTestFile} +% \item \DescribeMacro{\NameauthLName}\cmd{\Name*}, or an L-shorthand, sets \cmd{\@nameauth@FullNametrue}, then calls \cmd{\NameauthLName}. % -% \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. +% \item \DescribeMacro{\NameauthFName}\cmd{\FName}, or an S-shorthand, sets \cmd{\@nameauth@FirstNametrue}, then calls \cmd{\NameauthFName}. +% \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} +% \begin{InfoBox} +% One should not modify \cmd{\Name} and \cmd{\FName} directly. +% \end{InfoBox} % -% \endgroup^^A Local format hook redefinition -% \AltFormatInactive +% \subsubsection*{\hfil Names In Boxes} % -% \subsection{Full Customization} -% \label{sec:FullCustomize} +% Since \textsf{nameauth} uses \textsf{xparse}, the next examples use it also. Here we look at decoration in the sense of putting a name into something around it. This could be useful if, in certain parts of a document, one wanted to turn names into hyperlinks or some other kind of feature. Here we simply put names into colored boxes.\footnote{After the parsed and formatted 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.} % -% 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. +% \Global These macros can be redefined or used locally within a scope without making global changes to the document unless you specifically use \cmd{\global}. % -% \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. -% -% \subsubsection{Names In Boxes} +% \newpage % -% Since \textsf{nameauth} uses \textsf{xparse}, the next examples use it also. Here we look at decorationin the sense of putting a name into something around it. This could be useful if, in certain parts of a document, one wanted to turn names into hyperlinks or some other kind of feature. Here we simply put names into colored boxes. -% -% \ifdefined\NameauthDoTestFiles \edef\NameauthTestFile{test13_04.tex}\else +% \ifdefined\NameauthDoTestFiles \edef\NameauthTestFile{test13_02.tex}\else % \edef\NameauthTestFile{\jobname.tmp}\fi -% +%^^A % \begin{VerbatimOut}{\NameauthTestFile} % \documentclass{article} -% \input{compat.tex} % Included with nameauth; example file aids -% % compatibility across different LaTeX versions and engines. +% \input{compat.tex} % Included with nameauth for compatibility. % \usepackage{makeidx} % \usepackage[altformat]{nameauth} % \usepackage{xcolor} @@ -9955,34 +10374,22 @@ and version 1.3 or later is part of all distributions of LaTeX version % % Change the general-case name macro to show % % a name in a framed, colored box. % -% \NewDocumentCommand{\MyName}{O{} m O{}}{% -% \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]}% -% } +% \NewDocumentCommand{\MyName}{O{} m O{}} +% {\fcolorbox{black}{gray!25!white}{\@nameauth@Name[#1]{#2}[#3]}} % % % Likewise change the macro for when names are forced long. -% \NewDocumentCommand{\MyLName}{O{} m O{}}{% -% \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]}% -% } +% \NewDocumentCommand{\MyLName}{O{} m O{}} +% {\fcolorbox{black}{green!25!white}{\@nameauth@Name[#1]{#2}[#3]}} % % % Likewise change the macro when personal names are desired. -% \NewDocumentCommand{\MyFName}{O{} m O{}}{% -% \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]}% -% } +% \NewDocumentCommand{\MyFName}{O{} m O{}} +% {\fcolorbox{black}{yellow!25!white}{\@nameauth@Name[#1]{#2}[#3]}} % \makeatother % % % 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} +% % formatting, which is separate from the customization above. +% \renewcommand*\NamesFormat{\scshape} +% \renewcommand*\MainNameHook{} % % % Change the naming macro hooks. % \renewcommand*\NameauthName{\MyName} @@ -9999,35 +10406,23 @@ and version 1.3 or later is part of all distributions of LaTeX version % \printindex % \end{document} % \end{VerbatimOut} -% -% \begin{quote} +%^^A +% \begin{Quote} % \VerbatimInput[gobble=0]{\NameauthTestFile} % % \makeatletter -% \NewDocumentCommand{\MyName}{O{} m O{}}{^^A -% \global\@nameauth@toksa\expandafter{#1}^^A -% \global\@nameauth@toksb\expandafter{#2}^^A -% \global\@nameauth@toksc\expandafter{#3}^^A -% \fcolorbox{black}{gray!25!white}{\@nameauth@Name[#1]{#2}[#3]}^^A -% } -% -% \NewDocumentCommand{\MyLName}{O{} m O{}}{^^A -% \global\@nameauth@toksa\expandafter{#1}^^A -% \global\@nameauth@toksb\expandafter{#2}^^A -% \global\@nameauth@toksc\expandafter{#3}^^A -% \fcolorbox{black}{green!25!white}{\@nameauth@Name[#1]{#2}[#3]}^^A -% } +% \NewDocumentCommand{\MyName}{O{} m O{}} +% {\fcolorbox{black}{gray!25!white}{\@nameauth@Name[#1]{#2}[#3]}} % -% \NewDocumentCommand{\MyFName}{O{} m O{}}{^^A -% \global\@nameauth@toksa\expandafter{#1}^^A -% \global\@nameauth@toksb\expandafter{#2}^^A -% \global\@nameauth@toksc\expandafter{#3}^^A -% \fcolorbox{black}{yellow!25!white}{\@nameauth@Name[#1]{#2}[#3]}^^A -% } +% \NewDocumentCommand{\MyLName}{O{} m O{}} +% {\fcolorbox{black}{green!25!white}{\@nameauth@Name[#1]{#2}[#3]}} % +% \NewDocumentCommand{\MyFName}{O{} m O{}} +% {\fcolorbox{black}{yellow!25!white}{\@nameauth@Name[#1]{#2}[#3]}} % \makeatother -% \renewcommand*\NamesFormat[1]{\scshape#1} -% \renewcommand*\MainNameHook[1]{#1} +% +% \renewcommand*\NamesFormat{\scshape} +% \renewcommand*\MainNameHook{} % \renewcommand*\NameauthName{\MyName} % \renewcommand*\NameauthLName{\MyLName} % \renewcommand*\NameauthFName{\MyFName} @@ -10036,61 +10431,58 @@ and version 1.3 or later is part of all distributions of LaTeX version % the Fatherhood of God and the brotherhood of man. % \Name[Adolf]{Harnack} flourished in the early twentieth % century; \Name*[Adolf]{Harnack}[Adolf von]; \FName[Adolf]{Harnack}. -% \end{quote} -% -% 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. +% \end{Quote} +% \endgroup^^A Local format hook redefinition % -% 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}. +% \begingroup +% \renewcommand*\NamesFormat{\color{blue}\sffamily} +% \renewcommand*\MainNameHook{\sffamily} +% \begin{Quotation}{\Name[Mark]{Twain}} +% {\Title{The Innocents Abroad} (1869)} +% Virtue never has been as respectable as money. +% \index{creatives, quotes of\noexpand\string|hyperpage} +% \end{Quotation} +% \endgroup % % \newpage % -% \subsubsection{Change Parsing} -% \label{sec:ChangeParse} +% \begingroup^^A Local format hook redefinition % -% In Section~\ref{sec:FinalOptargs} we saw reasons why \textsf{nameauth} ignores spaces before final optional arguments. Here we show how to change that. With \textsf{xparse} since May 2018, the \texttt{!O\{\}} specifier makes spaces significant before an optional argument. Before then, the example below got the same result through undocumented behavior, now fixed. +% \subsubsection*{\hfil Change Parsing} % +% Section~\ref{sec:FinalOptargs} discussed final optional arguments. Here we use \textsf{xparse} to change the default behavior of optional arguments, but only for \TeX\ distros since May 2018. +%^^A % \begin{VerbatimOut}{\jobname.tmp} % \makeatletter -% \@ifl@t@r\fmtversion{2018/04/30}{\def\nameauthxp{}}{} -% \makeatother +% \@ifl@t@r\fmtversion{2018/04/30}{\newcommand\nameauthxp{}}{} % -% \makeatletter % \ifdefined\nameauthxp -% \NewDocumentCommand{\MyName}{O{} m !O{}}{% -% \global\@nameauth@toksa\expandafter{#1}% -% \global\@nameauth@toksb\expandafter{#2}% -% \global\@nameauth@toksc\expandafter{#3}% -% \@nameauth@Name[#1]{#2}[#3]% -% } +% \NewDocumentCommand{\MyName}{O{} m !O{}} +% {\@nameauth@Name[#1]{#2}[#3]} % \else -% \NewDocumentCommand{\MyName}{O{} m O{}}{% -% \global\@nameauth@toksa\expandafter{#1}% -% \global\@nameauth@toksb\expandafter{#2}% -% \global\@nameauth@toksc\expandafter{#3}% -% \@nameauth@Name[#1]{#2}[#3]% -% } +% \NewDocumentCommand{\MyName}{O{} m O{}} +% {\@nameauth@Name[#1]{#2}[#3]} % \fi % \makeatother % % \let\NameauthName\MyName % \let\NameauthLName\MyName % \let\NameauthFName\MyName -% % \ForgetName[Albert]{Einstein} % \ForgetName{Miyazaki, Hayao} % -% We want ``Albert Einstein [reportedly] said'', -% ``Miyazaki Hayao [supposedly] said'', -% ``Einstein [reportedly] said'', and -% ``Miyazaki [supposedly] said''. +% We want: ``Albert Einstein [first] spoke about physics. +% Miyazaki Hayao [later] spoke about animation. +% Einstein [first] spoke about physics. +% Miyazaki [later] spoke about animation.'' % -% We get ``\Name[Albert]{Einstein} [reportedly] said'', -% ``\Name{Miyazaki, Hayao} [supposedly] said'', -% ``\Name[Albert]{Einstein} [reportedly] said'', and -% ``\Name{Miyazaki, Hayao} [supposedly] said''. +% We get: ``\Name[Albert]{Einstein} [first] spoke about physics. +% \Name{Miyazaki, Hayao} [later] spoke about animation. +% \Name[Albert]{Einstein} [first] spoke about physics. +% \Name{Miyazaki, Hayao} [later] spoke about animation.'' % \end{VerbatimOut} -% -% \begin{quote} +%^^A +% \begin{Quote} %^^A Display the appropriate verbatim text above. % \VerbatimInput[gobble=0]{\jobname.tmp} %^^A Redefine formatting macros. @@ -10099,506 +10491,432 @@ and version 1.3 or later is part of all distributions of LaTeX version % % \makeatletter % \ifdefined\nameauthxp -% \NewDocumentCommand{\MyName}{O{} m !O{}}{%^^A -% \global\@nameauth@toksa\expandafter{#1}%^^A -% \global\@nameauth@toksb\expandafter{#2}%^^A -% \global\@nameauth@toksc\expandafter{#3}%^^A -% \@nameauth@Name[#1]{#2}[#3]} +% \NewDocumentCommand{\MyName}{O{} m !O{}} +% {\@nameauth@Name[#1]{#2}[#3]} % \else -% \NewDocumentCommand{\MyName}{O{} m O{}}{%^^A -% \global\@nameauth@toksa\expandafter{#1}%^^A -% \global\@nameauth@toksb\expandafter{#2}%^^A -% \global\@nameauth@toksc\expandafter{#3}%^^A -% \@nameauth@Name[#1]{#2}[#3]} +% \NewDocumentCommand{\MyName}{O{} m O{}} +% {\@nameauth@Name[#1]{#2}[#3]} % \fi % \makeatother % % \let\NameauthName\MyName % \let\NameauthLName\MyName % \let\NameauthFName\MyName -% % \ForgetName[Albert]{Einstein} % \ForgetName{Miyazaki, Hayao} % -% We want ``Albert Einstein [reportedly] said'', -% ``Miyazaki Hayao [supposedly] said'', -% ``Einstein [reportedly] said'', and -% ``Miyazaki [supposedly] said''. +% We want: ``Albert Einstein [first] spoke about physics. +% Miyazaki Hayao [later] spoke about animation. +% Einstein [first] spoke about physics. +% Miyazaki [later] spoke about animation.'' % -% We get ``\Name[Albert]{Einstein} [reportedly] said'', -% ``\Name{Miyazaki, Hayao} [supposedly] said'', -% ``\Name[Albert]{Einstein} [reportedly] said'', and -% ``\Name{Miyazaki, Hayao} [supposedly] said''. -% \end{quote} -% \endgroup^^A General format hook redefinition +% We get: ``\Name[Albert]{Einstein} [first] spoke about physics. +% \Name{Miyazaki, Hayao} [later] spoke about animation. +% \Name[Albert]{Einstein} [first] spoke about physics. +% \Name{Miyazaki, Hayao} [later] spoke about animation.'' +% \end{Quote} % -% \ReturnLink +% \endgroup^^A Local format hook redefinition % -% \newpage +% \ReturnLink % -% \section{Technical Notes and Tips} -% \label{sec:TechNotes} +% \end{AltFormatZone} +% \Info{\hrule\strut We end a big region of alternate formatting\strut\hrule} % -% \subsection{Tips: General} +% \begingroup +% \renewcommand*\NamesFormat[1]{\color{blue}\sffamily #1} +% \renewcommand*\MainNameHook[1]{\sffamily #1} +% \begin{Quotation}{\Name[Herbert]{Hoover}} +% {\Title{American Individualism} (1922)} +% \textls[-5]{Now, as the storm of war, of revolution and of emotion +% subsides there is left even with us of the United States much unrest, +% much discontent with the surer forces of human advancement. To all of +% us, out of this crucible of actual, poignant, individual experience +% has come a deal of new understanding, and it is for all of us to ponder +% these new currents if we are to shape our future with intelligence.} +% \index{politicians, quotes of\noexpand\string|hyperpage} +% \end{Quotation} +% \endgroup % -% \begin{itemize} -% \item Technical details about package development and testing are in \texttt{README.md}. -% \item Both \texttt{compat.tex} and \texttt{examples.tex} contain useful information. -% \item Do not put naming macros withing a macro defined by \cmd{\edef}. -% Yet naming macros can be passed as arguments to such a macro. -% \item In \texttt{dtx} files, the \texttt{nameauth} environment and initial tagging -% macros work easiest in the \texttt{<driver>} section preamble. Yet if any of these -% contains one or more \cmd{\newif} statements, they must go in the ``commented part'' -% since the preamble falls between \texttt{\textbackslash iffalse} and -% \texttt{\textbackslash fi}. -% \end{itemize} +% \newpage % -% \subsection[Tips: Indexing]{Tips: Indexing and Sorting} -% \label{sec:DebugSort} +% \section{Obsolete Features} +% \label{sec:OldStuff} % -% \begin{itemize} -% \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}, \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 active characters, spaces, or control sequences -% in the name arguments? Use \cmd{\PretagName}. -% \item Is alternate formatting used consistently? Are names used -% within sections of alternate formatting used outside of them? -% \item Are macros in the name arguments that can expand differently -% under different conditions preceded by \cmd{\noexpand}? -% \end{itemize} -% \end{itemize} +% \begin{InfoBox}[General Hook Redefinition] +% \VerbatimInput[gobble=0,numbers=none,fontsize=\small]{manhook.tmp} +% \end{InfoBox} % -% Using \cmd{\protected@edef} in macros can add spaces to index entries. The \textsf{nameauth} macros must use \cmd{\protected@edef} to work with classes that write index entries to \texttt{aux} files. One must check this in the \texttt{idx} file. We show this below: +% \input{manhook.tmp} % -% \begin{quote} -% \begin{Verbatim} -% \makeatletter -% \newcommand\Idx[1]{\protected@edef\arg{#1}\index{\arg}} -% \makeatother -% \end{Verbatim} +% \subsection[Pseudonyms]{Pseudonym Macros} +% \label{sec:AKA} % -% \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} +% The macros described in this section are early features of \textsf{nameauth}. They do not work like other macros that display names. They remain only for backward compatibility, but will not be developed further. % -% \subsection[Tips: Name Args]{Tips: Macros in Name Arguments} +% \subsubsection*{\hfil Special Syntax} % -% \begin{itemize} -% \item A missing square bracket or curly brace in name arguments can cause errors like -% ``\texttt{Paragraph ended}'' and ``\texttt{Missing} \meta{grouping token} -% \texttt{inserted.}'' -% \item Use alternate formatting to avoid potential problems, especially -% when using \cmd{\CapThis}, which segments arguments (Sections~\ref{sec:AltFormat}, -% \ref{sec:AdvCustomize}). -% \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}. -% \item Below we show general aspects of scoping to apply them to this package: -% \end{itemize} +% To save space, we show \meta{SAFX} as the equivalent of \meta{SNN\textbf{,}Affix}. The macros in this section all take arguments of the form: % -% \begin{VerbatimOut}{\jobname.tmp} -% \newif\ifCondA -% \newcommand\MacroA{} -% \begingroup -% \newif\ifCondB -% \global\newif\ifCondC -% \global\newcommand\MacroB{} -% \newcommand\MacroC{\def\MacroD{}} -% \global\MacroC -% \global\CondAtrue -% \endgroup +% \begin{SyntaxBoxii} +% Target Name & Cross-Reference Name\\\midrule +% \oarg{FNN}\marg{SAFX} & \oarg{xref FNN}\marg +% {xref SAFX}\oarg{xref Alt.}\\ +% \end{SyntaxBoxii} % % \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 The target name comes first, which is the \emph{opposite} of \cmd{\IndexRef}. There the target name comes last because it is text passed to the index macros. % -% \item \ifdefined\CondBtrue \texttt{\textbackslash ifCondB} is defined -% \else \texttt{\textbackslash ifCondB} is not defined \fi -% in the outer scope (local definition). +% \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{Alt.} nor the obsolete syntax can be used with the target name. Both can be used with the cross-reference. % -% \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 \meta{SAFX} and \meta{xref SAFX} can have comma-delimited suffixes. % -% \item \ifCondA \texttt{\textbackslash ifCondA} is true -% \else \texttt{\textbackslash ifCondA} is false \fi -% (\cmd{\global} assignment works, not instantiation). +% \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} -% \end{VerbatimOut} % -% \begin{quote} -% \VerbatimInput[gobble=0]{\jobname.tmp} -% -% \input{\jobname.tmp} -% \end{quote} -% -% Any macro that is used in the argument of a naming macro must be defined in all scopes in which that name is used. The names themselves are global, but macros in their arguments are not guaranteed to be so: -% -% \begin{VerbatimOut}{\jobname.tmp} -% \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{VerbatimOut} -% -% \begin{quote} +% This syntax can produce results in the text that can look legitimate, yet the index entries are wrong due to confusion. The normal name arguments make it easier to determine name forms. For example, % \IndexInactive -% \VerbatimInput[gobble=0]{\jobname.tmp} +% \begin{itemize} +% \item We see \PName*{William, I}[William]{the Conqueror} in the text. +% \item |\PName*{William, I}[William]{the Conqueror}| +% \item The syntax obfuscates the fact that the xref has a Western form. +% \item The index is wrong: ``\ShowIdxPageref*[William]{the Conqueror} \textit{see} \ShowIdxPageref*{William, I}'' +% \end{itemize} +% \IndexActive % -% \input{\jobname.tmp} -% \end{quote} +% \newpage % +% \subsubsection*{\hfil The Macros} % -% \subsection[Active Unicode]{Active Unicode Characters} -% \label{sec:Unicode} +% \DescribeMacro{\AKA} +% The \emph{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. % -% \subsubsection{General Information} +% \begin{SyntaxBox} +% \small\cmd{\AKA\ }\oarg{FNN}\marg{SAFX}\oarg{xref FNN}\marg +% {xref SAFX}\oarg{xref Alt.}\\ +% \small\cmd{\AKA*}\oarg{FNN}\marg{SAFX}\oarg{xref FNN}\marg +% {xref SAFX}\oarg{xref Alt.}\\ +% \end{SyntaxBox} % -% Both \texttt{xelatex} and \texttt{lualatex} support Unicode natively. In \texttt{pdflatex}, this happens with active characters. There are features (e.g., in \textsf{microtype}) that require \texttt{pdflatex}. Both \texttt{makeindex} and \texttt{xindy} have their own design choices. +% \begin{itemize} +% \item Both macros create a cross-reference in the index to the target name. % -% 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} for more information. +% \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*}. % -% 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}): +% \item If \meta{xref Alt.} is present in a Western name form, then instead of \meta{xref FNN}, \meta{xref Alt.} will be printed in the text. % -% \begin{quote} -% \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} +% \item If \meta{xref Alt.} is present in a Non-Western name form, then instead of \meta{xref Affix} (if present), \meta{xref Alt.} will be printed in the text. % -% In Congreſs, July 4, 1776 -% \end{quote} +% \item If \meta{xref Alt.} is present without either \meta{xref FNN} or \meta{xref Affix}, the obsolete syntax is used only with the xref. % -% Below we group characters that are supported in \texttt{pdflatex} -% without additional modification by accents and diacritical marks: +% \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*}. % -% \begin{center}\large -% \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}{ll}\toprule -% \rowcolor{nagrey}^^A -% \bfseries Capitals & \strut\\ +% \item \cmd{\AKA}, \cmd{\AKA*}, \cmd{\PName*}, and \cmd{\PName*} do not 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} % -% acute & Á Ć \Bullet{D} É Ǵ \Bullet{H} Í \Bullet{J} \Bullet{K} Ĺ -% Ń Ó Ŕ Ś \Bullet{T} Ú \Bullet{W} Ý Ź \strut\\ +% Below we make cross-references to \Name[Bob]{Hope} \cmd{\Name[Bob]\{Hope\}}; all of the forms listed create the cross-reference ``\ShowIdxPageref*[Leslie Townes]{Hope} \textit{see} \ShowIdxPageref*[Bob]{Hope}''. +% \begin{Block} +% \PatInfo[3ex]{\ShowPattern[Bob]{Hope}!MN\break +% \ShowPattern[Leslie Townes]{Hope}!PN} +% \AKA[Bob]{Hope}[Leslie Townes]{Hope}\dotfill^^A +% |\AKA[Bob]{Hope}[Leslie Townes]{Hope}|\\ +% \RevComma\AKA[Bob]{Hope}[Leslie Townes]{Hope}\dotfill^^A +% |\RevComma\AKA[Bob]{Hope}[Leslie Townes]{Hope}|\\ +% \AKA[Bob]{Hope}[Leslie Townes]{Hope}[Lester T.]\dotfill^^A +% |\AKA[Bob]{Hope}[Leslie Townes]{Hope}[Lester T.]|\\ +% \AKA*[Bob]{Hope}[Leslie Townes]{Hope}\dotfill^^A +% |\AKA*[Bob]{Hope}[Leslie Townes]{Hope}|\\ +% \AKA*[Bob]{Hope}[Leslie Townes]{Hope}[Lester]\dotfill^^A +% |\AKA*[Bob]{Hope}[Leslie Townes]{Hope}[Lester]| +% \end{Block} % -% \rowcolor{nagrey}^^A -% grave & À \Bullet{C} \Bullet{D} È \Bullet{G} \Bullet{H} Ì \Bullet{J} -% \Bullet{K} \Bullet{L} \Bullet{N} Ò \Bullet{R} \Bullet{S} -% \Bullet{T} Ù \Bullet{W} \Bullet{Y} \Bullet{Z} \strut\\ +% Using these macros with Roman names and other specialized names likely will produce unsatisfactory results. Below we display other name forms after referring to some names to ensure that they have sensible page entries: +% \PatInfo[4ex]{\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} +% \begin{Quote} +% \begin{tabular}{@{}ll} +% \ForgetThis\Name{Louis, XIV}& +% |\ForgetThis\Name{Louis, XIV}|\\ +% \Name{Lao-tzu} & |\Name{Lao-tzu}|\\ +% \Name[Lafcadio]{Hearn} & |\Name[Lafcadio]{Hearn}|\\ +% \Name[Charles]{du~Fresne}& +% |\Name[Charles]{du~Fresne}|\\ +% \end{tabular} +% \end{Quote} +% Caps and reversing macros work on the arguments that are printed +% in the text. +% \begin{Block} +% \AKA{Louis, XIV}{Sun King}\dotfill^^A +% |\AKA{Louis, XIV}{Sun King}|\\ +% \AKA{Lao-tzu}{Li, Er}\dotfill^^A +% |\AKA{Lao-tzu}{Li, Er}|\\ +% \AKA[Charles]{du~Fresne}{du~Cange}\dotfill^^A +% |\AKA[Charles]{du~Fresne}{du~Cange}|\\ +% \CapThis\AKA[Charles]{du~Fresne}{du~Cange}\dotfill^^A +% |\CapThis\AKA[Charles]{du~Fresne}{du~Cange}|\\ +% \CapName\AKA[Lafcadio]{Hearn}{Koizumi, Yakumo}\dotfill^^A +% |\CapName\AKA[Lafcadio]{Hearn}{Koizumi, Yakumo}|\\ +% \RevName\AKA[Lafcadio]{Hearn}{Koizumi, Yakumo}\dotfill^^A +% |\RevName\AKA[Lafcadio]{Hearn}{Koizumi, Yakumo}|\\ +% \ForceFN\AKA[Lafcadio]{Hearn}{Koizumi, Yakumo}\dotfill^^A +% |\ForceFN\AKA[Lafcadio]{Hearn}{Koizumi, Yakumo}| +% \end{Block} % -% circumflex &  Ĉ \Bullet{D} Ê Ĝ Ĥ Î Ĵ \Bullet{K} \Bullet{L} -% \Bullet{N} Ô \Bullet{R} Ŝ \Bullet{T} Û Ŵ Ŷ -% \Bullet{Z} \strut\\ +% \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 quirky rubbish, these two macros are a dumpster fire. +% \begin{SyntaxBox} +% \small\cmd{\PName\ }\oarg{FNN}\marg{SAFX}\oarg{xref\,FNN}\marg +% {xref\,SAFX}\oarg{xref\,Alt.}\\ +% \small\cmd{\PName*}\oarg{FNN}\marg{SAFX}\oarg{xref\,FNN}\marg +% {xref\,SAFX}\oarg{xref\,Alt.}\\ +% \end{SyntaxBox} % -% \rowcolor{nagrey}^^A -% tilde & à \Bullet{C} \Bullet{D} \Bullet{E} \Bullet{G} \Bullet{H} -% Ĩ \Bullet{J} \Bullet{K} \Bullet{L} Ñ Õ \Bullet{R} -% \Bullet{S} \Bullet{T} Ũ \Bullet{W} \Bullet{Y} -% \Bullet{Z} \strut\\ +% \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 Alt.}. +% \begin{itemize} +% \item Most prefix macros only affect \meta{FNN}\meta{SAFX}, not the cross-reference. % -% diaeresis\footnotemark & Ä \Bullet{C} \Bullet{D} Ë \Bullet{G} \Bullet{H} -% Ï \Bullet{J} \Bullet{K} \Bullet{L} \Bullet{N} Ö \Bullet{R} -% \Bullet{S} \Bullet{T} Ü \Bullet{W} Ÿ \Bullet{Z} \strut\\ +% \item The cross-reference always has a long form. % -% \rowcolor{nagrey}^^A -% cedilla & \Bullet{A} Ç \Bullet{D} \Bullet{E} Ģ \Bullet{H} \Bullet{I} -% \Bullet{J} Ķ Ļ Ņ \Bullet{O} Ŗ Ş Ţ \Bullet{U} \Bullet{W} -% \Bullet{Y} \Bullet{Z} \strut\\ +% \item \cmd{\SkipIndex} keeps both names out of the index. % -% macron & Ā \Bullet{C} \Bullet{D} Ē Ḡ \Bullet{H} Ī \Bullet{J} -% \Bullet{K} \Bullet{L} \Bullet{N} Ō \Bullet{R} \Bullet{S} -% \Bullet{T} Ū Ǣ Ȳ \Bullet{Z} \strut\\ +% \item \meta{Alt.} and the obsolete syntax work only with the cross-reference. +% \end{itemize} +% \ForgetName[Mark]{Twain} +% \ForgetName{William, I} +% \ForgetName{Lao-tzu} +% \begin{Block} +% \FUse \PName[Mark]{Twain}[Samuel L.]{Clemens}\\ +% \LUse \PName[Mark]{Twain}[Samuel L.]{Clemens}\\ +% \UseB |\PName[Mark]{Twain}[Samuel L.]{Clemens}|\\ +% \UseL \PName*[Mark]{Twain}[Samuel L.]{Clemens}\\ +% \UseB |\PName*[Mark]{Twain}[Samuel L.]{Clemens}| +% +% \UseI \ShowIdxPageref*[Samuel L.]{Clemens} \textit{see} +% \ShowIdxPageref*[Mark]{Twain}\medskip +% +% \FUse \ForgetThis\PName{Voltaire}[François-Marie]{Arouet}\\ +% \LUse \PName{Voltaire}[François-Marie]{Arouet}\\ +% \UseB |\PName{Voltaire}[François-Marie]{Arouet}| +% +% \UseI \ShowIdxPageref*[François-Marie]{Arouet} \textit{see} +% \ShowIdxPageref*{Voltaire}\medskip +% +% \FUse \PName{William, I}{William, the Conqueror}\\ +% \LUse \PName{William, I}{William, the Conqueror}\\ +% \UseB |\PName{William, I}{William, the Conqueror}|\\ +% \UseL \PName*{William, I}{William, the Conqueror}\\ +% \UseB |\PName*{William, I}{William, the Conqueror}| +% +% \UseI \ShowIdxPageref*{William, the Conqueror} \textit{see} +% \ShowIdxPageref*{William, I}\medskip +% +% \FUse \PName{Bernard, of Clairvaux} +% {\textit{Doctor mellifluus}}\\ +% \LUse \PName{Bernard, of Clairvaux} +% {\textit{Doctor mellifluus}}\\ +% \UseB |\PName{Bernard, of Clairvaux}|\\ +% \UseB | {\textit{Doctor mellifluus}}|\\ +% \UseL \PName*{Bernard, of Clairvaux} +% {\textit{Doctor mellifluus}}\\ +% \UseB |\PName*{Bernard, of Clairvaux}|\\ +% \UseB | {\textit{Doctor mellifluus}}| +% +% \UseI \ShowIdxPageref*{\textit{Doctor mellifluus}} \textit{see} +% \ShowIdxPageref*{Bernard, of Clairvaux}\medskip +% +% \FUse \PName{Lao-tzu}{Li, Er}\\ +% \LUse \PName{Lao-tzu}{Li, Er}\\ +% \UseB |\PName{Lao-tzu}{Li, Er}| +% +% \UseI \ShowIdxPageref*{Li, Er} \textit{see} \ShowIdxPageref*{Lao-tzu} +% \end{Block} % -% \rowcolor{nagrey}^^A -% breve & Ă \Bullet{C} \Bullet{D} \Bullet{E} Ğ \Bullet{H} Ĭ \Bullet{J} -% \Bullet{K} \Bullet{L} \Bullet{N} Ŏ \Bullet{R} \Bullet{S} -% \Bullet{T} Ŭ \Bullet{W} \Bullet{Y} \Bullet{Z} \strut\\ +% \subsubsection*{\hfil Formatting Workarounds} % -% dot/dotless & Ḃ Ċ \Bullet{D} Ė Ġ \Bullet{H} İ \Bullet{J} \Bullet{K} -% \Bullet{L} \Bullet{N} \Bullet{O} \Bullet{R} \Bullet{S} -% \Bullet{T} \Bullet{U} \Bullet{W} \Bullet{Y} Ż \strut\\ +% These macros only use subsequent-use formatting hooks (Section~\ref{sec:Formatting}). When \cmd{\NamesFormat} was the only formatting hook, cross-references printed in the text were not formatted. % -% \rowcolor{nagrey}^^A -% ogonek & Ą \Bullet{C} \Bullet{D} Ę \Bullet{G} \Bullet{H} Į \Bullet{J} -% \Bullet{K} \Bullet{L} \Bullet{N} Ǫ \Bullet{R} \Bullet{S} -% \Bullet{T} Ų \Bullet{W} \Bullet{Y} \Bullet{Z} \strut\\ +% \Info*{\small\texttt{formatAKA}}The \texttt{formatAKA} option permits \cmd{\ForceName} to force ``first-use'' formatting hooks, but under different conditions because the name patterns are in the cross-reference system (Section~\ref{sec:NamePatterns}). When using \texttt{formatAKA} we get: % -% caron & Ǎ Č Ď Ě Ǧ \Bullet{H} Ǐ \Bullet{J} Ǩ Ľ Ň Ǒ Ř Š Ť Ǔ \Bullet{W} -% \Bullet{Y} Ž \strut\\ +% \begingroup +% \makeatletter\@nameauth@AKAFormattrue\makeatother +% \begin{itemize} +% \global\NamesInactive +% \item Front Matter +% \PatInfo{\ShowPattern[Good Queen]{Bess}!PN} +% \begin{itemize}\footnotesize +% \item \AKA{Elizabeth,I}[Good Queen]{Bess}%^^A +% \dotfill |\AKA{Elizabeth,I}[Good Queen]{Bess}| +% \item \AKA{Elizabeth,I}[Good Queen]{Bess}%^^A +% \dotfill |\AKA{Elizabeth,I}[Good Queen]{Bess}| +% \end{itemize} % -% \rowcolor{nagrey}^^A -% various & Å Æ Ð (eth) Đ (stroke) IJ\ Ł -% Ŋ Ø Œ Ő Ů Ű Ș Ț Þ \strut\\\midrule +% \global\NamesActive +% \item Main Matter +% \begin{itemize}\footnotesize +% \item \AKA{Elizabeth,I}[Good Queen]{Bess}%^^A +% \dotfill |\AKA{Elizabeth,I}[Good Queen]{Bess}| +% \item \ForceName%^^A +% \AKA{Elizabeth,I}[Good Queen]{Bess}^^A +% \dotfill |\ForceName\AKA{Elizabeth,I}[Good Queen]{Bess}| +% \end{itemize} +% \end{itemize} +% \endgroup % -% \\\midrule +% 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 using the cross-reference name patterns. We need to use \cmd{\ForceName}, which triggers the expected use of \cmd{\NamesFormat}, the first-use main-matter hook. % -% \rowcolor{nagrey}^^A -% \bfseries Lowercase & \strut\\ +% \Info*{\small\texttt{alwaysformat}}We can use the \texttt{alwaysformat} option to force only the use of \cmd{\NamesFormat} and \cmd{\FrontNamesFormat}, but that can look like rubbish: +% \begin{Quote} +% \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} % -% acute & á ć \bullet{d} é ǵ \bullet{h} í \bullet{j} \bullet{k} ĺ -% ń ó ŕ ś \bullet{t} ú \bullet{w} ý ź \strut\\ +% \subsection{Obsolete Syntax} +% \label{sec:Obsolete} % -% \rowcolor{nagrey}^^A -% grave & à \bullet{c} \bullet{d} è \bullet{g} \bullet{h} ì \bullet{j} -% \bullet{k} \bullet{l} \bullet{n} ò \bullet{r} \bullet{s} -% \bullet{t} ù \bullet{w} \bullet{y} \bullet{z} \strut\\ +% This older version of the Non-Western syntax limits the use of alternate names and cross-references, prevents the use of comma-delimited names, and complicates indexing. It remains for backward compatibility. % -% circumflex & â ĉ \bullet{d} ê ĝ ĥ î ĵ \bullet{k} \bullet{l} \bullet{n} -% ô \bullet{r} ŝ \bullet{t} û ŵ ŷ \bullet{z} \strut\\ +% \begin{SyntaxBox} +% \cmd{\Name}\marg{SNN}\oarg{Alternate} +% \end{SyntaxBox} % -% \rowcolor{nagrey}^^A -% tilde & ã \bullet{c} \bullet{d} \bullet{e} \bullet{g} \Bullet{h} ĩ -% \bullet{j} \bullet{k} \bullet{l} ñ õ \bullet{r} \bullet{s} -% \bullet{t} ũ \bullet{w} \bullet{y} \bullet{z} \strut\\ +% Unlike the comma-delimited \meta{SNN\textbf{,}Affix} pair, it was easy to implement the older syntax with \meta{Alternate}. This syntax created an unacceptable second-tier status, thus, the current syntax replaced it. We show this syntax only for the sake of completeness; we advise not to use it. +% \begin{itemize} +% \item One must \emph{leave empty} the first optional \meta{FNN} argument. % -% diaeresis & ä \bullet{c} \bullet{d} ë \bullet{g} \bullet{h} ï \bullet{j} -% \bullet{k} \bullet{l} \bullet{n} ö \bullet{r} \bullet{s} -% \bullet{t} ü \bullet{w} ÿ \bullet{z} \strut\\ +% \item One must \emph{never use} the comma-delimited argument \meta{Affix}. % -% \rowcolor{nagrey}^^A -% cedilla & \bullet{a} ç \bullet{d} \bullet{e} ģ \bullet{h} \bullet{i} -% \bullet{j} ķ ļ ņ \bullet{o} ŗ ş ţ \bullet{u} \bullet{w} -% \bullet{y} \bullet{z} \strut\\ +% \item These names \emph{always use} \meta{Alternate}. % -% macron & ā \bullet{c} \bullet{d} ē ḡ \bullet{h} ī \bullet{j} -% \bullet{k} \bullet{l} \bullet{n} ō \bullet{r} -% \bullet{s} \bullet{t} ū ǣ ȳ \bullet{z} \strut\\ +% \item \meta{Alternate} acts like \meta{Affix}. This is the only time that the \meta{Alternate} argument affects both name and index patterns (Section~\ref{sec:NamePatterns}). % +% \item These names take the form \meta{SNN Alternate} in the index. +% \end{itemize} +% \begin{Quote} +% \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 +% \begin{Quote} +% After studying in the US during the 1930s, in 1954 Rev. +% \Fukuyama\ddag\ \cmd{\Fukuyama}\cmd{\ddag} published +% \Title{Nihon Fukuin R\=uteru Ky\=okai Shi} (History +% of the Evangelical Lutheran Church in Japan). +% \end{Quote} +% \AltFormatInactive +% \begin{Center} +% \begin{tabular}{ll}\toprule % \rowcolor{nagrey}^^A -% breve & ă \bullet{c} \bullet{d} \bullet{e} ğ \bullet {h} ĭ -% \bullet{j} \bullet{k} \bullet{l} \bullet{n} ŏ \bullet{r} -% \bullet{s} \bullet{t} ŭ \bullet{w} \bullet{y} -% \bullet{z} \strut\\ -% -% dot/dotless & ḃ ċ \bullet{d} ė ġ \bullet{h} ı \bullet{j} \bullet{k} -% \bullet{l} \bullet{n} \bullet{o} \bullet{r} \bullet{s} -% \bullet{t} \bullet{u} \bullet{w} \bullet{y} ż \strut\\ -% +% \ForgetThis\Name{Henry}[VIII]\ddag & +% |\ForgetThis\Name{Henry}[VIII]\ddag|\\ % \rowcolor{nagrey}^^A -% ogonek & ą \bullet{c} \bullet{d} ę \bullet{g} \bullet{h} į \bullet{j} -% \bullet{k} \bullet{l} \bullet{n} ǫ \bullet{r} \bullet{s} -% \bullet{t} ų \bullet{w} \bullet{y} \bullet{z} \strut\\ +% \Name{Henry}[VIII]\ddag & +% |\Name{Henry}[VIII]\ddag|\\ % -% caron & ǎ č ď ě ǧ \bullet{h} ǐ ǰ ǩ ľ ň ǒ ř š ť ǔ \bullet{w} -% \bullet{y} ž \strut\\ +% \ForgetThis\Name{Chiang}[Kai-shek]\ddag & +% |\ForgetThis\Name{Chiang}[Kai-shek]\ddag|\\ +% \Name{Chiang}[Kai-shek]\ddag & +% |\Name{Chiang}[Kai-shek]\ddag|\\ % % \rowcolor{nagrey}^^A -% various & å æ ð đ ij\ ł ŋ ø œ ő ů ű ș ß ț þ \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 -% -% \subsubsection[Compatibility]{Compatibility: Old and New} -% \label{sec:CompatON} -% -% Changes in the way that \texttt{pdflatex} and \texttt{latex} handle Unicode characters since 2018 have made indexing simpler and more intuitive, e.g. -% -% \begin{center} -% \begin{tabular}{rllrll}\toprule +% \Dagb\ddag & |\Dagb\ddag|\\ % \rowcolor{nagrey}^^A -% \bfseries Pre-2018 & & \bfseries Index & -% \bfseries Post-2018 & & \bfseries Index\\ +% \Dagb\ddag & |\Dagb\ddag|\\ % -% ä & \textrightarrow & -% \texttt{\cmd{\IeC\textvisiblespace}\{\cmd{\"a}\}} & -% ä & \textrightarrow & \texttt{ä}\\ +% \CapName\Yosh\ddag & |\CapName\Yosh\ddag|\\ +% \CapName\RevName\LYosh\ddag & |\CapName\RevName\LYosh\ddag|\\ % % \rowcolor{nagrey}^^A -% æ & \textrightarrow & -% \texttt{\cmd{\IeC\textvisiblespace}\{\cmd{\ae\textvisiblespace}\}} & -% æ & \textrightarrow & \texttt{æ}\\\bottomrule -% \end{tabular} -% \end{center} -% -% 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. -% -% There are two ways to test if one is working with a newer or older version of \texttt{pdflatex} or \texttt{latex}. The first involves \LaTeX\ kernel macros in the document preamble to check the format date. We check if the date is later than the first use of the file \texttt{utf8-2018.def}, If that is the case, we can define macros or set Boolean flags, which we can test repeatedly. For example, in the document preamble we could have: -% -% \begin{quote} -% \begin{Verbatim} -% \makeatletter -% \@ifl@t@r\fmtversion{2018/10/05}{\def\nameauthltx{}}{} -% \@ifl@t@r\fmtversion{2018/04/30}{\def\nameauthxp{}}{} -% \makeatother -% \end{Verbatim} -% \end{quote} -% -% The tests above apply to two things that are pertinent to \textsf{nameauth}. The first is the presence of \texttt{utf8-2018.def}. The second involves changes in \textsf{xparse} that could impact \textsf{nameauth}, which we used silently in Section~\ref{sec:ChangeParse}. -% Another test checks directly for the presence of \texttt{utf8-2018.def}: -% -% \begin{quote} -% \begin{Verbatim} -% \IfFileExists{utf8-2018.def} -% {do if exists} -% {do if absent} -% \end{Verbatim} -% \end{quote} -% -% 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. Since 2018, those restrictions have been removed. -% To create a document that can work with old or new versions of \texttt{pdflatex} and \texttt{latex}, one can choose to use macrons or not. In a recent version, one will see macrons in the following names, otherwise, no macron will be present. -% \begin{quote} -% \begin{Verbatim} -% \ifdefined\nameauthltx \Name{Ghazāli} \else \Name{Ghazali}\fi -% -% \IfFileExists{utf8-2018.def}{\Name{Ghazāli}}{\Name{Ghazali}} -% \end{Verbatim} -% \ifdefined\nameauthltx \Name{Ghazāli} \else \Name{Ghazali}\fi -% -% \IfFileExists{utf8-2018.def}{\Name{Ghazāli}}{\Name{Ghazali}} -% \end{quote} -% -% 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{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 2018. -% \item Use of certain text elements, such as \cmd{\dotfill} within -% tables, has become more permissive in recent \TeX\ distributions. -% \item The file \texttt{examples.tex} (see \texttt{README.md}) includes -% additional code snippets that deal with compatibility. -% \item We \cmd{\input} the included snippet \texttt{compat.tex} in -% \texttt{examples.tex} to permit use with different \LaTeX\ engines -% and older \TeX\ distributions. -% \end{itemize}\negbigskip -% -% \begin{InfoBox} -% Users are encouraged to view and modify \texttt{compat.tex} to meet their own needs. -% \end{InfoBox}\negbigskip -% -% \subsubsection[Fragility]{Fragility of Active Unicode} -% -% \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} -% \def\foo#1#2#3!{<#1#2><#3>} -% \begin{tabular}{llll}\toprule +% & |\AltFormatActive| \AltFormatActive\\ % \rowcolor{nagrey}^^A -% \bfseries Arg. & \bfseries Macro & \bfseries Engine & \bfseries Result\\ -% -% |abc| & |\foo abc!| & (any) & \foo abc!\\ -% |{æ}bc| & |\foo {æ}bc!| & (any) & \foo {æ}bc!\\ -% |\ae bc| & |\foo \ae bc!| & (any) & \foo \ae bc!\\ -% +% \ForgetThis\Fukuyama\ddag & |\ForgetThis\Fukuyama\ddag|\\ % \rowcolor{nagrey}^^A -% |æbc| & |\foo æbc!| & \texttt{xelatex} & -% \ifxetex\foo æbc!\else<æb><c>\fi\\ +% \Fukuyama\ddag & |\Fukuyama\ddag|\\ % \rowcolor{nagrey}^^A -% |æbc| & |\foo æbc!| & \texttt{lualatex} & -% \ifluatex\foo æbc!\else<æb><c>\fi\\ +% & |\AltFormatInactive| \AltFormatInactive\\\bottomrule +% \end{tabular} +% \end{Center} % -% |æbc| & |\foo æbc!| & \texttt{pdflatex} & \foo æbc!\\ -% |æbc| & |\foo æbc!| & \texttt{latex} & \foo æbc!\\ -% \bottomrule +% Regardless of its flaws, the obsolete syntax shares name patterns, index tags, name tags, and index entries with the current syntax: +% \begin{Quote} +% \begin{tabular}{@{}lll} +% Obsolete syntax: & \ForgetThis\Name{Henry}[VIII]\ddag & +% \cmd{\ForgetThis}\cmd{\Name\{Henry\}[VIII]}\cmd{\ddag}\\[1ex] +% & \ShowPattern{Henry}[VIII] & \cmd{\ShowPattern\{Henry\}[VIII]}\\[1ex] +% Current syntax: & \Name{Henry, VIII} & \cmd{\Name\{Henry, VIII\}}\\[1ex] +% & \ShowPattern{Henry, VIII} & \cmd{\ShowPattern\{Henry, VIII\}}\\ % \end{tabular} -% \end{center} +% \end{Quote} % -% 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|. +% 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 such variants: +% \item[] \Name*{Henry, VIII}[Tudor]\dotfill \cmd{\Name*\{Henry, VIII\}[Tudor]} % -% 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 \}}. +% \item The proper form for the old syntax is, e.g.: +% \item[] \Name*{Henry}[VIII]\dotfill \cmd{\Name*\{Henry\}[VIII]} % -% 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}). +% \IndexInactive +% \item Next we see malformed Western names: +% \item[] \Name[Henry]{VIII}, \Name[Henry]{VIII}\dotfill \cmd{\Name[Henry]\{VIII\}}\\ +% \Name*[Henry]{VIII}[Tudor], \Name[Henry]{VIII}[Tudor]\dotfill^^A +% \cmd{\Name*[Henry]\{VIII\}[Tudor]} +% \item[] These malformed names have the same index entry\dotfill^^A +% \ShowIdxPageref*[Henry]{VIII} +% \IndexActive +% \end{itemize} +% If users want to receive warnings about this syntax, use the \emph{strictsyntax} option. % % \ReturnLink % -% \begin{Quote}{\Name{Plato}, opening statement in \textit{Cratylus} (c. 388 \textsc{bc})} -% \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.^^A -% \index{philosophers, quotes of\noexpand\string|hyperpage} -% \end{Quote} -% % \newpage % % \StopEventually{^^A % \let\emph\oldemph % \newgeometry{textheight=239mm,left=20mm,right=20mm,nohead} -% \IndexProtect\PrintChanges\newpage\PrintIndex +% \IndexProtect +% \GlossaryPrologue{\section{Change History}^^A +% Minor changes, such as only to documentation and example files, are not shown.} +% \PrintChanges +% \newpage +% \IndexPrologue{\section{Index}^^A +% Page numbers in \emph{italic} refer to the page where the corresponding entry is \textbf{described.} Page numbers that are underlined refer to the \textbf{code line} of the definition. Unmodified roman page numbers are used by names and other entries in the documentation.} +% \PrintIndex % } % \iffalse %<*package> % \fi % +%^^A ----- Paragraph Skip Reset ----- +% \setlength{\parskip}{0pt plus 1pt} +% % \section{Implementation} % -% 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. +% Both the manual and the package code follow a similar organization. % % \subsection{Boolean Flags} % -% The \textsf{nameauth} package is a parser. The flags in this section -% show and change the state of that parser. +% The \textsf{nameauth} package is a name parser and indexer. These flags +% reflect its states. % % \subsubsection{Flow Control} % @@ -10617,7 +10935,7 @@ and version 1.3 or later is part of all distributions of LaTeX version % \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. +% the core name engine from executing until the ``big lock'' is set false. % % \begin{macrocode} \newif\if@nameauth@Lock @@ -10651,14 +10969,20 @@ and version 1.3 or later is part of all distributions of LaTeX version % % \subsubsection[Syntax]{Name Grammar and Syntax} % +% \subsubsection*{\hfil Strict Syntax} +% +% If this flag is true, one will get warnings when using the obsolete syntax. +% +% \begin{macrocode} +\newif\if@nameauth@StrictSyntax +% \end{macrocode} +% % \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 nonwestern name. The second shows the kind of nonwestern -% syntax used. These are not reset after evaluation. +% These flags 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. They are not reset. % % \begin{macrocode} \newif\ifNameauthWestern @@ -10688,8 +11012,7 @@ and version 1.3 or later is part of all distributions of LaTeX version % % \subsubsection*{\hfil Reverse Name Order} % -% These flags govern name reversing. The first is global. -% The second is for individual names. +% These flags govern name reversing, first global, then for individual names. % % \begin{macrocode} \newif\if@nameauth@RevAll @@ -10727,26 +11050,29 @@ and version 1.3 or later is part of all distributions of LaTeX version % % \texttt{\textbackslash if@nameauth@FullName} is true for a long % name form. \texttt{\textbackslash if@nameauth@FirstName} causes only -% Western forenames or nonwestern surnames to be displayed when a shorter -% form is used. The default is to reset both globally on a per-name basis. +% Western forenames or (potentially) Non-Western surnames to be displayed +% when a shorter form is used. % -% \texttt{\textbackslash if@nameauth@ShortSNN} is used with +% \texttt{\textbackslash if@nameauth@ShortSNN} works 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@ForceAffix} toggles the display of +% only the Western affix. +% \texttt{\textbackslash if@nameauth@EastFN} forces the printing +% of Eastern forenames via \cmd{\ForceFN}. % % \begin{macrocode} \newif\if@nameauth@FullName \newif\if@nameauth@FirstName \newif\if@nameauth@AltAKA \newif\if@nameauth@ShortSNN +\newif\if@nameauth@ForceAffix \newif\if@nameauth@EastFN % \end{macrocode} % % \subsubsection{Debugging} % % When used with the index debugging macros, show complete index entries -% if true, otherwise show simple entries. +% in the text if true, otherwise show simple entries. % % \begin{macrocode} \newif\if@nameauth@LongIdxDebug @@ -10756,9 +11082,9 @@ and version 1.3 or later is part of all distributions of LaTeX version % % \subsubsection*{\hfil Toggle Indexing} % -% The indexing flags permit or prevent indexing and tags. +% The indexing flags permit or prevent name indexing and tags. % \cmd{\IndexActive} and \cmd{\IndexInctive} or the \texttt{index} and -% \texttt{noindex} options toggle the first flag; \cmd{\SkipIndex} +% \texttt{noindex} options toggle the first flag and \cmd{\SkipIndex} % toggles the second. % % \begin{macrocode} @@ -10774,7 +11100,7 @@ and version 1.3 or later is part of all distributions of LaTeX version \newif\if@nameauth@Pretag % \end{macrocode} % -% \subsubsection*{\hfil Verbose Warnings} +% \subsubsection*{\hfil Verbose Index Warnings} % % Control the number of warnings concerning the index; default is terse. % @@ -10782,13 +11108,8 @@ and version 1.3 or later is part of all distributions of LaTeX version \newif\if@nameauth@Verbose % \end{macrocode} % -% \subsubsection*{\hfil Cross-References} +% \subsubsection*{\hfil Index 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. % @@ -10796,7 +11117,7 @@ and version 1.3 or later is part of all distributions of LaTeX version \newif\if@nameauth@SeeAlso % \end{macrocode} % -% \subsubsection[Formatting]{Formatting and Name Control Sequences} +% \subsubsection[Formatting]{Formatting and Name Patterns} % % \subsubsection*{\hfil Choose Formatting System} % @@ -10851,8 +11172,8 @@ and version 1.3 or later is part of all distributions of LaTeX version % % \subsubsection*{\hfil Creating and Destroying Name Patterns} % -% Restrict the creation and destruction of name patters to the current -% name system if true. +% Restrict creation and destruction of name patters to the current +% name system if true. Otherwise, work with both systems. % % \begin{macrocode} \newif\if@nameauth@LocalNames @@ -10862,7 +11183,7 @@ and version 1.3 or later is part of all distributions of LaTeX version % % \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. +% macros to have global scope. % % \begin{macrocode} \newif\if@nameauth@GlobalScope @@ -10883,12 +11204,11 @@ and version 1.3 or later is part of all distributions of LaTeX version % \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 +% These flags are used only for backward compatibility. The first +% determines how per-name flags are reset. The second affects the % behavior of \cmd{\JustIndex}. The third toggles whether or not the % name argument token registers are set globally. The fourth toggles the -% inclusion of \textsf{xargs} and \textsf{suffix} for legacy cases where -% user customizations were made. +% inclusion of \textsf{xargs} and \textsf{suffix} for legacy cases. % % \begin{macrocode} \newif\if@nameauth@OldReset @@ -10902,22 +11222,14 @@ and version 1.3 or later is part of all distributions of LaTeX version % % \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. +% arguments passed to macros that accept naming arguments. % % \begin{macrocode} \newtoks\@nameauth@toksa \newtoks\@nameauth@toksb \newtoks\@nameauth@toksc % \end{macrocode} -% \end{macro} -% \end{macro} -% \end{macro} % These three token registers contain the current values of the name % arguments in each line of the \texttt{nameauth} environment, thus, \texttt{@nameauth@e} for that environment. % @@ -10930,7 +11242,7 @@ and version 1.3 or later is part of all distributions of LaTeX version % \subsubsection{Hooks} % % \begin{macro}{\NamesFormat} -% Post-process ``first'' instance of final complete name form in text. +% Used for ``first'' instances of names in main-matter text. % See Sections~\ref{sec:Formatting} and~\ref{sec:ComplexHooks}. Called when % both |\@nameauth@MainFormat| and |\@nameauth@FirstFormat| are true. % @@ -10941,10 +11253,9 @@ and version 1.3 or later is part of all distributions of LaTeX version % % \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} +% Used for later instances of names 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. +% and |\@nameauth@FirstFormat| is false. % % \begin{macrocode} \newcommand*\MainNameHook{} @@ -10953,8 +11264,8 @@ and version 1.3 or later is part of all distributions of LaTeX version % % \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 +% Used for ``first'' instances of names in front-matter text. This +% formatting hook is called when |\@nameauth@MainFormat| is false % and |\@nameauth@FirstFormat| is true. % % \begin{macrocode} @@ -10964,8 +11275,8 @@ and version 1.3 or later is part of all distributions of LaTeX version % % \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 +% Used for subsequent instances of names in front-matter text. +% This hook is called when |\@nameauth@MainFormat| is false % and |\@nameauth@FirstFormat| is false. % % \begin{macrocode} @@ -10973,13 +11284,12 @@ and version 1.3 or later is part of all distributions of LaTeX version % \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}. +% \noindent The following are customization points for +% the core name engine (Section~\ref{sec:FullCustomize}). % % \begin{macro}{\NameauthName} % \changes{2.2}{2015/12/01}{Added} -% Hook called when no special name modification is made. +% Hook called when no special name modification is made. % % \begin{macrocode} \newcommand*\NameauthName{\@nameauth@Name} @@ -11019,9 +11329,7 @@ and version 1.3 or later is part of all distributions of LaTeX version % % \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 tag -% (Section~\ref{sec:DataTagHooks}). We preset it to an empty value. With +% The current name pattern is stored here. With % every call to a macro that takes name arguments % (Section~\ref{sec:NameArgMacros}), this hook is updated. % @@ -11036,7 +11344,7 @@ and version 1.3 or later is part of all distributions of LaTeX version % \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{=}|. +% index sorting. % % \begin{macrocode} \def\@nameauth@Actual{@} @@ -11045,9 +11353,9 @@ and version 1.3 or later is part of all distributions of LaTeX version % % \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}. +% This makes an index xref into an ``exclusion'': any name pattern +% ending in \texttt{!PN} that expands to this value. +% See \cmd{\ExcludeName} below. % % \begin{macrocode} \newcommand*\@nameauth@Exclude{!} @@ -11067,7 +11375,12 @@ and version 1.3 or later is part of all distributions of LaTeX version % % \subsubsection[Syntax]{Name Grammar and Syntax} % -% Change the way that names are displayed, specifically with respect to their syntactic forms. +% Show warnings when using the obsolete syntax. +% +% \begin{macrocode} +\DeclareOption{strictsyntax}{\@nameauth@StrictSyntaxtrue} +% \end{macrocode} +% Change the way that names are displayed with respect to their syntactic forms. % % \begin{macrocode} \DeclareOption{nocomma}{\@nameauth@AlwaysCommafalse} @@ -11096,7 +11409,7 @@ and version 1.3 or later is part of all distributions of LaTeX version % % \subsubsection{Formatting} % -% Start off in a different naming regime or change formatting behavior in general or for \cmd{\AKA}. +% Determine the name system or change formatting behavior. % % \begin{macrocode} \DeclareOption{mainmatter}{\@nameauth@MainFormattrue} @@ -11108,10 +11421,10 @@ and version 1.3 or later is part of all distributions of LaTeX version % \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}} +\DeclareOption{noformat}{\providecommand*\NamesFormat{}} +\DeclareOption{smallcaps}{\providecommand*\NamesFormat{\scshape}} +\DeclareOption{italic}{\providecommand*\NamesFormat{\itshape}} +\DeclareOption{boldface}{\providecommand*\NamesFormat{\bfseries}} % \end{macrocode} % % \subsubsection[Alternate Format]{Alternate Formatting} @@ -11171,20 +11484,20 @@ and version 1.3 or later is part of all distributions of LaTeX version % % \newpage % -% \addtocontents{toc}{\protect\goodbreak} % \subsection{Internal Macros} % \label{sec:InternalMacros} % % \subsubsection{Fundamental Macros} % -% The following macros are the most essential to the concept of ``name''. +% The following macros are the most essential to the concept of names. % -% \subsubsection*{\hfil Name Control Sequence: Who Am I?} +% \subsubsection*{\hfil Name Patterns: 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}. +% string to make a control sequence for a name. Testing for the existence +% and providing for macros based on that control sequence is the core of +% \textsf{nameauth}. % % \begin{macrocode} \newcommand*\@nameauth@Clean[1] @@ -11194,7 +11507,7 @@ 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 +% Unless we are in \cmd{\AKA}, create a name pattern % in the core name engine. % % \begin{macrocode} @@ -11210,9 +11523,7 @@ and version 1.3 or later is part of all distributions of LaTeX version % \subsubsection*{\hfil Parsing: Root and Suffix} % % \begin{macro}{\@nameauth@Root} -% 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. +% Return everything before a comma in \meta{SNN}, using the helper macro below. % % \begin{macrocode} \newcommand*\@nameauth@Root[1]{\@nameauth@@Root#1,\\} @@ -11233,9 +11544,8 @@ 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} -% 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. +% Return everything before a vertical bar (\texttt{\textbar}) +% in an index tag, using the helper below. % % \begin{macrocode} \newcommand*\@nameauth@TrimTag[1]{\@nameauth@@TrimTag#1|\\} @@ -11253,10 +11563,8 @@ 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} -% 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. +% Return only the affix in an \meta{SNN\textbf{,}Affix} pair, +% using the helper macro below. % % \begin{macrocode} \newcommand*\@nameauth@Suffix[1]{\@nameauth@@Suffix#1,,\\} @@ -11269,7 +11577,6 @@ and version 1.3 or later is part of all distributions of LaTeX version % \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. -% Used to print the suffix. % % \begin{macrocode} \def\@nameauth@@Suffix#1,#2,#3\\{% @@ -11280,8 +11587,7 @@ 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} -% These two macros test the suffix for a leading active Unicode -% character. We use this for capitalization to avoid errors. +% Test the suffix for a leading active Unicode character. % % \begin{macrocode} \newcommand*\@nameauth@GetSuff[1]{\@nameauth@@GetSuff#1,,\\} @@ -11304,10 +11610,8 @@ and version 1.3 or later is part of all distributions of LaTeX version % \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 (using \texttt{pdflatex} and -% \texttt{latex}). Otherwise we use native Unicode. +% active Unicode character, using an \DE{Esszett} (\texttt{ß}) +% as the control. Used only with \textsf{inputenc}\,/\,\textsf{fontenc} in the next two macros below. % % \begin{macrocode} \newcommand*\@nameauth@TestToks[1] @@ -11330,10 +11634,9 @@ 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 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}. +% Fully test what method to use when capitalizing a letter, whether +% native Unicode (\texttt{xelatex} or \texttt{lualatex} via +% \cmd{\Umathchar}) or \textsf{inputenc}\,/\,\textsf{fontenc}. % % \begin{macrocode} \newcommand*\@nameauth@UTFtest[1] @@ -11360,9 +11663,8 @@ 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 +% This test is like the one above, but for a suffix, which requires +% more work to function properly. Moreover, we only use this when % the regular suffix macro is not \cmd{\@empty}. % % \begin{macrocode} @@ -11371,18 +11673,14 @@ and version 1.3 or later is part of all distributions of LaTeX version \expandafter\def\expandafter\@nameauth@testarg% \expandafter{\@nameauth@GetSuff{#1}}% % \end{macrocode} -% -% \newpage\noindent -% -% This following token register assignment looks weird, but it is -% how we get a test that works. +% This token register assignment looks weird, but it 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. +% \newpage +% \noindent Assign the token register value to a macro to do the test. % % \begin{macrocode} \expandafter\def\expandafter\@nameauth@test@rg% @@ -11407,10 +11705,8 @@ 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} -% 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}. +% \changes{3.2}{2017/03/22}{Not for UTF in \textsf{inputenc}} +% Capitalize the first letter of the argument, using the helper below. % % \begin{macrocode} \newcommand*\@nameauth@Cap[1]{\@nameauth@C@p#1\\} @@ -11431,9 +11727,7 @@ 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} -% These two macros cap the first active Unicode letter when one -% is using \textsf{inputenc} (an argument ``twice as wide'' as -% normal, native Unicode). +% Capitalize the first active Unicode letter when using \textsf{inputenc}. % % \begin{macrocode} \newcommand*\@nameauth@CapUTF[1]{\@nameauth@C@pUTF#1\\} @@ -11454,10 +11748,9 @@ 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 +% Capitalize the first letter of all name arguments, when not % in alternate formatting. We only use this macro in the local scope -% of \cmd{\@nameauth@Parse}. Uses the foregoing macros. +% of \cmd{\@nameauth@Parse}. % % \begin{macrocode} \newcommand*\@nameauth@CapArgs[3] @@ -11469,7 +11762,7 @@ and version 1.3 or later is part of all distributions of LaTeX version \let\csuffb\suffb% \let\cargc\argc% % \end{macrocode} -% We test \meta{FNN} for active, non-native Unicode +% We test \meta{FNN} for active Unicode % characters, then cap the first letter. % % \begin{macrocode} @@ -11477,14 +11770,15 @@ and version 1.3 or later is part of all distributions of LaTeX version \def\test{#1}% \expandafter\@nameauth@UTFtest\expandafter{\test}% % \end{macrocode} -% Capitalize the first active Unicode character. +% Capitalize the first active Unicode character +% when using \textsf{inputenc}. % % \begin{macrocode} \if@nameauth@UTF \expandafter\def\expandafter\carga\expandafter{% \expandafter\@nameauth@CapUTF\expandafter{\test}}% % \end{macrocode} -% Capitalize the first native Unicode character (not active). +% Capitalize the first native Unicode character. % % \begin{macrocode} \else @@ -11493,8 +11787,8 @@ and version 1.3 or later is part of all distributions of LaTeX version \fi \fi % \end{macrocode} -% We test \meta{SNN} 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}% @@ -11507,7 +11801,7 @@ and version 1.3 or later is part of all distributions of LaTeX version \expandafter\def\expandafter\crootb\expandafter{% \expandafter\@nameauth@CapUTF\expandafter{\rootb}}% % \end{macrocode} -% Capitalize the first native character (not active). +% Capitalize the first native Unicode character. % % \begin{macrocode} \else @@ -11515,8 +11809,8 @@ and version 1.3 or later is part of all distributions of LaTeX version \expandafter\@nameauth@Cap\expandafter{\rootb}}% \fi % \end{macrocode} -% We test \meta{Affix} 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 @@ -11532,7 +11826,7 @@ and version 1.3 or later is part of all distributions of LaTeX version \expandafter\def\expandafter\csuffb\expandafter{% \expandafter\@nameauth@CapUTF\expandafter{\test}}% % \end{macrocode} -% Capitalize the first native Unicode character (not active). +% Capitalize the first native Unicode character. % % \begin{macrocode} \else @@ -11542,8 +11836,8 @@ and version 1.3 or later is part of all distributions of LaTeX version \fi \fi % \end{macrocode} -% We test \meta{Alternate} 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 @@ -11557,7 +11851,8 @@ and version 1.3 or later is part of all distributions of LaTeX version \expandafter\def\expandafter\cargc\expandafter{% \expandafter\@nameauth@CapUTF\expandafter{\test}}% % \end{macrocode} -% Capitalize the first native Unicode character (not active). +% \newpage +% \noindent Capitalize the first native Unicode character. % % \begin{macrocode} \else @@ -11566,9 +11861,8 @@ and version 1.3 or later is part of all distributions of LaTeX version \fi \fi % \end{macrocode} -% 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. +% Let all the local name elements have caps. +% We do not know which ones will be used. % % \begin{macrocode} \let\arga\carga% @@ -11604,7 +11898,7 @@ and version 1.3 or later is part of all distributions of LaTeX version % 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. +% \cmd{\@nameauth@CheckDot}. % % \begin{macrocode} \def\@nameauth@TestPunct##1% @@ -11623,7 +11917,7 @@ and version 1.3 or later is part of all distributions of LaTeX version % \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 +% character of the input is a full stop. We evaluate the lookahead % \cmd{\@nameauth@token} while keeping it on the list of input tokens. % % \begin{macrocode} @@ -11633,8 +11927,7 @@ and version 1.3 or later is part of all distributions of LaTeX version % \end{macro} % % \begin{macro}{\@nameauth@EvalDot} -% If \cmd{\@nameauth@token}, the lookahead, is a full stop, we gobble -% the next token because it is that full stop. +% If \cmd{\@nameauth@token}, the lookahead, is a full stop, we gobble it. % % \begin{macrocode} \newcommand*\@nameauth@EvalDot @@ -11650,10 +11943,9 @@ and version 1.3 or later is part of all distributions of LaTeX version % % \begin{macro}{\@nameauth@AddPunct} % \changes{3.5}{2020/11/23}{Added} -% 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}. +% Here we make spaces between name elements in the text break or not, +% and decide whether to add commas or not, depending on the name type. +% We only use this macro in \cmd{\@nameauth@Parse}. % % \begin{macrocode} \newcommand*\@nameauth@AddPunct @@ -11670,16 +11962,12 @@ and version 1.3 or later is part of all distributions of LaTeX version \if@nameauth@NBSP \edef\Space{\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 use commas differently from all other names, +% so we only use the following logic if \meta{FNN} is not empty. % % \begin{macrocode} \unless\ifx\arga\@empty - \if@nameauth@AlwaysComma - \def\Space{, }% - \if@nameauth@NBSP\edef\Space{,\nobreakspace}\fi - \fi + \if@nameauth@AlwaysComma\@nameauth@ShowCommatrue\fi \if@nameauth@ShowComma \def\Space{, }% \if@nameauth@NBSP\edef\Space{,\nobreakspace}\fi @@ -11695,9 +11983,11 @@ and version 1.3 or later is part of all distributions of LaTeX version % \end{macro} % % \subsubsection*{\hfil Parsing: Name Argument Loading} +% \label{page:NameauthLoadArgs} % % \begin{macro}{\@nameauth@LoadArgs} % \changes{3.5}{2020/11/23}{Added} +% \changes{4.1}{2025/02/04}{Clean name patterns via \cmd{\xdef}, name arg tokens saved here} % Assign name arguments to internal macros to determine name syntax. % This is used in all macros that take name arguments. % @@ -11714,12 +12004,29 @@ and version 1.3 or later is part of all distributions of LaTeX version \protected@edef\@nameauth@SB{\@nameauth@Suffix{#2}}% \protected@edef\@nameauth@C{\trim@spaces{#3}}% % \end{macrocode} -% Make (usually) unique control sequence values from the name arguments. +% Make (usually) unique control sequence values from the name arguments +% for all possible name forms. We use \cmd{\@nameauth@Choice} to pick +% the name pattern that we want. Using \cmd{\edef} ensures that these +% macros are just the detokenized arguments. % % \begin{macrocode} - \def\@nameauth@csb{\@nameauth@Clean{#2}}% - \def\@nameauth@csbc{\@nameauth@Clean{#2,#3}}% - \def\@nameauth@csab{\@nameauth@Clean{#1!#2}}% + \xdef\@nameauth@csb{\@nameauth@Clean{#2}}% + \xdef\@nameauth@csbc{\@nameauth@Clean{#2,#3}}% + \xdef\@nameauth@csab{\@nameauth@Clean{#1!#2}}% +% \end{macrocode} +% \newpage +% \noindent Make token register copies of the current name arguments. +% +% \begin{macrocode} + \if@nameauth@OldToks + \@nameauth@toksa\expandafter{#1}% + \@nameauth@toksb\expandafter{#2}% + \@nameauth@toksc\expandafter{#3}% + \else + \global\@nameauth@toksa\expandafter{#1}% + \global\@nameauth@toksb\expandafter{#2}% + \global\@nameauth@toksc\expandafter{#3}% + \fi } % \end{macrocode} % \end{macro} @@ -11728,13 +12035,13 @@ and version 1.3 or later is part of all distributions of LaTeX version % % \begin{macro}{\@nameauth@Choice} % \changes{3.5}{2020/11/23}{Added} -% \changes{3.7}{2023/02/03}{Access name pattern and type; redesigned to -% optimize many macros} +% \changes{3.7}{2023/02/03}{Redesigned to optimize many macros} +% \changes{4.1}{2025/02/04}{Globally update name pattern and name type info} % 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. +% pattern and type of name. % % \begin{macrocode} \newcommand\@nameauth@Choice[3] @@ -11742,29 +12049,33 @@ and version 1.3 or later is part of all distributions of LaTeX version \ifx\@nameauth@A\@empty \ifx\@nameauth@C\@empty % \end{macrocode} -% This path is for nonwestern names. The \texttt{\#1} argument is +% This path is for Non-Western names. The \texttt{\#1} argument is % used both here and below when \cmd{\@nameauth@SB} is present. The % \texttt{\#1} path always corresponds to the present syntax. % Thus, when printing names in the text, the \texttt{\#1} argument % must test both \cmd{\@nameauth@C} and \cmd{\@nameauth@SB}, replacing -% the latter with former ifit exists. With indexing and other macros, +% the latter with former if it exists. With indexing and other macros, % one ignores \cmd{\@nameauth@C}. % % \begin{macrocode} - \let\NameauthPattern\@nameauth@csb% - \NameauthWesternfalse \NameauthObsoletefalse% + \global\let\NameauthPattern\@nameauth@csb% + \global\NameauthWesternfalse% + \global\NameauthObsoletefalse% #1% \else \ifx\@nameauth@SB\@empty % \end{macrocode} -% The \texttt{\#2} argument is only for nonwestern names that use +% The \texttt{\#2} argument is only for Non-Western names that use % the obsolete syntax. Here \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% + \if@nameauth@StrictSyntax + \PackageWarning{nameauth}{Use of obsolete syntax}\fi + \global\let\NameauthPattern\@nameauth@csbc% + \global\NameauthWesternfalse% + \global\NameauthObsoletetrue% #2% \else % \end{macrocode} @@ -11774,24 +12085,26 @@ and version 1.3 or later is part of all distributions of LaTeX version % syntax with a potential name swap. % % \begin{macrocode} - \let\NameauthPattern\@nameauth@csb% - \NameauthWesternfalse \NameauthObsoletefalse% + \global\let\NameauthPattern\@nameauth@csb% + \global\NameauthWesternfalse% + \global\NameauthObsoletefalse% #1% \fi \fi \else % \end{macrocode} -% This decision path is for Western names. When printing +% This path is for Western names. When printing % names in the text, somewhere in the \texttt{\#3} % argument one must test for \cmd{\@nameauth@C} and swap it for -% \cmd{\@nameauth@A}. One also must check for and handle -% \cmd{\@nameauth@SB}. Otherwise, for indexing and control sequences, -% one ignores \cmd{\@nameauth@C} in this path and handles -% \cmd{\@nameauth@SB} appropriately. +% \cmd{\@nameauth@A}. Also check for and handle +% \cmd{\@nameauth@SB}. Otherwise, for indexing and patterns, +% ignore \cmd{\@nameauth@C} in this path and handle +% \cmd{\@nameauth@SB} appropriately. % % \begin{macrocode} - \let\NameauthPattern\@nameauth@csab% - \NameauthWesterntrue \NameauthObsoletefalse% + \global\let\NameauthPattern\@nameauth@csab% + \global\NameauthWesterntrue% + \global\NameauthObsoletefalse% #3% \fi } @@ -11800,39 +12113,35 @@ 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} +% \changes{4.1}{2025/02/04}{Add global \cmd{\ForceAffix} flag reset} % 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}. +% output in the text. Other places where flags are reset are for +% special cases. % % \begin{macrocode} \newcommand*\@nameauth@Flags {% + \global\@nameauth@ForceAffixfalse% \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 +% of \cmd{\ForgetThis} and \cmd{\SubvertThis} pass through \cmd{\AKA} +% and \cmd{\AKA*}. We reset \texttt{\textbackslash % if@nameauth@AltAKA} here due to macros like \cmd{\PName}. % % \begin{macrocode} \if@nameauth@InAKA\@nameauth@AltAKAfalse\fi \@nameauth@SkipIndexfalse% \if@nameauth@InName - \@nameauth@Forgetfalse% - \@nameauth@Subvertfalse% + \@nameauth@Forgetfalse \@nameauth@Subvertfalse% \fi - \@nameauth@NBSPfalse% - \@nameauth@NBSPXfalse% - \@nameauth@DoCapsfalse% - \@nameauth@Accentfalse% - \@nameauth@AllThisfalse% - \@nameauth@ShowCommafalse% - \@nameauth@NoCommafalse% - \@nameauth@RevThisfalse% + \@nameauth@NBSPfalse \@nameauth@NBSPXfalse% + \@nameauth@DoCapsfalse \@nameauth@Accentfalse% + \@nameauth@AllThisfalse \@nameauth@ShowCommafalse% + \@nameauth@NoCommafalse \@nameauth@RevThisfalse% \@nameauth@RevThisCommafalse% - \@nameauth@ShortSNNfalse% - \@nameauth@EastFNfalse% + \@nameauth@ShortSNNfalse \@nameauth@EastFNfalse% \else % \end{macrocode} % The current way that the flags are reset makes them both global @@ -11842,24 +12151,20 @@ and version 1.3 or later is part of all distributions of LaTeX version % \begin{macrocode} \if@nameauth@InAKA\global\@nameauth@AltAKAfalse\fi \global\@nameauth@SkipIndexfalse% - \global\@nameauth@Forgetfalse% - \global\@nameauth@Subvertfalse% - \global\@nameauth@NBSPfalse% - \global\@nameauth@NBSPXfalse% - \global\@nameauth@DoCapsfalse% - \global\@nameauth@Accentfalse% - \global\@nameauth@AllThisfalse% - \global\@nameauth@ShowCommafalse% - \global\@nameauth@NoCommafalse% - \global\@nameauth@RevThisfalse% + \global\@nameauth@Forgetfalse \global\@nameauth@Subvertfalse% + \global\@nameauth@NBSPfalse \global\@nameauth@NBSPXfalse% + \global\@nameauth@DoCapsfalse \global\@nameauth@Accentfalse% + \global\@nameauth@AllThisfalse \global\@nameauth@ShowCommafalse% + \global\@nameauth@NoCommafalse \global\@nameauth@RevThisfalse% \global\@nameauth@RevThisCommafalse% - \global\@nameauth@ShortSNNfalse% - \global\@nameauth@EastFNfalse% + \global\@nameauth@ShortSNNfalse \global\@nameauth@EastFNfalse% \fi } % \end{macrocode} % \end{macro} % +% \newpage +% % \subsubsection[Errors/Debugging]{Error Detection and Debugging} % % \begin{macro}{\@nameauth@Error} @@ -11867,8 +12172,8 @@ and version 1.3 or later is part of all distributions of LaTeX version % \changes{3.01}{2016/10/27}{Fixed} % \changes{3.5}{2020/11/23}{Fix namespace} % 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. +% when a required name argument is empty, expands to empty, or +% has an empty root in a root/suffix pair. % % \begin{macrocode} \newcommand*\@nameauth@Error[2] @@ -11889,8 +12194,8 @@ and version 1.3 or later is part of all distributions of LaTeX version % % \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.5}{2020/11/23}{Fix name space, redefine hook +% to print in text} % \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 @@ -11948,6 +12253,7 @@ and version 1.3 or later is part of all distributions of LaTeX version % \end{macro} % % \subsubsection{Core Name Engine} +% \label{sec:CoreName} % % \subsubsection*{\hfil Argument Processing Layer} % @@ -11972,10 +12278,9 @@ and version 1.3 or later is part of all distributions of LaTeX version \NewDocumentCommand{\@nameauth@Name}{O{} m O{}} {% % \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 @@ -12029,7 +12334,8 @@ 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. +% \newpage +% \noindent Reset all the ``per name'' Boolean values after printing a name. % The default is global. % % \begin{macrocode} @@ -12057,8 +12363,9 @@ and version 1.3 or later is part of all distributions of LaTeX version % use \cmd{\MakeUppercase}} % \changes{3.5}{2020/11/23}{Global token regs, optimize logic, % fix namespace} +% \changes{4.1}{2025/02/04}{Name arg tokens saved elsewhere for consistency} % Parse and print a name in the text. The final required argument tells -% us which naming system we are in (Section~\ref{sec:NamePatterns}). +% us which name 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. % @@ -12068,20 +12375,6 @@ and version 1.3 or later is part of all distributions of LaTeX version \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. -% -% \begin{macrocode} - \if@nameauth@OldToks - \@nameauth@toksa\expandafter{#1}% - \@nameauth@toksb\expandafter{#2}% - \@nameauth@toksc\expandafter{#3}% - \else - \global\@nameauth@toksa\expandafter{#1}% - \global\@nameauth@toksb\expandafter{#2}% - \global\@nameauth@toksc\expandafter{#3}% - \fi -% \end{macrocode} % If global caps. reversing, and commas are true, % set the per-name flags true. % @@ -12090,8 +12383,8 @@ and version 1.3 or later is part of all distributions of LaTeX version \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 +% Enter a local scope where we can use simple macros +% without worry about name space collisions. We process % and load the arguments into the appropriate macros. % % \begin{macrocode} @@ -12099,8 +12392,7 @@ and version 1.3 or later is part of all distributions of LaTeX version \def\@nameauth@InParser{}% \@nameauth@LoadArgs{#1}{#2}{#3}% % \end{macrocode} -% Copy the protected control sequences to local, -% unprotected ones. +% Let the protected control sequences to local ones. % % \begin{macrocode} \let\arga\@nameauth@A% @@ -12130,15 +12422,15 @@ and version 1.3 or later is part of all distributions of LaTeX version % \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 optional arguments. +% We attach ``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 % \end{macrocode} -% Nonwestern names, current syntax. +% Non-Western names, current syntax. % We test \cmd{\argc} and \cmd{\suffb} as needed. % % \begin{macrocode} @@ -12152,7 +12444,7 @@ and version 1.3 or later is part of all distributions of LaTeX version \@nameauth@MakeCS{\@nameauth@csb#4}% }% % \end{macrocode} -% Nonwestern names, obsolete syntax. Here \cmd{\argc} is significant. +% Non-Western names, obsolete syntax. Here \cmd{\argc} is significant. % % \begin{macrocode} {% @@ -12163,7 +12455,8 @@ 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}. +% account for \cmd{\suffb}. We allow \cmd{\ForceAffix} to +% work only if if no affix exists % % \begin{macrocode} {% @@ -12172,7 +12465,9 @@ and version 1.3 or later is part of all distributions of LaTeX version \else \let\FNN\argc% \fi - \unless\ifx\suffb\@empty + \ifx\suffb\@empty + \@nameauth@ForceAffixfalse% + \else \def\SNN{\rootb\Space\suffb}% \if@nameauth@ShortSNN \let\SNN\rootb% @@ -12206,17 +12501,29 @@ and version 1.3 or later is part of all distributions of LaTeX version % \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 nonwestern names. We inherit macros from +% 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] {% \ifdefined\@nameauth@InParser +% \end{macrocode} +% Toggle flags based on the name arguments. +% +% \begin{macrocode} \@nameauth@Form{#1}% +% \end{macrocode} +% Send a mononym to the hook dispatcher. +% +% \begin{macrocode} \ifx\FNN\@empty \@nameauth@Hook{\SNN}% \else +% \end{macrocode} +% Send a full name or reversed full name to the hook dispatcher. +% +% \begin{macrocode} \if@nameauth@FullName \if@nameauth@RevThis \@nameauth@Hook{\FNN\Space\SNN}% @@ -12224,6 +12531,10 @@ and version 1.3 or later is part of all distributions of LaTeX version \@nameauth@Hook{\SNN\Space\FNN}% \fi \else +% \end{macrocode} +% Send a partial name to the hook dispatcher. +% +% \begin{macrocode} \if@nameauth@FirstName \if@nameauth@EastFN \@nameauth@Hook{\FNN}% @@ -12244,6 +12555,7 @@ and version 1.3 or later is part of all distributions of LaTeX version % \changes{3.0}{2016/10/26}{Added} % \changes{3.3}{2020/02/20}{global flag reset} % \changes{3.7}{2023/02/03}{always define local macros} +% \changes{4.1}{2025/02/04}{Support affix-only output} % 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. @@ -12252,8 +12564,18 @@ and version 1.3 or later is part of all distributions of LaTeX version \newcommand*\@nameauth@West[1] {% \ifdefined\@nameauth@InParser +% \end{macrocode} +% Toggle flags based on the name arguments. +% +% \begin{macrocode} \@nameauth@Form{#1}% \edef\RevSpace{,\SpaceW}% +% \end{macrocode} +% \newpage +% \noindent Send a reversed full name, reversed full name with commas, +% or a full name to the hook dispatcher. +% +% \begin{macrocode} \if@nameauth@FullName \if@nameauth@RevThis \@nameauth@Hook{\SNN\SpaceW\FNN}% @@ -12265,10 +12587,22 @@ and version 1.3 or later is part of all distributions of LaTeX version \fi \fi \else - \if@nameauth@FirstName - \@nameauth@Hook{\FNN}% +% \end{macrocode} +% Send only an affix to the hook dispatcher. +% +% \begin{macrocode} + \if@nameauth@ForceAffix + \@nameauth@Hook{\suffb}% \else - \@nameauth@Hook{\rootb}% +% \end{macrocode} +% Send a partial name to the hook dispatcher. +% +% \begin{macrocode} + \if@nameauth@FirstName + \@nameauth@Hook{\FNN}% + \else + \@nameauth@Hook{\rootb}% + \fi \fi \fi \fi @@ -12338,7 +12672,8 @@ and version 1.3 or later is part of all distributions of LaTeX version % \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} +% \changes{3.5}{2020/11/23}{Fix namespace} +% \changes{4.1}{2025/02/04}{Ensure localized hook flag} % Boolean flags control which hook is called (first/subsequent use, % name type). We only use this macro in the local scope of the parser. % @@ -12353,7 +12688,6 @@ and version 1.3 or later is part of all distributions of LaTeX version % if@nameauth@InHook} will reset outside of the local scope in % \cmd{\@nameauth@Parse}. % \begin{macrocode} - \@nameauth@InHooktrue% \protected@edef\test{#1}% \expandafter\@nameauth@TestDot\expandafter{\test}% \if@nameauth@MainFormat @@ -12362,9 +12696,9 @@ and version 1.3 or later is part of all distributions of LaTeX version % % \begin{macrocode} \if@nameauth@FirstFormat - \bgroup\NamesFormat{#1}\egroup% + \bgroup\@nameauth@InHooktrue\NamesFormat{#1}\egroup% \else - \bgroup\MainNameHook{#1}\egroup% + \bgroup\@nameauth@InHooktrue\MainNameHook{#1}\egroup% \fi \else % \end{macrocode} @@ -12372,9 +12706,9 @@ and version 1.3 or later is part of all distributions of LaTeX version % % \begin{macrocode} \if@nameauth@FirstFormat - \bgroup\FrontNamesFormat{#1}\egroup% + \bgroup\@nameauth@InHooktrue\FrontNamesFormat{#1}\egroup% \else - \bgroup\FrontNameHook{#1}\egroup% + \bgroup\@nameauth@InHooktrue\FrontNameHook{#1}\egroup% \fi \fi \fi @@ -12382,6 +12716,8 @@ and version 1.3 or later is part of all distributions of LaTeX version % \end{macrocode} % \end{macro} % +% \newpage +% % \subsubsection{Indexing} % % \begin{macro}{\@nameauth@Index} @@ -12389,65 +12725,83 @@ and version 1.3 or later is part of all distributions of LaTeX version % \changes{2.0}{2015/11/11}{New tagging} % \changes{3.3}{2020/02/20}{Support hyperref} % \changes{3.5}{2020/11/23}{Fix namespace} +% \changes{4.1}{2025/02/04}{Fix sub-entry xrefs} % 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] +\newcommand*\@nameauth@Index[4][\@empty] {% \if@nameauth@DoIndex + \edef\@nameauth@XrefType{#1}% % \end{macrocode} +% If a cross-reference will be created, its type is in the first +% argument. We put that argument into a macro to evaluate it. % 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}% + \ifcsname#2!TAG\endcsname + \protected@edef\@nameauth@Tag{\csname#2!TAG\endcsname}% \expandafter\def\expandafter\@nameauth@ShortTag\expandafter{% \expandafter\@nameauth@TrimTag\expandafter{\@nameauth@Tag}}% % \end{macrocode} -% Create entries with a sorting tag and an info tag. +% Set up either a page entry or an xref with both a sorting +% tag and an info tag. % % \begin{macrocode} - \ifcsname#1!PRE\endcsname - \protected@edef\@nameauth@Pre{\csname#1!PRE\endcsname}% - \if@nameauth@Xref + \ifcsname#2!PRE\endcsname + \protected@edef\@nameauth@Pre{\csname#2!PRE\endcsname}% + \ifx\@nameauth@XrefType\@empty \protected@edef\@nameauth@IdxEntry - {\@nameauth@Pre#2\@nameauth@ShortTag}% + {\@nameauth@Pre#3\@nameauth@Tag}% \else \protected@edef\@nameauth@IdxEntry - {\@nameauth@Pre#2\@nameauth@Tag}% + {\@nameauth@Pre#3\@nameauth@ShortTag|#1{#4}}% \fi \else % \end{macrocode} -% Create entries with just an info tag. +% Set up either a page entry or a cross-reference with an info tag. % % \begin{macrocode} - \if@nameauth@Xref + \ifx\@nameauth@XrefType\@empty \protected@edef\@nameauth@IdxEntry - {#2\@nameauth@ShortTag}% + {#3\@nameauth@Tag}% \else \protected@edef\@nameauth@IdxEntry - {#2\@nameauth@Tag}% + {#3\@nameauth@ShortTag|#1{#4}}% \fi \fi \else % \end{macrocode} -% Create entries with just a sorting tag. +% Set up either a page entry or a cross-reference with a sorting tag. % % \begin{macrocode} - \ifcsname#1!PRE\endcsname - \protected@edef\@nameauth@Pre{\csname#1!PRE\endcsname}% - \protected@edef\@nameauth@IdxEntry{\@nameauth@Pre#2}% + \ifcsname#2!PRE\endcsname + \protected@edef\@nameauth@Pre{\csname#2!PRE\endcsname}% + \ifx\@nameauth@XrefType\@empty + \protected@edef\@nameauth@IdxEntry{\@nameauth@Pre#3}% + \else + \protected@edef\@nameauth@IdxEntry{\@nameauth@Pre#3|#1{#4}}% + \fi \else - \protected@edef\@nameauth@IdxEntry{#2}% +% \end{macrocode} +% \newpage +% \noindent Set up either a page entry or a cross-reference with no tag. +% +% \begin{macrocode} + \ifx\@nameauth@XrefType\@empty + \protected@edef\@nameauth@IdxEntry{#3}% + \else + \protected@edef\@nameauth@IdxEntry{#3|#1{#4}}% + \fi \fi \fi % \end{macrocode} -% Create entries with no tag. +% Create the index entry. % % \begin{macrocode} \expandafter\NameauthIndex\expandafter{\@nameauth@IdxEntry}% @@ -12456,11 +12810,11 @@ and version 1.3 or later is part of all distributions of LaTeX version % \end{macrocode} % \end{macro} % -% \subsection[User Macros: Prefixes]{For Users: Prefix Macros} +% \subsection[User Macros: Prefix]{For Users: Prefix Macros} % \label{sec:PrefixMacs} % -% All prefix macros are meant to precede a particular name and only -% affect a particular name. +% Prefix macros precede a particular name (or xref) to affect +% only that name. % % \subsubsection[Syntax]{Name Syntax} % @@ -12499,9 +12853,7 @@ 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 does not work. +% Overrides the automatic test for active Unicode characters; a fallback. % % \begin{macrocode} \newcommand*\AccentCapThis @@ -12518,7 +12870,7 @@ and version 1.3 or later is part of all distributions of LaTeX version % \end{macrocode} % \end{macro} % -% \subsubsection*{\hfil Reversing} +% \subsubsection*{\hfil Reversing and Name Parts} % % \begin{macro}{\RevName} % \changes{1.5}{2013/02/22}{Added} @@ -12553,9 +12905,19 @@ and version 1.3 or later is part of all distributions of LaTeX version % % \subsubsection*{\hfil Affixes and Breaking} % +% \begin{macro}{\ForceAffix} +% \changes{4.1}{2025/02/04}{Added} +% Force the printing of just the affix of a short Western name +% in the text. +% +% \begin{macrocode} +\newcommand*\ForceAffix{\@nameauth@ForceAffixtrue} +% \end{macrocode} +% \end{macro} +% % \begin{macro}{\DropAffix} % \changes{3.0}{2016/10/26}{Added} -% Suppress the affix in a long Western name. +% Suppress printing the affix of a long Western name. % % \begin{macrocode} \newcommand*\DropAffix{\@nameauth@ShortSNNtrue} @@ -12564,8 +12926,7 @@ and version 1.3 or later is part of all distributions of LaTeX version % % \begin{macro}{\KeepAffix} % \changes{1.9}{2015/07/09}{Added} -% Trigger a name-suffix pair to be separated by -% a non-breaking space. +% Bind a name-affix pair with a non-breaking space. % % \begin{macrocode} \newcommand*\KeepAffix{\@nameauth@NBSPtrue} @@ -12649,12 +13010,13 @@ and version 1.3 or later is part of all distributions of LaTeX version % \end{macrocode} % \end{macro} % +% \TOCbreak % \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. +% endure for multiple names. They tend to affect an entire scope +% and usually come in pairs. % % \subsubsection[Syntax]{Name Syntax} % @@ -12715,8 +13077,7 @@ and version 1.3 or later is part of all distributions of LaTeX version % \changes{1.5}{2013/02/22}{Added} % 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. +% \cmd{\ReverseActive} takes priority over this macro. % % \begin{macrocode} \newcommand*\ReverseCommaActive{\@nameauth@RevAllCommatrue} @@ -12805,12 +13166,13 @@ and version 1.3 or later is part of all distributions of LaTeX version % \end{macro} % % \subsubsection[Alternate Format]{Alternate Formatting} +% \label{sec:AltFmtMacros} % % \begin{macro}{\AltFormatActive} % \changes{3.1}{2017/01/13}{Added} % \changes{4.0}{2024/02/09}{Combine starred, un-starred macros} % \begin{macro}{\AltFormatActive*}\end{macro}\vspace{-2.7ex} -% Turn on alternate formatting and +% \noindent Turn on alternate formatting and % disengage the formatting macros if using the starred form or % engage the formatting macros if using the un-starred form. % @@ -12826,8 +13188,8 @@ and version 1.3 or later is part of all distributions of LaTeX version % \end{macro} % % \begin{macro}{\AltFormatInactive} -% Turn off alternate formatting altogether. % \changes{3.1}{2017/01/13}{Added} +% Turn off alternate formatting altogether. % % \begin{macrocode} \newcommand*\AltFormatInactive @@ -12835,6 +13197,44 @@ and version 1.3 or later is part of all distributions of LaTeX version % \end{macrocode} % \end{macro} % +% \begin{environment}{AltFormatZone} +% \changes{4.1}{2025/02/04}{Added} +% We enable alternate formatting in its active (on) state. +% +% \begin{macrocode} +\newenvironment{AltFormatZone} + {\AltFormatActive\begingroup\def\@nameauth@InZone{}\ignorespaces} + {\endgroup\AltFormatInactive\ignorespacesafterend} +% \end{macrocode} +% \end{environment} +% +% \begin{environment}{AltFormatZone*} +% \changes{4.1}{2025/02/04}{Added} +% We enable alternate formatting in its inactive (off) state. +% +% \begin{macrocode} +\newenvironment{AltFormatZone*} + {\AltFormatActive*\begingroup\def\@nameauth@InZone{}\ignorespaces} + {\endgroup\AltFormatInactive\ignorespacesafterend} +% \end{macrocode} +% \end{environment} +% +% \begin{macro}{\FixateFormat} +% \changes{4.1}{2025/02/04}{Added} +% Redefine alternate formatting switches to do nothing only within +% the environments above. The user must choose to invoke this macro. +% +% \begin{macrocode} +\newcommand{\FixateFormat} +{% + \ifdefined\@nameauth@InZone + \RenewDocumentCommand{\AltFormatActive}{s}{}% + \renewcommand\AltFormatInactive{}% + \fi +} +% \end{macrocode} +% \end{macro} +% % \begin{macro}{\AltOn} % Locally turn on alternate formatting. % \changes{3.1}{2017/01/13}{Added} @@ -12882,11 +13282,13 @@ 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. +% \changes{4.1}{2025/02/04}{Two font switches avoid warnings} +% Alternate formatting macro: small caps when active. Change +% first to roman, then small caps, to avoid font warning. % % \begin{macrocode} \newcommand*\textSC[1] - {\if@nameauth@DoAlt\textsc{#1}\else#1\fi} + {\if@nameauth@DoAlt{\rmfamily\textsc{#1}}\else#1\fi} % \end{macrocode} % \end{macro} % @@ -12946,7 +13348,7 @@ and version 1.3 or later is part of all distributions of LaTeX version % \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 -% name systems at once, only the current one. +% name systems, only the current one. % % \begin{macrocode} \newcommand*\LocalNames{\global\@nameauth@LocalNamestrue} @@ -12957,7 +13359,7 @@ and version 1.3 or later is part of all distributions of LaTeX version % \changes{2.3}{2016/01/05}{Added} % \changes{2.4}{2016/03/15}{Ensure global} % \cmd{\GlobalNames} restores the default behavior of \cmd{\ForgetName} -% and \cmd{\SubvertName}, which affect both name systems at once. +% and \cmd{\SubvertName}, which affects both name systems at once. % % \begin{macrocode} \newcommand*\GlobalNames{\global\@nameauth@LocalNamesfalse} @@ -12973,9 +13375,15 @@ 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} +% \changes{4.1}{2025/02/04}{Support affix-only output; allow empty output} % 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}. +% We \cmd{\let} values to \cmd{\FNN} and \cmd{\SNN} not to +% be efficient but to be pedantic. Sometimes, the attempt to +% short-circuit parser logic will seem to work, only for a case +% to emerge that breaks things. Being pedantic reduces that risk, +% even if it is slower at times. % % \begin{macrocode} \newcommand*\NameParser @@ -12984,18 +13392,19 @@ and version 1.3 or later is part of all distributions of LaTeX version \let\SNN\rootb% \@nameauth@Choice % \end{macrocode} -% Nonwestern names. +% 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% + \unless\if@nameauth@FirstName \SNN \fi \else \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 @@ -13006,14 +13415,15 @@ and version 1.3 or later is part of all distributions of LaTeX version \fi }% % \end{macrocode} -% Nonwestern names, obsolete syntax. +% 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 @@ -13029,7 +13439,8 @@ and version 1.3 or later is part of all distributions of LaTeX version % % \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 @@ -13045,7 +13456,14 @@ and version 1.3 or later is part of all distributions of LaTeX version \fi \fi \else - \if@nameauth@FirstName \FNN \else \let\SNN\rootb \SNN \fi + \if@nameauth@ForceAffix + \let\SNN\suffb \SNN% + \else + \if@nameauth@FirstName \FNN% + \else + \let\SNN\rootb \SNN% + \fi + \fi \fi }% \fi @@ -13061,15 +13479,15 @@ and version 1.3 or later is part of all distributions of LaTeX version % 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. +% \cmd{\AKA}, and \cmd{\PName}. It thus tests for spurious spaces and +% bad output. % % \subsubsection{Basic Interface} % % \begin{macro}{\Name} % \changes{4.0}{2024/02/09}{Combine starred, un-starred macros} % \begin{macro}{\Name*}\end{macro}\vspace{-2.7ex} -% \cmd{\Name} calls \cmd{\NameauthName}, the interface hook, printing +% \noindent \cmd{\Name} calls \cmd{\NameauthName}, the interface hook, printing % a long name and calling \cmd{\NameauthLName} when using the starred form. % % \begin{macrocode} @@ -13086,7 +13504,7 @@ and version 1.3 or later is part of all distributions of LaTeX version % \changes{0.9}{2012/02/10}{Added} % \changes{4.0}{2024/02/09}{Combine starred, un-starred macros} % \begin{macro}{\FName*}\end{macro}\vspace{-2.7ex} -% \cmd{\FName} sets up a short name instance and calls \cmd{\NameauthFName}, +% \noindent \cmd{\FName} sets up a short name instance and calls \cmd{\NameauthFName}, % the interface hook. Its starred form is identical in function. % % \begin{macrocode} @@ -13103,7 +13521,8 @@ and version 1.3 or later is part of all distributions of LaTeX version % \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 +% \changes{4.1}{2025/02/04}{Better at ignoring spaces} +% % 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. @@ -13113,7 +13532,8 @@ and version 1.3 or later is part of all distributions of LaTeX version {% \begingroup% \let\ex\expandafter% - \csdef{<}##1&##2&##3&##4>{% + \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}}% @@ -13125,7 +13545,8 @@ and version 1.3 or later is part of all distributions of LaTeX version % \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. +% Lacking either will produce an error. +% Redefining a shorthand only creates a warning. % % \begin{macrocode} \ifx\@arga@\@empty @@ -13133,7 +13554,7 @@ and version 1.3 or later is part of all distributions of LaTeX version {environment nameauth: Macro name missing; \expandafter\detokenize\expandafter{##3}}% \fi - \@nameauth@Error{##3}{macro: \ex\zap@space\string\ \@empty##1}% + \@nameauth@Error{##3}{macro \ex\zap@space\string\ \@empty##1}% \ifcsname\@arga@\endcsname \PackageWarning{nameauth} {Environment nameauth: shorthand macro already exists}% @@ -13141,17 +13562,28 @@ and version 1.3 or later is part of all distributions of LaTeX version % \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 -% nonwestern names that use the new syntax. We use one \cmd{\ex} per -% token because we only have one argument to expand first. +% Non-Western names that use the new syntax. % % \begin{macrocode} \ifx\@testd@\@empty \ifx\@testb@\@empty +% \end{macrocode} +% Standard name: +% +% \begin{macrocode} \ex\csgdef\ex{\ex\@arga@\ex}% \ex{\ex\NameauthName\ex{\the\@nameauth@etoksc}}% +% \end{macrocode} +% Long name: +% +% \begin{macrocode} \ex\csgdef\ex{\ex\@larga@\ex}% \ex{\ex\@nameauth@FullNametrue% \ex\NameauthLName\ex{\the\@nameauth@etoksc}}% +% \end{macrocode} +% Short name: +% +% \begin{macrocode} \ex\csgdef\ex{\ex\@sarga@\ex}% \ex{\ex\@nameauth@FirstNametrue% \ex\NameauthFName\ex{\the\@nameauth@etoksc}}% @@ -13160,17 +13592,27 @@ and version 1.3 or later is part of all distributions of LaTeX version % 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. +% \medskip % +% \noindent Standard name: % \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}}% +% \end{macrocode} +% Long name: +% +% \begin{macrocode} \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}}% +% \end{macrocode} +% Short name: +% +% \begin{macrocode} \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% @@ -13179,20 +13621,31 @@ and version 1.3 or later is part of all distributions of LaTeX version \fi \else % \end{macrocode} -% Below are ``native'' Eastern names with alternates and +% Below are ``native'' Eastern names with alternates or % the older syntax. We again have two arguments to expand first. % +% \medskip +% +% \noindent Standard name: % \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]}% +% \end{macrocode} +% Long name: +% +% \begin{macrocode} \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]}% +% \end{macrocode} +% Short name: +% +% \begin{macrocode} \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% @@ -13203,6 +13656,9 @@ and version 1.3 or later is part of all distributions of LaTeX version % 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}. % +% \medskip +% +% \noindent Standard name: % \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}% @@ -13211,6 +13667,10 @@ and version 1.3 or later is part of all distributions of LaTeX version \ex\ex\ex\@nameauth@etoksb\ex\ex\ex]% \ex\ex\ex{\ex\the\ex\@nameauth@etoksc\ex}% \ex[\the\@nameauth@etoksd]}% +% \end{macrocode} +% Long name: +% +% \begin{macrocode} \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{% @@ -13220,6 +13680,10 @@ and version 1.3 or later is part of all distributions of LaTeX version \@nameauth@etoksb\ex\ex\ex]% \ex\ex\ex{\ex\the\ex\@nameauth@etoksc\ex}% \ex[\the\@nameauth@etoksd]}% +% \end{macrocode} +% Short name: +% +% \begin{macrocode} \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{% @@ -13233,7 +13697,7 @@ and version 1.3 or later is part of all distributions of LaTeX version \fi\ignorespaces% }\ignorespaces% } -{\endgroup\ignorespaces} +{\endgroup\ignorespacesafterend} % \end{macrocode} % \end{environment} % @@ -13243,17 +13707,20 @@ and version 1.3 or later is part of all distributions of LaTeX version % \changes{3.3}{2020/02/20}{Added} % \changes{3.7}{2023/02/03}{Redesigned} % \changes{4.0}{2024/02/09}{Use \textsf{xparse}} -% 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. +% \changes{4.1}{2025/02/04}{Allow null args} +% This macro shows a name pattern created by its arguments, unless +% invoked with an empty argument. Then it returns \cmd{\NameauthPattern} +% from the last name arguments that were evaluated. % % \begin{macrocode} \NewDocumentCommand{\ShowPattern}{O{} m O{}} {% - \@nameauth@Error{#2}{macro: \string\ShowPattern}% + \protected@edef\@nameauth@testname{\trim@spaces{#2}}% + \unless\ifx\@nameauth@testname\@empty + \@nameauth@Error{#2}{macro \string\ShowPattern}% \@nameauth@LoadArgs{#1}{#2}{#3}% \@nameauth@Choice{}{}{}\NameauthPattern% + \else\NameauthPattern\fi } % \end{macrocode} % \end{macro} @@ -13263,83 +13730,144 @@ and version 1.3 or later is part of all distributions of LaTeX version % \changes{3.5}{2020/11/23}{Fix name space, use Boolean flags} % \changes{3.7}{2023/02/03}{Use common back-end} % \changes{4.0}{2024/02/09}{Combine starred, un-starred macros} +% \changes{4.1}{2025/02/04}{Allow null args} % \begin{macro}{\ShowIdxPageref*}\end{macro}\vspace{-2.7ex} -% Show an index page entry appearance for given name parameters. +% \noindent Show an index page entry appearance for the given +% name arguments or, if a null argument is given, show an entry +% for the name arguments in the token registers. % \begin{macrocode} \NewDocumentCommand{\ShowIdxPageref}{s O{} m O{}} {% + \begingroup% + \let\ex\expandafter% \IfBooleanTF {#1}% % \end{macrocode} % The starred form displays 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} {% - \@nameauth@Error{#3}{macro: \string\ShowIdxPageref*}% - \@nameauth@LoadArgs{#2}{#3}{#4}% - \@nameauth@IdxPageref{#2}{#3}{#4}% + \protected@edef\@nameauth@testname{\trim@spaces{#3}}% + \unless\ifx\@nameauth@testname\@empty + \@nameauth@Error{#3}{macro \string\ShowIdxPageref*}% + \@nameauth@LoadArgs{#2}{#3}{#4}% + \@nameauth@IdxPageref{#2}{#3}{#4}% + \else +% \end{macrocode} +% Pull name arguments from the token regs. +% +% \begin{macrocode} + \ex\ex\ex\ex\ex\ex\ex\@nameauth@LoadArgs% + \ex\ex\ex\ex\ex\ex\ex{% + \ex\ex\ex\the\ex\ex\ex\@nameauth@toksa\ex\ex\ex}% + \ex\ex\ex{\ex\the\ex\@nameauth@toksb\ex}% + \ex{\the\@nameauth@toksc}% + \ex\ex\ex\ex\ex\ex\ex\@nameauth@IdxPageref% + \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 }% % \end{macrocode} % The un-starred form 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} {% - \@nameauth@Error{#3}{macro: \string\ShowIdxPageref}% - \@nameauth@LoadArgs{#2}{#3}{#4}% \global\@nameauth@LongIdxDebugtrue% - \@nameauth@IdxPageref{#2}{#3}{#4}% + \protected@edef\@nameauth@testname{\trim@spaces{#3}}% + \unless\ifx\@nameauth@testname\@empty + \@nameauth@Error{#3}{macro \string\ShowIdxPageref}% + \@nameauth@LoadArgs{#2}{#3}{#4}% + \@nameauth@IdxPageref{#2}{#3}{#4}% + \else +% \end{macrocode} +% Pull name arguments from the token regs. +% +% \begin{macrocode} + \ex\ex\ex\ex\ex\ex\ex\@nameauth@LoadArgs% + \ex\ex\ex\ex\ex\ex\ex{% + \ex\ex\ex\the\ex\ex\ex\@nameauth@toksa\ex\ex\ex}% + \ex\ex\ex{\ex\the\ex\@nameauth@toksb\ex}% + \ex{\the\@nameauth@toksc}% + \ex\ex\ex\ex\ex\ex\ex\@nameauth@IdxPageref% + \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 }% + \endgroup% } % \end{macrocode} % \end{macro} % % \begin{macro}{\ShowNameInfo} % \changes{3.7}{2023/02/03}{Added} -% \changes{4.0}{2024/02/09}{Use \textsf{xparse}, improve output} -% Show how the name arguments are being interpreted by the -% \textsf{nameauth} macros, but as detokenized text, +% \changes{4.0}{2024/02/09}{Use \textsf{xparse}} +% \changes{4.1}{2025/02/04}{Allow null args} +% Show how the name arguments are interpreted by the \textsf{nameauth} +% macros, but as detokenized text. If a null argument is given, use the +% arguments in the token regs, left from the last name evaluated. +% The starred form puts the separate data on different lines. % % \begin{macrocode} \NewDocumentCommand{\ShowNameInfo}{O{} m O{}} {% + \begingroup% + \let\ex\expandafter% % \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}% + \protected@edef\@nameauth@testname{\trim@spaces{#2}}% + \unless\ifx\@nameauth@testname\@empty + \@nameauth@Error{#2}{macro \string\ShowNameInfo}% + \@nameauth@LoadArgs{#1}{#2}{#3}% + \else % \end{macrocode} -% We produce what we know about the name arguments. -% First is nonwestern names using the current syntax. +% In the case of a null argument, +% load name arguments from the token regs. +% +% \begin{macrocode} + \ex\ex\ex\ex\ex\ex\ex\@nameauth@LoadArgs% + \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 + \protected@edef\@nameauth@cleanA + {\expandafter\detokenize\expandafter{\@nameauth@A}}% + \protected@edef\@nameauth@cleanB + {\expandafter\detokenize\expandafter{\@nameauth@B}}% + \protected@edef\@nameauth@cleanSB + {\expandafter\detokenize\expandafter{\@nameauth@SB}}% + \protected@edef\@nameauth@cleanC + {\expandafter\detokenize\expandafter{\@nameauth@C}}% +% \end{macrocode} +% First we have Non-Western names using the current syntax. % % \begin{macrocode} \@nameauth@Choice {% - (SNN: \expandafter\detokenize\expandafter{\@nameauth@B})% + (SNN: \@nameauth@cleanB)% \unless\ifx\@nameauth@SB\@empty - \ (Affix*: - \expandafter\detokenize\expandafter{\@nameauth@SB})% + \ (Affix*: \@nameauth@cleanSB)% \fi \unless\ifx\@nameauth@C\@empty - \ (Alt: - \expandafter\detokenize\expandafter{\@nameauth@C})% + \ (Alt: \@nameauth@cleanC)% \fi }% % \end{macrocode} -% Next is nonwestern names using the obsolete syntax. +% Next is Non-Western names using the obsolete syntax. % % \begin{macrocode} {% - (SNN: \expandafter\detokenize\expandafter{\@nameauth@B})% + (SNN: \@nameauth@cleanB)% \unless\ifx\@nameauth@C\@empty - \ (Alt*: - \expandafter\detokenize\expandafter{\@nameauth@C})% + \ (Alt*: \@nameauth@cleanC)% \fi }% % \end{macrocode} @@ -13347,39 +13875,60 @@ and version 1.3 or later is part of all distributions of LaTeX version % % \begin{macrocode} {% - (FNN: \expandafter\detokenize\expandafter{\@nameauth@A}) - (SNN: \expandafter\detokenize\expandafter{\@nameauth@B})% + (FNN: \@nameauth@cleanA) + (SNN: \@nameauth@cleanB)% \unless\ifx\@nameauth@SB\@empty - \ (Affix: - \expandafter\detokenize\expandafter{\@nameauth@SB})% + \ (Affix: \@nameauth@cleanSB)% \fi \unless\ifx\@nameauth@C\@empty - \ (Alt: - \expandafter\detokenize\expandafter{\@nameauth@C})% + \ (Alt: \@nameauth@cleanC)% \fi }% -} + \endgroup% +} % \end{macrocode} % \end{macro} % % \begin{macro}{\ShowNameState} % \changes{3.7}{2023/02/03}{Added} % \changes{4.0}{2024/02/09}{Use \textsf{xparse}} -% This macro tells the user what control sequence patterns -% exist for any given name. +% \changes{4.1}{2025/02/04}{Allow null args, add starred form, improve output} +% \begin{macro}{\ShowNameState*}\end{macro}\vspace{-2.7ex} +% These macros show the user the name pattern, name type, index state, +% and name systems of a given name. The un-starred form prints on one +% line; the starred form, multiple lines. If a null argument +% is given, they use the arguments from the last printed name. % % \begin{macrocode} -\NewDocumentCommand{\ShowNameState}{O{} m O{}} +\NewDocumentCommand{\ShowNameState}{s O{} m O{}} {% % \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. +% the appropriate macros. Test for a star and set the break +% to |\par| or a space. % % \begin{macrocode} \begingroup% - \@nameauth@Error{#2}{macro: \string\NamePatterns}% - \@nameauth@LoadArgs{#1}{#2}{#3}% + \IfBooleanTF{#1} + {\def\@nameauth@break{\par}} + {\def\@nameauth@break{ }} + \let\ex\expandafter% + \protected@edef\@nameauth@testname{\trim@spaces{#3}}% + \unless\ifx\@nameauth@testname\@empty + \@nameauth@Error{#3}{macro \string\ShowNameState}% + \@nameauth@LoadArgs{#2}{#3}{#4}% + \else +% \end{macrocode} +% Pull name arguments from the token regs. +% +% \begin{macrocode} + \ex\ex\ex\ex\ex\ex\ex\@nameauth@LoadArgs% + \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 % \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. @@ -13447,22 +13996,25 @@ and version 1.3 or later is part of all distributions of LaTeX version \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}% + \ifdefined \@nameauth@excl + \def\@nameauth@idxstate{5}% + \fi + \else + \def\@nameauth@idxstate{1}% + \def\@nameauth@nosystem{none}% \fi \fi % \end{macrocode} % Display the output. % % \begin{macrocode} - Pattern: {\NameauthPattern} - Type: {\@nameauth@nametype} - Index state: {\@nameauth@idxstate} + Pattern: \NameauthPattern\@nameauth@break + Type: \@nameauth@nametype\@nameauth@break + State: \@nameauth@idxstate\@nameauth@break Systems:% + \ifdefined \@nameauth@nosystem\ \@nameauth@nosystem \fi \ifdefined \@nameauth@mainname\ \@nameauth@mainname \fi \ifdefined \@nameauth@frontname\ \@nameauth@frontname \fi \ifdefined \@nameauth@xref\ \@nameauth@xref \fi @@ -13475,6 +14027,8 @@ and version 1.3 or later is part of all distributions of LaTeX version % \end{macrocode} % \end{macro} % +% \newpage +% % \subsubsection{Indexing} % % \begin{macro}{\IndexName} @@ -13487,6 +14041,7 @@ and version 1.3 or later is part of all distributions of LaTeX version % improve logic, fix namespace} % \changes{3.7}{2023/02/03}{Fix warnings} % \changes{4.0}{2024/02/09}{Use \textsf{xparse}} +% \changes{4.1}{2025/02/04}{Use updated \cmd{\@nameauth@Index}} % This creates an index entry with page entries. 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. @@ -13496,8 +14051,7 @@ and version 1.3 or later is part of all distributions of LaTeX version \NewDocumentCommand{\IndexName}{O{} m O{}} {% % \end{macrocode} -% Process and load the arguments into the appropriate macros; -% test for malformed input. +% Process and load the arguments; test for malformed input. % % \begin{macrocode} \@nameauth@LoadArgs{#1}{#2}{#3}% @@ -13525,20 +14079,23 @@ and version 1.3 or later is part of all distributions of LaTeX version \fi \fi % \end{macrocode} +% Enter a local scope, and if so forced, enable indexing only +% within that scope. % 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 -% \end{macrocode} -% Nonwestern names. -% We ignore \cmd{\@nameauth@C} and handle \cmd{\@nameauth@SB} appropriately. +% Non-Western names. We ignore \cmd{\@nameauth@C}. % % \begin{macrocode} + \@nameauth@Choice {% \def\@nameauth@Temp{\expandafter\detokenize\expandafter{#2}}% \ifcsname\@nameauth@csb!PN\endcsname +% \end{macrocode} +% Verbose warnings: Does an exclusion or cross-reference exist? +% +% \begin{macrocode} \if@nameauth@Verbose \edef\@nameauth@testex {\csname\@nameauth@csb!PN\endcsname}% @@ -13551,22 +14108,35 @@ and version 1.3 or later is part of all distributions of LaTeX version \fi \fi \else +% \end{macrocode} +% \newpage +% \noindent Mononym entry +% +% \begin{macrocode} \ifx\@nameauth@SB\@empty - \@nameauth@Index{\@nameauth@csb}{\@nameauth@B}% + \@nameauth@Index{\@nameauth@csb}{\@nameauth@B}{}% \else +% \end{macrocode} +% Non-Western entry +% +% \begin{macrocode} \@nameauth@Index{\@nameauth@csb} - {\@nameauth@B\@nameauth@space\@nameauth@SB}% + {\@nameauth@B\@nameauth@space\@nameauth@SB}{}% \fi \fi }% % \end{macrocode} -% Nonwestern names, obsolete syntax. -% Using \cmd{\@nameauth@C} in this path affects indexing. +% Non-Western names, obsolete syntax. +% Using \cmd{\@nameauth@C} affects indexing here. % % \begin{macrocode} {% \def\@nameauth@Temp{\expandafter\detokenize\expandafter{#2 #3}}% \ifcsname\@nameauth@csbc!PN\endcsname +% \end{macrocode} +% Verbose warnings: Does an exclusion or cross-reference exist? +% +% \begin{macrocode} \if@nameauth@Verbose \edef\@nameauth@testex {\csname\@nameauth@csbc!PN\endcsname}% @@ -13579,18 +14149,26 @@ and version 1.3 or later is part of all distributions of LaTeX version \fi \fi \else +% \end{macrocode} +% Non-Western entry +% +% \begin{macrocode} \@nameauth@Index{\@nameauth@csbc} - {\@nameauth@B\@nameauth@space\@nameauth@C}% + {\@nameauth@B\@nameauth@space\@nameauth@C}{}% \fi }% % \end{macrocode} % Western names. -% We ignore \cmd{\@nameauth@C} and handle \cmd{\@nameauth@SB} appropriately. +% We ignore \cmd{\@nameauth@C} and handle \cmd{\@nameauth@SB}. % % \begin{macrocode} {% \def\@nameauth@Temp{\expandafter\detokenize\expandafter{#1 #2}}% \ifcsname\@nameauth@csab!PN\endcsname +% \end{macrocode} +% Verbose warnings: Does an exclusion or cross-reference exist? +% +% \begin{macrocode} \if@nameauth@Verbose \edef\@nameauth@testex {\csname\@nameauth@csab!PN\endcsname}% @@ -13603,13 +14181,21 @@ and version 1.3 or later is part of all distributions of LaTeX version \fi \fi \else +% \end{macrocode} +% Western entry, no affix +% +% \begin{macrocode} \ifx\@nameauth@SB\@empty \@nameauth@Index{\@nameauth@csab} - {\@nameauth@B,\@nameauth@space\@nameauth@A}% + {\@nameauth@B,\@nameauth@space\@nameauth@A}{}% \else +% \end{macrocode} +% Western entry, with affix +% +% \begin{macrocode} \@nameauth@Index{\@nameauth@csab} {\@nameauth@B,\@nameauth@space% - \@nameauth@A,\@nameauth@space\@nameauth@SB}% + \@nameauth@A,\@nameauth@space\@nameauth@SB}{}% \fi \fi }% @@ -13625,8 +14211,9 @@ and version 1.3 or later is part of all distributions of LaTeX version % new exclusion test, improve logic, fix namespace} % \changes{3.7}{2023/02/03}{Fix warnings} % \changes{4.0}{2024/02/09}{Use \textsf{xparse}} +% \changes{4.1}{2025/02/04}{Use updated \cmd{\@nameauth@Index}} % Create a cross-reference that is not already an exclusion or -% a cross-reference. Print nothing. +% a cross-reference. % % \begin{macrocode} \NewDocumentCommand{\IndexRef}{O{} m O{} m} @@ -13642,9 +14229,7 @@ and version 1.3 or later is part of all distributions of LaTeX version % % \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. % @@ -13658,14 +14243,16 @@ and version 1.3 or later is part of all distributions of LaTeX version \fi \@nameauth@Choice % \end{macrocode} -% Nonwestern 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, no \meta{Affix} % % \begin{macrocode} {% \def\@nameauth@Temp{\expandafter\detokenize\expandafter{#2}}% \ifcsname\@nameauth@csb!PN\endcsname +% \end{macrocode} +% Verbose warnings: Does an exclusion or cross-reference exist? +% +% \begin{macrocode} \if@nameauth@Verbose \edef\@nameauth@testex {\csname\@nameauth@csb!PN\endcsname}% @@ -13677,24 +14264,28 @@ and version 1.3 or later is part of all distributions of LaTeX version {\string\IndexRef: xref exists \@nameauth@Temp}% \fi \fi + \else % \end{macrocode} -% 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. +% If no xref or exclusion exists, proceed. If creating +% a \textit{see also} reference, just do it. % % \begin{macrocode} - \else \ifx\@nameauth@SB\@empty \if@nameauth@SeeAlso - \@nameauth@Index{\@nameauth@csb} - {\@nameauth@B|seealso{\@nameauth@Target}}% + \@nameauth@Index[seealso]{\@nameauth@csb} + {\@nameauth@B}{\@nameauth@Target}% \csgdef{\@nameauth@csb!PN}{}% \else +% \end{macrocode} +% When creating a \textit{see} reference, check if a name +% already exists. If so, skip and warn. +% +% \begin{macrocode} \unless\if@nameauth@OldSee \unless\ifcsname\@nameauth@csb!MN\endcsname \unless\ifcsname\@nameauth@csb!NF\endcsname - \@nameauth@Index{\@nameauth@csb} - {\@nameauth@B|see{\@nameauth@Target}}% + \@nameauth@Index[see]{\@nameauth@csb} + {\@nameauth@B}{\@nameauth@Target}% \csgdef{\@nameauth@csb!PN}{}% \else \PackageWarning{nameauth} @@ -13707,34 +14298,43 @@ and version 1.3 or later is part of all distributions of LaTeX version no xref \@nameauth@Temp}% \fi \else +% \end{macrocode} +% Extra verbose warnings and old behavior +% +% \begin{macrocode} \if@nameauth@Verbose \PackageWarning{nameauth} {\string\IndexRef: non-strict xref \@nameauth@Temp}% \fi - \@nameauth@Index{\@nameauth@csb} - {\@nameauth@B|see{\@nameauth@Target}}% + \@nameauth@Index[see]{\@nameauth@csb} + {\@nameauth@B}{\@nameauth@Target}% \csgdef{\@nameauth@csb!PN}{}% \fi \fi + \else % \end{macrocode} -% 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. +% Non-Western name, new syntax, \meta{Affix} exists; create +% a \textit{see also} reference if needed. % % \begin{macrocode} - \else \if@nameauth@SeeAlso - \@nameauth@Index{\@nameauth@csb} + \@nameauth@Index[seealso]{\@nameauth@csb} {\@nameauth@B\@nameauth@space% - \@nameauth@SB|seealso{\@nameauth@Target}}% + \@nameauth@SB}{\@nameauth@Target}% \csgdef{\@nameauth@csb!PN}{}% \else +% \end{macrocode} +% \newpage +% \noindent When creating a \textit{see} reference, check if a name +% already exists. If so, skip and warn. +% +% \begin{macrocode} \unless\if@nameauth@OldSee \unless\ifcsname\@nameauth@csb!MN\endcsname \unless\ifcsname\@nameauth@csb!NF\endcsname - \@nameauth@Index{\@nameauth@csb} + \@nameauth@Index[see]{\@nameauth@csb} {\@nameauth@B\@nameauth@space% - \@nameauth@SB|see{\@nameauth@Target}}% + \@nameauth@SB}{\@nameauth@Target}% \csgdef{\@nameauth@csb!PN}{}% \else \PackageWarning{nameauth} @@ -13747,13 +14347,17 @@ and version 1.3 or later is part of all distributions of LaTeX version no xref \@nameauth@Temp}% \fi \else +% \end{macrocode} +% Extra verbose warnings and old behavior +% +% \begin{macrocode} \if@nameauth@Verbose \PackageWarning{nameauth} {\string\IndexRef: non-strict xref \@nameauth@Temp}% \fi - \@nameauth@Index{\@nameauth@csb} + \@nameauth@Index[see]{\@nameauth@csb} {\@nameauth@B\@nameauth@space% - \@nameauth@SB|see{\@nameauth@Target}}% + \@nameauth@SB}{\@nameauth@Target}% \csgdef{\@nameauth@csb!PN}{}% \fi \fi @@ -13761,12 +14365,16 @@ 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 % % \begin{macrocode} {% \def\@nameauth@Temp{\expandafter\detokenize\expandafter{#2 #3}}% \ifcsname\@nameauth@csbc!PN\endcsname +% \end{macrocode} +% Verbose warnings: Does an exclusion or cross-reference exist? +% +% \begin{macrocode} \if@nameauth@Verbose \edef\@nameauth@testex {\csname\@nameauth@csbc!PN\endcsname}% @@ -13778,25 +14386,30 @@ and version 1.3 or later is part of all distributions of LaTeX version {\string\IndexRef: xref exists \@nameauth@Temp}% \fi \fi + \else % \end{macrocode} -% 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. +% \newpage +% \noindent If no xref or exclusion exists, proceed. If creating +% a \textit{see also} reference, just do it. % % \begin{macrocode} - \else \if@nameauth@SeeAlso - \@nameauth@Index{\@nameauth@csbc} - {\@nameauth@B\@nameauth@space% - \@nameauth@C|seealso{\@nameauth@Target}}% + \@nameauth@Index[seealso]{\@nameauth@csbc} + {\@nameauth@B\@nameauth@space\@nameauth@C} + {\@nameauth@Target}% \csgdef{\@nameauth@csbc!PN}{}% \else +% \end{macrocode} +% When creating a \textit{see} reference, check if a name +% already exists. If so, skip and warn. +% +% \begin{macrocode} \unless\if@nameauth@OldSee \unless\ifcsname\@nameauth@csbc!MN\endcsname \unless\ifcsname\@nameauth@csbc!NF\endcsname - \@nameauth@Index{\@nameauth@csbc} - {\@nameauth@B\@nameauth@space% - \@nameauth@C|see{\@nameauth@Target}}% + \@nameauth@Index[see]{\@nameauth@csbc} + {\@nameauth@B\@nameauth@space\@nameauth@C} + {\@nameauth@Target}% \csgdef{\@nameauth@csbc!PN}{}% \else \PackageWarning{nameauth} @@ -13809,25 +14422,34 @@ and version 1.3 or later is part of all distributions of LaTeX version no xref \@nameauth@Temp}% \fi \else +% \end{macrocode} +% Extra verbose warnings and old behavior +% +% \begin{macrocode} \if@nameauth@Verbose \PackageWarning{nameauth} {\string\IndexRef: non-strict xref \@nameauth@Temp}% \fi - \@nameauth@Index{\@nameauth@csbc} - {\@nameauth@B\@nameauth@space% - \@nameauth@C|see{\@nameauth@Target}}% + \@nameauth@Index[see]{\@nameauth@csbc} + {\@nameauth@B\@nameauth@space\@nameauth@C} + {\@nameauth@Target}% \csgdef{\@nameauth@csbc!PN}{}% \fi \fi \fi }% % \end{macrocode} -% Western name, without and with affix. First check if an xref or excluded. +% Western name % % \begin{macrocode} {% \def\@nameauth@Temp{\expandafter\detokenize\expandafter{#1 #2}}% \ifcsname\@nameauth@csab!PN\endcsname +% \end{macrocode} +% \newpage +% \noindent Verbose warnings: Does an exclusion or cross-reference exist? +% +% \begin{macrocode} \if@nameauth@Verbose \edef\@nameauth@testex {\csname\@nameauth@csab!PN\endcsname}% @@ -13839,26 +14461,31 @@ and version 1.3 or later is part of all distributions of LaTeX version {\string\IndexRef: xref exists \@nameauth@Temp}% \fi \fi + \else % \end{macrocode} -% 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. +% If no xref or exclusion exists, proceed. +% Process names without an affix. +% If creating a \textit{see also} reference, just do it. % % \begin{macrocode} - \else \ifx\@nameauth@SB\@empty \if@nameauth@SeeAlso - \@nameauth@Index{\@nameauth@csab} - {\@nameauth@B,\@nameauth@space% - \@nameauth@A|seealso{\@nameauth@Target}}% + \@nameauth@Index[seealso]{\@nameauth@csab} + {\@nameauth@B,\@nameauth@space\@nameauth@A} + {\@nameauth@Target}% \csgdef{\@nameauth@csab!PN}{}% \else +% \end{macrocode} +% When creating a \textit{see} reference, check if a name +% already exists. If so, skip and warn. +% +% \begin{macrocode} \unless\if@nameauth@OldSee \unless\ifcsname\@nameauth@csab!MN\endcsname \unless\ifcsname\@nameauth@csab!NF\endcsname - \@nameauth@Index{\@nameauth@csab} - {\@nameauth@B,\@nameauth@space% - \@nameauth@A|see{\@nameauth@Target}}% + \@nameauth@Index[see]{\@nameauth@csab} + {\@nameauth@B,\@nameauth@space\@nameauth@A} + {\@nameauth@Target}% \csgdef{\@nameauth@csab!PN}{}% \else \PackageWarning{nameauth} @@ -13871,37 +14498,45 @@ and version 1.3 or later is part of all distributions of LaTeX version no xref \@nameauth@Temp}% \fi \else +% \end{macrocode} +% Extra verbose warnings and old behavior +% +% \begin{macrocode} \if@nameauth@Verbose \PackageWarning{nameauth} {\string\IndexRef: non-strict xref \@nameauth@Temp}% \fi - \@nameauth@Index{\@nameauth@csab} - {\@nameauth@B,\@nameauth@space% - \@nameauth@A|see{\@nameauth@Target}}% + \@nameauth@Index[see]{\@nameauth@csab} + {\@nameauth@B,\@nameauth@space\@nameauth@A} + {\@nameauth@Target}% \csgdef{\@nameauth@csab!PN}{}% \fi \fi + \else % \end{macrocode} -% 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. +% Process names with an affix. +% If creating a \textit{see also} reference, just do it. % % \begin{macrocode} - \else \if@nameauth@SeeAlso - \@nameauth@Index{\@nameauth@csab} + \@nameauth@Index[seealso]{\@nameauth@csab} {\@nameauth@B,\@nameauth@space% - \@nameauth@A,\@nameauth@space% - \@nameauth@SB|seealso{\@nameauth@Target}}% + \@nameauth@A,\@nameauth@space\@nameauth@SB} + {\@nameauth@Target}% \csgdef{\@nameauth@csab!PN}{}% \else +% \end{macrocode} +% When creating a \textit{see} reference, check if a name +% already exists. If so, skip and warn. +% +% \begin{macrocode} \unless\if@nameauth@OldSee \unless\ifcsname\@nameauth@csab!MN\endcsname \unless\ifcsname\@nameauth@csab!NF\endcsname - \@nameauth@Index{\@nameauth@csab} + \@nameauth@Index[see]{\@nameauth@csab} {\@nameauth@B,\@nameauth@space% - \@nameauth@A,\@nameauth@space% - \@nameauth@SB|see{\@nameauth@Target}}% + \@nameauth@A,\@nameauth@space\@nameauth@SB} + {\@nameauth@Target}% \csgdef{\@nameauth@csab!PN}{}% \else \PackageWarning{nameauth} @@ -13914,21 +14549,28 @@ and version 1.3 or later is part of all distributions of LaTeX version no xref \@nameauth@Temp}% \fi \else +% \end{macrocode} +% Extra verbose warnings and old behavior +% +% \begin{macrocode} \if@nameauth@Verbose \PackageWarning{nameauth} {\string\IndexRef: non-strict xref \@nameauth@Temp}% \fi - \@nameauth@Index{\@nameauth@csab} + \@nameauth@Index[see]{\@nameauth@csab} {\@nameauth@B,\@nameauth@space% - \@nameauth@A,\@nameauth@space% - \@nameauth@SB|see{\@nameauth@Target}}% + \@nameauth@A,\@nameauth@space\@nameauth@SB} + {\@nameauth@Target}% \csgdef{\@nameauth@csab!PN}{}% \fi \fi \fi \fi }% - \@nameauth@Xreffalse% +% \end{macrocode} +% Reset the \textit{see also} flag to false. +% +% \begin{macrocode} \if@nameauth@OldReset \@nameauth@SeeAlsofalse% \else @@ -13937,6 +14579,7 @@ and version 1.3 or later is part of all distributions of LaTeX version } % \end{macrocode} % \end{macro} +% \newpage % % \begin{macro}{\ExcludeName} % \changes{0.94}{2012/02/15}{Added} @@ -13949,7 +14592,7 @@ and version 1.3 or later is part of all distributions of LaTeX version % \changes{4.0}{2024/02/09}{Use \textsf{xparse}} % Prevent a name from being indexed by initializing a regular % cross-reference control sequence with the value of -% \cmd{\@nameauth@Exclude}. +% \cmd{\@nameauth@Exclude}. % % \begin{macrocode} \NewDocumentCommand{\ExcludeName}{O{} m O{}} @@ -13970,7 +14613,6 @@ and version 1.3 or later is part of all distributions of LaTeX version {\def\@nameauth@Temp{\expandafter\detokenize\expandafter{#2 #3}}} {\def\@nameauth@Temp{\expandafter\detokenize\expandafter{#1 #2}}}% % \end{macrocode} -% % Verbose warnings say that an extant name is being excluded; % the operation is allowed. % @@ -14017,7 +14659,7 @@ and version 1.3 or later is part of all distributions of LaTeX version % \changes{3.7}{2023/02/03}{Fix warnings, optimized} % \changes{4.0}{2024/02/09}{Combine starred, un-starred macros} % \begin{macro}{\IncludeName*}\end{macro}\vspace{-2.7ex} -% Allow names to be included as page entries, even if they have been +% \noindent Allow names to be included as page entries, even if they have been % used as cross-references. % \begin{macrocode} \NewDocumentCommand{\IncludeName}{s O{} m O{}} @@ -14048,9 +14690,12 @@ and version 1.3 or later is part of all distributions of LaTeX version \@nameauth@LoadArgs{#2}{#3}{#4}% \@nameauth@Error{#3}{macro \string\IncludeName}% \@nameauth@Choice - {\def\@nameauth@Temp{\expandafter\detokenize\expandafter{#3}}} - {\def\@nameauth@Temp{\expandafter\detokenize\expandafter{#3 #4}}} - {\def\@nameauth@Temp{\expandafter\detokenize\expandafter{#2 #3}}}% + {\def\@nameauth@Temp + {\expandafter\detokenize\expandafter{#3}}} + {\def\@nameauth@Temp + {\expandafter\detokenize\expandafter{#3 #4}}} + {\def\@nameauth@Temp + {\expandafter\detokenize\expandafter{#2 #3}}}% % \end{macrocode} % Test whether the name is an exclusion or a regular xref. % If the former, delete its control sequence. If the latter, @@ -14080,8 +14725,7 @@ and version 1.3 or later is part of all distributions of LaTeX version % improve logic, fix namespace} % \changes{3.7}{2023/02/03}{Fix warnings, optimized} % \changes{4.0}{2024/02/09}{Use \textsf{xparse}} -% This creates an index entry tag that is applied before a name -% by \cmd{\@nameauth@Index}. +% This creates an index sort tag that is applied before a name. % % \begin{macrocode} \NewDocumentCommand{\PretagName}{O{} m O{} m} @@ -14105,7 +14749,8 @@ and version 1.3 or later is part of all distributions of LaTeX version {\def\@nameauth@Temp{\expandafter\detokenize\expandafter{#1 #2}}}% % \end{macrocode} % Create the sort tag. Verbose warnings let us know if we are -% sorting either exclusions or cross-references. +% sorting either exclusions or names that are either +% cross-references or do not exist yet. % % \begin{macrocode} \if@nameauth@Verbose @@ -14116,7 +14761,7 @@ and version 1.3 or later is part of all distributions of LaTeX version {\string\PretagName: tag exclusion \@nameauth@Temp}% \else \PackageWarning{nameauth} - {\string\PretagName: tag xref \@nameauth@Temp}% + {\string\PretagName: tag xref/no exist \@nameauth@Temp}% \fi \fi \csgdef{\NameauthPattern!PRE}{#4\@nameauth@Actual}% @@ -14178,7 +14823,6 @@ and version 1.3 or later is part of all distributions of LaTeX version } % \end{macrocode} % \end{macro} -% % \newpage % % \begin{macro}{\UntagName} @@ -14229,19 +14873,23 @@ and version 1.3 or later is part of all distributions of LaTeX version % \changes{3.5}{2020/11/23}{Improve logic, fix namespace} % \changes{3.7}{2023/02/03}{Optimized} % \changes{4.0}{2024/02/09}{Use \textsf{xparse}} +% \changes{4.1}{2025/02/04}{Works always in hooks when using null args} % This prints the information created by \cmd{\NameAddInfo} if it exists. % % \begin{macrocode} \NewDocumentCommand{\NameQueryInfo}{O{} m O{}} {% \unless\if@nameauth@BigLock - \@nameauth@LoadArgs{#1}{#2}{#3}% - \@nameauth@Error{#2}{macro \string\NameQueryInfo}% - \@nameauth@Choice{}{}{}% + \protected@edef\@nameauth@testname{\trim@spaces{#2}}% + \unless\ifx\@nameauth@testname\@empty + \@nameauth@Error{#2}{macro \string\NameQueryInfo}% + \@nameauth@LoadArgs{#1}{#2}{#3}% + \@nameauth@Choice{}{}{}% + \fi \ifcsname\NameauthPattern!DB\endcsname - \csname\NameauthPattern!DB\endcsname% + \expandafter\csname\NameauthPattern!DB\endcsname% \fi - \fi + \fi } % \end{macrocode} % \end{macro} @@ -14277,6 +14925,7 @@ and version 1.3 or later is part of all distributions of LaTeX version % 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. +% \newpage % % \begin{macrocode} \NewDocumentCommand{\IfMainName}{O{} m O{} +m +m} @@ -14476,7 +15125,7 @@ and version 1.3 or later is part of all distributions of LaTeX version % \changes{3.5}{2020/11/23}{Fix namespace} % \changes{4.0}{2024/02/09}{Combine starred, un-starred macros} % \begin{macro}{\AKA*}\end{macro}\vspace{-2.7ex} -% \cmd{\AKA} prints an alternate name and creates index cross-references. +% \noindent \cmd{\AKA} prints an alternate name and creates index cross-references. % The starred form displays the alternate name like \cmd{\FName}. % % \begin{macrocode} @@ -14484,8 +15133,8 @@ and version 1.3 or later is part of all distributions of LaTeX version {% % \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. +% Tell the formatting system that \cmd{\AKA} is running. +% Prevent and reset \cmd{\JustIndex}. % % \begin{macrocode} \if@nameauth@BigLock @@ -14501,14 +15150,18 @@ and version 1.3 or later is part of all distributions of LaTeX version \global\@nameauth@JustIndexfalse% \fi % \end{macrocode} -% Test for malformed input. +% Test for malformed input, then load args and save the persistent +% info of the xref. % % \begin{macrocode} \@nameauth@Error{#3}{macro \string\AKA}% \@nameauth@Error{#5}{macro \string\AKA}% + \@nameauth@LoadArgs{#4}{#5}{#6}% + \@nameauth@Choice{}{}{}% % \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{}% @@ -14564,7 +15217,7 @@ and version 1.3 or later is part of all distributions of LaTeX version % \changes{3.7}{2023/02/03}{Fix warnings} % \changes{4.0}{2024/02/09}{Combine starred, un-starred macros} % \begin{macro}{\PName*}\end{macro}\vspace{-2.7ex} -% \cmd{\PName} is a convenience macro that calls \cmd{\NameauthName}, then \cmd{\AKA}. Its starred form prints a long name. +% \noindent \cmd{\PName} is a convenience macro that calls \cmd{\NameauthName}, then \cmd{\AKA}. Its starred form prints a long name. % % \begin{macrocode} \NewDocumentCommand{\PName}{s O{} m O{} m O{}} @@ -14623,44 +15276,45 @@ and version 1.3 or later is part of all distributions of LaTeX version %</package> %<*compat> %<<compatvb - % This is not a standalone document. % Use this file only in the document preamble. +% Ensure that we have the needed macros. +\usepackage{etoolbox} + +% Allow special catcodes. \makeatletter % Do not include the rest of this file % unless we are in a document preamble. - \ifx\@onlypreamble\@notprerr\else + % Include the rest of this if--else statement. -% Check against the latex version date. Create a macro -% if the date is at least 2018/10/05 because that is -% when Unicode processing changed for the better. + % Check against the latex version date. Create a macro + % if the date is at least 2018/10/05 because that is + % when Unicode processing changed for the better. + \@ifl@t@r\fmtversion{2018/10/05}{\newcommand\nameauthltx{}}{} - \@ifl@t@r\fmtversion{2018/10/05}{\def\nameauthltx{}}{} + % Here we check for 2018/04/30 because that is when xparse + % added the ! modifier. + \@ifl@t@r\fmtversion{2018/04/30}{\newcommand\nameauthxp{}}{} -% Here we check for 2018/04/30 because that is when xparse -% added the ! modifier. - - \@ifl@t@r\fmtversion{2018/04/30}{\def\nameauthxp{}}{} - -% Here we assist backward compatibility for older -% distributions of LaTeX and compatibility for multiple -% LaTeX engines. - -% If we want to use TikZ, this flag will help us. + % Here we assist backward compatibility for older + % distributions of LaTeX and compatibility for multiple + % LaTeX engines. + % If we want to use TikZ, this flag will help us. + % We use this method to avoid crashing some \texttt{dvi} + % viewers. Define the macro \noTikZ to bypass this check. \newif\ifDoTikZ -% If we couch this statement in a conditional, we avoid -% potential errors in older versions. - + % If we couch this statement in a conditional, we avoid + % potential errors in older versions. \IfFileExists{iftex.sty}{\usepackage{iftex}}{} -% The presence of \RequireTUTeX means that these older -% packages are not needed (thanks to iftex). Otherwise -% we are using an older version and need these packages. + % The presence of \RequireTUTeX means that these older + % packages are not needed (thanks to iftex). Otherwise + % we are using an older version and need these packages. \unless\ifdefined\RequireTUTeX \usepackage{ifxetex} @@ -14668,59 +15322,87 @@ and version 1.3 or later is part of all distributions of LaTeX version \usepackage{ifpdf} \fi -% Instead of worrying about older or newer changes, we -% ensure consistency when the LaTeX engine changes. -% The goal is to get the same ``lmodern'' look. -% Users will need to change language and font options -% for their own needs. + % Instead of worrying about older or newer changes, we + % ensure consistency when the LaTeX engine changes. + % The goal is to get the same ``lmodern'' look. + % Users will need to change language and font options + % for their own needs. + % To remain compatible with our experience on older + % distributions, we load fontspec and prefer polyglossia + % with both XeLaTeX and LuaLaTeX. One cannot load both + % babel and polyglossia. See the relevant documentation. + + % This flag causes polyglossia to be the default. + \newif\ifloadbabel + + % Here we do the right thing for the right LaTeX version. \ifxetex + % We always load fontspec in this case. \usepackage{fontspec} - \usepackage{polyglossia} - \setdefaultlanguage{american} - \DoTikZtrue % Loading TikZ will work (pdf) + % Loading TikZ will work (pdf) + \DoTikZtrue \else \ifluatex \ifpdf + % This is the usual pdf-version lualatex. + % We always load fontspec in this case. \usepackage{fontspec} - \usepackage{polyglossia} - \setdefaultlanguage{american} - \DoTikZtrue % Loading TikZ will work (pdf) + % Loading TikZ will work (pdf) + \DoTikZtrue \else + \loadbabeltrue + % This is dvilualatex (dvi mode). \IfFileExists{utf8-2018.def}{} {\usepackage[utf8]{inputenc}} \usepackage[TS1,T1]{fontenc} - \usepackage[american]{babel} \usepackage{lmodern} - % Using dvi-based workflows does not - % work well with TikZ; pstricks instead + % No TikZ with dvi workflows for dvi viewers. \fi \else + \loadbabeltrue + % Here we load the same packages, whether dvi + % or pdf is being used. We address that below. \IfFileExists{utf8-2018.def}{} {\usepackage[utf8]{inputenc}} \usepackage[TS1,T1]{fontenc} - \usepackage[american]{babel} \usepackage{lmodern} - \ifpdf - \usepackage{tikz} - \DoTikZtrue % Loading TikZ will work (pdf) - \fi - % Using dvi-based workflows does not - % work well with TikZ; pstricks instead + % Now we check for pdflatex. If so, use TikZ. + \ifpdf \DoTikZtrue \fi + % Otherwise, no TikZ with dvi workflows. \fi \fi -% Here one would load TikZ if needed -% \ifDoTikZ \usepackage{tikz} \fi + % Defining the \nolangs macro inhibits defaults. + \unless\ifdefined{\nolangs} + \ifloadbabel + \usepackage[american]{babel} + \else + \usepackage{polyglossia} + \setdefaultlanguage{american} + \fi + \fi + + % Defining the \noTikZ macro inhibits defaults. + \unless\ifdefined{\noTikZ} + \ifDoTikZ + \usepackage{tikz} + \else + % Do something with pstricks, pdftricks, ps4pdf. + \fi + \fi +% End of part needing to be in the preamble. \fi +% Return to normal catcodes. \makeatother + +% End of included file. %compatvb %</compat> %<*examples> %<<examplesvb - \documentclass[oneside]{article} \input{compat.tex} % Included with nameauth; needed only if @@ -14732,9 +15414,8 @@ and version 1.3 or later is part of all distributions of LaTeX version \usepackage{makeidx} % Must have for defining \seealso macro. \usepackage{index} -\usepackage[oldargs]{nameauth}[2024/02/09] +\usepackage[oldargs]{nameauth}[2025/02/04] -\usepackage[inline]{enumitem} \usepackage{fancyvrb} % Define fancyvrb defaults. @@ -14742,40 +15423,37 @@ and version 1.3 or later is part of all distributions of LaTeX version \usepackage{xcolor} \usepackage[colorlinks=true]{hyperref} + % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % Set up indexing and put margin paragraphs on the left. % + \makeindex \newindex{per}{rdx}{rnd}{Index of Persons} \renewcommand\NameauthIndex{\index[per]} \reversemarginpar -% -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -% 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. + % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % Create name shorthands. Note the use of \noexpand % in the macro arguments below. % + \begin{nameauth} - \< Doug & Frederick & Douglass & > - \< Bailey & Betsey & Bailey & > + \< Doug & Frederick & Douglass & > + \< Bailey & Betsey & Bailey & > \end{nameauth} \begin{nameauth} \< Wash & George & Washington & > + \< Bradley & Omar N. & Bradley & > \< Aris & & Aristotle & > \< Plato & & Plato & > - \< Aeth & & Æthelred, II & > - \< Sun & & Sun, Yat-sen & > + \< Aeth & & \AE thelred, II & > \< 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} @@ -14817,8 +15495,14 @@ and version 1.3 or later is part of all distributions of LaTeX version %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % Below we establish sort tags for names. % + +% Sort these names under: US Generals. +\PretagName[Omar N.]{Bradley}{US Generals!Bradley, Omar} +\PretagName[George S.]{Patton, Jr.}{US Generals!Patton, George} + % Sort these names under: US Presidents. \PretagName[George]{Washington}{US Presidents!Washington, George} +\PretagName[Dwight D.]{Eisenhower}{US Presidents!Eisenhower, Dwight D.} \PretagName[Abraham]{Lincoln}{US Presidents!Lincoln, Abraham} % Sort these names under: Philosophers. @@ -14828,71 +15512,85 @@ and version 1.3 or later is part of all distributions of LaTeX version % 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.} % Sort these names under: Europeans, historical. -\PretagName{Æthelred, II}{Europeans, historical!Aethelred 2} +\PretagName{\AE thelred, II}{Europeans, historical!Aethelred 2} \PretagName[Hernando]{de Soto} {Europeans, historical!de Soto, Hernando} + \PretagName{Vlad, Ţepeş}{Vlad Tepes} % for accented names + \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} + \PretagName[Martin]{\noexpand\textSC{Luther}}{Luther, Martin} \PretagName[Catherine \noexpand\AltCaps{d}e'] {\noexpand\textSC{Medici}}{Medici, Catherine de} + \PretagName[Thomas]{\noexpand\textSC{Jefferson}\noexpand\GEN{}} {Jefferson, Thomas} + \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} + \PretagName[\noexpand\SCIPi]{\noexpand\SCIPii} {Scipio Africanus} \PretagName[\noexpand\TSemp]{Gracchus} {Gracchus, Tiberius Sempronius} + \PretagName[Lucius]{\noexpand\CSB}{Cornelius Scipio Barbatus} + \PretagName[\noexpand\WM]{\noexpand\SHK} {Shakespeare, William} \PretagName[Robert]{\textSC{Burns}}{Burns, Robert} + \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} % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % -\title{\bfseries Some Examples} +\title{\bfseries Some \textsf{nameauth} Examples} \author{Charles P. Schaum} -\date{2024/02/09} +\date{2025/02/04} \begin{document} \maketitle @@ -14905,66 +15603,147 @@ and version 1.3 or later is part of all distributions of LaTeX version % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % + \section{Minimal Example} -\textbf{Group 1}\\ -\begin{enumerate*} +\textbf{Group 1} +\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 + \item[\textbf{3.}] \Doug\ was born in February, 1817. His earliest memories centered around the cabin of his grandmother, \Bailey. -\end{enumerate*} +\end{enumerate} -\medskip\noindent\textbf{Group 2}\\ +\medskip\noindent\textbf{Group 2} \ForgetName[Frederick]{Douglass} \ForgetName[Betsey]{Bailey} -\begin{enumerate*} +\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 + \item[\textbf{3.}] \Doug\ was born in February, 1817. 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{enumerate} + +% +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +% + +\section{Roman Names I} + +Here we modify a few details from the manual in order to make +all the name examples work well together. + +\newcommand\nri{} +\newcommand\nrii{} + +\begin{nameauth} + \< Senecai & Lucius Annaeus & Seneca\nri & > + \< Senecaii & Lucius Annaeus & Seneca\nrii & > +\end{nameauth} + +\renewcommand*\NamesFormat[1] + {#1\NameQueryInfo{}} + +\PretagName[Lucius Annaeus]{Seneca\nri}{Seneca, Lucius Annaeus 1} +\PretagName[Lucius Annaeus]{Seneca\nrii}{Seneca, Lucius Annaeus 2} +\TagName[Lucius Annaeus]{Seneca\nri}{ (the Elder)} +\TagName[Lucius Annaeus]{Seneca\nrii}{ (the Younger)} +\NameAddInfo[Lucius Annaeus]{Seneca\nri}{ the Elder} +\NameAddInfo[Lucius Annaeus]{Seneca\nrii}{ the Younger} + +We can differentiate between +\Senecai\ and \Senecaii; +\Senecai \NameQueryInfo{} and \Senecaii \NameQueryInfo{}. + +Their full index entries are:\\ +\ShowIdxPageref[Lucius Annaeus]{Seneca\nri}\\ +\ShowIdxPageref[Lucius Annaeus]{Seneca\nrii} +\index{Roman names, student} + + +\begin{nameauth} + \< CatoY & Marcus Porcius & Cato, the Younger & > + \< CatoYi & Marcus Porcius & Cato the Younger & > +\end{nameauth} +\ExcludeName[Marcus Porcius]{Cato, the Younger} +\makeatletter +\NameAddInfo[Marcus Porcius]{Cato, the Younger} + {\if@nameauth@InHook\ (Uticensis, 94--45 \textsc{bc})% + \else Uticensis\fi} +\makeatother + +\JustIndex\CatoYi +\CatoY\ is known as \CatoY\ \ForceAffix\CatoY, to distinguish him +from his great-grandfather. His names include \SCatoY[Marcus] +(\textit{praenomen}), \SCatoY[Porcius] (\textit{nomen}, one of the +Porcia clan), and \CatoY, the \textit{cognomen} by which he is best +known. His other \textit{agnomen}, \NameQueryInfo{}, means he was +born in Utica. +\JustIndex\CatoYi He is indexed as: \ShowIdxPageref*{} +\index{Roman names, student} + + +\begin{nameauth} + \< CatoE & Marcus Porcius & Cato, the Elder & > + \< CatoEi & Marcus & Porcius Cato the Elder & > +\end{nameauth} +\ExcludeName[Marcus Porcius]{Cato, the Elder} + +\JustIndex\CatoEi +\DropAffix\CatoE\ (234--149 \textsc{bc}) is known as +\CatoE{} \ForceAffix\CatoE, among other sobriquets. +His \textit{praenomen} is \SCatoE[Marcus]. His +\textit{nomen} is \SCatoE[Porcius], a member of the +Porcia clan. His \textit{cognomen} is \CatoE. +\JustIndex\CatoEi +Index: \ShowIdxPageref*{} +\index{Roman names, scholar} % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % + \section{Multiple Indexes} -The Electric Boogaloo\index{Boogaloo, Electric}\\ % main index -was created by \Name{Ollie~\& Jerry}. % name index +The Electric Boogaloo\index{Boogaloo, Electric} % main index +was created by \Name{Ollie~\& Jerry}. % name index \index{indexes, multiple} % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % + \section{Index Categories} \subsection{Famous Black Americans} -\ForgetThis\Name[Frederick]{Douglass} rose to eminence by sheer -force of character and talents that neither slavery nor caste +\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. \subsection{Patres Patriae} We mention President \Wash; again, \Wash. -Family and close friends called him \SWash.% +Family and close friends called him \SWash.\\ + \TagName[George]{Washington}{!as general} -We reminisce about \LWash[General].% +We can reminisce about \LWash[General]. \UntagName[George]{Washington} + When speaking of \Linc, we can refer to \LLinc[Abe]. \subsection{Philosophers} @@ -14974,7 +15753,6 @@ Among philosophers we consider \Plato\ and \Aris. \subsection{Historical Figures} We ponder about \Aeth, then \Aeth. -We speak of \Sun, then \Sun. We note \Soto, then just \Soto. \CapThis\Soto{} starts a sentence. @@ -14982,18 +15760,28 @@ We note \Soto, then just \Soto. \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}% +\LWash, \LIke, \LBradley, and \LPatton + were high-ranking generals.\\ +\SeeAlso\IndexRef[George]{Washington}{Eisenhower} +\SeeAlso\IndexRef[Dwight D.]{Eisenhower}{Washington} +\IncludeName*[George]{Washington} +\IncludeName*[Dwight D.]{Eisenhower} + +\UntagName[George]{Washington} +\UntagName[Dwight D.]{Eisenhower} \Wash\ and \Ike\ also were US presidents. -\small -% Instead of pre-tagging Ike we do the following: -\index[per]{US Presidents!other|see{Eisenhower, Dwight D., president}} +\ForgetName[Omar N.]{Bradley} +\ForgetName[George S.]{Patton, Jr.} +\TagName[Omar N.]{Bradley}{!colleagues of} +\TagName[George S.]{Patton, Jr.}{!colleagues of} +\IndexRef[Omar N.]{Bradley}{Eisenhower, Patton} +\IndexRef[George S.]{Patton, Jr.}{Bradley, Eisenhower} % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % + \section{More Complex Hooks} % First save main- and front-matter hooks. Then change @@ -15007,7 +15795,8 @@ We note \Soto, then just \Soto. \marginpar{\raggedleft\scriptsize #1}\fi} \index{complex hooks, intro} -The new format (front matter):\NamesInactive +\subsection{New Format, Front Matter} +\NamesInactive \Name{Vlad, III}[III Dracula], known as \IndexRef{Vlad, Ţepeş}{Vlad III} @@ -15017,7 +15806,8 @@ after his death, was the son of \Name{Vlad, II}[II Dracul], a member of the Order of the Dragon. Later instances of ``\Name*{Vlad, III}'' and ``\Name{Vlad, III}'' appear thus. -The new format (main matter):\NamesActive +\subsection{New Format, Main Matter} +\NamesActive \Name{Vlad, III}[III Dracula], known as \IndexRef{Vlad, Ţepeş}{Vlad III} @@ -15030,19 +15820,137 @@ a member of the Order of the Dragon. Later instances of \let\NamesFormat\OldFormat \let\FrontNamesFormat\OldFrontNames -We are back in the old format. +\subsection{Old Format, Front and Main} -in the front matter we see: \NamesInactive +\NamesInactive In the front matter we see: \ForgetThis\Name{Vlad, III}[III Dracula], -\Name*{Vlad, III}, and \Name{Vlad, III}. +\Name*{Vlad, III}, and \Name{Vlad, III}.\\ -in the main matter we see: \NamesActive +\NamesActive\noindent In the main matter we see: \ForgetThis\Name{Vlad, III}[III Dracula], \Name*{Vlad, III}, and \Name{Vlad, III}. % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % + +\section{Template Test} + +Here we demonstrate that fetching information by using the name pattern is better than reading the internal token registers. This is due to expansion sometimes happening in the basic interface. + +We set up the following test for our three templates, with indexing suppressed: + +\begin{itemize} + \item If we see the outcome, ``Test\dots passed'', we have success. + \item If we see the outcome, ``Test\dots'', we have failure. +\end{itemize} + +\subsection{Test Setup} + +\begingroup + +\IndexInactive +\begin{VerbatimOut}{\jobname.tmp} + \NameAddInfo{Testi}{\dots passed} + \NameAddInfo{\noexpand\testname}{\dots passed} + \newcommand\testname{Testii} + \begin{nameauth} + \< Testi & & Testi & > + \< Testii & & \noexpand\testname & > + \end{nameauth} +\end{VerbatimOut} + +\VerbatimInput[gobble=0]{\jobname.tmp} + +\input{\jobname.tmp} + +\subsection{Recommended Hook} + +We display the name, followed by the tag produced with the most recent name pattern vis: \Verb+\NameQueryInfo{}+ taking a null argument. + +\begin{VerbatimOut}{\jobname.tmp} + \renewcommand*\NamesFormat[1] + {#1\NameQueryInfo{}} +\end{VerbatimOut} + +\VerbatimInput[gobble=0]{\jobname.tmp} +\input{\jobname.tmp} + +\begin{tabular}{ll} + \Verb+\ForgetThis\Name{Testi}+ & \ForgetThis\Name{Testi} \\ + \Verb+\ForgetThis\Testi+ & \ForgetThis\Testi \\ + \Verb+\ForgetThis\Name{\noexpand\testname}+ & + \ForgetThis\Name{\noexpand\testname} \\ + \Verb+\ForgetThis\Testii+ & \ForgetThis\Testii \\ +\end{tabular} + +\subsection{Alternate Hook A} + +If we try to use the internal token registers, we have to get more complicated, and it does not always work: + +\begin{VerbatimOut}{\jobname.tmp} + \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{VerbatimOut} + +\VerbatimInput[gobble=0]{\jobname.tmp} +\input{\jobname.tmp} + +\begin{tabular}{ll} + \Verb+\ForgetThis\Name{Testi}+ & \ForgetThis\Name{Testi} \\ + \Verb+\ForgetThis\Testi+ & \ForgetThis\Testi \\ + \Verb+\ForgetThis\Name{\noexpand\testname}+ & + \ForgetThis\Name{\noexpand\testname} \\ + \Verb+\ForgetThis\Testii+ & \ForgetThis\Testii \\ +\end{tabular} + + +\subsection{Alternate Hook B} + +This is an ``older'' way of using the internal token registers. It has similar problems with consistency: + +\begin{VerbatimOut}{\jobname.tmp} + \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{VerbatimOut} + +\VerbatimInput[gobble=0]{\jobname.tmp} +\input{\jobname.tmp} + +\begin{tabular}{ll} + \Verb+\ForgetThis\Name{Testi}+ & \ForgetThis\Name{Testi} \\ + \Verb+\ForgetThis\Testi+ & \ForgetThis\Testi \\ + \Verb+\ForgetThis\Name{\noexpand\testname}+ & + \ForgetThis\Name{\noexpand\testname} \\ + \Verb+\ForgetThis\Testii+ & \ForgetThis\Testii \\ +\end{tabular} + +\endgroup + +% +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +% + \section{Life Dates in Hooks} % Add name tags to names. @@ -15064,28 +15972,27 @@ in the main matter we see: \NamesActive \renewcommand*\NamesFormat[1] {% - #1% - \ifcsname\NameauthPattern!DB\endcsname - \unless\ifNoTag - \expandafter\csname\NameauthPattern!DB\endcsname% - \fi - \global\NoTagfalse% - \fi + #1\unless\ifNoTag\NameQueryInfo{}\fi + \global\NoTagfalse% } -\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, +\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 instance 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} +\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} +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 name tag tag: \NoTagtrue\ForgetThis\Name{Atat\"urk}. @@ -15093,6 +16000,7 @@ first use, but with no name tag tag: % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % + \section{Alternate Formatting} \AltFormatActive @@ -15127,6 +16035,7 @@ murder of thousands of Huguenots. % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % + \section{Grammatical Inflections in Names} \newif\ifGenitive @@ -15149,6 +16058,7 @@ public policy and in personal affairs. % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % + \section{Sample Reference Work I} % Make a cross-reference from a variant name form to the @@ -15168,8 +16078,8 @@ public policy and in personal affairs. \newcommand{\RefArticle}[3] {% - \def\check{#2}% - \ifx\check\empty + \def\Check{#2}% + \ifx\Check\empty \noindent\ForgetThis\textsl{#1}\ #3 \else \noindent\ForgetThis\textsl{#1}\ #2\ #3 @@ -15202,7 +16112,10 @@ public policy and in personal affairs. % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % -\section{Roman Names: Student Reference} + +\section{Roman Names II} + +\subsection{General Reference} % Global Boolean flags need to be defined only once. \newif\ifNoPraenomen @@ -15260,7 +16173,7 @@ public policy and in personal affairs. \ifNoGens\XGenstrue\fi% \ifNoCognomen\XCogntrue\fi% \ifNoAgnomen\XAgnotrue\fi% - #1% + #1\NameQueryInfo{}% \global\NoPraenomenfalse% \global\NoGensfalse% \global\NoCognomenfalse% @@ -15291,36 +16204,13 @@ He flourished during the Egyptian reigns of 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 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}. \TGrac\ 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}. -% -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -% -\section{Roman Names: Scholarly Work} +\subsection{Scholarly Work} % Name variant macros need to be defined % uniquely for each name. @@ -15349,10 +16239,11 @@ and served during the Third Samnite War. % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % + \section{Reference Work II} % Boolean flags; the first sets up headwords and the second -% indicates that a nonwestern form should not be reversed. +% indicates that a Non-Western form should not be reversed. \newif\ifHeadword \newif\ifAncientName @@ -15374,22 +16265,16 @@ and served during the Third Samnite War. \ifNameauthWestern \@nameauth@RevThisCommatrue% \bfseries \NameParser% - \normalfont% - \ifcsname\NameauthPattern!DB\endcsname - \expandafter\csname\NameauthPattern!DB\endcsname% - \fi + \normalfont\NameQueryInfo{}% \else - \bgroup% + \begingroup% \bfseries \NameParser% \unless\ifAncientName \normalfont; W:\AltOff\space \@nameauth@RevThistrue \NameParser% \fi - \normalfont% - \ifcsname\NameauthPattern!DB\endcsname - \expandafter\csname\NameauthPattern!DB\endcsname% - \fi - \egroup% + \normalfont\NameQueryInfo{}% + \endgroup% \fi \else \NameParser% @@ -15404,7 +16289,8 @@ and served during the Third Samnite War. \newcommand\Headword{\Headwordtrue\ForgetThis} \renewcommand{\RefArticle}[2] {% - \noindent\Headword #1 #2% + \noindent\Headword #1 #2 + \medskip } \index{reference work} @@ -15430,6 +16316,7 @@ Engine. \Name[Ada]{\noexpand\textIT{Lovelace}}\dots} % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % + \section{Marginalia} % Global Boolean flags need to be defined only once. @@ -15519,7 +16406,8 @@ in the 1800s, \Revert\Shak\ became known as ``\Shak''. % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % -\section{Customization, Easy} + +\section{Customization Using Internals} \makeatletter \newcommand*\Fbox[1]{% @@ -15542,7 +16430,10 @@ among American Indian nations after 1837. We can show the forms % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % -\section{Customization, Complicated} + +\section{Customization Using Separate Macros} + +We do not show this section in the manual because it starts to go farther afield of the main focus of \textsf{nameauth}. Nevertheless, we show it for completeness. \newif\ifFbox % Replaces \if@nameauth@DoAlt \AltOn \AltOff \newif\ifFirstCap % Replaces \if@nameauth@DoCaps \AltCaps @@ -15624,7 +16515,10 @@ murder of thousands of Huguenots. % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % -\section{Customization, Complete} + +\section{Full Customization} + +We do not go into this much detail in the manual because it starts to go farther afield of the main focus of \textsf{nameauth}. Nevertheless, we show it for completeness. \subsection[With xparse]{With \textsf{xparse}} @@ -15633,28 +16527,16 @@ murder of thousands of Huguenots. % Change the general-case name macro to show % a name in a framed, colored box. -\NewDocumentCommand{\MyName}{O{} m O{}}{% - \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]}% -} +\NewDocumentCommand{\MyName}{O{} m O{}} + {\fcolorbox{black}{gray!25!white}{\@nameauth@Name[#1]{#2}[#3]}} % Likewise change the macro for when names are forced long. -\NewDocumentCommand{\MyLName}{O{} m O{}}{% - \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]}% -} +\NewDocumentCommand{\MyLName}{O{} m O{}} + {\fcolorbox{black}{green!25!white}{\@nameauth@Name[#1]{#2}[#3]}} % Likewise change the macro when personal names are desired. -\NewDocumentCommand{\MyFName}{O{} m O{}}{% - \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]}% -} +\NewDocumentCommand{\MyFName}{O{} m O{}} + {\fcolorbox{black}{yellow!25!white}{\@nameauth@Name[#1]{#2}[#3]}} \makeatother % Change the formatting hooks, but do not use alternate. @@ -15686,32 +16568,19 @@ century; \Name*[Adolf von]{Harnack}; \FName[Adolf]{Harnack}. \subsection[With xargs]{With \textsf{xargs}} \makeatletter - % Change the general-case name macro to show % a name in a framed, colored box. -\renewcommandx\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]}% -} +\renewcommandx\MyName[3][1=\empty, 3=\empty] + {\fcolorbox{black}{gray!25!white}{\@nameauth@Name[#1]{#2}[#3]}} % Likewise change the macro for when names are forced long. -\renewcommandx\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]}% -} +\renewcommandx\MyLName[3][1=\empty, 3=\empty] + {\fcolorbox{black}{green!25!white}{\@nameauth@Name[#1]{#2}[#3]}} % Likewise change the macro when personal names are desired. -\renewcommandx\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]}% -} +\renewcommandx\MyFName[3][1=\empty, 3=\empty] + {\fcolorbox{black}{yellow!25!white}{\@nameauth@Name[#1]{#2}[#3]}} \makeatother % Change the formatting hooks, but do not use alternate. @@ -15743,20 +16612,23 @@ century; \Name*[Adolf von]{Harnack}; \FName[Adolf]{Harnack}. % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % + \section{\protect\LaTeX\ Engines} -We use \texttt{american} for the language; one should use one's own. -We use Latin Modern for the font; that should be changed at the user's -discretion. We could load \textsf{tikz} using -\texttt{\textbackslash ifDoTikZ} to avoid crashing some \texttt{dvi} -viewers in a \texttt{dvi}-only workflow. Below we list the salient -points from \texttt{compat.tex}, included with \textsf{nameauth}. +\subsection{\protect\texttt{compat.tex}} + +One can define \Verb+\nolangs+ before loading the file below to inhibit +the default language loading. We use Latin Modern for the font to get +a consistent look. Below we list the salient cross-engine points from +\texttt{compat.tex}, included with \textsf{nameauth}. \index{\protect\LaTeX\ engines} \begin{quote}\small - \VerbatimInput[gobble=0, firstline=29]{compat.tex} + \VerbatimInput[gobble=0, firstline=24]{compat.tex} \end{quote} +\subsection{Check Engine Tests} + 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 @@ -15795,8 +16667,6 @@ or just the body text to work under multiple engines: \fi \end{Verbatim} -\newpage - \begin{Verbatim} \unless\ifxetex \unless\ifluatex @@ -15816,33 +16686,38 @@ or just the body text to work under multiple engines: % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % + \section{Miscellaneous Tests: Spaces} Here we test to see if any unwanted spaces exist in macros that take -name arguments. If everything is OK, one should see two vertical bars +name arguments. If everything is OK, one should see two vertical bars \texttt{||} where no output in the text is produced, or no spaces between an enclosed name and the bars. This section also tests if most possible argument combinations work in most macros that take name arguments. +\subsection{Western Name with Suffix} + \begin{quote} -\Verb+\Name[FNNa]{SNNa,Affix}[Alternate]+\dotfill - |\Name[FNNa]{SNNa,Affix}[Alternate]|\\ -\Verb+\Name*[FNNa]{SNNa,Affix}+\dotfill - |\Name*[FNNa]{SNNa,Affix}|\\ -\Verb+\DropAffix\Name*[FNNa]{SNNa,Affix}[Alternate]+\dotfill - |\DropAffix\Name*[FNNa]{SNNa,Affix}[Alternate]|\\ -\Verb+\DropAffix\Name*[FNNa]{SNNa,Affix}+\dotfill - |\DropAffix\Name*[FNNa]{SNNa,Affix}|\\ -\Verb+\Name[FNNa]{SNNa,Affix}[Alternate]+\dotfill - |\Name[FNNa]{SNNa,Affix}[Alternate]|\\ -\Verb+\Name[FNNa]{SNNa,Affix}+\dotfill - |\Name[FNNa]{SNNa,Affix}|\\ -\Verb+\FName[FNNa]{SNNa,Affix}[Alternate]+\dotfill - |\FName[FNNa]{SNNa,Affix}[Alternate]|\\ -\Verb+\FName[FNNa]{SNNa,Affix}+\dotfill - |\FName[FNNa]{SNNa,Affix}| +\Verb+\Name[FNNa]{SNNa, Affix}[Alternate]+\dotfill + |\Name[FNNa]{SNNa, Affix}[Alternate]|\\ +\Verb+\Name*[FNNa]{SNNa, Affix}+\dotfill + |\Name*[FNNa]{SNNa, Affix}|\\ +\Verb+\DropAffix\Name*[FNNa]{SNNa, Affix}[Alternate]+\dotfill + |\DropAffix\Name*[FNNa]{SNNa, Affix}[Alternate]|\\ +\Verb+\DropAffix\Name*[FNNa]{SNNa, Affix}+\dotfill + |\DropAffix\Name*[FNNa]{SNNa, Affix}|\\ +\Verb+\Name[FNNa]{SNNa, Affix}[Alternate]+\dotfill + |\Name[FNNa]{SNNa, Affix}[Alternate]|\\ +\Verb+\Name[FNNa]{SNNa, Affix}+\dotfill + |\Name[FNNa]{SNNa, Affix}|\\ +\Verb+\FName[FNNa]{SNNa, Affix}[Alternate]+\dotfill + |\FName[FNNa]{SNNa, Affix}[Alternate]|\\ +\Verb+\FName[FNNa]{SNNa, Affix}+\dotfill + |\FName[FNNa]{SNNa, Affix}| \end{quote} +\subsection{Western Name without Suffix} + \begin{quote} \Verb+\Name[FNNb]{SNNb}[Alternate]+\dotfill |\Name[FNNb]{SNNb}[Alternate]|\\ @@ -15858,25 +16733,29 @@ possible argument combinations work in most macros that take name arguments. |\FName[FNNb]{SNNb}| \end{quote} +\subsection{Non-Western Name, Current Syntax} + \begin{quote} -\Verb+\Name{SNNc,Affix}[Alternate]+\dotfill - |\Name{SNNc,Affix}[Alternate]|\\ -\Verb+\Name*{SNNc,Affix}+\dotfill - |\Name*{SNNc,Affix}|\\ -\Verb+\Name{SNNc,Affix}[Alternate]+\dotfill - |\Name{SNNc,Affix}[Alternate]|\\ -\Verb+\Name{SNNc,Affix}+\dotfill - |\Name{SNNc,Affix}|\\ -\Verb+\FName{SNNc,Affix}[Alternate]+\dotfill - |\FName{SNNc,Affix}[Alternate]|\\ -\Verb+\FName{SNNc,Affix}+\dotfill - |\FName{SNNc,Affix}|\\ -\Verb+\ForceFN\FName{SNNc,Affix}[Alternate]+\dotfill - |\ForceFN\FName{SNNc,Affix}[Alternate]|\\ -\Verb+\ForceFN\FName{SNNc,Affix}+\dotfill - |\ForceFN\FName{SNNc,Affix}| +\Verb+\Name{SNNc, Affix}[Alternate]+\dotfill + |\Name{SNNc, Affix}[Alternate]|\\ +\Verb+\Name*{SNNc, Affix}+\dotfill + |\Name*{SNNc, Affix}|\\ +\Verb+\Name{SNNc, Affix}[Alternate]+\dotfill + |\Name{SNNc, Affix}[Alternate]|\\ +\Verb+\Name{SNNc, Affix}+\dotfill + |\Name{SNNc, Affix}|\\ +\Verb+\FName{SNNc, Affix}[Alternate]+\dotfill + |\FName{SNNc, Affix}[Alternate]|\\ +\Verb+\FName{SNNc, Affix}+\dotfill + |\FName{SNNc, Affix}|\\ +\Verb+\ForceFN\FName{SNNc, Affix}[Alternate]+\dotfill + |\ForceFN\FName{SNNc, Affix}[Alternate]|\\ +\Verb+\ForceFN\FName{SNNc, Affix}+\dotfill + |\ForceFN\FName{SNNc, Affix}| \end{quote} +\subsection{Non-Western Name, Obsolete Syntax} + \begin{quote} \Verb+\Name{SNNd}[Alternate]+\dotfill |\Name{SNNd}[Alternate]|\\ @@ -15890,296 +16769,327 @@ possible argument combinations work in most macros that take name arguments. |\ForceFN\FName{SNNd}[Alternate]| \end{quote} +\subsection{Working with All Forms} + +\subsubsection{Index Names and Xrefs} + \begin{quote} -\Verb+\IndexName[FNNe]{SNNe,Affix}[Alternate]+\dotfill - |\IndexName[FNNe]{SNNe,Affix}[Alternate]|\\ -\Verb+\IndexName[FNNe]{SNNe,Affix}+\dotfill - |\IndexName[FNNe]{SNNe,Affix}|\\ -\Verb+\IndexName{SNNf,Affix}[Alternate]+\dotfill - |\IndexName{SNNf,Affix}[Alternate]|\\ -\Verb+\IndexName{SNNf,Affix}+\dotfill - |\IndexName{SNNf,Affix}|\\ +\Verb+\IndexName[FNNe]{SNNe, Affix}[Alternate]+\dotfill + |\IndexName[FNNe]{SNNe, Affix}[Alternate]|\\ +\Verb+\IndexName[FNNe]{SNNe, Affix}+\dotfill + |\IndexName[FNNe]{SNNe, Affix}|\\ +\Verb+\IndexName{SNNf, Affix}[Alternate]+\dotfill + |\IndexName{SNNf, Affix}[Alternate]|\\ +\Verb+\IndexName{SNNf, Affix}+\dotfill + |\IndexName{SNNf, Affix}|\\ \Verb+\IndexName{SNNf}[Alternate]+\dotfill |\IndexName{SNNf}[Alternate]| \end{quote} \begin{quote} -\Verb+\IndexRef[FNNg]{SNNg,Affix}[Alternate]{Target}+\dotfill - |\IndexRef[FNNg]{SNNg,Affix}[Alternate]{Target}|\\ -\Verb+\IndexRef[FNNg]{SNNg,Affix}{Target}+\dotfill - |\IndexRef[FNNg]{SNNg,Affix}{Target}|\\ -\Verb+\IndexRef{SNNh,Affix}[Alternate]{Target}+\dotfill - |\IndexRef{SNNh,Affix}[Alternate]{Target}|\\ -\Verb+\IndexRef{SNNh,Affix}{Target}+\dotfill - |\IndexRef{SNNh,Affix}{Target}|\\ +\Verb+\IndexRef[FNNg]{SNNg, Affix}[Alternate]{Target}+\dotfill + |\IndexRef[FNNg]{SNNg, Affix}[Alternate]{Target}|\\ +\Verb+\IndexRef[FNNg]{SNNg, Affix}{Target}+\dotfill + |\IndexRef[FNNg]{SNNg, Affix}{Target}|\\ +\Verb+\IndexRef{SNNh, Affix}[Alternate]{Target}+\dotfill + |\IndexRef{SNNh, Affix}[Alternate]{Target}|\\ +\Verb+\IndexRef{SNNh, Affix}{Target}+\dotfill + |\IndexRef{SNNh, Affix}{Target}|\\ \Verb+\IndexRef{SNNh}[Alternate]{Target}+\dotfill |\IndexRef{SNNh}[Alternate]{Target}| \end{quote} +\subsubsection{Excluding and Including} + \begin{quote} -\Verb+\ExcludeName[FNNi]{SNNi,Affix}[Alternate]+\dotfill - |\ExcludeName[FNNi]{SNNi,Affix}[Alternate]|\\ -\Verb+\ExcludeName[FNNi]{SNNi,Affix}+\dotfill - |\ExcludeName[FNNi]{SNNi,Affix}|\\ -\Verb+\ExcludeName{SNNj,Affix}[Alternate]+\dotfill - |\ExcludeName{SNNj,Affix}[Alternate]|\\ -\Verb+\ExcludeName{SNNj,Affix}+\dotfill - |\ExcludeName{SNNj,Affix}|\\ +\Verb+\ExcludeName[FNNi]{SNNi, Affix}[Alternate]+\dotfill + |\ExcludeName[FNNi]{SNNi, Affix}[Alternate]|\\ +\Verb+\ExcludeName[FNNi]{SNNi, Affix}+\dotfill + |\ExcludeName[FNNi]{SNNi, Affix}|\\ +\Verb+\ExcludeName{SNNj, Affix}[Alternate]+\dotfill + |\ExcludeName{SNNj, Affix}[Alternate]|\\ +\Verb+\ExcludeName{SNNj, Affix}+\dotfill + |\ExcludeName{SNNj, Affix}|\\ \Verb+\ExcludeName{SNNj}[Alternate]+\dotfill |\ExcludeName{SNNj}[Alternate]| \end{quote} \begin{quote} -\Verb+\IncludeName[FNNi]{SNNi,Affix}[Alternate]+\dotfill - |\IncludeName[FNNi]{SNNi,Affix}[Alternate]|\\ -\Verb+\IncludeName[FNNi]{SNNi,Affix}+\dotfill - |\IncludeName[FNNi]{SNNi,Affix}|\\ -\Verb+\IncludeName{SNNj,Affix}[Alternate]+\dotfill - |\IncludeName{SNNj,Affix}[Alternate]|\\ -\Verb+\IncludeName{SNNj,Affix}+\dotfill - |\IncludeName{SNNj,Affix}|\\ +\Verb+\IncludeName[FNNi]{SNNi, Affix}[Alternate]+\dotfill + |\IncludeName[FNNi]{SNNi, Affix}[Alternate]|\\ +\Verb+\IncludeName[FNNi]{SNNi, Affix}+\dotfill + |\IncludeName[FNNi]{SNNi, Affix}|\\ +\Verb+\IncludeName{SNNj, Affix}[Alternate]+\dotfill + |\IncludeName{SNNj, Affix}[Alternate]|\\ +\Verb+\IncludeName{SNNj, Affix}+\dotfill + |\IncludeName{SNNj, Affix}|\\ \Verb+\IncludeName{SNNj}[Alternate]+\dotfill |\IncludeName{SNNj}[Alternate]| \end{quote} \begin{quote} -\Verb+\IncludeName*[FNNi]{SNNi,Affix}[Alternate]+\dotfill - |\IncludeName*[FNNi]{SNNi,Affix}[Alternate]|\\ -\Verb+\IncludeName*[FNNi]{SNNi,Affix}+\dotfill - |\IncludeName*[FNNi]{SNNi,Affix}|\\ -\Verb+\IncludeName*{SNNj,Affix}[Alternate]+\dotfill - |\IncludeName*{SNNj,Affix}[Alternate]|\\ -\Verb+\IncludeName*{SNNj,Affix}+\dotfill - |\IncludeName*{SNNj,Affix}|\\ +\Verb+\IncludeName*[FNNi]{SNNi, Affix}[Alternate]+\dotfill + |\IncludeName*[FNNi]{SNNi, Affix}[Alternate]|\\ +\Verb+\IncludeName*[FNNi]{SNNi, Affix}+\dotfill + |\IncludeName*[FNNi]{SNNi, Affix}|\\ +\Verb+\IncludeName*{SNNj, Affix}[Alternate]+\dotfill + |\IncludeName*{SNNj, Affix}[Alternate]|\\ +\Verb+\IncludeName*{SNNj, Affix}+\dotfill + |\IncludeName*{SNNj, Affix}|\\ \Verb+\IncludeName*{SNNj}[Alternate]+\dotfill |\IncludeName*{SNNj}[Alternate]| \end{quote} +\subsubsection{Index Sorting} + \begin{quote} -\Verb+\PretagName[FNNk]{SNNk,Affix}[Alternate]{Sorta}+\dotfill - |\PretagName[FNNk]{SNNk,Affix}[Alternate]{Sorta}|\\ -\Verb+\PretagName[FNNl]{SNNl,Affix}{Sortb}+\dotfill - |\PretagName[FNNl]{SNNl,Affix}{Sortb}|\\ -\Verb+\PretagName{SNNm,Affix}[Alternate]{Sortc}+\dotfill - |\PretagName{SNNm,Affix}[Alternate]{Sortc}|\\ -\Verb+\PretagName{SNNn,Affix}{Sortd}+\dotfill - |\PretagName{SNNn,Affix}{Sortd}|\\ +\Verb+\PretagName[FNNk]{SNNk, Affix}[Alternate]{Sorta}+\dotfill + |\PretagName[FNNk]{SNNk, Affix}[Alternate]{Sorta}|\\ +\Verb+\PretagName[FNNl]{SNNl, Affix}{Sortb}+\dotfill + |\PretagName[FNNl]{SNNl, Affix}{Sortb}|\\ +\Verb+\PretagName{SNNm, Affix}[Alternate]{Sortc}+\dotfill + |\PretagName{SNNm, Affix}[Alternate]{Sortc}|\\ +\Verb+\PretagName{SNNn, Affix}{Sortd}+\dotfill + |\PretagName{SNNn, Affix}{Sortd}|\\ \Verb+\PretagName{SNNo}[Alternate]{Sorte}+\dotfill |\PretagName{SNNo}[Alternate]{Sorte}| \end{quote} +\subsubsection{Index Tagging and Untagging} + \begin{quote} -\Verb+\TagName[FNNa]{SNNa,Affix}[Alternate]{Tag}+\dotfill - |\TagName[FNNa]{SNNa,Affix}[Alternate]{Tag}|\\ -\Verb+\TagName[FNNa]{SNNa,Affix}{Tag}+\dotfill - |\TagName[FNNa]{SNNa,Affix}{Tag}|\\ +\Verb+\TagName[FNNa]{SNNa, Affix}[Alternate]{Tag}+\dotfill + |\TagName[FNNa]{SNNa, Affix}[Alternate]{Tag}|\\ +\Verb+\TagName[FNNa]{SNNa, Affix}{Tag}+\dotfill + |\TagName[FNNa]{SNNa, Affix}{Tag}|\\ \Verb+\TagName[FNNb]{SNNb}[Alternate]{Tag}+\dotfill |\TagName[FNNb]{SNNb}[Alternate]{Tag}|\\ \Verb+\TagName[FNNb]{SNNb}{Tag}+\dotfill - |\TagName[FNNb]{SNNb,Affix}{Tag}|\\ -\Verb+\TagName{SNNc,Affix}[Alternate]{Tag}+\dotfill - |\TagName{SNNc,Affix}[Alternate]{Tag}|\\ -\Verb+\TagName{SNNc,Affix}{Tag}+\dotfill - |\TagName{SNNc,Affix}{Tag}|\\ + |\TagName[FNNb]{SNNb, Affix}{Tag}|\\ +\Verb+\TagName{SNNc, Affix}[Alternate]{Tag}+\dotfill + |\TagName{SNNc, Affix}[Alternate]{Tag}|\\ +\Verb+\TagName{SNNc, Affix}{Tag}+\dotfill + |\TagName{SNNc, Affix}{Tag}|\\ \Verb+\TagName{SNNd}[Alternate]{Tag}+\dotfill |\TagName{SNNd}[Alternate]{Tag}| \end{quote} \begin{quote} -\Verb+\UntagName[FNNa]{SNNa,Affix}[Alternate]+\dotfill - |\UntagName[FNNa]{SNNa,Affix}[Alternate]|\\ -\Verb+\UntagName[FNNa]{SNNa,Affix}+\dotfill - |\UntagName[FNNa]{SNNa,Affix}|\\ +\Verb+\UntagName[FNNa]{SNNa, Affix}[Alternate]+\dotfill + |\UntagName[FNNa]{SNNa, Affix}[Alternate]|\\ +\Verb+\UntagName[FNNa]{SNNa, Affix}+\dotfill + |\UntagName[FNNa]{SNNa, Affix}|\\ \Verb+\UntagName[FNNb]{SNNb}[Alternate]+\dotfill |\UntagName[FNNb]{SNNb}[Alternate]|\\ \Verb+\UntagName[FNNb]{SNNb}+\dotfill - |\UntagName[FNNb]{SNNb,Affix}|\\ -\Verb+\UntagName{SNNc,Affix}[Alternate]+\dotfill - |\UntagName{SNNc,Affix}[Alternate]|\\ -\Verb+\UntagName{SNNc,Affix}+\dotfill - |\UntagName{SNNc,Affix}|\\ + |\UntagName[FNNb]{SNNb, Affix}|\\ +\Verb+\UntagName{SNNc, Affix}[Alternate]+\dotfill + |\UntagName{SNNc, Affix}[Alternate]|\\ +\Verb+\UntagName{SNNc, Affix}+\dotfill + |\UntagName{SNNc, Affix}|\\ \Verb+\UntagName{SNNd}[Alternate]+\dotfill |\UntagName{SNNd}[Alternate]| \end{quote} +\subsubsection{Name Info} + \begin{quote} -\Verb+\NameAddInfo[FNNa]{SNNa,Affix}[Alternate]{Info1}+\dotfill - |\NameAddInfo[FNNa]{SNNa,Affixa}[Alternate]{Info1}|\\ -\Verb+\NameAddInfo[FNNa]{SNNa,Affix}{Info2}+\dotfill - |\NameAddInfo[FNNa]{SNNa,Affix}{Info2}|\\ +\Verb+\NameAddInfo[FNNa]{SNNa, Affix}[Alternate]{Info1}+\dotfill + |\NameAddInfo[FNNa]{SNNa, Affixa}[Alternate]{Info1}|\\ +\Verb+\NameAddInfo[FNNa]{SNNa, Affix}{Info2}+\dotfill + |\NameAddInfo[FNNa]{SNNa, Affix}{Info2}|\\ \Verb+\NameAddInfo[FNNb]{SNNb}[Alternate]{Info3}+\dotfill |\NameAddInfo[FNNb]{SNNb}[Alternate]{Info3}|\\ \Verb+\NameAddInfo[FNNb]{SNNb}{Info4}+\dotfill |\NameAddInfo[FNNb]{SNNb}{Info4}|\\ -\Verb+\NameAddInfo{SNNc,Affix}[Alternate]{Info5}+\dotfill - |\NameAddInfo{SNNc,Affix}[Alternate]{Info5}|\\ -\Verb+\NameAddInfo{SNNc,Affix}{Info6}+\dotfill - |\NameAddInfo{SNNc,Affix}{Info6}|\\ +\Verb+\NameAddInfo{SNNc, Affix}[Alternate]{Info5}+\dotfill + |\NameAddInfo{SNNc, Affix}[Alternate]{Info5}|\\ +\Verb+\NameAddInfo{SNNc, Affix}{Info6}+\dotfill + |\NameAddInfo{SNNc, Affix}{Info6}|\\ \Verb+\NameAddInfo{SNNd}[Alternate]{Info7}+\dotfill |\NameAddInfo{SNNd}[Alternate]{Info7}| \end{quote} \begin{quote} -\Verb+\NameQueryInfo[FNNa]{SNNa,Affix}[Alternate]+\dotfill - |\NameQueryInfo[FNNa]{SNNa,Affix}[Alternate]|\\ -\Verb+\NameQueryInfo[FNNa]{SNNa,Affix}+\dotfill - |\NameQueryInfo[FNNa]{SNNa,Affix}|\\ +\Verb+\NameQueryInfo[FNNa]{SNNa, Affix}[Alternate]+\dotfill + |\NameQueryInfo[FNNa]{SNNa, Affix}[Alternate]|\\ +\Verb+\NameQueryInfo[FNNa]{SNNa, Affix}+\dotfill + |\NameQueryInfo[FNNa]{SNNa, Affix}|\\ \Verb+\NameQueryInfo[FNNb]{SNNb}[Alternate]+\dotfill |\NameQueryInfo[FNNb]{SNNb}[Alternate]|\\ \Verb+\NameQueryInfo[FNNb]{SNNb}+\dotfill |\NameQueryInfo[FNNb]{SNNb}|\\ -\Verb+\NameQueryInfo{SNNc,Affix}[Alternate]+\dotfill - |\NameQueryInfo{SNNc,Affix}[Alternate]|\\ -\Verb+\NameQueryInfo{SNNc,Affix}+\dotfill - |\NameQueryInfo{SNNc,Affix}|\\ +\Verb+\NameQueryInfo{SNNc, Affix}[Alternate]+\dotfill + |\NameQueryInfo{SNNc, Affix}[Alternate]|\\ +\Verb+\NameQueryInfo{SNNc, Affix}+\dotfill + |\NameQueryInfo{SNNc, Affix}|\\ \Verb+\NameQueryInfo{SNNd}[Alternate]+\dotfill |\NameQueryInfo{SNNd}[Alternate]| \end{quote} \begin{quote} -\Verb+\NameClearInfo[FNNa]{SNNa,Affix}[Alternate]+\dotfill - |\NameClearInfo[FNNa]{SNNa,Affix}[Alternate]|\\ -\Verb+\NameClearInfo[FNNa]{SNNa,Affix}+\dotfill - |\NameClearInfo[FNNa]{SNNa,Affix}|\\ +\Verb+\NameClearInfo[FNNa]{SNNa, Affix}[Alternate]+\dotfill + |\NameClearInfo[FNNa]{SNNa, Affix}[Alternate]|\\ +\Verb+\NameClearInfo[FNNa]{SNNa, Affix}+\dotfill + |\NameClearInfo[FNNa]{SNNa, Affix}|\\ \Verb+\NameClearInfo[FNNb]{SNNb}[Alternate]+\dotfill |\NameClearInfo[FNNb]{SNNb}[Alternate]|\\ \Verb+\NameClearInfo[FNNb]{SNNb}+\dotfill |\NameClearInfo[FNNb]{SNNb}|\\ -\Verb+\NameClearInfo{SNNc,Affix}[Alternate]+\dotfill - |\NameClearInfo{SNNc,Affix}[Alternate]|\\ -\Verb+\NameClearInfo{SNNc,Affix}+\dotfill - |\NameClearInfo{SNNc,Affix}|\\ +\Verb+\NameClearInfo{SNNc, Affix}[Alternate]+\dotfill + |\NameClearInfo{SNNc, Affix}[Alternate]|\\ +\Verb+\NameClearInfo{SNNc, Affix}+\dotfill + |\NameClearInfo{SNNc, Affix}|\\ \Verb+\NameClearInfo{SNNd}[Alternate]+\dotfill |\NameClearInfo{SNNd}[Alternate]| \end{quote} +\subsubsection{Forgetting, Global} + \begin{quote} -\Verb+\ForgetName[FNNa]{SNNa,Affix}[Alternate]+\dotfill - |\ForgetName[FNNa]{SNNa,Affix}[Alternate]|\\ -\Verb+\ForgetName[FNNa]{SNNa,Affix}+\dotfill - |\ForgetName[FNNa]{SNNa,Affix}|\\ +\Verb+\ForgetName[FNNa]{SNNa, Affix}[Alternate]+\dotfill + |\ForgetName[FNNa]{SNNa, Affix}[Alternate]|\\ +\Verb+\ForgetName[FNNa]{SNNa, Affix}+\dotfill + |\ForgetName[FNNa]{SNNa, Affix}|\\ \Verb+\ForgetName[FNNb]{SNNb}[Alternate]+\dotfill |\ForgetName[FNNb]{SNNb}[Alternate]|\\ \Verb+\ForgetName[FNNb]{SNNb}+\dotfill |\ForgetName[FNNb]{SNNb}|\\ -\Verb+\ForgetName{SNNc,Affix}[Alternate]+\dotfill - |\ForgetName{SNNc,Affix}[Alternate]|\\ -\Verb+\ForgetName{SNNc,Affix}+\dotfill - |\ForgetName{SNNc,Affix}|\\ +\Verb+\ForgetName{SNNc, Affix}[Alternate]+\dotfill + |\ForgetName{SNNc, Affix}[Alternate]|\\ +\Verb+\ForgetName{SNNc, Affix}+\dotfill + |\ForgetName{SNNc, Affix}|\\ \Verb+\ForgetName{SNNd}[Alternate]+\dotfill |\ForgetName{SNNd}[Alternate]| \end{quote} +\subsubsection{Subverting, Local} + \begin{quote} \Verb+\LocalNames+\LocalNames\\ -\Verb+\SubvertName[FNNa]{SNNa,Affix}[Alternate]+\dotfill - |\SubvertName[FNNa]{SNNa,Affix}[Alternate]|\\ +\Verb+\SubvertName[FNNa]{SNNa, Affix}[Alternate]+\dotfill + |\SubvertName[FNNa]{SNNa, Affix}[Alternate]|\\ \Verb+\SubvertName[FNNb]{SNNb}[Alternate]+\dotfill |\SubvertName[FNNb]{SNNb}[Alternate]|\\ -\Verb+\SubvertName{SNNc,Affix}[Alternate]+\dotfill - |\SubvertName{SNNc,Affix}[Alternate]|\\ +\Verb+\SubvertName{SNNc, Affix}[Alternate]+\dotfill + |\SubvertName{SNNc, Affix}[Alternate]|\\ \Verb+\SubvertName{SNNd}[Alternate]+\dotfill |\SubvertName{SNNd}[Alternate]|\\ \Verb+\GlobalNames+\GlobalNames \end{quote} +\subsubsection{Name Conditionals} + \begin{quote} -\Verb+\IfMainName[FNNa]{SNNa,Affix}{Y}{N}+\dotfill - |\IfMainName[FNNa]{SNNa,Affix}{Y}{N}|\\ +\Verb+\IfMainName[FNNa]{SNNa, Affix}{Y}{N}+\dotfill + |\IfMainName[FNNa]{SNNa, Affix}{Y}{N}|\\ \Verb+\IfMainName[FNNb]{SNNb}{Y}{N}+\dotfill |\IfMainName[FNNb]{SNNb}{Y}{N}|\\ -\Verb+\IfMainName{SNNc,Affix}{Y}{N}+\dotfill - |\IfMainName{SNNc,Affix}{Y}{N}|\\ +\Verb+\IfMainName{SNNc, Affix}{Y}{N}+\dotfill + |\IfMainName{SNNc, Affix}{Y}{N}|\\ \Verb+\IfMainName{SNNd}[Alternate]{Y}{N}+\dotfill |\IfMainName{SNNd}[Alternate]{Y}{N}| \end{quote} \begin{quote} -\Verb+\IfFrontName[FNNa]{SNNa,Affix}[Alternate]{Y}{N}+\dotfill - |\IfFrontName[FNNa]{SNNa,Affix}[Alternate]{Y}{N}|\\ +\Verb+\IfFrontName[FNNa]{SNNa, Affix}[Alternate]{Y}{N}+\dotfill + |\IfFrontName[FNNa]{SNNa, Affix}[Alternate]{Y}{N}|\\ \Verb+\IfFrontName[FNNb]{SNNb}[Alternate]{Y}{N}+\dotfill |\IfFrontName[FNNb]{SNNb}[Alternate]{Y}{N}|\\ -\Verb+\IfFrontName{SNNc,Affix}[Alternate]{Y}{N}+\dotfill - |\IfFrontName{SNNc,Affix}[Alternate]{Y}{N}|\\ +\Verb+\IfFrontName{SNNc, Affix}[Alternate]{Y}{N}+\dotfill + |\IfFrontName{SNNc, Affix}[Alternate]{Y}{N}|\\ \Verb+\IfFrontName{SNNd}[Alternate]{Y}{N}+\dotfill |\IfFrontName{SNNd}[Alternate]{Y}{N}| \end{quote} \begin{quote} -\Verb+\SeeAlso\IndexRef[FNNp]{SNNp,Affix}{Target}+\dotfill - |\SeeAlso\IndexRef[FNNp]{SNNp,Affix}{Target}|\\ -\Verb+\ExcludeName{SNNq,Affix}+\dotfill - |\ExcludeName{SNNq,Affix}|\\ -\Verb+\IfAKA[FNNp]{SNNp,Affix}[Alternate]{Y}{N}{X}+\dotfill - |\IfAKA[FNNp]{SNNp,Affix}[Alternate]{Y}{N}{X}|\\ -\Verb+\IfAKA[FNNp]{SNNp,Affix}{Y}{N}{X}+\dotfill - |\IfAKA[FNNp]{SNNp,Affix}{Y}{N}{X}|\\ -\Verb+\IfAKA{SNNq,Affix}[Alternate]{Y}{N}{X}+\dotfill - |\IfAKA{SNNq,Affix}[Alternate]{Y}{N}{X}|\\ -\Verb+\IfAKA{SNNq,Affix}{Y}{N}{X}+\dotfill - |\IfAKA{SNNq,Affix}{Y}{N}{X}|\\ +\Verb+\SeeAlso\IndexRef[FNNp]{SNNp, Affix}{Target}+\dotfill + |\SeeAlso\IndexRef[FNNp]{SNNp, Affix}{Target}|\\ +\Verb+\ExcludeName{SNNq, Affix}+\dotfill + |\ExcludeName{SNNq, Affix}|\\ +\Verb+\IfAKA[FNNp]{SNNp, Affix}[Alternate]{Y}{N}{X}+\dotfill + |\IfAKA[FNNp]{SNNp, Affix}[Alternate]{Y}{N}{X}|\\ +\Verb+\IfAKA[FNNp]{SNNp, Affix}{Y}{N}{X}+\dotfill + |\IfAKA[FNNp]{SNNp, Affix}{Y}{N}{X}|\\ +\Verb+\IfAKA{SNNq, Affix}[Alternate]{Y}{N}{X}+\dotfill + |\IfAKA{SNNq, Affix}[Alternate]{Y}{N}{X}|\\ +\Verb+\IfAKA{SNNq, Affix}{Y}{N}{X}+\dotfill + |\IfAKA{SNNq, Affix}{Y}{N}{X}|\\ \Verb+\IfAKA{SNNr}[Alternate]{Y}{N}{X}+\dotfill |\IfAKA{SNNr}[Alternate]{Y}{N}{X}| \end{quote} +\subsubsection{Pseudonym Syntax: The Horror} + +\begin{quote} +\Verb+\AKA[FNN1]{SNN1, Affix1}%+\\ +\Verb+ [FNN2]{SNN2, Affix2}[Alternate2]+\dotfill + |\AKA[FNN1]{SNN1, Affix1}[FNN2]{SNN2, Affix2}[Alternate2]|\\ +\Verb+\AKA[FNN1]{SNN1, Affix1}%+\\ +\Verb+ [FNN2]{SNN2, Affix2}+\dotfill + |\AKA[FNN1]{SNN1, Affix1}[FNN2]{SNN2, Affix2}|\\ +\Verb+\DropAffix\AKA[FNN1]{SNN1, Affix1}%+\\ +\Verb+ [FNN2]{SNN2, Affix2}+\dotfill + |\DropAffix\AKA[FNN1]{SNN1, Affix1}[FNN2]{SNN2, Affix2}|\\ +\Verb+\AKA*[FNN1]{SNN1, Affix1}%+\\ +\Verb+ [FNN2]{SNN2, Affix2}[Alternate2]+\dotfill + |\AKA*[FNN1]{SNN1, Affix1}[FNN2]{SNN2, Affix2}[Alternate2]|\\ +\Verb+\AKA*[FNN1]{SNN1, Affix1}%+\\ +\Verb+ [FNN2]{SNN2, Affix2}+\dotfill + |\AKA*[FNN1]{SNN1, Affix1}[FNN2]{SNN2, Affix2}| +\end{quote} + \begin{quote} -\Verb+\AKA[FNN1]{SNN1,Affix1}%+\\ -\Verb+ [FNN2]{SNN2,Affix2}[Alternate2]+\dotfill - |\AKA[FNN1]{SNN1,Affix1}[FNN2]{SNN2,Affix2}[Alternate2]|\\ -\Verb+\AKA[FNN1]{SNN1,Affix1}%+\\ -\Verb+ [FNN2]{SNN2,Affix2}+\dotfill - |\AKA[FNN1]{SNN1,Affix1}[FNN2]{SNN2,Affix2}|\\ -\Verb+\DropAffix\AKA[FNN1]{SNN1,Affix1}%+\\ -\Verb+ [FNN2]{SNN2,Affix2}+\dotfill - |\DropAffix\AKA[FNN1]{SNN1,Affix1}[FNN2]{SNN2,Affix2}|\\ -\Verb+\AKA*[FNN1]{SNN1,Affix1}%+\\ -\Verb+ [FNN2]{SNN2,Affix2}[Alternate2]+\dotfill - |\AKA*[FNN1]{SNN1,Affix1}[FNN2]{SNN2,Affix2}[Alternate2]|\\ -\Verb+\AKA*[FNN1]{SNN1,Affix1}%+\\ -\Verb+ [FNN2]{SNN2,Affix2}+\dotfill - |\AKA*[FNN1]{SNN1,Affix1}[FNN2]{SNN2,Affix2}| +\Verb+\AKA[FNN1]{SNN1, Affix1}%+\\ +\Verb+ {SNN3, Affix3}[Alternate3]+\dotfill + |\AKA[FNN1]{SNN1, Affix1}{SNN3, Affix3}[Alternate3]|\\ +\Verb+\AKA[FNN1]{SNN1, Affix1}%+\\ +\Verb+ {SNN3, Affix3}+\dotfill + |\AKA[FNN1]{SNN1, Affix1}{SNN3, Affix3}|\\ +\Verb+\AKA*[FNN1]{SNN1, Affix1}%+\\ +\Verb+ {SNN3, Affix3}+\dotfill + |\AKA*[FNN1]{SNN1, Affix1}{SNN3, Affix3}|\\ +\Verb+\ForceFN\AKA*[FNN1]{SNN1, Affix1}%+\\ +\Verb+ {SNN3, Affix3}[Alternate3]+\dotfill + |\ForceFN\AKA*[FNN1]{SNN1, Affix1}{SNN3, Affix3}[Alternate3]|\\ +\Verb+\ForceFN\AKA*[FNN1]{SNN1, Affix1}%+\\ +\Verb+ {SNN3, Affix3}+\dotfill + |\ForceFN\AKA*[FNN1]{SNN1, Affix1}{SNN3, Affix3}| \end{quote} \begin{quote} -\Verb+\AKA[FNN1]{SNN1,Affix1}%+\\ -\Verb+ {SNN3,Affix3}[Alternate3]+\dotfill - |\AKA[FNN1]{SNN1,Affix1}{SNN3,Affix3}[Alternate3]|\\ -\Verb+\AKA[FNN1]{SNN1,Affix1}%+\\ -\Verb+ {SNN3,Affix3}+\dotfill - |\AKA[FNN1]{SNN1,Affix1}{SNN3,Affix3}|\\ -\Verb+\AKA*[FNN1]{SNN1,Affix1}%+\\ -\Verb+ {SNN3,Affix3}+\dotfill - |\AKA*[FNN1]{SNN1,Affix1}{SNN3,Affix3}|\\ -\Verb+\ForceFN\AKA*[FNN1]{SNN1,Affix1}%+\\ -\Verb+ {SNN3,Affix3}[Alternate3]+\dotfill - |\ForceFN\AKA*[FNN1]{SNN1,Affix1}{SNN3,Affix3}[Alternate3]|\\ -\Verb+\ForceFN\AKA*[FNN1]{SNN1,Affix1}%+\\ -\Verb+ {SNN3,Affix3}+\dotfill - |\ForceFN\AKA*[FNN1]{SNN1,Affix1}{SNN3,Affix3}| +\Verb+\AKA[FNN1]{SNN1, Affix1}{SNN4}[Alternate4]+\dotfill + |\AKA[FNN1]{SNN1, Affix1}{SNN4}[Alternate4]|\\ +\Verb+\AKA*[FNN1]{SNN1, Affix1}{SNN4}[Alternate4]+\dotfill + |\AKA*[FNN1]{SNN1, Affix1}{SNN4}[Alternate4]|\\ +\Verb+\ForceFN\AKA*[FNN1]{SNN1, Affix1}{SNN4}[Alternate4]+\dotfill + |\ForceFN\AKA*[FNN1]{SNN1, Affix1}{SNN4}[Alternate4]| \end{quote} \begin{quote} -\Verb+\AKA[FNN1]{SNN1,Affix1}{SNN4}[Alternate4]+\dotfill - |\AKA[FNN1]{SNN1,Affix1}{SNN4}[Alternate4]|\\ -\Verb+\AKA*[FNN1]{SNN1,Affix1}{SNN4}[Alternate4]+\dotfill - |\AKA*[FNN1]{SNN1,Affix1}{SNN4}[Alternate4]|\\ -\Verb+\ForceFN\AKA*[FNN1]{SNN1,Affix1}{SNN4}[Alternate4]+\dotfill - |\ForceFN\AKA*[FNN1]{SNN1,Affix1}{SNN4}[Alternate4]| +\Verb+\AKA{SNN5, Affix5}%+\\ +\Verb+ [FNN6]{SNN6, Affix6}[Alternate6]+\dotfill + |\AKA{SNN5, Affix5}[FNN6]{SNN6, Affix6}[Alternate6]|\\ +\Verb+\AKA{SNN5, Affix5}{SNN7, Affix7}+\dotfill + |\AKA{SNN5, Affix5}{SNN7, Affix7}|\\ +\Verb+\AKA{SNN5, Affix5}{SNN8}[Alternate8]+\dotfill + |\AKA{SNN5, Affix5}{SNN8}[Alternate8]|\\ \end{quote} +\subsection{Reference Targets for Completeness} + \begin{quote} -\Verb+\AKA{SNN5,Affix5}%+\\ -\Verb+ [FNN6]{SNN6,Affix6}[Alternate6]+\dotfill - |\AKA{SNN5,Affix5}[FNN6]{SNN6,Affix6}[Alternate6]|\\ -\Verb+\AKA{SNN5,Affix5}{SNN7,Affix7}+\dotfill - |\AKA{SNN5,Affix5}{SNN7,Affix7}|\\ -\Verb+\AKA{SNN5,Affix5}{SNN8}[Alternate8]+\dotfill - |\AKA{SNN5,Affix5}{SNN8}[Alternate8]|\\ +\Verb+\IndexName{Target}+\dotfill|\IndexName{Target}|\\ +\Verb+\IndexName[FNN1]{SNN1, Affix1}+\dotfill + |\IndexName[FNN1]{SNN1, Affix1}|\\ +\Verb+\IndexName{SNN5, Affix5}+\dotfill + |\IndexName{SNN5, Affix5}| \end{quote} % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % + \phantomsection \addcontentsline{toc}{section}{Index of Persons} \printindex[per] diff --git a/macros/latex/contrib/nameauth/nameauth.pdf b/macros/latex/contrib/nameauth/nameauth.pdf Binary files differindex 0fa566fad6..139e62f414 100644 --- a/macros/latex/contrib/nameauth/nameauth.pdf +++ b/macros/latex/contrib/nameauth/nameauth.pdf diff --git a/macros/luatex/generic/luamplib/NEWS b/macros/luatex/generic/luamplib/NEWS index 8cd3cccf02..9158d1ef92 100644 --- a/macros/luatex/generic/luamplib/NEWS +++ b/macros/luatex/generic/luamplib/NEWS @@ -1,5 +1,12 @@ History of the luamplib package +2025/02/06 2.37.0 + * introduce a new operator 'mpliblength <string>', a unicode-aware version of + the 'length' primitive + + * introduce a new operator 'mplibsubstring <pair> of <string>', a unicode-aware + version of the 'substring ... of ...' primitive + 2024/12/16 2.36.3 * change '//' to 'math.floor' for compatibility with luajittex (#158) diff --git a/macros/luatex/generic/luamplib/luamplib.dtx b/macros/luatex/generic/luamplib/luamplib.dtx index 4909841c92..c08d07f029 100644 --- a/macros/luatex/generic/luamplib/luamplib.dtx +++ b/macros/luatex/generic/luamplib/luamplib.dtx @@ -1,6 +1,6 @@ % \iffalse meta-comment -- by the way, this file contains UTF-8 % -% Copyright (C) 2008-2024 by Hans Hagen, Taco Hoekwater, Elie Roux, +% Copyright (C) 2008-2025 by Hans Hagen, Taco Hoekwater, Elie Roux, % Manuel Pégourié-Gonnard, Philipp Gesang and Kim Dohyun. % Currently maintained by Kim Dohyun. % Support: <https://github.com/lualatex/luamplib> @@ -85,7 +85,7 @@ See source file '\inFileName' for licencing and contact information. %<*driver> \NeedsTeXFormat{LaTeX2e} \ProvidesFile{luamplib.drv}% - [2024/12/16 v2.36.3 Interface for using the mplib library]% + [2025/02/06 v2.37.0 Interface for using the mplib library]% \documentclass{ltxdoc} \usepackage{metalogo,multicol,xspace} \usepackage[x11names]{xcolor} @@ -155,7 +155,7 @@ See source file '\inFileName' for licencing and contact information. % \author{Hans Hagen, Taco Hoekwater, Elie Roux, Philipp Gesang and Kim Dohyun\\ % Current Maintainer: Kim Dohyun\\ % Support: \url{https://github.com/lualatex/luamplib}} -% \date{2024/12/16 v2.36.3} +% \date{2025/02/06 v2.37.0} % % \maketitle % @@ -251,7 +251,7 @@ See source file '\inFileName' for licencing and contact information. % just by appending |withprescript| |"tr_transparency=|\meta{number}|"| to the sentence. % ($0 \le \meta{number} \le 1$) % -% From v2.36, transparency is available with \emph{plain} as well. +% From v2.36, |withtransparency| is available with \emph{plain} as well. % See \hyperlink{luamplibtransparency}{below} \S\,1.2. % % \item[shading] @@ -1103,6 +1103,18 @@ See source file '\inFileName' for licencing and contact information. % Default value: |(white,black)| % \end{description} % +% \subsubsection{\texttt{mpliblength ...}} +% |mpliblength| \meta{string} returns the number of unicode characters in the string. +% This is a unicode-aware version equivalent to the \metapost primitive |length|, but +% accepts only a string-type argument. +% For instance, |mpliblength| |"abçdéf"| returns |6|, not |8|. +% +% \subsubsection{\texttt{mplibsubstring ... of ...}} +% |mplibsubstring| \meta{pair} |of| \meta{string} is a unicode-aware version equivalent to the +% \metapost's |substring ... of ...| primitive. The syntax is the same as the latter. +% For instance, |mplibsubstring| |(2,5)| |of| |"abçdéf"| returns |"çdé"|, +% and |mplibsubstring| |(5,2)| |of| |"abçdéf"| returns |"édç"|. +% % \subsection{Lua} % % \subsubsection{\texttt{runscript ...}} @@ -1188,8 +1200,8 @@ See source file '\inFileName' for licencing and contact information. luatexbase.provides_module { name = "luamplib", - version = "2.36.3", - date = "2024/12/16", + version = "2.37.0", + date = "2025/02/06", description = "Lua package to typeset Metapost with LuaTeX's MPLib.", } @@ -2632,6 +2644,27 @@ end % \end{macrocode} % +% lua function for |mplibsubstring ... of ...| +% \begin{macrocode} +function luamplib.utf8substring (s,b,e) + local t, tt, step = { }, { } + for _, c in utf8.codes(s) do + table.insert(t, utf8.char(c)) + end + if b <= e then + b, step = b+1, 1 + else + e, step = e+1, -1 + end + for i = b, e, step do + table.insert(tt, t[i]) + end + s = table.concat(tt):gsub('"','"&ditto&"') + return string.format('"%s"', s) +end + +% \end{macrocode} +% % Our \metapost preambles % \begin{macrocode} luamplib.preambles = { @@ -3054,6 +3087,14 @@ def withshadingcolors (expr a, b) = withprescript "sh_color_b=" & colordecimals b fi enddef; +def mpliblength primary t = + runscript("return utf8.len[===[" & t & "]===]") +enddef; +def mplibsubstring expr p of t = + runscript("return luamplib.utf8substring([===[" & t & "]===]," + & decimal xpart p & "," + & decimal ypart p & ")") +enddef; ]], legacyverbatimtex = [[ def specialVerbatimTeX (text t) = runscript("luamplibprefig{"&t&"}") enddef; @@ -3218,7 +3259,7 @@ end % in the argument of pdfliteral. % \begin{macrocode} local function pdf_literalcode (...) - put2output{ -2, format(...) :gsub(decimals,rmzeros) } + put2output{ -2, (format(...) :gsub(decimals,rmzeros)) } end local start_pdf_code = pdfmode and function() pdf_literalcode"q" end @@ -4523,7 +4564,7 @@ end % \begin{macrocode} \NeedsTeXFormat{LaTeX2e} \ProvidesPackage{luamplib} - [2024/12/16 v2.36.3 mplib package for LuaTeX] + [2025/02/06 v2.37.0 mplib package for LuaTeX] \fi \ifdefined\newluafunction\else \input ltluatex diff --git a/macros/luatex/generic/luamplib/luamplib.pdf b/macros/luatex/generic/luamplib/luamplib.pdf Binary files differindex 9c7bbc7efc..95965a4f20 100644 --- a/macros/luatex/generic/luamplib/luamplib.pdf +++ b/macros/luatex/generic/luamplib/luamplib.pdf diff --git a/macros/luatex/generic/luamplib/test-luamplib-latex.tex b/macros/luatex/generic/luamplib/test-luamplib-latex.tex index 71a87ae02e..f983d96b17 100644 --- a/macros/luatex/generic/luamplib/test-luamplib-latex.tex +++ b/macros/luatex/generic/luamplib/test-luamplib-latex.tex @@ -353,6 +353,12 @@ draw fullcircle scaled 100 withpattern "mypatt" withpen pencircle scaled 1 withshadingcolors (red,blue) ; \endmpfig +\mpfig + string Test; Test="abçdéf"; + for k=0 upto mpliblength(Test)-1: + draw TEX(mplibsubstring (k,k+1) of Test) scaled 2 shifted (20k,0); + endfor +\endmpfig \tracingcommands0 \vskip 2\baselineskip |