% \iffalse meta-comment % % Copyright (C) 2023 by Charles P. Schaum % ------------------------------------------------------- % % 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. % %<*internal> \iffalse % %<*readme> %<1 | Yes | | Cygwin | Cygwin (distro packages) | Not tested; likely1 | Not tested; likely 2 | | Cygwin | MikTeX (Windows) | Yes1, 3 | No;4 do manually | | Cygwin | TeXlive (Windows) | Not tested; likely1 | Not tested; do manually | | Cygwin | Both Cygwin and Windows | Not tested; not recommended | Not tested; not recommended | | WSL | WSL Linux distro packages | Yes1 | Yes5 | | WSL | MikTeX (Windows) | Yes1, 3 | No;4 do manually | | WSL | TeXlive (Windows) | Not tested; likely1 | Not tested; do manually | | WSL | Both WSL and Windows | Not tested; not recommended | Not tested; not recommended | | WSL/Cyg | Both WSL and Cygwin | Not tested; not recommended | Not tested; not recommended | | GNUWin | any (Windows) | Not tested; not recommended | Not tested; not recommended | 1 All dependencies must be met. Bear in mind MacOS quirks. 2 Installs only to Cygwin environment; not to Windows environment. 3 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. 4 Neither `ltxfileinfo` nor `kpsewhich` will give useful results; do a manual install. 5 Installs only to WSL Linux distro environment; not to Windows environment. ### 4.2.4 Building the Package 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`. ### 4.2.5 Installation 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. Assuming that one has a use case where one can use GNU make, one can choose the following: * 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 system-wide, local TDS-compliant directory tree. The user will be prompted for the `sudo` password. If, for some reason, this fails, do a manual install (below). Note that these make targets depend on `package`, which does not do a clean build. To ensure a clean build, use `make release inst` or `make release install`. ### 4.2.6 Removal The same constraints that apply to installation also apply to removal. If one can do the former, one can do the latter. * Type `make uninst` to remove the package files in the user's personal TDS-compliant directory tree. * Type `make uninstall` to remove the package files in the system-wide, local TDS-compliant directory tree. The user will be prompted for the `sudo` password. If, for some reason, this fails, do a manual removal (opposite of steps used below). The approach of `Makefile` is not to get too aggressive with deletions from the texmf tree, just in case. One may see harmless, extra empty directories after removal. ## 4.3 Manual Method Unlike when using GNU make, which automates adding extensions, in the case of working with WSL together with native Windows TeX distros, in the command lines below there may be certain cases where one may have to add the ".exe" extension to the programs. Those cases should, however, be few. ### 4.3.1 Prepare to Install, No Building One does not need to build `nameauth` completely from source (although it may be a good idea to do a native build). If the provided files are sufficient, one can type: pdftex nameauth.dtx This only unpacks the supplied generated files from `nameauth.dtx`. It does not try to create the documentation. One will have the following files now: | Filename | Description | TDS-where to | | :------------- | :------------------------- | :----------- | | `Makefile` | for use with GNU make | source dir | | `cat01.pdf` | manual illustration, ch. 7 | source dir | | `beamer01.pdf` | manual illustration, ch. 9 | source dir | | `beamer02.pdf` | manual illustration, ch. 9 | source dir | | `beamer03.pdf` | manual illustration, ch. 9 | source dir | | `nameauth.dtx` | commented macro file | source dir | | | | | | `nameauth.ins` | installation driver | unneeded | | | | | | `compat.tex` | compatibility module | doc dir | | `examples.tex` | example file | doc dir | | `nameauth.pdf` | package documentation | doc dir | | `README.md` | this file | doc dir | | | | | | `nameauth.sty` | style file | package dir | One may skip past building to **4.3.3 Installation Prerequisites** below. ### 4.3.2 Building the Package 1. Using the unpacked files from the zip archive, we begin by creating the installation driver, unpacking additional files from `nameauth.dtx`, and generating a copy of the documentation without the table of contents and cross-references: pdflatex --shell-escape --recorder --interaction=batchmode nameauth.dtx Now we should have the following files: | Filename | Description | | :------------- | :--------------------------- | | `Makefile` | for use with GNU make | | `cat01.pdf` | manual illustration, ch. 7 | | `beamer01.pdf` | manual illustration, ch. 9 | | `beamer02.pdf` | manual illustration, ch. 9 | | `beamer03.pdf` | manual illustration, ch. 9 | | `nameauth.dtx` | commented style file | | | | | `compat.tex` | compatibility module | | `examples.tex` | example file | | `nameauth.pdf` | package documentation | | `README.md` | this file | | | | | `nameauth.ins` | installation driver | | `nameauth.sty` | style file | In addition, we have the following temporary files: | Filename | Description | | :------------- | :--------------------------- | | `nameauth.aux` | auxiliary file | | `nameauth.fls` | shows files read | | `nameauth.glo` | raw glossary entries | | `nameauth.hd ` | | | `nameauth.idx` | raw index entries | | `nameauth.log` | log file | | `nameauth.out` | pdf bookmark/hypertext info | | `nameauth.tmp` | temp file used with fancyvrb | | `nameauth.toc` | table of contents info | 2. Generate the TOC and cross-references within the documentation: pdflatex --recorder --interaction=nonstopmode nameauth.dtx 3. Generate the index and glossary files using `makeindex`: makeindex -q -s gglo.ist -o nameauth.gls nameauth.glo makeindex -q -s gind.ist -o nameauth.ind nameauth.idx This adds the following files: | Filename | Description | | :------------- | :----------------------- | | `nameauth.gls` | typeset glossary entries | | `nameauth.ilg` | `makeindex` log file | | `nameauth.ind` | typeset index entries | 4. Integrate the glossary (list of changes) and index into the documentation. The second run updates the TOC: pdflatex --recorder --interaction=nonstopmode nameauth.dtx pdflatex --recorder --interaction=nonstopmode nameauth.dtx ### 4.3.3 Installation Prerequisites In order to perform manual installation, one should be familiar with the general information at the [TeX FAQ](https://www.texfaq.org/FAQ-installthings). Different TeX distributions have somewhat different ways to store TDS-compliant configuration and package data. See, for example, for MikTeX [here](https://docs.miktex.org/manual/localadditions.html#id573803) and [here](https://miktex.org/kb/texmf-roots). Otherwise see the [TeX FAQ](https://www.texfaq.org/FAQ-privinst) and [this page](https://en.wikibooks.org/wiki/LaTeX/Installing_Extra_Packages). The instructions below conform generally to a Unix-based system. There are some cases under Windows where this method may not work. For other systems, please consult the appropriate documentation as needed. The user must already have a TDS-compliant tree set up in order for installation to work. We assume that one knows how to become superuser, create directories, move files, and the like. ### 4.3.4 User's Home Directory `TEXMFHOME` is a variable that points to the root of a TDS-compliant directory tree available to a user. To get its value on POSIX-compliant systems, use: kpsewhich --var-value TEXMFHOME Quite often, `$TEXMFHOME` is equivalent to `$HOME/texmf`. The dollar sign in front of the variable denotes the value of the variable instead of its name. If `$HOME` is `/home/bob`, then `$TEXMFHOME` would be `/home/bob/texmf`. We can understand the following paths to be under this home directory. | Path | Files | | :--------------------------------- | :------------- | | `$TEXMFHOME/source/latex/nameauth` | `Makefile` | | | `cat01.pdf` | | | `beamer01.pdf` | | | `beamer02.pdf` | | | `beamer03.pdf` | | | `nameauth.dtx` | | | | | `$TEXMFHOME/doc/latex/nameauth` | `compat.tex` | | | `examples.tex` | | | `nameauth.pdf` | | | `README.md` | | | | | `$TEXMFHOME/tex/latex/nameauth` | `nameauth.sty` | Create the directories in the left-hand column, or whatever one needs to do in one's own case. Move or copy the files in the right-hand column to their respective directories in the left-hand column. On older TeX distributions, run `mktexlsr` on `$TEXMFHOME` to complete the install process (current distributions may not need this). ### 4.3.5 System-Wide Directory `TEXMFLOCAL` is a variable that points to the root of a TDS-compliant directory tree available to all users on a local site, system-wide installation.To get its value, use: kpsewhich --var-value TEXMFLOCAL See the [TeX FAQ](https://www.texfaq.org/FAQ-what-TDS). We can understand the following paths to be under this local site, system-wide directory: | Path | Files | | :---------------------------------- | :------------- | | `$TEXMFLOCAL/source/latex/nameauth` | `Makefile` | | | `cat01.pdf` | | | `beamer01.pdf` | | | `beamer02.pdf` | | | `beamer03.pdf` | | | `nameauth.dtx` | | | | | `$TEXMFLOCAL/doc/latex/nameauth` | `compat.tex` | | | `examples.tex` | | | `nameauth.pdf` | | | `README.md` | | | | | `$TEXMFLOCAL/tex/latex/nameauth` | `nameauth.sty` | Create the directories in the left-hand column, or whatever one needs to do in one's own case. Move or copy the files in the right-hand column to their respective directories in the left-hand column. Change file ownership as needed (not so much on Windows). If needed, run `mktexlsr` with the appropriate permissions on `$TEXMFLOCAL` to complete the install process. See also the discussion on [this page](https://tex.stackexchange.com/questions/45231/how-to-install-system-wide-packages-without-requiring-an-ls-r-database-with-tex). # 5. More on Package Building * `Makefile` has been upgraded to handle more special cases and not to do unexpected or bad things in those cases, especially on Windows. * The package and manual build on current and older TeX distributions. In a number of examples, some Unicode characters have been replaced with control sequences in order for this compatibility to work, due to how files written out and read back in affects the expansion of active Unicode characters. * The documentation now builds only with `pdflatex`, but the examples and tests can use any LaTeX engine. This is because several typesetting decisions that are quite helpful for the manual work only with `pdflatex`. * This release was tested on Linux (Pop! OS; vanilla TL 2022 and 2017) and Windows 10 (MikTeX with both Cygwin and WSL). The tests using TL 2017 include my published book manuscript, *Breath of God, Yet Work of Man: Scripture, Philosophy, Dialogue, and Conflict*, with Dr. Albert B. Collver III. * The CTAN release was created with vanilla TL 2022 on Pop! OS. The most recent `equivs` file was used to meet package equivalencies. See also [this page](https://tug.org/texlive/debian.html). * TeXlive 2022 and TL 2017 are managed on Pop! OS using [tl-switch](https://github.com/ServusCarolus/tl-switch). * Four pdf files (`cat01.pdf` and `beamer*.pdf`) used in graphic illustrations are created from the output of test files associated with this manual (see below). Normally, the user need not generate them; they are supplied as source files. # 6. Examples / Testing The file `examples.tex`, which also uses `compat.tex`, usually should be enough to illustrate various non-trivial features of this package. It includes most of the longer examples in the manual, edited to fit together in a single document. In addition to this file, a special run of `nameauth.dtx` that defines the macro `\NameauthDoTestFiles` will generate many separate test files. Normally they are written out to `nameauth.tmp` and read in again as verbatim text. They are not included in the package archive by default in order to minimize clutter. To test `nameauth`, either test the files right after installing, or create a new testing directory. One can copy the files from the TDS-compliant source dir and optionally, the documentation directory as well, or unpack the CTAN zip file and build the package. ## 6.1 GNU make: Examples, Tests, Images * Use the default: `make examples`. * To create `examples.pdf` with other LaTeX engines, one can do the following: make examples ENGINE=xelatex make examples ENGINE=lualatex make examples ENGINE=dvilualatex make examples ENGINE=latex * If one wants to change engines and re-test the file, type `make exclean`. * To generate additional test files, type `make tests`. This will produce many test files numbered by chapter and example within that chapter from the `nameauth.dtx` file. It will compile all of the test files using `pdflatex`. One can add the value of ENGINE: make tests ENGINE=xelatex make tests ENGINE=lualatex make tests ENGINE=dvilualatex make tests ENGINE=latex * If one wants to change engines and re-test the files, type `make testclean`. * If, for some reason, one wanted to make the manual illustrations (usually not required), one would type `make images`. ## 6.2 Manual Method ### 6.2.1 Examples Compile `examples.tex`. In the following command lines, one may substitute `latex`, `xelatex`, `lualatex`, and `dvilualatex` for `pdflatex`. pdflatex --interaction=nonstopmode examples pdflatex --interaction=nonstopmode examples makeindex -o examples.ind examples.idx This next line is needed because the `index` package makes an index of persons. makeindex -o examples.rnd examples.rdx These lines complete the indexes and TOC. pdflatex --interaction=nonstopmode examples pdflatex --interaction=nonstopmode examples Another step is used only with `latex` and `dvilualatex`. We default to `dvipdfmx` in case Ghostscript is not installed. If Ghostscript is already installed, one can use `dvipdf` instead. If a file `examples.out.ps` exists, one may delete it after creating the pdf file. dvipdfmx examples If one changes LaTeX engines, one must remove all of the auxiliary files. ### 6.2.2 Tests Generate the test files in the following manner from the `dtx`: pdflatex "\def\NameauthDoTestFiles{}\input{nameauth.dtx}" Compile the test files. In the following command lines, one may substitute `latex`, `xelatex`, `lualatex`, and `dvilualatex` for `pdflatex`. One must change the root or base file name for each test file. pdflatex --interaction=nonstopmode test01-01 pdflatex --interaction=nonstopmode test01-01 makeindex -o test01-01.ind test01-01.idx This next line is needed only for `test07-01.tex` because the `index` package is used for an index of persons. makeindex -o test07-01.rnd test07-01.rdx These lines complete the indexes and TOC. pdflatex --interaction=nonstopmode test01-01 pdflatex --interaction=nonstopmode test01-01 This step is used only when using `latex` and `dvilualatex`. dvipdfmx test01-01 If one changes LaTeX engines, one must remove all of the auxiliary files. ### 6.2.3 Images If, for some reason, one wants to make the manual illustrations (usually not required), this would be the default procedure: Generate the test files in the following manner from the `dtx`: pdflatex "\def\NameauthDoTestFiles{}\input{nameauth.dtx}" Compile the test files: 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 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 # 7. Additional Notes In version 3.7 I spent over seven months analyzing and optimizing both code and documentation. Stepping away from this package for a bit gave me the perspective and clarity to improve it greatly. * I cast aside a number of stale presuppositions that had built up over time. I explored all the ways that one could use certain features and fixed the bugs that appeared by using a better general approach. * I brought back some thorough tests reminiscent of early package versions, but moved to the examples file. * I rewrote the documentation to remove a lot of idiosyncratic formatting. It looks much cleaner, both as source code and as typeset documentation. * Extensive rewriting has led to the TOC becoming the principal expression of scope and sequence. The goal was greater rigor in keeping the easy stuff easy and the complex stuff more accessible. * The package itself has been reorganized to follow the same sequence as the documentation, letting the rhythm of repetition aid learning. One sees this right away in the TOC. * Several macros have been optimized, leading to simpler and cleaner designs that are easier to debug. * A few bugs that could result from directly changing internal package flags have been fixed, allowing the user-accessible parser to work in all cases as intended. * Any name arguments shown in warnings are detokenized in order to prevent potential errors. Regressions caused by a reverted edit in an earlier version that I failed to catch caused several package warnings to halt with errors. These "lameauth" errors are fixed. # 8. Copyright Copyright (C) 2023 by Charles P. Schaum 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](https://www.latex-project.org/lppl.txt) and version 1.3 or later is part of all distributions of LaTeX version 2005/12/01 or later. %readmevb % %<*internal> \fi \def\nameofplainTeX{plain} \ifx\fmtname\nameofplainTeX\else \expandafter\begingroup \fi % %<*install> \input docstrip.tex \keepsilent \askforoverwritefalse \preamble This is a generated file. Copyright (C) 2023 by Charles P. Schaum 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. \endpreamble \usedir{tex/latex/nameauth} \generate{ \file{\jobname.sty}{\from{\jobname.dtx}{package}} } % %\endbatchfile %<*internal> \usedir{source/latex/nameauth} \generate{ \file{\jobname.ins}{\from{\jobname.dtx}{install}} } \usedir{doc/latex/nameauth} \nopostamble \generate{ \file{examples.tex}{\from{\jobname.dtx}{examples}} } \generate{ \file{compat.tex}{\from{\jobname.dtx}{compat}} } \nopreamble \generate{ \file{README.md}{\from{\jobname.dtx}{readme}} } \ifx\fmtname\nameofplainTeX \expandafter\endbatchfile \else \expandafter\endgroup \fi % % \fi % % \iffalse %<*driver> \ProvidesFile{nameauth.dtx} % %\NeedsTeXFormat{LaTeX2e}[2005/12/01] %\ProvidesPackage{nameauth} %<*package> [2023/02/03 3.7 Name authority mechanism for consistency in text and index] % % %<*driver> %^^A %%%%%%%%%%%%% Stuff Needed in the Document Preamble %%%%%%%%%%%%%%%%% \documentclass[11pt]{ltxdoc} %^^A Below we check if our TL distribution has the iftex package and load it. \IfFileExists{iftex.sty}{\usepackage{iftex}}{} %^^A Only versions of iftex since 2019 have the macro \RequireTUTeX. %^^A If the package is not loaded or if it is not new, %^^A we load the older, transitional packages. \unless\ifdefined\RequireTUTeX \usepackage{ifxetex} \usepackage{ifluatex} \usepackage{ifpdf} \fi %^^A We only use pdflatex to make the documentation. \IfFileExists{utf8-2018.def}{}{\usepackage[utf8]{inputenc}} \usepackage[TS1,T1]{fontenc} \usepackage{textcomp} %^^A For backward compatibility \usepackage[ngerman,american]{babel} \newcommand\de[1]{\foreignlanguage{ngerman}{#1}} \usepackage{lmodern} \usepackage{newunicodechar} \DeclareTextSymbolDefault{\textlongs}{TS1} \DeclareTextSymbol{\textlongs}{TS1}{115} \newunicodechar{ſ}{\textlongs} %^^A Finish with fonts and micro-typography. \usepackage{manfnt} \usepackage{microtype} %^^A This helps track down any stray or unintended changes to font sizes. \let\savegraf\everypar \makeatletter \newcommand\FontDebugStart {%^^A \let\oldep\everypar%^^A \newtoks\everypar%^^A \oldep{\the\everypar \llap{\f@size pt\hspace{4em plus 1fil minus 1em}}}%^^A } \newcommand\FontDebugStop {%^^A \let\oldep\savegraf%^^A \oldep{\the\everypar}%^^A } \makeatother %^^A Add fancy graphical features \usepackage{tikz} \usepackage{tcolorbox} %^^A Set basic format for boxes drawn by TikZ. \tcbset{fonttitle=\bfseries\sffamily,box align=top,lower separated=false} %^^A Set up page layout to fit both letter and DIN A4. \usepackage[paperheight=279.4mm,paperwidth=210mm, textheight=239.4mm,textwidth=140mm, right=20mm,marginparwidth=40mm,nohead]{geometry} %^^A Two-column TOC \usepackage[toc]{multitoc} %^^A Include an index \usepackage{makeidx} %^^A These options allow the index to focus on names in the index more %^^A like one might see in a normal document. %^^A \DisableCrossrefs \CodelineIndex \RecordChanges \frenchspacing %^^A Include specifically the current version of the package. \usepackage{\jobname}[2023/02/03] %^^A Set up the ``actual'' character \IndexActual{=} %^^A Set up all tabular packages. Booktabs makes them pretty, %^^A colortabl shades rows. \usepackage{booktabs} \usepackage{colortbl} %^^A Set up lists. \usepackage[inline]{enumitem} \setlist{rightmargin=\leftmargin,itemsep=0pt} %^^A Use underlining in certain contexts. \usepackage{soulutf8} %^^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} %^^A Use color indicators in a couple of tables. \newcommand\NO{\bgroup \color{black!20!white}\lower 0.075ex\hbox{\rule{1.5ex}{1.5ex}}\egroup} \newcommand\YES{\bgroup \color{black!80!white}\lower 0.075ex\hbox{\rule{1.5ex}{1.5ex}}\egroup} %^^A Let verbatim environments be fancy. \usepackage{fancyvrb} %^^A Define fancyvrb defaults. \fvset{gobble=2,numbers=left,fontsize=\small} %^^A Tweak spacing as needed \usepackage{setspace} %^^A Define some stretch if needed \newcommand\smallstretch{\setstretch{1.05}} \newcommand\medstretch{\setstretch{1.1}} \newcommand\bigstretch{\setstretch{1.2}} %^^A Permit horizontal boxes to be overfull. \hfuzz=3pt %^^A Define negative skip values if needed. \newcommand\negsmallskip{\vspace{-\smallskipamount}} \newcommand\negmedskip{\vspace{-\medskipamount}} \newcommand\negbigskip{\vspace{-\bigskipamount}} %^^A Have documentation with hyperlinks \usepackage[numbered]{hypdoc} %^^A Change URL color \hypersetup{urlcolor=violet} %^^A Redefine emphasis in the body text because italic has dedicated uses. \let\oldemph\emph \let\emph\textbf %^^A Redefine name formatting for this manual. \renewcommand*\FrontNamesFormat[1]{\color{red}\sffamily #1} \renewcommand*\FrontNameHook[1]{\color{darkgray}\sffamily #1} \renewcommand*\NamesFormat[1]{\color{blue}\sffamily #1} \renewcommand*\MainNameHook[1]{\sffamily #1} %^^A Show a ``dangerous bend'' in the margin. \newcommand*\Warn {%^^A \unless\ifinner {\marginpar{\raggedleft\strut\small\raise0.7ex\hbox{\dbend}}}%^^A \fi } %^^A Put information in the margin. \newcommand*\Info[1] {%^^A \unless\ifinner {\marginpar{\raggedleft\footnotesize#1}}%^^A \fi } \newcommand\Same {\Info{Same name patterns\break and index entries\break as above.}} %^^A Show a name pattern in margin. \newcommand*\PatInfo[1] {%^^A \unless\ifinner {%^^A \marginpar {\raggedleft\footnotesize Name Pattern(s):\hfill\break \ttfamily#1}%^^A }%^^A \fi } %^^A Show a basic index entry info in margin. \newcommand*\IdxInfo[1] {%^^A \unless\ifinner {%^^A \marginpar{\raggedleft\footnotesize Basic Index:\hfill\break#1}%^^A }%^^A \fi } %^^A Show both name patterns and index entries in margin. \newcommand*\BothInfo[2] {%^^A \unless\ifinner {%^^A \marginpar{%^^A \raggedleft\footnotesize Name Pattern(s):\hfill\break%^^A {\ttfamily#1}\smallskip\break%^^A \raggedleft\footnotesize Basic Index:\hfill\break#2%^^A }%^^A }%^^A \fi } %^^A Return to the TOC at the end of a major section. \newcommand*\ReturnLink {%^^A \leavevmode \begin{quote}%^^A \centering\tcbox{Back to \hyperlink{TOC}{Table of Contents}}%^^A \end{quote}%^^A } %^^A Print a high-visibility callout that can have an optional title. \newenvironment{InfoBox}[1][] {%^^A \def\titulus{#1}%^^A \medskip%^^A \ifx\titulus\empty \begin{tcolorbox}[colback=white,colframe=red!90!black]%^^A \else \begin{tcolorbox}[colback=white,colframe=red!90!black, adjusted title={\bfseries\hfil #1}]%^^A \fi } {\end{tcolorbox}\medskip} %^^A Print a callout that can have an optional title. \newenvironment{SyntaxBox}[1][] {%^^A \def\titulus{#1}%^^A \begingroup\medskip \ifx\titulus\empty \begin{tcolorbox}[colback=white,colframe=darkgray]%^^A \begin{tabular}{@{}l@{}} \else \begin{tcolorbox}[colback=white,colframe=darkgray, adjusted title={\bfseries\hfil #1}]%^^A \begin{tabular}{@{}l@{}} \fi } {\end{tabular}\end{tcolorbox}\medskip\endgroup} %^^A Print a two-cell callout that can have an optional title. \newenvironment{SyntaxBoxii}[1][] {%^^A \def\titulus{#1}%^^A \ifx\titulus\empty \smallskip\begin{tcolorbox}[colback=white,colframe=darkgray]%^^A \begingroup\begin{tabular}{@{}ll@{}} \else \smallskip\begin{tcolorbox}[colback=white,colframe=darkgray, adjusted title={\bfseries\hfil #1}]%^^A \begingroup\begin{tabular}{@{}ll@{}} \fi } {\end{tabular}\endgroup\end{tcolorbox}\smallskip} %^^A Print a quote and the source. \renewcommand{\hrulefill}{% \leavevmode\leaders\hrule height 1.5pt\hfill\kern0pt } \newenvironment{Quote}[1] {\def\QuoteName{#1}\begin{quote}\small\vfill\hrulefill\medskip\\} {\\[1ex]\hbox{}\hfill---\normalsize\QuoteName\end{quote}} %^^A Used for one or more examples \newenvironment{Block} {%^^A \begin{quote}\small \setlist{rightmargin=0pt,leftmargin=0pt,topsep=0ex,itemsep=0pt}%^^A \begin{itemize}\item[] } {\end{itemize}\end{quote}} %^^A Warning repeated throughout the manual \newcommand\NameArgWarning {%^^A \begin{InfoBox}%^^A When a macro occurs in a name argument and the argument will be displayed in the text and in the index, if there are any concerns about macro expansion, one should put \cmd{\noexpand} before that macro. \end{InfoBox}%^^A } %^^A Macros that handle describing index states \newcommand\Stay[2] {%^^A \parbox{0.685\textwidth}{#1\dotfill}%^^A \lower 2ex\hbox{%^^A \quad\tcbox[boxsep=0.2ex]{\textls[-20]{Stay in State #2}}%^^A }%^^A } \newcommand\Go[2] {%^^A \parbox{0.685\textwidth}{#1\dotfill}%^^A \lower 2ex\hbox{%^^A \quad\tcbox[boxsep=0.2ex]{\textls[30]{Go to State #2}}%^^A }%^^A } %^^A Used when introducing name forms \newcommand\FUse{\leavevmode\hbox to 5em{First use:\hfill}} \newcommand\LUse{\leavevmode\hbox to 5em{Later use:\hfill}} %^^A Use this example in the body text. It is defined here due %^^A to the vertical bars, which are redefined in the body text. % \newcommand\Orphan[2]{#1(\hyperpage{#2})} \TagName[Lost]{Name}{\,\S|Orphan{perdit}} \TagName{foo\Name {bar}}{\,\S|hyperpage} %^^A 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. \begin{nameauth} \< Aeth & & Æthelred, II & > \< Aris & & Aristotle & > \< Bailey & Betsey & Bailey & > \< Carter & J.E. & Carter, Jr. & > \< Cicero & M.T. & Cicero & > \< Confucius & & Confucius & > \< Dagb & & Dagobert & I > \< Dem & & Demetrius, I & > \< deSmet & Pierre-Jean & \noexpand\Fbox{\noexpand\AltCaps{d}e~Smet} & > \< Soto & Hernando & de~Soto & > \< Doug & Frederick & Douglass & > \< DuBois & W.E.B. & Du~Bois & > \< AltDuBois & W.E.B. & DuBois & > \< Einstein & Albert & Einstein & > \< Eliz & & Elizabeth, I & > \< Fukuyama & & \noexpand\textUC{Fukuyama} & Takeshi > \< JWG & J.W. von & Goethe & > \< TGrac & \noexpand\TSemp & Gracchus & > \< Harnack & Adolf & Harnack & > \< AVH & Adolf & Harnack & Adolf\noexpand\von > \< Henry & & Henry & VIII > \< Ike & Dwight D. & Eisenhower & > \< Jeff & Thomas & \noexpand\textSC{Jefferson}\noexpand\GEN{} & > \< Eriugena & & John, Eriugena & > \< MLK & Martin Luther & King, Jr. & > \< Lewis & Clive Staples & Lewis & > \< CSL & Clive Staples & Lewis & C.S. > \< Linc & Abraham & Lincoln & > \< Luth & Martin & \noexpand\textSC{Luther} & > \< Cath & Catherine \noexpand\AltCaps{d}e' & \noexpand\textSC{Medici} & > \< Miyazaki & & Miyazaki, Hayao & > \< MSens & & Miyazaki, Hayao & Sensei > \< Noguchi & Hideyo & Noguchi & > \< Patton & George S. & Patton, Jr. & > \< Plato & & Plato & > \< JRIV & J.D. & Rockefeller, IV & > \< JayR & J.D. & Rockefeller, IV & Jay > \< Scipio & \noexpand\SCIPi & \noexpand\SCIPii & > \< OScipio & Lucius & \noexpand\CSB & > \< Shak & \noexpand\WM & \noexpand\SHK & > \< Striet & John & \noexpand\de{Strietelmeier} & > \< Sun & & Sun, Yat-sen & > \< KempMed & & Thomas, à~Kempis & > \< KempW & Thomas & à~Kempis & > \< Tyson & Mike & Tyson & > \< Iron & Mike & Tyson & Iron Mike > \< VBuren & Martin & Van Buren & > \< Wash & George & Washington & > %^^A We use the next row as an example in the docs. %^^A \< White & E.\,B. & White & > \< Yamt & & Yamamoto, Isoroku & > \< Yosh & & Yoshida & Shigeru > \end{nameauth} %^^A Add sort tags here for those needing them. \PretagName{Æthelred, II}{Aethelred 2} \PretagName[Thomas]{à~Kempis}{Akempis, Thomas} \PretagName{Antiochus, III}{Antiochus 3} \PretagName{Antiochus, IV}{Antiochus 4} \PretagName{Atat\"urk}{Ataturk} \PretagName[W.H.]{Auden}{Auden, Wystan} \PretagName[Charles]{\noexpand\textBF{Babbage}}{Babbage, Charles} \PretagName{Bo\"ethius}{Boethius} \PretagName[Robert]{\textSC{Burns}}{Burns, Robert} \PretagName[Giovanni]{d'Andrea}{Dandrea, Giovanni} \PretagName{Demetrius, I}{Demetrius 1} \PretagName[Jacques]{De~Pamele}{Depamele, Jacques} \PretagName[Charles-Louis]{de Secondat}{deSecondat, Charles} \PretagName[Pierre-Jean]{\noexpand\Fbox{\noexpand\AltCaps{d}e~Smet}} {deSmet, Pierre-Jean} \PretagName[Hernando]{de~Soto}{Desoto, Hernando} \PretagName{\textit{Doctor mellifluus}}{Doctor mellifluus} \PretagName[W.E.B.]{Du~Bois}{DuBois, William} \PretagName{du~Cange}{Ducange} \PretagName[Charles]{du~Fresne}{Dufresne, Charles} \PretagName{Elizabeth, I}{Elizabeth 1} \PretagName{\noexpand\textUC{Fukuyama}}[Takeshi]{Fukuyama Takeshi} \PretagName[Greta]{\noexpand\textSC{Garbo}}{Garbo, Greta} \PretagName{Ghazāli}{Ghazali} \PretagName[\noexpand\TSemp]{Gracchus}{Gracchus, Tiberius Sempronius} \PretagName{Gregory, I}{Gregory 1} \PretagName[Thomas]{\noexpand\textSC{Jefferson}\noexpand\GEN{}} {Jefferson, Thomas} \PretagName{\noexpand\textUC{Kanade}, Takeo}{Kanade Takeo} \PretagName[Ada]{\noexpand\textIT{Lovelace}}{Lovelace, Ada} \PretagName[Martin]{\noexpand\textSC{Luther}}{Luther, Martin} \PretagName[Catherine \noexpand\AltCaps{d}e']{\noexpand\textSC{Medici}} {Medici, Catherine de} \PretagName{\noexpand\textSC{Misora}, Hibari}{Misora Hibari} \PretagName[Frenec]{Molnár}{Molnar, Frenec} \PretagName[Sandra Day]{O'Connor}{OConnor, Sandra} \PretagName{Ptolemy, IV}{Ptolemy 4} \PretagName{Ptolemy, V}{Ptolemy 5} \PretagName[J.D.]{Rockefeller, IV}{Rockefeller, John D 4} \PretagName[Heinrich Wilhelm]{\noexpand\textSC{R\"uhmann}} {Ruehmann, Heinrich Wilhelm} \PretagName[Heinz]{\noexpand\textSC{R\"uhmann}}{Ruehmann, Heinz} \PretagName{Seleucus, III}{Seleucus 3} \PretagName[\noexpand\SCIPi]{\noexpand\SCIPii}{Scipio Africanus} \PretagName[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{Thomas, à~Kempis}{Thomas Akempis} \PretagName{Vlad, {\c T}epe{\c s}}{Vlad Tepes} \PretagName[E.\,B.]{White}{White, Elwyn} \PretagName[Konrad]{\noexpand\textSC{Zuse}}{Zuse, Konrad} %^^A Add index tags for all names in the dtx file. \TagName{Æthelred, II}{, king|hyperpage} \TagName{Antiochus, III}{ the Great, king|hyperpage} \TagName{Antiochus, IV}{ Epiphanes, king|hyperpage} \TagName{Aristotle}{|hyperpage} \TagName[W.H.]{Auden}{|hyperpage} \TagName[Charles]{\noexpand\textBF{Babbage}}{|hyperpage} \TagName[Betsey]{Bailey}{|hyperpage} \TagName[Leonard]{Bernstein}{|hyperpage} \TagName{Bernard, of Clairvaux}{|hyperpage} \TagName{Bo\"ethius}{|hyperpage} \TagName[Robert]{\textSC{Burns}}{|hyperpage} \TagName[Julius]{Caesar}{, imperator|hyperpage} \TagName[Rudolph]{Carnap}{|hyperpage} \TagName[J.E.]{Carter, Jr.}{, pres.|hyperpage} \TagName[Charlie]{Chaplin}{|hyperpage} \TagName[Charles W.]{Chesnutt}{|hyperpage} \TagName[M.T.]{Cicero}{|hyperpage} \TagName{Chiang}[Kai-shek]{\ddag, pres.|hyperpage} \TagName[Schuyler]{Colfax}{, v.p.|hyperpage} \TagName{Confucius}{|hyperpage} \TagName{Cratylus}{|hyperpage} \TagName[e.e.]{cummings}{|hyperpage} \TagName{Dagobert}[I]{\ddag, king|hyperpage} \TagName[Sammy]{Davis,Jr.}{|hyperpage} \TagName[Giovanni]{d'Andrea}{|hyperpage} \TagName{Demetrius, I}{ Soter, king|hyperpage} \TagName[Jacques]{De~Pamele}{|hyperpage} \TagName[Pierre-Jean] {\noexpand\Fbox{\noexpand\AltCaps{d}e~Smet}}{|hyperpage} \TagName[Hernando]{de~Soto}{|hyperpage} \TagName[Marc van]{Dongen}{|hyperpage} \TagName[Frederick]{Douglass}{|hyperpage} \TagName[W.E.B.]{Du~Bois}{|hyperpage} \TagName[Charles]{du~Fresne}{|hyperpage} \TagName[Albert]{Einstein}{|hyperpage} \TagName[Dwight D.]{Eisenhower}{, pres.|hyperpage} \TagName{Elizabeth, I}{, queen|hyperpage} \TagName[Robin]{Fairbairns}{|hyperpage} \TagName{\noexpand\textUC{Fukuyama}}[Takeshi]{\ddag|hyperpage} \TagName[Greta]{\noexpand\textSC{Garbo}}{|hyperpage} \TagName{Ghazāli}{|hyperpage} \TagName{Ghazali}{|hyperpage} \TagName[\noexpand\TSemp]{Gracchus}{, consul|hyperpage} \TagName[J.W. von]{Goethe}{|hyperpage} \TagName[Ulysses S.]{Grant}{, pres.|hyperpage} \TagName[Enrico]{Gregorio}{|hyperpage} \TagName{Gregory, I}{, pope|hyperpage} \TagName[Oskar]{Hammerstein, II}{|hyperpage} \TagName[Adolf]{Harnack}{|hyperpage} \TagName[Lafcadio]{Hearn}{|hyperpage} \TagName{Hermogenes}{|hyperpage} \TagName{Henry}[VIII]{, king|hyperpage} \TagName[Bob]{Hope}{|hyperpage} \TagName[Hubert H.]{Humphrey}{, v.p.|hyperpage} \TagName[Thomas]{\noexpand\textSC{Jefferson}\noexpand\GEN{}} {, pres.|hyperpage} \TagName{Jesus, Christ}{|hyperpage} \TagName{John, Eriugena}{|hyperpage} \TagName[Mustafa]{Kemal}{|hyperpage} \TagName[John F.]{Kennedy}{, pres.|hyperpage} \TagName{Kim, Jong Un}{|hyperpage} \TagName[Martin Luther]{King, Jr.}{|hyperpage} \TagName{Lao-tzu}{|hyperpage} \TagName[Clive Staples]{Lewis}{|hyperpage} \TagName[Abraham]{Lincoln}{, pres.|hyperpage} \TagName[Titus]{Livius}{|hyperpage} \TagName{Louis, XIV}{, king|hyperpage} \TagName[Ada]{\noexpand\textIT{Lovelace}}{|hyperpage} \TagName[Uwe]{Lueck}{|hyperpage} \TagName[Dan]{Luecking}{|hyperpage} \TagName[Martin]{\noexpand\textSC{Luther}}{|hyperpage} \TagName{Maimonides}{|hyperpage} \TagName[Dean]{Martin}{|hyperpage} \TagName{\noexpand\textSC{Misora}, Hibari}{|hyperpage} \TagName[Nicolas]{Malebranche}{|hyperpage} \TagName[Catherine \noexpand\AltCaps{d}e']{\noexpand\textSC{Medici}} {|hyperpage} \TagName{\noexpand\textSC{Mencius}}{|hyperpage} \TagName{Miyazaki, Hayao}{|hyperpage} \TagName[L.M.]{Montgomery}{|hyperpage} \TagName[Frenec]{Molnár}{\dag|hyperpage} \TagName[Nancy C.]{Mulvany}{|hyperpage} \TagName{Nippon Gakki}{|hyperpage} \TagName[Hideyo]{Noguchi}{\dag|hyperpage} \TagName[Sandra Day]{O'Connor}{, justice|hyperpage} \TagName[Heiko]{Oberdiek}{|hyperpage} \TagName[George S.]{Patton, Jr.}{|hyperpage} \TagName[Lucius]{Sergius Paulus}{|hyperpage} \TagName{Plato}{|hyperpage} \TagName{Pontius, Pilate}{|hyperpage} \TagName{Ptolemy, IV}{ Philopator, king|hyperpage} \TagName{Ptolemy, V}{ Epiphanes, king|hyperpage} \TagName{Rambam}{|hyperpage} \TagName[Luke]{Ranieri}{|hyperpage} \TagName[the]{Rat Pack}{|hyperpage} \TagName[J.D.]{Rockefeller, IV}{|hyperpage} \TagName[Theodore]{Roosevelt}{, pres.|hyperpage} \TagName[Heinz]{\noexpand\textSC{R\"uhmann}}{|hyperpage} \TagName[Salman]{Rushdie}{|hyperpage} \TagName{Saul, of Tarsus}{|hyperpage} \TagName[Robert]{Schlicht}{|hyperpage} \TagName{Seleucus, III}{ Ceraunus, king|hyperpage} \TagName[\noexpand\SCIPi]{\noexpand\SCIPii}{|hyperpage} \TagName[Lucius]{\noexpand\CSB}{, consul|hyperpage} \TagName[\noexpand\WM]{\noexpand\SHK}{|hyperpage} \TagName[Frank]{Sinatra}{|hyperpage} \TagName[R.]{Snel van Royen}{|hyperpage} \TagName[W.]{Snel van Royen}{|hyperpage} \TagName{Socrates}{|hyperpage} \TagName[Philipp]{Stephani}{|hyperpage} \TagName[John]{\noexpand\de{Strietelmeier}}{|hyperpage} \TagName{Sun, Yat-sen}{, pres.|hyperpage} \TagName{Thomas, à~Kempis}{|hyperpage} \TagName{Thomas, Aquinas}{|hyperpage} \TagName[Henry David]{Thoreau}{|hyperpage} \TagName{\noexpand\textUC{Kanade}, Takeo}{|hyperpage} \TagName[Mark]{Twain}{|hyperpage} \TagName[Mike]{Tyson}{|hyperpage} \TagName[Bob]{Uecker}{|hyperpage} \TagName[Harold]{Urey}{|hyperpage} \TagName[Martin]{Van Buren}{, pres.|hyperpage} \TagName[Publius]{Vegetius Renatus}{|hyperpage} \TagName[Jesse]{Ventura}{|hyperpage} \TagName{Vlad, II}{ Dracul|hyperpage} \TagName{Vlad, III}{ Dracula|hyperpage} \TagName{Voltaire}{|hyperpage} \TagName[George]{Washington}{, pres.|hyperpage} \TagName[Alan]{Watts}{|hyperpage} \TagName[E.\,B.]{White}{|hyperpage} \TagName{William, I}{, king |hyperpage} \TagName{William, the Conqueror}{|hyperpage} \TagName{Yamaha, Torakusu}{|hyperpage} \TagName{Yamaha Corp.}{|hyperpage} \TagName{Yamamoto, Isoroku}{|hyperpage} \TagName{Yoshida}[Shigeru]{\ddag, PM|hyperpage} \TagName[Caspar]{Ziegler}{|hyperpage} \TagName[Konrad]{\noexpand\textSC{Zuse}}{|hyperpage} \begin{document} \DocInput{\jobname.dtx} \end{document} % % \fi % %^^A %%%%%%%%%%%%%%%%%%%%%%% Error Correction %%%%%%%%%%%%%%%%%%%%%%%%%%%% % % \CheckSum{3451} % % \CharacterTable % {Upper-case \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z % Lower-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 % Digits \0\1\2\3\4\5\6\7\8\9 % Exclamation \! Double quote \" Hash (number) \# % Dollar \$ Percent \% Ampersand \& % Acute accent \' Left paren \( Right paren \) % Asterisk \* Plus \+ Comma \, % Minus \- Point \. Solidus \/ % Colon \: Semicolon \; Less than \< % Equals \= Greater than \> Question mark \? % Commercial at \@ Left bracket \[ Backslash \\ % Right bracket \] Circumflex \^ Underscore \_ % Grave accent \` Left brace \{ Vertical bar \| % 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.7}{2023/02/03}{Major updates to all files} % % \GetFileInfo{\jobname.dtx} % % \DoNotIndex{\@empty, \@gobble, \@period, \@token, \trim@spaces, % \zap@space} % % \DoNotIndex{\begingroup, \bfseries, \bgroup, % \csdef, \csgdef, \csname, \csundef, % \DeclareOption, \def, \detokenize, % \edef, \egroup, \else, \endcsname, \endgroup, \endinput, \ExecuteOptions, % \expandafter, % \fi, \futurelet, % \global, % \hbox, % \if, \ifcsname, \ifx, \ignorespaces, \index, \itshape, % \leavevmode, \let, % \newcommand, \newcommandx, \newenvironment, \newif, \nobreakspace, % \PackageError, \PackageWarning, \ProcessOptions, % \relax, \renewcommand, \RequirePackage, % \scshape, % \textbackslash, % \uppercase} % %^^A %%%%%%%%%%%%%%% Macros That Must Be Defined Here %%%%%%%%%%%%%%%%%%%% % %^^A Conditional set if we have an old TeXLive version % % \newif\ifOldTeX % \IfFileExists{utf8-2018.def}{}{\OldTeXtrue} % %^^A Global definitions of conditionals used for examples %^^A must be included here because \newif statements cannot %^^A occur within an \iffalse ... \fi pair (driver section). % %^^A For George Washington/Mustafa Kemal % \newif\ifNoTag % %^^A For Thomas Jefferson % \newif\ifGenitive % \newif\ifDoGenitive % %^^A For the Cornelii Scipiones % \newif\ifNoPraenomen % \newif\ifNoGens % \newif\ifNoCognomen % \newif\ifNoAgnomen % \newif\ifXPrae % \newif\ifXGens % \newif\ifXCogn % \newif\ifXAgno % %^^A For Babbage and company % \newif\ifHeadword % \newif\ifAncientName % %^^A For William Shakespeare % \newif\ifSpecialFN % \newif\ifSpecialSN % \newif\ifRevertSN % %^^A For advanced hooks % \newif\ifFbox % \newif\ifFirstCap % \newif\ifInHook % \Fboxtrue % \newif\ifCaps % %^^A Global definitions of macros for examples % %^^A For Thomas Jefferson % \newcommand*\GEN{\ifDoGenitive\textSC{'s}\fi} % %^^A For Scipio Africanus % \newcommand*\SCIPi % {^^A % \ifXGens Publius\else % \ifXPrae Cornelius\else % Publius Cornelius^^A % \fi % \fi % } % % \newcommand*\SCIPii % {^^A % \ifXAgno Scipio\else % Scipio Africanus^^A % \fi % } % %^^A For Gracchus % \newcommand*\TSemp % {^^A % \ifXGens Tiberius\else % \ifXPrae Sempronius\else % Tiberius Sempronius^^A % \fi % \fi % } % %^^A For Scipio Barbatus % \newcommand*\CSB % {^^A % \ifXGens % \ifXAgno Scipio\else % Scipio Barbatus\fi % \else % \ifXCogn Cornelius\else % \ifXAgno Cornelius Scipio\else % Cornelius Scipio Barbatus^^A % \fi % \fi % \fi % } % %^^A For William Shakespeare % \newcommand*\WM % {^^A % \ifSpecialFN Wm.\else % William\fi % } % % \newcommand*\SHK % {^^A % \ifRevertSN % \textSC{Shakespeare}\else % \ifSpecialSN % \noexpand\AltCaps{t}he Bard\else % \textSC{Shakespeare}^^A % \fi % \fi % } % % \newcommand*\Revert{\RevertSNtrue} % %^^A %%%%%%%%%%%%%%%%%%%%%%%%%% Title Page %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % % \title{\textsf{nameauth} --- Name authority mechanism\\ % for consistency in text and index^^A % \thanks{This file describes version \fileversion, last revised \filedate.}} % \author{Charles P. Schaum\thanks{Email: charles[dot]schaum@comcast.net}} % \date{Released \filedate} % % \maketitle %^^A This negative space fixes a warning. % \vspace{-16.67pt} % % \begin{abstract} % \noindent The \textsf{nameauth} package automates the correct formatting and indexing of names for professional writing. This aids the use of a \emph{name authority} and the editing process without needing to retype name references. % \end{abstract} % %^^A %%%%%%%%%%%%%%%%%%%%%%%%%%%%%% TOC %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % % \begingroup % \small % \hypertarget{TOC}{}^^A % \tableofcontents % \endgroup % % \bigskip % % \begin{InfoBox}[Disclaimer] % Names are about real people; examples should be too. This manual mentions notable figures both living and deceased. All names herein are meant to be used respectfully, for teaching purposes only. At no time is any disrespect or bias intended or implied by the author. % \end{InfoBox} % % \bigskip % % \begin{InfoBox} % All direct quotes contained herein are in the public domain or copyrighted works cited in small excerpts under the terms of fair use, to which the present author claims no copyright. Such quotes are used to stimulate the mind and promote the concept that names have value, can take different forms, and can represent sharply different viewpoints. Some quotes are a kind of ``running gag'' about Shakespearian names and roses. That illustrates the transformative aspect of fair use as well as the ratio of work quoted to its total size. % \end{InfoBox} % % \begin{Quote}{\Name[Theodore]{Roosevelt}\break\hbox{}\hfill % Introduction, \textit{The Papers and Writings of Abraham Lincoln} (1905)} % It is a very poor thing, whether for nations or individuals, to advance the history of great deeds done in the past as an excuse for doing poorly in the present; but it is an excellent thing to study the history of the great deeds of the past, and of the great men who did them, with an earnest desire to profit thereby so as to render better service in the present. In their essentials, the men of the present day are much like the men of the past, and the live issues of the present can be faced to better advantage by men who have in good faith studied how the leaders of the nation faced the dead issues of the past. % \end{Quote} % % \newpage % %^^A %%%%%%%%%%%%%%%%% Start of Documentation Proper %%%%%%%%%%%%%%%%%%%%% % % \section{Quick Start} % \label{sec:QuickStart} % % A \emph{name authority} is a canonical, scholarly list of names to which variant name forms and aliases refer. This package helps one easily work with a name authority to manage, format, and index names, especially in larger publications. % % \subsection{Simple Example} % \label{sec:QuickExample} % \begingroup % \renewcommand{\NamesFormat}{} % \renewcommand{\MainNameHook}{} % % We begin with an excerpt from a biography written by \Name[Charles W.]{Chesnutt}[Charles Waddell], a prominent African-American author at the turn of the twentieth century.\footnote{\Name[Charles W.]{Chesnutt}, \textit{Frederick Douglass} (Boston: Small, Maynard, 1899). See also \href{https://docsouth.unc.edu/neh/chesnutt/summary.html} {\bfseries this web page}.} % We create a new document and use only the default \textsf{nameauth} package options. We do not create any formatting for names (Section~\ref{sec:Formatting}). % % The \texttt{nameauth} environment (Section~\ref{sec:QuickUIStart}) is in the preamble. It resembles a \texttt{tabular} with four columns. In column one we define the naming macros. In columns two and three we define the names that the macros will display. We leave column four empty. After the first group, we use \cmd{\Forgetname} (Section~\ref{sec:NameControl}) to ``forget'' that the names appeared, making the conditions of the second group the same as the first for illustrative purposes. % % \ifdefined\NameauthDoTestFiles \edef\NameauthTestFile{test01_01.tex}\else % \edef\NameauthTestFile{\jobname.tmp}\fi % % \begin{VerbatimOut}{\NameauthTestFile} % \documentclass{article} % \input{compat.tex} % Included with nameauth; needed only if % % compiling on multiple TeX distros or LaTeX engines. % \usepackage{makeidx} % \usepackage{nameauth} % \makeindex % \usepackage[inline]{enumitem} % % \begin{nameauth} % % Col. 1 Col. 2 Col. 3 Col. 4 % \< Doug & Frederick & Douglass & > % \< Bailey & Betsey & Bailey & > % \end{nameauth} % % \begin{document} % % \begin{enumerate*} % \item[\textbf{1.}] \Doug\ rose to eminence by sheer force % of character and talents that neither slavery nor caste % proscription could crush. % \item[\textbf{2.}] \Doug's early life is perhaps the most % complete indictment of the slave system ever presented at % the bar of public opinion. % \item[\textbf{3.}] \Doug\ was born in February, l8l7. His % earliest memories centered around the cabin of his % grandmother, \Bailey. % \end{enumerate*} % % \ForgetName[Frederick]{Douglass} % \ForgetName[Betsey]{Bailey} % \begin{enumerate*} % \item[\textbf{2.}] \Doug's early life is perhaps the most % complete indictment of the slave system ever presented at % the bar of public opinion. % \item[\textbf{3.}] \Doug\ was born in February, l8l7. His % earliest memories centered around the cabin of his % grandmother, \Bailey. % \item[\textbf{1.}] \Doug\ rose to eminence by sheer force % of character and talents that neither slavery nor caste % proscription could crush. % \end{enumerate*} % % \printindex % \end{document} % \end{VerbatimOut} % % \begin{quote}\small % \VerbatimInput[gobble=0]{\NameauthTestFile} % \end{quote} % % \begin{quote}\small % \begin{enumerate*} % \item[\textbf{1.}] \Doug\ rose to eminence by sheer force % of character and talents that neither slavery nor caste % proscription could crush. % \item[\textbf{2.}] \Doug's early life is perhaps the most % complete indictment of the slave system ever presented at % the bar of public opinion. % \item[\textbf{3.}] \Doug\ was born in February, l8l7. His % earliest memories centered around the cabin of his % grandmother, \Bailey. % \end{enumerate*} % % \ForgetName[Frederick]{Douglass} % \ForgetName[Betsey]{Bailey} % \begin{enumerate*} % \item[\textbf{2.}] \Doug's early life is perhaps the most % complete indictment of the slave system ever presented at % the bar of public opinion. % \item[\textbf{3.}] \Doug\ was born in February, l8l7. His % earliest memories centered around the cabin of his % grandmother, \Bailey. % \item[\textbf{1.}] \Doug\ rose to eminence by sheer force % of character and talents that neither slavery nor caste % proscription could crush. % \end{enumerate*} % \end{quote} % % If we reorder the statements, the names change form automatically. In a book-length project, one might manage hundreds of names, associated information, and index entries. The \textsf{nameauth} package automates aspects of academic and business writing to minimize the work of such management: % % \begin{itemize} % \item Automate the display and formatting of names. % \item Manage and display information that is associated with names. % \item Make decisions relating to names (name control sequence patterns). % \item Sort name index entries properly. % \item Automatically add information to index entries. % \item Ensure correct indexing of names that span page breaks. % \item Change name forms in the text while retaining consistent index entries. % \item Adopt name forms in the text and index that are culturally appropriate. % \item Do not force the user to adopt any one culture's naming conventions. % \item Permit European academic conventions (``Continental'' formatting). % \end{itemize} % % Indexing rules implemented by \textsf{nameauth} are based on \Name[Nancy C.]{Mulvany}, \textit{Indexing Books} (Chicago: University of Chicago Press, 1994). All references [\hypertarget{Mulvany}{Mulvany}] refer to this edition. See also \textit{The Chicago Manual of Style} by the same publisher. % \endgroup % % \begin{Quote}{\ForgetThis\Doug\break % \hbox{}\hfill motto, \textit{The North Star} (Rochester, NY, 1847)} % Right Is of No Sex\,---\,Truth Is of No Color\,---\,God Is the Father % of Us All, and All We Are Brethren.\vspace{-1ex} % \end{Quote} % % \newpage % % \subsection{How To Use the Manual} % \label{sec:ManualUse} % % This manual tries to support various learning styles by using layout, colors, shapes, and similar ordering of both document sections and package code. % % \subsubsection*{Macro Argument Types} % \vspace{-4ex} % % \begin{multicols}{2} % \begin{tcolorbox}[colback=white,colframe=black, % adjusted title={\bfseries\hfil \{Mandatory Arguments\}}] % \centering This manual shows mandatory arguments in black. % \end{tcolorbox} % % \begin{tcolorbox}[colback=white,colframe=nared, % adjusted title={\bfseries\hfil [Optional Arguments]}] % \centering This manual shows optional arguments in dark red. % \end{tcolorbox} % \end{multicols} % % \subsubsection*{Scope and Sequence} % % The table of contents has become detailed in order to indicate more clearly what topics are covered, from frequent and simple to infrequent and complex. Later topics require knowledge from multiple sections. The end of each major section includes a return link to the table of contents. % % \subsubsection*{Key Concepts} % % Throughout much of this manual, starting in Section~\ref{sec:BasicStart}, we use debugging macros (Section~\ref{sec:Debugging}) to show \emph{name control patterns} in the margins (cf. Section~\ref{sec:NamePatterns}). These patterns are the key to how names work in \textsf{nameauth}. Through Section~\ref{sec:NameMedieval} we show \emph{basic index entries} in the margins. These macros and the \texttt{idx} file can aid greatly with complex use cases and subtle issues. % % \subsubsection*{Special Signs} % % \noindent This manual uses signs and illustrative typesetting that are not built-in defaults of \textsf{nameauth}, but in some cases are implemented using it: % % \begin{itemize} % \item[\ \ ]We highlight {\NamesFormat{First Uses}} and % {\MainNameHook{Later Uses}} of names (Sections~\ref{sec:Formatting}, % \ref{sec:NameControl}). % \item[\dag\ ]A dagger indicates reversed Western forms % (Sections~\ref{sec:RevNames}). % \item[\ddag\ ]A double dagger shows usage of the obsolete syntax % (Section~\ref{sec:Obsolete}). % \item[\S\ ]A section mark denotes index entries of fictional names. % \item[\(\leftarrow\)]The\Warn{} ``dangerous bend'' shows where caution % is needed. % \end{itemize} % % \subsubsection*{Example Files} % % The files \texttt{examples.tex} and \texttt{compat.tex} located with this manual. For generating package testing files, see \texttt{README.md}, also located with this manual. % % \begin{InfoBox}[Thanks]\small % For assistance at various times, thanks to \Name[Marc van]{Dongen}, \Name[Enrico]{Gregorio}, \Name[Philipp]{Stephani}, \Name[Heiko]{Oberdiek}, \Name[Uwe]{Lueck}, \Name[Dan]{Luecking}, \Name[Robert]{Schlicht}, and others.\\[1ex] % \hbox{}\hfil \textit{In memoriam} \Name[Robin]{Fairbairns}\\[1ex] % He was very kind when I first uploaded \textsf{nameauth}, and gracious thereafter as well. % \end{InfoBox} % % \newpage % % \subsection{Basic Concepts} % % This section introduces fundamental concepts needed by package users. % % \subsubsection{Name Ambiguity} % \negmedskip % % Apart from cultural context, the elements of a name are ambiguous. The \textsf{nameauth} macros embrace the ambiguity of culture, context, and publishing markets as they create consistent name forms and index entries Let us consider three names from history. Many Western readers will tend to interpret them in this manner: % % \begin{center}\small\medstretch % \begin{tabular}{lll}\toprule % & Forename(s) & Surname\\ % \rowcolor{nagrey}\Name[M.T.]{Cicero}[Marcus Tullius] & % \FName[M.T.]{Cicero}[Marcus Tullius] & % \Name[M.T.]{Cicero}\\ % \Name{Jesus, Christ} & % \Name{Jesus, Christ} & % \ForceFN\FName{Jesus, Christ}\\ % \rowcolor{nagrey}\Name{Pontius, Pilate} & % \Name{Pontius, Pilate} & % \ForceFN\FName{Pontius, Pilate}\\\bottomrule % \end{tabular} % \end{center} % % The problem is that all these interpretations technically are wrong! Yet popular books tend to permit error for the sake of readability. To illustrate that, we encode \Name[M.T.]{Cicero} as a Western name. Yet this approach would be quite incorrect in a scholarly publication or reference work (Section~\ref{sec:Romani}). % % As a Roman \textit{praenomen}, \FName[M.T.]{Cicero}[Marcus] did not have the same importance or meaning as a modern Western forename.\footnote{\url{https://en.wikipedia.org/wiki/Praenomen}} % Moreover, \Name[M.T.]{Cicero} is not the surname of the great Roman orator. His \textit{nomen}, the name of his clan or \textit{gens}, is \FName[M.T.]{Cicero}[Tullius]. For quite some time in English he was known as \IndexRef{Tully}{Cicero, M.T.}\Name{Tully}. The name \Name[M.T.]{Cicero} is a \textit{cognomen}, a name tied to a personal attribute or later, a branch family in a clan. % % The case of \Name*{Jesus, Christ} becomes clearer when we consider \Name*{Jesus, Christ}[of Nazareth] (John 19:19) and \Name*{Jesus, Christ} [son of David] (Mark~10:47; cf. Matthew~1:20). The personal name is \Name{Jesus, Christ} (Greek for Joshua). Adding \ForceFN \FName*{Jesus, Christ}[of Nazareth] and \ForceFN\FName*{Jesus, Christ} [Son of David] shows, respectively, the place of notable origin and family descent. \ForceFN\FName*{Jesus, Christ} is a religious title (Anointed One), a Greek loan-word from Hebrew \textit{mashiach} (Messiah). % % The name \Name*{Pontius, Pilate} is interesting because his \textit{praenomen} has been lost to history. This fits with Roman naming trends at the time. \Name{Pontius, Pilate} is a clan name. Most references, including his own inscriptions, favor his \textit{cognomen} \ForceFN\FName{Pontius, Pilate}[Pilatus], which is due likely to its connection to skill with the \textit{pilum} and martial prowess. % % Thus, in this manual, we make the following name encoding choices, targeted for a ``semi-scholarly'' book that popularizes history for a general Western readership: % % \begin{center}\small\medstretch % \begin{tabular}{lll}\toprule % Macro & Type & Index\\ % \rowcolor{nagrey}|\Name[M.T.]{Cicero}| & % Western name & % \ShowIdxPageref*[M.T.]{Cicero}\\ % |\Name{Jesus, Christ}| & % ancient name & % \ShowIdxPageref*{Jesus, Christ}\\ % \rowcolor{nagrey}|\Name{Pontius, Pilate}| & % ancient name & % \ShowIdxPageref*{Pontius, Pilate}\\\bottomrule % \end{tabular} % \end{center} % % \begin{Quote}{\ForgetThis\Name[M.T.]{Cicero}[Marcus Tullius]\break % \hbox{}\hfill\textit{De oratore} B II; C IX, \S 36} % By what other voice, too, than that of the orator, is history, the evidence of time, the light of truth, the life of memory, the directress of life, the herald of antiquity, committed to immortality?\vspace{-1ex} % \end{Quote} % % \subsubsection{Name Arguments} % \label{sec:NameArgs} % % Below are the forms of name arguments, as defined by the current syntax. Compare [\hyperlink{Mulvany}{Mulvany}, 152--82] and the \textit{Chicago Manual of Style}. \Name[Nancy C.]{Mulvany} offers some excellent advice on names, cross-references, and name variants that can guide one well when using this package. The forms below are an adaptation of these sources to \LaTeX. % % \noindent\begin{tcolorbox}[colframe=naslate, % adjusted title={Western Name: % \oarg{FNN}\marg{SNN, Affix}\oarg{Alternate}}] % \centering\small\smallskip %^^A % \tcbox[equal height group=A,on line,tikznode,colback=white, % adjusted title={\bfseries\sffamily Forename(s):\\ \meta{FNN}}] % {Personal name(s):\\ % \textit{baptismal name}\\ % \textit{Christian name}\\ % \textit{multiple names}\\ % \textit{praenomen}\footnotemark\\ % \phantom{Family\,/\,clan name}}\hfill^^A %^^A % \tcbox[equal height group=A,on line,tikznode,colback=white, % adjusted title={\bfseries\sffamily Surname(s):\\ \meta{SNN}}] % {Family name:\\ % \textit{of father, mother}\\ % \textit{ancestor, vocation}\\ % \textit{origin, region}\\ % \textit{nomen\,/\,cognomen}\\ % \textit{patronym}\\\vspace{-3ex} % \phantom{\textit{nomen\,/\,cognomen}}}\hfill^^A %^^A % \tcbox[equal height group=A,on line,tikznode, % colback=white,colframe=nared, % adjusted title={\bfseries\sffamily Qualifier:\\ \meta{Affix}}] % {Sobriquet/title:\\ % \textit{Sr., Jr., III\dots}\\ % \textit{notable attribute}\\ % \textit{origin, region}\\ % \phantom{\textit{notable attribute}}}\medskip % % \begin{tcolorbox}[colback=white,colframe=nared, % adjusted title={\bfseries\sffamily Alternate Name(s): % \meta{Alternate}}] % \centering Replaces \meta{FNN} only in the text. % \end{tcolorbox}\negsmallskip % % \end{tcolorbox} % \footnotetext{There are several ways of handling the Roman \textit{tria % nomina}. See Section~\ref{sec:Romani}.} % % \begin{tcolorbox}[colframe=naslate, % adjusted title={``Native'' Eastern Name}: % \marg{SNN, Affix}\oarg{Alternate}] % \centering\small\smallskip % % \tcbox[equal height group=B,on line,tikznode, % colback=white, % adjusted title={\bfseries\sffamily Family name:\\ \meta{SNN}}] % {Family\,/\,clan name}\hfill^^A %^^A % \tcbox[equal height group=B,on line, % tikznode,colback=white, % adjusted title={\bfseries\sffamily Personal name:\\ \meta{Affix}}] % {Few multiple\\ % names; multi-\\ % character okay.\\\vspace{-3ex} % \phantom{\textit{nomen\,/\,cognomen}}}\hfill^^A %^^A % \tcbox[equal height group=B,on line,tikznode, % colback=white,colframe=nared, % adjusted title={\bfseries\sffamily Alt. name:\\ \meta{Alternate}}] % {Replaces \meta{Affix}\\ % only in text.\footnotemark\\ % \phantom{\textit{notable attribute}}}\smallskip % \end{tcolorbox} % \footnotetext{The obsolete syntax uses \meta{Alternate} instead of % \meta{Affix} for a personal name (Section~\ref{sec:Obsolete}).} % % \begin{tcolorbox}[colframe=naslate, % adjusted title={Royal/Medieval/Ancient Name}: % \marg{SNN, Affix}\oarg{Alternate}] % \centering\small\smallskip % % \tcbox[equal height group=C,on line,tikznode,colback=white, % adjusted title={\bfseries\sffamily Personal name:\\ \meta{SNN}}] % {\small Given name(s)\\ % \phantom{Family\,/\,clan name}}\hfill^^A %^^A % \tcbox[equal height group=C,on line,tikznode, % colback=white,colframe=nared, % adjusted title={\bfseries\sffamily Qualifier:\\ \meta{Affix}}] % {Sobriquet/title:\\ % \textit{Sr., Jr., III\dots}\\ % \textit{notable attribute}\\ % \textit{origin, region}\\ % \textit{patronym}\\\vspace{-3ex} % \phantom{\textit{nomen\,/\,cognomen}}}\hfill^^A %^^A % \tcbox[equal height group=C,on line,tikznode, % colback=white,colframe=nared, % adjusted title={\bfseries\sffamily Alt. name:\\ \meta{Alternate}}] % {Replaces \meta{Affix}\\ % only in text.\footnotemark\\ % \phantom{\textit{notable attribute}}}\smallskip % \end{tcolorbox} % \footnotetext{The obsolete syntax uses \meta{Alternate} instead of % \meta{Affix} for a qualifier (Section~\ref{sec:Obsolete}).} % % \newpage % % \subsubsection[Final Optargs]{Final Optional Arguments} % \label{sec:FinalOptargs} % % Macros that take name arguments (Sections~\ref{sec:NameArgs} and~\ref{sec:NameArgMacros}) have the potential to contain a final optional argument. Their trailing arguments look like: % % \begin{tcolorbox}[colframe=naslate]\centering % \begin{tabular}{c@{ }c} % \small Required & \small Optional\\ % \tcbox[equal height group=E,colback=white, % tikznode,left=1mm,right=1mm,valign=center] % {\bfseries\dots\marg{SNN\color{nared}, Affix}} & % \tcbox[equal height group=E,colback=white, % tikznode,left=1mm,right=1mm,valign=center] % {\bfseries\oarg{\color{nared}Alternate}} % \end{tabular} % \end{tcolorbox}\smallskip % % Usually these arguments have no side effects, except in the case where we want to follow a name with an editorial insertion enclosed in square brackets. Since this does occur in academic and journalistic writing, we show how to handle this below and on the next page, where we suppress formatting to focus on syntax: % % \begin{VerbatimOut}{\jobname.tmp} % \begin{itemize} % \item We are looking for ``Albert Einstein [said]'' and % ``Miyazaki Hayao [said]''; also ``Einstein [said]'' % and ``Miyazaki [said]''. % \item We get ``\Name[Albert]{Einstein} [said]'' and % ``\Name{Miyazaki, Hayao} [said]''. % The personal names got replaced with alternate % name arguments in the long name forms. % \item Repeating does not help: ``\Name[Albert]{Einstein} % [said]'' and ``\Name{Miyazaki, Hayao} [said]''. % The text \texttt{[said]} was not displayed due to % shorter name forms being shown by default in % subsequent name uses. % \item[] \textbf{We fix the situation thus:} % \item Add explicit spaces: ``\Name[Albert]{Einstein}\ % [said]'' and ``\Name {Miyazaki, Hayao}\ [said]''. % \item Add curly braces: ``\Name[Albert]{Einstein}{} % [said]'' and ``\Name{Miyazaki, Hayao}{} [said]''. % \end{itemize} % \end{VerbatimOut} % % \begin{quote}\small % \VerbatimInput[gobble=0]{\jobname.tmp} % \renewcommand\NamesFormat{} % \renewcommand\MainNameHook{} % % \input{\jobname.tmp} % \end{quote} % % The same situation and resolution happens also when name shorthands have been defined. For example, ``\cmd{\Einstein\textbackslash\ [said]}'' produces ``\Einstein\ [said]'' and ``\cmd{\Miyazaki\textbackslash\ [said]}'' produces ``\Miyazaki\ [said]''. This situation does not arise with great frequency, but it can crop up occasionally and may leave one scratching one's head over something odd in the text. % % \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}). Thus, this section and its subsection are the most critical to understanding and mastering the use of \textsf{nameauth}. % % \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 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. % \end{itemize} % % \subsubsection{Western Names} % \negsmallskip % % \begin{tcolorbox}[colframe=naslate]\centering\small % \begin{tabular}{l@{ }c@{ }c@{ }c} % & Required & Required \meta{SNN} & Optional\\ % & \meta{FNN} & optional \meta{Affix} & (text only)\\[1ex] % \tcbox[equal height group=D,colback=white,tikznode, % left=1mm,right=1mm,valign=center] % {\normalsize\bfseries \hbox{\cmd{\Name}\texttt{ }}\\ % \cmd{\Name*}\\ % \cmd{\FName}} & % \tcbox[equal height group=D,colback=white,tikznode, % left=1mm,right=1mm,valign=center] % {\normalsize\bfseries\oarg{FNN}} & % \tcbox[equal height group=D,colback=white,tikznode, % left=1mm,right=1mm,valign=center] % {\normalsize\bfseries\marg{SNN\color{nared}, Affix}} & % \tcbox[equal height group=D,colback=white,tikznode, % left=1mm,right=1mm,valign=center] % {\normalsize\bfseries\oarg{\color{nared}Alternate}} % \end{tabular} % \end{tcolorbox}\medskip % % \noindent % Within \textsf{nameauth}, Western names have distinct features: % % \begin{itemize} % \item Western names must use the first optional \meta{FNN} argument. % \item They require a comma to delimit any affixes % (Section~\ref{sec:Affix}). % \item Western index entries have two general forms: % \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. \cmd{\FName} prints long in first uses, then just a forename in later uses. \cmd{\FName*} does the same thing as \cmd{\FName} (just add an \texttt{F}\dots). The affix in a surname only appears in long name references. % % \begin{Block} % \vspace{3.5ex} % \BothInfo{\ShowPattern[George]{Washington}\break % \ShowPattern[George S.]{Patton, Jr.}} % {\ShowIdxPageref*[George]{Washington}\break % \ShowIdxPageref*[George S.]{Patton, Jr.}} % \vspace{-3.5ex} % \FUse |\Name [George]{Washington}|\dotfill \Name [George]{Washington}\\ % \LUse |\Name*[George]{Washington}|\dotfill \Name*[George]{Washington}\\ % \LUse |\Name [George]{Washington}|\dotfill \Name [George]{Washington}\\ % \LUse |\FName[George]{Washington}|\dotfill \FName[George]{Washington} % \end{Block}\negmedskip % % \begin{Block} % \FUse |\Name [George S.]{Patton, Jr.}|\dotfill % \Name [George S.]{Patton, Jr.}\\ % \LUse |\Name*[George S.]{Patton, Jr.}|\dotfill % \Name*[George S.]{Patton, Jr.}\\ % \LUse |\Name [George S.]{Patton, Jr.}|\dotfill % \Name [George S.]{Patton, Jr.}\\ % \LUse |\FName[George S.]{Patton, Jr.}|\dotfill % \FName[George S.]{Patton, Jr.} % \end{Block} % % \subsubsection*{\hfil Affixes and Alternate Forms} % % In a long name reference, \cmd{\DropAffix} drops a name affix from a Western name. The \meta{Alternate} argument permits changes in the text only for long references and forename-only references. Otherwise, the automatic shortening of names will display only a short surname. % % \begin{itemize} % \vspace{5ex} % \BothInfo{\ShowPattern[George S.]{Patton, Jr.}\break % \ShowPattern[J.D.]{Rockefeller, IV}\break % \ShowPattern[Clive Staples]{Lewis}} % {\ShowIdxPageref*[George S.]{Patton, Jr.}\break % \ShowIdxPageref*[J.D.]{Rockefeller, IV}\break % \ShowIdxPageref*[Clive Staples]{Lewis}} % \vspace{-5ex} % \item Drop the affix in a long name reference:\\[1ex] % \FUse |\DropAffix\Name*[George S.]{Patton, Jr.}|\dotfill\hbox{}\\ % \hbox{}\dotfill \ForgetThis\DropAffix\Name*[George S.]{Patton, Jr.}\\ % \LUse |\DropAffix\Name*[George S.]{Patton, Jr.}|\dotfill\hbox{}\\ % \hbox{}\dotfill \DropAffix\Name*[George S.]{Patton, Jr.} % \item Use an alternate forename in a long name or forename % reference:\\[1ex] % \FUse \cmd{\Name[J.D.]\{Rockefeller, IV\}[John Davison]}\dotfill % \hbox{}\\ % \hbox{}\dotfill\Name[J.D.]{Rockefeller, IV}[John Davison]\\ % \LUse |\FName[George S.]{Patton, Jr.}[George]|\dotfill % \FName[George S.]{Patton, Jr.}[George] % \item Drop the affix and alter the forenames:\\[1ex] % \FUse |\DropAffix\Name*[J.D.]{Rockefeller, IV}[Jay]|\dotfill\hbox{}\\ % \hbox{}\dotfill\ForgetThis\DropAffix\Name*[J.D.]{Rockefeller, IV}[Jay] % \LUse |\DropAffix\Name*[J.D.]{Rockefeller, IV}[Jay]|\dotfill\hbox{}\\ % \hbox{}\dotfill\DropAffix\Name*[J.D.]{Rockefeller, IV}[Jay] % \item Use multiple alternate forenames for the same person:\\[1ex] % \FUse |\Name [Clive Staples]{Lewis}|\dotfill \Name [Clive Staples]{Lewis}\\ % \LUse |\Name*[Clive Staples]{Lewis}[C.S.]|\dotfill % \Name*[Clive Staples]{Lewis}[C.S.]\\ % \LUse |\FName[Clive Staples]{Lewis}[Jack]|\dotfill % \FName[Clive Staples]{Lewis}[Jack] % \end{itemize} % \negmedskip % % To sort the index consistently and properly, all names should be sorted by their longest unique name forms and by the Arabic equivalents of Roman numerals. See Section~\ref{sec:NameMedieval}, \ref{sec:IndexSort}, \ref{sec:IndexInitials}, \ref{sec:VarNames}. and all of Section~\ref{sec:AdvancedFormat}. % % \begin{itemize} % \item[] For example, with the name \LJRIV: % \item The initials \texttt{J.D.} become \texttt{John D} in the sort tag. % \item The affix \texttt{IV} becomes \texttt{4}. % \item |\PretagName[J.D.]{Rockefeller, IV}{Rockefeller, John D 4}| % \end{itemize} % % \begin{Quote}{\ForgetThis\Wash, Farewell Address (1796)} % The alternate domination of one faction over another, sharpened by the spirit of revenge, \dots is itself a frightful despotism. But this leads at length to a more formal and permanent despotism. The disorders and miseries, which result, gradually incline the minds of men to seek security and repose in the absolute power of an individual; and sooner or later the chief of some prevailing faction, more able or more fortunate than his competitors, turns this disposition to the purposes of his own elevation, on the ruins of Public Liberty. % \end{Quote} % % \subsubsection[Reversed Western]{Reversed Western Names} % \negsmallskip % % \begin{tcolorbox}[colframe=naslate]\centering\small % \begin{tabular}{l@{ }c@{ }c@{ }c} % & Required & Required \meta{SNN} & Optional\\ % & \meta{FNN} & no \meta{Affix} & (text only)\\[1ex] % \tcbox[equal height group=D,colback=white,tikznode, % left=1mm,right=1mm,valign=center] % {\normalsize\bfseries \hbox{\cmd{\Name}\texttt{ }}\\ % \cmd{\Name*}\\ % \cmd{\FName}} & % \tcbox[equal height group=D,colback=white,tikznode, % left=1mm,right=1mm,valign=center] % {\normalsize\bfseries\oarg{FNN}} & % \tcbox[equal height group=D,colback=white,tikznode, % left=1mm,right=1mm,valign=center] % {\normalsize\bfseries\quad\marg{SNN}\quad\hbox{}} & % \tcbox[equal height group=D,colback=white,tikznode, % left=1mm,right=1mm,valign=center] % {\normalsize\bfseries\oarg{\color{nared}Alternate}} % \end{tabular} % \end{tcolorbox}\medskip % % \noindent % Reversed Western names (Section~\ref{sec:RevNames}) have these features: % % \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}). % \end{itemize} % % \subsubsection*{\hfil Starting with Western Name Forms} % % \leavevmode^^A % \BothInfo{\ShowPattern[Frenec]{Molnár}\break % \ShowPattern[Hideyo]{Noguchi}} % {\ShowIdxPageref*[Hideyo]{Noguchi}\break % \ShowIdxPageref*[Frenec]{Molnár}} % These reversed Western forms are used optimally in a context where Hungarian names and similar cases of name order appear in a document because their index entries take a Western form [\hyperlink{Mulvany}{Mulvany}, 166].\footnote{Regarding the margin note that shows name control sequences, with \texttt{pdflatex} and \texttt{latex}, in \texttt{\ShowPattern[Frenec]{Molnár}} the glyphs \texttt{Ãą} correspond to \cmd{\IeC\{\textbackslash\textquotesingle a\}}.} % % \begin{Block} % \FUse |\Name [Frenec]{Molnár}|\dotfill \Name [Frenec]{Molnár}\\ % \FUse |\Name [Hideyo]{Noguchi}|\dotfill \Name [Hideyo]{Noguchi}\\ % \LUse |\Name*[Hideyo]{Noguchi}[Doctor]|\dotfill \Name*[Hideyo]{Noguchi}[Doctor] % \end{Block} % % \subsubsection*{\hfil Using the Reversing Macros} % % \noindent We use the prefix macros \cmd{\RevName} and optionally \cmd{\CapName} (Section~\ref{sec:SelectOver}) to print a Hungarian or ``non-native'' Eastern name in the text while keeping Western forms in the index. These macros, as is the case with many \textsf{nameauth} macros, work properly in context, not arbitrarily: % % \begin{Block} % \LUse |\RevName\Name*[Frenec]{Molnár}\dag|\Same\dotfill % \RevName\Name*[Frenec]{Molnár}\dag\\ % \LUse |\RevName\Name [Frenec]{Molnár}\dag|\dotfill % \RevName\Name [Frenec]{Molnár}\dag\\ % \LUse |\CapName\RevName\Name*[Hideyo]{Noguchi}[Sensei]\dag|\dotfill\\ % \hbox{}\dotfill \CapName\RevName\Name*[Hideyo]{Noguchi}[Sensei]\dag\\ % \LUse |\CapName\RevName\Name [Hideyo]{Noguchi}[Sensei]\dag|\dotfill\\ % \hbox{}\dotfill \CapName\RevName\Name [Hideyo]{Noguchi}[Sensei]\dag % \end{Block} % % If Western names are reversed to have Eastern order, they will have Eastern name order in the text, but \emph{they will retain Western-form index entries.} The reversing macros help when a publication uses only Western name entries in the index, or when printing and indexing names with requirements like Hungarian names. % % \subsubsection{Eastern Names} % % All non-Western name forms in \textsf{nameauth} have the syntax: \meta{SNN,Affix}. In Eastern names, \meta{SNN} refers to a family name and \meta{Affix} to a personal name. Otherwise, \meta{SNN} refers to a person's name and \meta{Affix} to added information. Knowing this difference helps one avoid nonsense names.\medskip % % \negsmallskip\begin{tcolorbox}[colframe=naslate]\centering\small % \begin{tabular}{l@{ }c@{ }c} % & Required \meta{SNN} & Optional\\ % & required \meta{Affix} & (text only)\\[1ex] % \tcbox[equal height group=D,colback=white,tikznode, % left=1mm,right=1mm,valign=center] % {\normalsize\bfseries \hbox{\cmd{\Name}\texttt{ }}\\ % \cmd{\Name*}\\ % \cmd{\FName}} & % \tcbox[equal height group=D,colback=white,tikznode, % left=1mm,right=1mm,valign=center] % {\normalsize\bfseries\marg{SNN, Affix}} & % \tcbox[equal height group=D,colback=white,tikznode, % left=1mm,right=1mm,valign=center] % {\normalsize\bfseries\oarg{\color{nared}Alternate}} % \end{tabular} % \end{tcolorbox}\medskip % % \noindent % These features denote ``native'' Eastern names in \textsf{nameauth} (Sections~\ref{sec:Eastern}, \ref{sec:RevNames}): % % \begin{itemize} % \item They must \emph{leave empty} the \meta{FNN} argument. % \item They use instead the \meta{SNN, Affix} arguments. % \item Their index entries take the non-Western form: \meta{SNN Affix}. % \item Names with the form \meta{SNN, Affix} can use the \meta{Alternate} % argument to swap \meta{Affix} with \meta{Alternate}. % \item They have non-Western name patterns and index entry forms. % \end{itemize} % % \subsubsection*{\hfil ``Native'', Reversible Eastern Name Forms} % % Among the names shown below, \cmd{\FName} does not show a personal name by default. This design helps to prevent Western writers from being culturally insensitive. % % \begin{Block} % \vspace{3.5ex} % \BothInfo{\ShowPattern{Miyazaki, Hayao}} % {\ShowIdxPageref*{Miyazaki, Hayao}} % \vspace{-3.5ex} % \FUse |\Name {Miyazaki, Hayao}|\dotfill % \ForgetThis\Name {Miyazaki, Hayao}\\ % \LUse |\Name {Miyazaki, Hayao}|\dotfill \Name {Miyazaki, Hayao}\\ % \LUse |\Name*{Miyazaki, Hayao}[Sensei]|\dotfill % \Name*{Miyazaki, Hayao}[Sensei]\\ % \LUse |\FName{Miyazaki, Hayao}|\dotfill \FName{Miyazaki, Hayao} % \end{Block} % % One must use \cmd{\ForceFN} with \cmd{\FName} (Section~\ref{sec:FName}) to get a personal name. \meta{Alternate} swaps with \meta{FNN} (in both long forms and in short forms) in the text only. \meta{Alternate} does not work with the obsolete syntax (Section~\ref{sec:Obsolete}): % % \begin{Block} % \LUse |\ForceFN\FName{Miyazaki, Hayao}|\Same\dotfill % \ForceFN\FName{Miyazaki, Hayao}\\ % \LUse |\CapName\Name*{Miyazaki, Hayao}[Sensei]|\dotfill % \CapName\Name*{Miyazaki, Hayao}[Sensei]\\ % \LUse |\ForceFN\FName{Miyazaki, Hayao}[Sensei]|\dotfill % \ForceFN\FName{Miyazaki, Hayao}[Sensei]\\ % \LUse |\RevName\Name*{Miyazaki, Hayao}[Mr.]|\dotfill % \RevName\Name*{Miyazaki, Hayao}[Mr.] % \end{Block} % % If ``native'' Eastern names are reversed, they will have Western name order in the text, but \emph{they will retain Eastern-form index entries.} % % \begin{Quote}{\Name[Harold]{Urey} (1961)} % The space program is not only scientific in purpose but also is an expression of man's insistent determination to do the nearly impossible\,---\,to explore the unknown, even at great risk.\vspace{-1ex} % \end{Quote} % % \newpage % % \subsubsection[Ancient Names]{Royal, Medieval, and Ancient Names} % \negsmallskip % % \begin{tcolorbox}[colframe=naslate]\centering\small % \begin{tabular}{l@{ }c@{ }c} % & Required \meta{SNN} & Optional,\\ % & optional \meta{Affix} & special\\[1ex] % \tcbox[equal height group=D,colback=white,tikznode, % left=1mm,right=1mm,valign=center] % {\normalsize\bfseries \hbox{\cmd{\Name}\texttt{ }}\\ % \cmd{\Name*}\\ % \cmd{\FName}} & % \tcbox[equal height group=D,colback=white,tikznode, % left=1mm,right=1mm,valign=center] % {\normalsize\bfseries\marg{SNN\color{nared}, Affix}} & % \tcbox[equal height group=D,colback=white,tikznode, % left=1mm,right=1mm,valign=center] % {\normalsize\bfseries\oarg{\color{nared}Alternate}} % \end{tabular} % \end{tcolorbox}\medskip % % \noindent % These features denote royal, medieval, and ancient names in \textsf{nameauth}, grouped under the general rubric of ``non-Western'' name forms: % % \begin{itemize} % \item They must \emph{leave empty} the \meta{FNN} argument. % \item They use either the \meta{SNN, Affix} arguments or just \meta{SNN}. % \item Their index entries take the non-Western forms: \meta{SNN Affix} % or \meta{SNN}. % \item Names with the form \meta{SNN, Affix} can use the \meta{Alternate} % argument to swap \meta{Affix} with \meta{Alternate}. % \item Names with the form \meta{SNN} should not use \meta{Alternate} % (cf. Section~\ref{sec:Obsolete}). % \item They have non-Western name patterns and index entry forms. % \item One generally does not reverse these names (Section~\ref{sec:RevNames}). % \end{itemize} % % \subsubsection*{\hfil No School Like the Old School} % % \begin{itemize} % \vspace{3ex} % \BothInfo{\ShowPattern{Elizabeth, I}\break % \ShowPattern{John, Eriugena}\break % \ShowPattern{Aristotle}} % {\ShowIdxPageref*{Elizabeth, I}\break % \ShowIdxPageref*{John, Eriugena}\break % \ShowIdxPageref*{Aristotle}} % \vspace{-3ex} % \item \cmd{\FName} normally prints \meta{SNN} to avoid nonsense names % in the text.\\[1ex] % \FUse |\Name {Elizabeth, I}|\dotfill \Name {Elizabeth, I}\\ % \LUse |\Name {Elizabeth, I}|\dotfill \Name {Elizabeth, I}\\ % \LUse |\FName{Elizabeth, I}|\dotfill \FName{Elizabeth, I} % % \item Here we work with titles and sobriquets:\\[1ex] % \FUse |\ForgetThis\Name{Elizabeth, I}[I ``Gloriana'']|\dotfill\hbox{}\\ % \hbox{}\dotfill \ForgetThis\Name{Elizabeth, I}[I ``Gloriana''] % \LUse |\ForceFN\FName{Elizabeth, I}[Gloriana]|\dotfill % \ForceFN\FName{Elizabeth, I}[Gloriana] % % \item Here we show a non-royal:\\[1ex] % \FUse |\Name {John, Eriugena}[Scotus Eriugena]|\dotfill\hbox{}\\ % \hbox{}\dotfill \Name {John, Eriugena}[Scotus Eriugena]\\ % \LUse |\Name*{John, Eriugena}|\dotfill \Name*{John, Eriugena}\\ % \LUse |\Name {John, Eriugena}|\dotfill \Name {John, Eriugena}\\ % \LUse |\ForceFN\FName{John, Eriugena}|\dotfill % \ForceFN\FName{John, Eriugena} % % \item These are nonsense names:\\[1ex] % \LUse |\ForceFN\FName{Elizabeth, I}|\dotfill % \ForceFN\FName{Elizabeth, I}\\ % \LUse |\RevName\Name*{John, Eriugena}|\dotfill % \RevName\Name*{John, Eriugena} % % \item The trivial case:\\[1ex] % \FUse |\Name{Aristotle}|\dotfill \Name{Aristotle}\\ % \LUse |\Name{Aristotle}|\dotfill \Name{Aristotle} % \end{itemize} % % \newpage % % \subsection{Quick Interface} % \label{sec:QuickUIStart} % % \subsubsection{Name Shorthands} % % \DescribeEnv{nameauth} % To reduce typing, we replace frequently-used macros with the shorthand forms of the quick interface. Using the \texttt{nameauth} environment in the preamble guards against undefined macros. It defines a delimited macro \cmd{\<}, recalling a \texttt{tabular}: % % \begin{SyntaxBox} % \cmd{\begin\{nameauth\}}\\ % \hspace{2em}\cmd{\<} \meta{arg1} \texttt{\&} % \meta{arg2} \texttt{\&} % \meta{arg3} \texttt{\&} % \meta{arg4} \texttt{>}\\ % \cmd{\end\{nameauth\}} % \end{SyntaxBox} % % In this context, \meta{arg1} becomes the root of three new macros per name:\medskip % % \begin{tabular}{@{\quad}l@{\ same as: }ll} % \texttt{\textbackslash}\meta{arg1} & % \cmd{\Name\ }\oarg{arg2}\marg{arg3}\oarg{arg4} \\ % \texttt{\textbackslash L}\meta{arg1} & % \cmd{\Name*}\oarg{arg2}\marg{arg3}\oarg{arg4} & % {\color{nared} |%| L for \textit{long}} \\ % \texttt{\textbackslash S}\meta{arg1} & % \cmd{\FName}\oarg{arg2}\marg{arg3}\oarg{arg4} & % {\color{nared} |%| S for \textit{short}} \\ % \end{tabular}\medskip % % Usually we leave \meta{arg4} empty, apart from specific contexts. That field permanently displays only alternate names, or is used with the obsolete syntax (Section~\ref{sec:Obsolete}). Here is another way of thinking about arguments in the \texttt{nameauth} environment that relates back to what we have seen: % % \begin{SyntaxBox} % \cmd{\begin\{nameauth\}}\\ % \hspace{2em}\cmd{\<} \meta{arg1} \texttt{\&} % \meta{\color{nared}FNN} \texttt{\&} % \meta{SNN\color{nared}, Affix} \texttt{\&} % \meta{\color{nared}Alternate} \texttt{>}\\ % \cmd{\end\{nameauth\}} % \end{SyntaxBox} % % By seeing the mandatory arguments in black and the optional ones in red, it helps us to see that, if either \meta{arg1} or \meta{arg3} are empty, or \meta{SNN} is empty, \textsf{nameauth} will generate a package error. Forgetting the backslash, any ampersand, or angle bracket will cause fatal errors. See Section~\ref{sec:FinalOptargs} on final optional arguments.\medskip % % Package warnings\Warn\ result when one redefines name shorthands using the \texttt{nameauth} environment. For example, we use \texttt{White} in two different rows to populate \meta{Arg1}. That causes \cmd{\White}, \cmd{\LWhite}, and \cmd{\SWhite} to be redefined: % % \begin{quote}\small % \begin{Verbatim} % \begin{nameauth} % \< White & E.B. & White & > % version 1 % \< White & E.\,B. & White & > % version 2 % \end{nameauth} % \end{Verbatim} % \end{quote} % \begin{nameauth} % \< White & E.B. & White & > ^^A version 1 % \< White & E.\,B. & White & > ^^A version 2 % \end{nameauth} % % \cmd{\White} produces \White, the version with the thin space. We lost the first version of the name when we redefined it.\footnote{When building this package there should be a warning: \texttt{Shorthand macro already exists.} This is intentional, meant to test if the warning is working properly.} % % On the next page we will create an example \texttt{nameauth} environment using many of the names that we have so far encountered. We will add other names that we have not yet seen, introducing additional concepts in the process. Those include Western name forms that contain particles (usually prepositions or clan designators), which are discussed in greater detail in Section~\ref{sec:NameParticles}. % % \newpage % % The comments below are merely explanatory and in no wise required to use the environment. Likewise, extra spaces that are added for clarity are stripped. % % \begin{quote}\small % \begin{Verbatim} % \begin{nameauth} % % Western Name Forms % % % \< Wash & George & Washington & > % \< Lewis & Clive Staples & Lewis & > % % Western Name Forms with Affixes % \< Patton & George S. & Patton, Jr. & > % \< JRIV & J.D. & Rockefeller, IV & > % % Western Name Forms with Particles % \< Soto & Hernando & de Soto & > % \< JWG & J.W. von & Goethe & > % \< VBuren & Martin & Van Buren & > % % Reversed Western Forms % \< Noguchi & Hideyo & Noguchi & > % \< Molnar & Frenec & Molnár & > % % ``Native'' Eastern Forms % \< Miyazaki & & Miyazaki, Hayao & > % % Royal, Medieval, and Ancient Forms % \< Eliz & & Elizabeth, I & > % \< Aeth & & Æthelred, II & > % \< Eriugena & & John, Eriugena & > % \< Aris & & Aristotle & > % % Name Forms Always Using Alternate Names % \< CSL & Clive Staples & Lewis & C.S. > % \< MSens & & Miyazaki, Hayao & Sensei > % \end{nameauth} % \end{Verbatim} % \end{quote} % % Here is an example of how much typing one can save with the quick interface, not to mention the prevention of error by not retyping arguments: % \begin{center}\small\medstretch % \begin{tabular}{rll}\toprule % Output & & Macro\\ % \rowcolor{nagrey}\Wash & Quick: & \cmd{\Wash}\\ % \rowcolor{nagrey} & Basic: & % \cmd{\Name}\texttt{[George]\{Washington\}}\\ % \LWash & Quick: & \cmd{\LWash}\\ % & Basic: & % \cmd{\Name*}\texttt{[George]\{Washington\}}\\ % \rowcolor{nagrey}\SWash & Quick: & \cmd{\SWash}\\ % \rowcolor{nagrey} & Basic: & % \cmd{\FName}\texttt{[George]\{Washington\}}\\ % \ForgetThis\Wash & Quick: & \cmd{\ForgetThis}\cmd{\Wash}\\ % & Basic: & % \cmd{\ForgetName}\texttt{[George]\{Washington\}}\\ % & & % \cmd{\Name}\texttt{[George]\{Washington\}}\\ % \rowcolor{nagrey}\ForgetThis\Wash & Quick: & \cmd{\ForgetThis}\cmd{\Wash}\\ % \rowcolor{nagrey} & Basic: & % \cmd{\ForgetThis}\cmd{\Name}\texttt{[George]\{Washington\}}\\ % \SubvertThis\Wash & Quick: & \cmd{\SubvertThis}\cmd{\Wash}\\ % & Basic: & % \cmd{\SubvertName}\texttt{[George]\{Washington\}}\\ % & & % \cmd{\Name}\texttt{[George]\{Washington\}}\\ % \rowcolor{nagrey}\SubvertThis\Wash & Quick: & \cmd{\SubvertThis}\cmd{\Wash}\\ % \rowcolor{nagrey} & Basic: & % \cmd{\SubvertThis}\cmd{\Name}\texttt{[George]\{Washington\}}\\ % \JustIndex\Wash(unseen in text) & Quick: & \cmd{\JustIndex}\cmd{\Wash}\\ % & Basic: & % \cmd{\IndexName}\texttt{[George]\{Washington\}}\\\bottomrule % \end{tabular} % \end{center} % % \subsubsection[Name Variants]{Quick Name Variant Overview} % % After setting up the previous environment, we can use the resulting name shorthands. Below we introduce more ``prefix macros'' that affect syntactic forms of names. For the sake of clarity we use but do not show the prefix macro \cmd{\ForgetThis} (Section~\ref{sec:NameControl}), which produces a first use of a name. % % \vspace{4ex} % \BothInfo{\ShowPattern[George]{Washington}\break % \ShowPattern[Hernando]{de~Soto}\break % \ShowPattern[George S.]{Patton, Jr.}\break % \ShowPattern[J.D.]{Rockefeller, IV}\break % \ShowPattern[Clive Staples]{Lewis}\break % \ShowPattern{Aristotle}\break % \ShowPattern{Æthelred, II}\break % \ShowPattern{John, Eriugena}\break % \ShowPattern[Hideyo]{Noguchi}\break % \ShowPattern{Miyazaki, Hayao}} % {\ShowIdxPageref*[George]{Washington}\break % \ShowIdxPageref*[Hernando]{de~Soto}\break % \ShowIdxPageref*[George S.]{Patton, Jr.}\break % \ShowIdxPageref*[J.D.]{Rockefeller, IV}\break % \ShowIdxPageref*[Clive Staples]{Lewis}\break % \ShowIdxPageref*{Aristotle}\break % \ShowIdxPageref*{Æthelred, II}\break % \ShowIdxPageref*{John, Eriugena}\break % \ShowIdxPageref*[Hideyo]{Noguchi}\break % \ShowIdxPageref*{Miyazaki, Hayao}} % \vspace{-4ex} % \begin{Block} % \textsc{Western:} \hfill (Sections~\ref{sec:Naming}, % \ref{sec:FName}\\ % \FUse \cmd{\Wash}\dotfill \ForgetThis\Wash\\ % \LUse \cmd{\LWash}\dotfill \LWash\\ % \LUse \cmd{\Wash}\dotfill \Wash\\ % \LUse \cmd{\SWash}\dotfill \SWash % \end{Block} % % \begin{Block} % \textsc{Nicknames and Affixes:} \hfill % (Sections~\ref{sec:FName}, \ref{sec:Affix})\\ % \FUse \cmd{\DropAffix}\cmd{\Patton}\hfill % \ForgetThis\DropAffix\Patton\\ % \LUse \cmd{\LPatton}\dotfill \LPatton\\ % \LUse \cmd{\DropAffix}\cmd{\LPatton}\dotfill \DropAffix\LPatton\\ % \LUse \cmd{\Patton}\dotfill \Patton\medskip % % \FUse \cmd{\Patton}\dotfill \ForgetThis\Patton\\ % \LUse \cmd{\DropAffix}\cmd{\LPatton}\dotfill % \DropAffix\LPatton\\ % \LUse \cmd{\DropAffix}\cmd{\LPatton[George]}\dotfill % \DropAffix\LPatton[George]\\ % \LUse \cmd{\SPatton[George]}\dotfill \SPatton[George]\medskip % % \FUse \cmd{\JRIV[John Davison]}\dotfill % \ForgetThis\JRIV[John Davison]\\ % \LUse \cmd{\LJRIV}\dotfill \LJRIV\\ % \LUse \cmd{\DropAffix}\cmd{\LJRIV[Jay]}\dotfill % \DropAffix\LJRIV[Jay]\medskip % % \FUse \cmd{\Lewis}\dotfill \ForgetThis\Lewis\\ % \LUse \cmd{\LLewis[C.S.]}\dotfill \LLewis[C.S.]\\ % \LUse \cmd{\LLewis[Jack]}\dotfill \LLewis[Jack]\\ % \LUse \cmd{\SLewis}\dotfill \SLewis\\ % \LUse \cmd{\SLewis[Jack]}\dotfill \SLewis[Jack]\\ % \LUse \cmd{\LCSL}\dotfill \LCSL\\ % \LUse \cmd{\SCSL}\dotfill \SCSL % \end{Block} % % \begin{Block} % \textsc{``Native'' Eastern:} \hfill (Section~\ref{sec:Eastern})\\ % \FUse \cmd{\CapName}\cmd{\Miyazaki}\dotfill % \ForgetThis\CapName\Miyazaki\\ % \LUse \cmd{\CapName}\cmd{\LMiyazaki}\dotfill % \CapName\LMiyazaki\\ % \LUse \cmd{\CapName}\cmd{\Miyazaki}\dotfill % \CapName\Miyazaki\\ % \LUse \cmd{\RevName}\cmd{\LMiyazaki}\dotfill % \RevName\LMiyazaki\\ % \LUse \cmd{\RevName}\cmd{\LMiyazaki[Mr.]}\dotfill % \RevName\LMiyazaki[Mr.]\\ % \LUse \cmd{\SMiyazaki}\dotfill \SMiyazaki\\ % \LUse \cmd{\ForceFN}\cmd{\SMiyazaki}\dotfill % \ForceFN\SMiyazaki % \end{Block} % % \begin{Block} % \textsc{Reversed Western:} \hfill (Section~\ref{sec:RevNames})\\ % \FUse \cmd{\Noguchi}\dotfill \ForgetThis\Noguchi\\ % \LUse \cmd{\LNoguchi}\dotfill \LNoguchi\\ % \LUse \cmd{\LNoguchi[Doctor]}\dotfill \LNoguchi[Doctor]\\ % \LUse \cmd{\SNoguchi}\dotfill \SNoguchi\\ % \LUse \cmd{\RevName}\cmd{\LNoguchi}\cmd{\dag}\dotfill % \RevName\LNoguchi\dag\\ % \LUse \cmd{\CapName}\cmd{\RevName}\cmd{\LNoguchi}\cmd{\dag}\dotfill % \CapName\RevName\LNoguchi\dag\\ % \LUse \cmd{\CapName}\cmd{\Noguchi}\cmd{\dag}\dotfill % \CapName\Noguchi\dag % \end{Block} % % \begin{Block} % \textsc{Western, Reversed by Surname:} \hfill % (Section \ref{sec:LastFirst})\\ % \FUse \cmd{\RevComma}\cmd{\LWash}\dotfill % \ForgetThis\RevComma\LWash\\ % \LUse \cmd{\RevComma}\cmd{\LWash}\dotfill \RevComma\LWash % \end{Block} % % \newpage % % \begin{Block} % \textsc{Particles:} \hfill (Section~\ref{sec:NameParticles})\\ % \LUse \cmd{\Soto}\dotfill \ForgetThis\Soto\\ % \LUse \cmd{\Soto}\dotfill \Soto\\ % \LUse \cmd{\CapThis}\cmd{\Soto}\dotfill \CapThis\Soto % \end{Block} % % \begin{Block} % \textsc{Royal and Medieval:} \hfill % (Section~\ref{sec:NameMedieval})\\ % \LUse \cmd{\Aeth}\dotfill \ForgetThis\Aeth\footnote % {Regarding the margin note that shows name control sequences, % with \texttt{pdflatex} and \texttt{latex}, in % \texttt{\ShowPattern{Æthelred, II}} the glyphs \texttt{ÃĘ} % correspond to \cmd{\IeC\{}\cmd{\AE\}}.}\\ % \LUse \cmd{\Aeth}\dotfill \Aeth\\ % \LUse |\LAeth[II, ``Unræd'']|\dotfill % \LAeth[II, ``Unræd'']\\[1ex] % \LUse \cmd{\Eriugena[Scotus Eriugena]}\dotfill % \ForgetThis\Eriugena[Scotus Eriugena]\\ % \LUse \cmd{\LEriugena}\dotfill \LEriugena\\ % \LUse \cmd{\Eriugena}\dotfill \Eriugena % \end{Block} % % \begin{Block} % \textsc{Ancient Mononym} \hfill (trivial case)\\ % \LUse \cmd{\Aris}\dotfill \ForgetThis\Aris\\ % \LUse \cmd{\Aris}\dotfill \Aris % \end{Block} % % \subsubsection[\protect\textit{Alternate} Field] % {\protect\meta{Alternate} Name Field Tips} % \label{sec:ArgIV} % % \vspace{3ex} % \BothInfo{\ShowPattern[Clive Staples]{Lewis}\break % \ShowPattern{Miyazaki, Hayao}} % {\ShowIdxPageref*[Clive Staples]{Lewis}\break % \ShowIdxPageref*{Miyazaki, Hayao}} % \vspace{-3ex} % Two shorthands above use \meta{arg4}, the final field in each row of the \texttt{nameauth} environment. These are \cmd{\CSL} and \cmd{\MSens}. They correspond to similar name shorthands \cmd{\Lewis} and \cmd{\Miyazaki}, which leave \meta{arg4} empty. Here is how they are related: % % \begin{itemize} % \item They share identical name control patterns % (Section~\ref{sec:NamePatterns}).\\[1ex] % \ForgetName{Miyazaki, Hayao}\ForgetName[Clive Staples]{Lewis} % First: \cmd{\MSens} \MSens; subsequent: \cmd{\Miyazaki} \Miyazaki.\\ % First: \cmd{\CSL\ \ } \CSL;\hspace{2.2em} % subsequent: \cmd{\Lewis \ \ \ } \Lewis. % \item Usually, one leaves \meta{arg4} empty and adds alternate names in % brackets as needed: \cmd{\LLewis[C.S.]} \LLewis[C.S.] % \item By using \meta{arg4}, one trades less work for more ambiguity: Can % one add an alternate name or not? To answer that, one should keep track % of all name shorthands that use \meta{arg4}. % \item Failure to keep track of such macros creates output like % \cmd{\LCSL[Jack]} \LCSL[Jack] and \cmd{\LMSens[Sensei]} \LMSens[Sensei]. % The reason why these macro versions produce undesired output is because % \meta{arg4} permanently populates \meta{Alternate}. % \item Bear also in mind that \meta{arg4} can be used for the obsolete % syntax, as mentioned previously, but we do not cover that here. % \end{itemize} % % \begin{Quote}{\ForgetThis\Miyazaki\break % \hbox{}\hfill Proposal for \textit{Princess Mononoke}} % We depict hatred, but it is to depict that there are more important things. We depict a curse, to depict the joy of liberation. % \end{Quote} % % \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}) will update \cmd{\NameauthPattern} (used in Section~\ref{sec:DataTemp}) and can have final optional arguments (Section~\ref{sec:FinalOptargs}). Those with additional starred forms are shown followed by a \texttt{*}. Optional prefix macros are shown in the next subsection. % % \begin{center}\medstretch % \begin{tabular}{lrcll}\toprule % Optional Prefix & Macro & & Arguments & \\ % \rowcolor{nagrey}\llap{Naming\qquad}\meta{prefix macros} & % \cmd{\Name} & \texttt{*} & \meta{name args} & \\ % \rowcolor{nagrey}\llap{\ul{\ \ \ \ \ \ \ \ \ \ \ \ }\qquad}^^A % \meta{prefix macros} & % \cmd{\FName} & \texttt{*} & \meta{name args} & \\ % \llap{Page ref\qquad}\cmd{\SeeAlso} & \cmd{\IndexName} & & % \meta{name args} & \\ % \llap{\ul{Only cross-ref}\qquad}\cmd{\SeeAlso} & \cmd{\IndexRef} & & % \meta{xref args} & \meta{target}\\ % \rowcolor{nagrey}\llap{Prevent page ref\qquad} & \cmd{\ExcludeName} & & % \meta{name args} & \\ % \rowcolor{nagrey}\llap{\ul{Enable page ref}\qquad} & \cmd{\IncludeName} & % \texttt{*} & \meta{name args} & \\ % \llap{Sort index\qquad} & \cmd{\PretagName} & & \meta{name args} & % \meta{sort key} \\ % \llap{Append idx tag\qquad} & \cmd{\TagName} & & \meta{name args} & % \meta{tag} \\ % \llap{\ul{Delete idx tag}\qquad}& \cmd{\UntagName} & & \meta{name args} & \\ % \rowcolor{nagrey}\llap{Make data tag\qquad} & \cmd{\NameAddInfo} & & % \meta{name args} & \meta{tag} \\ % \rowcolor{nagrey}\llap{Show data tag\qquad} & \cmd{\NameQueryInfo} & & % \meta{name args} & \\ % \rowcolor{nagrey}\llap{\ul{Delete data tag}\qquad} & \cmd{\NameClearInfo} & & % \meta{name args} & \\ % \llap{Delete name cs\qquad} & \cmd{\ForgetName} & & \meta{name args} & \\ % \llap{\ul{Create name cs}\qquad} & \cmd{\SubvertName} & & % \meta{name args} & \\ % \rowcolor{nagrey}\llap{Name cs tests\qquad} & \cmd{\IfMainName} & & % \meta{name args} & \marg{y}\marg{n}\\ % \rowcolor{nagrey}& \cmd{\IfFrontName} & & \meta{name args} & % \marg{y}\marg{n}\\ % \rowcolor{nagrey}\llap{\ul{\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ }\qquad} & % \cmd{\IfAKA} & & \meta{name args} & \marg{y}\marg{n}\marg{x}\\ % \llap{Debugging\qquad} & \cmd{\ShowPattern} & & \meta{name args} & \\ % & \cmd{\ShowIdxPageref} & \texttt{*} & \meta{name args} & \\ % & \cmd{\ShowNameInfo} & & \meta{name args} & \\ % & \cmd{\ShowNameState} & & \meta{name args} &\\\bottomrule % \end{tabular} % \end{center} % % The \meta{xref args} are the same as \meta{name args} for a cross-reference to a \meta{target} (Section~\ref{sec:IndexRef}). Not shown are \cmd{\AKA}, \cmd{\AKA*}, \cmd{\PName}, and \cmd{\PName*} (Section~\ref{sec:AKA}). Here we do not describe in detail what the arguments mean. % % \begin{Quote}{\ForgetThis\MLK[Dr. Martin Luther]\break % \hbox{}\hfill \textit{Stride Towards Freedom} (1958)} % \IndexName{Jesus, Christ}^^A % We believe firmly in the revelation of God in Jesus Christ. I can see no conflict between our devotion to Jesus Christ and our present action. In fact, I can see a necessary relationship. If one is truly devoted to the religion of Jesus he will seek to rid the earth of social evils. The gospel is social as well as personal. % \end{Quote} % % \newpage % % \subsubsection{Prefix Macros} % % Similar to the package options (Section~\ref{sec:PkgOptions}), many prefix macros alter the values of the Boolean flags that reflect the state of names and name processing. The naming and indexing macros reset the Boolean flags after they are invoked. % % \begin{center}\small\medstretch % \begin{tabular}{rp{0.72\textwidth}}\toprule % & \bfseries Capitalization in the Text\\ % \cmd{\CapName} & % Cap entire \meta{SNN} in body text. Overrides \cmd{\CapThis}.\\ % \cmd{\CapThis} & % Capitalize first letter of all name components in body text.\\ % \cmd{\AccentCapThis} & Fallback when Unicode detection cannot be done.\\ % \rowcolor{nagrey} & \bfseries Reversing in the Text\\ % \rowcolor{nagrey}\cmd{\RevName} & % Reverse order of any name in body text. Overrides \cmd{\RevComma}\\ % \rowcolor{nagrey}\cmd{\RevComma} & % Reverse only Western names to \meta{SNN}, \meta{FNN}.\\ % & \bfseries Commas in the Text\\ % \cmd{\ShowComma} & Add comma between \meta{SNN} and \meta{Affix}.\\ % \cmd{\NoComma} & % No comma between \meta{SNN} and \meta{Affix}. Overrides \cmd{\ShowComma}.\\ % \rowcolor{nagrey} & \bfseries Name Breaks in the Text\\ % \rowcolor{nagrey}\cmd{\DropAffix} & % Drop affix only for a long Western name reference.\\ % \rowcolor{nagrey}\cmd{\KeepAffix} & % Insert non-breaking space (NBSP) between \meta{SNN}, \meta{FNN/Affix}.\\ % \rowcolor{nagrey}\cmd{\KeepName} & % Insert NBSP between all name elements. Overrides \cmd{\KeepAffix}.\\ % & \bfseries Forcing Name Forms via Control Sequence\\ % \cmd{\ForgetThis} & Force a first-time name use. Negates \cmd{\SubvertThis}.\\ % \cmd{\SubvertThis} & Force a subsequent use.\\ % \rowcolor{nagrey} & \bfseries Forcing Name Forms via Boolean Flags\\ % \rowcolor{nagrey}\cmd{\ForceName} & Force first-use formatting hooks.\\ % \rowcolor{nagrey}\cmd{\ForceFN} & % Force printing of \meta{Affix}/\meta{Alternate} in non-Western % short forms.\\ % & \bfseries Indexing\\ % \cmd{\SeeAlso} & % For \cmd{\IndexName}, \cmd{\AKA}, and \cmd{\PName}; make a % \textit{see also} xref.\\ % \cmd{\SkipIndex} & For naming macros; do not create an index entry.\\ % \cmd{\JustIndex} & % For naming macros; index only (once); negated by \cmd{\AKA}, % \cmd{\PName}.\\\bottomrule % \end{tabular} % \end{center} % % \noindent Some important notes include: % % \begin{itemize} % \item Prefix macros stack:\\[0.4ex] % |\CapThis\RevName\SkipIndex\Name[bar]{foo}|\dotfill % \CapThis\RevName\SkipIndex\Name[bar]{foo} % \item The Boolean flags governed by the prefix macros are reverted after % the appropriate macros produce output in the text (or index) unless the % output of the naming macros is suppressed. % \item Except for \cmd{\SeeAlso}, use prefix macros only before a naming % macro that is designed to print output in the text. % \item Use \cmd{\SeeAlso} only with \cmd{\IndexRef}, \cmd{\AKA}, and % \cmd{\PName}. Otherwise it will be ignored and reset by \cmd{\IndexName} % and the naming macros. % \item Using \cmd{\JustIndex} will cause name form modifiers to be reset. % \end{itemize} % % \noindent Macros that do not take name arguments include: % % \begin{itemize} % \item Prefix macros (Section~\ref{sec:PrefixMacs}). % \item Helper macros (Section~\ref{sec:Helpers}). % \item Most internal package macros. % \item Formatting macros. % \end{itemize} % % \subsection{Names and Complexity} % \label{sec:Complexity} % % The \textsf{nameauth} package allows levels of complexity when representing names. Already, we have seen this example above: % % \begin{Block}\small % |\LEliz[I ``Gloriana'']|\dotfill \LEliz[I ``Gloriana''] % \end{Block} % % We can so the same thing with different macros, but they do not offer more features, only more complexity: % % \begin{Block} % |\LEliz\ ``\ForceFN\SEliz[Gloriana]''|\dotfill % \LEliz\ ``\ForceFN\SEliz[Gloriana]'' % \end{Block} % % In Section~\ref{sec:NameAncient} we will learn how to add a one-time increase in complexity by using ``name info tags'' with modified formatting hooks to do the following that \emph{does} offer potentially more features: % % \begingroup % \NameAddInfo{Elizabeth, I}{ ``Gloriana''} % \renewcommand*\NamesFormat[1] % {^^A % \color{blue}\sffamily #1^^A % \ifcsname\NameauthPattern!DB\endcsname % \expandafter\csname\NameauthPattern!DB\endcsname^^A % \fi % } % \renewcommand*\MainNameHook{\sffamily} % \begin{Block}\small % \FUse |\ForgetThis\LEliz|\dotfill \ForgetThis\LEliz\\ % \LUse |\LEliz|\dotfill \LEliz\\ % \LUse |\Eliz|\dotfill \Eliz % \end{Block} % \endgroup % % There can be needless complexity, and there can be helpful complexity. For example, if \LaTeX\ is used as the back end for an \texttt{xslt} transform, it can be useful to have well-defined macro states that map systematically to the input without needing human intervention. % % Section~\ref{sec:NameParticles} shows a similar trade-off between a simple example and a formatted example using the name of poet \Name[e.e.]{cummings}. Moving on to Section~\ref{sec:Romani}, complexity increases, yet the state of any given name remains well-defined. % % \begin{InfoBox}[Avoid the Rabbit Hole] % \begin{itemize}[leftmargin=1em] % \item There are trade-offs between ease of use and automation. % \item Examples that are easy to implement often are not easily automated. % \item Examples that are more complex lend themselves to automation using % package features as building blocks. % \item In \textsf{nameauth}, names are nouns that have state and modifiers. % \item In \textsf{nameauth}, names are verbs capable of changing their % environment. % \end{itemize} % % The example in Section~\ref{sec:QuickExample} was quite simple, yet there are many use cases that need not be much more complex than that. Thus, one must discern useful complexity from useless complexity.\medskip % % Unless one has a use case that demands automation and complexity, hopefully illustrated by examples in this manual, one should tend toward simplicity and the macros seen in the earlier pages of this manual. % \end{InfoBox} % % \ReturnLink % % \newpage % % \section{Package Options} % \label{sec:PkgOptions} % \negmedskip % % \begin{SyntaxBox} % \cmd{\usepackage[}\meta{\(option_1\)}\texttt{,}\meta{\(option_2\)}^^A % \texttt{,}\dots\texttt{,}\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. % % \subsection{Name Grammar and Syntax} % % \subsubsection[Affix Commas]{Show/Hide Affix Commas} % % \bgroup\begin{tabular}{p{0.22\textwidth}p{0.6\textwidth}} % \quad\bfseries\texttt{nocomma} & % \bfseries Modern standards: Suppress commas between surnames and % affixes.\smallskip\\ % \leavevmode\color{nared}\quad\texttt{comma} & % \leavevmode\color{nared}Older standards: Retain commas between surnames % and affixes.\medskip\\ % \end{tabular}\egroup % % \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}. % % \subsubsection[Surname in Caps]{Capitalize Entire Surnames} % % \bgroup\begin{tabular}{p{0.22\textwidth}p{0.6\textwidth}} % \quad\bfseries\texttt{normalcaps} & % \bfseries Do not perform any special capitalization.\smallskip\\ % \leavevmode\color{nared}\quad\texttt{allcaps} & % \leavevmode\color{nared}Capitalize entire surnames, e.g., romanized % Eastern names, throughout the document.\medskip\\ % \end{tabular}\egroup % % \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} % % \bgroup\begin{tabular}{p{0.22\textwidth}p{0.6\textwidth}} % \quad\bfseries\texttt{notreversed} & % \bfseries Print names in the order specified by \cmd{\Name} % and the other macros.\smallskip\\ % \leavevmode\color{nared}\quad\texttt{allreversed} & % \leavevmode\color{nared}Print all name forms in ``smart'' reverse order; % Western as non-Western, and vice versa.\smallskip\\ % \leavevmode\color{nared}\quad\texttt{allrevcomma} & % \leavevmode\color{nared}Print all names in ``Surname, Forenames'' order, % meant for Western names.\medskip\\ % \end{tabular}\egroup % % \noindent 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. % % \begin{Quote}{\Name[Mark]{Twain}, \textit{The Innocents Abroad} (1869)} % Virtue never has been as respectable as money. % \end{Quote} % % \subsection{Indexing} % % \subsubsection{Toggle Indexing} % % \bgroup\begin{tabular}{p{0.22\textwidth}p{0.6\textwidth}} % \quad\bfseries\texttt{index} & % \bfseries Create index entries in place with names.\smallskip\\ % \leavevmode\color{nared}\quad\texttt{noindex} & % \leavevmode\color{nared}Suppress indexing of names.\medskip\\ % \end{tabular}\egroup % %^^A Starting with the text below, any errors will force one to remove all %^^A auxiliary files before compiling this file. There is no clear indication %^^A of why that happens to be the case. % % \noindent % 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}. % % \subsubsection{Toggle Index Sorting} % % \bgroup\begin{tabular}{p{0.22\textwidth}p{0.6\textwidth}} % \quad\bfseries\texttt{pretag} & % \bfseries Create sort keys used with \texttt{makeindex}.\smallskip\\ % \leavevmode\color{nared}\quad\texttt{nopretag} & % \leavevmode\color{nared}Do not create sort keys.\medskip\\ % \end{tabular}\egroup % % \noindent The default allows \cmd{\PretagName} to create sort keys used with \texttt{makeindex}. The \texttt{nopretag} option disables the sorting mechanism and causes \cmd{\PretagName} only to emit warnings, as may be needed with, e.g., \texttt{xindy}. See Section~\ref{sec:IndexSort}. % % \subsubsection{Verbose Warnings} % % \bgroup\begin{tabular}{p{0.22\textwidth}p{0.6\textwidth}} % \leavevmode\color{nared}\quad\texttt{verbose} & % \leavevmode\color{nared}Show more diagnostic warnings.\medskip\\ % \end{tabular}\egroup % % \noindent The default suppresses all but the most essential package warnings. Increasing the warnings may help to debug index page entries, cross-references, and exclusions. Section~\ref{sec:GeneralIndex} shows macros that can enable and disable verbose warnings. % % \addtocontents{toc}{\protect\goodbreak} % % \subsection[Formatting]{Formatting and Name Control Sequences} % % 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. % % \subsubsection[Choose System]{Choose Formatting System} % % \bgroup\begin{tabular}{p{0.22\textwidth}p{0.6\textwidth}} % \bfseries\quad\texttt{mainmatter} & % \bfseries Start with ``main-matter names'' and formatting hooks \normalfont % (Section~\ref{sec:PostProcess}).\smallskip\\ % \leavevmode\color{nared}\quad\texttt{frontmatter} & % \leavevmode\color{nared}Start with ``front-matter names'' and hooks until % \cmd{\NamesActive} starts the main system.\smallskip\\ % \leavevmode\color{nared}\quad\texttt{alwaysformat} & % \leavevmode\color{nared}Use only respective ``first use'' formatting % hooks.\smallskip\\ % \leavevmode\color{nared}\quad\texttt{formatAKA} & % \leavevmode\color{nared}Format the first use of a name with \cmd{\AKA} like % the first use of a name with \cmd{\Name}.\medskip\\ % \end{tabular}\egroup % % \noindent 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}. % % 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{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} % % \bgroup\begin{tabular}{p{0.22\textwidth}p{0.6\textwidth}} % \quad\bfseries\texttt{noformat} & % \bfseries Pass the displayed name through the formatting hooks % unchanged.\smallskip\\ % \leavevmode\color{nared}\quad\texttt{smallcaps} & % \leavevmode\color{nared}First use of a main-matter name in small % caps.\smallskip\\ % \leavevmode\color{nared}\quad\texttt{italic} & % \leavevmode\color{nared}First use of a main-matter name in % italic.\smallskip\\ % \leavevmode\color{nared}\quad\texttt{boldface} & % \leavevmode\color{nared}First use of a main-matter name in % boldface.\medskip\\ % \end{tabular}\egroup % % \noindent The options above are ``quick'' definitions of \cmd{\NamesFormat} based on English typography. The default is no formatting.\footnote{For the old default, use the \texttt{smallcaps} option. User feedback dictated this change.} % See also Robert Bringhurst, \textit{The Elements of Typographic Style}, version 3.2 (Point Roberts, Washington: Hartley \& Marks, 2008), 53--60. All references [\hypertarget{Bringhurst}{Bringhurst}] refer to this edition. % % The following macros govern the way that names in the text appear. Two naming systems are used in \textsf{nameauth}, one for main-matter text (default) and one for front-matter text.\footnote{\cmd{\NamesFormat} was once the only formatting hook. The other macros developed from there. Regrettably, this package originated in a time when the present author was ignorant of several cultural and technical aspects of handling names. The ``learn as you go'' approach contributed to a fair bit of ``cargo-cult'' programming.} % These hooks do not affect the index. Changes to the formatting hooks normally apply within the scope where they occur: % % \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. % % \subsection{Alternate Formatting} % % \bgroup\begin{tabular}{p{0.22\textwidth}p{0.6\textwidth}} % \leavevmode\color{nared}\quad\texttt{altformat} & % \leavevmode\color{nared}Make available the alternate formatting framework % from the start of the document. Activate alternate formatting by % default.\medskip\\ % \end{tabular}\egroup % % \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. % % \subsection[Scope of Decisions]{Change Scope of Name Decision Macros} % % \bgroup\begin{tabular}{p{0.22\textwidth}p{0.6\textwidth}} % \leavevmode\color{nared}\quad\texttt{globaltest} & % \leavevmode\color{nared}Do not put name decision paths in a local % scope.\medskip\\ % \end{tabular}\egroup % % \noindent The default puts the decision paths of \cmd{\IfMainName}, etc., into groups with local scope (Section~\ref{sec:NameTests}). This option removes that scoping. % % \subsection{Version Compatibility} % % \emph{Using these options will increase the chance of undocumented behavior.} They are included only for the sake of backward compatibility with older versions of \textsf{nameauth}. The goal is to preserve the behavior of this package at the point it was used in a document, especially if local fixes were employed.\medskip % % \bgroup\begin{tabular}{p{0.22\textwidth}p{0.6\textwidth}} % \leavevmode\color{nared}\quad\texttt{oldAKA} & % \leavevmode\color{nared}Force \cmd{\AKA*} to act like it did before version % 3.0, instead of like \cmd{\FName}.\smallskip\\ % \leavevmode\color{nared}\quad\texttt{oldreset} & % \leavevmode\color{nared}Reset per-use name flags locally; let % \cmd{\ForgetThis} and \cmd{\SubvertThis} pass through \cmd{\AKA} (pre-v3.3). % Let \cmd{\SeeAlso} pass through \cmd{\IndexName} and other macros. % Keep \cmd{\IndexName} and \cmd{\IndexRef} from resetting \cmd{\SkipIndex} % (pre-version 3.5).\smallskip\\ % \leavevmode\color{nared}\quad\texttt{oldpass} & % \leavevmode\color{nared}When \cmd{\Justindex} is called, allow long or short % Boolean flags to pass through, as they did before version 3.3.\smallskip\\ % \leavevmode\color{nared}\quad\texttt{oldtoks} & % \leavevmode\color{nared}Token registers holding the arguments of the % last-used name are set locally, as before version 3.5.\smallskip\\ % \leavevmode\color{nared}\quad\texttt{oldsee} & % \leavevmode\color{nared}Allow lax handling of \textit{see} references that % are extant names, as before version 3.5.\medskip\\ % \end{tabular}\egroup % % \noindent Previously, local scope for Boolean flags related to the prefix macros and long/short name forms could produce unexpected results. Those results, in turn, could mask problems caused by some flags not being reset by \cmd{\AKA}, \cmd{\AKA*}, and \cmd{\JustIndex}. The result was undocumented behavior. % % \begin{itemize} % \item Version 2.6 approximate compatibility\\ % \texttt{oldAKA,oldpass,oldreset,oldtoks,oldsee} % \item Versions 3.0--3.2 compatibility\\ % \texttt{oldpass,oldreset,oldtoks,oldsee} % \item Versions 3.3--3.4 compatibility\\ % \texttt{oldreset,oldtoks,oldsee} % \end{itemize} % \negbigskip % % \ReturnLink % % \begin{Quote}{\Name[John F.]{Kennedy}, Inaugural Address (1961)} % The world is very different now. For man holds in his mortal hands the power to abolish all forms of human poverty and all forms of human life. And yet the same revolutionary beliefs for which our forebears fought are still at issue around the globe\,---\,the belief that the rights of man come not from the generosity of the state, but from the hand of God. % \end{Quote} % % \section{Feature Priority} % \label{sec:Priorities} % % \begin{center}\small\medstretch % \begin{tabular}{llll}\toprule % \bfseries Indexing & \bfseries Capitalization & % \bfseries Reversing & \bfseries Name Forms, \\ % & & & \bfseries Commas, Breaks\\\midrule % \ttfamily\bfseries index & \ttfamily\bfseries normalcaps & % \ttfamily\bfseries notreversed & \cmd{\ForgetThis} \\ % \ttfamily\bfseries noindex & \ttfamily\bfseries allcaps & % \ttfamily\bfseries allreversed & \cmd{\DropAffix} \\ % \cmd{\IndexActive} & \cmd{\AllCapsInactive} & \cmd{\ReverseActive} \\ % \cmd{\IndexInactive} & \cmd{\AllCapsActive} & \cmd{\ReverseInactive} \\ % \rowcolor{black!6!white} % \cmd{\JustIndex} & \cmd{\CapName} & \cmd{\RevName} & \cmd{\SubvertThis}\\ % \rowcolor{black!6!white} & & & \cmd{\ForceName}\\ % \rowcolor{black!6!white} & & & \cmd{\NoComma}\\ % \rowcolor{black!12!white} % \cmd{\SkipIndex} & \cmd{\AccentCapThis} & % \ttfamily\bfseries allrevcomma & \cmd{\KeepName}\\ % \rowcolor{black!12!white} & & \cmd{\RevCommaActive} & \cmd{\ForceFN}\\ % \rowcolor{black!12!white} & & \cmd{\RevCommaInactive} & \cmd{\ShowComma}\\ % \rowcolor{black!18!white} % \cmd{\SeeAlso} & \cmd{\CapThis} & \cmd{\RevComma} & % \cmd{\KeepAffix}\\\bottomrule % \end{tabular} % \end{center} % % Above we see the relative priority of package options and macros. Package options are shown in boldface. % % \begin{itemize} % \item Lighter-colored rows show higher priority. Darker-colored rows show % lower priority. Higher-priority options and macros can override % lower-priority ones. % \item All options and macros in a given row have equal priority and are % able to countermand each other within a given column. % \item Priority affects macros and options within columns. % \cmd{\IndexInactive} overrides \cmd{\JustIndex}, which overrides % \cmd{\SkipIndex}. If \cmd{\IndexInactive} is invoked, \cmd{\JustIndex} % will have no effect. % \item Section~\ref{sec:IdxPrefix} shows the interaction between % \cmd{\SkipIndex} and \cmd{\JustIndex} to be complex and non-intuitive. % It explains why it is best to use only \cmd{\SkipIndex} or % \cmd{\JustIndex} before a naming macro. % \item Priority usually does not affect macros and options in different % columns. Yet the macros themselves can have specific effects that change % the expected behavior of macros in other columns. % % For example, \cmd{\JustIndex} prevents a name from being displayed in % the text. Even if \cmd{\IndexInactive} overrides \cmd{\JustIndex} with % respect to indexing, it has no effect on the fact that the name will not % be printed. % % Also, \cmd{\JustIndex} resets the effects of \cmd{\ForgetThis} and % \cmd{\SubvertThis} because those prefix macros should precede only naming % macros that produce output in the text. % % Due to this behavior, even though \cmd{\JustIndex} does not ``override'' % the caps and reversing macros and options, nevertheless it simply prevents % any other macros related to the display of a name from taking effect. % \end{itemize} % % \ReturnLink % % \newpage % % \section{Naming Macros} % % 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. % % \subsection{\texttt{\textbackslash Name} and \texttt{\textbackslash Name*}} % \label{sec:Naming} % % \DescribeMacro{\Name} % \cmd{\Name} displays and indexes names. It always prints the \meta{SNN} argument. \cmd{\Name} prints the full name at the first occurrence, % \DescribeMacro{\Name*} % then usually just the \meta{SNN} argument thereafter. \cmd{\Name*} always prints the full name: % % \begin{SyntaxBox} % \cmd{\Name\ }\oarg{FNN}\marg{SNN|,| Affix}\oarg{Alternate}\\ % \cmd{\Name*}\oarg{FNN}\marg{SNN|,| Affix}\oarg{Alternate} % \end{SyntaxBox} % % In the body text, not the index, the \meta{Alternate} argument replaces either \meta{FNN} or, if \meta{FNN} is absent, \meta{Affix}. If both \meta{FNN} and \meta{Affix} are absent when \meta{Alternate} is present, then the obsolete syntax is used (Section~\ref{sec:Obsolete}, not shown below). % % \begin{quote}\small % \begin{Verbatim} % \begin{nameauth} % \< Einstein & Albert & Einstein & > % \< Carter & J.E. & Carter, Jr. & > % \< Confucius & & Confucius & > % \< Miyazaki & & Miyazaki, Hayao & > % \< Eliz & & Elizabeth, I & > % \end{nameauth} % \end{Verbatim} % \end{quote} % % \ForgetName[Albert]{Einstein}\ForgetName[J.E.]{Carter, Jr.} % \begin{center}\small % \vspace{3ex} % \BothInfo{\ShowPattern[Albert]{Einstein}\break % \ShowPattern[J.E.]{Carter, Jr.}\break % \ShowPattern{Confucius}\break % \ShowPattern{Miyazaki, Hayao}\break % \ShowPattern{Elizabeth, I}} % {\ShowIdxPageref*[Albert]{Einstein}\break % \ShowIdxPageref*[J.E.]{Carter, Jr.}\break % \ShowIdxPageref*{Confucius}\break % \ShowIdxPageref*{Miyazaki, Hayao}\break % \ShowIdxPageref*{Elizabeth, I}} % \vspace{-3ex}\medstretch % \begin{tabular}{ll}\toprule % |\Name [Albert]{Einstein}| or |\Einstein| & \Name [Albert]{Einstein}\\ % |\Name*[Albert]{Einstein}| or |\LEinstein| & \LEinstein\\ % |\Name [Albert]{Einstein}| or |\Einstein| & \Einstein\\ % \rowcolor{nagrey}|\Name [J.E.]{Carter, Jr.}| or |\Carter| & % \Name [J.E.]{Carter, Jr.}\\ % \rowcolor{nagrey}|\Name*[J.E.]{Carter, Jr.}[James Earl]| & % \LCarter[James Earl]\\ % \rowcolor{nagrey} or |\LCarter[James Earl]|& \\ % \rowcolor{nagrey}|\Name [J.E.]{Carter, Jr.}| or |\Carter| & \Carter\\ % |\Name {Confucius}|, |\Confucius| & \Confucius\\ % |\Name {Confucius}|, |\Confucius| & \Confucius\\ % \rowcolor{nagrey}|\Name {Miyazaki, Hayao}| or |\Miyazaki| & % \ForgetThis\Name {Miyazaki, Hayao}\\ % \rowcolor{nagrey}|\Name*{Miyazaki, Hayao}[Sensei]| & % \Name*{Miyazaki, Hayao}[Sensei]\\ % \rowcolor{nagrey}|\Name {Miyazaki, Hayao}| or |\Miyazaki| & % \Name {Miyazaki, Hayao}\\ % |\Name {Elizabeth, I}| or |\Eliz| & \ForgetThis\Eliz\\ % |\Name*{Elizabeth, I}| or |\LEliz| & \Name*{Elizabeth, I}\\ % |\Name {Elizabeth, I}| or |\Eliz| & \Name {Elizabeth, I}\\\bottomrule % \end{tabular} % \end{center} % % When using the quick interface, the preferred way to get alternate names is |``\LCarter[James Earl]''| ``\LCarter[James Earl]'' and |``\LMiyazaki[Sensei]''| ``\LMiyazaki[Sensei]''. The alternate forename is not shown in subsequent short name references e.g., |``\Carter[James Earl]''| is just ``\Carter[James Earl]''. Thus, one must use either long-name references or forename references to see the alternate names. % % \subsection{Forenames: \texttt{\textbackslash FName}} % \label{sec:FName} % % \DescribeMacro{\FName} % \cmd{\FName} and its synonym \cmd{\FName*} print personal names only in subsequent name uses. % \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. % % Unlike all other starred forms of macros in \textsf{nameauth}, these macros are synonyms because one might edit either \cmd{\Name} or \cmd{\Name*} by adding an \texttt{F} to create a short name instead of the usual forms. This was implemented before the quick interface. % % \begin{SyntaxBox} % \cmd{\FName\ }\oarg{FNN}\marg{SNN|,| Affix}\oarg{Alternate}\\ % \cmd{\FName*}\oarg{FNN}\marg{SNN|,| Affix}\oarg{Alternate} % \end{SyntaxBox} % % These forename reference macros will permit all name types, but the normal behavior prints forenames only with Western names. With non-Western names only \meta{SNN} is printed. This is designed to prevent Western writers from causing undue offense in Eastern contexts. It also prevents the display of nonsense names in the context of royal names.\medskip % % \DescribeMacro{\ForceFN} % 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}\small % \vspace{3ex} % \PatInfo{\ShowPattern[Albert]{Einstein}\break % \ShowPattern[J.E.]{Carter, Jr.}\break % \ShowPattern{Confucius}\break % \ShowPattern{Miyazaki, Hayao}\break % \ShowPattern{Elizabeth, I}} % \vspace{-3ex}\medstretch % \begin{tabular}{ll}\toprule % |\FName[Albert]{Einstein}| or |\SEinstein| & \SEinstein\\ % \rowcolor{nagrey}|\FName[J.E.]{Carter, Jr.}[James Earl]| & % \SCarter[James Earl]\\ % \rowcolor{nagrey}or |\SCarter[James Earl]| & \\ % |\FName{Confucius}| or |\SConfucius |& \FName{Confucius}\\ % \rowcolor{nagrey}|\FName{Miyazaki, Hayao}| or |\SMiyazaki| & % \FName{Miyazaki, Hayao}\\ % |\ForceFN\FName{Miyazaki, Hayao}| & \ForceFN\FName{Miyazaki, Hayao}\\ % or |\ForceFN\SMiyazaki| & \\ % \rowcolor{nagrey}|\ForceFN\FName{Miyazaki, Hayao}[Sensei]| & % \ForceFN\FName{Miyazaki, Hayao}[Sensei]\\ % \rowcolor{nagrey}or |\ForceFN\SMiyazaki[Sensei]| & \\ % |\FName{Elizabeth, I}| or |\SEliz| & \SEliz\\ % \rowcolor{nagrey}|\ForceFN\SEliz[Good Queen Bess]| & % \ForceFN\SEliz[Good Queen Bess]\\\bottomrule % \end{tabular} % \end{center} % % The \meta{Alternate} argument replaces forenames in the text, which strongly shapes the use of \cmd{\FName}. We already have covered the use of \meta{Arg4} of the \texttt{nameauth} environment in Section~\ref{sec:ArgIV}. Please refer to that material when using \meta{Alternate}, especially with the quick interface. % % \begin{Quote}{\Name[Dwight D.]{Eisenhower}\break % \hbox{}\hfill Associated Press luncheon (24 April 1950)} % Censorship, in my opinion, is a stupid and shallow way of approaching the solution to any problem. Though sometimes necessary, as witness a professional and technical secret that may have a bearing upon the welfare and very safety of this country, we should be very careful in the way we apply it, because in censorship always lurks the very great danger of working to the disadvantage of the American nation. % \end{Quote} % % \subsection{Technical Details} % \label{sec:TechDetails} % % \subsubsection{Spaces in Arguments} % % To get consistent index entries (where spaces are significant), all \textsf{nameauth} macros that take name arguments trim extra spaces around each name argument. We shade those areas below, after which we provide an example with suppressed formatting:\medskip % % \begin{tcolorbox}[colframe=naslate, % valign=center,top=0mm,bottom=0mm]\centering % \begin{tabular}{c@{\qquad}c@{\qquad}c@{\qquad}c@{\qquad}c} % \tcbox[equal height group=F,colback=white,tikznode, % left=1mm,right=1mm,valign=center] % {\bfseries\meta{\color{nared}FNN}} & % \tcbox[equal height group=F,colback=white,tikznode, % left=1mm,right=1mm,valign=center] % {\bfseries\meta{SNN}} & % \tcbox[equal height group=F,colback=white,tikznode, % left=1mm,right=1mm,valign=center] % {\bfseries\ttfamily\strut\color{nared},} & % \tcbox[equal height group=F,colback=white,tikznode, % left=1mm,right=1mm,valign=center] % {\bfseries\meta{\color{nared}Affix}} & % \tcbox[equal height group=F,colback=white,tikznode, % left=1mm,right=1mm,valign=center] % {\bfseries\meta{\color{nared}Alternate}} % \end{tabular} % \end{tcolorbox}\smallskip % % \begin{VerbatimOut}{\jobname.tmp} % No spaces: % \fbox{\strut\Name*[Martin Luther]{King,Jr.}} % \fbox{\strut\Name [Martin Luther]{King,Jr.}} % \fbox{\strut\FName[Martin Luther]{King,Jr.}} % % Spaces:\hspace{1.4em} % \fbox{\strut\Name*[ Martin Luther ]{ King , Jr. }} % \fbox{\strut\Name [ Martin Luther ]{ King , Jr. }} % \fbox{\strut\FName[ Martin Luther ]{ King , Jr. }} % \end{VerbatimOut} % % \begin{quote}\small % \vspace{3.5ex} % \BothInfo{\ShowPattern[Martin Luther]{King, Jr.}\break % \ShowPattern[ Martin Luther ]{ King , Jr. }} % {\ShowIdxPageref*[Martin Luther]{King, Jr.}\break % \ShowIdxPageref*[ Martin Luther ]{ King , Jr. }} % \vspace{-3.5ex} % % \VerbatimInput[gobble=0]{\jobname.tmp} % \renewcommand*\NamesFormat{} % \renewcommand*\MainNameHook{} % % \input{\jobname.tmp} % \end{quote} % % Now we resume this manual's formatting to help show that the names below are different, even though they appear similar. % % Non-breaking spaces, explicit spaces, thin spaces, and macros that expand to spaces \emph{are not trimmed} by either \LaTeX\ or \textsf{nameauth}. They produce different name patterns and, if used in macro arguments, must be used consistently (Section~\ref{sec:NameParticles}). Below we suppress indexing and show three different names: % % \begin{center}\IndexInactive\small\medstretch % \begin{tabular}{lcl}\toprule % Macro\,/\,Char: & Appearance: & Name Pattern:\\ % \rowcolor{nagrey}|\Name{foo~bar}| & \Name{foo~bar} & % \ttfamily\ShowPattern{foo~bar} \\ % |\Name{foo\ bar}| & \Name{foo\ bar} & \ttfamily\ShowPattern{foo\ bar} \\ % \rowcolor{nagrey}|\Name{foo\space bar}| & % \Name{foo\space bar} & \ttfamily\ShowPattern{foo\space bar} \\\bottomrule % \end{tabular}\IndexActive % \end{center} % % \subsubsection{Full Stop Detection} % % Western names tend to use full stops in these cases: % % \begin{itemize} % \item After the initial letter abbreviation of forenames. % \item After affixes: ``Jr''. (junior), ``Sr''. (senior), ``d.\,Ä.'' % (\textit{der Ältere}), ``d.\,J.'' (\textit{der Jüngere}) etc. % \item In some contexts, after degrees like ``M.D.'' (\textit{Medicinae % Doctor}), J.D. (\textit{Juris Doctor}), Ph.D. % (\textit{Philosophiae Doctor}), etc. % \end{itemize} % % The naming macros and some others (Section~\ref{sec:AKA}) check if the printed name ends with a full stop. They also check the lookahead token for a full stop and gobble the lookahead. In the following example we ``forget'' the existence of a name pattern via \cmd{\ForgetName} below (Section~\ref{sec:NameControl}) to simulate not having seen it before: % % \begin{VerbatimOut}{\jobname.tmp} % Full stop on lookahead gobbled\dotfill % \Name[Martin Luther]{King, Jr.}[Rev. Dr. Martin Luther]. % % Full stop remains (affix auto-drops)\dotfill % Rev. Dr. \Name[Martin Luther]{King, Jr.}. % % Full stop gobbled (force long name form)\dotfill % \Name*[Martin Luther]{King, Jr.}. % % Full stop remains (force affix to drop)\dotfill % \DropAffix\Name*[Martin Luther]{King, Jr.}. % % Full stop gobbled (alternate using initials)\dotfill % \FName[Martin Luther]{King, Jr.}[M.L.]. % \end{VerbatimOut} % % \begin{quote}\small % \VerbatimInput[gobble=0]{\jobname.tmp} % \ForgetName[Martin Luther]{King, Jr.} % % \input{\jobname.tmp} % \end{quote} % % \subsubsection{Braces and Spaces} % % We disable indexing for the examples below so that we do not generate unwanted entries. Take care when using curly braces \texttt{\bfseries\{\,\}} in naming macro arguments. They will produce different names, as the formatting shows: % % \IndexInactive % \begin{center}\small\medstretch % \begin{tabular}{llll}\toprule % & Macro: & Result: & Name Pattern:\\ % \rowcolor{nagrey} 1 & |\Name[one]{two}| & \Name[one]{two} & % \ttfamily\ShowPattern[one]{two} \\ % 2 & |\Name[{one}]{{t}w{o}}| & \Name[{one}]{{t}w{o}} & % \ttfamily\ShowPattern[{one}]{{t}w{o}} \\ % \rowcolor{nagrey} 3 & |\Name{one, two}| & \Name{one, two} & % \ttfamily\ShowPattern{one, two} \\ % 4 & |\Name{{one}, two}| & \Name{{one}, two} & % \ttfamily\ShowPattern{{one}, two} \\ % \rowcolor{nagrey} 5 & |\Name{{one, two}}| & \Name{{one, two}} & % \ttfamily\ShowPattern{{one, two}} \\\bottomrule % \end{tabular} % \end{center} % % Names one and two are Western; names three and four are non-Western. All names have different patterns and different index entries, even if they look similar in the text (Sections~\ref{sec:NamePatterns}, \ref{sec:IndexSort}). Name~5 is very tricky. The parts of |\Name{{one, two}}| are: \ShowNameInfo{{one, two}}. Compare that with the parts of |\Name{one, two}|: \ShowNameInfo{one, two}. This can affect alternate formatting (Section~\ref{sec:AltFormat}). % \IndexActive % % Curly braces can change the lookahead token and defeat punctuation detection (as well as create a unique name). Using spaces between a name and a full stop can have a similar effect: % % \begin{VerbatimOut}{\jobname.tmp} % Full stop remains (not in group)\dotfill % Dr. {\Name*[Martin Luther]{King, Jr.}}. % % Full stop is gobbled (in containing group)\dotfill % Dr. {\Name*[Martin Luther]{King, Jr.}.} % % Full stop remains (affix in own group)\dotfill % Dr. \SkipIndex\Name*[Martin Luther]{King, {Jr.}}. % % Full stop is gobbled (outside affix group)\dotfill % Dr. \SkipIndex\Name*[Martin Luther]{King, {Jr}.}. % % Full stop remains (intervening space)\dotfill % Dr. \Name*[Martin Luther]{King, Jr.} . % % Full stop gobbled (follows macro cs)\dotfill \LPatton . % % Full stop remains (follows optarg)\dotfill \LPatton[George] . % \end{VerbatimOut} % % \begin{quote}\small % \VerbatimInput[gobble=0]{\jobname.tmp} % % \input{\jobname.tmp} % \end{quote} % % \subsubsection{Formatting Initials} % % This is a thorny topic. Some publishers are dead-set on having a space between initials. Many designers find that practice to be inelegant at best. [\hyperlink{Bringhurst}{Bringhurst}] wisely advises one to omit spaces between initials. % % Yet fighting with one's editor will be a lost cause unless one already has sufficient \textit{gravitas}. If a style guide requires spaces, try thin spaces. The quick interface reduces the likelihood that one will produce names that look the same, but whose arguments and name patterns differ. Below we use no formatting: % % \begin{quote}^^A Normal size to show the spacing better. % \begin{minipage}[c]{0.45\textwidth} % \begin{Verbatim} % \PretagName[E.\,B.]{White}% % {White, Elwyn} % \begin{nameauth} % \< White & E.\,B. & White & > % \end{nameauth} % \end{Verbatim} % \end{minipage} % \begin{minipage}[c]{0.35\textwidth} % \renewcommand*\NamesFormat{}\renewcommand*\MainNameHook{} % \def\sep{\vrule width0.5pt\kern-0.5pt}% % \begin{tabular}{@{}ll@{}} % \cmd{\LWhite} & \hspace{0.48pt}\LWhite\\ % & \sep\hphantom{E.}\sep\,\sep\hphantom{B.}\sep\hphantom{\ }^^A % \sep\hphantom{White}\sep\\\hline % & \sep\hphantom{E.}\sep\ \sep\hphantom{B.}\sep\ \sep\hphantom{White}\sep\\ % Normal text:\hfill & E. B. White\\ % \end{tabular} % \end{minipage} % \end{quote} % % One might notice that we used \cmd{\PretagName} to sort this name by something other than its initials: ``White, Elwyn''. sorting only by initials (and with embedded macros like a thin space) will produce unexpected orderings of entries (Section~\ref{sec:IndexInitials}). % % \ReturnLink % % \begin{Quote}{\Name[Leonard]{Bernstein}\break % \hbox{}\hfill ``What Makes Opera Grand?'', \textit{Vogue} % (December 1958)} % \textls[-15]{Any great work of art \dots revives and readapts time and space, and the measure of its success is the extent to which it makes you an inhabitant of that world\,---\,the extent to which it invites you in and lets you breathe its strange, special air.} % \end{Quote} % % \newpage % % \section{Language Topics} % \label{sec:Lang} % % Here we cover technical issues related to various languages and cultures. % % \subsection[Active Characters]{Caveats with Active Characters} % % Active characters affect name patterns and index sorting, depending on the \LaTeX\ engine being used. We pay more attention to \cmd{\PretagName} (Section~\ref{sec:IndexSort}; cf.~\ref{sec:Unicode}):\footnote{Regarding the margin note that shows name control sequences, with \texttt{pdflatex} and \texttt{latex}, in \texttt{\ShowPattern{Æthelred, II}} the glyphs \texttt{ÃĘ} correspond to \cmd{\IeC\{}\cmd{\AE\}}. Likewise in \texttt{\ShowPattern{Boëthius}} the glyphs \texttt{Ãń} correspond to \cmd{\IeC\{}\cmd{\"e\}}.} % % \begin{enumerate}\small % \vspace{4ex} % \PatInfo{\ShowPattern{Æthelred, II} \textrm{(1)}\break % \ShowPattern{\AE thelred, II} \textrm{(2)}\break % \ShowPattern{Bo\"ethius} \textrm{(3)}\break % \ShowPattern{Boëthius} \textrm{(4)}\break % \ShowPattern{Bo{\"e}thius} \textrm{(5)}} % \vspace{-4ex} % \item |\Name*{Æthelred, II}|\dotfill \Name*{Æthelred, II} % \item[] We have seen this name earlier, as the formatting shows. % \item[] We sort this with |\PretagName{Æthelred, II}{Aethelred, 2}| % \item |\SkipIndex\Name{\AE thelred, II}|\dotfill % \SkipIndex\Name{\AE thelred, II} % \item[] This name is new, as the formatting shows us. It looks like the % name above, but its control pattern differs by the macro \cmd{\AE}. % \item[] We get a different index entry, regardless of how we sort it. % \item |\Name{Bo\"ethius}|\dotfill \Name{Bo\"ethius} % \item[] This new name uses |\"e| to display a lowercase e with a diaeresis. % \item[] We sort it with |\PretagName{Bo\"ethius}{Boethius}|. % \item |\SkipIndex\Name{Boëthius}|\dotfill \SkipIndex\Name{Boëthius} % \item[] This name differs by the character ë. % \item |\SkipIndex\Name{Bo{\"e}thius}|\dotfill \SkipIndex\Name{Bo{\"e}thius} % \item[] Yet another different name differs by grouping tokens. These are % significant with regard to name patterns and indexing. % \end{enumerate} % % \subsection{Hyphenation} % \negmedskip % \NameArgWarning % % In modern English, names can be hyphenated to reflect their cultural origins. With \textsf{nameauth}, one can handle such names by using optional hyphens, the \textsf{babel} package, or the \textsf{polyglossia} package. Below we offer an example using a mancro that does not expand differently throughout the document.\footnote{Using macros in name arguments does introduce potential problems that we discuss in Sections~\ref{sec:NameParticles}, \ref{sec:AltFormat}, and elsewhere, showing how to prevent errors.} % \IndexName[John]{\noexpand\de{Strietelmeier}} % % \begin{quote}\small % \begin{Verbatim} % \newcommand\de[1]{\foreignlanguage{ngerman}{#1}} % % or polyglossia: \newcommand\de[1]{\textgerman{#1}} % % \begin{nameauth} % \< Striet & John & \noexpand\de{Strietelmeier} & > % \end{nameauth} % % \PretagName[John]{\noexpand\de{Strietelmeier}} % {Strietelmeier, John} % \end{Verbatim} % \end{quote} % % \begin{itemize} % \item \textbf{Example 1: Default Hyphenation} % % \item[] Here\PatInfo{\ShowPattern[John]{Strietelmeier}} we use the default hyphenation. Using \cmd{\textls} from \textsf{microtype} we get the name to break badly. We omit this version from the index. One might think that the name were pronounced ``stre-et-el-mei-er''.\smallskip % % \item[] \textls[5]{In English, some names come from other cultures. Names % like \SkipIndex\Name[John]{Strietelmeier} % \cmd{\SkipIndex}\cmd{\Name[John]\{Strietelmeier\}} can break badly.}\medskip % % \item \textbf{Example 2: Discretionary Hyphens} % % Here\PatInfo{\ShowPattern[John]{Strie\-tel\-meier}} we create a different name from the one above. One must use the discretionary hyphens consistently in the macro arguments. We also omit this version from the index. We see that it breaks properly.\smallskip % % \item[] \textls[9]{In English, some names come from other cultures. Names % like \SkipIndex\Name[John]{Strie\-tel\-meier}} % \textls[10]{\cmd{\SkipIndex}^^A % \cmd{\Name[John]\{Strie\textbackslash-tel\textbackslash-meier\}} % break badly in some cases.}\medskip % % \item \textbf{Example 3: Language Packages} % % Finally\PatInfo{\textls[-5]{\ShowPattern[John]{\de{Strietelmeier}}}} we use the general solution shown above with \textsf{babel} or \textsf{polyglossia}. Since the leading element of \meta{SNN} is a macro, using \cmd{\CapThis} would halt \LaTeX\ with errors unless we used alternate formatting that does not segment the argument (Section~\ref{sec:AltFormat}):\smallskip % % \item[] \textls[7]{In English, some names come from other cultures. Names % like} \Striet, \textls[20]{\cmd{\Striet} or % \cmd{\Name[John]\{}\cmd{\noexpand}\cmd{\de\{Strietelmeier\}\}}}\break % break badly in some cases. % \end{itemize} % % \subsection{Affixes Need Commas} % \label{sec:Affix} % % \negmedskip\begin{InfoBox} % Regarding an \meta{SNN, Affix} pair, the key to avoiding error is to apply macros to \meta{SNN} and \meta{Affix} as if they were independent arguments.\end{InfoBox} % % A comma is not a required name element unless used in an \meta{SNN, Affix} pair. When thus used it delimits a Western surname from its affix, an Eastern family name from a personal name, and an ancient name from an affix. % % When a comma appears in a required name argument, each member of the \meta{SNN, Affix} pair is treated as a separate argument. Thus, we say that the comma segments the macro argument. % % If one encapsulates an \meta{SNN, Affix} pair within a macro, \LaTeX\ may halt with errors. We have seen above that spaces around the comma are ignored. % % \begin{center}\small % \vspace{1ex} % \BothInfo{\ShowPattern[Oskar]{Hammerstein, II}\break % \ShowPattern{Louis, XIV}\break % \ShowPattern{Sun, Yat-sen}} % {\ShowIdxPageref*[Oskar]{Hammerstein, II}\break % \ShowIdxPageref*{Louis, XIV}\break % \ShowIdxPageref*{Sun, Yat-sen}} % \vspace{-1ex}\medstretch % \ForgetName{Sun, Yat-sen} % \begin{tabular}{ll}\toprule % |\Name[Oskar]{Hammerstein, II}| & \KeepAffix\Name[Oskar]{Hammerstein, II}\\ % |\Name[Oskar]{Hammerstein, II}| & \Name[Oskar]{Hammerstein, II}\\ % \rowcolor{nagrey}|\Name{Louis, XIV}| & \KeepAffix\Name{Louis, XIV}\\ % \rowcolor{nagrey}|\Name{Louis, XIV}| & \Name{Louis, XIV}\\ % |\Name{Sun, Yat-sen}| & \KeepAffix\Name{Sun, Yat-sen}\\ % |\Name{Sun, Yat-sen}| & \Name{Sun, Yat-sen}\\\bottomrule % \end{tabular} % \end{center} % % \newpage % % Western names with affixes must use \meta{SNN,Affix},^^A % \PatInfo{\ShowPattern[Oskar]{Hammerstein}[II]} never the obsolete syntax, which is meant for non-Western names and is discouraged. We get \SkipIndex\Name[Oskar]{Hammerstein}[II] and a bad index entry from, e.g., \cmd{\SkipIndex}\cmd{\Name[Oskar]\{Hammerstein\}[II]}.\medskip % % \DescribeMacro{\KeepAffix} % If the name displayed in the text shows both \meta{SNN} and \meta{Affix}, then \cmd{\KeepAffix} turns the space \emph{between} \meta{SNN} and \meta{Affix} into a non-breaking space. \cmd{\KeepAffix}\cmd{\Name\{Louis, XIV\}} will not break between \Name{Louis, XIV} and \ForceFN\FName{Louis, XIV}. All name types that use \meta{Affix} are supported. \medskip % % \DescribeMacro{\KeepName} % In longer name forms, \cmd{\KeepName} turns spaces \emph{between} all visible name elements into non-breaking spaces. % % \begin{itemize}\small % \item |\Name[Sandra Day]{O'Connor}| \Name[Sandra Day]{O'Connor} has two % points where the name can break: after \FName[Sandra Day]{O'Connor}[Sandra] % and after \FName[Sandra Day]{O'Connor}[Day]. % \item |\KeepName\Name*[Sandra Day]{O'Connor}| % \KeepName\Name*[Sandra Day]{O'Connor} % has one point where the name can break: after % \FName[Sandra Day]{O'Connor}[Sandra]. % \end{itemize} % % This macro does not alter spaces \emph{within} name elements composed of multiple names, like French or German forenames and Spanish surnames. \cmd{\KeepName} works with all name types.\medskip % % \DescribeMacro{\DropAffix} % If \cmd{\DropAffix} precedes only a Western name, it will suppress the affix after the surname in a first or long reference. We get ``\DropAffix\Name*[Oskar]{Hammerstein, II}'' From |\DropAffix\Name*[Oskar]{Hammerstein, II}|. % % With non-Western names, the \meta{Affix} in the \meta{SNN, Affix} pair drops automatically in the text for subsequent uses, making \cmd{\DropAffix} redundant. We see that above in the case of \Name*{Louis,XIV}, who becomes \Name{Louis,XIV}.\medskip % % \DescribeMacro{\ShowComma} % 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. % % \begin{center}\small\medstretch % \begin{tabular}{ll}\toprule % |\ShowComma\LPatton| & \ShowComma\LPatton\\ % \rowcolor{nagrey}|\NoComma\LPatton| & \NoComma\LPatton\\\bottomrule % \end{tabular} % \end{center} % % 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}). % % \subsection[Eastern Names, Name Caps] % {Eastern Names and Family Names in All Caps} % \label{sec:Eastern} % % Proper Eastern names, included with ancient and medieval forms in the broader group of non-Western names, are encoded using comma-delimited syntax (compare the obsolete syntax in Section~\ref{sec:Obsolete}). They have non-Western index entries: \meta{SNN} \meta{Affix} (no comma between name elements). The current syntax permits alternate names; the obsolete does not. % % \begin{SyntaxBox} % \cmd{\Name}\marg{SNN, Affix}\oarg{Alternate} % \end{SyntaxBox} % % Even in some academic texts, one sees non-Western names encoded with Western forms.\footnote{\textls[-5]{Jaroslav Pelikan, \textit{The Christian Tradition}, 5 vols. (Chicago: Chicago UP, 1971–1989); Immanuel Geiss, \textit{Personen: Die biographische Dimension der Weltgeschichte}, Geschichte Griffbereit vol. 2 (Munich: Wissen Media Verlag, 2002).} At this time, \href{https://www.nndb.com/}{\bfseries NNDB} sorts \Name{Kim, Jong Un} under U, not K.} % The \textsf{nameauth} package seeks to remedy that issue, which has more to do with outsourcing indexes to non-expert providers than with scholars. For example, the macro |\Name*{Sun, Yat-sen}| \Name*{Sun, Yat-sen} ensures correct forms in the text and the index. We get cross-cultural sensitivity and scholarly accuracy.\medskip % % \DescribeMacro{\AllCapsActive} % Certain contexts call for one's entire family name to be capitalized. This differs % \DescribeMacro{\AllCapsInactive} % from the way in which initial letter capitalization is handled (Section~\ref{sec:NameParticles}). In addition to the \texttt{allcaps} package option % \DescribeMacro{\CapName} % (Section~\ref{sec:PkgOptions}), \cmd{\AllCapsActive} and \cmd{\AllCapsInactive} work for blocks of text. All have priority over \cmd{\CapName}, which works once per name. These capitalize \meta{SNN} in the body text only. They also work with \cmd{\AKA} and friends. For capitalization in both the text and index (beyond doing it manually) see Sections~\ref{sec:AltFormat} and~\ref{sec:AdvCustomize}.\medskip % % 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. % % \vspace{2ex} % \BothInfo{\ShowPattern[Hideyo]{Noguchi}\break % \ShowPattern{Miyazaki, Hayao}} % {\ShowIdxPageref*[Hideyo]{Noguchi}\break % \ShowIdxPageref*{Miyazaki, Hayao}} % \vspace{-2ex} % \begin{center}\small\medstretch % \begin{tabular}{ll}\toprule % |\LNoguchi| & \LNoguchi \\ % \rowcolor{nagrey}|\CapName\LNoguchi}| & \CapName\LNoguchi\\ % |\LMiyazaki| & \LMiyazaki \\ % \rowcolor{nagrey}|\CapName\LMiyazaki| & \CapName\LMiyazaki\\\bottomrule % \end{tabular} % \end{center} % % \subsection{Reversed Names} % \label{sec:RevNames} % % Sometimes the name form in the text differs from its expected index entry, as we saw with Hungarian names. In another example, a publisher might expect Western-style name forms in the index. In \textsf{nameauth} we can use the reversing option and macros to change the form in the text while not disturbing the index entries.\medskip % % \DescribeMacro{\ReverseActive} % In addition to the \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. Reversing only affects long name forms. In this manual, reversed Western forms are shown with a dagger (\dag).\medskip % % Both\Info{\cmd{\global}} \cmd{\ReverseActive} and \cmd{\ReverseInactive} can be used either as a pair or singly within an explicitly local scope. Use \cmd{\global} to force a global effect. % % \vspace{4ex} % \BothInfo{\ShowPattern[Hideyo]{Noguchi}\break \ShowPattern{Miyazaki, Hayao}} % {\ShowIdxPageref*[Hideyo]{Noguchi}\break \ShowIdxPageref*{Miyazaki, Hayao}} % \vspace{-4ex} % \begin{center}\small\medstretch % \begin{tabular}{rll}\toprule % & unchanged & |\RevName|\\ % \rowcolor{nagrey}|\LNoguchi| & \LNoguchi & \RevName\LNoguchi\dag\\ % \rowcolor{nagrey}|\LNoguchi[Doctor]| & \LNoguchi[Doctor] & % \raise0.5ex\hbox to 5em{\hfil\rule{3em}{0.6pt}} \\ % \rowcolor{nagrey}|\LNoguchi[Sensei]| & % \raise0.5ex\hbox to 5em{\hfil\rule{3em}{0.6pt}} & % \RevName\LNoguchi[Sensei]\dag\\ % \rowcolor{nagrey}|\Noguchi| & \Noguchi & \RevName\Noguchi\dag\\ % \rowcolor{nagrey}|\SNoguchi| & \SNoguchi & \RevName\SNoguchi\dag\\ % |\LMiyazaki| & \LMiyazaki & \RevName\LMiyazaki\\ % |\LMiyazaki[Mr.]| & \raise0.5ex\hbox to 5em{\hfil\rule{3em}{0.6pt}} & % \RevName\LMiyazaki[Mr.]\\ % |\LMiyazaki[Sensei]| & \LMiyazaki[Sensei] & % \raise0.5ex\hbox to 5em{\hfil\rule{3em}{0.6pt}}\\ % |\Miyazaki| & \Miyazaki & \RevName\Miyazaki\\ % |\SMiyazaki| & \SMiyazaki & \RevName\SMiyazaki\\ % |\ForceFN\SMiyazaki| & \ForceFN\SMiyazaki & % \ForceFN\RevName\SMiyazaki\\\bottomrule % \end{tabular} % \end{center} % % \begin{SyntaxBox}[Reversing Western Names] % \cmd{\RevName}\cmd{\Name}\oarg{FNN}\marg{SNN}\oarg{Alternate} % \end{SyntaxBox} % % As we see from the syntax, one should avoid using \meta{Affix} with such names. For example, |\RevName\LPatton\dag| produces ``\RevName\LPatton\dag''. The name looks wrong unless one uses either \cmd{\RevComma} or \cmd{\DropAffix}. % % The index entry of this name form looks like \meta{SNN}, \meta{FNN} (including the comma). This is a Western index entry. This form is used also for Hungarian names, e.g.: |\RevName\Name[Frenec]{Molnár}\dag| \ForgetThis\RevName\Name[Frenec]{Molnár}\dag, \RevName\Name[Frenec]{Molnár}\dag. % % \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 is and remains a non-Western index entry. % % \begin{InfoBox}[Reversing Ancient Names] % The syntax would be the same for reversing Eastern names, but this % usually results in producing nonsense names. We do not recommend it. % \end{InfoBox} % % \subsection[Listing by Surname]{Listing Western names by Surname} % \label{sec:LastFirst} % % \DescribeMacro{\ReverseCommaActive} % To make lists of ``last comma first'' names, in addition to the \texttt{allrevcomma} option (Section~\ref{sec:PkgOptions}), % \DescribeMacro{\ReverseCommaInactive} % the macros \cmd{\ReverseCommaActive} and \cmd{\ReverseCommaInactive} function the same way with blocks of text.\DescribeMacro{\RevComma} They both have priority over \cmd{\RevComma}. These all affect only long Western name forms. The first two are broad toggles, while the third is used once per name.\medskip % % Both\Info{\cmd{\global}} \cmd{\ReverseCommaActive} and \cmd{\ReverseCommaInactive} can be used either as a pair or singly within a local scope. Use \cmd{\global} to force a global effect. % % \begin{center}\small\medstretch % \begin{tabular}{lll}\toprule % \Name*[Oskar]{Hammerstein, II} & % \RevComma\Name*[Oskar]{Hammerstein, II} & change\\ % \LNoguchi & \RevComma\LNoguchi & change\\ % \rowcolor{nagrey}\LAeth & \RevComma\LAeth & no change\\ % \rowcolor{nagrey}\Name*{Sun, Yat-sen} & % \RevComma\Name*{Sun, Yat-sen} & no change\\\bottomrule % \end{tabular} % \end{center}^^A % \vspace{-12ex} % \PatInfo{\ShowPattern[Oskar]{Hammerstein, II}\break % \ShowPattern[Hideyo]{Noguchi}\break % \ShowPattern{Æthelred,II}\break % \ShowPattern{Sun, Yat-sen}} % \vspace{12ex} % % \begin{Quote}{\small\Name[W.H.]{Auden}\break % \hbox{}\hfill \textit{Paris Review} interview (1972) p. 206} % I don't think the mystical experience can be verbalized. When the ego disappears, so does power over language. % \end{Quote} % % \newpage % % \subsection{Particles in Names} % \label{sec:NameParticles} % % Particles are small words attached to names, grouped either with forenames or surnames, that refer often to places of origin or noble houses. Some particles have been carried into modern names through various means. % % \subsubsection{Standard Rules} % % Modern standards tend to treat particles in the following way: % % \begin{itemize} % \item English use of \textit{de}, \textit{de\ la}, \textit{d'}, % \textit{von}, \textit{van}, and \textit{ten} often keeps them with the % surname with varied capitalization. % \item \textit{Le}, \textit{La}, and \textit{L'} always are capitalized % unless preceded by \textit{de}.\footnote{According to % [\hyperlink{Mulvany}{Mulvany}, 152–82] and the \textit{Chicago Manual % of Style}.} % \item Modern Romance languages keep particles with the surname. % \item German and medieval Romance languages keep particles with forenames. % \item Welsh, Irish, and Scots names often merge particles with surnames: % FitzRoy or Fitzroy; O'Leary; McDonald, MacLeish. % \end{itemize} % % \begin{center}\small % \vspace{2ex} % \BothInfo{\ShowPattern[Martin]{Van Buren}\break % \ShowPattern[Hernando]{de~Soto}\break % \ShowPattern[J.W. von]{Goethe}} % {\ShowIdxPageref*[Martin]{Van Buren}\break % \ShowIdxPageref*[Hernando]{de~Soto}\break % \ShowIdxPageref*[J.W. von]{Goethe}} % \vspace{-2ex}\medstretch % \begin{tabular}{rll}\toprule % \bfseries Macro & \bfseries Body Text & \bfseries Index \\ % \rowcolor{nagrey}\cmd{\ForgetThis}\cmd{\VBuren} & % \ForgetThis\VBuren & \ShowIdxPageref*[Martin]{Van Buren}\\ % \cmd{\VBuren} & \VBuren & \ShowIdxPageref*[Martin]{Van Buren}\\ % \rowcolor{nagrey}\cmd{\ForgetThis}\cmd{\Soto} & % \ForgetThis\Soto & \ShowIdxPageref*[Hernando]{de~Soto}\\ % \cmd{\CapThis}\cmd{\Soto} & \CapThis\Soto & % \ShowIdxPageref*[Hernando]{de~Soto}\\ % \rowcolor{nagrey}\cmd{\ForgetThis}\cmd{\JWG} & \ForgetThis\JWG & % \ShowIdxPageref*[J.W. von]{Goethe}\\ % \cmd{\JWG} & \JWG & \ShowIdxPageref*[J.W. von]{Goethe}\\\bottomrule % \end{tabular} % \end{center} % % \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. % % \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 Particles} % % \DescribeMacro{\CapThis} % In English and modern Romance languages, names like \LSoto\ have their particles in the \meta{SNN} argument: \Soto. When the particle appears at the beginning of a sentence, one must capitalize it, e.g.,: ``\CapThis\Soto\ |\CapThis\Soto\| was a famous Spanish explorer in North America.'' % % \begin{itemize} % \item With \texttt{latex} and \texttt{pdflatex}, using \cmd{\CapThis} % should work with all of the Unicode characters available in the T1 % encoding. For a broader set of characters, consider using \texttt{xelatex} % and \texttt{lualatex}. % \item Section~\ref{sec:NonstandardCaps} applies \cmd{\CapThis} % to nonstandard names and indexing. % \item Sections~\ref{sec:AltFormat} and~\ref{sec:Unicode} explain % potential problems of \cmd{\CapThis}. That is a trade-off % for using a natural language approach. % \item \cmd{\CapName} overrides the \meta{SNN} created by \cmd{\CapThis}. % It is unlikely that the two would be used in the same context. % \end{itemize} % % \DescribeMacro{\AccentCapThis} % 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 % % \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\}}.} % % \begin{quote}\small % \begin{Verbatim} % \PretagName{Thomas, à~Kempis}{Thomas Akempis} % medieval % \PretagName[Thomas]{à~Kempis}{Akempis, Thomas} % Western % % % We do not index an alternate medieval form % \ExcludeName{Thomas, \`a~Kempis} % % % If we did use the alternate form, we would sort it as % \PretagName{Thomas, \`a~Kempis}{Thomas Akempis} % % \begin{nameauth} % \< KempMed & & Thomas, à~Kempis & > % medieval % \< KempW & Thomas & à~Kempis & > % Western % \end{nameauth} % % % Create xref before using the Western name. % \IndexRef[Thomas]{à~Kempis}{Thomas à~Kempis} % \end{Verbatim} % \ExcludeName{Thomas,\`a~Kempis} % \IndexRef[Thomas]{à~Kempis}{Thomas à~Kempis} % \end{quote} % % \begin{itemize} % \item Medieval form: \cmd{\KempMed} % \BothInfo{\ShowPattern{Thomas, à~Kempis}\hfill \textrm{(1--4, 7)}\break % \ShowPattern{Thomas,\`a~Kempis}\hfill \textrm{(5--6)}\break % \ShowPattern[Thomas]{à~Kempis}\hfill \textrm{(8--10)}} % {\ShowIdxPageref*{Thomas, à~Kempis}\hfill (1--4, 7)\break % \ShowIdxPageref*{Thomas,\`a~Kempis}\hfill (5--6)\break % \ShowIdxPageref*[Thomas]{à~Kempis}\hfill (8--10)} % \begin{enumerate} % \item In the text, we see \KempMed\ and \KempMed. The added name % ``\ForceFN\SKempMed'' |\ForceFN\SKempMed| is a place name, not a % surname. It is Latin for \textit{von Kempen}. % \item \KempMed\ is indexed as ``\ShowIdxPageref*{Thomas, à~Kempis}''. % \item \CapThis\ForceFN\SKempMed\ |\CapThis\ForceFN\SKempMed| % can start a sentence. % \item We use \cmd{\PretagName} (Section~\ref{sec:IndexSort}) to sort the % name under \texttt{Thomas}, followed by \texttt{Akempis}, not % \texttt{A kempis} (cf. 10 below). % \end{enumerate} % \item Alternate medieval form: |\Name{Thomas,\`a~Kempis}| % \begin{enumerate}\addtocounter{enumi}{4} % \item \Name{Thomas,\`a~Kempis} is a different name. % \item We used \cmd{\ExcludeName} (Section~\ref{sec:IdxFine}) % before using the alternate form to keep it from generating an extra % index entry. % \item We index the canonical form here with % \JustIndex\KempMed|\JustIndex\KempMed|. % \end{enumerate} % % \newpage % % \item Western form: \cmd{\KempW} % \begin{enumerate}\addtocounter{enumi}{7} % \item \KempW\ is a Western name form with the index entry: % ``\ShowIdxPageref*[Thomas]{à~Kempis}''. % \item \CapThis\KempW\ appears via |\CapThis\KempW|. % \item We first created a cross-reference from the Western form to the % medieval form to prevent spurious page entries % (Section~\ref{sec:IndexRef}). % \item[] We index the canonical form again: % \JustIndex\KempMed|\JustIndex\KempMed|. % \item[\dbend] \cmd{\PretagName[Thomas]\{à~Kempis\}\{a Kempis, Thomas\}} % puts \KempMed\ before \texttt{aardvark} in the index. We remove the extra % spaces to get the proper sorting between \texttt{ajar} and % \texttt{alkaline}: % |\PretagName[Thomas]{à~Kempis}{Akempis, Thomas}| % \end{enumerate} % \end{itemize} % \negmedskip % % \ReturnLink % % \addtocontents{toc}{\protect\goodbreak} % \section{Debugging} % \label{sec:Debugging} % % As we move forward in this manual, many concepts will mesh together in complex ways. Indexing is the first topic to do that. Name patterns govern those interactions, and debugging macros illustrate what is going on. First, we explain what the debugging macros are trying to communicate. Next, we describe the macros. % % Previously, we have seen simple name patterns displayed in the margin, which look like the examples shown below: % % \begin{quote}\small\ttfamily % \begin{tabular}{@{\qquad}l} % \ShowPattern[George]{Washington}\\ % \ShowPattern{Miyazaki, Hayao} % \end{tabular} % \end{quote} % % Now we switch to full name patterns, which indicate the ``system'' or data set to which a control sequence representing a name belongs. Name patterns usually expand to empty, except for exclusions.\footnote{To fit the information in the margin, we display them by taking the output of \cmd{\ShowPattern} and manually adding the system to correspond to the package internals.} % The patterns look like this: % % \begin{quote}\small % \ttfamily\begin{tabular}{@{\qquad}l@{\quad \% }l} % \ShowPattern[George]{Washington}!MN & name, main matter\\ % \ShowPattern{Miyazaki, Hayao}!NF & name, front matter\\ % \ShowPattern[Jay]{Rockefeller}!PN & index cross-reference\\ % \ShowPattern[W.E.B.]{Du~Bois}!PRE & index sort tag\\ % \ShowPattern{Gregory, I}!TAG & index data tag\\ % \ShowPattern[Schuyler]{Colfax}!DB & name data tag\\ % \end{tabular} % \end{quote} % % No longer will we show index entries in the margin because they shall become too large and complex to fit there. We will show index entries in the body text. % % \subsection[Name Patterns]{Name Pattern Overview} % \label{sec:NamePatterns} % % The next table shows how macro arguments generate name patterns. The \meta{Alternate} argument only affects patterns when using the obsolete syntax (Section~\ref{sec:Obsolete}). The patterns govern names in both the text and the index. The colon at the beginning of each pattern was added to prevent any collisions with extant macros: % % \begin{center}\small\medstretch % \begin{tabular}{lll}\toprule % Macro Arguments & Patterns & Name Type\\ % \rowcolor{nagrey}\oarg{FNN}\marg{SNN} & % :\meta{FNN}!\meta{SNN} & Western\\ % \oarg{FNN}\marg{SNN}\oarg{Alt} & % :\meta{FNN}!\meta{SNN} & Western\\ % \rowcolor{nagrey}\oarg{FNN}\marg{SNN, Affix} & % :\meta{FNN}!\meta{SNN},\meta{Affix} & Western\\ % \oarg{FNN}\marg{SNN, Affix}\oarg{Alt} & % :\meta{FNN}!\meta{SNN},\meta{Affix} & Western\\ % \rowcolor{nagrey}\hphantom{\oarg{FNN}}\marg{SNN, Affix} & % :\meta{SNN},\meta{Affix} & non-Western\\ % \hphantom{\oarg{FNN}}\marg{SNN, Affix}\oarg{Alt} & % :\meta{SNN},\meta{Affix} & non-Western\\ % \rowcolor{nagrey}\hphantom{\oarg{FNN}}\marg{SNN}\oarg{Alt} & % :\meta{SNN},\meta{Alt} & old syntax\\ % \hphantom{\oarg{FNN}}\marg{SNN} & % :\meta{SNN} & non-Western\\\bottomrule % \end{tabular} % \end{center}\medskip % % \DescribeMacro{\NameauthPattern} % Every time a macro that takes name arguments is called (Section~\ref{sec:NameArgMacros}), the internal name category logic will \cmd{\let} the current name pattern to \cmd{\NameauthPattern}, making it available to formatting hooks (cf. Section~\ref{sec:DataTagHooks}). % % The name category logic is provided by \cmd{\@nameauth@Choice}, which determines the type of name (Western or non-Western) by its arguments. Various \textsf{nameauth} macros append the appropriate ``system'' or name data set indicator to the pattern. We use this concept starting here, but mostly in Section~\ref{sec:AdvancedFormat}. % % First we show name patterns generated from name elements and the type of name. Reversed Western names are marked by a dagger (\dag); names that use the obsolete syntax are marked by a double dagger (\ddag). We use two versions of each name, plus variations in formatting, to show that the patterns depend on the arguments, not the appearance of the name. Note also that the obsolete non-Western syntax and the current one still share the same patterns. % % \begin{center}\small\medstretch % \begin{tabular}{rll}\toprule % Macro & Body Text & \cmd{\ShowPattern}\\ % \rowcolor{nagrey}\cmd{\Harnack[Adolf von]} & \Harnack[Adolf von] & % \texttt{\ShowPattern[Adolf]{Harnack}}\\ % \rowcolor{nagrey}\cmd{\LHarnack} & \LHarnack & % \texttt{\ShowPattern[Adolf]{Harnack}}\\ % \cmd{\ForgetThis}\cmd{\Patton} & \ForgetThis\Patton & % \texttt{\ShowPattern[George S.]{Patton, Jr.}}\\ % \cmd{\DropAffix}\cmd{\LPatton} & \DropAffix\LPatton & % \texttt{\ShowPattern[George S.]{Patton, Jr.}}\\ % \rowcolor{nagrey}\cmd{\ForgetThis}\cmd{\Noguchi} & \ForgetThis\Noguchi & % \texttt{\ShowPattern[Hideyo]{Noguchi}}\\ % \rowcolor{nagrey}\cmd{\RevName}\cmd{\LNoguchi}\cmd{\dag} & % \RevName\LNoguchi\dag & \texttt{\ShowPattern[Hideyo]{Noguchi}}\\ % \cmd{\ForgetThis}\cmd{\Yamt} & \ForgetThis\Yamt & % \texttt{\ShowPattern{Yamamoto,Isoroku}}\\ % \cmd{\RevName}\cmd{\LYamt} & \RevName\LYamt & % \texttt{\ShowPattern{Yamamoto,Isoroku}}\\ % \rowcolor{nagrey}\cmd{\Name\{Henry,VIII\}} & \Name{Henry,VIII} & % \texttt{\ShowPattern{Henry,VIII}}\\ % \rowcolor{nagrey}\cmd{\Name*\{Henry\}[VIII]}\cmd{\ddag} & % \Name*{Henry}[VIII]\ddag & \texttt{\ShowPattern{Henry,VIII}}\\ % \cmd{\Dem[I Soter]} & \Dem[I Soter] & \texttt{\ShowPattern{Demetrius,I}}\\ % \cmd{\LDem} & \LDem & \texttt{\ShowPattern{Demetrius,I}}\\ % \rowcolor{nagrey}\cmd{\ForgetThis}\cmd{\Aris} & \ForgetThis\Aris & % \texttt{\ShowPattern{Aristotle}}\\ % \rowcolor{nagrey}\cmd{\Aris} & \Aris & % \texttt{\ShowPattern{Aristotle}}\\\bottomrule % \end{tabular} % \end{center}\medskip % % Six suffixes are appended to these patterns to create six ``systems'' or data sets. The \meta{pattern} element in the next table is the output of \cmd{\ShowPattern}. Within that \meta{pattern} is a leading colon, name elements with spaces removed, and delimiters that separate those elements. Western names use an exclamation point and a comma. Non-Western names only use a comma. For the use of ID, see \cmd{\ShowNameState} on page~\pageref{page:NameState}. For the way that exclusions use the cross-reference system as a special case for preventing index interaction, see Section~\ref{sec:IdxFine}. % % \begin{center}\small\medstretch % \begin{tabular}{llll}\toprule % Description & Pattern & ID & Example\\ % \rowcolor{nagrey}Front-matter names & \meta{pattern}\texttt{!NF} & % front & \texttt{\ShowPattern[Adolf]{Harnack}{!NF}}\\ % Main-matter names & \meta{pattern}\texttt{!MN} & main & % \texttt{\ShowPattern[Hideyo]{Noguchi}{!MN}}\\ % \rowcolor{nagrey}Index cross-refs & \meta{pattern}\texttt{!PN} & % xref & \texttt{\ShowPattern{Yamamoto, Isoroku}{!PN}}\\ % Exclusions & \meta{pattern}\texttt{!PN} & % excl & (like xref, special value)\\ % \rowcolor{nagrey}Index sort tags & \meta{pattern}\texttt{!PRE} & pretag & % \texttt{\ShowPattern{Henry, VIII}{!PRE}}\\ % Index data tags & \meta{pattern}\texttt{!TAG} & % idxtag & \texttt{\ShowPattern{Demetrius, I}{!TAG}}\\ % \rowcolor{nagrey}Name data tags & \meta{pattern}\texttt{!DB} & namedb & % \texttt{\ShowPattern{Aristotle}{!DB}}\\\bottomrule % \end{tabular} % \end{center} % % The following macros write the patterns that they generate to certain systems or data sets. \cmd{\IndexName} does not generate a name pattern, even though it writes index entries. This lets the index control logic be keyed to cross-references. % % \begin{center}\small\medstretch % \begin{tabular}{lcccccc}\toprule[1pt] % Macros & \ttfamily \,!NF\, & \ttfamily \,!MN\, & \ttfamily \,!PN\, & % \ttfamily !PRE & \ttfamily !TAG & \ttfamily \,!DB\,\\\midrule % \cmd{\Name} \cmd{\Name*} \cmd{\FName} \cmd{\FName*} & \YES & \YES & \NO & % \NO & \NO & \NO\\ % \cmd{\ForgetName} \cmd{\SubvertName} & \YES & \YES & \NO & % \NO & \NO & \NO\\\midrule % \cmd{\PName} \cmd{\PName*} & \YES & \YES & \YES & \NO & \NO & \NO\\\midrule % \cmd{\AKA} \cmd{\AKA*} \cmd{\IndexRef} & \NO & \NO & \YES & % \NO & \NO & \NO\\ % \cmd{\ExcludeName} & \NO & \NO & \YES & \NO & \NO & \NO\\ % \cmd{\IncludeName} \cmd{\IncludeName*} & \NO & \NO & \YES & % \NO & \NO & \NO\\\midrule % \cmd{\PretagName} & \NO & \NO & \NO & \YES & \NO & \NO\\\midrule % \cmd{\TagName} \cmd{\UntagName} & \NO & \NO & \NO & % \NO & \YES & \NO\\\midrule % \cmd{\NameAddInfo} \cmd{\NameClearInfo} & \NO & \NO & \NO & % \NO & \NO & \YES\\\bottomrule % \end{tabular} % \end{center} % % \subsection{Indexing: States} % \label{sec:RuleStates} % % Six distinct ``states'' describe any name pattern with respect to the index. They are derived using \cmd{\ShowNameState}. Below we show these states and what they mean. % % \begin{tcolorbox} % [colback=white,colframe=darkgray, % adjusted title={\bfseries\hfil State 1: No Name Information Present}] % \footnotesize % \begin{itemize}[leftmargin=1em,rightmargin=1em] % \item \Stay{\cmd{\IndexName} makes index page entry, % creates no name pattern control sequence}{1} % \item \Stay{\cmd{\TagName} makes index tag, creates a pattern % ending in \texttt{!TAG}; \cmd{\UntagName} destroys it}{1} % \item \Stay{\cmd{\PretagName} makes index sort tag, creates a % pattern ending in \texttt{!PRE} (do only once)}{1} % \item \Stay{\cmd{\ForgetName} is redundant; it cannot destroy % a control sequence that does not exist.}{1} % \item \Go{Naming macro makes name pattern (\texttt{!MN} or % \texttt{!NF}), prints name, makes two index page entries}{2} % \item \Go{\cmd{\SubvertName} makes a name pattern ending % either in \texttt{!MN} or in \texttt{!NF}, or both at once}{2} % \item \Go{\cmd{\IndexRef} makes an xref pattern ending with % \texttt{!PN}; that pattern expands to empty}{3} % \item \Go{\cmd{\SeeAlso}\cmd{\IndexRef} makes an xref pattern % ending with \texttt{!PN}; that pattern expands to empty}{3} % \item \Go{\cmd{\ExcludeName} makes an xref pattern ending with % \texttt{!PN}; that pattern expands to \texttt{!x!}}{5} % \end{itemize} % \end{tcolorbox} % % \begin{tcolorbox} % [colback=white,colframe=darkgray, % adjusted title={\bfseries\hfil State 2: Only a Name Pattern Exists}] % \footnotesize % \begin{itemize}[leftmargin=1em,rightmargin=1em] % \item \Stay{\cmd{\IndexName} makes index page entry, creates % no name pattern control sequence}{2} % \item \Stay{\cmd{\TagName} makes index tag, creates a pattern % ending in \texttt{!TAG}; \cmd{\UntagName} destroys it}{2} % \item \Stay{\cmd{\PretagName} is doable, but not recommended % (that will create spurious entries)}{2} % \item \Stay{Naming macro makes name pattern (\texttt{!MN} or % \texttt{!NF}), prints name, makes two index page entries}{2} % \item \Stay{\cmd{\SubvertName} is redundant; it cannot create % a control sequence that already exists.}{2} % \item \Stay{\cmd{\IndexRef} by itself does nothing because a % name pattern already exists}{2} % \item \Go{\cmd{\ForgetName} destroys a name pattern ending in % \texttt{!MN}, \texttt{!NF}, or both at once}{1} % \item \Go{\cmd{\SeeAlso}\cmd{\IndexRef} makes an xref pattern % ending with \texttt{!PN}; that pattern expands to empty}{4} % \item \Go{\cmd{\ExcludeName} makes an xref pattern ending with % \texttt{!PN}, that pattern expands to \texttt{!x!}}{6} % \end{itemize} % \end{tcolorbox} % % \begin{tcolorbox} % [colback=white,colframe=darkgray, % adjusted title={\bfseries\hfil State 3: Only an Xref Pattern Exists}] % \footnotesize % \begin{itemize}[leftmargin=1em,rightmargin=1em] % \item \Stay{\cmd{\PretagName} is doable, but not recommended % (that will create spurious entries)}{3} % \item \Stay{\cmd{\TagName}, \cmd{\UntagName}, \cmd{\IndexName}, % \cmd{\IndexRef} (also with \cmd{\SeeAlso}), \cmd{\ExcludeName}, % and \cmd{\IncludeName} do nothing}{3} % \item \Stay{\cmd{\ForgetName} is redundant; it cannot destroy % a control sequence that does not exist.}{3} % \item \Go{\cmd{\Includename*} destroys an extant xref pattern % (\texttt{!PN})}{1} % \item \Go{Naming macro makes name pattern (\texttt{!MN} or % \texttt{!NF}), prints name, makes no index entries}{4} % \item \Go{\cmd{\SubvertName} creates a name pattern ending % either in \texttt{!MN} or in \texttt{!NF}, or both at once}{4} % \end{itemize} % \end{tcolorbox} % % \begin{tcolorbox} % [colback=white,colframe=darkgray, % adjusted title={\bfseries\hfil State 4: Both Name and % Xref Patterns Exist}] % \footnotesize % \begin{itemize}[leftmargin=1em,rightmargin=1em] % \item \Stay{\cmd{\PretagName} is doable, but not recommended % (that will create spurious entries)}{4} % \item \Stay{\cmd{\TagName}, \cmd{\UntagName}, \cmd{\IndexName}, % \cmd{\IndexRef} (also with \cmd{\SeeAlso}), \cmd{\ExcludeName}, % and \cmd{\IncludeName} do nothing}{4} % \item \Stay{Naming macro makes name pattern (\texttt{!MN} or % \texttt{!NF}), prints name, makes no index entries}{4} % \item \Stay{\cmd{\SubvertName} is redundant; it cannot create % a control sequence that already exists.}{4} % \item \Go{\cmd{\Includename*} destroys an extant xref pattern % (\texttt{!PN})}{2} % \item \Go{\cmd{\ForgetName} destroys a name pattern ending in % \texttt{!MN}, \texttt{!NF}, or both at once}{3} % \end{itemize} % \end{tcolorbox} % % \begin{tcolorbox} % [colback=white,colframe=darkgray, % adjusted title={\bfseries\hfil State 5: Only an Exclusion Exists}] % \footnotesize % \begin{itemize}[leftmargin=1em,rightmargin=1em] % \item \Stay{\cmd{\PretagName} is doable, but not recommended % (that will create spurious entries)}{5} % \item \Stay{\cmd{\TagName}, \cmd{\UntagName}, \cmd{\IndexName}, % \cmd{\IndexRef} (also with \cmd{\SeeAlso}), and % \cmd{\ExcludeName} do nothing}{5} % \item \Stay{\cmd{\ForgetName} is redundant; it cannot destroy % a control sequence that does not exist.}{5} % \item \Go{\cmd{\Includename}, \cmd{\Includename*} destroy xref % pattern ending with \texttt{!PN}, expanding to \texttt{!x!}}{1} % \item \Go{Naming macro makes name pattern (\texttt{!MN} or % \texttt{!NF}), prints name, makes no index entries}{6} % \item \Go{\cmd{\SubvertName} creates a name pattern ending either % in \texttt{!MN} or in \texttt{!NF}, or both at once}{6} % \end{itemize} % \end{tcolorbox} % % \begin{tcolorbox} % [colback=white,colframe=darkgray, % adjusted title={\bfseries\hfil State 6: Both Name Pattern and % Exclusion Exist}] % \footnotesize % \begin{itemize}[leftmargin=1em,rightmargin=1em] % \item \Stay{\cmd{\PretagName} is doable, but not recommended % (that will create spurious entries)}{6} % \item \Stay{\cmd{\TagName}, \cmd{\UntagName}, \cmd{\IndexName}, % \cmd{\IndexRef} (also with \cmd{\SeeAlso}), and % \cmd{\ExcludeName} do nothing}{6} % \item \Stay{Naming macro makes name pattern (\texttt{!MN} or % \texttt{!NF}), prints name, makes no index entries}{6} % \item \Go{\cmd{\Includename}, \cmd{\Includename*} destroy xref % pattern ending with \texttt{!PN}, expanding to \texttt{!x!}}{2} % \item \Go{\cmd{\ForgetName} destroys a name pattern ending in % \texttt{!MN}, \texttt{!NF}, or both at once}{5} % \end{itemize} % \end{tcolorbox} % % \subsection{Debugging Macros} % \label{sec:DebuggingMacros} % % \DescribeMacro{\ShowPattern} % We use \cmd{\ShowPattern} in Section~\ref{sec:NamePatterns} to illustrate name control patterns. It displays how the name arguments create name patterns that form name control sequences. One can debug pattern collisions and other issues with this macro: % % \begin{SyntaxBox} % \cmd{\ShowPattern}\oarg{FNN}\marg{SNN|,| Affix}\oarg{Alternate} % \end{SyntaxBox} % % Thus, |\texttt{\ShowPattern[Hernando]{de~Soto}}| will produce the output \JustIndex\Soto\texttt{\ShowPattern[Hernando]{de~Soto}}. As we have seen before, using \textsf{inputenc}/\textsf{fontenc} will cause names like |\texttt{\ShowPattern{Boëthius}}| to produce \texttt{\ShowPattern{Boëthius}}\JustIndex\Name{Bo\"ethius}.\medskip % % \DescribeMacro{\ShowIdxPageref} % \cmd{\ShowIdxPageref} displays a full index entry in the text as if it were only a page reference, not a cross-reference. % % \begin{SyntaxBox} % \cmd{\ShowIdxPageref\ }\oarg{FNN}\marg{SNN|,| Affix}\oarg{Alternate} % \end{SyntaxBox} % % Index styles, \cmd{\PretagName}, and \cmd{\TagName} affect the output of \cmd{\ShowIdxPageref}. Active characters and macros appear as printed, not as in \texttt{idx} files. In a normal \LaTeX\ document, for example, if we mention \LSoto\ after setting up the following sort tag (Section~\ref{sec:IndexSort}), we get: % % \begin{quote}\small % |\PretagName[Hernando]{de~Soto}{Desoto, Hernando}| % % \IndexActual{@}\UntagName[Hernando]{de~Soto} % |\ShowIdxPageref[Hernando]{de~Soto}|\\ % \ShowIdxPageref[Hernando]{de~Soto}\footnote{We cannot generate any index % entries in this quote because we changed \cmd{\IndexActual}.} % \end{quote} % % In this \texttt{dtx} file, however, due to extra setup needed in the % ``commented'' part of the file (Section~\ref{sec:IndexTag}), we get: % % \begin{quote}\small % |\PretagName[Hernando]{de~Soto}{Desoto, Hernando}|\\ % \verb+\TagName[Hernando]{de~Soto}{\string|hyperpage}+ % % \TagName[Hernando]{de~Soto}{\string|hyperpage} % \IndexActual{=} % |\ShowIdxPageref[Hernando]{de~Soto}|\\ % \ShowIdxPageref[Hernando]{de~Soto} % \end{quote} % % \DescribeMacro{\ShowIdxPageref*} % Throughout this manual, \cmd{\ShowIdxPageref*} illustrates basic index entries that do not contain sorting information or tags. The syntax is: % % \begin{SyntaxBox} % \cmd{\ShowIdxPageref*}\oarg{FNN}\marg{SNN|,| Affix}\oarg{Alternate} % \end{SyntaxBox} % % Regardless of whether we have a normal \LaTeX\ document or a \texttt{dtx} file, we get:\JustIndex\Soto % % \begin{quote}\small % |\ShowIdxPageref*[Hernando]{de~Soto}|\\ % \ShowIdxPageref*[Hernando]{de~Soto} % \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. % % \begin{SyntaxBox} % \cmd{\ShowNameInfo}\oarg{FNN}\marg{SNN|,| Affix}\oarg{Alternate} % \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}. Below are names that (mostly) appear elsewhere in the manual: % % \begin{itemize}\small % \item |\ShowNameInfo[J.E.]{Carter, Jr.}[James Earl]| % \item[] \ShowNameInfo[J.E.]{Carter, Jr.}[James Earl] % \item[] |\Name*[J.E.]{Carter, Jr.}[James Earl]|\dotfill % \Name*[J.E.]{Carter, Jr.}[James Earl] % \item |\ShowNameInfo{Miyazaki, Hayao}[Sensei]| % \item[] \ShowNameInfo{Miyazaki, Hayao}[Sensei] % \item[] |\Name*{Miyazaki, Hayao}[Sensei]|\dotfill % \Name*{Miyazaki, Hayao}[Sensei] % \item |\ShowNameInfo{Elizabeth, I}[I, ``Gloriana'']| % \item[] \ShowNameInfo{Elizabeth, I}[I, ``Gloriana''] % \item[] |\Name*{Elizabeth, I}[I, ``Gloriana'']|\dotfill % \Name*{Elizabeth, I}[I, ``Gloriana''] % % \newpage % % \item |\ShowNameInfo{Henry}[VIII]| (obsolete syntax) % \item[] \ShowNameInfo{Henry}[VIII] % \item[] |\Name*{Henry}[VIII]\ddag|\dotfill % \Name*{Henry}[VIII]\ddag % \item |\ShowNameInfo{Confucius}| % \item[]\ShowNameInfo{Confucius} % \item[] |\Name*{Confucius}|\dotfill\Name*{Confucius} % \end{itemize} % % For the following examples we activate alternate formatting % (Section~\ref{sec:AltFormat}). % % \AltFormatActive % \begin{itemize}\small % \item |\ShowNameInfo[John]{\noexpand\de{Strietelmeier}}| % \item[]\ShowNameInfo[John]{\noexpand\de{Strietelmeier}} % \item[]|\Name* [John]{\noexpand\de{Strietelmeier}|\dotfill\LStriet % \item |\ShowNameInfo[Catherine \noexpand\AltCaps{d}e']|\\ % |{\noexpand\textSC{Medici}}| % \item[]\ShowNameInfo[Catherine \noexpand\AltCaps{d}e'] % {\noexpand\textSC{Medici}} % \item[]|\Name [Catherine \noexpand\AltCaps{d}e']|\\ % |{\noexpand\textSC{Medici}}|\dotfill\Cath % \item |\ShowNameInfo[Martin]{\noexpand\textSC{Luther}}|\footnote{In % several cases (e.g., here) when one uses small caps, harmless % font substitution warnings result.} % \item[]\ShowNameInfo[Martin]{\noexpand\textSC{Luther}} % \item[]|\Name* [Martin]{\noexpand\textSC{Luther}}|\dotfill\Luth % \item Using \cmd{\noexpand} before macros in name arguments % ``fixates'' them. % \begin{itemize} % \item|\ShowNameInfo[John]{\noexpand\de{Strietelmeier}}| % \item[]\ShowNameInfo[John]{\noexpand\de{Strietelmeier}} % \item|\ShowNameInfo[John]{\de{Strietelmeier}}| % \item[]\footnotesize\ShowNameInfo [John]{\de{Strietelmeier}} % \end{itemize} % \item If one uses an undefined macro in the arguments, % but precedes it with \cmd{\noexpand}, \cmd{\ShowNameInfo} % will not generate an error. % \begin{itemize} % \item|\ShowNameInfo{\noexpand\SomeUndefinedMacro}| % \item\ShowNameInfo{\noexpand\SomeUndefinedMacro} % \end{itemize} % \end{itemize} % \AltFormatInactive % % \negmedskip % \NameArgWarning % \medskip % % \phantomsection % \label{page:NameState} % \DescribeMacro{\ShowNameState} % With this macro we can see all the systems with which a name pattern is associated and the current index ``state'' described in Section~\ref{sec:RuleStates}. Its syntax is: % % \begin{SyntaxBox} % \cmd{\ShowNameState}\oarg{FNN}\marg{SNN|,| Affix}\oarg{Alternate} % \end{SyntaxBox} % % For example: |\ShowNameState[George]{Washington}| outputs a line of plain text regarding \LWash, which we can typeset any way we like: % % \begin{quote}\small % \hfil\ShowNameState[George]{Washington}.\IndexName[George]{Washington} % \end{quote} % % \newpage % % The information given includes: % % \begin{itemize} % \item Base name pattern, the base control pattern that % \textsf{nameauth} sees. % \item Type of name, referring to how the name in the argument was parsed. % \begin{itemize}[leftmargin=3.7em] % \item[w :] Western (regardless of whether it is reversed) % \item[nw :] non-Western (regardless of whether it is reversed) % \item[nw,os :] non-Western name, obsolete syntax (Section~\ref{sec:Obsolete}) % \end{itemize} % \item Index state (Section~\ref{sec:RuleStates}) shows what index-related % options are permissible and how the indexing macros will behave. % \begin{itemize}[leftmargin=3.7em] % \item[states :] 1, 2, 3, 4, 5, and 6 % \end{itemize} % \item All the control systems (Section~\ref{sec:NamePatterns}) that % the name pattern inhabits. % \begin{itemize}[leftmargin=4.5em] % \item[systems :] front, main, xref, excl, pretag, idxtag, namedb. % \end{itemize} % \end{itemize} % % In the next table we show examples that have indexing states in order from one to six, and we illustrate all name types and control systems. All extant names have index tags because, in a \texttt{dtx} file using the \textsf{ltxdoc} class with \textsf{hypdoc}, one must add a hyperlink to all names in the index (Section~\ref{sec:SpecialTag}). Otherwise, names need not always have a control pattern in the \texttt{idxtag} system. % % \begin{center}\small\medstretch % \begin{tabular}{p{0.4\textwidth}p{0.5\textwidth}}\toprule % Name & \cmd{\ShowNameState}\\ % \rowcolor{nagrey}(\textit{unused in naming macro})\par % |\ShowNameState{Not Seen, Yet}| & \ShowNameState{Not Seen, Yet} \\ % \Name*[Rudolph]{Carnap}\par |\Name*[Rudolph]{Carnap}| & % \ShowNameState[Rudolph]{Carnap}\\ % \rowcolor{nagrey}\Name*{Henry, VIII}\par % |\Name*{Henry, VIII}| & \ShowNameState{Henry, VIII}\\ % \Name*{Henry}[VIII]\ddag\par |\Name*{Henry}[VIII]\ddag| & % \ShowNameState{Henry}[VIII]\\ % \rowcolor{nagrey}\Name*{Thomas, à~Kempis}\par % |\Name*{Thomas, à~Kempis}| & \ShowNameState{Thomas, à~Kempis}\\ % (\textit{unused in naming macro})\par % |\IndexRef{Sun King}{Louis XIV}|\IndexRef{Sun King}{Louis XIV}\par % |\ShowNameState{Sun King}| & \hbox{}\par \ShowNameState{Sun King}\\ % \rowcolor{nagrey}\Name*{Sun King}\par % |\Name*{Sun King}| & \ShowNameState{Sun King}\\ % (\textit{unused in naming macro})\ExcludeName{Santa, Claus}\par % |\ExcludeName{Santa, Claus}| & \ShowNameState{Santa, Claus}\\ % \rowcolor{nagrey}\Name*{Thomas,\`a~Kempis}\par % |\Name*{Thomas,\`a~Kempis}| & \ShowNameState{Thomas,\`a~Kempis}\\ % \bottomrule % \end{tabular} % \end{center} % % \ReturnLink % % \newpage % % \section{Indexing Macros} % \label{sec:Indexing} % \IndexWarnVerbose % % We discuss indexing here because it pulls together all the concepts from the previous sections and applies them to the index instead of the body text. % % \subsection[General Control]{General Indexing Control} % \label{sec:GeneralIndex} % % \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}. % % \vspace{2ex} % \Info{Test indexing rules:\break % \Name{Yamaha, Torakusu}\label{page:Idx1}\break % create index entry:\break % \cmd{\IndexName}\break % \texttt{\{Nippon Gakki\}}\IndexName{Nippon Gakki}} % \vspace{-2ex} % \begin{itemize} % \item \cmd{\IndexInactive} broadly suppresses \cmd{\IndexName}, % \cmd{\IndexRef}, and the indexing components of the naming macros, % \cmd{\AKA}, and \cmd{\PName}. % \item For a fine degree of control, use \cmd{\ExcludeName} and % \cmd{\IncludeName}. % \end{itemize} % % \cmd{\IndexActive}\Info{\cmd{\global}} and \cmd{\IndexInactive} can be used as a pair or singly within a group. They have top priority (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. % % \ifdefined\NameauthDoTestFiles \edef\NameauthTestFile{test07_01.tex}\else % \edef\NameauthTestFile{\jobname.tmp}\fi % % \begin{VerbatimOut}{\NameauthTestFile} % \documentclass{article} % \input{compat.tex} % Included with nameauth; needed only if % % compiling on multiple TeX distros or LaTeX engines. % \usepackage{index} % \usepackage{nameauth} % % \makeindex % Default index % \newindex{per}{rdx}{rnd}{Index of Persons} % Other index % \renewcommand*\NameauthIndex{\index[per]} % % \begin{document} % The Electric Boogaloo\index{Boogaloo, Electric}\\ % main index % was created by \Name{Ollie~\& Jerry}. % name index % % \printindex[per] % Shows the entry: Ollie & Jerry, 1 % % \renewcommand\indexname{Index of Subjects} % \printindex % Shows the entry: Boogaloo, Electric, 1 % \end{document} % \end{VerbatimOut} % % \begin{quote}\small % \VerbatimInput[gobble=0]{\NameauthTestFile} % \end{quote} % % \subsubsection{Verbose Warnings} % % \DescribeMacro{\IndexWarnVerbose} % As with many of the other options in \textsf{nameauth}, we have added two macros that toggle verbose index warnings like the \texttt{verbose} option (default is terse). % \DescribeMacro{\IndexWarnTerse} % To disable verbose warnings, use \cmd{\IndexWarnTerse}. To enable verbose warnings, use the \texttt{verbose} option or \cmd{\IndexWarnVerbose}. Throughout Section~\ref{sec:Indexing} we enable verbose warnings.\footnote{We both enable verbose warnings, and we deliberately trigger many of them. This helps to test if they are working as expected.} % % \newpage % % \cmd{\IndexWarnVerbose}\Info{\cmd{\global}} and \cmd{\IndexWarnTerse} can be used as a pair or singly within a group. They have the same priority as the \texttt{verbose} option, but they do not affect what is displayed in the document. Use \cmd{\global} to force a global effect. % % \subsubsection{Index Protection} % % \DescribeMacro{\IndexProtect} % This macro prevents naming macros from producing output, both in the text and in the index. It is local in scope. Its primary use is to prevent errors in the index, in case the naming macros get passed as arguments to themselves or passed into index entries by mistake. The core naming engine uses internal locks to protect against this problem in the text. % % \vspace{3ex} % \Info{Test indexing rules:\break % \Name{Yamaha, Torakusu}\label{page:Idx2}} % \vspace{-3ex} % One can use \cmd{\IndexProtect} right before \cmd{\printindex} to protect the index against bogus output. For example: % % \begin{itemize} % \item |\Name{foo\Name{bar}}| in the text generates \Name{foo\Name{bar}}. % Notice that the internal locks prevent |\Name{bar}| from producing % output in the text. % \item The first \LaTeX\ pass creates |\indexentry{foo\Name {bar}}| % in the \texttt{idx} file. With enough passes, using also % \texttt{makeindex}, in the \texttt{ind} file we get both % |\item foo\Name {bar}| from the text and an additional % |\item bar| from the macro executed in the index. % \item That gives one index entry ``foo{\NamesFormat bar}'' and % another entry ``bar''. % \item Using \cmd{\IndexProtect} \cmd{\printindex} still permits % the index entry generated by |\item foo\Name {bar}|, but it does not % allow |\Name {bar}| to generate any output or additional entries % in the index. % \item We get only one entry ``foo'', similar to what we see in the text. % This manual uses the tag \S\ for \cmd{\Name\{foo}\cmd{\Name\{bar\}\}}, % not shown in the example for the sake of clarity. % \end{itemize} % % \subsection{Page Entries} % \label{sec:IndexPageno} % % \DescribeMacro{\IndexName} % 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} % \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 non-Western syntax (Section~\ref{sec:Obsolete}). Indexing follows [\hyperlink{Mulvany}{Mulvany}, 152--82]. The points below deal with macros explained in Section~\ref{sec:IdxPrefix}. % % \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}. % \end{itemize} % % \subsection{Cross-References} % \label{sec:IndexRef} % % Index cross-references have two kinds. \textit{See} references only point from a name to other name entries containing page references. \textit{See also} references occur at the end of an entry with page references or subentries. % % \subsubsection[Basic Macro]{Basic Macros for Both Kinds of Xrefs} % % \DescribeMacro{\IndexRef} % By default, \cmd{\IndexRef} creates a \textit{see} reference from the name defined by its first three arguments to the target in its final argument. To create a \textit{see also} reference, one must precede it with \cmd{\SeeAlso} (Section~\ref{sec:IdxPrefix}). Thus, the two forms used are: % % \begin{SyntaxBox} % \phantom{\cmd{\SeeAlso}}\cmd{\IndexRef}\oarg{FNN}\marg{SNN|,| % Affix}\oarg{Alternate}\marg{Target}\\ % \cmd{\SeeAlso}\cmd{\IndexRef}\oarg{FNN}\marg{SNN|,| % Affix}\oarg{Alternate}\marg{Target} % \end{SyntaxBox} % % Although it might be redundant to point this out, in practice, when using \cmd{\IndexName} and \cmd{\IndexRef}, one can forget that the latter has four arguments, at least two of which are required. Missing text and bad xrefs can result. % % \begin{itemize} % \item Define \textit{see} references \emph{before} making any % \cmd{\Name} references to them. % \vspace{-1ex} % \Info{Test indexing rules:\break % Creating \textit{see also} xref\break\footnotesize % \cmd{\SeeAlso}\cmd{\IndexRef}\break\ttfamily % \{Yamaha, Torakusu\}\break % \{Nippon Gakki\}\SeeAlso\IndexRef{Yamaha, Torakusu}{Nippon Gakki}^^A % \label{page:Idx3}} % \vspace{1ex} % \item Define \textit{see also} references \emph{after} all % \cmd{\Name} references to the respective names have been created. % \item \cmd{\IndexRef} will not alter or repeat extant cross-references. % \item \cmd{\IndexRef} will not cross-reference names excluded % by \cmd{\ExcludeName}. % \item \cmd{\IndexRef} will not add a \textit{see} cross-reference % that would map also to an extant name control pattern, unless one % uses the \texttt{oldsee} option. A fuller explanation of this % non-trivial fact lies in Section~\ref{sec:RuleStates}, illustrated % by a state diagram. A page entry usually correlates with a name % control pattern, but that may not always be the case. We check for % a control sequence (name pattern); usually, a page entry also exists. % \item \cmd{\IndexName} resets the effects of both \cmd{\SeeAlso} % and \cmd{\SkipIndex}, unless one uses the \texttt{oldreset} option. % \item To have multiple names and cross-references interact, see % Section~\ref{sec:IdxVariants}. % \end{itemize} % % \cmd{\IndexRef} prints nothing in the text. The name parsing is like \cmd{\IndexName}. The final argument is not checked in any way. For example: % % \begin{quote}\small % \vspace{3ex} % \Info{\strut\footnotesize Name Pattern(s):\hfill % \break\ttfamily\ShowPattern{Sun King}!PN} % \vspace{-3ex} % \begin{tabular}{ll} % source: & \cmd{\IndexRef}\texttt{\{Sun King\}\{Louis XIV\}}^^A % \IndexRef{Sun King}{Louis XIV}\\[0.5ex] % index: & Sun King \textit{see} Louis XIV\\ % \end{tabular} % \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}\small % \begin{tabular}{ll} % source: & |\IndexRef{bar}{baz; foo}|\\[0.5ex] % index: & bar, \textit{see} baz; foo\\ % \end{tabular} % \end{quote} % % \newpage % % \subsubsection[Fine Control]{Fine Control of Xref Logic} % \label{sec:IdxFine} % % Here we show how the index control logic pertinent to cross-references can be extended to establish fine-grained control that can exclude or include names.\medskip % % \DescribeMacro{\ExcludeName} % We can prevent a name from being used as either an index entry or as an index cross-reference. This macro will not exclude extant cross-references: % % \begin{SyntaxBox} % \cmd{\ExcludeName}\oarg{FNN}\marg{SNN|,| Affix}\oarg{Alternate} % \end{SyntaxBox} % % Unlike \cmd{\IndexInactive} and \cmd{\IndexActive}, which globally prevent and permit indexing, \cmd{\ExcludeName} only excludes a specific name from being printed as a page reference or cross-reference in the index. See the following example, as well as examples in Sections~\ref{sec:NameParticles} and \ref{sec:VarNames}. Indexing remains active: % % \begin{VerbatimOut}{\jobname.tmp} % \ExcludeName{Mr. Baseball} % In this example we cannot get page references for % \Name{Mr. Baseball}, the nickname of % \Name[Bob]{Uecker}, because it was excluded. % \end{VerbatimOut} % % \begin{quote}\small % \vspace{3ex} % \PatInfo{\ShowPattern{Mr. Baseball}!PN\break % \ShowPattern[Bob]{Uecker}!MN} % \vspace{-3ex} % \VerbatimInput[gobble=0]{\jobname.tmp} % % \input{\jobname.tmp} % \end{quote} % % \DescribeMacro{\IncludeName} % Use these macros to break a few indexing rules. They remove the protections used for exclusion and cross-referencing. % \DescribeMacro{\IncludeName*} % They have the same syntax as \cmd{\ExcludeName}: % % \begin{SyntaxBox} % \cmd{\IncludeName\ }\oarg{FNN}\marg{SNN|,| Affix}\oarg{Alternate}\\ % \cmd{\IncludeName*}\oarg{FNN}\marg{SNN|,| 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 references to a name in the index that had been used as a cross-reference. % % \vspace{3ex} % \Info{Test indexing rules:\break \Name{Yamaha, Torakusu}\label{page:Idx4}} % \vspace{-3ex} % Analogously, \cmd{\ForgetName} (Section~\ref{sec:NameControl}) removes name control patterns, allowing one to create a cross-reference. Section~\ref{sec:RuleStates} explains this behavior as a set of states. Below we run some tests (cf. Section~\ref{sec:NameTests}) and produce a few warnings because verbose warnings are active here. % % \begin{itemize} % \item \Name*{Mr. Baseball} is % \IfAKA{Mr. Baseball}{\meta{an xref}}{\meta{a name}}{\meta{excluded}}. % The test used was: % \item[] |\IfAKA{Mr. Baseball}{|\meta{an xref}|}{|\meta{a name}^^A % |}{|\meta{excluded}|}| % \item We now try |\IndexRef{Mr. Baseball}{Uecker, Bob}|^^A % \IndexRef{Mr. Baseball}{Uecker, Bob}. % \Name*{Mr. Baseball} is still % \IfAKA{Mr. Baseball}{\meta{an xref}}{\meta{a name}}{\meta{excluded}}. % No cross-reference was created. % \item Using |\IncludeName{Mr. Baseball}|\IncludeName{Mr. Baseball} % makes it % \IfAKA{Mr. Baseball}{\meta{an xref}}{\meta{a name}}{\meta{excluded}}. % Now we could create page entries with a naming macro, but we % do not do so. % \item Instead, we use % |\ForgetName{Mr. Baseball}|\ForgetName{Mr. Baseball} to destroy % the name pattern, the control sequence that governs the name. % It is now % \IfAKA{Mr. Baseball} % {\meta{an xref}} % {\IfMainName{Mr. Baseball}{\meta{extant}} % {\IfFrontName{Mr. Baseball} % {\meta{extant}}{\meta{destroyed}}^^A % }^^A % } % {\meta{excluded}}. % \item |\IndexRef{Mr. Baseball}{Uecker, Bob}|^^A % \IndexRef{Mr. Baseball}{Uecker, Bob} creates % \IfAKA{Mr. Baseball}{\meta{an xref}}{\meta{a name}}{\meta{excluded}}. % \end{itemize} % % \newpage % % Cross-references get more protection. We have seen % \DropAffix\LJRIV[Jay] indexed under % ``\ShowIdxPageref*[J.D.]{Rockefeller, IV}'' with % |\DropAffix\LJRIV[Jay]|. % We create the following cross-reference: % \IndexRef[Jay]{Rockefeller}{Rockefeller, J.D., IV}^^A % |\IndexRef[Jay]{Rockefeller}{Rockefeller, J.D., IV}|. % \vspace{-6ex} % \PatInfo{\ShowPattern[J.D.]{Rockefeller, IV}!MN\break % \ShowPattern[Jay]{Rockefeller}!PN\break % \ShowPattern[Jay]{Rockefeller}!MN} % \vspace{6ex} % \begin{itemize} % \item % \cmd{\IfAKA[Jay]\{Rockefeller\}}|{|\meta{xref}|}{|\meta{name}|}{}| % calls \SJRIV[Jay] an % \IfAKA[Jay]{Rockefeller}{\meta{xref}}{\meta{name}}{}. % \item After % |\IncludeName[Jay]{Rockefeller}|\IncludeName[Jay]{Rockefeller} % he still is an % \IfAKA[Jay]{Rockefeller}{\meta{xref}}{\meta{name}}{}. % \item After % |\IncludeName*[Jay]{Rockefeller}|\IncludeName*[Jay]{Rockefeller} % he may be a \IfAKA[Jay]{Rockefeller}{\meta{xref}}{\meta{name}}{}. % \item Now \cmd{\Name[Jay]\{Rockefeller\}} can create page entries. % \end{itemize} % % \negmedskip % \begin{InfoBox} % Using \cmd{\IncludeName*} is necessary when creating index sub-entries for a name using \cmd{\IndexTag}. If one creates a cross-reference in any sub-entry of a name, \cmd{\IncludeName*} will permit additional page references to be made for the other sub-entries of that name or for the name itself. See Section~\ref{sec:CatSub}. % \end{InfoBox} % % \subsection[Prefix Macros]{Prefix Macros Used for Indexing} % \label{sec:IdxPrefix} % % Indexing macros ignore Boolean flags meant for naming macros. Yet there are three prefix macros that affect indexing: \cmd{\SeeAlso}, \cmd{\SkipIndex}, and \cmd{\JustIndex}.\medskip % % \DescribeMacro{\SeeAlso} % Put \cmd{\SeeAlso} before \cmd{\IndexRef}, \cmd{\AKA}, and \cmd{\PName} (Section~\ref{sec:AKA}) to make a \textit{see also} reference for a name that has appeared already in the index. If enabled before invoking \cmd{\PName}, \cmd{\SeeAlso} will be disabled when the regular name is generated, then enabled when the cross-reference is generated. % % \begin{VerbatimOut}{\jobname.tmp} % One can refer to \Name[the]{Rat Pack} as a group of entertainers % including \Name[Sammy]{Davis, Jr.}, \Name[Dean]{Martin}, and % \Name[Frank]{Sinatra}. No more page references to % \Name*[the]{Rat Pack} will occur after this line, and a % \textit{see also} xref will exist. % \SeeAlso\IndexRef[the]{Rat Pack} % {Davis, Sammy, Jr.; Martin, Dean; Sinatra, Frank} % \end{VerbatimOut} % % \begin{quote}\small % \VerbatimInput[gobble=0]{\jobname.tmp} % % \input{\jobname.tmp} % \end{quote} % % \leavevmode\Info{Test indexing rules:\break % \Name{Nippon Gakki}\label{page:Idx5}} % Currently \cmd{\IndexName} and other \textsf{nameauth} macros that create index entries will reset the Boolean flag governed by \cmd{\SeeAlso} unless one uses the \texttt{oldreset} option. preventing a stray use of the macro from affecting the index.\medskip % % \DescribeMacro{\SkipIndex} % The prefix macro \cmd{\SkipIndex} will suppress indexing for just one instance of a name displayed by a naming macro. |\SkipIndex\Name[Monty]{Python}| produces \SkipIndex\Name[Monty]{Python} in the text, but with no index entry. \cmd{\SkipIndex} works with the naming macros. Side effects include: % % \begin{itemize} % \item Unless the \texttt{oldreset} option is used, both \cmd{\IndexName} % and \cmd{\IndexRef} issue warnings if \cmd{\SkipIndex} precedes them, % ignore \cmd{\SkipIndex}, and reset its flag. % \item Only when the \texttt{oldreset} option is used, both \cmd{\PName} % and \cmd{\PName*} issue warnings when {\ttfamily % \string \if@nameauth@SkipIndex} is true on exit. % \end{itemize} % % \DescribeMacro{\JustIndex} % This prefix macro makes \cmd{\Name}, \cmd{\Name*}, \cmd{\FName}, and the quick interface shorthand macros act similar to \cmd{\IndexName}. \cmd{\JustIndex} suppresses name output in the text, but flags for long and first name forms are reset as if the naming macro had produced output. Using the \texttt{oldreset} option prevents these flags from being reset, completely mimicking a call to \cmd{\IndexName}. % % \begin{center}\small\medstretch % \begin{tabular}{lll}\toprule % Option & Source & Output\\ % \rowcolor{nagrey}default & |\JustIndex\SWash \Wash| & % \JustIndex\SWash \Wash \hphantom{ George}\\ % default & |\JustIndex\LWash \Wash| & \JustIndex\LWash \Wash\\ % \rowcolor{nagrey}\ttfamily oldpass & |\JustIndex\SWash \Wash| & % \JustIndex\SWash \Wash\\ % \ttfamily oldpass & |\JustIndex\LWash \Wash| & % \JustIndex\LWash \Wash\\\bottomrule % \end{tabular} % \vspace{-15ex}\PatInfo{\ShowPattern[George]{Washington}!MN}\vspace{15ex} % \end{center} % % \phantomsection % \vspace{1ex} % \Info{Test indexing rules:\break % Creating \textit{see} xref\break\footnotesize % \cmd{\IndexRef}\ttfamily \{Nippon Gakki\}\break % \{Yamaha Corp.\}^^A % \IndexRef{Nippon Gakki}{Yamaha Corp.}^^A % \label{page:Idx6}} % \vspace{-1ex} % There are potential side effects related to \cmd{\JustIndex}: % % \begin{itemize} % \item Both \cmd{\AKA} and \cmd{\PName} ignore \cmd{\JustIndex} % and go on about their business. They also set % \cmd{\@nameauth@JustIndexfalse}. % \item \cmd{\JustIndex} resets the flags set by \cmd{\ForgetThis} % and \cmd{\SubvertThis}, preventing them from passing through. % \item The following three lines are equivalent. According to % Section~\ref{sec:Priorities}, \cmd{\JustIndex} takes priority % with \cmd{\Name\{A\}} and passes \cmd{\SkipIndex} to % \cmd{\Name\{B\}}. % % \begin{quote}\small % \cmd{\JustIndex} \cmd{\SkipIndex} \cmd{\Name\{A\}} \cmd{\Name\{B\}}\\ % \cmd{\SkipIndex} \cmd{\JustIndex} \cmd{\Name\{A\}} \cmd{\Name\{B\}}\\ % \cmd{\JustIndex} \cmd{\Name\{A\}} \cmd{\SkipIndex} \cmd{\Name\{B\}} % \end{quote} % % \item One cannot use \cmd{\JustIndex} and the naming macros in place % of \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\smallstretch % \begin{tabular}{rp{0.3\textwidth}p{0.5\textwidth}}\toprule % Page & Macro & Index Result\\ % \rowcolor{nagrey}\pageref{page:Idx1} & % \cmd{\Name\{Yamaha, Torakusu\}}\par % \cmd{\IndexName\{Nippon Gakki\}} & % \ShowIdxPageref*{Yamaha, Torakusu}, \pageref{page:Idx1}\par % \ShowIdxPageref*{Nippon Gakki}, \pageref{page:Idx1}\\ % \pageref{page:Idx2} & % \cmd{\Name\{Yamaha, Torakusu\}} & % \ShowIdxPageref*{Yamaha, Torakusu}, \pageref{page:Idx1}, % \pageref{page:Idx2}\par % \ShowIdxPageref*{Nippon Gakki}, \pageref{page:Idx1}\\ % \rowcolor{nagrey}\pageref{page:Idx3} & % \cmd{\SeeAlso}\cmd{\IndexRef\{Yamaha,}\par % \texttt{Torakusu\}\{Nippon Gakki\}} & % \ShowIdxPageref*{Yamaha, Torakusu}, \pageref{page:Idx1}, % \pageref{page:Idx2} \textit{see also} Nippon Gakki\par % \ShowIdxPageref*{Nippon Gakki}, \pageref{page:Idx1}\\ % \pageref{page:Idx4} & % \cmd{\Name\{Yamaha, Torakusu\}} & % \ShowIdxPageref*{Yamaha, Torakusu}, \pageref{page:Idx1}, % \pageref{page:Idx2} \textit{see also} Nippon Gakki\par % \ShowIdxPageref*{Nippon Gakki}, \pageref{page:Idx1}\\ % \rowcolor{nagrey}\pageref{page:Idx5} & % \cmd{\Name\{Nippon Gakki\}} & % \ShowIdxPageref*{Yamaha, Torakusu}, \pageref{page:Idx1}, % \pageref{page:Idx2} \textit{see also} Nippon Gakki\par % \ShowIdxPageref*{Nippon Gakki}, \pageref{page:Idx1}, \pageref{page:Idx5}\\ % \pageref{page:Idx6} & % \cmd{\IndexRef\{Nippon Gakki\}}\par \texttt{\{Yamaha Corp.\}} & % \ShowIdxPageref*{Yamaha, Torakusu}, \pageref{page:Idx1}, % \pageref{page:Idx2} \textit{see also} Nippon Gakki\par % \ShowIdxPageref*{Nippon Gakki}, \pageref{page:Idx1}, % \pageref{page:Idx5}\\\bottomrule % \end{tabular} % \end{center} % % \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} % % This manual's index entries for \Name{Nippon Gakki} and \Name{Yamaha Corp.} will also include this page in addition to those shown above. % % \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. % % \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. \medskip % % Effects of \cmd{\IndexActual}\Info{\cmd{\global}} are local in scope. Use \cmd{\global} to make it otherwise, but that will affect every use of \cmd{\PretagName} thereafter. We demonstrate this scoping below as it pertains to \texttt{gind.ist} in a \texttt{dtx} file: % % \begin{quote}\small % \vspace{4ex} % \PatInfo{\ShowPattern{Ægidius}!PRE} % \vspace{-4ex} % \begin{Verbatim} % \PretagName{Ægidius}{Aegidius} % % In a \texttt{dtx} file the ``actual'' character is \texttt{=}. % \begingroup % In a local scope we change to the normal character \texttt{@} % and show the index entry: % \texttt{\IndexActual{@}\ShowIdxPageref{Ægidius}}. % \endgroup % Now back to \texttt{dtx} mode: \texttt{\ShowIdxPageref{Ægidius}}. % \end{Verbatim} % % \PretagName{Ægidius}{Aegidius} % % In a \texttt{dtx} file the ``actual'' character is \texttt{=}. % \begingroup % In a local scope we change to the normal character \texttt{@} % and show the index entry: % \texttt{\IndexActual{@}\ShowIdxPageref{Ægidius}}. % \endgroup % Now back to \texttt{dtx} mode: \texttt{\ShowIdxPageref{Ægidius}}. % \end{quote} % % \noindent \DescribeMacro{\PretagName} % The \textsf{nameauth} package enables automatic index sorting using a ``pretag'' (cf. Section~\ref{sec:NamePatterns}). Unless the \texttt{nopretag} option is used (which results in warnings), \cmd{\PretagName} creates a sort key terminated with the ``actual'' character. Do not put the ``actual'' character in the ``pretag'': % % \begin{SyntaxBox} % \cmd{\PretagName}\oarg{FNN}\marg{SNN|,| Affix}\oarg{Alternate}\marg{tag} % \end{SyntaxBox} % % \vspace{2ex} % \PatInfo{\ShowPattern{Æthelred, II}!PRE\break % \ShowPattern[W.E.B.]{Du~Bois}!PRE\break % \ShowPattern{Æthelred, II}!MN\break % \ShowPattern[W.E.B.]{Du~Bois}!MN} % \vspace{-2ex} % One can ``pretag'' any name, any cross-reference, and even excluded names. Once made, sorting tags cannot be unmade. If one uses \cmd{\PretagName} in the preamble, those names will be sorted automatically throughout the document. For example: % % \begin{quote}\small % \begin{Verbatim} % \PretagName{Æthelred, II}{Aethelred 2} % \PretagName[W.E.B.]{Du~Bois}{Dubois, William} % \end{Verbatim} % \end{quote} % % Every reference to \LAeth\ and \LDuBois\ is automatically tagged and sorted.\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. % % 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: % % \begin{VerbatimOut}{\jobname.tmp} % \PretagName{\textit{Doctor angelicus}}{Doctor angelicus} % \IndexRef{\textit{Doctor angelicus}}{Thomas Aquinas} % % Perhaps the greatest medieval theologian was % \Name{Thomas, Aquinas}, later known as % \Name{\textit{Doctor angelicus}}. % \end{VerbatimOut} % % \begin{quote}\small % {\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} % % \input{\jobname.tmp} % \end{quote} % % If we had wanted \Name{\textit{Doctor angelicus}} to have page entries and a \textit{see also} reference, we would have omitted line~2 above, waited until the end of the body text, after both names were fully indexed, and then used the following: % % \begin{quote}\small % |\SeeAlso\IndexRef{\textit{Doctor angelicus}}{Thomas Aquinas}| % \end{quote} % % Spaces change sorting. For example, the\Info{Particles} sort tag \texttt{De\textvisiblespace Soto} precedes \texttt{deal} due to the space therein. The sort tag \texttt{DeSoto} falls as expected between \texttt{derp} and \texttt{determinism}. % % \newpage % % German\Info{Collating\break sequences} \textsf{ä ö ü ß} map to English \textsf{ae oe ue ss}. Yet Norwegian \textsf{æ ø å} follow \textsf{z} in that order. Check a style guide regarding collating sequences, spaces, and sorting. This is where using \texttt{xindy} can be very helpful. See also Section~\ref{sec:NameParticles}. % % Additional examples\Info{Alternate\break formatting} starting with Section~\ref{sec:RealAltEx} deal with index sorting as it relates to alternate formatting and ``Continental'' practice. When sorting names that use alternate formatting or macros in name arguments, please ensure that the macros expand to the form desired in the index. If one is not using built-in macros related to alternate formatting, additional steps might be required when using \cmd{\PretagName} with names containing macros. % % \subsubsection{Sorting Initials} % \label{sec:IndexInitials} % % Sorting \Name*[J.D.]{Rockefeller, IV} |\Name*[J.D.]{Rockefeller, IV}| presents a problem that does not occur with \Name*[Clive Staples]{Lewis} |\Name*[Clive Staples]{Lewis}|. In the case of \Name*[J.D.]{Rockefeller, IV}[Jay], the initials will appear in the index, while with \Name*[Clive Staples]{Lewis}[C.S.], the longer names will appear in the index. % % \begin{InfoBox} % In order to sort the index consistently and properly, all names % should be sorted by their longer name forms, not their initials. % \end{InfoBox} % % In \textsf{nameauth} we have a specific way to do that once per name, and all the remaining names will be sorted as expected. Before we use a name like \Name[J.D.]{Rockefeller, IV}, preferably in the preamble, we use the following macro: % % \begin{quote}\small % |\PretagName[J.D.]{Rockefeller, IV}{Rockefeller, John D 4}| % \end{quote} % % Notice that we follow the form of the index entry, which will be ``\ShowIdxPageref*[J.D.]{Rockefeller, IV}''. We spell out the first forename, leave enough of the second forename for sorting, and turn the Roman numeral affix into an Arabic numeral so that it does not sort like alphabetic letters. For more examples of handling alternate forms of surnames see Sections~\ref{sec:NameMedieval}, \ref{sec:VarNames}, all subsections of Section~\ref{sec:AdvancedFormat}, and~\ref{sec:AdvCustomize}. % % \subsection{Index Tags} % \label{sec:IndexTag} % % Index info tags (``index tags'') are information added automatically to index page entries for names used with \textsf{nameauth} macros. % % \subsubsection{General Approach} % % \DescribeMacro{\TagName} % This macro creates a tag that persists until one changes it with \cmd{\TagName} or destroys it with \cmd{\UntagName}. % \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}: % % \begin{SyntaxBox} % \cmd{\TagName}\oarg{FNN}\marg{SNN|,| Affix}\oarg{Alternate}\marg{tag}\\ % \cmd{\UntagName}\oarg{FNN}\marg{SNN|,| Affix}\oarg{Alternate} % \end{SyntaxBox} % % All the indexing macros are keyed to the name patterns. \cmd{\PretagName} generates the leading sort key. \cmd{\TagName} and \cmd{\UntagName} affect the trailing content. The following graphic illustrates the ``segments'' of an index entry and the \textsf{nameauth} macros that affect the respective segments: % % \begin{center}\small\smallstretch % \begin{tabular}{r|l|l|l}\toprule % & & Naming macros\\ % & \cmd{\PretagName} & \cmd{\IndexName}\\ % \large\bfseries|\index{| & \large\bfseries|Aethelred 2@| & % \large\bfseries|Æthelred II| & \large\bfseries|, king}|\\ % & & & \cmd{\TagName}\\ % & & & \cmd{\UntagName}\\\bottomrule % \end{tabular} % \end{center} % % Tags created by \cmd{\TagName} can be \Info{Scholarly texts}helpful in the indexes of academic texts by adding dates, titles, etc. \cmd{\TagName} causes the \textsf{nameauth} indexing macros to append ``\texttt{,\textvisiblespace pope}'' to the index entries created below: % % \begin{VerbatimOut}{\jobname.tmp} % \TagName{Gregory, I}{, pope} % Pope \Name*{Gregory, I} was known as \Name{Gregory, I} % ``the Great''.\IndexRef{Gregory, the Great}{Gregory I} % \end{VerbatimOut} % % \begin{quote}\small % \vspace{3.5ex} % \PatInfo{\ShowPattern{Gregory, I}!TAG\break % \ShowPattern{Gregory, I}!MN\break % \ShowPattern{Gregory, the Great}!PN} % \vspace{-3.5ex} % \VerbatimInput[gobble=0]{\jobname.tmp} % % Pope \Name*{Gregory, I} was known as \Name{Gregory, I} % ``the Great''.\IndexRef{Gregory, the Great}{Gregory I} % \end{quote} % % \cmd{\TagName} works with all names that produce index page entries. It does not work with with cross-references that are produced by \cmd{\IndexRef}, \cmd{\AKA}, etc. % % Tags can hold different kinds of information, but they should not be overly verbose. They can include daggers, asterisks, and so on. For example, all fictional names in the index of this manual are tagged with \S. One must add any desired spaces to the start of the tag. % % \subsubsection[Identical Names]{Disambiguating Identical Names} % % 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: % % \begin{VerbatimOut}{\jobname.tmp} % \TagName[E.]{Humperdinck}{ (composer)} % This refers to the classical composer: % \Name[E.]{Humperdinck}[Engelbert]. % % \TagName[E.]{Humperdinck}{ (singer)} % This refers to the pop singer from the 60s and 70s: % \ForgetThis\Name[E.]{Humperdinck}[Engelbert]. % \end{VerbatimOut} % % \begin{quote}\small % \vspace{4ex} % \PatInfo{\ShowPattern[E.]{Humperdinck}!TAG\break % \ShowPattern[E.]{Humperdinck}!MN} % \vspace{-4ex} % \VerbatimInput[gobble=0]{\jobname.tmp} % % \TagName[E.]{Humperdinck}{ (composer)\string|hyperpage} % This refers to the classical composer: % \Name[E.]{Humperdinck}[Engelbert]. % % \TagName[E.]{Humperdinck}{ (singer)\string|hyperpage} % This refers to the pop singer from the 60s and 70s: % \ForgetThis\Name[E.]{Humperdinck}[Engelbert]. % \end{quote} % % \subsubsection[Special Tags]{Special Tags for Special Cases} % \label{sec:SpecialTag} % % \cmd{\TagName} can create ``special'' index entries for names with the general form below. These tags are compatible with \textsf{hyperref} used in normal \LaTeX\ documents.\footnote{This was implemented in v.3.3, based on the answer of \Name*[Heiko]{Oberdiek} to \href{https://tex.stackexchange.com/questions/201720/index-produces-invalid-idx-entry-with-manual-style-commaparse-hyperref} % {\bfseries this question}.} % When \texttt{\textbackslash}\meta{macro}\texttt{\#1\{\#1\}} exists and \meta{name args} are the arguments, one can use the form: % % \begin{SyntaxBox} % \cmd{\TagName}\meta{name args}\texttt{\{\textbar}\meta{macro}\texttt{\}} % \end{SyntaxBox} % % When \Warn\ using the \textsf{ltxdoc} class with \textsf{hypdoc}, as in this manual, \textsf{nameauth} does not create hyperlinked page entries. If one puts index tags in the || section of the \texttt{dtx} file, which will read the ``commented''part of the \texttt{dtx} file into a \texttt{document} environment, then one can use the following: % % \begin{quote}\small % \cmd{\TagName}\meta{name args}\texttt{\{\textbar hyperpage\}} % \end{quote} % % Things get more complicated in the ``commented'' part of the package documentation in this \texttt{dtx} file. There, thanks to \textsf{ltxdoc}, the vertical bar is active. Index tags in the documentation part must use the form: % % \begin{quote}\small % \cmd{\TagName}\meta{name args}\texttt{\{}\cmd{\string}\texttt{\textbar % hyperpage\}} % \end{quote} % % 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}\small % \begin{Verbatim} % \newcommand\Orphan[2]{#1(\hyperpage{#2})} % \TagName[Lost]{Name}{\,\S|Orphan{perdit}} % \Name[Lost]{Name} % \end{Verbatim} % % \Name[Lost]{Name}\\ % \texttt{idx} file: % |\indexentry{Name, Lost\,\S |\texttt % {\textbar}|Orphan{perdit}}{|\meta{page}|}|\\ % \texttt{ind} file: % |\item Name, Lost\,\S \pfill \Orphan{perdit}{|\meta{page}|}| % \end{quote} % % The \textsf{microtype}\Info{Manual breaks\break and entries} package and its \texttt{Spacing} environment may be the best solution to fix index entries and sub-entries that break badly across columns or pages. Yet we could add manual breaks after editing is complete. % % We must create a helper macro that takes an argument and adds a break after that argument. That is how macros like \cmd{\textbf} use implied page references in the index page entries, e.g.: \cmd{\index\{Doe, John\string|textbf\}}. % % Below we use \cmd{\newpage} to jump to a new column. See also the \textsf{multicol} and \textsf{idxlayout} packages, as well as classes like \textsf{memoir}. On line~1 we define the \cmd{\Endbreak} macro that will break the column after the end of an index entry. % % \begin{quote}\small % |\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: % % \begin{quote}\footnotesize\smallstretch % \begin{tabular}{p{0.055\textwidth}@{\ }p{0.4\textwidth}@{\ }l}\toprule % Page & Macro & Index Result\\ % \rowcolor{nagrey}10 & \cmd{\Name\{Some, Name\}}\dotfill \hbox{} & % Some Name, 10\\ % \rowcolor{nagrey} & \cmd{\index\{Topic\}}\dotfill \hbox{} & % Topic, 10\\ % 15 & \cmd{\Name\{Some, Name\}}\dotfill \hbox{} & Some Name, 10, 15\\ % & \cmd{\index\{Topic\}}\dotfill \hbox{} & Topic, 10, 15\\ % \rowcolor{nagrey}18 & \cmd{\TagName\{Some, Name\textbar EndBreak\}\%} & \\ % \rowcolor{nagrey} & \cmd{\Name\{Some, Name\}}\dotfill \hbox{} & % Some Name, 10, 15, 18\meta{break}\\ % \rowcolor{nagrey} & % \cmd{\index\{Topic\textbar EndBreak\}}\dotfill \hbox{} & % Topic, 10, 15, 18\meta{break}\\\bottomrule % \end{tabular} % \end{quote} % % We do not have to supply an argument to \cmd{\EndBreak} because, as with the font switching example above, the page reference is implied. % % We can intermix \textsf{nameauth} macros with manual index entries. We may need to look at the \texttt{idx} or \texttt{ind} files to craft matching entries on the page where the break occurs. Instead of using \cmd{\TagName}, we also can do this: % % \begin{quote}\footnotesize\smallstretch % \begin{tabular}{p{0.055\textwidth}@{\ }p{0.4\textwidth}@{\ }l}\toprule % Page & Macro & Index Result\\ % \rowcolor{nagrey} 18 & % \cmd{\SkipIndex}\cmd{\Name\{Some, Name\}\%}\hfill\hbox{} & \\ % \rowcolor{nagrey} & % \cmd{\index\{Some Name\textbar EndBreak\}}\dotfill \hbox{} & % Some Name, 10, 15, 18\meta{break}\\\bottomrule % \end{tabular} % \end{quote} % % Results for manual entries may vary, depending on what distribution of \LaTeX\ is being used and how old it is. Any name with active characters needs to be handled differently before 2018 than after 2018. All instances of \cmd{\index\{Some Name\textbar EndBreak\}} must fall on the same page. % % We do not\Warn\ recommend breaking an index entry in the middle. There are several web pages that discuss the topic of gobbling the commas that are generated when one wants to use macros to manipulate index entries. \href{https://tex.stackexchange.com/questions/86646/indexing-subentries-and-see-also}{\bfseries This page} and \href{https://tex.stackexchange.com/questions/231840/what-is-the-proper-use-of-several-seealso-in-the-same-index-entry-with-makeinde}{\bfseries this one} also share a number of viewpoints. A ``quick and dirty'' version corresponding to the \cmd{\EndBreak} macro above would be the one that follows: % % \begin{quote}\small % \begin{Verbatim} % \makeatletter % \newcommand*{\MidBreak}[1]{#1\newpage\@gobble} % \makeatother % \end{Verbatim} % \end{quote} % % Nevertheless, it is clear from some discussions that such macros can be rather fiddly at times and can produce unexpected results. One is advised to take caution when breaking index entries midway or otherwise modifying them in this manner. % % \subsection[Categories/Sub-entries]{Categories and Sub-entries} % \label{sec:CatSub} % % It is possible for indexes to have a structure of categories and sub-entries similar to the example outline below: % % \begin{itemize} % \item[] \meta{category 1} % \begin{itemize} % \item[] \meta{name entry} % \begin{itemize} % \item[] \meta{name sub-entry 1} % \item[] \meta{name sub-entry 2}\dots % \end{itemize} % \item[] \meta{name entry}\dots % \end{itemize} % \item[] \meta{category 2}\dots % \end{itemize} % % In order to get names in \textsf{nameauth} to work with this structure, one must make use of both \cmd{\PretagName} and \cmd{\TagName}. For example, to sort a name under \meta{category}, one must use, e.g.: % % \begin{SyntaxBox} % \cmd{\PretagName[}\meta{FNN}\texttt{]\{}\meta{SNN}\texttt % {\}\{}\meta{category 1}\texttt{!}\meta{SNN}\texttt % {, }\meta{FNN}\texttt{\}} % \end{SyntaxBox} % % Whenever one wants to generate a sub-entry for a name, one can use \cmd{\TagName} to create that sub-entry when needed via, e.g.: % % \begin{SyntaxBox} % \cmd{\TagName[}\meta{FNN}\texttt{]\{}\meta{SNN}\texttt % {\}\{!}\meta{name sub-entry 1}\texttt{\}} % \end{SyntaxBox} % % One is not restricted to Western or non-Western name arguments; the boxes above are meant just to show the basic tag formats. % % One could use \Warn\cmd{\TagName} to change to another sub-entry or the default tag as needed, or use \cmd{\UntagName} to remove the tag. If a sub-entry contains a cross-reference via \cmd{\IndexRef}, it is necessary to follow that with \cmd{\IncludeName*} to permit any further page references in other sub-entries or the main name entry. Below we demonstrate how one would implement sub-entries using index tags in a normal \LaTeX\ document. We cannot show categories when using \texttt{gind.ist}. % % Categories higher than names are handled by \cmd{\PretagName}. Categories lower in the hierarchy are handled by \cmd{\TagName}. It is best practice to have three or less levels of categories in an index. Two levels are more common. Using such levels also depends on the index style and formatting files. % \JustIndex\Wash \JustIndex\Ike % % \ifdefined\NameauthDoTestFiles \edef\NameauthTestFile{test07_02.tex}\else % \edef\NameauthTestFile{\jobname.tmp}\fi % % \begin{VerbatimOut}{\NameauthTestFile} % \documentclass{article} % \input{compat.tex} % Included with nameauth; needed only if % % compiling on multiple TeX distros or LaTeX engines. % \usepackage{makeidx} % \usepackage{nameauth} % \makeindex % \usepackage[a6paper,landscape,left=1cm,right=1cm]{geometry} % % \newcommand*{\EndBreak}[1]{#1\newpage} % % % Sort these names under: US Presidents. % \PretagName[George]{Washington}{US Presidents!Washington, George} % \PretagName[Abraham]{Lincoln}{US Presidents!Lincoln, Abraham} % % % Sort these names under: Philosophers. % \PretagName{Aristotle}{Philosophers!Aristotle} % \PretagName{Plato}{Philosophers!Plato} % % % Sort these names under: Black Americans, famous. % \PretagName[Frederick]{Douglass} % {Black Americans, famous!Douglass, Frederick} % \PretagName[Martin Luther]{King, Jr.} % {Black Americans, famous!King, Martin Luther, Jr.} % % % Sort these names under: Europeans, historical. % \PretagName{\AE thelred, II}{Europeans, historical!Aethelred 2} % \PretagName[Hernando]{de Soto} % {Europeans, historical!de Soto, Hernando} % % % This is not a sub-category. % \TagName[George S.]{Patton, Jr.}{, general} % % \begin{nameauth} % \< Wash & George & Washington & > % \< Aris & & Aristotle & > % \< Plato & & Plato & > % \< Aeth & & \AE thelred, II & > % \< Sun & & Sun, Yat-sen & > % \< Linc & Abraham & Lincoln & > % \< MLK & Martin Luther & King, Jr. & > % \< Soto & Hernando & de Soto & > % \< Goethe & J.W. von & Goethe & > % \< Patton & George S. & Patton, Jr. & > % \< Ike & Dwight D. & Eisenhower & > % \end{nameauth} % % \begin{document} % \small % % \section{Famous Black Americans} % % \Name[Frederick]{Douglass} rose to eminence by sheer force of % character and talents that neither slavery nor caste % proscription could crush. Circumstances made % \Name[Frederick]{Douglass} a slave, but they could not prevent % him from becoming a freeman and a leader among mankind.\\ % % We also celebrate \MLK, then \MLK. % % \section{Patres Patriae} % % We mention President \Wash; again, \Wash. % Family and close friends called him \SWash.\\ % % \TagName[George]{Washington}{!as general} % We can reminisce about \LWash[General]. % \UntagName[George]{Washington} % % When speaking of \Linc, we can refer to \LLinc[Abe]. % % \section{Philosophers} % % Among philosophers we consider \Plato\ and \Aris. % % \section{Historical Figures} % % \TagName{Sun, Yat-sen}{|EndBreak} % We ponder about \Aeth, then \Aeth. % We speak of \Sun, then \Sun. % We note \Soto, then just \Soto. % \CapThis\Soto{} starts a sentence. % % \section{Further Discussion} % % \TagName[George]{Washington}{!as general} % \TagName[Dwight D.]{Eisenhower}{!as general} % \LWash, \LPatton, and \LIke\ were high-ranking generals.\\ % % \TagName[Dwight D.]{Eisenhower}{!as president} % \UntagName[George]{Washington} % \Wash\ and \Ike\ also were US presidents. % % % Instead of pre-tagging Ike we do the following: % \index{US Presidents!other|see{Eisenhower, Dwight D., president}} % % \small % \printindex % \end{document} % \end{VerbatimOut} % % \begin{quote}\small % \VerbatimInput[gobble=0]{\NameauthTestFile} % \end{quote} % % Below we show only the index, which is page three of the document. % A few notable features include: % % \begin{itemize} % \item \Patton\ uses a regular index tag instead of a subcategory. % If one cannot use a subcategory due to layout constraints, regular % index tags are a good substitute. % \item \Ike\ illustrates multiple subcategories for a name. A % cross-reference from a sub-entry of US presidents points to him. % \item \Wash\ illustrates having both a super-category and a subcategory. % \item \Ike, \Patton, and \Sun\ are not sorted under categories. The % other names are sorted under categories. % \end{itemize}\smallskip % \JustIndex\MLK \JustIndex\Doug \JustIndex\Aeth \JustIndex\Soto % \JustIndex\Aris \JustIndex\Plato \JustIndex\Linc % % \begin{tcolorbox}[colback=white] % \IfFileExists{cat01.pdf}{\includegraphics[scale=0.85]{cat01.pdf}} % {\hbox{\vbox to 8cm{\hbox{\hfill}}}} % \end{tcolorbox} % \JustIndex\Wash \JustIndex\Ike % \medskip % % \IndexWarnTerse % % \ReturnLink % % \begin{Quote}{\Name[Publius]{Vegetius Renatus}, \textit{De re militari}} % Igitur qui desiderat pacem, praeparet bellum.\\ % (Accordingly, the person who would desire peace prepares for war.) % \end{Quote} % % \newpage % % \section{Name Data Tags} % \label{sec:DataTags} % % \DescribeMacro{\NameAddInfo} % All valid names in \textsf{nameauth} can have data tags; no restrictions exist. Unlike index tags, name data tags are not printed automatically with every name managed by \textsf{nameauth}. Sections~\ref{sec:NameTests} and~\ref{sec:DataTagHooks} have more examples. The macro is \cmd{\long}, allowing for some complexity in the \meta{tag} argument: % % \begin{SyntaxBox} % \cmd{\NameAddInfo}\oarg{FNN}\marg{SNN|,| Affix}\oarg{Alternate}\marg{tag} % \end{SyntaxBox} % % \vspace{2ex} % \PatInfo{\ShowPattern[George]{Washington}!DB\break % \ShowPattern[George]{Washington}!MN} % \vspace{-2ex} % For example, |\NameAddInfo[George]{Washington}{(1732--99)}| \NameAddInfo[George]{Washington}{(1732--99)} makes a data tag but does not print whenever \Wash\ \cmd{\Wash} is used. The data tag is a hidden macro that needs to be displayed using another helper macro keyed to that name, which we discuss below.\medskip % % \DescribeMacro{\NameQueryInfo} % To print the data tag macro associated with a name, we use \cmd{\NameQueryInfo}, a helper macro that uses the name arguments to display the hidden macro associated with that name in the name info data set: % % \begin{SyntaxBox} % \cmd{\NameQueryInfo}\oarg{FNN}\marg{SNN|,| Affix}\oarg{Alternate} % \end{SyntaxBox} % % Since we already created a data tag for \LWash, we will retrieve that data now: \cmd{\NameQueryInfo[George]\{Washington\}} expands to \NameQueryInfo[George]{Washington}. Of course, it may seem tedious to retrieve this information by hand. In Section~\ref{sec:DataTagHooks} and thereafter we show how one can automate the retrieval of data tags using formatting hooks, Yet therein also lies a caution: % % \begin{InfoBox}[Caution for Using \cmd{\noexpand}] % When using a formatting hook definition based on the recommended template (Section~\ref{sec:DataTemp}), one can use \cmd{\noexpand} in arguments for \cmd{\NameAddInfo}, \cmd{\NameQueryInfo}, and \cmd{\NameClearInfo} without restriction.\medskip % % When using designs based on older templates, using \cmd{\noexpand} may cause \cmd{\NameQueryInfo} to print nothing if one uses the basic interface. Using the quick interface will work as expected. % \end{InfoBox} % % One can insert a space at the start of a data tag; use signs like asterisks, daggers, and the like; and even create footnotes, such as the source for footnote \addtocounter{footnote}{1}\arabic{footnote}\addtocounter{footnote}{-1} on the following page: % % \begin{VerbatimOut}{\jobname.tmp} % \NameAddInfo[Ulysses S.]{Grant} % {eighteenth US president (1869--1877)} % \NameAddInfo[Schuyler]{Colfax} % {\footnote{\Name[Schuyler]{Colfax} was the seventeenth US % vice-president during the first term (1869--73) of % \Name*[Ulysses S.]{Grant}, \NameQueryInfo[Ulysses S.]{Grant}.}} % % Remember \Name[Schuyler]{Colfax}?\NameQueryInfo[Schuyler]{Colfax} % Derived from the same origin as ``scholar'', this name can occur % as ``Skylar'' for girls and ``Skyler'' for boys. % \end{VerbatimOut} % % \begin{quote}\small % \vspace{3.5ex} % \PatInfo{\ShowPattern[George]{Washington}!DB\break % \ShowPattern[Ulysses S.]{Grant}!DB\break % \ShowPattern[Schuyler]{Colfax}!DB\break % \ShowPattern[Schuyler]{Colfax}!MN\break % \ShowPattern[Ulysses S.]{Grant}!MN} % \vspace{-3.5ex} % \VerbatimInput[gobble=0]{\jobname.tmp} % % \input{\jobname.tmp} % \end{quote} % % The previous\Warn{} example cannot be used in a formatting hook (Section~\ref{sec:DataTagHooks}). Within the formatting hooks, one is in a ``locked path'' that will not permit the ``re-entrant'' call to a naming macro. This is necessary to prevent a stack overflow. Were this example called in a formatting hook, \Name*[Ulysses S.]{Grant} would not print, although the data tag for \Name[Ulysses S.]{Grant} would print because it is called separately. % % One can\Warn{} nest data tags and have them call each other. Therefore, one must protect against a stack overflow by using Boolean flags and conditional statements. In the minimal working example below, \cmd{\NameQueryInfo} calls a tag that sets a Boolean flag true, which causes the \emph{other} tag called later to stop the potential for recursion and exit. % % \begin{VerbatimOut}{\jobname.tmp} % \newif\ifA % \newif\ifB % \NameAddInfo{A} % {\Atrue A \ifB Stop \else \NameQueryInfo{B} \fi \Afalse} % \NameAddInfo{B} % {\Btrue B \ifA Stop \else \NameQueryInfo{A} \fi \Bfalse} % \begin{itemize} % \item \NameQueryInfo{A} % \item \NameQueryInfo{B} % \end{itemize} % \end{VerbatimOut} % % \begin{quote}\small % \VerbatimInput[gobble=0]{\jobname.tmp} % % \input{\jobname.tmp} % \end{quote} % % \DescribeMacro{\NameClearInfo} % \cmd{\NameAddInfo} will replace one data tag with another data tag, but it does not delete a data tag. That is the role of \cmd{\NameClearInfo}. The syntax is: % % \begin{SyntaxBox} % \cmd{\NameClearInfo}\oarg{FNN}\marg{SNN|,| Affix}\oarg{Alternate} % \end{SyntaxBox} % % We now revisit \LWash\ and his associated data tag. \PatInfo{\ShowPattern[George]{Washington}!DB} % % \begin{VerbatimOut}{\jobname.tmp} % The data tag is: \fbox{\NameQueryInfo[George]{Washington}}\quad % Clearing data.\NameClearInfo[George]{Washington}\quad % The data tag is empty: \fbox{\NameQueryInfo[George]{Washington}} % \end{VerbatimOut} % % \begin{quote}\small % \VerbatimInput[gobble=0]{\jobname.tmp} % % \input{\jobname.tmp} % \end{quote} % % \ReturnLink % % \newpage % % \section[Formatting and Decisions]{Basic Formatting and Name Decisions} % \label{sec:FormatChoice} % % Since both syntactic name forms and formatting interact heavily with the presence and absence of name patterns, we include them together in one section. % % \subsection{Basic Formatting} % \label{sec:Formatting} % % 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: % % \begingroup % \renewcommand\NamesFormat{} % \renewcommand\MainNameHook{} % \renewcommand\FrontNamesFormat{} % \renewcommand\FrontNameHook{} % \begin{tcolorbox}[colframe=naslate,colback=white, % adjusted title={\hfil Syntactic Changes;^^A % No Formatting/Post-Processing}]\centering % \begin{tabular}{llll}\toprule % First & Later & First name & Later name\\\midrule % \cmd{\Patton} & \cmd{\Patton} & \ForgetThis\Patton & \Patton\\ % \cmd{\LPatton} & \cmd{\LPatton} & \ForgetThis\LPatton & % \LPatton\\ % \cmd{\SPatton} & \cmd{\SPatton} & \ForgetThis\SPatton & % \SPatton\\\midrule % \cmd{\Yamt} & \cmd{\Yamt} & \ForgetThis\Yamt & \Yamt\\ % \cmd{\LYamt} & \cmd{\LYamt} & \ForgetThis\LYamt & \LYamt\\ % \cmd{\SYamt} & \cmd{\SYamt} & \ForgetThis\SYamt & \SYamt\\\bottomrule % \end{tabular} % \end{tcolorbox} % \endgroup % % We can add formatting to these syntactic changes. In its basic form, formatting is typographic post-processing. In its advanced form, formatting locally affects also the syntactic forms of names while leaving index entries undisturbed. % % Many books are structured with front matter that includes a table of contents, foreword, introductory material or survey material, and other instructive content that is not part of the main matter. The \textsf{nameauth} package has separate syntax and formatting system for front matter (\texttt{!NF}) and main matter (\texttt{!MN}). These formatting systems are linked to the existence of a name control pattern. % % \begin{itemize} % \item Name first use % \begin{itemize} % \item No name control sequence exists. % \item A name is printed with its long form (default). % \item The ``first-use'' formatting hook is used (default). % \item After the name is printed, a name control sequence is created. % \end{itemize} % \item Name subsequent use % \begin{itemize} % \item A name control sequence 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}).\medskip % % \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. % % Especially with the macros that deal with formatting, the naming scheme is unfortunate because it involved some groping in the dark regarding the concepts.\medskip % % These\Info{\cmd{\global}} two macros can be used explicitly as a pair or singly within an explicit local scope. Use \cmd{\global} to force a global effect.\medskip % % \DescribeMacro{\NamesFormat} % The main-matter system uses \cmd{\NamesFormat} to post-process first occurrences of names and % \DescribeMacro{\MainNameHook} % \cmd{\MainNameHook} for subsequent uses. The front-matter system uses \cmd{\FrontNamesFormat} % \DescribeMacro{\FrontNamesFormat} % for first uses and \cmd{\FrontNameHook} for subsequent uses. The \texttt{alwaysformat} % \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.} % Section~\ref{sec:NamePatterns} shows how name control sequences are keyed either to the main-matter system or to the front-matter system. The two formatting systems are distinct, useful for separate document elements. We color-code them and ``forget'' any previous name uses: \medskip % % \ForgetName[Rudolph]{Carnap} % \vspace{4ex} % \PatInfo{\textrm{front-matter}\hfill\break % \ShowPattern[Rudolph]{Carnap}!NF\break % \ShowPattern[Nicolas]{Malebranche}!NF\break % \textrm{main-matter}\hfill\break % \ShowPattern[Rudolph]{Carnap}!MN\break % \ShowPattern[Nicolas]{Malebranche}!MN} % \vspace{-4ex} % \begin{tcolorbox}[colframe=red,colback=white, % adjusted title={\hfil Front-matter system: \cmd{\NamesInactive}}] % \NamesInactive % \begin{tabular}{ll} % |\Name[Rudolph]{Carnap}| & \Name[Rudolph]{Carnap}\\ % |\Name[Rudolph]{Carnap}| & \Name[Rudolph]{Carnap}\\ % |\Name[Nicolas]{Malebranche}| & \Name[Nicolas]{Malebranche}\\ % |\Name[Nicolas]{Malebranche}| & \Name[Nicolas]{Malebranche}\\ % \end{tabular} % \end{tcolorbox} % \medskip % % \begin{tcolorbox}[colframe=blue,colback=white, % adjusted title={\hfil Main-matter system: \cmd{\NamesActive}}] % \NamesActive % \begin{tabular}{ll} % |\Name[Rudolph]{Carnap}| & \Name[Rudolph]{Carnap}\\ % |\Name[Rudolph]{Carnap}| & \Name[Rudolph]{Carnap}\\ % |\Name[Nicolas]{Malebranche}| & \Name[Nicolas]{Malebranche}\\ % |\Name[Nicolas]{Malebranche}| & \Name[Nicolas]{Malebranche}\\ % \end{tabular} % \end{tcolorbox} % \medskip % % We used the \textsf{xcolor} package with the following macros: % \begin{quote}\small % \begin{Verbatim} % \renewcommand*\FrontNamesFormat[1]{\color{red}\sffamily #1} % \renewcommand*\FrontNameHook[1]{\color{darkgray}\sffamily #1} % \renewcommand*\NamesFormat[1]{\color{blue}\sffamily #1} % \renewcommand*\MainNameHook[1]{\sffamily #1} % \end{Verbatim} % \end{quote} % % \DescribeMacro{\ForceName} % We show examples of \cmd{\ForceName} in Sections~\ref{sec:NameControl}, \ref{sec:DataTagHooks}, and~\ref{sec:AKA}. Use this prefix macro to force ``first use'' formatting for the next \cmd{\Name}, etc., but without deleting any name control sequences. Thus: % % \begin{quote}\small % \hphantom{\cmd{\ForceName}}^^A % \PatInfo{\ShowPattern[Rudolph]{Carnap}!MN}^^A % \cmd{\Name[Rudolph]\{Carnap\}} \Name[Rudolph]{Carnap}\\ % \cmd{\ForceName}\cmd{\Name[Rudolph]\{Carnap\}} % \ForceName\Name[Rudolph]{Carnap} % \end{quote} % % Below\Info{\texttt{alwaysformat}} we simulate \texttt{alwaysformat} via package internals: % % \makeatletter\@nameauth@AlwaysFormattrue\makeatother% % \ForgetName[M.T.]{Cicero}\ForgetName{Elizabeth, I}% % \begin{itemize} % \item Front matter: \NamesInactive \Name[Albert]{Einstein}, % \Name[Albert]{Einstein}; \Name{Confucius}, \Name{Confucius}.\\ % Patterns: \texttt{\ShowPattern[Albert]{Einstein}!NF % \ShowPattern{Confucius}!NF} % \item Main matter: \NamesActive \Name[M.T.]{Cicero}, \Name[M.T.]{Cicero}; % \Name{Elizabeth, I}, \Name{Elizabeth, I}.\\ % Patterns: \texttt{\ShowPattern[M.T.]{Cicero}!MN % \ShowPattern{Elizabeth, I}!MN} % \end{itemize} % \makeatletter\@nameauth@AlwaysFormatfalse\makeatother % % \newpage % % The internal name parser\Info{Hook caveats} determines what syntactic name elements exist and how they are constituted. It passes that information to macros that determine the form of non-Western or Western names to be displayed. They in turn call the format hook dispatcher for post-processing, which calls the formatting hooks using the pattern: % % \begin{quote}\small % \cmd{\bgroup}\meta{Hook}\texttt{\{\#1\}}\cmd{\egroup}. % \end{quote} % % One can create formatting hooks that take either no argument or one argument. Since the formatting hooks are already defined, one must not use \cmd{\newcommand} to create new hooks. Instead, use \cmd{\renewcommand} e.g.: % % \begin{quote}\small % \cmd{\renewcommand*}\cmd{\NamesFormat\{}\meta{content}\texttt{\}}\\ % \cmd{\renewcommand*}\cmd{\NamesFormat[1]\{}\meta{content}\texttt{\}} % \end{quote} % % A hook that takes one argument can use, change, or discard it and invoke \cmd{\NameParser} (Section~\ref{sec:SpecialUses}). Due to package design using local scope, both the following achieve exactly the same effect: % % \begin{quote}\small % \cmd{\renewcommand*}\cmd{\NamesFormat\{}\cmd{\itshape}\texttt{\}}\\ % \cmd{\renewcommand*}\cmd{\NamesFormat\{}\cmd{\textit}\texttt{\}} % \end{quote} % % \subsection{Application: Footnotes} % % The independent systems of names work with footnotes. Names in the body text, such as \ForgetThis\Harnack\ (later ennobled to \LHarnack[Adolf von]), normally affect name forms in the footnotes.\footnote{We have \Harnack\ from \cmd{\Harnack} instead of \ForgetThis\Harnack.} % In footnote \arabic{footnote} \cmd{\MainNameHook} is called instead of \cmd{\NamesFormat} because \Harnack\ already had occurred above. We can use the front-matter system to change that: % % \begin{VerbatimOut}{\jobname.tmp} % \makeatletter % \let\@oldfntext\@makefntext % \long\def\@makefntext#1{\NamesInactive\@oldfntext{#1}\NamesActive} % \makeatother % \end{VerbatimOut} % % \begin{quote}\small % \vspace{4ex} % \PatInfo{\ShowPattern[Adolf]{Harnack}!MN\break % \ShowPattern[Adolf]{Harnack}!NF} % \vspace{-4ex} % \VerbatimInput[gobble=0]{\jobname.tmp} % \end{quote} % \input{\jobname.tmp} % % When we create another footnote, we see very different results.\footnote{We have \Harnack\ from \cmd{\Harnack}, then \Harnack.} % Footnote \arabic{footnote} shows the first use of a name because it is the first use in the front-matter system. One can synchronize the two systems with \cmd{\ForgetThis} and \cmd{\SubvertThis} (Section~\ref{sec:NameControl}). Below we revert footnotes with: % % \begin{VerbatimOut}{\jobname.tmp} % \makeatletter % \let\@makefntext\@oldfntext % \makeatother % \end{VerbatimOut} % % \begin{quote}\small % \VerbatimInput[gobble=0]{\jobname.tmp} % \end{quote} % \input{\jobname.tmp} % % \begin{Quote}{\Name[Hubert H.]{Humphrey}, speech (26 March 1966)} % In real life, unlike in Shakespeare, the sweetness of the rose depends upon the name it bears. Things are not only what they are. They are, in very important respects, what they seem to be. % \end{Quote} % % \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}).\medskip % % \DescribeMacro{\ForgetName} % This macro takes the same arguments as \cmd{\Name}, but it prints no output. It ``forgets'' a name, forcing a ``pre-first use'' state. The next time a naming macro makes reference to the name, it will display as if the name did not yet exist: % % \begin{SyntaxBox} % \cmd{\ForgetName}\oarg{FNN}\marg{SNN|,| 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 references.\medskip % % \DescribeMacro{\ForgetThis} % This prefix macro causes the next instance of a naming macro or shorthand to ``forget'' a name before printing it. After knowing |\Einstein| ``\Einstein'' we forget him and again have a first reference: |\ForgetThis\Einstein| ``\ForgetThis\Einstein''. \cmd{\ForgetThis} no longer affects the index unless one uses the \texttt{oldreset} option.\medskip % % \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}: % % \begin{SyntaxBox} % \cmd{\SubvertName}\oarg{FNN}\marg{SNN|,| 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. % % \begin{InfoBox} % \centering We still advise one to avoid using \cmd{\ForgetThis} and \cmd{\SubvertThis}\\ before any naming macro that produces no output in the text. % \end{InfoBox} % % \DescribeMacro{\LocalNames} % By default, \cmd{\ForgetName}, \cmd{\SubvertName}, \cmd{\ForgetThis}, and \cmd{\SubvertThis} are not limited either by scope or by the active naming system. % \DescribeMacro{\GlobalNames} % \cmd{\LocalNames} restricts the effects of these macros to the current naming system, but not to scope. \cmd{\GlobalNames} restores the default behavior that affects both systems. Both macros always have global scope. % % To see how these two macros work, in the following example we define a macro that reports whether or not |\Name[Charlie]{Chaplin}| exists. This macro gives four possible results: the name exists in the main matter, it exists in the front matter, it exists in both systems, or it does not exist (see Section~\ref{sec:NameTests}): % % \begin{VerbatimOut}{\jobname.tmp} % \def\CheckChuck{{\bfseries\IfFrontName[Charlie]{Chaplin} % {\IfMainName[Charlie]{Chaplin}{both}{front}} % {\IfMainName[Charlie]{Chaplin}{main}{none}}}} % \end{VerbatimOut} % % \begin{quote}\small % \VerbatimInput[gobble=0]{\jobname.tmp} % \end{quote} % \input{\jobname.tmp} % % \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} % % \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} % % \item Switch to the ``front-matter'' system and create a name. % \PatInfo{\ShowPattern[Charlie]{Chaplin}!NF} % Ifone is within a group or local scope, one may have to add % \cmd{\global} to \cmd{\NamesInactive}: % \begin{itemize}[rightmargin=2\leftmargin] % \item[] |\global\NamesInactive|\global\NamesInactive % \item[] |\Name[Charlie]{Chaplin}|\dotfill \Name[Charlie]{Chaplin} % \item[] |\CheckChuck|\dotfill \CheckChuck % \end{itemize} % % \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} % % \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} % % \item Next ``subvert'' the front-matter name to ``remember'' it again. % Then switch to main matter: % \begin{itemize}[rightmargin=2\leftmargin] % \item[] |\Subvert\Name[Charlie]{Chaplin}|\SubvertName[Charlie]{Chaplin} % \item[] |\CheckChuck|\dotfill \CheckChuck % \item[] |\global\NamesActive|\global\NamesActive % \end{itemize} % % \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} % % \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} % % \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} % % \subsection{Formatting and Decisions} % % We pull together information on name forms and formatting, focusing on what happens in one naming system only, since the two systems are independent. % % \begin{itemize}[leftmargin=3cm]\small % \item[First Use:] \cmd{\Bailey} \dotfill \ForgetThis\Bailey\\ % \cmd{\LBailey} \dotfill \ForgetThis\LBailey\\ % \cmd{\SBailey} \dotfill \ForgetThis\SBailey\\ % Name control pattern created with text output. % Index state 2, 4, or 6 (Section~\ref{sec:RuleStates}). % Name form: long. First-use hooks. % % \item[Later Use:] \cmd{\Bailey} \dotfill \Bailey\\ % \cmd{\LBailey} \dotfill \LBailey\\ % \cmd{\SBailey} \dotfill \SBailey\\ % No change to name pattern. Index state 2, 4, or 6. % Name form: short. Subsequent-use hooks. % % \item[Forgotten:] \cmd{\ForgetName[Betsey]\{Bailey\}} \dotfill % (no output)\ForgetName[Betsey]{Bailey}\\ % Name pattern deleted. Index state 1, 3, or 5 % (Section~\ref{sec:RuleStates}). % Next use usually will be a first use, e.g.: \Bailey. % % \item[Subverted:] \cmd{\SubvertName[Betsey]\{Bailey\}} \dotfill % (no output)\SubvertName[Betsey]{Bailey}\\ % Name pattern created. Index state 2, 4, or 6. % Next use usually will be a later use, e.g.: \Bailey, \LBailey, \SBailey. % % \item[\cmd{\ForgetThis}:] % \cmd{\ForgetThis}\cmd{\Bailey} \dotfill \ForgetThis\Bailey\\ % \cmd{\ForgetThis}\cmd{\LBailey} \dotfill \ForgetThis\LBailey\\ % \cmd{\ForgetThis}\cmd{\SBailey} \dotfill \ForgetThis\SBailey\\ % Name pattern deleted, then created again. Index state 2, 4, or 6. % Name form and format: same as first use above. Next use usually % will be a later use, e.g.: \Bailey, \LBailey, \SBailey. % % \item[\cmd{\SubvertThis}:] % \cmd{\SubvertThis}\cmd{\Bailey} \dotfill \SubvertThis\Bailey\\ % \cmd{\SubvertThis}\cmd{\LBailey} \dotfill \SubvertThis\LBailey\\ % \cmd{\SubvertThis}\cmd{\SBailey} \dotfill \SubvertThis\SBailey\\ % Name pattern created. Index state 2, 4, or 6. % Name form and format: same as later use above. Next use usually % will be a later use, e.g.: \Bailey, \LBailey, \SBailey. % % \item[Format First:] % \cmd{\ForceName}\cmd{\Bailey} \dotfill \ForceName\Bailey\\ % \cmd{\ForceName}\cmd{\LBailey} \dotfill \ForceName\LBailey\\ % \cmd{\ForceName}\cmd{\SBailey} \dotfill \ForceName\SBailey\\ % No change to name pattern. Index state 2, 4, or 6. % Name form: short or long. Name format: First-use hooks. % \end{itemize} % % \AltFormatActive % \begin{Quote}{\ForgetThis\Luth\break % \hbox{}\hfill \textit{Von der Freiheit eines Christenmenschen} % (1520)\footnote{In several cases (e.g., here) when one uses small % caps, harmless font substitution warnings result.}} % Eyn Chriſten menſch iſt eyn freyer herr / % u\raise 0.2ex\hbox{\kern -1.1ex\textsuperscript{e}\kern 1pt}ber alle % ding / und niemande unterthan. Eyn Chriſten menſch iſt eyn dienſtpar % knecht aller ding und yderman unterthan. % % (A Christian is a free lord, above all things, and subject to no one. % A Christian is a willing servant of all things and is subject to % everyone.) % \end{Quote} % \AltFormatInactive % % \newpage % % \subsection{Testing Name Decisions} % \label{sec:NameTests} % % Since name patterns are control sequences like macros, we can test for their existence. This can relate names to each other dynamically throughout a document. % % \subsubsection{Testing Macros} % % The macros in this section test for the presence or absence of a name, then expand to a result based on the outcome of the test.\medskip % % \DescribeMacro{\GlobalNameTest} % The default behavior encapsulates the decision paths in a local scope, insulating any changes therein. % \DescribeMacro{\LocalNameTest} % If this is not desired, use the \texttt{globaltest} option or \cmd{\GlobalNameTest}. \cmd{\LocalNameTest} will re-enable the default. These commands affect assignment statements in test paths. By default, one must explicitly use \cmd{\global} when desired. See also the examples below.\medskip % % \DescribeMacro{\IfMainName} % In order to test whether or not a ``main matter'' name control sequence exists, use this long macro that can accommodate paragraph breaks: % % \begin{SyntaxBox} % \cmd{\IfMainName}\oarg{FNN}\marg{SNN|,| Affix}\oarg{Alternate}^^A % \marg{yes}\marg{no} % \end{SyntaxBox} % % For example we have not encountered |\Name[Bob]{Hope}| yet. Using \cmd{\IndexName} does not affect the tests in this section. We could do the following test that will reflect whether or not the name is present in the text: % % \begin{VerbatimOut}{\jobname.tmp} % I heard someone say: \IfMainName[Bob]{Hope} % {Bob here!} % {No Bob here.}\IndexName[Bob]{Hope} % \end{VerbatimOut} % % \begin{quote}\small % \VerbatimInput[gobble=0]{\jobname.tmp} % % \input{\jobname.tmp} % \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: % % \begin{VerbatimOut}{\jobname.tmp} % \GlobalNameTest % \def\msg{We are unsure about \LEliz} % % \IfMainName{Elizabeth,I} % {\def\msg{We really do know of \LEliz}} % {\def\msg{We do not know of \LEliz}} % % \parbox{0.4\textwidth}{\msg} (\cmd{\GlobalNameTest}). % % \LocalNameTest % \def\msg{We are unsure about \LEliz} % % \IfMainName{Elizabeth,I} % {\def\msg{We really do know of \LEliz}} % {\def\msg{We do not know of \LEliz}} % % \parbox{0.4\textwidth}{\msg} (\cmd{\LocalNameTest}). % \end{VerbatimOut} % % \begin{quote}\small % \VerbatimInput[gobble=0]{\jobname.tmp} % % \input{\jobname.tmp} % \end{quote} % % \newpage % % \DescribeMacro{\IfFrontName} % In order to test whether or not a ``front matter'' name pattern exists, use this long macro that can accommodate paragraph breaks. Its syntax is: % % \begin{SyntaxBox} % \cmd{\IfFrontName}\oarg{FNN}\marg{SNN|,| Affix}\oarg{Alternate}^^A % \marg{yes}\marg{no} % \end{SyntaxBox} % % This macro works just like \cmd{\IfMainName}, except using the ``front matter'' name control sequences as the test subject. These testing macros prove their worth especially through combination. For example, we do a test based on Section~\ref{sec:Formatting}. % % \begin{VerbatimOut}{\jobname.tmp} % \IfFrontName[Rudolph]{Carnap} % {\IfMainName[Rudolph]{Carnap} % {\Name[Rudolph]{Carnap} is in both main- and front-matter text.} % {\Name[Rudolph]{Carnap} is only in front-matter text.}} % {\IfMainName[Rudolph]{Carnap} % {\Name[Rudolph]{Carnap} is only in main-matter text.} % {\Name[Rudolph]{Carnap} has not been mentioned.}} % \end{VerbatimOut} % % \begin{quote}\small % \VerbatimInput[gobble=0]{\jobname.tmp} % % \input{\jobname.tmp} % \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 % \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}). % % \begin{itemize} % \item Excluded control sequences (the \meta{excl} path) expand % to the value of \cmd{\@nameauth@Exclude}. % \item Regular cross-references (the \meta{y} path) do not expand % to that value. At present, they are empty. % \item \cmd{\ExcludeName} creates excluded xrefs. \cmd{\IncludeName} % destroys them. % \item Regular xrefs are created by \cmd{\IndexRef}, \cmd{\AKA}, % \cmd{\PName} and their starred forms. Regular xrefs are destroyed % by \cmd{\IncludeName*}. % \end{itemize} % % Based on the known facts above, below we offer some examples: % % \begin{enumerate} % \item In\PatInfo{\ShowPattern[Jesse]{Ventura}!MN\break % \ShowPattern[James]{Janos}!PN\break % \ShowPattern[James]{Janos}!MN} % the text we first create a reference to former pro-wrestler and % Minnesota governor \Name[Jesse]{Ventura}, |\Name[Jesse]{Ventura}|. % \item We establish his lesser-known legal name as an alias: % ``\IndexRef[James]{Janos}{Ventura, Jesse}\Name[James]{Janos}'',\\ % |\IndexRef[James]{Janos}{Ventura,|\,|Jesse}\Name[James]{Janos}|. % \item We get the result: % ``\IfAKA[James]{Janos} % {\Name*[Jesse]{Ventura} is a stage name} % {\Name*[Jesse]{Ventura} is a regular name} % {}''. % If we do not use \cmd{\ExcludeName}, we can leave the % \meta{excl} branch empty: % \end{enumerate} % % \begin{quote}\small % \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}\small % \begin{Verbatim} % \IfAKA[FNN]{SNN, Affix}[Alternate] % {% % % yes; it is an xref % } % {% % % no, it is a name % \IfFrontName[FNN]{SNN, Affix}[Alternate] % {% % % yes, it is in the front matter % \IfMainName[FNN]{SNN, Affix}[Alternate] % {% % % it is in both front and main matter % } % {% % % it is only in the front matter % }% % } % {% % % no, it is not in the front matter % \IfMainName[FNN]{SNN, Affix}[Alternate] % {% % % it is only in the main matter % } % {% % % it does not exist % }% % }% % } % {% % % no; it is excluded % } % \end{Verbatim} % \end{quote} % % \subsubsection[Applications]{Applications: Game Books, Histories, Etc.} % % In any text where encountering certain names can change variables, character statistics, personal information, the macros described above can be used to key various pieces of information to the presence or the absence of a name. For example, in a series of independent document sections, one can craft notes like the one below to sketch out character development: % % \begin{quote} % \begin{Verbatim} % \ifMainName[Ferris}{Bueller} % {\Name[Cameron]{Frye} is gloomy and introspective.} % {\Name[Cameron]{Frye} is developing positive traits.} % \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: % % \begin{quote} % \JustIndex\JWG^^A % \begin{Verbatim} % \ifMainName[J.W. von}{Goethe} % {\Name[J.W. von}{Goethe}} % {\Name[J.W. von}{Goethe}[Johann Wolfgang von]} % \end{Verbatim} % \end{quote} % % In Sections~\ref{sec:NameAncient} and~\ref{sec:SpecialUses} we explore ways that one could automate something like what we have above. Section~\ref{sec:SpecialUses} applies better to Western names. % % In addition to using the name decision testing macros by themselves, one can use them with name data tags to ensure that the information associated with a given name is not anachronistic. % % For example, we know that certain people are associated with chronological events. We associate those people and events to the information presented in a name data tag via name testing macros: % % \begin{VerbatimOut}{\jobname.tmp} % \NameAddInfo{Saul, of Tarsus} % {\IfMainName{Jesus, Christ} % {\IfMainName[Lucius]{Sergius Paulus} % {finally renamed himself \Name{Paul}, in % honor of his patron} % {next became a preacher to the Gentiles}} % {wrote first that he persecuted Christians}} % \ForgetName{Jesus, Christ} % \ForgetName[Lucius]{Sergius Paulus} % \IndexRef{Paul}{Saul of Tarsus} % % \Name{Saul, of Tarsus} \NameQueryInfo{Saul, of Tarsus}. % He wrote in the letter to the Galatians, later reported in % the book of Acts, that he saw a vision of \Name{Jesus, Christ} % on the road to Damascus. % % \Name{Saul, of Tarsus} \NameQueryInfo{Saul, of Tarsus}. % He undertook three great missionary trips before being % sent to Rome to face trial in an appeal to Caesar. On one % journey, while in Cyprus, \Name{Saul, of Tarsus} converted % \Name[Lucius]{Sergius Paulus}, who became a patron. % % \Name{Saul, of Tarsus} \NameQueryInfo{Saul, of Tarsus}. % Under the name \Name{Paul} he wrote his letters. % \end{VerbatimOut} % % \begin{quote}\small % \vspace{3ex} % \PatInfo{\ShowPattern{Paul}!PN\break % \ShowPattern{Saul, of Tarsus}!DB\break % \ShowPattern{Jesus, Christ}!MN\break % \textls[-10]{\ShowPattern[Lucius]{Sergius Paulus}!MN}\break % \ShowPattern{Paul}!MN\break % \ShowPattern{Saul, of Tarsus}!MN} % \vspace{-3ex} % \VerbatimInput[gobble=0]{\jobname.tmp} % % \input{\jobname.tmp} % \end{quote} % % Using these tests\Info{Caveats} inside other macros or passing control sequences to them may create false results (see \textit{The \TeX book}, 212--15). This was especially the case before 2018 with names using diacritical marks and other letters outside the basic Latin characters. That is why \textsf{nameauth} uses token registers to save name arguments. % % 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. % % In addition to these points, using the \textsf{trace} package, \cmd{\show}, or \cmd{\meaning} can help one to mitigate problems. % % \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. % % \ifdefined\NameauthDoTestFiles \edef\NameauthTestFile{test09_01.tex}\else % \edef\NameauthTestFile{\jobname.tmp}\fi % % \begin{VerbatimOut}{\NameauthTestFile} % \documentclass{beamer} % \input{compat.tex} % Included with nameauth; needed only if % % compiling on multiple TeX distros or LaTeX engines. % \usepackage[noindex]{nameauth} % \mode % \beamerdefaultoverlayspecification{<+->} % % \begin{document} % % \begin{frame}{Move Text Without Retyping Names} % \begin{itemize}\footnotesize % \item<1-> Original\ForgetName[George]{Washington}% % \ForgetName[George]{Washington's}\\ % This version of \Name[Ulysses S.]{Grant} changes. % \begin{enumerate} % \item<2-> \IfMainName[George]{Washington's}{He}% % {\Name[George]{Washington}} % became the first president % of the United States. % \item<3-> \IfMainName[George]{Washington}{His}% % {\Name*[George]{Washington's}} % military successes during the Seven Years War % readied him to command the army % of the Continental Congress. % \end{enumerate} % \item<1-> Reordered\ForgetName[George]{Washington}% % \ForgetName[George]{Washington's}\\ % This version of \ForgetThis\Name[Ulysses S.]{Grant} % does not change. % \begin{enumerate} % \item<3-> \IfMainName[George]{Washington}{His}% % {\Name*[George]{Washington's}} % military successes during the Seven Years War % readied him to command the army % of the Continental Congress. % \item<2-> \IfMainName[George]{Washington's}{He}% % {\Name[George]{Washington}} % became the first president % of the United States. % \end{enumerate} % \end{itemize} % \end{frame} % % \end{document} % \end{VerbatimOut} % % \begin{quote}\small % \VerbatimInput[gobble=0]{\NameauthTestFile} % \IndexName[George]{Washington} % \IndexName[Ulysses S.]{Grant} % \end{quote} % % The overlays, numbered from one to three, keep name forms consistent by deleting name control sequence patterns for each new overlay. Otherwise, name patterns would change for each new overlay. % % \newpage % % Name conditionals ensure specific, context-dependent forms based on what name has appeared. These conditionals allow the text in each overlay to be order-independent and able to be moved around at will. The first overlay shows the use of \cmd{\ForgetThis} to keep names constant. % % \begin{tcolorbox}\centering % \IfFileExists{beamer01.pdf}{\includegraphics[scale=0.6]{beamer01.pdf}} % {\hbox{\vbox to 8cm{\hbox{\hfill}}}} % \end{tcolorbox} % \IndexName[George]{Washington} % \IndexName[Ulysses S.]{Grant} % \medskip % % The second overlay uses \cmd{\ForgetName} forcing specific name forms respective to each overlay, instead of respective to the overall sequence of overlays. We also observe the use of name conditionals in text elements that one might reorder. % % \begin{tcolorbox}\centering % \IfFileExists{beamer02.pdf}{\includegraphics[scale=0.6]{beamer02.pdf}} % {\hbox{\vbox to 8cm{\hbox{\hfill}}}} % \end{tcolorbox} % \IndexName[George]{Washington} % \IndexName[Ulysses S.]{Grant} % % Overlay three fully illustrates how all these features integrate. This could allow a presenter to maintain information used in different presentations, making each element or slide a ``drop-in'' unit that can figure out how to present names, name forms, and related information without extensive retyping. % % \begin{tcolorbox}\centering % \IfFileExists{beamer03.pdf}{\includegraphics[scale=0.6]{beamer03.pdf}} % {\hbox{\vbox to 8cm{\hbox{\hfill}}}} % \end{tcolorbox} % \IndexName[George]{Washington} % \IndexName[Ulysses S.]{Grant} % % \ReturnLink % % \AltFormatActive % \begin{Quote}{\ForgetThis\Shak\break % \hbox{}\hfill ``Romeo and Juliet'', Act II, Scene II} % 'Tis but thy name that is my enemy;\dots\\ % What's in a name? That which we call a rose\\ % By any other name would smell as sweet;\\ % So Romeo would, were he not Romeo call'd,\\ % Retain that dear perfection which he owes\\ % Without that title. Romeo, doff thy name,\\ % And for that name which is no part of thee\\ % Take all myself. % \end{Quote} % \AltFormatInactive % % \newpage % % \section{Name Authority Basics} % % \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{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} % % 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: % % \NameArgWarning % % \subsubsection[Alternate Argument]{Variants and the 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 a alternate name in the \texttt{nameauth} environment: % % \begin{quote}\small % \vspace{4ex} % \PatInfo{\ShowPattern[Mike]{Tyson}!MN} % \vspace{-4ex} % \begin{Verbatim} % \begin{nameauth} % \< Tyson & Mike & Tyson & > % \< Iron & Mike & Tyson & Iron Mike > % \end{nameauth} % \end{Verbatim} % \end{quote} % % When one takes advantage of \meta{Alternate}, all index page entries for the name variants occur under the canonical entry. The only additional step that one needs to include is a cross-reference: \cmd{\IndexRef\{Iron Mike\}\{Tyson, Mike\}}\IndexRef{Iron Mike}{Tyson, Mike} which will produce ``Iron Mike \textit{see} Tyson, Mike'' in the index. % % \begin{quote}\small\medstretch % \begin{tabular}{rlrl}\toprule % Macro & Output & Macro & Output\\ % \rowcolor{nagrey}\cmd{\LIron} \qquad & \LIron & % \cmd{\LTyson[Iron Mike]} & \LTyson[Iron Mike]\\ % \cmd{\Iron} & \Iron & \cmd{\Tyson} & \Tyson\\ % \rowcolor{nagrey}\cmd{\SIron} & \SIron & \cmd{\STyson} & % \STyson\\\bottomrule % \end{tabular} % \end{quote} % % Yet \meta{Alternate} does more than handle variant forenames in Western name forms. It can be used to manage alternate names in Eastern and ancient forms, as we have already seen. For this to work properly, we must have a name where \meta{SNN} and \meta{Affix} are both populated in order to use \meta{Alternate}. Otherwise, one winds up with the obsolete syntax (Section~\ref{sec:Obsolete}). % % We will engage this topic more, beginning with Section~\ref{sec:NameAncient}, Here we give a basic illustration of how one can start to manage these names. For instance: % % \begin{quote}\small % \vspace{4ex} % \PatInfo{\ShowPattern{Elizabeth, I}!MN} % \vspace{-4ex} % \begin{Verbatim} % \begin{nameauth} % \< Eliz & & Elizabeth, I & > % \end{nameauth} % % \LEliz[I, ``Gloriana''] was known also as % \ForceFN\SEliz[``Good Queen Bess'']. % \IndexRef{Gloriana}{Elizabeth I} % \IndexRef[Good Queen]{Bess}{Elizabeth I} % \end{Verbatim} % % \LEliz[I, ``Gloriana''] was known also as % \ForceFN\SEliz[``Good Queen Bess'']. % \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: % % \begin{enumerate} % \item Names that change capitalization in the surname, take grammatical % endings, or vary in other ways. See Sections~\ref{sec:NameParticles}, % \ref{sec:NameMedieval}, \ref{sec:NameAncient}, \ref{sec:RealAltEx}ff., % and~\ref{sec:Romani}, for increasingly complex examples. % \item Names having separate index entries that are linked together with % cross-references. Sections~\ref{sec:IndexPageno} and~\ref{sec:IndexRef} % give many examples, which we will not repeat here because most of the % work is done with indexing macros. % \item Names that the author wants to treat as different, yet which the % \textsf{nameauth} internals might see as the same. One can use the % naming macros, index tagging macros, and formatting macros to simulate % the existence of multiple identical names (see below and % Section~\ref{sec:IndexTag}). % \end{enumerate} % % The following method avoids using macros in name arguments and it is easier to set up. The trade-off is that, while macros in name arguments are harder to set up, they benefit from automation. Below we establish two names and a sort key for the main name under which both names are indexed: % % \begin{quote}\small % \begin{Verbatim} % \begin{nameauth} % \< DuBois & W.E.B. & Du~Bois & > % \< AltDuBois & W.E.B. & DuBois & > % \end{nameauth} % \PretagName[W.E.B.]{Du~Bois}{DuBois, William} % \end{Verbatim} % \end{quote} % % \begin{itemize} % \item Based on\PatInfo{\ShowPattern[W.E.B.]{Du~Bois}!MN\break % \ShowPattern[W.E.B.]{DuBois}!MN} historical research and what we can % tell from some name authorities, we decide that the the canonical % name will be: \cmd{\DuBois} \ForgetThis\DuBois. % \item We use the non-breaking space (the tilde active character) because % internally, \textsf{nameauth} removes all regular spaces from % name patterns. Both \cmd{\Name[W.E.B.]\{Du Bois\}} and % \cmd{\Name[W.E.B.]\{DuBois\}} have the same name control pattern: % \texttt{\ShowPattern[W.E.B.]{DuBois}} (Section~\ref{sec:NamePatterns}). % The name pattern \texttt{\ShowPattern[W.E.B.]{Du~Bois}} differs from % both of the other names. % \item Another reason to use the non-breaking space is that it prevents % a line break between the particle \textit{Du} and the name \textit{Bois}. % \item The sort key that could be applicable to both names is % \texttt{\{DuBois, William\}}. Had we used the sort key % \texttt{\{Du Bois, William\}}, the name would be sorted before % \texttt{dual}, which is not in order (Section~\ref{sec:IndexInitials}). % \item Instead of using \cmd{\SkipIndex}\cmd{\AltDuBois} many times, we % create a cross-reference before the alternate name is used to prevent % index page entries from being created for the alternate form: % \IndexRef[W.E.B.]{DuBois}{Du Bois, W.E.B.}\smallskip\\ % | \IndexRef[W.E.B.]{DuBois}{Du Bois, W.E.B.}| % \item We can keep full stop detection, modify name forms, and check % if the name straddles a page break in order to append % |\JustIndex\DuBois| if needed: % % \begin{VerbatimOut}{\jobname.tmp} % \newcommand\VarDuBois{\JustIndex\DuBois\AltDuBois} % \newcommand\LVarDuBois{\JustIndex\DuBois\LAltDuBois} % \newcommand\SVarDuBois{\JustIndex\DuBois\SAltDuBois} % Speaking of \VarDuBois[William E.B.].\\ % Speaking of \LVarDuBois.\\ % Speaking of \SVarDuBois[William E.B.]. % \end{VerbatimOut} % % \begin{quote}\small % \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}\small % \begin{Verbatim} % \newcommand\NewDuBois[2]{% % \def\Test{#1}% % \def\Long{L}% % \def\Short{S}% % \JustIndex\DuBois% % \ifx\Test\Long \LAltDuBois[#2] \else % \ifx\Test\Short \SAltDuBois[#2] \else % \AltDuBois \fi\fi % \JustIndex\DuBois} % \ForgetThis\NewDuBois{}{William E.B.}\\ % \NewDuBois{L}{}\\ % \NewDuBois{S}{William} % \end{Verbatim} % \medskip % \newcommand\NewDuBois[2]{^^A % \def\Test{#1}^^A % \def\Long{L}^^A % \def\Short{S}^^A % \JustIndex\DuBois^^A % \ifx\Test\Long \LAltDuBois[#2] \else % \ifx\Test\Short \SAltDuBois[#2] \else % \AltDuBois[#2] \fi\fi % \JustIndex\DuBois} % \ForgetThis\NewDuBois{}{William E.B.}\\ % \NewDuBois{L}{}\\ % \NewDuBois{S}{William} % \end{quote} % \end{itemize} % % \begin{Quote}{\ForgetThis\DuBois\break % \hbox{}\hfill \textit{Darkwater} (1920), C II: The Souls of White Folk} % The cause of war is preparation for war.\vspace{-1ex} % \end{Quote} % % \newpage % % \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: % % \begin{VerbatimOut}{\jobname.tmp} % \SubvertThis\CapThis\Name[e.e.]{cummings}'s motif of the % goat-footed balloon man has underlying sexual themes that % nevertheless have a childish facade. % \end{VerbatimOut} % % \begin{quote}\small % \vspace{4ex} % \BothInfo{\ShowPattern[e.e.]{cummings}!MN} % {\ShowIdxPageref*[e.e.]{cummings}} % \vspace{-4ex} % \VerbatimInput[gobble=0]{\jobname.tmp} % \renewcommand*\NamesFormat{} % \renewcommand*\MainNameHook{} % % \input{\jobname.tmp} % \end{quote} % % 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}: % % \begin{VerbatimOut}{\jobname.tmp} % \ExcludeName[e.e.]{cummings's}\IndexName[e.e.]{cummings} % \SubvertThis\CapThis\Name[e.e.]{cummings's} motif of the % goat-footed balloon man has underlying sexual themes that % nevertheless have a childish facade. % \end{VerbatimOut} % % \begin{quote}\small % \vspace{4.5ex} % \PatInfo{\ShowPattern[e.e.]{cummings's}} % \vspace{-4.5ex} % \VerbatimInput[gobble=0]{\jobname.tmp} % % \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. % % Section~\ref{sec:AltFormat} explains how to use \cmd{\CapThis} with alternate formatting when using macros in name arguments. Section~\ref{sec:InflNames} describes how automation lends itself to grammatical inflections of names.\medskip % % \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: % % \begin{enumerate} % \item We use\PatInfo{\ShowPattern[J.E.]{Carter, Jr.}!MN\hfill % \textrm{(1--2)}\break % \ShowPattern[Jimmy]{Carter}!PN\hfill \textrm{(3, 6)}\break % \ShowPattern[Jimmy]{Carter}!MN\hfill \textrm{(4)}\break % \ShowPattern[J.E.]{Carter, Jr.}!PN\hfill % \textrm{(5)}} % the canonical name to create page references:\smallskip\\ % \hbox{}\quad|\Name*[J.E.]{Carter, Jr.}|\dotfill % \Name*[J.E.]{Carter, Jr.} % \item Variants that use \meta{Alternate} in the text create page % entries under the canonical form, not the variant form:\smallskip\\ % \hbox{}\quad|\DropAffix\Name*[J.E.]{Carter, Jr.}[Jimmy]|\dotfill % \DropAffix\Name*[J.E.]{Carter, Jr.}[Jimmy]\\ % \hbox{}\quad|\ShowIdxPageref*[J.E.]{Carter, Jr.}[Jimmy]|\dotfill % \ShowIdxPageref*[J.E.]{Carter, Jr.}[Jimmy] % \item We must create a \textit{see} reference from an alternate form % to a canonical form \emph{before} using the alternate form in a naming % macro, or it will be ignored and a warning will result:\smallskip\\ % \hbox{}\quad|\IndexRef[Jimmy]{Carter}{Carter, J.E., Jr.}| % \IndexRef[Jimmy]{Carter}{Carter, J.E., Jr.} % \item No page references will occur below because we made the % \textit{see} reference first. Note how the alternate form is an % independent name:\smallskip\\ % \hbox{}\quad|\Name[Jimmy]{Carter}|\dotfill \Name[Jimmy]{Carter} % \item If we want to index the alternate name, we have to use the % canonical name instead of the alternate name:\smallskip\\ % \hbox{}\quad|\IndexName[J.E.]{Carter, Jr.}| % \item If instead we wanted to make a \textit{see also} reference, we % would use both the canonical name and the alternate name, then create % the cross-reference \emph{after} all uses of the alternate name % (at the end of the document), e.g.:\smallskip\\ % \hbox{}\quad|\SeeAlso\IndexRef[Jimmy]{Carter}{Carter, J.E., Jr.}| % \end{enumerate} % % Below,\Info{Multiple\break connections} two names are indexed with page numbers. They have \textit{see also} cross-references to each other. One of those names also has a \textit{see} reference to it: % % \begin{enumerate} % \item We use\PatInfo{\ShowPattern{Maimonides}!MN \textrm{(1)}\break % \ShowPattern{Moses, ben-Maimon}!PN \textrm{(2)}\break % \ShowPattern{Moses, ben-Maimon}!MN \textrm{(3)}\break % \ShowPattern{Rambam}!MN \textrm{(4)}\break % \ShowPattern{Rambam}!PN \textrm{(5)}} % the canonical name to set up page references:\smallskip\\ % \hbox{}\qquad|\Name{Maimonides}|\dotfill \Name{Maimonides} % \item \Name{Maimonides} has two other names, one more used than the % other. We set up his least-used name as the \textit{see} % reference:\smallskip\\ % \hbox{}\qquad|\IndexRef{Moses, ben-Maimon}{Maimonides}| % \IndexRef{Moses, ben-Maimon}{Maimonides} % \item We have a main name with a page entry and a ``\textit{see} % reference'' to that name. No page references will occur below because % we made the xref first:\smallskip\\ % \hbox{}\qquad|\Name{Moses, ben-Maimon}|\dotfill \Name{Moses, ben-Maimon} % \item Before creating \textit{see also} cross-references, we use the other % alias so that all the page entries precede the % cross-references:\smallskip\\ % \hbox{}\qquad|\Name{Rambam}|\dotfill \Name{Rambam} % \item All \textit{see also} references must come after all page references. % For example, one could put both of these macros at the end of the % document:\smallskip\\ % \hbox{}\qquad|\SeeAlso\IndexRef{Maimonides}{Rambam}| % \SeeAlso\IndexRef{Maimonides}{Rambam}\\ % \hbox{}\qquad|\SeeAlso\IndexRef{Rambam}{Maimonides}| % \SeeAlso\IndexRef{Rambam}{Maimonides} % \end{enumerate} % % There\Info{Multiple targets} is a case where one cross-reference can point to multiple targets, such as demonstrated in the example below: % % \begin{VerbatimOut}{\jobname.tmp} % \PretagName{\textit{Snellius}}{Snellius} % \IndexRef{\textit{Snellius}} % {Snel van Royen, R.; Snel van Royen, W.} % Both \Name[W.]{Snel van Royen}[Willebrord] and % his son \Name[R.]{Snel van Royen}[Rudolph] were known % by the Latin moniker \Name{\textit{Snellius}}. % \end{VerbatimOut} % % \begin{quote}\small % \vspace{5ex} % \PatInfo{\ShowPattern{\textit{Snellius}}!PRE\break % \ShowPattern{\textit{Snellius}}!PN\break % \ShowPattern[W.]{Snel van Royen}!MN\break % \ShowPattern[R.]{Snel van Royen}!MN} % \vspace{-5ex} % \VerbatimInput[gobble=0]{\jobname.tmp} % % \input{\jobname.tmp} % \end{quote} % % One must plan the location of xrefs or use \cmd{\IncludeName*}. Above, we have no page entry for |\Name{\textit{Snellius}}| because \cmd{\IndexRef} comes first. % % \begin{Quote}{\ForgetThis\Name{Maimonides}, % \textit{Guide for the Perplexed} (1190)} % For a truth, once established by proof, does neither gain force nor certainty by the consent of all scholars, nor lose by the general dissent. % \end{Quote} % % \newpage % % \subsection{Using a Name Authority} % % Below are a couple of names from a name authority created for a translation of \textit{De Diaconis et Diaconissis Veteris Ecclesiae Liber Commentarius} by \Name[Caspar]{Ziegler}, of which the present author was the editor.\footnote{The book, \textit{The Diaconate of the Ancient and Medieval Church} was typeset using \LaTeX, but had to be converted to a different format.} % % Constructing that name authority of over 500 names was a challenge. The deceased translator left names in abbreviated Latin. He left many place-names in Latin and incorrectly translated some others. To get valid names that one can research, the present author recommends: % % \begin{itemize} % \item \href{https://data.cerl.org/thesaurus/_search}{CERL Thesaurus} % \item \href{https://viaf.org/}{Virtual International Authority File} % \item \href{https://edit16.iccu.sbn.it/web/edit-16}{EDIT16} % \item \href{https://www.worldcat.org/}{WorldCat} % \item \href{https://id.loc.gov/authorities/names.html}{Library of Congress} % \item \href{https://www.columbia.edu/acis/ets/Graesse/contents.html} % {Older version of Graesse, \textit{Orbis Latinus}} % \end{itemize} % % I set the vernacular forms as canonical, with the Latin versions referring to them. I re-translated all the place-names. I also did the following: % % \begin{enumerate*} % \item Sort vernacular names with \cmd{\PretagName} due to % particles (Section~\ref{sec:IndexSort}). % \item If Latin names are only cross-references, use % \cmd{\IndexRef}\meta{name args} to generate cross-references % before referring to any names (Section~\ref{sec:IndexRef}). % \item If Latin names have page references, then place % \cmd{\SeeAlso}\cmd{\IndexRef}\meta{name args} as needed % at the end of the document, before \cmd{\printindex}. % \item Use \cmd{\CapThis} (Section~\ref{sec:NameParticles}). % \end{enumerate*} % % \begin{quote}\small % \vspace{3.5ex} % \BothInfo{\ShowPattern[Jacques]{De~Pamele}!MN\break % \ShowPattern[Jacobus]{Pamelius}!MN\break % \ShowPattern[Giovanni]{d'Andrea}!MN\break % \ShowPattern[Ioannes]{Andreae}!MN} % {\ShowIdxPageref*[Jacques]{De~Pamele}\break % \ShowIdxPageref*[Jacobus]{Pamelius}\break % \ShowIdxPageref*[Giovanni]{d'Andrea}\break % \ShowIdxPageref*[Ioannes]{Andreae}} % \vspace{-3ex} % \begin{Verbatim} % \PretagName[Jacques]{De~Pamele}{Depamele, Jacques} % \Name[Jacques]{De~Pamele}[Jacques de~Joigny] % \IndexRef[Jacobus]{Pamelius}{De~Pamele, Jacques} % \Name[Jacobus]{Pamelius} % % \PretagName[Giovanni]{d'Andrea}{Dandrea, Giovanni} % \Name[Giovanni]{d'Andrea} % \IndexRef[Ioannes]{Andreae}{d'Andrea, Giovanni} % \Name[Ioannes]{Andreae} % \end{Verbatim} % \end{quote} % \negmedskip % % \IndexRef[Jacobus]{Pamelius}{De~Pamele, Jacques} % \IndexRef[Ioannes]{Andreae}{d'Andrea, Giovanni} % \begin{itemize}[leftmargin=3.5cm] % \item[Canonical Name] |\Name[Jacques]{De~Pamele}[Jacques de~Joigny]|\\ % \Name[Jacques]{De~Pamele}[Jacques de~Joigny] % \item[Latin Name] |\Name[Jacobus]{Pamelius}| % \Name[Jacobus]{Pamelius} % \item[Canonical Name] |\Name[Giovanni]{d'Andrea}| % \Name[Giovanni]{d'Andrea} % \item[Latin Name] |\Name[Ioannes]{Andreae}| % \Name[Ioannes]{Andreae} % \end{itemize} % % \CapThis\Name[Giovanni]{d'Andrea} |\CapThis\Name[Giovanni]{d'Andrea}| can be used at the beginning of a sentence. |\Name[Jacques]{De~Pamele}| gives \Name[Jacques]{De~Pamele}.\negmedskip % % \ReturnLink % % \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. % % Before we delve into this section, below we see a general scheme of how the core name engine processes a name:\bigskip % % \begin{tcolorbox}[colback=white, % adjusted title={\bfseries Naming Macro Layer}] % % Naming macros \cmd{\Name}, \cmd{\Name*}, \cmd{\FName}, \cmd{\FName*}, and % the macros created by the \texttt{nameauth} environment all send their % arguments to three hooks that, by default, point to \cmd{\@nameauth@Name} % (Section~\ref{sec:FullCustomize}). Here \cmd{\@nameauth@Name} handles the % work requested by \cmd{\JustIndex}, \cmd{\SubvertThis}, \cmd{\ForgetThis}, % and \cmd{\SkipIndex}. It then hands off the name arguments to the name % parser, either with a main-matter \texttt{!MN} suffix or a front-matter % \texttt{!NF} suffix\dots % % \begin{tcolorbox}[colframe=naslate,colback=white, % adjusted title={\bfseries Syntactic Element Layer}] % % \cmd{\@nameauth@Parse}: Determine name category, capitalization, % punctuation, elements to be used, and pass on to\dots % % \begin{tcolorbox}[colframe=nablue,colback=white, % adjusted title={\sffamily\bfseries Name Display Layer}] % % \cmd{\@nameauth@NonWest}: Consult rules, construct displayed form.\\ % \cmd{\@nameauth@West}: Consult rules, construct displayed form.\\ % \cmd{\@nameauth@Form}: ``Magic Eight Ball'' of rules for name forms. % Includes checking if a name control sequence exists, checking which is % the calling macro, and so on. Pass the information to\dots % % \begin{tcolorbox}[colframe=nared,colback=white, % adjusted title={\sffamily\bfseries Format Hook Dispatcher}] % % \cmd{\@nameauth@Hook}: Check the name to be printed for a final full % stop. Check which naming system we are using. % % Call a formatting hook depending on if our name control sequence % pattern exists, and if we are in the main-matter system or the % front-matter system. The formatting hook prints the name in the text. % % \end{tcolorbox} % % \end{tcolorbox} % % \cmd{\@nameauth@Parse}: Make name control sequence from name pattern. % % \end{tcolorbox} % % \cmd{\@nameauth@NameEngine}: If the final full stop flag is true, check % the lookahead token for a full stop and gobble it if needed. % % \end{tcolorbox} % % \newpage % % \subsection{Formatting Hooks} % \label{sec:ComplexHooks} % % This proof of concept puts the first mention of a name either in italics (front matter) or in boldface (main matter), and it adds a margin note if that is allowed. We use \cmd{\let} to save and restore the old hooks, although we also could use a group to keep format changes in a local scope: % % \ifdefined\NameauthDoTestFiles \edef\NameauthTestFile{test11_01.tex}\else % \edef\NameauthTestFile{\jobname.tmp}\fi % % \begin{VerbatimOut}{\NameauthTestFile} % \documentclass{article} % \input{compat.tex} % Included with nameauth; needed only if % % compiling on multiple TeX distros or LaTeX engines. % \usepackage{makeidx} % \usepackage{nameauth} % \makeindex % % % First save main- and front-matter hooks. Then change % % first-use hooks for both main matter and front matter. % \let\OldFormat\NamesFormat % \let\OldFrontNames\FrontNamesFormat % % \renewcommand*\NamesFormat[1]{\textbf{#1}\unless\ifinner % \marginpar{\raggedleft\scriptsize #1}\fi} % \renewcommand*\FrontNamesFormat[1]{\textit{#1}\unless\ifinner % \marginpar{\raggedleft\scriptsize #1}\fi} % % \PretagName{Vlad, {\c T}epe{\c s}}{Vlad Tepes} % for accented names % \TagName{Vlad, II}{ Dracul} % for index information % \TagName{Vlad, III}{ Dracula} % \IndexRef{Dracula}{Vlad III} % % \begin{document} % % The new format (front matter):\NamesInactive % % \Name{Vlad, III}[III Dracula], known as % \IndexRef{Vlad, {\c T}epe{\c s}}{Vlad III} % \SubvertThis\Name*{Vlad, {\c T}epe{\c s}} % (\Name*{Vlad, {\c T}epe{\c s}}[the Impaler]) % after his death, was the son of \Name{Vlad, II}[II Dracul], % a member of the Order of the Dragon. Later references to % ``\Name*{Vlad, III}'' and ``\Name{Vlad, III}'' appear thus. % % The new format (main matter):\NamesActive % % \Name{Vlad, III}[III Dracula], known as % \IndexRef{Vlad, {\c T}epe{\c s}}{Vlad III} % \SubvertThis\Name*{Vlad, {\c T}epe{\c s}} % (\Name*{Vlad, {\c T}epe{\c s}}[the Impaler]) % after his death, was the son of \Name{Vlad, II}[II Dracul], % a member of the Order of the Dragon. Later references to % ``\Name*{Vlad, III}'' and ``\Name{Vlad, III}'' appear thus. % % \let\NamesFormat\OldFormat % \let\FrontNamesFormat\OldFrontNames % % We are back in the old format. % % in the front matter we see: \NamesInactive % \ForgetThis\Name{Vlad, III}[III Dracula], % \Name*{Vlad, III}, and \Name{Vlad, III}. % % in the main matter we see: \NamesActive % \ForgetThis\Name{Vlad, III}[III Dracula], % \Name*{Vlad, III}, and \Name{Vlad, III}. % % \printindex % \end{document} % \end{VerbatimOut} % % \begin{quote}\small % \VerbatimInput[gobble=0]{\NameauthTestFile} % % \let\OldFormat\NamesFormat % \let\OldFrontNames\FrontNamesFormat % % \renewcommand*\NamesFormat[1]{\textbf{#1}\unless\ifinner % \marginpar{\raggedleft\scriptsize #1}\fi} % \renewcommand*\FrontNamesFormat[1]{\textit{#1}\unless\ifinner % \marginpar{\raggedleft\scriptsize #1}\fi} % % The new format (front matter):\NamesInactive % % \Name{Vlad, III}[III Dracula], known as % \IndexRef{Vlad, {\c T}epe{\c s}}{Vlad III} % \SubvertThis\Name*{Vlad, {\c T}epe{\c s}} % (\Name*{Vlad, {\c T}epe{\c s}}[the Impaler]) % after his death, was the son of \Name{Vlad, II}[II Dracul], % a member of the Order of the Dragon. Later references to % ``\Name*{Vlad, III}'' and ``\Name{Vlad, III}'' appear thus. % % The new format (main matter):\NamesActive % % \Name{Vlad, III}[III Dracula], known as % \IndexRef{Vlad, {\c T}epe{\c s}}{Vlad III} % \SubvertThis\Name*{Vlad, {\c T}epe{\c s}} % (\Name*{Vlad, {\c T}epe{\c s}}[the Impaler]) % after his death, was the son of \Name{Vlad, II}[II Dracul], % a member of the Order of the Dragon. Later references to % ``\Name*{Vlad, III}'' and ``\Name{Vlad, III}'' appear thus. % % \let\NamesFormat\OldFormat % \let\FrontNamesFormat\OldFrontNames % % We are back in the old format. % % in the front matter we see: \NamesInactive % \ForgetThis\Name{Vlad, III}[III Dracula], % \Name*{Vlad, III}, and \Name{Vlad, III}. % % in the main matter we see: \NamesActive % \ForgetThis\Name{Vlad, III}[III Dracula], % \Name*{Vlad, III}, and \Name{Vlad, III}. % \end{quote} % % The reason why we redefine \cmd{\NamesFormat} is because it is more common to add extra information with the first mention of a name. Yet one similarly could redefine \cmd{\MainNameHook} or \cmd{\FrontNameHook} for subsequent uses of names. % % \subsection{Data tags in Hooks} % \label{sec:DataTagHooks} % % By recalling name data tags (Section~\ref{sec:DataTags}) in formatting hooks, one can automate how they either appear with a name or not. This package is all about automation and the associated trade-offs. % % Formatting hooks are called within a local scope. They take zero or one argument (Section~\ref{sec:Formatting}). When they take one argument, they have the option to print that argument, add information to the argument, or discard the argument. Yet macros used in formatting hooks can present challenges that we show how to manage: % % \begin{itemize} % \item 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 data 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 data tag with the first use of a name in the main-matter system, if such a tag exists. It is simple, it avoids the \cmd{\NameQueryInfo} problem, and it is easy to debug. % % \begin{quote} % \begin{Verbatim} % \renewcommand*\NamesFormat[1] % {% % #1% % \ifcsname\NameauthPattern!DB\endcsname % \expandafter\csname\NameauthPattern!DB\endcsname% % \fi % } % \end{Verbatim} % \end{quote} % % \subsubsection*{\hfil Older Templates} % % Two other hook designs were used in the past to display name data tags. They are included here only for the sake of illustration. After showing the templates, we test all three of them to show why we recommend the template above. % % We use \(\epsilon\)-\TeX\ features next. See \href{https://tex.stackexchange.com/questions/140785/how-is-unexpanded-defined}{\bfseries this page} on the use of \cmd{\unexpanded} and \href{https://tex.stackexchange.com/questions/61223/explanations-about-begingroup-edef-x-endgroup}{\bfseries another page} pertinent to the structure of this hook. We print the name, expand the arguments of \cmd{\NameQueryInfo}, and use those arguments to print the tag. % % \begin{quote} % \vspace{3ex}\Info{Alternate A}\vspace{-3ex} % \begin{Verbatim} % \makeatletter % \renewcommand*\NamesFormat[1]{% % \begingroup% % \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 data tag contains the second part. We will use both name % interfaces with all three templates. % % \VerbatimInput[gobble=0]{\jobname.tmp} % \end{quote} % % \input{\jobname.tmp} % % \begin{itemize} % \item The recommended hook gives us:\\ % \renewcommand*\NamesFormat[1] % {^^A % #1^^A % \ifcsname\NameauthPattern!DB\endcsname % \expandafter\csname\NameauthPattern!DB\endcsname^^A % \fi % } % \begin{tabular}{lll} % \cmd{\ForgetThis}\cmd{\Name\{}\cmd{\noexpand}\cmd{\testname\}} & % \ForgetThis\Name{\noexpand\testname} & success \\ % \cmd{\ForgetThis}\cmd{\Test} & \ForgetThis\Test & success \\ % \end{tabular} % % \item Alternate A gives us:\\ % \makeatletter % \renewcommand*\NamesFormat[1]{^^A % \begingroup^^A % \protected@edef\temp{\endgroup^^A % {#1\noexpand\NameQueryInfo % [\unexpanded\expandafter{\the\@nameauth@toksa}] % {\unexpanded\expandafter{\the\@nameauth@toksb}} % [\unexpanded\expandafter{\the\@nameauth@toksc}]^^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 data tags and the recommended template: % % \begin{quote} % \vspace{3ex} % \PatInfo{\ShowPattern{Demetrius, I}!DB} % \vspace{-3ex} % \begin{Verbatim}[firstnumber=last] % \NameAddInfo{Demetrius, I}{ Soter} % \renewcommand*\NamesFormat[1] % {% % #1% % \ifcsname\NameauthPattern!DB\endcsname % \expandafter\csname\NameauthPattern!DB\endcsname% % \fi % } % \renewcommand*\MainNameHook{} % \end{Verbatim} % \end{quote} % \NameAddInfo{Demetrius, I}{ Soter} % \renewcommand*\NamesFormat[1] % {^^A % #1^^A % \ifcsname\NameauthPattern!DB\endcsname % \expandafter\csname\NameauthPattern!DB\endcsname^^A % \fi % } % \renewcommand*\MainNameHook{} % % \begin{Block} % |\ForgetName{Demetrius, I}|\ForgetName{Demetrius, I}\\ % \cmd{\Dem}\dotfill \Dem\\ % \cmd{\LDem}\dotfill \LDem\\ % \cmd{\Dem}\dotfill \Dem % \end{Block} % % In both cases, the index entry in a normal document would be sorted like the following: % \begingroup % \IndexActual{@}^^A % \TagName{Demetrius, I}{ Soter, king}^^A % \texttt{\ShowIdxPageref{Demetrius, I}}.^^A % \TagName{Demetrius, I}{ Soter, king\string|hyperpage} % \endgroup % % The first use of a name, or one after the use of \cmd{\ForgetName} or \cmd{\ForgetThis}, shows the most information. A long reference to an extant name shows a little less info, and a short reference shows the least. Every difference in name form corresponds with a macro in a known state. % \endgroup^^A Local format hook redefinition % % \subsubsection[Life Dates]{Application: Life Dates} % % \begingroup^^A Local format hook redefinition % % History texts tend to use life dates, regnal dates, and dates when certain figures flourished. As we used more information with ancient names via name data tags, we can do something similar here. % % First we must create any data tags that might be used. Whether it is in the preamble or in the body text, the main point is that the tag can only be used if it exists. The tags have a leading space because they are printed conditionally. % % We also define a cross-reference ``Atat\"urk,'' yet we use naming macros with that name, printing formatted names in the text but making no index page entries. We add a Boolean flag to the formatting hook that lets us suppress dates in first uses as needed, while normally displaying dates in first uses by default. Below we suppress the usual formatting of this manual. % % \ifdefined\NameauthDoTestFiles \edef\NameauthTestFile{test11_02.tex}\else % \edef\NameauthTestFile{\jobname.tmp}\fi % % \begin{VerbatimOut}{\NameauthTestFile} % \documentclass{article} % \input{compat.tex} % Included with nameauth; needed only if % % compiling on multiple TeX distros or LaTeX engines. % \usepackage{makeidx} % \usepackage{nameauth} % \makeindex % % % Add data tags to names. % \NameAddInfo[George]{Washington}{ (1732--99)} % \NameAddInfo[Mustafa]{Kemal}{ (1881--1938)} % \NameAddInfo{Atat\"urk}{ (in 1934, a special surname)} % % % Ensure that Atat\"urk is a cross-reference that % % has no page entries in the index. % \IndexRef{Atat\"urk}{Kemal, Mustafa} % % % Manually suppress data tag in ``first'' reference % \newif\ifNoTag % % % Redesign formatting hook to usually print a tag % % only in ``first'' reference. On exit, It resets % % the flag that suppresses tags, making that flag % % work only once per name use. % % \renewcommand*\NamesFormat[1] % {% % #1% % \ifcsname\NameauthPattern!DB\endcsname % \unless\ifNoTag % \expandafter\csname\NameauthPattern!DB\endcsname% % \fi % \global\NoTagfalse% % \fi % } % % \begin{document} % % \ForgetThis\Name[George]{Washington} held office as the first US % president from 1789 to 1797. \Name[George]{Washington} was the only % president whose term in office was completely in the eighteenth % century. If we need to trigger the first use hook at some point, % we can suppress dates and get an automatic long reference via: % \NoTagtrue\ForgetThis\Name[George]{Washington}. Or we can trigger % the first-use hook in a subsequent name use and still have dates: % \ForceName\Name[George]{Washington}. % % We can add name info tags to names used only as cross- % references. For example, \Name[Mustafa]{Kemal} was granted % the name \Name{Atat\"urk}. We mention \Name[Mustafa]{Kemal} % and \Name{Atat\"urk} again. Likewise, we can trigger a % first use, but with no data tag tag: % \NoTagtrue\ForgetThis\Name{Atat\"urk}. % % \printindex % \end{document} % \end{VerbatimOut} % % \NameAddInfo[George]{Washington}{ (1732--99)} % \NameAddInfo[Mustafa]{Kemal}{ (1881--1938)} % \NameAddInfo{Atat\"urk}{ (in 1934, a special surname)} % \IndexRef{Atat\"urk}{Kemal, Mustafa} % \renewcommand*\NamesFormat[1] % {^^A % #1^^A % \ifcsname\NameauthPattern!DB\endcsname % \unless\ifNoTag % \expandafter\csname\NameauthPattern!DB\endcsname^^A % \fi % \global\NoTagfalse^^A % \fi % } % \renewcommand*\MainNameHook{} % % \begin{quote}\small % \VerbatimInput[gobble=0,lastline=34]{\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. % % \begin{quote}\small % \VerbatimInput[gobble=0,firstline=35,lastline=45]{\NameauthTestFile} % % \ForgetThis\Name[George]{Washington} held office as the first US % president from 1789 to 1797. \Name[George]{Washington} was the only % president whose term in office was completely in the eighteenth % century. If we need to trigger the first use hook at some point, % we can suppress dates and get an automatic long reference via: % \NoTagtrue\ForgetThis\Name[George]{Washington}. Or we can trigger % the first-use hook in a subsequent name use and still have dates: % \ForceName\Name[George]{Washington}. % \end{quote} % % Since we already set up a cross-reference with \cmd{\IndexRef}, we can use just the the naming macros with ``Atat\"urk'' and get the desired formatting without any page references in the index: % % \begin{quote}\small % \VerbatimInput[gobble=0,firstline=46]{\NameauthTestFile} % % We can add name info tags to names used only as cross- % references. For example, \Name[Mustafa]{Kemal} was granted % the name \Name{Atat\"urk}. We mention \Name[Mustafa]{Kemal} % and \Name{Atat\"urk} again. Likewise, we can trigger a % first use, but with no data tag tag: % \NoTagtrue\ForgetThis\Name{Atat\"urk}. % \end{quote} % % \endgroup^^A Local format hook redefinition % % \subsection{Alternate Formatting} % \label{sec:AltFormat} % % We build on the subject of complex formatting hooks that \cmd{\noexpand} playing a role therein, Before we engage the topic of Roman names and other complex examples, we need to cover alternate formatting. % % \subsubsection[Enabling/Disabling]{Enabling and Disabling} % % The first thing we need to know is how to enable and disable alternate formatting: % % \begin{center}\small\medstretch % \begin{tabular}{lcc}\toprule % Macro & Enabled & Activated\\\midrule % \cmd{\AltFormatActive} & \YES & \YES\\ % \cmd{\AltFormatActive*} & \YES & \NO\\ % \cmd{\AltFormatInactive} & \NO & \NO\\\bottomrule % \end{tabular} % \end{center} % % \begin{itemize} % \item \emph{Enabled} means that the alternate formatting mechanism % inhibits the normal behavior of \cmd{\CapThis}. % \item \emph{Disabled} means that the normal behavior of \cmd{\CapThis} % is again in force and alternate formatting is inhibited. % \item \emph{Activated} means that built-in alternate formatting macros % like \cmd{\textSC} format their arguments. % \item \emph{Deactivated} means that built-in alternate formatting macros % like \cmd{\textSC} do not format their arguments. % \end{itemize} % % \DescribeMacro{\AltFormatActive} % Both the \texttt{altformat} option and \cmd{\AltFormatActive} enable and activate alternate formatting. Both cause \cmd{\CapThis} to work via \cmd{\AltCaps} instead of the normal way. \cmd{\AltFormatActive} countermands \cmd{\AltFormatActive*}.\medskip % % \DescribeMacro{\AltFormatActive*} % The starred form \cmd{\AltFormatActive*} enables alternate formatting but deactivates the built-in alternate formatting macros, preventing them from changing their arguments. It countermands both the \texttt{altformat} option and \cmd{\AltFormatActive}. It causes \cmd{\CapThis} only to work via \cmd{\AltCaps}.\medskip % % \newpage % % \DescribeMacro{\AltFormatInactive} % This macro both disables and deactivates alternate formatting. This reverts globally to standard formatting and the normal function of \cmd{\CapThis}. \medskip % % Most \textsf{nameauth}\Info{Global scope} macros that turn things on and off have a local scope unless one uses \cmd{\global}. These alternate formatting macros have global scope to eliminate implied scope becoming a point of failure, creating spurious index entries. % % \begin{InfoBox} % The macros above \emph{always} make global changes. Using names designed for alternate formatting in a document section that uses regular formatting will produce an inconsistent appearance in the text and spurious index entries. % \end{InfoBox} % \negmedskip % % \subsubsection{Using \texttt{\textbackslash noexpand}} % % 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. % % In order to handle the inherent ambiguity of name forms, macros that take name arguments trade a certain ``fragility'' for the ability to be as close to natural language as possible. In versions of \textsf{nameauth} before 3.5, enclosing an \meta{SNN},\meta{Affix} argument within a robust macro like \cmd{\textsc} would halt \LaTeX\ with errors. That seems to be no longer the case. Nevertheless, depending on the macros used, it may be helpful to apply macros separately to \meta{SNN} and \meta{Affix} like this: % % \begin{quote} % |\Name{\noexpand\MyMacro{|\meta{SNN}|},\noexpand\MyMacro{|\meta{Affix}|}}|. % \end{quote} % % Using \cmd{\CapThis} with a name whose leading element is a macro may fail, depending on the particular macro. Use alternate formatting to have \cmd{\CapThis} activate the alternate capitalization mechanism. % % \NameArgWarning % % In Section~\ref{sec:DebuggingMacros} we encountered reasons for using \cmd{\noexpand} in name arguments, as well as related caveats. Now we include more reasons to use \cmd{\noexpand}: % % \begin{itemize} % \item If a macro is undefined, even putting \cmd{\noexpand} before it will % permit an error unless the macro is detokenized or verbatim. % \item The use of \cmd{\noexpand} isolates the local, conditional expansion of % macros in the formatting hooks from the global macro state in the index. % \item Indexing of such names normally does not occur within the formatting % hooks. Otherwise, different index entries would result. % \item One can use macros in the formatting hooks to trigger local changes. If % using Boolean flags to trigger those changes, one needs two flags per change % (e.g., grammatical inflection) but not per name. % \item Local flags are false when the hook executes. Global flags are reset % when the hook terminates. % \item Take care when using macros in name arguments without using % \cmd{\noexpand} before them. % \end{itemize} % % \subsubsection[Capitalization]{Alternate Capitalization} % \AltFormatActive % % Above we referred to potential problems using \cmd{\CapThis}. When alternate formatting is enabled, \cmd{\CapThis} changes its mechanism to avoid such problems.\medskip % % \DescribeMacro{\AltCaps} % Using the aid of the helper macro \cmd{\AltCaps}, \cmd{\CapThis} will cause \cmd{\AltCaps} to capitalize its argument only in a formatting hook. \cmd{\AltCaps} is enabled whenever alternate formatting is enabled, but it works independently of both \cmd{\AltOn} and \cmd{\AltOff}, which are covered in the next section. We describe the syntax: % % \begin{SyntaxBox} % \cmd{\noexpand}\cmd{\AltCaps}\marg{Arg} % \end{SyntaxBox} % % We offer a silly example below, taking advantage of the local scope of the \texttt{quote} environment to disable indexing temporarily: % % \begin{VerbatimOut}{\jobname.tmp} % \IndexInactive % What's in \Name[\noexpand\AltCaps{a}]{Name}? % \CapThis\Name*[\noexpand\AltCaps{a}]{Name} smells not, % but a rose does, even if it has % \Name*[\noexpand\AltCaps{a}]{Name}. % \end{VerbatimOut} % % \begin{quote}\small % \VerbatimInput[gobble=0]{\jobname.tmp} % % \input{\jobname.tmp} % \end{quote} % % \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 % % \begingroup^^A Local format hook redefinition % % \subsubsection{Formatting Features} % \label{sec:AltFeatures} % \AltFormatActive % % \DescribeMacro{\textSC} % Using alternate formatting can be as easy as using any one of four predefined macros. % \DescribeMacro{\textIT} % These macros are analogous to the predefined formatting hooks that are accessible via package options. % \DescribeMacro{\textBF} % They \emph{always format} their arguments when using the \texttt{altformat} option or \cmd{\AltFormatActive}. % \DescribeMacro{\textUC} % They \emph{never format} their arguments when \cmd{\AltFormatActive*} is used or alternate formatting is disabled. % % By themselves, they do not change format. Yet the macros \cmd{\AltOff} and \cmd{\AltOn}, described shortly, are able to turn the formatting of these macros on and off. We advise using \cmd{\noexpand} before these macros because they can be made to change format. Assuming that we have sorted the following names with \cmd{\PretagName} (Section~\ref{sec:IndexSort}), we get the following, using this manual's formatting conventions: % % \begin{VerbatimOut}{\jobname.tmp} % \Name[Konrad]{\noexpand\textSC{Zuse}}; % \Name[Konrad]{\noexpand\textSC{Zuse}}\\ % \Name[Ada]{\noexpand\textIT{Lovelace}}; % \Name[Ada]{\noexpand\textIT{Lovelace}}\\ % \Name[Charles]{\noexpand\textBF{Babbage}}; % \Name[Charles]{\noexpand\textBF{Babbage}}\\ % \Name{\noexpand\textUC{Kanade}, Takeo}; % \Name{\noexpand\textUC{Kanade}, Takeo} % \end{VerbatimOut} % % \begin{quote}\small % \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.\medskip % % Vaguely reminiscent of depressing\DescribeMacro{\AltOff}\ an automobile's manual clutch lever, \cmd{\AltOff} deactivates \cmd{\textSC}, \cmd{\textBF}, \cmd{\textIT}, and \cmd{\textUC} only in a formatting hook. The alternate formatting mechanism is still ``running'', but it is not transferring ``power'' to the formatting macros. They display their arguments unmodified.\medskip % % Likewise, \cmd{\AltOn}\DescribeMacro{\AltOn}\ activates \cmd{\textSC}, \cmd{\textBF}, \cmd{\textIT}, and \cmd{\textUC} only in a formatting hook, as if one let out the clutch pedal, causing ``power'' to transfer through the gearbox to the formatting macros. They now modify their arguments.\medskip % % If one uses the \texttt{altformat} option or \cmd{\AltFormatActive}, the formatting ``power'' goes to the formatting macros by default in order to have formatted names in the index. Otherwise, the normal formatting regime isolates formatting in the text, as the Anglosphere is wont to do. % % We use \cmd{\noexpand} as discussed and add a formatting hook to get changes in the text, not in the index. We also suspend this manual's formatting conventions: % % \ifdefined\NameauthDoTestFiles \edef\NameauthTestFile{test11_03.tex}\else % \edef\NameauthTestFile{\jobname.tmp}\fi % % \begin{VerbatimOut}{\NameauthTestFile} % \documentclass{article} % \input{compat.tex} % Included with nameauth; needed only if % % compiling on multiple TeX distros or LaTeX engines. % \usepackage{makeidx} % \usepackage[altformat]{nameauth} % \makeindex % % \PretagName[Konrad]{\noexpand\textSC{Zuse}}{Zuse, Konrad} % \PretagName[Ada]{\noexpand\textIT{Lovelace}}{Lovelace, Ada} % \PretagName[Charles]{\noexpand\textBF{Babbage}} % {Babbage, Charles} % \PretagName{\noexpand\textUC{Kanade}, Takeo}{Kanade Takeo} % % \begin{document} % % \renewcommand*\MainNameHook{\AltOff} % % \ForgetThis\Name[Konrad]{\noexpand\textSC{Zuse}}; % \Name[Konrad]{\noexpand\textSC{Zuse}}\\ % \ForgetThis\Name[Ada]{\noexpand\textIT{Lovelace}}; % \Name[Ada]{\noexpand\textIT{Lovelace}}\\ % \ForgetThis\Name[Charles]{\noexpand\textBF{Babbage}}; % \Name[Charles]{\noexpand\textBF{Babbage}}\\ % \ForgetThis\Name{\noexpand\textUC{Kanade}, Takeo}; % \Name{\noexpand\textUC{Kanade}, Takeo} % % \printindex % \end{document} % \end{VerbatimOut} % % \begin{quote}\small % \VerbatimInput[gobble=0]{\NameauthTestFile} % % \renewcommand*\NamesFormat{} % \renewcommand*\MainNameHook{\AltOff} % % \ForgetThis\Name[Konrad]{\noexpand\textSC{Zuse}}; % \Name[Konrad]{\noexpand\textSC{Zuse}}\\ % \ForgetThis\Name[Ada]{\noexpand\textIT{Lovelace}}; % \Name[Ada]{\noexpand\textIT{Lovelace}}\\ % \ForgetThis\Name[Charles]{\noexpand\textBF{Babbage}}; % \Name[Charles]{\noexpand\textBF{Babbage}}\\ % \ForgetThis\Name{\noexpand\textUC{Kanade}, Takeo}; % \Name{\noexpand\textUC{Kanade}, Takeo} % \end{quote} % % \AltFormatInactive % \endgroup^^A Local format hook redefinition % % \subsubsection{History Text} % \label{sec:RealAltEx} % \AltFormatActive % % \begingroup^^A Local format hook redefinition % % First we engage the idea of a history text, where we use standards for medieval Italian to encode a name instead of those used in modern Romance languages. % % \ifdefined\NameauthDoTestFiles \edef\NameauthTestFile{test11_04.tex}\else % \edef\NameauthTestFile{\jobname.tmp}\fi % % \begin{VerbatimOut}{\NameauthTestFile} % \documentclass{article} % \input{compat.tex} % Included with nameauth; needed only if % % compiling on multiple TeX distros or LaTeX engines. % \usepackage{makeidx} % \usepackage[altformat]{nameauth} % \makeindex % % \begin{nameauth} % \< Luth & Martin & \noexpand\textSC{Luther} & > % \< Cath & Catherine \noexpand\AltCaps{d}e' % & \noexpand\textSC{Medici} & > % \end{nameauth} % \PretagName[Martin]{\noexpand\textSC{Luther}}{Luther, Martin} % \PretagName[Catherine \noexpand\AltCaps{d}e'] % {\noexpand\textSC{Medici}}{Medici, Catherine de} % % \renewcommand*\MainNameHook{\sffamily\AltOff} % % \begin{document} % % \ForgetThis\Luth\ was a leading figure in the Protestant % Reformation. \Luth\ believed that one is declared % righteous in a forensic sense by divine grace through faith % created by the Holy Spirit via the Gospel and the Sacraments. % % \ForgetThis\Cath\ was not only Queen of France in her own right, % but she also guided the reigns of her three sons. % \CapThis\LCath[\noexpand\AltCaps{d}e'] % was blamed for the St.\ Bartholomew's Day massacre that saw the % murder of thousands of Huguenots. % % \printindex % \end{document} % \end{VerbatimOut} % % \renewcommand*\MainNameHook{\sffamily\AltOff} % \begin{quote}\small % \VerbatimInput[gobble=0]{\NameauthTestFile} % % \ForgetThis\Luth\ was a leading figure in the Protestant % Reformation. \Luth\ believed that one is declared % righteous in a forensic sense by divine grace through faith % created by the Holy Spirit via the Gospel and the Sacraments. % % \ForgetThis\Cath\ was not only Queen of France in her own right, % but she also guided the reigns of her three sons. % \CapThis\LCath[\noexpand\AltCaps{d}e'] % was blamed for the St.\ Bartholomew's Day massacre that saw the % murder of thousands of Huguenots. % \end{quote} % % Comparing the example above to Section~\ref{sec:NameParticles} shows us some differences. Medieval Italian, similar to modern German, keeps the particle(s) with the forename(s). Modern Italian groups particles and surnames together. Thus, we must use here: % % \begin{itemize} % \item \parbox{0.3\textwidth}{\LCath[\noexpand\AltCaps{d}e']} % |\LCath[\noexpand\AltCaps{d}e']| % \item \parbox{0.3\textwidth}{\CapThis\LCath[\noexpand\AltCaps{d}e']} % |\CapThis\LCath[\noexpand\AltCaps{d}e']| % \end{itemize} % \endgroup^^A Local format hook redefinition % % % \subsubsection{Inflected Names} % \label{sec:InflNames} % \begingroup^^A Local format hook redefinition % % Next we design grammatical inflections for use with alternate formatting. We do not use the general formatting conventions in this manual. We shall build on this example in order to design the more complex hooks used for Roman names. % % We need two Boolean flags for one change in name form, which is a grammatical inflection in this case. Thus, we set up \texttt{\textbackslash ifGenitive} as the global flag and \texttt{\textbackslash ifDoGenitive} as the local flag. % % \cmd{\DoGenitivetrue} occurs only in the formatting hook. The macro that produces the genitive (or possessive) ending only does so when \texttt{\textbackslash ifDoGenitive} is true. This keeps the index entries consistent via \cmd{\noexpand}. Likewise, \cmd{\AltOff} only occurs in the formatting hook \cmd{\MainNameHook}. % \JustIndex\Jeff % % \ifdefined\NameauthDoTestFiles \edef\NameauthTestFile{test11_05.tex}\else % \edef\NameauthTestFile{\jobname.tmp}\fi % % \begin{VerbatimOut}{\NameauthTestFile} % \documentclass{article} % \input{compat.tex} % Included with nameauth; needed only if % % compiling on multiple TeX distros or LaTeX engines. % \usepackage{makeidx} % \usepackage[altformat]{nameauth} % \makeindex % % \newif\ifGenitive % \newif\ifDoGenitive % % \newcommand*\GEN{\ifDoGenitive\textSC{'s}\fi} % % \begin{nameauth} % \< Jeff & Thomas & % \noexpand\textSC{Jefferson}\noexpand\GEN{} & > % \end{nameauth} % % \PretagName[Thomas]{\noexpand\textSC{Jefferson}\noexpand\GEN{}} % {Jefferson, Thomas} % \TagName[Thomas]{\noexpand\textSC{Jefferson}\noexpand\GEN{}} % {, pres.} % % \renewcommand*\NamesFormat[1] % {\ifGenitive\DoGenitivetrue\fi#1\global\Genitivefalse} % \renewcommand*\MainNameHook[1] % {\ifGenitive\DoGenitivetrue\fi\AltOff#1\global\Genitivefalse} % % \begin{document} % % Consider \Genitivetrue\Jeff\ legacy as the author of the % colonies' Declaration of Independence and his impact as third % president of the United States. \Jeff\ was a complex historical % figure whose actions defy a consistent moral compass both in % public policy and in personal affairs. % % \printindex % \end{document} % \end{VerbatimOut} % % \begin{quote}\small % \VerbatimInput[gobble=0]{\NameauthTestFile} % % \renewcommand*\NamesFormat[1] % {\ifGenitive\DoGenitivetrue\fi#1\global\Genitivefalse} % \renewcommand*\MainNameHook[1] % {\ifGenitive\DoGenitivetrue\fi\AltOff#1\global\Genitivefalse} % % Consider \Genitivetrue\Jeff\ legacy as the author of the % colonies' Declaration of Independence and his impact as third % president of the United States. \Jeff\ was a complex historical % figure whose actions defy a consistent moral compass both in % public policy and in personal affairs. % \end{quote} % \endgroup^^A Local format hook redefinition % % \subsubsection{Reference Work I} % \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: % % \begin{itemize} % \item Sort all names that use alternate formatting. % \item Match index entry forms to article head-words. Name variants % are cross-referenced to the name form in the head-word. % \item Ensure that the first appearance of a name displays only the % active alternate formatting. Any additional formatting comes from % the macro that formats entries. % \item Deactivate alternate formatting in subsequent name references. % \item Since some \LaTeX\ fonts do not combine small caps and boldface, % we instead use slanted text to set the head-words off from the articles. % That font switch is done in the macro that formats the articles % (\cmd{\RefArticle}). % \end{itemize} % % \ifdefined\NameauthDoTestFiles \edef\NameauthTestFile{test11_06.tex}\else % \edef\NameauthTestFile{\jobname.tmp}\fi % % \begin{VerbatimOut}{\NameauthTestFile} % \documentclass{article} % \input{compat.tex} % Included with nameauth; needed only if % % compiling on multiple TeX distros or LaTeX engines. % \usepackage{makeidx} % \usepackage[altformat]{nameauth} % \makeindex % % % Sort any names with macros in the arguments. % % \PretagName[Greta]{\noexpand\textSC{Garbo}}{Garbo, Greta} % \PretagName{\noexpand\textSC{Misora}, Hibari}{Misora Hibari} % \PretagName[Heinz]{\noexpand\textSC{R\"uhmann}}{Ruehmann, Heinz} % \PretagName[Heinrich Wilhelm]{\noexpand\textSC{R\"uhmann}} % {Ruehmann, Heinrich Wilhelm} % % % Make a cross-reference from a variant name form to the % % form of the head-words % % \IndexRef[Heinrich Wilhelm]{\noexpand\textSC{R\"uhmann}} % {\noexpand\textSC{R\"uhmann}, Heinz} % % % Define the formatting hooks. Since we use the `altformat' % % option, alternate formatting is turned off in later % % name uses. % % \renewcommand*\MainNameHook{\AltOff} % % % Typeset head-words with a slanted font. % % \newcommand{\RefArticle}[3] % {% % \def\check{#2}% % \ifx\check\empty % \noindent\ForgetThis\textsl{#1}\ #3 % \else % \noindent\ForgetThis\textsl{#1}\ #2\ #3 % \fi\medskip % } % % \begin{document} % % \RefArticle % {\RevComma\Name[Greta]{\noexpand\textSC{Garbo}}} % {} % {(18 September 1905\,--\,15 April 1990) was a Swedish % film actress during the 1920s and 1930s. % \Name[Greta]{\noexpand\textSC{Garbo}}\dots} % % \RefArticle % {\Name{\noexpand\textSC{Misora}, Hibari}} % {(W:\,``\RevName\Name*{\noexpand\textSC{Misora}, Hibari}'';} % {29 May 1937\,--\,24 June 1989) was a Japanese singer % and actress noted for her positive message. % \Name{\noexpand\textSC{Misora}, Hibari}\dots} % % \RefArticle % {\RevComma\Name[Heinz]{\noexpand\textSC{R\"uhmann}}} % {(\SubvertThis\ForceName % \FName[Heinrich Wilhelm]{\noexpand\textSC{R\"uhmann}};} % {7 March 1902\,--\,3 October 1994) was a German actor % in over 100 films. % \Name[Heinz]{\noexpand\textSC{R\"uhmann}}\dots} % % \printindex % \end{document} % \end{VerbatimOut} % % \begin{quote}\small % \VerbatimInput[gobble=0]{\NameauthTestFile} % % \IndexRef[Heinrich Wilhelm]{\noexpand\textSC{R\"uhmann}} % {\noexpand\textSC{R\"uhmann}, Heinz} % % \renewcommand*\NamesFormat{} % \renewcommand*\MainNameHook{\AltOff} % % \newcommand{\RefArticle}[3] % {^^A % \def\check{#2}^^A % \ifx\check\empty % \noindent\ForgetThis\textsl{#1}\ #3 % \else % \noindent\ForgetThis\textsl{#1}\ #2\ #3 % \fi\medskip % } % % \RefArticle % {\RevComma\Name[Greta]{\noexpand\textSC{Garbo}}} % {} % {(18 September 1905\,--\,15 April 1990) was a Swedish % film actress during the 1920s and 1930s. % \Name[Greta]{\noexpand\textSC{Garbo}}\dots} % % \RefArticle % {\Name{\noexpand\textSC{Misora}, Hibari}} % {(W:\,``\RevName\Name*{\noexpand\textSC{Misora}, Hibari}'';} % {29 May 1937\,--\,24 June 1989) was a Japanese singer % and actress noted for her positive message. % \Name{\noexpand\textSC{Misora}, Hibari}\dots} % % \RefArticle % {\RevComma\Name[Heinz]{\noexpand\textSC{R\"uhmann}}} % {(\SubvertThis\ForceName % \FName[Heinrich Wilhelm]{\noexpand\textSC{R\"uhmann}};} % {7 March 1902\,--\,3 October 1994) was a German actor % in over 100 films. % \Name[Heinz]{\noexpand\textSC{R\"uhmann}}\dots} % \end{quote} % % \endgroup^^A Local format hook redefinition % \AltFormatInactive % % \begin{Quote}{\Name[L.M.]{Montgomery}, % \textit{Anne of Green Gables}, C 5} % I read in a book once that a rose by any other name would smell as sweet, but I've never been able to believe it. I don't believe a rose \textsc{would} be as nice if it was called a thistle or a skunk cabbage. % \end{Quote} % % \newpage % % \subsection{Roman Names} % \label{sec:Romani} % % Roman names tend to be among the most variable in terms of treatment. As far as \textsf{nameauth} is concerned, they range from being treated as Western names to being treated in very special ways. Below we show some variations. % % \subsubsection[General Market]{Casual Reading / General Book Market} % % \begin{itemize} % \item Treat as a Western name, especially among well-known Roman names like % \Name*[M.T.]{Cicero}[Marcus Tullius], where the final name, \Cicero, is a % surname and the rest forenames:\footnote{Philip J. Adler, \textit{World % Civilizations}, 3rd ed. (Belmont, Calif.: Thomson/Wadsworth, 2003).} % % \begin{quote}\small % \begin{Verbatim} % \TagName[Julius]{Caesar}{, imperator} % for index % \Name[Julius]{Caesar}[Gaius Julius]\\ % \Name*[Julius]{Caesar}\\ % \Name[Julius]{Caesar} % \end{Verbatim} % \Name[Julius]{Caesar}[Gaius Julius]^^A % \PatInfo{\ShowPattern[Julius]{Caesar}[Gaius Julius]!MN}\\ % \Name*[Julius]{Caesar}\\ % \Name[Julius]{Caesar}\\[1ex] % Index: \ShowIdxPageref*[Julius]{Caesar}^^A % \end{quote} % % \item Treat as a Western name; put \textit{nomen} and \textit{cognomen} in % \meta{SNN}:\footnote{Paul L. Maier, \textit{In the Fullness of Time: A % Historian Looks at Christmas, Easter, and the Early Church}, revised ed. % (San Francisco: Harper, 1991).} % % \begin{quote}\small % \begin{Verbatim} % \ForgetThis\Name[Lucius]{Sergius Paulus}\\ % \Name[Lucius]{Sergius Paulus} % \end{Verbatim} % \ForgetThis\Name[Lucius]{Sergius Paulus}^^A % \PatInfo{\ShowPattern[Lucius]{Sergius Paulus}!MN}\\ % \Name[Lucius]{Sergius Paulus}\\[1ex] % Index: \ShowIdxPageref*[Lucius]{Sergius Paulus}^^A % \end{quote} % % \item Treat as ancient names, especially those with no \textit{praenomen}: % % \begin{quote}\small % \begin{Verbatim} % \ForgetThis\Name{Pontius, Pilate}[Pilatus]\\ % \Name*{Pontius, Pilate}\\ % \Name{Pontius, Pilate}\\ % \end{Verbatim} % \ForgetThis\Name{Pontius, Pilate}[Pilatus]^^A % \PatInfo{\ShowPattern{Pontius, Pilate}[Pilatus]!MN}\\ % \Name*{Pontius, Pilate}\\ % \Name{Pontius, Pilate}\\[1ex] % Index: \ShowIdxPageref*{Pontius, Pilate}^^A % \end{quote} % \end{itemize} % % 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{De bello gallico} 3.16.6} % Fere libenter homines, id quod volunt, credunt.\\ % (In general, people willingly believe what they want [to believe].) % \end{Quote} % % \newpage % % \subsubsection[Student Reference]{Student-Oriented Reference Works} % \AltFormatActive % % \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: % % \begin{itemize} % \item A personal name (\textit{praenomen}) % \item A clan name (\textit{nomen}) % \item A distinguishing name, sometimes denoting clan branches % (\textit{cognomen}); that could include various affixed names % (\textit{agnomina}) % \end{itemize} % % In ancient Rome, the family name (\textit{nomen}) was important, helping also to structure society.\footnote{\url{https://en.wikipedia.org/wiki/Patrician_(ancient_Rome)}} % The exact roles of names changed over time.\footnote{\url{https://en.wikipedia.org/wiki/Roman_naming_conventions}} % A very \href{https://www.youtube.com/watch?v=RMLb1jVl_Uo}{helpful video} can be found on the YouTube channel PolýMATHY by \Name[Luke]{Ranieri}. % % Some reference works treat the \textit{cognomen} as if it were a Western surname.\footnote{See Geiss, \textit{Geschichte Griffbereit}; Kinder and Hilgemann, \textit{dtv-Atlas zur Weltgeschichte}, 2 vols., 29th printing (1964; Munich: Deutscher Taschenbuch Verlag, 1993). See also \href{https://books.infotoday.com/books/Indexing-names.shtml}{\bfseries this page}.} % Using this approach, Roman names encoded with \textsf{nameauth} have this form: % % \begin{quote} % Index: \ShowIdxPageref*[\meta{praenomen} \meta{nomen}] % {\meta{cognomen} \meta{agnomen}}\\[1ex] % Macro: |\Name[|\meta{praenomen}| |\meta{nomen}|]{|\meta{cognomen}|,| % \meta{agnomen}|}| % \end{quote} % % With both \textit{praenomen} and \textit{nomen} in \meta{FNN}, as well as the \textit{agnomina} in \meta{Affix}, they drop automatically in subsequent name uses. With a \textit{cognomen} as an effective surname, our choices for name components in the text take on this logic: % % \begin{itemize} % \item Display one of the following in \meta{FNN}: % \begin{itemize} % \item Only the \textit{praenomen} % \item Only the \textit{nomen} % \item Both \textit{praenomen} and \textit{nomen} % \end{itemize} % % \item Display one of the following in \meta{SNN}: % \begin{itemize} % \item Only the \textit{cognomen} % \item Both \textit{cognomen} and \textit{agnomina} % \end{itemize} % \end{itemize} % % We accomplish this by using macros in the name arguments: % % \begin{itemize} % \item If the macros in the name arguments will be ``segmented'' in some % way, as \cmd{\CapThis} does, then use alternate formatting % (Sections~\ref{sec:AltFormat}). % \item When using Boolean flags (\texttt{\textbackslash if}\meta{flag}) in % the macros that represent name elements, ensure that those flags only change % their value within the local scope of the name formatting hooks % (Section~\ref{sec:Formatting}). % \item Two Boolean flags are needed for each automated variant in the name. One % flag reflects the global state and the name form in the index. The other % reflects the local state of the formatting hooks. % \end{itemize} % % \negmedskip % \NameArgWarning % % Since we have four name components, we need at most eight Boolean flags. Our two examples each use six flags, with four in common and one separate pair each. In the preamble we define all macros and conditionals used in naming macro arguments. Instead of \texttt{\textbackslash ifNoNomen} we use \texttt{\textbackslash ifNoGens} for readability. % % We must use \cmd{\noexpand} in the macro arguments. We define macros in both \meta{FNN} and \meta{SNN} that expand conditionally. We use the quick interface to define name shorthands, and we sort the name with \cmd{\PretagName}. False Boolean flags display longer name forms. True flags display shorter forms. % % We used \cmd{\PretagName} and \cmd{\TagName} as needed (cf. Section~\ref{sec:NameAncient}. These formatting hooks used with Roman names also work with other name types. % % \ifdefined\NameauthDoTestFiles \edef\NameauthTestFile{test11_07.tex}\else % \edef\NameauthTestFile{\jobname.tmp}\fi % % \begin{VerbatimOut}{\NameauthTestFile} % \documentclass{article} % \input{compat.tex} % Included with nameauth; needed only if % % compiling on multiple TeX distros or LaTeX engines. % \usepackage{makeidx} % \usepackage[altformat]{nameauth} % \makeindex % % % Global Boolean flags need to be defined only once. % \newif\ifNoPraenomen % \newif\ifNoCognomen % \newif\ifNoGens % \newif\ifNoAgnomen % % % Local Boolean flags need to be defined only once. % \newif\ifXPrae % \newif\ifXCogn % \newif\ifXGens % \newif\ifXAgno % % % Name variant macros need to be defined uniquely for each % % name. First is Scipio. Second is Gracchus. % % \newcommand*\SCIPi % {% % \ifXGens Publius\else % \ifXPrae Cornelius\else % Publius Cornelius% % \fi % \fi % } % % \newcommand*\SCIPii % {% % \ifXAgno Scipio\else % Scipio Africanus% % \fi % } % % \newcommand*\TSemp % {% % \ifXGens Tiberius\else % \ifXPrae Sempronius\else % Tiberius Sempronius% % \fi % \fi % } % % % Quick interface definitions. The first shows % % the concept of Roman names without extra features. % % The second (Gracchus) adds name info tags. % % \begin{nameauth} % \< Scipio & \noexpand\SCIPi & \noexpand\SCIPii & > % \< TGrac & \noexpand\TSemp & Gracchus & > % \end{nameauth} % % % We add the name data tag. % \NameAddInfo[\noexpand\TSemp]{Gracchus} % { (consul, 177 \textsc{bc})} % % % Sorting and tagging the names % \PretagName[\noexpand\SCIPi]{\noexpand\SCIPii} % {Scipio Africanus} % \PretagName[\noexpand\TSemp]{Gracchus} % {Gracchus, Tiberius Sempronius} % \TagName[\noexpand\TSemp]{Gracchus}{, consul} % % \begin{document} % % % Although it is helpful to set everything up % % In the preamble, it is not absolutely necessary. % % Here we define the simpler set of formatting hooks % % for Scipio, although the complex hooks will work % % for both equally as well. % % \renewcommand*\NamesFormat[1] % {% % \ifNoPraenomen\XPraetrue\fi% % \ifNoGens\XGenstrue\fi% % \ifNoCognomen\XCogntrue\fi% % \ifNoAgnomen\XAgnotrue\fi% % #1% % \global\NoPraenomenfalse% % \global\NoGensfalse% % \global\NoCognomenfalse% % \global\NoAgnomenfalse% % } % % \renewcommand*\MainNameHook[1] % {% % \ifNoPraenomen\XPraetrue\fi% % \ifNoGens\XGenstrue\fi% % \ifNoCognomen\XCogntrue\fi% % \ifNoAgnomen\XAgnotrue\fi% % #1% % \global\NoPraenomenfalse% % \global\NoGensfalse% % \global\NoCognomenfalse% % \global\NoAgnomenfalse% % } % % \Scipio\ was born around 236 \textsc{bc} into the % Scipiones branch of the Cornelii clan. % \NoAgnomentrue\Scipio\ rose to military fame during the % Second Punic War. Thereafter he was known as \Scipio. % He flourished during the Egyptian reigns of % \Name{Ptolemy, IV}[IV Philopator] and % \Name{Ptolemy, V}[V Epiphanes], and the Syrian % reigns of \Name{Seleucus, III}[III Ceraunus] and % \Name{Antiochus, III}[III the Great]. % % % We make no change to \MainNameHook, but we do % % change \NamesFormat to display any extant % % name data tags. % % \renewcommand*\NamesFormat[1] % {% % \ifNoPraenomen\XPraetrue\fi% % \ifNoGens\XGenstrue\fi% % \ifNoCognomen\XCogntrue\fi% % \ifNoAgnomen\XAgnotrue\fi% % #1% % \ifcsname\NameauthPattern!DB\endcsname % \expandafter\csname\NameauthPattern!DB\endcsname% % \fi % \global\NoPraenomenfalse% % \global\NoGensfalse% % \global\NoCognomenfalse% % \global\NoAgnomenfalse% % } % % \TGrac\ served as tribune of the plebs in 184 \textsc{bc}. % \NoGenstrue\STGrac\ was elected praetor for 180 \textsc{bc}, % after which he was appointed governor of Hispania Citerior. % serving with the rank of proconsul. In 177 \textsc{bc}, % he was elected consul, again in 163 \textsc{bc}. % % \printindex % \end{document} % \end{VerbatimOut} % % \begin{quote} % \VerbatimInput[gobble=0, lastline=74]{\NameauthTestFile} % \end{quote} % % Formatting hook macros need to be redefined only once. We reset the global Boolean flags to ensure the longest name forms in the index. The local Boolean flags automatically revert to false outside the scope of the formatting hooks. % % \renewcommand*\NamesFormat[1] % {^^A % \ifNoPraenomen\XPraetrue\fi^^A % \ifNoGens\XGenstrue\fi^^A % \ifNoCognomen\XCogntrue\fi^^A % \ifNoAgnomen\XAgnotrue\fi^^A % #1^^A % \global\NoPraenomenfalse^^A % \global\NoGensfalse^^A % \global\NoCognomenfalse^^A % \global\NoAgnomenfalse^^A % } % % \renewcommand*\MainNameHook[1] % {^^A % \ifNoPraenomen\XPraetrue\fi^^A % \ifNoGens\XGenstrue\fi^^A % \ifNoCognomen\XCogntrue\fi^^A % \ifNoAgnomen\XAgnotrue\fi^^A % #1^^A % \global\NoPraenomenfalse^^A % \global\NoGensfalse^^A % \global\NoCognomenfalse^^A % \global\NoAgnomenfalse^^A % } % \begin{quote}\small % \VerbatimInput[gobble=0, firstline=75, lastline=87]{\NameauthTestFile} % % \newpage % % \VerbatimInput[gobble=0, firstline=88, lastline=110]{\NameauthTestFile} % % \Scipio\ was born around 236 \textsc{bc} into the % Scipiones branch of the Cornelii clan. % \NoAgnomentrue\Scipio\ rose to military fame during the % Second Punic War. Thereafter he was known as \Scipio. % He flourished during the Egyptian reigns of % \Name{Ptolemy, IV}[IV Philopator] and % \Name{Ptolemy, V}[V Epiphanes], and the Syrian % reigns of \Name{Seleucus, III}[III Ceraunus] and % \Name{Antiochus, III}[III the Great]. % \end{quote} % % Below we show more name name variations than were shown above. In addition, we use those same formatting hooks to display non-Roman names: % % \begin{Block} % |\ForgetThis\Scipio|\dotfill\ForgetThis\Scipio\\ % |\LScipio|\dotfill\LScipio\\ % |\Scipio|\dotfill\Scipio\\ % |\SScipio|\dotfill\SScipio\\[2ex] % |\NoAgnomentrue\LScipio|\dotfill\NoAgnomentrue\LScipio\\ % |\NoAgnomentrue\Scipio|\dotfill\NoAgnomentrue\Scipio\\ % |\NoGenstrue\SScipio|\dotfill\NoGenstrue\SScipio\\ % |\NoPraenomentrue\SScipio|\dotfill\NoPraenomentrue\SScipio\\[2ex] % |\Name*{Ptolemy, IV}[IV Philopator]|\dotfill\Name*{Ptolemy, IV}[IV Philopator]\\ % |\Name*{Ptolemy, IV}|\dotfill\Name*{Ptolemy, IV}\\ % |\Name{Ptolemy, IV}|\dotfill\Name{Ptolemy, IV} % \end{Block} % % In Section~\ref{sec:NameAncient}, we used name data tags instead of \meta{Alternate} in the first-use formatting hook. Here we show the changes needed to add name data tags to the first-use formatting hook. Even though we are changing the formatting hooks throughout the document, none of the changes cause different index entries and will be unnoticed in the finished document. % % \NameAddInfo[\noexpand\TSemp]{Gracchus} % { (consul, 177 \textsc{bc})} % \renewcommand*\NamesFormat[1] % {^^A % \ifNoPraenomen\XPraetrue\fi^^A % \ifNoGens\XGenstrue\fi^^A % \ifNoCognomen\XCogntrue\fi^^A % \ifNoAgnomen\XAgnotrue\fi^^A % #1^^A % \ifcsname\NameauthPattern!DB\endcsname % \expandafter\csname\NameauthPattern!DB\endcsname^^A % \fi % \global\NoPraenomenfalse^^A % \global\NoGensfalse^^A % \global\NoCognomenfalse^^A % \global\NoAgnomenfalse^^A % } % \begin{quote}\small % \VerbatimInput[gobble=0,firstline=111]{\NameauthTestFile} % % \TGrac\ served as tribune of the plebs in 184 \textsc{bc}. % \NoGenstrue\STGrac\ was elected praetor for 180 \textsc{bc}, % after which he was appointed governor of Hispania Citerior. % serving with the rank of proconsul. In 177 \textsc{bc}, % he was elected consul, again in 163 \textsc{bc}. % \end{quote} % % Below we show both a Roman name and a different name type working the same way with the formatting hook: % % \begin{Block} % |\ForgetThis\TGrac|\dotfill\ForgetThis\TGrac\\ % |\LTGrac|\dotfill\LTGrac\\ % |\NoGenstrue\LTGrac|\dotfill\NoGenstrue\LTGrac\\ % |\TGrac|\dotfill\TGrac\\ % |\STGrac|\dotfill\STGrac\\ % |\NoGenstrue\STGrac|\dotfill\NoGenstrue\STGrac\\ % |\NoPraenomentrue\STGrac|\dotfill\NoPraenomentrue\STGrac\\[2ex] % |\ForgetThis\Dem|\dotfill\ForgetThis\Dem\\ % |\LDem|\dotfill\LDem\\ % |\Dem|\dotfill\Dem % \end{Block} % % \begin{Quote}{\ForgetThis\Scipio\break % \hbox{}\hfill attributed by \Name[Titus]{Livius} in % \textit{Ab urbe condita} B 30} % Bellum parate, quoniam pacem pati non potuistis.\\ % (Prepare for war, for it seems that you are unable to tolerate peace.) % \end{Quote} % % \newpage % % \subsubsection[Scholarly Reference]{Scholarly Reference Works} % % The \textit{Oxford Classical Dictionary} and other scholarly sources index according to the \textit{nomen}. That approach moves the \textit{nomen} from \meta{FNN} to \meta{SNN} thus: % % \begin{quote} % Index: \ShowIdxPageref*[\meta{praenomen}]{\meta{nomen} \meta{cognomen} % \meta{agnomen}}\\[1ex] % Macro: |\Name[|\meta{praenomen}|]{|\meta{nomen} \meta{cognomen} % \meta{agnomen}|}| % \end{quote} % % This indexing method is incompatible with the previous section, but we show both in this manual. We retain most of the code used in the last section, but we change the macros used in the name arguments. The logic still shows all names for the index, but we make different choices in the text: % % \begin{itemize} % \item Display the \textit{praenomen} in \meta{FNN}: % \item Display one of the following in \meta{SNN}: % \begin{itemize} % \item Only the \textit{cognomen} % \item Both the \textit{cognomen} and \textit{agnomina} % \item Only the \textit{nomen} % \item Both the \textit{nomen} and \textit{cognomen} % \item The \textit{nomen}, \textit{cognomen}, and \textit{agnomina} % \end{itemize} % \end{itemize} % % \ifdefined\NameauthDoTestFiles \edef\NameauthTestFile{test11_08.tex}\else % \edef\NameauthTestFile{\jobname.tmp}\fi % % \begin{VerbatimOut}{\NameauthTestFile} % \documentclass{article} % \input{compat.tex} % Included with nameauth; needed only if % % compiling on multiple TeX distros or LaTeX engines. % \usepackage{makeidx} % \usepackage[altformat]{nameauth} % \makeindex % % % Global Boolean flags need to be defined only once. % \newif\ifNoPraenomen % \newif\ifNoCognomen % \newif\ifNoGens % \newif\ifNoAgnomen % % % Local Boolean flags need to be defined only once. % \newif\ifXPrae % \newif\ifXCogn % \newif\ifXGens % \newif\ifXAgno % % % Name variant macros need to be defined % % uniquely for each name. % % \newcommand*\CSB % {% % \ifXGens % \ifXAgno Scipio\else % Scipio Barbatus\fi % \else % \ifXCogn Cornelius\else % \ifXAgno Cornelius Scipio\else % Cornelius Scipio Barbatus% % \fi % \fi % \fi % } % % % Quick interface definition % \begin{nameauth} % \< OScipio & Lucius & \noexpand\CSB & > % O for Oxford % \end{nameauth} % % % Sorting and tagging % \PretagName[Lucius]{\noexpand\CSB}{Cornelius Scipio Barbatus} % \TagName[Lucius]{\noexpand\CSB}{, consul} % % \renewcommand*\NamesFormat[1] % {% % \ifNoPraenomen\XPraetrue\fi% % \ifNoGens\XGenstrue\fi% % \ifNoCognomen\XCogntrue\fi% % \ifNoAgnomen\XAgnotrue\fi% % #1% % \ifcsname\NameauthPattern!DB\endcsname % \expandafter\csname\NameauthPattern!DB\endcsname% % \fi % \global\NoPraenomenfalse% % \global\NoGensfalse% % \global\NoCognomenfalse% % \global\NoAgnomenfalse% % } % % \begin{document} % % \OScipio\ was born around 337 \textsc{bc} into the % Scipiones branch of the Cornelii clan, one of the large % patrician clans. \NoGenstrue\NoAgnomentrue\OScipio\ was % one of the two elected consuls in 298 \textsc{bc} % and served during the Third Samnite War. % % \printindex % \end{document} % \end{VerbatimOut} % % \begin{quote}\small % \VerbatimInput[gobble=0]{\NameauthTestFile} % % \OScipio\ was born around 337 \textsc{bc} into the % Scipiones branch of the Cornelii clan, one of the large % patrician clans. \NoGenstrue\NoAgnomentrue\OScipio\ was % one of the two elected consuls in 298 \textsc{bc} % and served during the Third Samnite War. % \end{quote} % % Instead of relying on some \textsf{nameauth} features that drop some names automatically, in all but \meta{FNN} we have to state explicitly what we want: % % \begin{Block} % |\ForgetThis\OScipio|\dotfill\ForgetThis\OScipio\\ % |\LOScipio|\dotfill\LOScipio\\ % |\OScipio|\dotfill\OScipio\\ % |\SOScipio|\dotfill\SOScipio\\[2ex] % |\NoCognomentrue\OScipio|\dotfill\NoCognomentrue\OScipio\\ % |\NoAgnomentrue\OScipio|\dotfill\NoAgnomentrue\OScipio\\ % |\NoGenstrue\OScipio|\dotfill\NoGenstrue\OScipio\\ % |\NoGenstrue\NoAgnomentrue\OScipio|\dotfill\NoGenstrue\NoAgnomentrue\OScipio % \end{Block} % % One may create convenience macros instead of using the Boolean flags. Yet this might make things less clear at first glance, for example: % % \begin{Block} % \newcommand*\LucScipio{\NoGenstrue\NoAgnomentrue\OScipio} % |\newcommand*\LucScipio{\NoGenstrue\NoAgnomentrue\OScipio}|\\ % |\ForgetThis\LucScipio|\dotfill\ForgetThis\LucScipio\\ % |\LucScipio|\dotfill\LucScipio % \end{Block} % % The student and scholarly forms of Roman names are incompatible. Yet we show what the index entries would be in a normal \LaTeX document without hyperlinks: % % \begin{quote}\small % \IndexActual{@} % \UntagName[\noexpand\SCIPi]{\noexpand\SCIPii} % \TagName[\noexpand\TSemp]{Gracchus}{, consul} % \TagName[Lucius]{\noexpand\CSB}{, consul} % {\normalsize Popular Reference Works:}\\ % |\ShowIdxPageref[\noexpand\SCIPi]{\noexpand\SCIPii}|\\ % \ShowIdxPageref[\noexpand\SCIPi]{\noexpand\SCIPii}\\[1ex] % |\ShowIdxPageref[\noexpand\TSemp]{Gracchus}|\\ % \ShowIdxPageref[\noexpand\TSemp]{Gracchus}\\[1ex] % {\normalsize Scholarly Reference Works:}\\ % |\ShowIdxPageref[Lucius]{\noexpand\CSB}|\\ % \ShowIdxPageref[Lucius]{\noexpand\CSB} % \TagName[\noexpand\SCIPi]{\noexpand\SCIPii}{\string|hyperpage} % \TagName[\noexpand\TSemp]{Gracchus}{, consul\string|hyperpage} % \TagName[Lucius]{\noexpand\CSB}{, consul\string|hyperpage} % \end{quote} % \endgroup^^A Local format hook redefinition % \AltFormatInactive % % \subsection[Special Uses]{Special Name Uses} % \label{sec:SpecialUses} % % \AltFormatActive % \begingroup^^A Local format hook redefinition % Previously, formatting hooks either changed typefaces or mutated their arguments. Now we move beyond parsing the argument as we have received it.\medskip % % \DescribeMacro{\NameParser} % The user-accessible parser (Section~\ref{sec:NameParser}) builds a printed name from internal, locally-scoped macros. Its output is affected by a subset of the Boolean flags, namely, those flags that affect long and short forms, as well as name reversal. Within the hooks we can use the user-accessible parser as often as we want. % % \begin{itemize} % \item |\if@nameauth@FullName| toggles long or short name forms, as in % \cmd{\Name} versus \cmd{\Name*}. |\if@nameauth@FirstName| toggles % forenames when |\if@nameauth@FullName| is false. When modifying % these flags, one must know when they are normally true or false. % \item |\if@nameauth@RevThis| reverses name order. % \cmd{\ForceFN} normally toggles |\if@nameauth@EastFN|. % Using |\if@nameauth@RevThis|, reversing without commas, % overrides |\if@nameauth@RevThisComma| if both are true. % \item |\if@nameauth@RevThisComma| creates the form % \meta{SNN}, \meta{FNN}. % \end{itemize} % % Two Boolean\Info{\texttt{\textbackslash ifNameauthWestern}\break \texttt{\textbackslash ifNameauthObsolete}} flags are available to users so that they can know quickly what type of name was processed most recently by \cmd{\@nameauth@Choice}, which is called by all macros that take name arguments. These allow hook designers to vary the hook behavior based on the name type. They also persist after the macro that uses name arguments exits, unlike many other flags. % % \begin{center}\small\medstretch % \begin{tabular}{lccl}\toprule % Boolean flag & True & False & Name Type\\ % \midrule % \texttt{\textbackslash ifNameauthWestern} & \YES & \NO & Western\\ % \texttt{\textbackslash ifNameauthObsolete} & \NO & \NO\\\midrule % \texttt{\textbackslash ifNameauthWestern} & \NO & \YES & Non-Western\\ % \texttt{\textbackslash ifNameauthObsolete} & \NO & \NO & current syntax\\ % \midrule % \texttt{\textbackslash ifNameauthWestern} & \NO & \YES & Non-Western\\ % \texttt{\textbackslash ifNameauthObsolete} & \NO & \YES & obsolete syntax\\ % \bottomrule % \end{tabular} % \end{center} % % Since we are using the \texttt{altformat} option or \cmd{\AltFormatActive}, we can expect that formatting is activated by default. We design a subsequent-use hook that deactivates alternate formatting inside of it: % % \begin{SyntaxBox} % \cmd{\renewcommand*}\meta{SubsequentHook}\texttt{[1]\{\dots}\cmd % {\AltOff}\cmd{\NameParser}\texttt{\dots\}} % \end{SyntaxBox} % % If we used \cmd{\AltFormatActive*}, where the formatting macros are enabled, but deactivated by default, then we might want a hook that activates the macros: % % \begin{SyntaxBox} % \cmd{\renewcommand*}\meta{Hook}\texttt{[1]\{\dots}\cmd{\AltOn}\cmd % {\NameParser}\texttt{\dots\}} % \end{SyntaxBox} % \negmedskip % % \subsubsection{Reference Work II} % % Below we revisit the idea of a reference work, leveraging the formatting hooks to format headwords, add information from name info tags: % % \ifdefined\NameauthDoTestFiles \edef\NameauthTestFile{test11_09.tex}\else % \edef\NameauthTestFile{\jobname.tmp}\fi % % \begin{VerbatimOut}{\NameauthTestFile} % \documentclass{article} % \input{compat.tex} % Included with nameauth; needed only if % % compiling on multiple TeX distros or LaTeX engines. % \usepackage{makeidx} % \usepackage[altformat]{nameauth} % \makeindex % % % Boolean flags; the first sets up headwords and the second % % indicates that a non-Western form should not be reversed. % \newif\ifHeadword % \newif\ifAncientName % % % Sorting and tagging the names: % \PretagName[Charles]{\noexpand\textBF{Babbage}}{Babbage, Charles} % \PretagName{\noexpand\textUC{Kanade}, Takeo}{Kanade Takeo} % \PretagName[Ada]{\noexpand\textIT{Lovelace}}{Lovelace, Ada} % % % Adding name information: % \NameAddInfo{Aristotle}{ (384--322 \textsc{bc})} % \NameAddInfo[Charles]{\noexpand\textBF{Babbage}}{ (1791--1871)} % \NameAddInfo{\noexpand\textUC{Kanade}, Takeo}{ (1945-- )} % \NameAddInfo[Ada]{\noexpand\textIT{Lovelace}} % { (Augusta Ada King, Countess of Lovelace % [n\'ee Byron]; 1815--52)} % % % Redefining the formatting hooks: % \makeatletter % \renewcommand\NamesFormat[1] % {% % \ifHeadword % \ifNameauthWestern % \@nameauth@RevThisCommatrue% % \bfseries \NameParser% % \normalfont% % \ifcsname\NameauthPattern!DB\endcsname % \expandafter\csname\NameauthPattern!DB\endcsname% % \fi % \else % \bgroup% % \bfseries \NameParser% % \unless\ifAncientName % \normalfont; W:\AltOff\space % \@nameauth@RevThistrue \NameParser% % \fi % \normalfont% % \ifcsname\NameauthPattern!DB\endcsname % \expandafter\csname\NameauthPattern!DB\endcsname% % \fi % \egroup% % \fi % \else % \NameParser% % \fi % \global\Headwordfalse% % \global\AncientNamefalse% % } % \makeatother % \renewcommand\MainNameHook{\AltOff} % % % Define related macros: % \newcommand\Headword{\Headwordtrue\ForgetThis} % \newcommand{\RefArticle}[2] % {% % \noindent\Headword #1 #2% % \medskip % } % % \begin{document} % % \RefArticle{\AncientNametrue\Name{Aristotle}}{was the first to offer % a system of logic, most notably syllogistic logic, that would % become the basis for discrete states and circuitry of % digital computers. \Name{Aristotle}\dots} % % \RefArticle{\Name[Charles]{\noexpand\textBF{Babbage}}}{designed and % built the Difference Engine and began work on the Analytical % Engine. \Name[Charles]{\noexpand\textBF{Babbage}}\dots} % % \RefArticle{\Name{\noexpand\textUC{Kanade}, Takeo}}{is one of the % foremost pioneers in the field of computer vision. % \Name{\noexpand\textUC{Kanade}, Takeo}\dots} % % \RefArticle{\Name[Ada]{\noexpand\textIT{Lovelace}}}{collaborated with % \Name*[Charles]{\noexpand\textBF{Babbage}}* and wrote what some % consider to be the first computer program for the Analytical % Engine. \Name[Ada]{\noexpand\textIT{Lovelace}}\dots} % % \printindex % \end{document} % \end{VerbatimOut} % % \begin{quote}\small % \VerbatimInput[gobble=0]{\NameauthTestFile} % % \NameAddInfo{Aristotle}{ (384--322 \textsc{bc})} % \NameAddInfo[Charles]{\noexpand\textBF{Babbage}}{ (1791--1871)} % \NameAddInfo{\noexpand\textUC{Kanade}, Takeo}{ (1945-- )} % \NameAddInfo[Ada]{\noexpand\textIT{Lovelace}} % { (Augusta Ada King, Countess of Lovelace % [n\'ee Byron]; 1815--52)} % % \makeatletter % \renewcommand\NamesFormat[1] % {^^A % \ifHeadword % \ifNameauthWestern % \@nameauth@RevThisCommatrue^^A % \bfseries \NameParser^^A % \normalfont^^A % \ifcsname\NameauthPattern!DB\endcsname % \expandafter\csname\NameauthPattern!DB\endcsname^^A % \fi % \else % \bgroup^^A % \bfseries \NameParser^^A % \unless\ifAncientName % \normalfont; W:\AltOff\space % \@nameauth@RevThistrue \NameParser^^A % \fi % \normalfont^^A % \ifcsname\NameauthPattern!DB\endcsname % \expandafter\csname\NameauthPattern!DB\endcsname^^A % \fi % \egroup^^A % \fi % \else % \NameParser^^A % \fi % \global\Headwordfalse^^A % \global\AncientNamefalse^^A % } % \makeatother % \renewcommand\MainNameHook{\AltOff} % % \newcommand\Headword{\Headwordtrue\ForgetThis} % \newcommand{\RefArticle}[2] % {^^A % \noindent\Headword #1 #2^^A % \medskip % } % % \RefArticle{\AncientNametrue\Name{Aristotle}}{was the first to offer % a system of logic, most notably syllogistic logic, that would % become the basis for discrete states and circuitry of % digital computers. \Name{Aristotle}\dots} % % \RefArticle{\Name[Charles]{\noexpand\textBF{Babbage}}}{designed and % built the Difference Engine and began work on the Analytical % Engine. \Name[Charles]{\noexpand\textBF{Babbage}}\dots} % % \RefArticle{\Name{\noexpand\textUC{Kanade}, Takeo}}{is one of the % foremost pioneers in the field of computer vision. % \Name{\noexpand\textUC{Kanade}, Takeo}\dots} % % \RefArticle{\Name[Ada]{\noexpand\textIT{Lovelace}}}{collaborated with % \Name*[Charles]{\noexpand\textBF{Babbage}}* and wrote what some % consider to be the first computer program for the Analytical % Engine. \Name[Ada]{\noexpand\textIT{Lovelace}}\dots} % \end{quote} % % \subsubsection{Marginalia} % % \ifdefined\NameauthDoTestFiles \edef\NameauthTestFile{test11_10.tex}\else % \edef\NameauthTestFile{\jobname.tmp}\fi % % \begin{VerbatimOut}{\NameauthTestFile} % \documentclass{article} % \input{compat.tex} % Included with nameauth; needed only if % % compiling on multiple TeX distros or LaTeX engines. % \usepackage{makeidx} % \usepackage[altformat]{nameauth} % \makeindex % % % Global Boolean flags need to be defined only once. % \newif\ifSpecialFN % \newif\ifSpecialSN % \newif\ifRevertSN % % % Name variant macros need to be defined % % uniquely for each name. % % % For a long name, we want to use ``William'' in the text % % and ``Wm.'' in the margin. % % \newcommand*\WM % {% % \ifSpecialFN Wm.\else % William\fi % } % % % The first surname use will be ``Shakespeare'', but ``the % % Bard'' thereafter. We allow for alternate caps. % % We can get ``Shakespeare'' thereafter by toggling a flag. % % \newcommand*\SHK % {% % \ifRevertSN % \textSC{Shakespeare}\else % \ifSpecialSN % \noexpand\AltCaps{t}he Bard\else % \textSC{Shakespeare}% % \fi % \fi % } % % % Here is how we toggle that flag. % % \newcommand*\Revert{\RevertSNtrue} % % % Quick interface name definition: % % \begin{nameauth} % \< Shak & \noexpand\WM & \noexpand\SHK & > % \end{nameauth} % % % Sorting and tagging the name: % % \PretagName[\noexpand\WM]{\noexpand\SHK} % {Shakespeare, William} % \PretagName[Robert]{\textSC{Burns}}{Burns, Robert} % % % The ``first-use'' hook prints a name, then tries % % to insert a margin note using a different name form % % and the user-accessible parser. Finally it resets % % the reversion flag, which is only effective in the % % ``subsequent-use'' hook. Note how macros in the % % name arguments take the role of what the internal % % Boolean flags might otherwise handle. % % \makeatletter % \renewcommand*\NamesFormat[1] % {% % \RevertSNfalse\SpecialFNfalse\SpecialSNfalse% % #1% % \unless\ifinner % \marginpar % {% % \footnotesize\raggedleft% % \SpecialFNtrue\SpecialSNfalse% % \NameParser% % }% % \fi % \global\RevertSNfalse% % } % % \renewcommand*\MainNameHook[1] % {% % \AltOff\SpecialFNfalse\SpecialSNtrue% % #1% % \unless\ifinner % \unless\ifRevertSN % \marginpar % {% % \footnotesize\raggedleft% % \SpecialFNfalse\SpecialSNfalse% % \NameParser% % }% % \fi % \fi % \global\RevertSNfalse% % } % \makeatother % % \begin{document} % % \ForgetThis\Shak\ is the national poet of England % in much the same way that \Name[Robert]{\textSC{Burns}} % is that of Scotland. With the latter's rise of influence % in the 1800s, \Revert\Shak\ became known as ``\Shak''. % % \printindex % \end{document} % \end{VerbatimOut} % % Starting where we left off with Roman names, we begin in the document preamble by defining Boolean flags and macros. As with Roman names, their default values produce the name form in the index entry. The default name form aligns with the default Boolean flag setting: false. All non-default values and expansions of these macros occur only in the formatting hooks. We use \cmd{\PretagName} to sort the names. \cmd{\Revert} is used to print a last name without a margin note. % % \begin{quote} % \VerbatimInput[gobble=0,lastline=39]{\NameauthTestFile} % \end{quote} % % Next we define the two formatting hooks that structure the ways in which these macros can expand when printed in the text. We force \cmd{\NamesFormat} to print only allows only the default name via \cmd{\RevertSNfalse}, \cmd{\SpecialFNfalse}, and \cmd{\SpecialSNfalse}. \cmd{\MainNameHook} disables alternate formatting with \cmd{\AltOff}, but it allows variant name forms. % % We print the default name in the body text. If allowed, we print a margin paragraph with an alternate full name using \cmd{\NameParser}. Both hooks set \cmd{\RevertSNfalse} on exit, so that \cmd{\Revert} works on a per-name basis. % % \makeatletter % \renewcommand*\NamesFormat[1] % {^^A % \RevertSNfalse\SpecialFNfalse\SpecialSNfalse^^A % #1^^A % \unless\ifinner % \marginpar % {^^A % \footnotesize\raggedleft^^A % \SpecialFNtrue\SpecialSNfalse^^A % \NameParser^^A % }^^A % \fi % \global\RevertSNfalse^^A % } % \renewcommand*\MainNameHook[1] % {^^A % \AltOff\SpecialFNfalse\SpecialSNtrue^^A % #1^^A % \unless\ifinner % \unless\ifRevertSN % \marginpar % {^^A % \footnotesize\raggedleft^^A % \SpecialFNfalse\SpecialSNfalse^^A % \NameParser^^A % }^^A % \fi % \fi % \global\RevertSNfalse^^A % } % \makeatother % \begin{quote}\small % \VerbatimInput[gobble=0,firstline=40]{\NameauthTestFile} % % \ForgetThis\Shak\ is the national poet of England % in much the same way that \Name[Robert]{\textSC{Burns}} % is that of Scotland. With the latter's rise of influence % in the 1800s, \Revert\Shak\ became known as ``\Shak''. % \end{quote} % % \endgroup^^A Local format hook redefinition % \AltFormatInactive % \negmedskip % % \ReturnLink % % \AltFormatActive % \begin{Quote}{\ForgetThis\Shak\break % \hbox{}\hfill ``Julius Caesar'', Act III, Scene II} % \textbf{Antony:} Friends, Romans, countrymen, lend me your ears;\\ % I come to bury Caesar, not to praise him.\\ % The evil that men do lives after them;\\ % The good is oft interred with their bones;\\ % So let it be with Caesar. The noble Brutus\\ % Hath told you Caesar was ambitious:\\ % If it were so, it was a grievous fault,\\ % And grievously hath Caesar answer'd it.\\ % Here, under leave of Brutus and the rest---\\ % For Brutus is an honourable man;\\ % So are they all, all honourable men---\\ % Come I to speak in Caesar's funeral.\\ % He was my friend, faithful and just to me:\\ % But Brutus says he was ambitious;\\ % And Brutus is an honourable man. % \end{Quote} % \AltFormatInactive % % \newpage % % \section{Planned Obsolescence} % % \subsection[Pseudonyms]{Almost Obsolete: Pseudonym Macros} % \label{sec:AKA} % % The macros described in this section were early features of \textsf{nameauth}. They do not work like many of the other macros that display names and may be removed in the future. We retain them at present for backward compatibility. % % \subsubsection{Special Syntax} % % To save space, we show \meta{SAFX} as the equivalent of \meta{SNN|,| Affix}. The macros in this section all take arguments of the form: % % \begin{SyntaxBoxii} % Target Name & Cross-Reference Name\\\midrule % \oarg{FNN}\marg{SAFX} & \oarg{xref FNN}\marg % {xref SAFX}\oarg{xref Alternate}\\ % \end{SyntaxBoxii}\negmedskip % % \begin{itemize} % \item The target name comes first, which is the opposite of % \cmd{\IndexRef}. There the target name comes last because it is text % passed to the index macros. % \item The cross-reference comes last to allow for the widest range of % name forms (again, the opposite of \cmd{\IndexRef}). % We avoid two optional arguments in succession by preventing the target % from having a final optional argument. Neither \meta{Alternate} nor % the obsolete syntax cannot be used with the target name. Both can be % used with the cross-reference. % \item \meta{SAFX} and \meta{xref SAFX} can have comma-delimited suffixes. % \item One cannot use \cmd{\TagName} with a cross-reference, but one can % sort a cross-reference with \cmd{\PretagName} % (Section~\ref{sec:IndexSort}): % \end{itemize}\negmedskip % % \subsubsection{The Macros} % % \DescribeMacro{\AKA} % The \textit{also known as} macro and its starred form display an alias in the text and create a cross-reference in the index. % \DescribeMacro{\AKA*} % They format names differently than the naming macros because they use the name patterns for cross-references as a means to account for the name forms that they print in the test. % % \begin{SyntaxBox} % \cmd{\AKA\ }\oarg{FNN}\marg{SAFX}\oarg{xref FNN}\marg % {xref SAFX}\oarg{xref Alternate}\\ % \cmd{\AKA*}\oarg{FNN}\marg{SAFX}\oarg{xref FNN}\marg % {xref SAFX}\oarg{xref Alternate}\\ % \end{SyntaxBox}\negmedskip % % \begin{itemize} % \item Both macros create a cross-reference in the index to the % target name. % \item \cmd{\AKA} prints a long form of the cross-reference name in % the text. \cmd{\SeeAlso} works with \cmd{\AKA}, \cmd{\AKA*}, % \cmd{\PName}, and \cmd{\PName*}. % \item If \meta{xref Alternate} is present in a Western name form, then % instead of \meta{xref FNN}, \meta{xref Alternate} will be printed % in the text. % \item If \meta{xref Alternate} is present in a non-Western name form, % then instead of \meta{xref Affix} (if present), \meta{xref Alternate} % will be printed in the text. % \item If \meta{xref Alternate} is present without either \meta{xref FNN} % or \meta{xref Affix}, the obsolete syntax is used. % \item \cmd{\AKA*} is analogous to \cmd{\FName}. \cmd{\ForceFN} works % with it. The \texttt{oldAKA} option implies \cmd{\ForceFN} with every % use of \cmd{\AKA*}. % \item Neither \cmd{\AKA} nor its derivatives permit the effects of % \cmd{\ForgetThis} and \cmd{\SubvertThis} to ``pass through'' because % they produce output in the text. The \texttt{oldreset} option negates % this. % \end{itemize} % % Below we make cross-references to \cmd{\Name[Bob]\{Hope\}} \Name[Bob]{Hope}; all of the forms listed create the cross-reference ``\ShowIdxPageref*[Leslie Townes]{Hope} \textit{see} \ShowIdxPageref*[Bob]{Hope}''. % % \begin{center}\footnotesize % \vspace{2ex} % \Info{\strut\footnotesize Name Pattern(s):\hfill \break % \ttfamily \ShowPattern[Bob]{Hope}!MN\break % \ShowPattern[Leslie Townes]{Hope}!PN} % \vspace{-2ex}\smallstretch % \begin{tabular}{p{0.6\textwidth}l}\toprule % |\AKA[Bob]{Hope}[Leslie Townes]{Hope}| & % \AKA[Bob]{Hope}[Leslie Townes]{Hope}\\ % \rowcolor{nagrey}|\RevComma\AKA[Bob]{Hope}[Leslie Townes]{Hope}| & % \RevComma\AKA[Bob]{Hope}[Leslie Townes]{Hope}\\ % |\AKA[Bob]{Hope}[Leslie Townes]{Hope}[Lester T.]| & % \AKA[Bob]{Hope}[Leslie Townes]{Hope}[Lester T.]\\ % \rowcolor{nagrey}|\AKA*[Bob]{Hope}[Leslie Townes]{Hope}| & % \AKA*[Bob]{Hope}[Leslie Townes]{Hope}\\ % |\AKA*[Bob]{Hope}[Leslie Townes]{Hope}[Lester]| & % \AKA*[Bob]{Hope}[Leslie Townes]{Hope}[Lester]\\\bottomrule % \end{tabular} % \end{center} % % We display other name forms after referring to some names to ensure that they have sensible page references: % % \begin{quote}\small % \begin{tabular}{ll} % \cmd{\ForgetThis}\cmd{\Name\{Louis, XIV\}} & % \ForgetThis\Name{Louis, XIV}\\ % \cmd{\Name\{Lao-tzu\}} & \Name{Lao-tzu}\\ % \cmd{\Name[Lafcadio]\{Hearn\}} & \Name[Lafcadio]{Hearn}\\ % \cmd{\Name[Charles]\{du\string~Fresne\}} & % \Name[Charles]{du~Fresne}\\ % \end{tabular} % \end{quote} % Caps and reversing macros work on the arguments that are printed % in the text. % % \begin{center}\small % \vspace{2ex} % \PatInfo{\ShowPattern{Louis, XIV}!MN\break % \ShowPattern{Lao-tzu}!MN\break % \ShowPattern[Lafcadio]{Hearn}!MN\break % \ShowPattern[Charles]{du~Fresne}!MN\break % \ShowPattern{Sun King}!PN\break % \ShowPattern{Li, Er}!PN\break % \ShowPattern{du~Cange}!PN\break % \ShowPattern{Koizumi, Yakumo}!PN} % \vspace{-2ex}\medstretch % \begin{tabular}{p{0.65\textwidth}l}\toprule % |\AKA{Louis, XIV}{Sun King}| & \AKA{Louis, XIV}{Sun King}\\ % \rowcolor{nagrey}|\AKA*{Louis, XIV}{Sun King}| & % \AKA{Louis, XIV}{Sun King}\\ % |\AKA{Lao-tzu}{Li, Er}| & \AKA{Lao-tzu}{Li, Er}\\ % \rowcolor{nagrey}|\AKA*{Lao-tzu}{Li, Er}| & \AKA*{Lao-tzu}{Li, Er}\\ % |\AKA[Charles]{du~Fresne}{du~Cange}| & % \AKA[Charles]{du~Fresne}{du~Cange}\\ % \rowcolor{nagrey}|\CapThis\AKA[Charles]{du~Fresne}{du~Cange}| & % \CapThis\AKA[Charles]{du~Fresne}{du~Cange}\\ % |\CapName\AKA[Lafcadio]{Hearn}{Koizumi, Yakumo}| & % \CapName\AKA[Lafcadio]{Hearn}{Koizumi, Yakumo}\\ % \rowcolor{nagrey}|\RevName\AKA[Lafcadio]{Hearn}{Koizumi, Yakumo}| & % \RevName\AKA[Lafcadio]{Hearn}{Koizumi, Yakumo}\\\bottomrule % \end{tabular} % \end{center} % \medskip % % \DescribeMacro{\PName} % These convenience macros were an early feature of \textsf{nameauth}. They print a main name followed by a cross-reference in parentheses. % \DescribeMacro{\PName*} % If one is inclined to view \cmd{\AKA} as rubbish, these two macros are a biological hazard. % % \begin{SyntaxBox} % \cmd{\PName\ }\oarg{FNN}\marg{SAFX}\oarg{xref\,FNN}\marg % {xref\,SAFX}\oarg{xref\,Alternate}\\ % \cmd{\PName*}\oarg{FNN}\marg{SAFX}\oarg{xref\,FNN}\marg % {xref\,SAFX}\oarg{xref\,Alternate}\\ % \end{SyntaxBox} % % \cmd{\PName*} is like \cmd{\Name*} to the extent that it prints a long form % of \meta{FNN}\meta{SAFX}. It does not affect the cross-reference % \meta{xref FNN}\meta{xref SAFX}\meta{xref Alternate}. % % \begin{itemize} % \item Most prefix macros only affect \meta{FNN}\meta{SAFX}, % not the cross-reference. % \item The cross-reference always has a long form. % \item \cmd{\SkipIndex} keeps both names out of the index. % \item \meta{Alternate} and the obsolete syntax work only with % the cross-reference. % \end{itemize} % % If we attempted to use |\PName*{William, I}[William]{the Conqueror}|, this macro would put ``\SkipIndex\PName*{William, I}[William]{the Conqueror}'' in the body text, but its index entry would be incorrect: ``\ShowIdxPageref*[William]{the Conqueror} \textit{see} \ShowIdxPageref*{William, I}''. We use \cmd{\ForgetName\{William, I\}}^^A % \ForgetName{William, I} to prepare for the following example. We do not show the name patterns in the margin. % % \begingroup\small % \begin{itemize}[leftmargin=2cm] % \item[Macro:] \cmd{\PName[Mark]\{Twain\}[Samuel L.]\{Clemens\}} % \item[Text:] \ForgetThis\PName[Mark]{Twain}[Samuel L.]{Clemens}\\ % \PName[Mark]{Twain}[Samuel L.]{Clemens} % \item[Macro:] \cmd{\PName*[Mark]\{Twain\}[Samuel L.]\{Clemens\}} % \item[Text:] \PName*[Mark]{Twain}[Samuel L.]{Clemens} % \item[Index:] \ShowIdxPageref*[Samuel L.]{Clemens} \textit{see} % \ShowIdxPageref*[Mark]{Twain}\medskip % \item[Macro:] \cmd{\PName\{Voltaire\}[François-Marie]\{Arouet\}} % \item[Text:] \PName{Voltaire}[François-Marie]{Arouet} % \item[Index:] \ShowIdxPageref*[François-Marie]{Arouet} \textit{see} % \ShowIdxPageref*{Voltaire}\medskip % \item[Macro:] \cmd{\PName\{William, I\}\{William, the Conqueror\}} % \item[Text:] \PName{William, I}{William, the Conqueror}\\ % \PName{William, I}{William, the Conqueror} % \item[Index:] \ShowIdxPageref*{William, the Conqueror} \textit{see} % \ShowIdxPageref*{William, I}\medskip % \item[Macro:] \cmd{\PretagName\{}\cmd{\textit\{Doctor mellifluus\}\}^^A % \{Doctor mellifluus\}}\\ % \cmd{\PName\{Bernard, of Clairvaux\}\{}\cmd{\textit\{Doctor mellifluus\}} % \item[Text:] \PName{Bernard, of Clairvaux}{\textit{Doctor mellifluus}}\\ % \PName{Bernard, of Clairvaux}{\textit{Doctor mellifluus}} % \item[Index:] \ShowIdxPageref*{\textit{Doctor mellifluus}} \textit{see} % \ShowIdxPageref*{Bernard, of Clairvaux}\medskip % \item[Macro:] \cmd{\ForgetThis}\cmd{\PName\{Lao-tzu\}\{Li, Er\}} % \item[Text:] \ForgetThis\PName{Lao-tzu}{Li, Er} % \item[Index:] \ShowIdxPageref*{Li, Er} \textit{see} % \ShowIdxPageref*{Lao-tzu} % \end{itemize} % \endgroup % % While these macros certainly work, much like the obsolete syntax, they can be criticized as a design idea that originally seemed to hold promise, yet disappointed in practice due to using the cross-reference system for name formatting. % % \subsubsection[Workarounds]{Formatting Workarounds} % % By default, the macros in this section use only the formatting hooks for subsequent instances of names (Section~\ref{sec:Formatting}).\medskip % % First, the \texttt{formatAKA}\Info{\texttt{formatAKA}} option will permit \cmd{\ForceName} to force the ``first-use'' formatting hooks to be employed, but under different conditions. The name patterns that control these uses (Section~\ref{sec:NamePatterns}) apply only to cross-references; they are a distinct system of patterns that differs from normal names and ignores the difference between main-matter and front-matter name formatting. % % \begin{center}\small\medstretch % \makeatletter\@nameauth@AKAFormattrue\makeatother\global\NamesInactive % \begin{tabular}{rll}\toprule % & |\ForgetThis\Eliz| & |\AKA{Elizabeth,I}%|\\ % & & |[Good Queen]{Bess}|\\ % \rowcolor{nagrey}^^A % Front Matter: & \ForgetThis\Eliz & % \AKA{Elizabeth,I}[Good Queen]{Bess}\\ % \global\NamesActive^^A % Main Matter: & \ForgetThis\Eliz & % \AKA{Elizabeth, I}[Good Queen]{Bess}\\ % \rowcolor{nagrey}^^A % With \cmd{\ForceName}: & & % \ForceName\AKA{Elizabeth, I}[Good Queen]{Bess}\\\bottomrule % \end{tabular} % \vspace{-14ex} % \small\PatInfo{\ShowPattern{Elizabeth, I}!NF\break % \ShowPattern[Good Queen]{Bess}!PN\break % \ShowPattern{Elizabeth, I}!MN} % \vspace{14ex} % \end{center}\medskip % % The first appearance of \AKA{Elizabeth,I}[Good Queen]{Bess} above uses \cmd{\FrontNamesFormat} as its formatting hook because it is the first occurrence of the alternate name in the front matter. After that, even though \AKA{Elizabeth,I}[Good Queen]{Bess} occurs for the first time in the main matter, it uses the subsequent-use \cmd{\MainNameHook} because we are not using the regular name patterns. We need to use \cmd{\ForceName}, which triggers the expected use of \cmd{\NamesFormat}, the first-use main-matter hook.\medskip % % Second,\Info{\texttt{alwaysformat}} we can use the \texttt{alwaysformat} option to force only the use of \cmd{\NamesFormat} and \cmd{\FrontNamesFormat}. Of course, this can look like rubbish in certain circumstances. % % \begin{quote}\small % \makeatletter\@nameauth@AlwaysFormattrue\makeatother % \ForgetThis\LEliz\ was known as ``\AKA{Elizabeth,I}[Good Queen]{Bess}''. % Again we mention Queen \Eliz, ``\AKA{Elizabeth, I}[Good Queen]{Bess}''. % Using \cmd{\ForceName}: \ForceName\AKA{Elizabeth, I}[Good Queen]{Bess}. % \end{quote} % % \subsection{Obsolete Syntax} % \label{sec:Obsolete} % % This non-Western syntax limits alternate names and cross-references, prevents the use of comma-delimited names, and complicates indexing. It is a ``ghost of \textsf{nameauth} past'' that remains for the sake of backward compatibility and to prevent ``holes'' where naming macro arguments are discarded without apparent reason. % % \begin{SyntaxBox} % \cmd{\Name}\marg{SNN}\oarg{Alternate} % \end{SyntaxBox} % % The genesis of this syntax was the use of the \meta{Alternate} field for variant forenames in Western names, personal names in Eastern names, and sobriquets, titles, and so on in ancient names. Yet this prevented using alternate names for non-Western names and it limited those names to an unacceptable second-tier status. Developing the comma delimiter in \meta{SNN, Affix} presented significant challenges, but it was worth overcoming them to put all name forms on equal footing. % % We show this syntax for the sake of completeness, but we strongly encourage using the comma-delimited syntax instead. % % \begin{itemize} % \item One must \emph{leave empty} the first optional \meta{FNN} argument. % \item One must \emph{never} use the comma-delimited argument \meta{Affix}. % \item These names \emph{always} use \meta{Alternate}, which acts like % \meta{Affix} usually does, and affects both name and index patterns % (Section~\ref{sec:NamePatterns}). % \item These names take the form \meta{SNN Alternate} in the index. % \item In this manual we designate these names with a double dagger (\ddag). % \end{itemize} % % \begin{quote}\small % \begin{Verbatim} % \Name{Henry}[VIII] % Ancient % \Name{Chiang}[Kai-shek] % Eastern % \begin{nameauth} % \< Dagb & & Dagobert & I > % Ancient % \< Yosh & & Yoshida & Shigeru > % Eastern % \< Fukuyama & & % \noexpand\textUC{Fukuyama} & Takeshi > % Alt. format % \end{nameauth} % \end{Verbatim} % \end{quote} % % \AltFormatActive % After studying in the US during the 1930s, in 1954 Rev. % \cmd{\Fukuyama}\cmd{\ddag} \Fukuyama\ddag\ published % \textit{Nihon Fukuin R\=uteru Ky\=okai Shi} (History % of the Evangelical Lutheran Church in Japan). % \AltFormatInactive % % \newpage % % \begin{center}\small\medstretch % \begin{tabular}{ll}\toprule % |\ForgetThis\Name{Henry}[VIII]\ddag| & % \ForgetThis\Name{Henry}[VIII]\ddag\\ % |\Name{Henry}[VIII]\ddag| & % \Name{Henry}[VIII]\ddag\\ % \rowcolor{nagrey}|\ForgetThis\Name{Chiang}[Kai-shek]\ddag| & % \ForgetThis\Name{Chiang}[Kai-shek]\ddag\\ % \rowcolor{nagrey}|\Name{Chiang}[Kai-shek]\ddag| & % \Name{Chiang}[Kai-shek]\ddag\\ % |\Dagb\ddag| & \Dagb\ddag\\ % |\Dagb\ddag| & \Dagb\ddag\\ % \rowcolor{nagrey}|\CapName\Yosh\ddag| & \CapName\Yosh\ddag\\ % \rowcolor{nagrey}|\CapName\RevName\LYosh\ddag| & \CapName\RevName\LYosh\ddag\\ % |\AltFormatActive| \AltFormatActive\\ % |\ForgetThis\Fukuyama\ddag| & \ForgetThis\Fukuyama\ddag\\ % |\Fukuyama\ddag| & \Fukuyama\ddag\\ % |\AltFormatInactive| \AltFormatInactive\\\bottomrule % \end{tabular} % \end{center} % % Regardless of its flaws, the obsolete syntax shares name patterns, index tags, data tags, and index entries with the current syntax: % % \begin{quote}\small % \begin{tabular}{@{}lll} % Obsolete syntax: & \cmd{\ForgetThis}\cmd{\Name\{Henry\}[VIII]}\cmd{\ddag} & % \ForgetThis\Name{Henry}[VIII]\ddag\\ % & \cmd{\ShowPattern\{Henry\}[VIII]} & \ShowPattern{Henry}[VIII]\\[1ex] % Current syntax: & \cmd{\Name\{Henry, VIII\}} & \Name{Henry, VIII}\\ % & \cmd{\ShowPattern\{Henry, VIII\}} & \ShowPattern{Henry, VIII}\\ % \end{tabular} % \end{quote} % % We do not expect people to use the obsolete syntax much anymore. Here we list more advantages to using the current syntax and avoiding the old. % % \begin{itemize} % \item Only the newer syntax permits variants:\\ % \cmd{\Name*\{Henry, VIII\}[Tudor]} \Name*{Henry, VIII}[Tudor]. % \item The proper form for the old syntax is, e.g.:\\ % \cmd{\Name*\{Henry\}[VIII]}: \Name*{Henry}[VIII]. % \IndexInactive % \item \cmd{\Name[Henry]\{VIII\}} is a malformed Western name:\\ % ``\Name*[Henry]{VIII}'' and ``\Name[Henry]{VIII}''. % \item \cmd{\Name[Henry]\{VIII\}[Tudor]} also is malformed:\\ % ``\Name*[Henry]{VIII}[Tudor]'' and ``\Name[Henry]{VIII}[Tudor]'' % \item Both incorrect name forms have the same index entry:\\ % ``\ShowIdxPageref*[Henry]{VIII}'' % \IndexActive % \end{itemize} % \negmedskip % % \ReturnLink % % \begin{Quote}{\Name[Salman]{Rushdie}, \textit{The Satanic Verses} (1988)} % Names, once they are in common use, quickly become mere sounds, their etymology being buried, like so many of the earth's marvels, beneath the dust of habit. % \end{Quote} % % \newpage % % \begingroup^^A General format hook redefinition. % \section{Advanced Customization} % \label{sec:AdvCustomize} % % This section is meant to help those who want to access package internals as they add features, as well as those who want to design their own constructs and mesh them with \textsf{nameauth}. Here we set the formatting hooks to the package default, setting aside the common usage in this manual. We also use alternate formatting for much of this section. We set up the following hooks: % % \begin{VerbatimOut}{\jobname.tmp} % \renewcommand*\NamesFormat{} % \renewcommand*\FrontNamesFormat{} % \renewcommand*\MainNameHook{\AltOff} % \renewcommand*\FrontNameHook{\AltOff} % \end{VerbatimOut} % % \begin{quote}\small % \VerbatimInput[gobble=0]{\jobname.tmp} % \end{quote} % \input{\jobname.tmp} % % \AltFormatActive % \begingroup^^A Local format hook redefinition % % \subsection{Using Package Internals} % % We move toward custom formatting by starting with the established paradigm of alternate formatting (Section~\ref{sec:AltFormat}). We will change the ``back-end'' macros to a degree, so that we get a substantially similar experience with custom code. % % \ifdefined\NameauthDoTestFiles \edef\NameauthTestFile{test13_01.tex}\else % \edef\NameauthTestFile{\jobname.tmp}\fi % % \begin{VerbatimOut}{\NameauthTestFile} % \documentclass{article} % \input{compat.tex} % Included with nameauth; needed only if % % compiling on multiple TeX distros or LaTeX engines. % \usepackage{makeidx} % \usepackage[altformat]{nameauth} % \makeindex % % % Alternate formatting macro definition % \makeatletter % \newcommand*\Fbox[1]{% % \if@nameauth@DoAlt\protect\fbox{#1}\else#1\fi % } % \makeatother % % % Quick interface definition % \begin{nameauth} % \< deSmet & Pierre-Jean & % \noexpand\Fbox{\noexpand\AltCaps{d}e~Smet} & > % \end{nameauth} % % % Sorting and tagging % \PretagName[Pierre-Jean]% % {\noexpand\Fbox{\noexpand\AltCaps{d}e~Smet}}% % {de~Smet, Pierre-Jean} % % \renewcommand*\MainNameHook{\AltOff} % \renewcommand*\FrontNameHook{\AltOff} % % \begin{document} % % \deSmet\ was a Jesuit missionary who arrived in North % America in 1821 at the age of twenty, after a year of seminary % education. \CapThis\deSmet\ was ordained in 1827 and worked % among American Indian nations after 1837. We can show the forms % \LdeSmet\ and \SdeSmet. % % \printindex % \end{document} % \end{VerbatimOut} % % When designing macros that work with alternate formatting hooks, the Boolean flags that one must know are \texttt{\textbackslash if@nameauth@DoAlt}, which is toggled by \cmd{\AltOn} and \cmd{\AltOff}; \texttt{\textbackslash if@nameauth@DoCaps}, which handles capitalization via \cmd{\AltCaps}, and \texttt{\textbackslash if@nameauth@InHook}, which is true when the formatting hooks are called. % % Next, instead of using \cmd{\textSC} and friends, we define a new macro that works in similar fashion. \cmd{\Fbox} draws a frame around the name: % % \begin{quote}\small % \VerbatimInput[gobble=0,lastline=13]{\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}\small % \VerbatimInput[gobble=0,firstline=14,lastline=24]{\NameauthTestFile} % \end{quote} % % \makeatletter % \newcommand*\Fbox[1]{^^A % \if@nameauth@DoAlt\protect\fbox{#1}\else#1\fi % }^^A % \makeatother % % \newpage % % The final step is redefining the hooks, which can be quite simple: % % \begin{quote}\small % \VerbatimInput[gobble=0,firstline=25]{\NameauthTestFile} % % \deSmet\ was a Jesuit missionary who arrived in North % America in 1821 at the age of twenty, after a year of seminary % education. \CapThis\deSmet\ was ordained in 1827 and worked % among American Indian nations after 1837. We can show the forms % \LdeSmet\ and \SdeSmet. % \end{quote} % % Some formatting, such as the use of \cmd{\textSC}, is fairly standard. Other formatting, such as \cmd{\Fbox} above, is more ornamental. % \endgroup^^A Local format hook redefinition % \AltFormatInactive % % \AltFormatActive % \begingroup^^A Local format hook redefinition % % \subsection{Using Separate Macros} % % \ForgetName[Pierre-Jean]{\noexpand\Fbox{\noexpand\AltCaps{d}e~Smet}} % One is not tied to the internal mechanisms of \textsf{nameauth} in order to design alternate formatting, but this approach is more labor-intensive and requires one to keep track of more details. % % We still recommend using \cmd{\AltFormatActive} to mitigate errors. The following example tries to show how far one might go afield, yet remain compatible with standard names. % % Three Boolean flags replace package internals. The flag \texttt{\textbackslash ifFbox} activates formatting, \cmd{\CapThis} sets \texttt{\textbackslash ifFirstCap} true, and \texttt{\textbackslash ifInHook} is set manually, instead of being set by the hook dispatcher. % % \ifdefined\NameauthDoTestFiles \edef\NameauthTestFile{test13_02.tex}\else % \edef\NameauthTestFile{\jobname.tmp}\fi % % \begin{VerbatimOut}{\NameauthTestFile} % \documentclass{article} % \input{compat.tex} % Included with nameauth; needed only if % % compiling on multiple TeX distros or LaTeX engines. % \usepackage{makeidx} % \usepackage[altformat]{nameauth} % \makeindex % % \newif\ifFbox % Replaces \if@nameauth@DoAlt % \newif\ifFirstCap % Replaces \if@nameauth@DoCaps % \newif\ifInHook % Replaces \if@nameauth@InHook % \Fboxtrue % Replaces \AltFormatActive % % % Alternate formatting macro definition % \newcommand*\Fbox[1]{% % \ifFbox\protect\fbox{#1}\else#1\fi % } % % % Redefinition of \AltCaps and \CapThis % \renewcommand*\AltCaps[1]{% % \ifInHook % \ifFirstCap\MakeUppercase{#1}\else#1\fi % \else % #1% % \fi % } % \renewcommand*\CapThis{\FirstCaptrue} % % \renewcommand*\NamesFormat[1] % {\InHooktrue\NameParser\global\FirstCapfalse} % % \renewcommand*\MainNameHook[1] % {\Fboxfalse\InHooktrue\NameParser\global\FirstCapfalse} % % \let\FrontNamesFormat\Namesformat % \let\FrontNameHook\MainNameHook % % % Quick interface definition % \begin{nameauth} % \< deSmet & Pierre-Jean & % \noexpand\Fbox{\noexpand\AltCaps{d}e~Smet} & > % \end{nameauth} % % % Sorting and tagging % \PretagName[Pierre-Jean]% % {\noexpand\Fbox{\noexpand\AltCaps{d}e~Smet}}% % {de~Smet, Pierre-Jean} % % \begin{document} % % \deSmet\ was a Jesuit missionary who arrived in North % America in 1821 at the age of twenty, after a year of seminary % education. \CapThis\deSmet\ was ordained in 1827 and worked % among American Indian nations after 1837. We can show the forms % \LdeSmet\ and \SdeSmet. % % \printindex % \end{document} % \end{VerbatimOut} % % \begin{quote}\small % \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 new \cmd{\AltCaps} works like the built-in version, except it does not use the internal macros and flags. We also redefine \cmd{\CapThis} to use our flag instead of the internal flag: % % \begin{quote} % \VerbatimInput[gobble=0,firstline=17,lastline=26]{\NameauthTestFile} % \end{quote} % % We have to reproduce the logic and macros that the package would have provided. That means defining everything from scratch. To emphasize these differences, instead of displaying the macro argument, we use \cmd{\NameParser} to do that. % % Changes to \texttt{\textbackslash ifInHook} (default false) and \texttt{\textbackslash ifFbox} (default true) are local to the scope in which the hook macros are called. \texttt{\textbackslash ifFirstCap} must be set globally. Below we reproduce the logic of \cmd{\AltOff} before \cmd{\NameParser} in \cmd{\MainNameHook}: % % \begin{quote} % \VerbatimInput[gobble=0,firstline=27,lastline=32]{\NameauthTestFile} % \end{quote} % % By using the same hook logic and \cmd{\noexpand}, the new ``back-end'' meshes with the ``front-end'' macros used before without creating spurious index entries. % % \newcommand*\Fbox[1]{^^A % \ifFbox\protect\fbox{#1}\else#1\fi % } % \renewcommand*\AltCaps[1]{^^A % \ifInHook % \ifFirstCap\MakeUppercase{#1}\else#1\fi % \else % #1^^A % \fi % } % \renewcommand*\CapThis{\FirstCaptrue} % \renewcommand*\NamesFormat[1] % {\InHooktrue\NameParser\global\FirstCapfalse} % \renewcommand*\MainNameHook[1] % {\Fboxfalse\InHooktrue\NameParser\global\FirstCapfalse} % \let\FrontNamesFormat\Namesformat % \let\FrontNameHook\MainNameHook % % \begin{quote}\small % \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; needed only if % % compiling on multiple TeX distros or LaTeX engines. % \usepackage{makeidx} % \usepackage[altformat]{nameauth} % \makeindex % % \newif\ifCaps % Replaces \if@nameauth@DoAlt % \newif\ifFirstCap % Replaces \if@nameauth@DoCaps % \newif\ifInHook % Replaces \if@nameauth@InHook % \Capstrue % Replaces \AltFormatActive % % % Alternate formatting macro definition % \renewcommand*\textSC[1]{\ifCaps\textsc{#1}\else#1\fi} % % % Redefinition of \AltCaps and \CapThis % \renewcommand*\AltCaps[1]{% % \ifInHook % \ifFirstCap\MakeUppercase{#1}\else#1\fi % \else % #1% % \fi % } % \renewcommand*\CapThis{\FirstCaptrue} % % \renewcommand*\NamesFormat[1] % {\InHooktrue#1\global\FirstCapfalse} % % \renewcommand*\MainNameHook[1] % {\Capsfalse\InHooktrue#1\global\FirstCapfalse} % % \let\FrontNamesFormat\Namesformat % \let\FrontNameHook\MainNameHook % % \begin{nameauth} % \< Luth & Martin & \noexpand\textSC{Luther} & > % \< Cath & Catherine \noexpand\AltCaps{d}e' % & \noexpand\textSC{Medici} & > % \end{nameauth} % \PretagName[Martin]{\noexpand\textSC{Luther}}{Luther, Martin} % \PretagName[Catherine \noexpand\AltCaps{d}e'] % {\noexpand\textSC{Medici}}{Medici, Catherine de} % % \begin{document} % % \ForgetThis\Luth\ was a leading figure in the Protestant % Reformation. \Luth\ believed that one is declared % righteous in a forensic sense by divine grace through faith % created by the Holy Spirit via the Gospel and the Sacraments. % % \ForgetThis\Cath\ was not only Queen of France in her own right, % but she also guided the reigns of her three sons. % \CapThis\LCath[\noexpand\AltCaps{d}e'] % was blamed for the St.\ Bartholomew's Day massacre that saw the % murder of thousands of Huguenots. % % \printindex % \end{document} % \end{VerbatimOut} % % \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 % % We can go one step further and use our own macros with names designed for the built-in macros, as the next example shows: % % \begin{quote}\small % \VerbatimInput[gobble=0]{\NameauthTestFile} % % \ForgetThis\Luth\ was a leading figure in the Protestant % Reformation. \Luth\ believed that one is declared % righteous in a forensic sense by divine grace through faith % created by the Holy Spirit via the Gospel and the Sacraments. % % \ForgetThis\Cath\ was not only Queen of France in her own right, % but she also guided the reigns of her three sons. % \CapThis\LCath[\noexpand\AltCaps{d}e'] % was blamed for the St.\ Bartholomew's Day massacre that saw the % murder of thousands of Huguenots. % \end{quote} % % \endgroup^^A Local format hook redefinition % \AltFormatInactive % % \subsection{Full Customization} % \label{sec:FullCustomize} % % One can redesign or augment the core naming macros, then hook those modifications into the \textsf{nameauth} package without needing to patch the style file itself. % % \DescribeMacro{\NameauthName} % All these macros are set by default to \cmd{\@nameauth@Name}, the internal name parser. % \DescribeMacro{\NameauthLName} % \cmd{\Name}, or an unmodified shorthand, calls \cmd{\NameauthName}. \cmd{\Name*}, or an L-shorthand, sets \cmd{\@nameauth@FullNametrue}, then calls \cmd{\NameauthLName}. % \DescribeMacro{\NameauthFName} % \cmd{\FName}, or an S-shorthand, sets \cmd{\@nameauth@FirstNametrue}, then calls \cmd{\NameauthFName}. One should not modify \cmd{\Name} and \cmd{\FName} directly. Since \textsf{nameauth} uses \textsf{xargs}, the next example uses it also. % % \ifdefined\NameauthDoTestFiles \edef\NameauthTestFile{test13_04.tex}\else % \edef\NameauthTestFile{\jobname.tmp}\fi % % \begin{VerbatimOut}{\NameauthTestFile} % \documentclass{article} % \input{compat.tex} % Included with nameauth; needed only if % % compiling on multiple TeX distros or LaTeX engines. % \usepackage{makeidx} % \usepackage[altformat]{nameauth} % \makeindex % \usepackage{xcolor} % % \makeatletter % % % Change the general-case name macro to show % % a name in a framed, colored box. % % \newcommandx*\MyName[3][1=\@empty, 3=\@empty]{% % \global\@nameauth@toksa\expandafter{#1}% % \global\@nameauth@toksb\expandafter{#2}% % \global\@nameauth@toksc\expandafter{#3}% % \fcolorbox{black}{gray!25!white}{\@nameauth@Name[#1]{#2}[#3]}% % } % % % Likewise change the macro for when names are forced long. % \newcommandx*\MyLName[3][1=\@empty, 3=\@empty]{% % \global\@nameauth@toksa\expandafter{#1}% % \global\@nameauth@toksb\expandafter{#2}% % \global\@nameauth@toksc\expandafter{#3}% % \fcolorbox{black}{green!25!white}{\@nameauth@Name[#1]{#2}[#3]}% % } % % % Likewise change the macro when personal names are desired. % \newcommandx*\MyFName[3][1=\@empty, 3=\@empty]{% % \global\@nameauth@toksa\expandafter{#1}% % \global\@nameauth@toksb\expandafter{#2}% % \global\@nameauth@toksc\expandafter{#3}% % \fcolorbox{black}{yellow!25!white}{\@nameauth@Name[#1]{#2}[#3]}% % } % \makeatother % % % Change the formatting hooks, but do not use alternate. % % formatting, which is separate from that above. % \renewcommand*\NamesFormat[1]{\scshape#1} % \renewcommand*\MainNameHook[1]{#1} % % % Change the naming macro hooks. % \renewcommand*\NameauthName{\MyName} % \renewcommand*\NameauthLName{\MyLName} % \renewcommand*\NameauthFName{\MyFName} % % \begin{document} % % \ForgetThis\Name[Adolf]{Harnack} was a theologian who stressed % the Fatherhood of God and the brotherhood of man. % \Name[Adolf]{Harnack} flourished in the early twentieth % century. We also produce \Name*[Adolf]{Harnack} and % \FName[Adolf]{Harnack}. % % \printindex % \end{document} % \end{VerbatimOut} % % \begin{quote}\small % \VerbatimInput[gobble=0]{\NameauthTestFile} % % \makeatletter % \newcommandx*\MyName[3][1=\@empty, 3=\@empty]{^^A % \global\@nameauth@toksa\expandafter{#1}^^A % \global\@nameauth@toksb\expandafter{#2}^^A % \global\@nameauth@toksc\expandafter{#3}^^A % \fcolorbox{black}{gray!25!white}{\@nameauth@Name[#1]{#2}[#3]}^^A % } % % \newcommandx*\MyLName[3][1=\@empty, 3=\@empty]{^^A % \global\@nameauth@toksa\expandafter{#1}^^A % \global\@nameauth@toksb\expandafter{#2}^^A % \global\@nameauth@toksc\expandafter{#3}^^A % \fcolorbox{black}{green!25!white}{\@nameauth@Name[#1]{#2}[#3]}^^A % } % % \newcommandx*\MyFName[3][1=\@empty, 3=\@empty]{^^A % \global\@nameauth@toksa\expandafter{#1}^^A % \global\@nameauth@toksb\expandafter{#2}^^A % \global\@nameauth@toksc\expandafter{#3}^^A % \fcolorbox{black}{yellow!25!white}{\@nameauth@Name[#1]{#2}[#3]}^^A % } % % \makeatother % \renewcommand*\NamesFormat[1]{\scshape#1} % \renewcommand*\MainNameHook[1]{#1} % \renewcommand*\NameauthName{\MyName} % \renewcommand*\NameauthLName{\MyLName} % \renewcommand*\NameauthFName{\MyFName} % % \ForgetThis\Name[Adolf]{Harnack} was a theologian who stressed % the Fatherhood of God and the brotherhood of man. % \Name[Adolf]{Harnack} flourished in the early twentieth % century. We also produce \Name*[Adolf]{Harnack} and % \FName[Adolf]{Harnack}. % \end{quote} % % After the name is printed in the body text, the internal macros \emph{globally} set \cmd{\@nameauth@FullNamefalse} and \cmd{\@nameauth@FirstNamefalse}, as well as other flags related to the prefix macros. This prevents certain cases of undocumented behavior in versions of \textsf{nameauth} before 3.3, where resetting flags locally could cause unexpected name forms. If an existing document leverages the local resetting of flags, one can use the \texttt{oldreset} option.\medskip % % Like\Info{\cmd{\global}} many of the macros in this package, these macros can be redefined or used locally within a scope without making global changes to the document unless you specifically use \cmd{\global}. % \endgroup^^A General format hook redefinition % \negmedskip % % \ReturnLink % % \begin{Quote}{\ForgetThis\Name{Confucius}, \textit{The Analects}, C II} % He who exercises government by means of his virtue may be compared to the north polar star, which keeps its place and all the stars turn towards it. % \end{Quote} % % \newpage % % \section{Technical Notes and Tips} % \label{sec:TechNotes} % % \subsection{Tips: General} % % \begin{itemize} % \item A missing square bracket or curly brace can cause errors like % ``\texttt{Paragraph ended}'' and ``\texttt{Missing} \meta{grouping token} % \texttt{inserted.}'' % \item Ensure that macros and conditionals used in name arguments are % defined in the preamble or outermost scope. % \item Because \cmd{\CapThis} segments a name argument, using it with % macros in name arguments can cause errors if not used with alternate % formatting (Section~\ref{sec:AltFormat}). % \item Something like |\edef\foo{\CapThis\Name{bar}}| will fail. Yet % one can use |\CapThis\Name{bar}| as an argument to |\edef\foo#1{#1}|. % \item In \texttt{dtx} files, put the \texttt{nameauth} environment and % tags in the \texttt{} section preamble. Do not, however put % any \cmd{\newif} statements there because they cannot be placed between % \texttt{\textbackslash iffalse} and \texttt{\textbackslash fi}. Save the % \cmd{\newif} statements for the ``commented'' part. % \end{itemize} % % \subsection[Tips: Indexing]{Tips: Indexing and Sorting} % \label{sec:DebugSort} % % The following warnings are always active. These warnings are issued when the following actions are attempted, but are \emph{not allowed} unless certain package options are used: % % \begin{itemize} % \item Use \cmd{\SeeAlso} before \cmd{\IndexName} or a naming macro. % \item Use \cmd{\PretagName} with the \texttt{nopretag} option. % \item Use \cmd{\IndexRef} with an extant name. % The \texttt{oldsee} option permits this. % \item Put \cmd{\SkipIndex} before \cmd{\IndexName} and \cmd{\IndexRef}. % The \texttt{oldsee} option permits this. % \item Prevent \cmd{\SkipIndex} from remaining active after being done % with \cmd{\PName} and \cmd{\PName*}. Only when the \texttt{oldreset} % option is used, do not reset \cmd{\SkipIndex} and warn if is effects % remain active. % \end{itemize} % % Many warnings occur only when the \texttt{verbose} package option is used. These are less likely to indicate a serious problem, but might be helpful: % % \begin{itemize} % \item When the following actions are attempted, they are \emph{not allowed} % unless certain package options are used: % \begin{itemize} % \item Use \cmd{\IndexName} or a naming macro with a cross-reference % or exclusion. % \item Use \cmd{\IndexRef} with a cross-reference or exclusion. % \item Use \cmd{\ExcludeName}, \cmd{\IncludeName}, \cmd{\TagName}, % or \cmd{\UntagName} with a cross-reference. % \item Only if the \texttt{oldsee} option is used, instead of preventing % \cmd{\IndexRef} to create an xref on top of an extant name, just warn % if a name exists and creates a \textit{see} reference, which % prevents further page entries for that name. % \end{itemize} % \item When the following actions are attempted, they are \emph{permitted.} % \begin{itemize} % \item Use \cmd{\ExcludeName} with an extant name. % \item Use \cmd{\IncludeName*} with a cross-reference. % \item Use \cmd{\PretagName} to sort a cross-reference. % \end{itemize} % \end{itemize} % % \begin{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 ac tive characters, spaces, or control sequences % in the name arguments? Use \cmd{\PretagName}. % \item Is alternate formatting used consistently? Are any names used % within sections of alternate formatting ever used outside of them? % \item Are macros in the name arguments that can expand differently % under different conditions preceded by \cmd{\noexpand}? % \end{itemize} % \end{itemize} % % Extra spaces are significant when sorting index entries, yet usually are not significant in the body text. Macros that use \cmd{\protected@edef} can add spaces to index entries. Because \textsf{nameauth} must work with classes that write index entries to \texttt{aux} files, its macros must use \cmd{\protected@edef}. The only way to verify this is to inspect the \texttt{idx} file. We show this below: % % \begin{quote}\small % \begin{Verbatim} % \makeatletter % \newcommand\Idx[1]{\protected@edef\arg{#1}\index{\arg}} % \makeatother % \end{Verbatim} % % \cmd{\Idx\{}\cmd{\textsc\{football\}\}} produces:\\ % \hbox{}\qquad\cmd{\indexentry}\texttt % {\{\cmd{\textsc\textvisiblespace\textvisiblespace}\{football\}\}\{}\meta % {page}\texttt{\}}\\[1ex] % The macro \cmd{\index\{}\cmd{\textsc\{football\}\}} produces:\\ % \hbox{}\qquad\cmd{\indexentry}\texttt % {\{\cmd{\textsc}\{football\}\}\{}\meta{page}\texttt{\}} % \end{quote} % % \subsection[Tips: Name Args]{Tips: Macros in Name Arguments} % % \begin{itemize} % \item Use alternate formatting to avoid potential problems, especially % when using \cmd{\CapThis} (Sections~\ref{sec:AltFormat}, % \ref{sec:AdvCustomize}). % \item |\SkipIndex\Name{\noexpand\empty}| will not trigger a package error, % while |\SkipIndex\Name{\empty}| will trigger an error. % \item Use \cmd{\noexpand}\meta{macro} in name macro arguments as % a best practice. % \item Macros used in name arguments must be defined either in the % preamble or in the outermost document scope to avoid errors. % \item Boolean flags (\texttt{\textbackslash if}\meta{flag}) used in % formatting hooks must be defined either in the preamble or in the % outermost document scope. % \item The \cmd{\global} modifier does not work with \cmd{\newif} and % \cmd{\newcommand}. Yet \cmd{\global} can precede the use of a macro % defined with \cmd{\newcommand}. % \textit{The \TeX book}, pages 275--277, shows what \cmd{\global} can % and cannot do. See more about this issue and \cmd{\newcommand} on % \href{https://tex.stackexchange.com/questions/51733/global-renewcommand-equivalent-of-global-def} % {\bfseries this page}. % \end{itemize} % % Below we demonstrate how scoping rules work: % % \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 % \end{VerbatimOut} % % \begin{quote}\small % \VerbatimInput[gobble=0]{\jobname.tmp} % \end{quote} % \input{\jobname.tmp} % % \begin{itemize} % \item \ifdefined\CondAtrue \texttt{\textbackslash ifCondA} is defined % \else \texttt{\textbackslash ifCondA} is not defined \fi % in the outer scope (outer definition). % \item \ifdefined\MacroA \cmd{\MacroA} is defined % \else \cmd{\MacroA} is not defined \fi % in the outer scope (outer definition). % \item \ifdefined\CondBtrue \texttt{\textbackslash ifCondB} is defined % \else \texttt{\textbackslash ifCondB} is not defined \fi % in the outer scope (local definition). % \item \ifdefined\CondCtrue \texttt{\textbackslash ifCondC} is defined % \else \texttt{\textbackslash ifCondC} is not defined \fi % in the outer scope (no \cmd{\global}\cmd{\newif}). % \item \ifdefined\MacroB \cmd{\MacroB} is defined % \else \cmd{\MacroB} is not defined \fi % in the outer scope (no \cmd{\global}\cmd{\newcommand}). % \item \cmd{\MacroC} \ifdefined\MacroC is defined % \else is not defined \fi % in the outer scope (local definition). % \item \cmd{\MacroD} \ifdefined\MacroD is defined % \else is not defined \fi % in the outer scope (\cmd{\global} affects \cmd{\def} in \cmd{\MacroC}). % \item \ifCondA \texttt{\textbackslash ifCondA} is true % \else \texttt{\textbackslash ifCondA} is false \fi % (\cmd{\global} assignment works, not instantiation). % \end{itemize} % % Any macro that is used in the argument of a naming macro must be defined in all scopes in which that name is used. Below we deactivate indexing and show this: % % \begin{quote}\small % \IndexInactive % \begin{Verbatim} % \begin{nameauth} % \< Testi & & \noexpand\TESTi & > % \< Testii & & \noexpand\TESTii & > % \end{nameauth} % \def\TESTi{Test One} % \indent \hbox to 10em{(Outer 1) \Testi\hfill} % \begingroup % (Inner 1) \Testi\\ % \def\TESTii{Test Two} % \hbox to 10em{(Inner 2) \Testii\hfill} % \ndegroup % (Outer 2) \unless\ifdefined\TESTii \cmd{\TESTii} undefined\fi % \end{Verbatim} % % \begin{nameauth} % \< Testi & & \noexpand\TESTi & > % \< Testii & & \noexpand\TESTii & > % \end{nameauth} % \def\TESTi{Test One} % \indent \hbox to 10em{(Outer 1) \Testi\hfill} % \begingroup % (Inner 1) \Testi\\ % \def\TESTii{Test Two} % \hbox to 10em{(Inner 2) \Testii\hfill} % \endgroup % (Outer 2) \unless\ifdefined\TESTii \cmd{\TESTii} undefined\fi % \end{quote} % % \newpage % % \subsection[Active Unicode]{Active Unicode Characters} % \label{sec:Unicode} % % \subsubsection{General Information} % % 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}. % % 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}): % % \begin{quote}\small % \begin{Verbatim} % \usepackage[utf8]{inputenc} % For older TL releases % \usepackage[TS1,T1]{fontenc} % \usepackage{lmodern}% Contains TS1 glyph 115 % \usepackage{newunicodechar} % \DeclareTextSymbolDefault{\textlongs}{TS1} % \DeclareTextSymbol{\textlongs}{TS1}{115} % \newunicodechar{ſ}{\textlongs} % % In Congreſs, July 4, 1776 % \end{Verbatim} % % In Congreſs, July 4, 1776 % \end{quote} % % Many Unicode characters have native support in \texttt{xelatex} and % \texttt{lualatex}, but not in \texttt{pdflatex}. Yet the latter has % features (e.g., in \textsf{microtype}) that others lack. The features of % \texttt{makeindex} do not always equate to those in \texttt{xindy}. % Those differences impact design choices. % Below we group characters by accents and diacritical marks: % % \begin{center}\large\bigstretch % \def\Bullet#1{\setbox0\hbox{#1}\raise 0.4ex\hbox % to\wd0{\hfil\tiny\textbullet\hfil}} % \def\bullet#1{\setbox0\hbox{#1}\raise 0.2ex\hbox % to\wd0{\hfil\tiny\textbullet\hfil}} % \begin{tabular}{lll}\toprule % acute & Á Ć É Ǵ \Bullet{H} Í Ĺ & % á ć é ǵ \bullet{h} í ĺ \strut\\ % & Ń Ó Ŕ Ś Ú Ý Ź & % ń ó ŕ ś ú ý ź \strut\\ % \rowcolor{nagrey}grave & À \Bullet{C} È \Bullet{G} \Bullet{H} Ì Ò Ù & % à \bullet{c} è \bullet{g} \bullet{h} ì ò ù \strut\\ % circumflex &  Ĉ Ê Ĝ Ĥ Î Ĵ Ô Ŝ Û Ŵ Ŷ & % â ĉ ê ĝ ĥ î ĵ ô ŝ û ŵ ŷ \strut\\ % \rowcolor{nagrey}tilde & % à \Bullet{C} \Bullet{E} \Bullet{G} \Bullet{H} Ĩ Ñ Õ Ũ & % ã \bullet{c} \bullet{e} \bullet{g} \Bullet{h} ĩ ñ õ ũ \strut\\ % diaeresis\footnotemark & Ä \Bullet{C} Ë \Bullet{G} \Bullet{H} Ï Ö Ü Ÿ & % ä \bullet{c} ë \bullet{g} \bullet{h} ï ö ü ÿ \strut\\ % \rowcolor{nagrey}cedilla & \Bullet{A} Ç \Bullet{E} Ģ Ķ Ļ Ņ Ŗ Ş Ţ & % \bullet{a} ç \bullet{e} ģ ķ ļ ņ ŗ ş ţ \strut\\ % macron & Ā \Bullet{C} Ē Ḡ \Bullet{H} Ī Ō Ū Ǣ Ȳ & % ā \bullet{c} ē ḡ \bullet{h} ī ō ū ǣ ȳ \strut\\ % \rowcolor{nagrey}breve & Ă \Bullet{C} \Bullet{E} Ğ \Bullet{H} Ĭ Ŏ Ŭ & % ă \bullet{c} \bullet{e} ğ \bullet {h} ĭ ŏ ŭ \strut\\ % dot/dotless & Ḃ Ċ Ė Ġ \Bullet{H} İ Ż & ḃ ċ ė ġ \bullet{h} ı ż \strut\\ % \rowcolor{nagrey}ogonek & Ą \Bullet{C} Ę \Bullet{G} \Bullet{H} Į Ǫ Ų & % ą \bullet{c} ę \bullet{g} \bullet{h} į ǫ ų \strut\\ % caron & Ǎ Č Ď Ě Ǧ Ǐ Ǩ Ľ & ǎ č ď ě ǧ ǐ ǰ ǩ ľ \strut\\ % & Ň Ǒ Ř Š Ť Ǔ Ž & ň ǒ ř š ť ǔ ž \strut\\ % \rowcolor{nagrey}various & Å Æ Ð (eth) Đ (stroke) IJ\ Ł & % å æ ð đ ij\ ł \strut\\ % \rowcolor{nagrey} & Ŋ Ø Œ Ő Ů Ű Ș Ț Þ & % ŋ ø œ ő ů ű ș ß ț þ \strut\\\bottomrule % \end{tabular} % \footnotetext{A diaeresis mark is one way to indicate a sound change % (\textit{Umlaut}). German originally used a superscript \textsf{e} over % \textsf{a}, \textsf{o}, and \textsf{u}. The cursive form of \textsf{e} % simplified to a diaeresis in the 1800s. A diaeresis also signals % pronouncing a diphthong or digraph as two monophthongs, e.g., ``noëtic''.} % \end{center} % % \newpage % % \subsubsection[Compatibility]{Compatibility: Old and New} % % Since 2018, changes in the way that \texttt{pdflatex} and \texttt{latex} handle Unicode characters have made indexing simpler and more intuitive, e.g. % % \begin{center}\small\medstretch % \begin{tabular}{rllrll}\toprule % pre-2018 text & & index & post-2018 text & & index\\ % \rowcolor{nagrey} ä & \textrightarrow & % \texttt{\cmd{\IeC\textvisiblespace}\{\cmd{\"a}\}} & % ä & \textrightarrow & \texttt{ä}\\ % æ & \textrightarrow & % \texttt{\cmd{\IeC\textvisiblespace}\{\cmd{\ae\textvisiblespace}\}} & % æ & \textrightarrow & \texttt{æ}\\\bottomrule % \end{tabular} % \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. % % One can test for this change and take different approaches as needed. In making such choices, one may need to consult the entries in the \texttt{idx} and \texttt{ind} files to see how the name arguments are being indexed. The basic test is: % % \begin{quote}\small % \cmd{\IfFileExists\{utf8-2018.def\}}\marg{new}\marg{old} % \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: % % \begin{center}\large % \begin{tabular}{ll} % Ā Ē Ḡ Ī Ō Ū Ǣ Ȳ & ā ē ḡ ī ō ū ǣ ȳ\\ % \end{tabular} % \end{center} % % Since 2018, those restrictions have been removed. In order to create a document that can work with old or new versions of \LaTeX, one can conditionally use macrons or not. In a recent version of \LaTeX, one will see a macron in the name % \ifPDFTeX^^A % \IfFileExists{utf8-2018.def}^^A % {\Name{Ghazāli}}{\Name{Ghazali}}^^A % \else\Name{Ghazāli}^^A % \fi. % Otherwise, no macron will be present. We avoid errors that could arise with control sequences like \cmd{\=a} in the index when using \texttt{makeindex} and \texttt{gind.ist} by using the following snippet: % % \begin{quote}\small % \begin{Verbatim} % \ifPDFTeX % \IfFileExists{utf8-2018.def}% % {\Name{Ghazāli}}{\Name{Ghazali}}% % \else\Name{Ghazāli}% % \fi % \end{Verbatim} % \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 2019. % \item We \cmd{\input} the included snippet \texttt{compat.tex} to % allow \texttt{examples.tex} and the test files (see \texttt{README.md}) % to be compatible with different \LaTeX\ engines and older \TeX\ % distributions. The file \texttt{examples.tex} includes additional % examples that deal with compatibility. % \item Use of certain text elements, such as \cmd{\dotfill} within % tables, has become more permissive in recent \TeX\ distributions. % This manual avoids situations that would cause compatibility % problems in older distributions. % \end{itemize} % % \subsubsection[Fragility]{Fragility of Active Unicode} % % \TeX\ macros that partition their arguments can break active Unicode characters.The simple macro |\def\foo#1#2#3!{<#1#2><#3>}| takes three arguments, groups the first two, then the third, followed by a delimiter that ends the argument list: % % \begin{center}\small\medstretch % \def\foo#1#2#3!{<#1#2><#3>} % \begin{tabular}{llll}\toprule % Argument & Macro & Engine & Result\\ % \rowcolor{nagrey}|abc| & |\foo abc!| & (any) & \foo abc!\\ % \rowcolor{nagrey}|{æ}bc| & |\foo {æ}bc!| & (any) & \foo {æ}bc!\\ % \rowcolor{nagrey}|\ae bc| & |\foo \ae bc!| & (any) & \foo \ae bc!\\ % |æbc| & |\foo æbc!| & \texttt{xelatex} & % \ifxetex\foo æbc!\else<æb>\fi\\ % |æbc| & |\foo æbc!| & \texttt{lualatex} & % \ifluatex\foo æbc!\else<æb>\fi\\ % \rowcolor{nagrey}|æbc| & |\foo æbc!| & \texttt{pdflatex} & \foo æbc!\\ % \rowcolor{nagrey}|æbc| & |\foo æbc!| & \texttt{latex} & \foo æbc!\\ % \bottomrule % \end{tabular} % \end{center} % % The letter \texttt{a} is one argument. Since \texttt{\{æ\}} is in a group, it is one argument. The macro \cmd{\ae} also is one argument. Both \texttt{xelatex} and \texttt{lualatex} likewise treat the Unicode letter \texttt{æ} as one argument. Thus, in all these cases, the first two glyphs are grouped together in |#1#2| and \texttt{c} is left by itself in |#3|. % % In \texttt{latex} and \texttt{pdflatex}, however, \texttt{æ} is an active Unicode control sequence that uses two arguments 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 \}}. % % Starting on page \pageref{page:Caps} we show how to test if \cmd{\Umathchar} is not defined. If so, we check if the leading token of the argument matches the start of an active Unicode control sequence. If \cmd{\@car}\meta{test}\cmd{\@nil} is equal to \cmd{\@car ß} \cmd{\@nil} we capitalize |#1#2|, otherwise just |#1|. Should |#1| be a protected macro or something that does not expand to a sequence of letters, we use alternate formatting and \cmd{\AltCaps} (Section~\ref{sec:AltFeatures}). % % \ReturnLink % % \begin{Quote}{\Name{Plato}, opening statement in \textit{Cratylus}} % \Name{Hermogenes}: I should explain to you, \Name{Socrates}, that our friend \Name{Cratylus} has been arguing about names; he says that they are natural and not conventional; not a portion of the human voice which men agree to use; but that there is a truth or correctness in them, which is the same for Hellenes as for barbarians. Whereupon I ask him, whether his own name of \Name{Cratylus} is a true name or not, and he answers `Yes.' And \Name{Socrates}? `Yes.' Then every man's name, as I tell him, is that which he is called. To this he replies{---}`If all the world were to call you \Name{Hermogenes}, that would not be your name.' And when I am anxious to have a further explanation he is ironical and mysterious, and seems to imply that he has a notion of his own about the matter, if he would only tell, and could entirely convince me, if he chose to be intelligible. % \end{Quote} % % \newpage % % \StopEventually{^^A % \let\emph\oldemph % \newgeometry{textheight=239mm,left=20mm,right=20mm,nohead} % \IndexProtect\PrintChanges\newpage\PrintIndex % } % \iffalse %<*package> % \fi % % \section{Implementation} % \small % % 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. % % \subsection{Boolean Flags} % % The \textsf{nameauth} package is a parser. The flags in this section % show the state of that parser. % % \subsubsection{Flow Control} % % \subsubsection*{\hfil Who Called Me?} % % Let name formatting macros in the core name engine know if they were % called by the naming macros or by the pseudonym macros. % % \begin{macrocode} \newif\if@nameauth@InAKA \newif\if@nameauth@InName % \end{macrocode} % % \subsubsection*{\hfil Core Macro Locks} % % \cmd{\@nameauth@Name}, \cmd{\AKA}, and macros that call them use % \texttt{\textbackslash if@nameauth@Lock} to avoid a stack overflow. % Setting \texttt{\textbackslash if@nameauth@BigLock} true will prevent % the core name engine from executing until it is set false. % % \begin{macrocode} \newif\if@nameauth@Lock \newif\if@nameauth@BigLock % \end{macrocode} % % \subsubsection*{\hfil Formatting Hook Indicator} % % Tell alternate formatting control macros that they are in % a formatting hook. % % \begin{macrocode} \newif\if@nameauth@InHook % \end{macrocode} % % \subsubsection*{\hfil Core Name Engine Choices} % % \cmd{\JustIndex} toggles this flag, which makes the core name engine % act like \cmd{\IndexName}. % % \begin{macrocode} \newif\if@nameauth@JustIndex % \end{macrocode} % These two flags trigger \cmd{\ForgetName} and \cmd{\SubvertName} % within \cmd{\@nameauth@Name}. % % \begin{macrocode} \newif\if@nameauth@Forget \newif\if@nameauth@Subvert % \end{macrocode} % % \subsubsection[Syntax]{Name Grammar and Syntax} % % \subsubsection*{\hfil Name Types} % % These flags\Info{\texttt{\textbackslash ifNameauthWestern}\break % \texttt{\textbackslash ifNameauthObsolete}} % reflect the last name type evaluated by any macro that takes % name arguments. The first shows whether or not we have a Western % or non-Western name. The second shows the kind of non-Western % syntax used. These are not reset after evaluation. % % \begin{macrocode} \newif\ifNameauthWestern \newif\ifNameauthObsolete % \end{macrocode} % % \subsubsection*{\hfil Show/Hide Affix Commas} % % The \texttt{comma} and \texttt{nocomma} options toggle the first % flag below. \cmd{\ShowComma} and \cmd{\NoComma} respectively toggle % the second and third. % % \begin{macrocode} \newif\if@nameauth@AlwaysComma \newif\if@nameauth@ShowComma \newif\if@nameauth@NoComma % \end{macrocode} % % \subsubsection*{\hfil Capitalize Entire Surnames} % % The first flag is global. The second is for individual names. % % \begin{macrocode} \newif\if@nameauth@AllCaps \newif\if@nameauth@AllThis % \end{macrocode} % % \subsubsection*{\hfil Reverse Name Order} % % These flags govern name reversing. The first is global. % The second is for individual names. % % \begin{macrocode} \newif\if@nameauth@RevAll \newif\if@nameauth@RevThis % \end{macrocode} % These flags deals with Western names ordered % in a list according to surname. % % \begin{macrocode} \newif\if@nameauth@RevAllComma \newif\if@nameauth@RevThisComma % \end{macrocode} % % \subsubsection*{\hfil Full Stop Detection} % % This flag is used to prevent double full stops after a name % is displayed. % % \begin{macrocode} \newif\if@nameauth@Punct % \end{macrocode} % % \subsubsection*{\hfil Name Breaking} % % \cmd{\KeepAffix} toggles the first flag below, while \cmd{\KeepName} % toggles the second. Both affect the use of non-breaking spaces % in the text. % % \begin{macrocode} \newif\if@nameauth@NBSP \newif\if@nameauth@NBSPX % \end{macrocode} % % \subsubsection*{\hfil Long and Short Names} % % \texttt{\textbackslash if@nameauth@FullName} is true for a long % name form. \texttt{\textbackslash if@nameauth@FirstName} causes only % Western forenames or non-Western surnames to be displayed when a shorter % form is used. The default is to reset both globally on a per-name basis. % % \texttt{\textbackslash if@nameauth@ShortSNN} is used with % \cmd{\DropAffix} to suppress the affix of a Western name. % \texttt{\textbackslash if@nameauth@EastFN} toggles the forced printing % of Eastern forenames. % % \begin{macrocode} \newif\if@nameauth@FullName \newif\if@nameauth@FirstName \newif\if@nameauth@AltAKA \newif\if@nameauth@ShortSNN \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. % % \begin{macrocode} \newif\if@nameauth@LongIdxDebug % \end{macrocode} % % \subsubsection{Indexing} % % \subsubsection*{\hfil Toggle Indexing} % % The indexing flags permit or prevent indexing and tags. % \cmd{\IndexActive} and \cmd{\IndexInctive} or the \texttt{index} and % \texttt{noindex} options toggle the first flag; \cmd{\SkipIndex} % toggles the second. % % \begin{macrocode} \newif\if@nameauth@DoIndex \newif\if@nameauth@SkipIndex % \end{macrocode} % % \subsubsection*{\hfil Toggle Index Sorting} % % Allow or prevent the insertion of index sort keys. % % \begin{macrocode} \newif\if@nameauth@Pretag % \end{macrocode} % % \subsubsection*{\hfil Verbose Warnings} % % Control the number of warnings concerning the index; default is terse. % % \begin{macrocode} \newif\if@nameauth@Verbose % \end{macrocode} % % \subsubsection*{\hfil Cross-References} % % Tell the index entry formatter to create a cross-reference. % % \begin{macrocode} \newif\if@nameauth@Xref % \end{macrocode} % Determine whether \cmd{\IndexRef} creates a \textit{see} reference % or a \textit{see also} reference. % % \begin{macrocode} \newif\if@nameauth@SeeAlso % \end{macrocode} % % \subsubsection[Formatting]{Formatting and Name Control Sequences} % % \subsubsection*{\hfil Choose Formatting System} % % \cmd{\NamesActive} and \cmd{\NamesInactive}, with the % \texttt{mainmatter} and \texttt{frontmatter} options, toggle % formatting hooks via \texttt{\textbackslash if@nameauth@MainFormat}. % % \begin{macrocode} \newif\if@nameauth@MainFormat % \end{macrocode} % % \subsubsection*{\hfil Modify Pseudonym Formatting} % % Permit \cmd{\AKA} and related macros to call the first-use formatting % hooks once. % % \begin{macrocode} \newif\if@nameauth@AKAFormat % \end{macrocode} % % \subsubsection*{\hfil Select Formatting Hooks} % % \texttt{\textbackslash if@nameauth@FirstFormat} triggers the first-use % hooks to be called; otherwise the second-use hooks are called. % Additionally, \texttt{\textbackslash if@nameauth@AlwaysFormat} forces % this true, except when \texttt{\textbackslash if@nameauth@AKAFormat} % is false. % % \begin{macrocode} \newif\if@nameauth@FirstFormat \newif\if@nameauth@AlwaysFormat % \end{macrocode} % % \subsubsection*{\hfil Caps and Alternate Formatting} % % The next flags deal with first-letter capitalization. \cmd{\CapThis} % sets the first Boolean value. The second is triggered by % \cmd{\@nameauth@UTFtest} when it encounters an active Unicode character. % The third is a fallback triggered by \cmd{\AccentCapThis}. The fourth % disables \cmd{\CapThis} for alternate formatting. The fifth toggles % alternate formatting within formatting hooks. % % \begin{macrocode} \newif\if@nameauth@DoCaps \newif\if@nameauth@UTF \newif\if@nameauth@Accent \newif\if@nameauth@AltFormat \newif\if@nameauth@DoAlt % \end{macrocode} % % \subsubsection{Name Decisions} % % \subsubsection*{\hfil Creating and Destroying Name Patterns} % % Restrict the creation and destruction of name patters to the current % name system if true. % % \begin{macrocode} \newif\if@nameauth@LocalNames % \end{macrocode} % % \subsubsection*{\hfil Scope of Name Decision Macros} % % \cmd{\IfMainName}, \cmd{\IfFrontName}, and \cmd{\IfAKA} use % locally-scoped paths by default. When true, this flag causes these % macros to not apply local scope, retaining the current scope. % % \begin{macrocode} \newif\if@nameauth@GlobalScope % \end{macrocode} % % \subsubsection[Compatibility]{Version Compatibility} % % \texttt{\textbackslash if@nameauth@AltAKA} is toggled respectively % by \cmd{\AKA} and \cmd{\AKA*} to print a longer or shorter name. % \texttt{\textbackslash if@nameauth@OldAKA} forces the pre-3.0 behavior % of \cmd{\AKA*}. % % \begin{macrocode} \newif\if@nameauth@OldAKA % \end{macrocode} % Determine how strict to be with \textit{see} references. % % \begin{macrocode} \newif\if@nameauth@OldSee % \end{macrocode} % These three flags are used only for backward compatibility. The first % broadly determines how per-name flags are reset; the second affects the % behavior of \cmd{\JustIndex}; and the third toggles whether or not the % name argument token registers are set globally. % % \begin{macrocode} \newif\if@nameauth@OldReset \newif\if@nameauth@OldPass \newif\if@nameauth@OldToks % \end{macrocode} % % \subsection[Registers, Hooks, Values] % {Token Registers, Hooks, and Internal Values} % % \subsubsection[Token Registers]{Name Argument Token Registers} % % \begin{macro}{\@nameauth@toksa} % \begin{macro}{\@nameauth@toksb} % \begin{macro}{\@nameauth@toksc} % These three token registers contain the current values of the name % arguments passed to \cmd{\Name}, its variants, and the cross-reference % arguments of \cmd{\AKA}. Users can access them especially in % formatting hooks. % % \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. % % \begin{macrocode} \newtoks\@nameauth@etoksb \newtoks\@nameauth@etoksc \newtoks\@nameauth@etoksd % \end{macrocode} % % \subsubsection{Hooks} % % \begin{macro}{\NamesFormat} % Post-process ``first'' instance of final complete name form in text. % See Sections~\ref{sec:Formatting} and~\ref{sec:ComplexHooks}. Called when % both |\@nameauth@MainFormat| and |\@nameauth@FirstFormat| are true. % % \begin{macrocode} \newcommand*\NamesFormat{} % \end{macrocode} % \end{macro} % % \begin{macro}{\MainNameHook} % \changes{2.4}{2016/03/15}{Added} % Post-process subsequent instance of final complete name form in % main-matter text. See Sections~\ref{sec:Formatting} % and~\ref{sec:ComplexHooks}f. Called when |\@nameauth@MainFormat| is true % and the Boolean flag |\@nameauth@FirstFormat| is false. % % \begin{macrocode} \newcommand*\MainNameHook{} % \end{macrocode} % \end{macro} % % \begin{macro}{\FrontNamesFormat} % \changes{2.5}{2016/04/06}{Added} % Post-process ``first'' instance of final complete name form in % front-matter text. Called when |\@nameauth@MainFormat| is false % and |\@nameauth@FirstFormat| is true. % % \begin{macrocode} \newcommand*\FrontNamesFormat{} % \end{macrocode} % \end{macro} % % \begin{macro}{\FrontNameHook} % \changes{2.4}{2016/03/15}{Added} % Post-process subsequent instance of final complete name form in % front-matter text. Called when |\@nameauth@MainFormat| is false % and |\@nameauth@FirstFormat| is false. % % \begin{macrocode} \newcommand*\FrontNameHook{} % \end{macrocode} % \end{macro} % % \noindent The following three macros usually point to the core name % engine, \cmd{\@nameauth@Name}. They allow users to customize the naming % macros in the fullest sense. See Section~\ref{sec:FullCustomize}. % % \begin{macro}{\NameauthName} % \changes{2.2}{2015/12/01}{Added} % Hook called when no special name modification is made. % % \begin{macrocode} \newcommand*\NameauthName{\@nameauth@Name} % \end{macrocode} % \end{macro} % % \begin{macro}{\NameauthLName} % \changes{2.3}{2016/01/05}{Added} % Hook called after a name is forced long via % \texttt{\textbackslash if@nameauth@name} being set to true. % % \begin{macrocode} \newcommand*\NameauthLName{\@nameauth@Name} % \end{macrocode} % \end{macro} % % \begin{macro}{\NameauthFName} % \changes{2.2}{2015/12/01}{Added} % Hook called after \texttt{\textbackslash if@nameauth@FirstName} % is set true. % % \begin{macrocode} \newcommand*\NameauthFName{\@nameauth@Name} % \end{macrocode} % \end{macro} % % \begin{macro}{\NameauthIndex} % \changes{3.5}{2020/11/23}{Added} % This hook allows one to redefine what happens when any naming macro % or indexing macro calls the equivalent of \cmd{\index}. See % Section~\ref{sec:GeneralIndex}. % % \begin{macrocode} \newcommand*\NameauthIndex{\index} % \end{macrocode} % \end{macro} % % \begin{macro}{\NameauthPattern} % \changes{3.7}{2023/02/03}{Added} % Gives access to the current name control pattern. This hook can be % used, e.g., in formatting hooks to recall a name data tag % (Section~\ref{sec:DataTagHooks}). We preset it to an empty value. With % every call to a macro that takes name arguments % (Section~\ref{sec:NameArgMacros}), this hook is updated. % % \begin{macrocode} \let\NameauthPattern\@empty % \end{macrocode} % \end{macro} % % \subsubsection{Internal Values} % % \begin{macro}{\@nameauth@Actual} % \changes{2.0}{2015/11/11}{Added} % \changes{3.5}{2020/11/23}{Use \cmd{\def}} % This sets the ``actual'' character used by \textsf{nameauth} for % index sorting. This lets one use, for example, |\global\IndexActual{=}|. % % \begin{macrocode} \def\@nameauth@Actual{@} % \end{macrocode} % \end{macro} % % \begin{macro}{\@nameauth@Exclude} % \changes{3.5}{2020/11/23}{Added} % This makes an xref into an ``exclusion''. An exclusion is any name % control sequence ending in \texttt{!PN} that expands to this value. % See \cmd{\ExcludeName}. % % \begin{macrocode} \newcommand*\@nameauth@Exclude{!} % \end{macrocode} % \end{macro} % % \begin{macro}{\@nameauth@space} % \changes{3.7}{2023/02/03}{Made global} % This macro provides a consistent space character for index entries. % % \begin{macrocode} \def\@nameauth@space{ } % \end{macrocode} % \end{macro} % % \subsection{Package Options} % % \subsubsection[Syntax]{Name Grammar and Syntax} % % Change the way that names are displayed, specifically with respect to their syntactic forms. % % \begin{macrocode} \DeclareOption{nocomma}{\@nameauth@AlwaysCommafalse} \DeclareOption{comma}{\@nameauth@AlwaysCommatrue} \DeclareOption{normalcaps}{\@nameauth@AllCapsfalse} \DeclareOption{allcaps}{\@nameauth@AllCapstrue} \DeclareOption{notreversed}% {\@nameauth@RevAllfalse\@nameauth@RevAllCommafalse} \DeclareOption{allreversed}% {\@nameauth@RevAlltrue\@nameauth@RevAllCommafalse} \DeclareOption{allrevcomma}% {\@nameauth@RevAllfalse\@nameauth@RevAllCommatrue} % \end{macrocode} % % \subsubsection{Indexing} % % Global setting for enabling indexing, sort tags, and verbose warnings. % % \begin{macrocode} \DeclareOption{index}{\@nameauth@DoIndextrue} \DeclareOption{noindex}{\@nameauth@DoIndexfalse} \DeclareOption{pretag}{\@nameauth@Pretagtrue} \DeclareOption{nopretag}{\@nameauth@Pretagfalse} \DeclareOption{verbose}{\@nameauth@Verbosetrue} % \end{macrocode} % % \subsubsection{Formatting} % % Start off in a different naming regime or change formatting behavior in general or for \cmd{\AKA}. % % \begin{macrocode} \DeclareOption{mainmatter}{\@nameauth@MainFormattrue} \DeclareOption{frontmatter}{\@nameauth@MainFormatfalse} \DeclareOption{alwaysformat}{\@nameauth@AlwaysFormattrue} \DeclareOption{formatAKA}{\@nameauth@AKAFormattrue} % \end{macrocode} % % \subsubsection[Predefined Hooks]{Predefined Formatting Hooks} % % \begin{macrocode} \DeclareOption{noformat}{\renewcommand*\NamesFormat{}} \DeclareOption{smallcaps}{\renewcommand*\NamesFormat{\scshape}} \DeclareOption{italic}{\renewcommand*\NamesFormat{\itshape}} \DeclareOption{boldface}{\renewcommand*\NamesFormat{\bfseries}} % \end{macrocode} % % \subsubsection{Alternate Formatting} % % Enable alternate formatting. % % \begin{macrocode} \DeclareOption{altformat}{% \@nameauth@AltFormattrue\@nameauth@DoAlttrue} % \end{macrocode} % % \subsubsection{Scope} % % Name test paths are either local or the same scope in which they are called. % % \begin{macrocode} \DeclareOption{globaltest}{\@nameauth@GlobalScopetrue} % \end{macrocode} % % \subsubsection[Compatibility]{Version Compatibility} % % Revert package behavior to mimic older versions. % % \begin{macrocode} \DeclareOption{oldAKA}{\@nameauth@OldAKAtrue} \DeclareOption{oldreset}{\@nameauth@OldResettrue} \DeclareOption{oldpass}{\@nameauth@OldPasstrue} \DeclareOption{oldtoks}{\@nameauth@OldTokstrue} \DeclareOption{oldsee}{\@nameauth@OldSeetrue} % \end{macrocode} % % \subsection{Package Initialization} % % Execute default options and process options passed by the user. % Load required packages for $\epsilon$-\TeX\ features, trimming % spaces from arguments, starred commands, and optional arguments. % % \begin{macrocode} \ExecuteOptions {nocomma,mainmatter,index,pretag, normalcaps,notreversed,noformat} \ProcessOptions\relax \RequirePackage{etoolbox} \RequirePackage{trimspaces} \RequirePackage{suffix} \RequirePackage{xargs} % \end{macrocode} % % \subsection{Internal Macros} % \label{sec:InternalMacros} % % \subsubsection{Fundamental Macros} % % The following macros are the most essential to the concept of ``name''. % % \subsubsection*{\hfil Name Control Sequence: Who Am I?} % % \begin{macro}{\@nameauth@Clean} % Thanks to \Name*[Heiko]{Oberdiek}, this macro produces a ``sanitized'' % string to make a control sequence for a name. Testing the existence of % that control sequence is the core of \textsf{nameauth}. % % \begin{macrocode} \newcommand*\@nameauth@Clean[1] {\expandafter\zap@space\detokenize{#1} \@empty} % \end{macrocode} % \end{macro} % % \begin{macro}{\@nameauth@MakeCS} % \changes{3.5}{2020/11/23}{Added} % Unless we are in \cmd{\AKA}, create a name control sequence % in the core name engine. % % \begin{macrocode} \newcommand*\@nameauth@MakeCS[1] {% \unless\ifcsname#1\endcsname \unless\if@nameauth@InAKA\csgdef{#1}{}\fi \fi } % \end{macrocode} % \end{macro} % % \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. % % \begin{macrocode} \newcommand*\@nameauth@Root[1]{\@nameauth@@Root#1,\\} % \end{macrocode} % \end{macro} % % \begin{macro}{\@nameauth@@Root} % \changes{2.0}{2015/11/11}{Trim spaces} % \changes{3.0}{2016/10/26}{Redesigned} % \changes{3.2}{2017/03/22}{Renamed} % Throw out the comma and suffix, return the radix. % % \begin{macrocode} \def\@nameauth@@Root#1,#2\\{\trim@spaces{#1}} % \end{macrocode} % \end{macro} % % \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. % % \begin{macrocode} \newcommand*\@nameauth@TrimTag[1]{\@nameauth@@TrimTag#1|\\} % \end{macrocode} % \end{macro} % % \begin{macro}{\@nameauth@@TrimTag} % \changes{3.0}{2016/10/26}{Added} % Throw out the bar and suffix, return the radix. % % \begin{macrocode} \def\@nameauth@@TrimTag#1|#2\\{#1} % \end{macrocode} % \end{macro} % % \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. % % \begin{macrocode} \newcommand*\@nameauth@Suffix[1]{\@nameauth@@Suffix#1,,\\} % \end{macrocode} % \end{macro} % % \begin{macro}{\@nameauth@@Suffix} % \changes{0.9}{2012/02/10}{Added} % \changes{1.5}{2013/02/22}{Trim spaces} % \changes{3.0}{2016/10/26}{New test} % \changes{3.2}{2017/03/22}{Renamed} % Throw out the radix; return the suffix with no leading spaces. % Used to print the suffix. % % \begin{macrocode} \def\@nameauth@@Suffix#1,#2,#3\\{% \ifx\\#2\\\@empty\else\trim@spaces{#2}\fi } % \end{macrocode} % \end{macro} % % \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. % % \begin{macrocode} \newcommand*\@nameauth@GetSuff[1]{\@nameauth@@GetSuff#1,,\\} % \end{macrocode} % \end{macro} % % \begin{macro}{\@nameauth@@GetSuff} % \changes{3.2}{2017/03/22}{Added} % Throw out the radix; return the suffix. % % \begin{macrocode} \def\@nameauth@@GetSuff#1,#2,#3\\{#2} % \end{macrocode} % \end{macro} % % \subsubsection*{\hfil Parsing: Capitalization} % \label{page:Caps} % % \begin{macro}{\@nameauth@TestToks} % \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. % % \begin{macrocode} \newcommand*\@nameauth@TestToks[1] {% \toks@\expandafter{\@car#1\@nil}% \edef\@nameauth@one{\the\toks@}% \toks@\expandafter{\@carß\@nil}% \edef\@nameauth@two{\the\toks@}% \ifx\@nameauth@one\@nameauth@two \@nameauth@UTFtrue% \else \@nameauth@UTFfalse% \fi } % \end{macrocode} % \end{macro} % % \begin{macro}{\@nameauth@UTFtest} % \changes{3.0}{2016/10/26}{Added} % \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}. % % \begin{macrocode} \newcommand*\@nameauth@UTFtest[1] {% \def\@nameauth@testarg{#1}% \ifdefined\Umathchar \@nameauth@UTFfalse% \else \ifdefined\UTFviii@two@octets \if@nameauth@Accent \@nameauth@UTFtrue\@nameauth@Accentfalse% \else \expandafter\@nameauth@TestToks \expandafter{\@nameauth@testarg}% \fi \else \@nameauth@UTFfalse% \fi \fi } % \end{macrocode} % \end{macro} % % \begin{macro}{\@nameauth@UTFtestS} % \changes{3.2}{2017/03/22}{Added} % \changes{3.5}{2020/11/23}{Fix namespace} % This test is like the one above, but a special case when we have % a suffix. We have to do a bit more in the way of expansion to get % the comparison to work properly. Moreover, we only use this when % the regular suffix macro is not \cmd{\@empty}. % % \begin{macrocode} \newcommand*\@nameauth@UTFtestS[1] {% \expandafter\def\expandafter\@nameauth@testarg% \expandafter{\@nameauth@GetSuff{#1}}% % \end{macrocode} % This following token register assignment looks weird, but it is % how we get a test that works. % % \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. % % \begin{macrocode} \expandafter\def\expandafter\@nameauth@test@rg% \expandafter{\the\toks@}% \ifdefined\Umathchar \@nameauth@UTFfalse% \else \ifdefined\UTFviii@two@octets \if@nameauth@Accent \@nameauth@UTFtrue\@nameauth@Accentfalse% \else \expandafter\@nameauth@TestToks% \expandafter{\@nameauth@test@rg}% \fi \else \@nameauth@UTFfalse% \fi \fi } % \end{macrocode} % \end{macro} % % \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}. % % \begin{macrocode} \newcommand*\@nameauth@Cap[1]{\@nameauth@C@p#1\\} % \end{macrocode} % \end{macro} % % \begin{macro}{\@nameauth@C@p} % \changes{3.1}{2017/01/13}{Added} % \changes{3.2}{2017/03/22}{Renamed, use \cmd{\MakeUppercase}} % Helper macro for the one above. % % \begin{macrocode} \def\@nameauth@C@p#1#2\\{% \expandafter\trim@spaces\expandafter{\MakeUppercase{#1}#2}% } % \end{macrocode} % \end{macro} % % \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). % % \begin{macrocode} \newcommand*\@nameauth@CapUTF[1]{\@nameauth@C@pUTF#1\\} % \end{macrocode} % \end{macro} % % \begin{macro}{\@nameauth@C@pUTF} % \changes{3.1}{2017/01/13}{Added} % \changes{3.2}{2017/03/22}{Use \cmd{\MakeUppercase}} % Helper macro for the one above. % % \begin{macrocode} \def\@nameauth@C@pUTF#1#2#3\\{% \expandafter\trim@spaces\expandafter{\MakeUppercase{#1#2}#3}% } % \end{macrocode} % \end{macro} % % \begin{macro}{\@nameauth@CapArgs} % \changes{3.5}{2020/11/23}{Added} % Capitalize the first letter of all name arguments. Implements % capitalization on demand in the body text (not the index) when not % in alternate formatting. We only use this macro in the local scope % of \cmd{\@nameauth@Parse}. Uses the foregoing macros. % % \begin{macrocode} \newcommand*\@nameauth@CapArgs[3] {% \ifdefined\@nameauth@InParser \unless\if@nameauth@AltFormat \let\carga\arga% \let\crootb\rootb% \let\csuffb\suffb% \let\cargc\argc% % \end{macrocode} % We test \meta{FNN} for active, non-native Unicode % characters, then cap the first letter. % % \begin{macrocode} \unless\ifx\arga\@empty \def\test{#1}% \expandafter\@nameauth@UTFtest\expandafter{\test}% % \end{macrocode} % Capitalize the first active Unicode character. % % \begin{macrocode} \if@nameauth@UTF \expandafter\def\expandafter\carga\expandafter{% \expandafter\@nameauth@CapUTF\expandafter{\test}}% % \end{macrocode} % Capitalize the first native Unicode character (not active). % % \begin{macrocode} \else \expandafter\def\expandafter\carga\expandafter{% \expandafter\@nameauth@Cap\expandafter{\test}}% \fi \fi % \end{macrocode} % We test \meta{SNN} for active Unicode characters, % then cap the first letter. % % \begin{macrocode} \def\test{#2}% \expandafter\@nameauth@UTFtest\expandafter{\test}% % \end{macrocode} % Capitalize the first active Unicode character. % % \begin{macrocode} \if@nameauth@UTF \expandafter\def\expandafter\crootb\expandafter{% \expandafter\@nameauth@CapUTF\expandafter{\rootb}}% % \end{macrocode} % Capitalize the first native character (not active). % % \begin{macrocode} \else \expandafter\def\expandafter\crootb\expandafter{% \expandafter\@nameauth@Cap\expandafter{\rootb}}% \fi % \end{macrocode} % We test \meta{Affix} for active Unicode characters, % then cap the first letter. % % \begin{macrocode} \unless\ifx\suffb\@empty \def\test{#2}% \expandafter\@nameauth@UTFtestS\expandafter{\test}% \protected@edef\test{\@nameauth@GetSuff{#2}}% % \end{macrocode} % Capitalize the first active Unicode character. % % \begin{macrocode} \if@nameauth@UTF \protected@edef\test{\@nameauth@Suffix{#2}}% \expandafter\def\expandafter\csuffb\expandafter{% \expandafter\@nameauth@CapUTF\expandafter{\test}}% % \end{macrocode} % Capitalize the first native Unicode character (not active). % % \begin{macrocode} \else \edef\@nameauth@test{\@nameauth@Suffix{#2}}% \expandafter\def\expandafter\csuffb\expandafter{% \expandafter\@nameauth@Cap\expandafter{\test}}% \fi \fi % \end{macrocode} % We test \meta{Alternate} for active Unicode characters, % then cap the first letter. % % \begin{macrocode} \unless\ifx\argc\@empty \def\test{#3}% \expandafter\@nameauth@UTFtest\expandafter{\test}% % \end{macrocode} % Capitalize the first active Unicode character. % % \begin{macrocode} \if@nameauth@UTF \expandafter\def\expandafter\cargc\expandafter{% \expandafter\@nameauth@CapUTF\expandafter{\test}}% % \end{macrocode} % Capitalize the first native Unicode character (not active). % % \begin{macrocode} \else \expandafter\def\expandafter\cargc\expandafter{% \expandafter\@nameauth@Cap\expandafter{\test}}% \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. % % \begin{macrocode} \let\arga\carga% \let\rootb\crootb% \let\suffb\csuffb% \let\argc\cargc% \fi \fi } % \end{macrocode} % \end{macro} % % \subsubsection*{\hfil Parsing: Full Stops} % % \begin{macro}{\@nameauth@TestDot} % \changes{3.5}{2020/11/23}{Redesigned} % This macro, based on a snippet by \Name*[Uwe]{Lueck}, checks for % a full stop at the end of its argument using the two internal helper % macros below. % % \begin{macrocode} \newcommand*\@nameauth@TestDot[1] {% % \end{macrocode} % If no full stop is present, \texttt{\#\#1} is associated with the first % \cmd{\@End.} The second \cmd{\@End} gets absorbed, leaving % \texttt{\#\#2} empty. If a full stop is present, \texttt{\#\#2} % will contain it. % % \begin{macrocode} \def\@nameauth@TestD@t##1.\@End##2\\{\@nameauth@TestPunct{##2}}% % \end{macrocode} % The two control sequences are equal if \texttt{\#\#1} is empty % (no full stop). If \texttt{\#\#1} is not empty, it sets % \cmd{\@nameauth@Puncttrue}, which triggers the call to % \cmd{\@nameauth@CheckDot} below. One cannot use \cmd{\unless} below. % % \begin{macrocode} \def\@nameauth@TestPunct##1% {% \ifx\@nameauth@TestPunct##1\@nameauth@TestPunct \else \global\@nameauth@Puncttrue% \fi }% \global\@nameauth@Punctfalse% \@nameauth@TestD@t#1\@End.\@End\\% } % \end{macrocode} % \end{macro} % % \begin{macro}{\@nameauth@CheckDot} % We assume that \cmd{\expandafter} precedes the invocation of % \cmd{\@nameauth@CheckDot}, which only is called if the terminal % character of the input is a period. We evaluate the lookahead % \cmd{\@nameauth@token} while keeping it on the list of input tokens. % % \begin{macrocode} \newcommand*\@nameauth@CheckDot {\futurelet\@nameauth@token\@nameauth@EvalDot} % \end{macrocode} % \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. % % \begin{macrocode} \newcommand*\@nameauth@EvalDot {% \let\@nameauth@stop=.% \ifx\@nameauth@token\@nameauth@stop \expandafter\@gobble \fi } % \end{macrocode} % \end{macro} % % \newpage % % \subsubsection*{\hfil Parsing: Breaking, Spaces, and Commas} % % \begin{macro}{\@nameauth@AddPunct} % \changes{3.5}{2020/11/23}{Added} % Here we govern whether (in the text, not the index) spaces between % name elements break or not, and whether to add commas or not. Much % applies only to Western names, thus we check if \meta{FNN} is empty % or not. We only use this macro in \cmd{\@nameauth@Parse}. % % \begin{macrocode} \newcommand*\@nameauth@AddPunct {% \ifdefined\@nameauth@InParser \def\Space{ }% \def\SpaceW{ }% % \end{macrocode} % \cmd{\SpaceW} is used for the space between a Western name and an affix, % specifically tied to \cmd{\KeepAffix}. \cmd{\Space} is used for all % other spaces between name elements. % % \begin{macrocode} \if@nameauth@NBSP \edef\Space{\nobreakspace}\fi \if@nameauth@NBSPX \edef\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. % % \begin{macrocode} \unless\ifx\arga\@empty \if@nameauth@AlwaysComma \def\Space{, }% \if@nameauth@NBSP\edef\Space{,\nobreakspace}\fi \fi \if@nameauth@ShowComma \def\Space{, }% \if@nameauth@NBSP\edef\Space{,\nobreakspace}\fi \fi \if@nameauth@NoComma \def\Space{ }% \if@nameauth@NBSP\edef\Space{\nobreakspace}\fi \fi \fi \fi } % \end{macrocode} % \end{macro} % % \subsubsection*{\hfil Parsing: Name Argument Loading} % % \begin{macro}{\@nameauth@LoadArgs} % \changes{3.5}{2020/11/23}{Added} % Assign name arguments to internal macros to determine name syntax. % This is used in all macros that take name arguments. % % \begin{macrocode} \newcommand*\@nameauth@LoadArgs[3] {% % \end{macrocode} % We want these arguments to expand to \cmd{\@empty} (or not) % when we test them. % % \begin{macrocode} \protected@edef\@nameauth@A{\trim@spaces{#1}}% \protected@edef\@nameauth@B{\@nameauth@Root{#2}}% \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. % % \begin{macrocode} \def\@nameauth@csb{\@nameauth@Clean{#2}}% \def\@nameauth@csbc{\@nameauth@Clean{#2,#3}}% \def\@nameauth@csab{\@nameauth@Clean{#1!#2}}% } % \end{macrocode} % \end{macro} % % \subsubsection*{\hfil Parsing: Standard Parsing Logic} % % \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} % This standard logic applies to all macros that take name arguments. Here % we update \cmd{\NameauthPattern}, % \texttt{\textbackslash ifNameauthWestern}, and % \texttt{\textbackslash ifNameauthObsolete} to show the resulting name % pattern and type of name, usable in formatting hooks. % % \begin{macrocode} \newcommand\@nameauth@Choice[3] {% \ifx\@nameauth@A\@empty \ifx\@nameauth@C\@empty % \end{macrocode} % This decision path is for non-Western names. The \texttt{\#1} argument % recurs below where \cmd{\@nameauth@SB} is present. Thus, for output % to the text, the \texttt{\#1} argument must test both \cmd{\@nameauth@C} % and \cmd{\@nameauth@SB}, and swap the former with the latter if % necessary. For output to the index or for handling control sequences, % one ignores \cmd{\@nameauth@C}. % % \begin{macrocode} \let\NameauthPattern\@nameauth@csb% \NameauthWesternfalse \NameauthObsoletefalse% #1% \else \ifx\@nameauth@SB\@empty % \end{macrocode} % The \texttt{\#2} argument is only for non-Western names that use % the obsolete syntax. In the \texttt{\#2} argument \cmd{\@nameauth@SB} % never occurs. For indexing and control sequences, one cannot ignore % the use of \cmd{\@nameauth@C} in this path. % % \begin{macrocode} \let\NameauthPattern\@nameauth@csbc% \NameauthWesternfalse \NameauthObsoletetrue% #2% \else % \end{macrocode} % But if both \cmd{\@nameauth@SB} and \cmd{\@nameauth@C} are present, % we invoke the \texttt{\#1} argument instead and let it do any further % testing and processing. % % \begin{macrocode} \let\NameauthPattern\@nameauth@csb% \NameauthWesternfalse \NameauthObsoletefalse% #1% \fi \fi \else % \end{macrocode} % This decision path is for Western names. In those cases where one % must work with name forms in the text, somewhere in the \texttt{\#3} % argument one must test for \cmd{\@nameauth@C} and swap it for % \cmd{\@nameauth@A}, as well as accounting for the presence or absence % of \cmd{\@nameauth@SB}. Otherwise, for indexing and control sequences, % one ignores \cmd{\@nameauth@C} in this path and handles % \cmd{\@nameauth@SB} appropriately. % % \begin{macrocode} \let\NameauthPattern\@nameauth@csab% \NameauthWesterntrue \NameauthObsoletefalse% #3% \fi } % \end{macrocode} % \end{macro} % % \begin{macro}{\@nameauth@Flags} % \changes{3.5}{2020/09/25}{Added} % Reset flags after the naming macros and \cmd{\AKA} and friends create % output in the text. Other places in the core naming engine where flags % are reset are for special cases like \cmd{\JustIndex}. % % \begin{macrocode} \newcommand*\@nameauth@Flags {% \if@nameauth@OldReset % \end{macrocode} % The \texttt{oldreset} option implies not only a difference % in scope regarding how flags are reset, but it also lets the effects % of \cmd{\ForgetThis} and \cmd{\SubvertThis} to pass through \cmd{\AKA} % and \cmd{\AKA*}. Regardless, we only reset \texttt{\textbackslash % if@nameauth@AltAKA} here due to macros like \cmd{\PName}. % % \begin{macrocode} \if@nameauth@InAKA\@nameauth@AltAKAfalse\fi \@nameauth@SkipIndexfalse% \if@nameauth@InName \@nameauth@Forgetfalse% \@nameauth@Subvertfalse% \fi \@nameauth@NBSPfalse% \@nameauth@NBSPXfalse% \@nameauth@DoCapsfalse% \@nameauth@Accentfalse% \@nameauth@AllThisfalse% \@nameauth@ShowCommafalse% \@nameauth@NoCommafalse% \@nameauth@RevThisfalse% \@nameauth@RevThisCommafalse% \@nameauth@ShortSNNfalse% \@nameauth@EastFNfalse% \else % \end{macrocode} % The current way that the flags are reset makes them both global % and more uniform, hopefully eliminating a few chances for errors % that might be quite difficult to debug. % % \begin{macrocode} \if@nameauth@InAKA\global\@nameauth@AltAKAfalse\fi \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@RevThisCommafalse% \global\@nameauth@ShortSNNfalse% \global\@nameauth@EastFNfalse% \fi } % \end{macrocode} % \end{macro} % % \subsubsection[Errors/Debugging]{Error Detection and Debugging} % % \begin{macro}{\@nameauth@Error} % \changes{3.0}{2016/10/26}{Added} % \changes{3.01}{2016/10/27}{Fixed} % \changes{3.5}{2020/11/23}{Fix namespace} % The \textsf{nameauth} package will halt with a meaningful error % when a required name argument is empty, expands to empty, % has an empty root in a malformed root/suffix pair. % % \begin{macrocode} \newcommand*\@nameauth@Error[2] {% \edef\@nameauth@msga{#2 SNN arg empty}% \edef\@nameauth@msgb{#2 SNN arg malformed}% \protected@edef\@nameauth@testname{\trim@spaces{#1}}% \protected@edef\@nameauth@testroot{\@nameauth@Root{#1}}% \ifx\@nameauth@testname\@empty \PackageError{nameauth}{\@nameauth@msga}% \fi \ifx\@nameauth@testroot\@empty \PackageError{nameauth}{\@nameauth@msgb}% \fi } % \end{macrocode} % \end{macro} % % \begin{macro}{\@nameauth@IdxPageref} % \changes{3.3}{2020/02/20}{Added} % \changes{3.5}{2020/11/23}{Use index hook, optimize logic, % fix name space, use Boolean flags} % \changes{3.7}{2023/02/03}{Renamed; only show index entries; % add warning; optimized} % Here we set up a local scope because we make changes that would % otherwise affect normal \textsf{nameauth} output. We redefine % \cmd{\NameauthIndex} to print an argument in the text instead of % the index, and we force indexing to occur. % % \begin{macrocode} \newcommand*\@nameauth@IdxPageref[3] {% % \end{macrocode} % Warn if \cmd{\SkipIndex} was called before \cmd{\ShowIdxPageref}, % and reset it. % % \begin{macrocode} \if@nameauth@SkipIndex \PackageWarning{nameauth} {\string\SkipIndex precedes \string\ShowIdxPageref; check}% \unless\if@nameauth@OldReset \@nameauth@SkipIndexfalse% \fi \fi % \end{macrocode} % Start a local scope to isolate any changes and redefine % \cmd{\NameauthIndex} (the index macro hook) to print % an entry in the text. % % \begin{macrocode} \begingroup% \def\NameauthIndex##1{##1}% \@nameauth@DoIndextrue% % \end{macrocode} % We locally delete any tag and xref control sequences as needed. % They will be restored when the scope ends. If \cmd{\ShowIdxPageref} % set \cmd{\@nameauth@LongIdxDebugtrue} we produce a full index entry % that shows all the tags and the ``actual'' character as well as the % name. Otherwise we produce a short index entry that shows only the name. % % \begin{macrocode} \@nameauth@Choice{}{}{}% \csundef{\NameauthPattern!PN}% \unless\if@nameauth@LongIdxDebug \csundef{\NameauthPattern!PRE}% \csundef{\NameauthPattern!TAG}% \fi \IndexName[#1]{#2}[#3]% % \end{macrocode} % We close the scope and reset the flags. % % \begin{macrocode} \endgroup% \global\@nameauth@LongIdxDebugfalse% } % \end{macrocode} % \end{macro} % % \subsubsection{Core Name Engine} % % \subsubsection*{\hfil Argument Processing Layer} % % \begin{macro}{\@nameauth@Name} % \changes{1.5}{2013/02/22}{Reversing/caps} % \changes{2.0}{2015/11/11}{Trim spaces; fix tags} % \changes{2.1}{2015/11/24}{Fix Unicode} % \changes{2.3}{2016/01/05}{Now internal} % \changes{2.4}{2016/03/15}{Set token regs} % \changes{2.41}{2016/03/17}{Fix token regs} % \changes{2.5}{2016/04/06}{Fix old syntax} % \changes{2.6}{2016/09/19}{Better indexing} % \changes{3.0}{2016/10/26}{Redesigned} % \changes{3.1}{2017/01/13}{New workflow} % \changes{3.3}{2020/02/20}{global flag reset} % \Name*[Marc van]{Dongen} provided the original basic structure. % Parsing, indexing, and formatting are more modularized than % in earlier versions. % % \begin{macrocode} \newcommandx*\@nameauth@Name[3][1=\@empty, 3=\@empty] {% % \end{macrocode} % Both \cmd{\@nameauth@Name} and \cmd{\AKA} engage the lock below, % preventing a stack overflow. Tell the formatting mechanism that % it is being called from % \cmd{\@nameauth@Name}. % % \begin{macrocode} \if@nameauth@BigLock \@nameauth@Locktrue\fi \unless\if@nameauth@Lock \@nameauth@Locktrue% \@nameauth@InNametrue% % \end{macrocode} % Test for malformed input. % % \begin{macrocode} \@nameauth@Error{#2}{macro \string\@nameauth@name}% % \end{macrocode} % If we use \cmd{\JustIndex} then skip everything else. % The \texttt{oldpass} option restores what we did before % version 3.3, where we locally reset \cmd{\@nameauth@JustIndexfalse} % and were done. Now, however, the default is a global reset to avoid % undocumented behavior. % % \begin{macrocode} \if@nameauth@JustIndex \IndexName[#1]{#2}[#3]% \if@nameauth@OldPass \@nameauth@JustIndexfalse% \else \if@nameauth@OldReset \@nameauth@FullNamefalse% \@nameauth@FirstNamefalse% \@nameauth@JustIndexfalse% \else \global\@nameauth@FullNamefalse% \global\@nameauth@FirstNamefalse% \global\@nameauth@JustIndexfalse% \fi \fi \else % \end{macrocode} % Create or delete name pattern if directed. Deletion has priority % because it occurs after creation. Ensure that names are printed % in horizontal mode. Wrap the name with two index entries in case % a page break occurs between them. % % \begin{macrocode} \if@nameauth@Subvert \SubvertName[#1]{#2}[#3]\fi \if@nameauth@Forget \ForgetName[#1]{#2}[#3]\fi \leavevmode\hbox{}% \unless\if@nameauth@SkipIndex \IndexName[#1]{#2}[#3]\fi \if@nameauth@MainFormat \@nameauth@Parse{#1}{#2}{#3}{!MN}% \else \@nameauth@Parse{#1}{#2}{#3}{!NF}% \fi \unless\if@nameauth@SkipIndex \IndexName[#1]{#2}[#3]\fi % \end{macrocode} % Reset all the ``per name'' Boolean values after printing a name. % The default is global. % % \begin{macrocode} \@nameauth@Flags% \fi \@nameauth@Lockfalse% \@nameauth@InNamefalse% % \end{macrocode} % Close the ``locked'' branch and complete the full stop detection % and removal. % % \begin{macrocode} \fi \if@nameauth@Punct\expandafter\@nameauth@CheckDot\fi } % \end{macrocode} % \end{macro} % % \subsubsection*{\hfil Syntactic Element Layer} % % \begin{macro}{\@nameauth@Parse} % \changes{3.0}{2016/10/26}{Added} % \changes{3.1}{2017/01/13}{New workflow, caps} % \changes{3.2}{2017/03/22}{Fix alt. format, affixes, % use \cmd{\MakeUppercase}} % \changes{3.5}{2020/11/23}{Global token regs, optimize logic, % fix namespace} % Parse and print a name in the text. The final required argument tells % us which naming system we are in (Section~\ref{sec:NamePatterns}). % Both \cmd{\@nameauth@Name} and \cmd{\AKA} call this parser, which only % works in a locked state. % % \begin{macrocode} \newcommand\@nameauth@Parse[4] {% \if@nameauth@BigLock \@nameauth@Lockfalse\fi \if@nameauth@Lock % \end{macrocode} % Make token register copies of the current name args % to be available for the hook macros. % % \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. % % \begin{macrocode} \if@nameauth@AllCaps \@nameauth@AllThistrue\fi \if@nameauth@RevAll \@nameauth@RevThistrue\fi \if@nameauth@RevAllComma \@nameauth@RevThisCommatrue\fi % \end{macrocode} % Now we enter a local scope where we can use simple control % strings without needing to worry about collisions. We process % and load the arguments into the appropriate macros. % % \begin{macrocode} \begingroup% \def\@nameauth@InParser{}% \@nameauth@LoadArgs{#1}{#2}{#3}% % \end{macrocode} % Copy the protected control sequences to local, % unprotected ones. % % \begin{macrocode} \let\arga\@nameauth@A% \let\rootb\@nameauth@B% \let\suffb\@nameauth@SB% \let\argc\@nameauth@C% % \end{macrocode} % Capitalization on demand in the body text % if not in alternate formatting. % % \begin{macrocode} \if@nameauth@DoCaps \@nameauth@CapArgs{#1}{#2}{#3}% \fi % \end{macrocode} % We capitalize the entire surname when desired; % different from above and overrides it. % % \begin{macrocode} \if@nameauth@AllThis \protected@edef\rootb% {\MakeUppercase{\@nameauth@Root{#2}}}% \fi % \end{macrocode} % Use non-breaking spaces and commas as desired. % % \begin{macrocode} \@nameauth@AddPunct% % \end{macrocode} % We parse names by attaching ``meaning'' to patterns % of macro arguments primarily via \cmd{\FNN} and \cmd{\SNN}. % Then we call the name printing macros, based on optional arguments. % % \begin{macrocode} \let\SNN\rootb% \@nameauth@Choice % \end{macrocode} % Non-Western names, current syntax. % We test \cmd{\argc} and \cmd{\suffb} as needed. % % \begin{macrocode} {% \ifx\argc\@empty \let\FNN\suffb% \else \let\FNN\argc% \fi \@nameauth@NonWest{\@nameauth@csb#4}% \@nameauth@MakeCS{\@nameauth@csb#4}% }% % \end{macrocode} % Non-Western names, obsolete syntax. Here \cmd{\argc} is significant. % % \begin{macrocode} {% \let\FNN\argc% \@nameauth@NonWest{\@nameauth@csbc#4}% \@nameauth@MakeCS{\@nameauth@csbc#4}% }% % \end{macrocode} % Western names. % We test for \cmd{\argc} and swap it for \cmd{\arga} and % account for \cmd{\suffb}. % % \begin{macrocode} {% \ifx\argc\@empty \let\FNN\arga% \else \let\FNN\argc% \fi \unless\ifx\suffb\@empty \def\SNN{\rootb\Space\suffb}% \if@nameauth@ShortSNN \let\SNN\rootb% \fi \fi \@nameauth@West{\@nameauth@csab#4}% \@nameauth@MakeCS{\@nameauth@csab#4}% }% % \end{macrocode} % We end the local group and reset the flags for name forms here. % % \begin{macrocode} \endgroup% \if@nameauth@OldReset \@nameauth@FullNamefalse% \@nameauth@FirstNamefalse% \@nameauth@FirstFormatfalse% \else \global\@nameauth@FullNamefalse% \global\@nameauth@FirstNamefalse% \global\@nameauth@FirstFormatfalse% \fi \fi } % \end{macrocode} % \end{macro} % % \subsubsection*{\hfil Name Display Layer} % % \begin{macro}{\@nameauth@NonWest} % \changes{3.0}{2016/10/26}{Added} % \changes{3.02}{2016/11/01}{Restrict \cmd{\ForceFN}} % \changes{3.3}{2020/02/20}{global flag reset} % Arrange forms of non-Western names. We inherit macros from % the parser and only use this macro in the local scope of the parser. % % \begin{macrocode} \newcommand*\@nameauth@NonWest[1] {% \ifdefined\@nameauth@InParser \@nameauth@Form{#1}% \ifx\FNN\@empty \@nameauth@Hook{\SNN}% \else \if@nameauth@FullName \if@nameauth@RevThis \@nameauth@Hook{\FNN\Space\SNN}% \else \@nameauth@Hook{\SNN\Space\FNN}% \fi \else \if@nameauth@FirstName \if@nameauth@EastFN \@nameauth@Hook{\FNN}% \else \@nameauth@Hook{\SNN}% \fi \else \@nameauth@Hook{\SNN}% \fi \fi \fi \fi } % \end{macrocode} % \end{macro} % % \begin{macro}{\@nameauth@West} % \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} % Arrange forms of Western names and ``non-native'' Eastern names. % We inherit macros from the parser and only use this macro in the % local scope of the parser. % % \begin{macrocode} \newcommand*\@nameauth@West[1] {% \ifdefined\@nameauth@InParser \@nameauth@Form{#1}% \edef\RevSpace{,\SpaceW}% \if@nameauth@FullName \if@nameauth@RevThis \@nameauth@Hook{\SNN\SpaceW\FNN}% \else \if@nameauth@RevThisComma \@nameauth@Hook{\SNN\RevSpace\FNN}% \else \@nameauth@Hook{\FNN\SpaceW\SNN}% \fi \fi \else \if@nameauth@FirstName \@nameauth@Hook{\FNN}% \else \@nameauth@Hook{\rootb}% \fi \fi \fi } % \end{macrocode} % \end{macro} % % \begin{macro}{\@nameauth@Form} % \changes{3.5}{2020/11/23}{Added} % Set up the flags per the formatting rules for first, subsequent, long, % and short uses. We only use this macro in the local scope of the parser. % % \begin{macrocode} \newcommand*\@nameauth@Form[1] {% \ifdefined\@nameauth@InParser % \end{macrocode} % If the name does not exist yet or if the \texttt{alwaysformat} option % is used, force first-use formatting, force a long name, % and inhibit a short name. % % \begin{macrocode} \unless\ifcsname#1\endcsname \@nameauth@FirstFormattrue% \@nameauth@FullNametrue% \@nameauth@FirstNamefalse% \else \if@nameauth@AlwaysFormat\@nameauth@FirstFormattrue\fi \fi % \end{macrocode} % If we are not in \cmd{\AKA}, if a short name form is desired, % inhibit a long form. % % \begin{macrocode} \unless\if@nameauth@InAKA \if@nameauth@FirstName\@nameauth@FullNamefalse\fi \else % \end{macrocode} % If we are in \cmd{\AKA} use special formatting rules. \cmd{\AKA*} % acts like \cmd{\FName}, while \cmd{\AKA} acts like \cmd{\Name*}. % Both prefer using the subsequent-use hooks unless the \texttt{formatAKA} % option or the \texttt{alwaysformat} option are used. % % \begin{macrocode} \if@nameauth@AltAKA \if@nameauth@OldAKA\@nameauth@EastFNtrue\fi \@nameauth@FullNamefalse% \@nameauth@FirstNametrue% \else \@nameauth@FullNametrue% \@nameauth@FirstNamefalse% \fi \unless\if@nameauth@AlwaysFormat \unless\if@nameauth@AKAFormat \@nameauth@FirstFormatfalse% \fi \fi \fi \fi } % \end{macrocode} % \end{macro} % % \subsubsection*{\hfil Format Hook Dispatcher} % % \begin{macro}{\@nameauth@Hook} % \changes{2.4}{2016/03/15}{Current form} % \changes{2.5}{2016/04/06}{Improve hooks} % \changes{3.0}{2016/10/26}{Fix punct. detection} % \changes{3.5}{2020/11/23} {Fix namespace} % Boolean flags control which hook is called (first/subsequent use, % name type). We only use this macro in the local scope of the parser. % % \begin{macrocode} \newcommand*\@nameauth@Hook[1] {% \ifdefined\@nameauth@InParser % \end{macrocode} % We tell the formatting hooks that they are in the hook dispatcher % to enable alternate formatting. We test the printed name form to see % if it has a trailing full stop. The flag \texttt{\textbackslash^^A % if@nameauth@InHook} will reset outside of the local scope in % \cmd{\@nameauth@Parse}. % \begin{macrocode} \@nameauth@InHooktrue% \protected@edef\test{#1}% \expandafter\@nameauth@TestDot\expandafter{\test}% \if@nameauth@MainFormat % \end{macrocode} % We use the formatting hooks for the main-matter system. % % \begin{macrocode} \if@nameauth@FirstFormat \bgroup\NamesFormat{#1}\egroup% \else \bgroup\MainNameHook{#1}\egroup% \fi \else % \end{macrocode} % We use the formatting hooks for the front-matter system. % % \begin{macrocode} \if@nameauth@FirstFormat \bgroup\FrontNamesFormat{#1}\egroup% \else \bgroup\FrontNameHook{#1}\egroup% \fi \fi \fi } % \end{macrocode} % \end{macro} % % \subsubsection{Indexing} % % \begin{macro}{\@nameauth@Index} % \changes{0.94}{2012/02/15}{Added} % \changes{2.0}{2015/11/11}{New tagging} % \changes{3.3}{2020/02/20}{Support hyperref} % \changes{3.5}{2020/11/23}{Fix namespace} % This is the core index mechanism. If the indexing flag is true, % create an index entry, otherwise do nothing. Add any tags % automatically if they exist. % % \begin{macrocode} \newcommand*\@nameauth@Index[2] {% \if@nameauth@DoIndex % \end{macrocode} % If an index tag exists for the entry, get it. Also create % a short version of the tag without any vertical bar or trailing macro. % If we are creating a cross-reference, use the short tag, otherwise % use the long tag. % % \begin{macrocode} \ifcsname#1!TAG\endcsname \protected@edef\@nameauth@Tag{\csname#1!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. % % \begin{macrocode} \ifcsname#1!PRE\endcsname \protected@edef\@nameauth@Pre{\csname#1!PRE\endcsname}% \if@nameauth@Xref \protected@edef\@nameauth@IdxEntry {\@nameauth@Pre#2\@nameauth@ShortTag}% \else \protected@edef\@nameauth@IdxEntry {\@nameauth@Pre#2\@nameauth@Tag}% \fi \else % \end{macrocode} % Create entries with just an info tag. % % \begin{macrocode} \if@nameauth@Xref \protected@edef\@nameauth@IdxEntry {#2\@nameauth@ShortTag}% \else \protected@edef\@nameauth@IdxEntry {#2\@nameauth@Tag}% \fi \fi \else % \end{macrocode} % Create entries with just a sorting tag. % % \begin{macrocode} \ifcsname#1!PRE\endcsname \protected@edef\@nameauth@Pre{\csname#1!PRE\endcsname}% \protected@edef\@nameauth@IdxEntry{\@nameauth@Pre#2}% \else \protected@edef\@nameauth@IdxEntry{#2}% \fi \fi % \end{macrocode} % Create entries with no tag. % % \begin{macrocode} \expandafter\NameauthIndex\expandafter{\@nameauth@IdxEntry}% \fi } % \end{macrocode} % \end{macro} % % \newpage % % \subsection[User Macros: Prefixes]{For Users: Prefix Macros} % \label{sec:PrefixMacs} % % All prefix macros are meant to precede a particular name and only % affect a particular name. % % \subsubsection[Syntax]{Name Syntax} % % \subsubsection*{\hfil Commas Before Affixes} % % \begin{macro}{\ShowComma} % \changes{1.4}{2012/07/24}{Added} % Put comma between name and suffix one time. % % \begin{macrocode} \newcommand*\ShowComma{\@nameauth@ShowCommatrue} % \end{macrocode} % \end{macro} % % \begin{macro}{\NoComma} % \changes{2.6}{2016/09/19}{Added} % Remove comma between name and suffix one time % (with \texttt{comma} option). % % \begin{macrocode} \newcommand*\NoComma{\@nameauth@NoCommatrue} % \end{macrocode} % \end{macro} % % \subsubsection*{\hfil Capitalization} % % \begin{macro}{\CapThis} % \changes{0.94}{2012/02/15}{Added} % Tells the root capping macro to cap the first character % of all name elements. % % \begin{macrocode} \newcommand*\CapThis{\@nameauth@DoCapstrue} % \end{macrocode} % \end{macro} % % \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. % % \begin{macrocode} \newcommand*\AccentCapThis {\@nameauth@Accenttrue\@nameauth@DoCapstrue} % \end{macrocode} % \end{macro} % % \begin{macro}{\CapName} % \changes{1.5}{2013/02/22}{Added} % Capitalize entire \meta{SNN}. Overrides \cmd{\CapThis} for surnames. % % \begin{macrocode} \newcommand*\CapName{\@nameauth@AllThistrue} % \end{macrocode} % \end{macro} % % \subsubsection*{\hfil Reversing} % % \begin{macro}{\RevName} % \changes{1.5}{2013/02/22}{Added} % Reverse name order. % % \begin{macrocode} \newcommand*\RevName{\@nameauth@RevThistrue} % \end{macrocode} % \end{macro} % % \begin{macro}{\ForceFN} % \changes{3.0}{2016/10/26}{Added} % Force the printing of an Eastern forename or ancient affix % in the text, but only when using the ``short name'' macro % \cmd{\FName} and the \cmd{\S}\meta{macro}. % % \begin{macrocode} \newcommand*\ForceFN{\@nameauth@EastFNtrue} % \end{macrocode} % \end{macro} % % \subsubsection*{\hfil Reversing with Commas} % % \begin{macro}{\RevComma} % \changes{1.5}{2013/02/22}{Added} % Last name, comma, first name. % % \begin{macrocode} \newcommand*\RevComma{\@nameauth@RevThisCommatrue} % \end{macrocode} % \end{macro} % % \subsubsection*{\hfil Affixes and Breaking} % % \begin{macro}{\DropAffix} % \changes{3.0}{2016/10/26}{Added} % Suppress the affix in a long Western name. % % \begin{macrocode} \newcommand*\DropAffix{\@nameauth@ShortSNNtrue} % \end{macrocode} % \end{macro} % % \begin{macro}{\KeepAffix} % \changes{1.9}{2015/07/09}{Added} % Trigger a name-suffix pair to be separated by % a non-breaking space. % % \begin{macrocode} \newcommand*\KeepAffix{\@nameauth@NBSPtrue} % \end{macrocode} % \end{macro} % % \begin{macro}{\KeepName} % \changes{3.1}{2017/01/13}{Added} % Use non-breaking spaces between name syntactic forms. % % \begin{macrocode} \newcommand*\KeepName {\@nameauth@NBSPtrue\@nameauth@NBSPXtrue} % \end{macrocode} % \end{macro} % % \subsubsection{Indexing} % % \begin{macro}{\SkipIndex} % \changes{3.1}{2017/01/13}{Added} % Turn off the next instance of indexing in \cmd{\Name}, % \cmd{\FName}, and starred forms. % % \begin{macrocode} \newcommand*\SkipIndex{\@nameauth@SkipIndextrue} % \end{macrocode} % \end{macro} % % \begin{macro}{\JustIndex} % \changes{3.1}{2017/01/13}{Added} % Makes the next call to \cmd{\Name}, \cmd{\FName}, % and starred forms act like \cmd{\IndexName}. % Overrides \cmd{\SkipIndex}. % % \begin{macrocode} \newcommand*\JustIndex{\@nameauth@JustIndextrue} % \end{macrocode} % \end{macro} % % \begin{macro}{\SeeAlso} % \changes{3.0}{2016/10/26}{Added} % Change the type of cross-reference from a \textit{see} % reference to a \textit{see also} reference. Works once % per xref, unless one uses \cmd{\Include*}. % % \begin{macrocode} \newcommand*\SeeAlso{\@nameauth@SeeAlsotrue} % \end{macrocode} % \end{macro} % % \subsubsection[Format/Decisions]{Formatting and Name Decisions} % % \begin{macro}{\ForceName} % \changes{3.1}{2017/01/13}{Added} % Set \cmd{\@nameauth@FirstFormat} to be true even for % subsequent name uses. Makes the core name engine use % \cmd{\NamesFormat}. Works for one name only. % % \begin{macrocode} \newcommand*\ForceName{\@nameauth@FirstFormattrue} % \end{macrocode} % \end{macro} % % \begin{macro}{\ForgetThis} % \changes{3.1}{2017/01/13}{Added} % Have the naming engine \cmd{\@nameauth@Name} % call \cmd{\ForgetName} internally. % % \begin{macrocode} \newcommand*\ForgetThis{\@nameauth@Forgettrue} % \end{macrocode} % \end{macro} % % \begin{macro}{\SubvertThis} % \changes{3.1}{2017/01/13}{Added} % Have the naming engine \cmd{\@nameauth@Name} % call \cmd{\SubvertName} internally. % % \begin{macrocode} \newcommand*\SubvertThis{\@nameauth@Subverttrue} % \end{macrocode} % \end{macro} % % \subsection[User Macros: Helpers]{For Users: Helper Macros} % \label{sec:Helpers} % % Helper macros do not need to precede a particular name and their effects % endure for multiple names. They tend to affect an entire scope. That is % why they usually come in pairs. % % \subsubsection[Syntax]{Name Syntax} % % \subsubsection*{\hfil Capitalization} % % \begin{macro}{\AllCapsInactive} % Turn off global surname capitalization. % \changes{1.5}{2013/02/22}{Added} % % \begin{macrocode} \newcommand*\AllCapsInactive{\@nameauth@AllCapsfalse} % \end{macrocode} % \end{macro} % % \begin{macro}{\AllCapsActive} % \changes{1.5}{2013/02/22}{Added} % Turn on global surname capitalization. % Activates \cmd{\CapName} for every name. % % \begin{macrocode} \newcommand*\AllCapsActive{\@nameauth@AllCapstrue} % \end{macrocode} % \end{macro} % % \subsubsection*{\hfil Reversing} % % \begin{macro}{\ReverseInactive} % Turn off global name reversing. % \changes{1.5}{2013/02/22}{Added} % % \begin{macrocode} \newcommand*\ReverseInactive{\@nameauth@RevAllfalse} % \end{macrocode} % \end{macro} % % \begin{macro}{\ReverseActive} % \changes{1.5}{2013/02/22}{Added} % Turn on global name reversing. % Activates \cmd{\RevName} for every name. % % \begin{macrocode} \newcommand*\ReverseActive{\@nameauth@RevAlltrue} % \end{macrocode} % \end{macro} % % \subsubsection*{\hfil Reversing with Commas} % % \begin{macro}{\ReverseCommaInactive} % \changes{1.5}{2013/02/22}{Added} % Turn off global ``last-name-comma-first''. % % \begin{macrocode} \newcommand*\ReverseCommaInactive{\@nameauth@RevAllCommafalse} % \end{macrocode} % \end{macro} % % \begin{macro}{\ReverseCommaActive} % \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. % % \begin{macrocode} \newcommand*\ReverseCommaActive{\@nameauth@RevAllCommatrue} % \end{macrocode} % \end{macro} % % \subsubsection{Indexing} % % \begin{macro}{\IndexActual} % \changes{2.0}{2015/11/11}{Added} % \changes{3.5}{2020/11/23}{Use \cmd{\def}} % Change the ``actual'' character from the default. % This allows one to use, for example, % |\global\IndexActual{=}| in \texttt{dtx} files. % % \begin{macrocode} \newcommand*\IndexActual[1]{\def\@nameauth@Actual{#1}} % \end{macrocode} % \end{macro} % % \begin{macro}{\IndexInactive} % \changes{0.94}{2012/02/15}{Added} % Turn off global indexing of names. % % \begin{macrocode} \newcommand*\IndexInactive{\@nameauth@DoIndexfalse} % \end{macrocode} % \end{macro} % % \begin{macro}{\IndexActive} % \changes{0.94}{2012/02/15}{Added} % Turn on global indexing of names. % % \begin{macrocode} \newcommand*\IndexActive{\@nameauth@DoIndextrue} % \end{macrocode} % \end{macro} % % \begin{macro}{\IndexWarnVerbose} % \changes{3.7}{2023/02/03}{Added} % Turn on verbose warnings for indexing. % % \begin{macrocode} \newcommand*\IndexWarnVerbose{\@nameauth@Verbosetrue} % \end{macrocode} % \end{macro} % % \begin{macro}{\IndexWarnTerse} % \changes{3.7}{2023/02/03}{Added} % Turn off verbose warnings for indexing. % % \begin{macrocode} \newcommand*\IndexWarnTerse{\@nameauth@Verbosefalse} % \end{macrocode} % \end{macro} % % \begin{macro}{\IndexProtect} % \changes{3.3}{2020/02/20}{Added} % We shut down all output from the naming and indexing macros % to protect against problems in the index in case a macro in the % index contains one of the naming macros. This macro is deliberately % local, so one can use scoping to isolate its effects. % % \begin{macrocode} \newcommand*\IndexProtect {\@nameauth@DoIndexfalse\@nameauth@BigLocktrue} % \end{macrocode} % \end{macro} % % \subsubsection{Formatting} % % \begin{macro}{\NamesInactive} % Switch to the front-matter name system. % % \begin{macrocode} \newcommand*\NamesInactive{\@nameauth@MainFormatfalse} % \end{macrocode} % \end{macro} % % \begin{macro}{\NamesActive} % Switch to the main-matter name system. % % \begin{macrocode} \newcommand*\NamesActive{\@nameauth@MainFormattrue} % \end{macrocode} % \end{macro} % % \subsubsection{Alternate Formatting} % % \begin{macro}{\AltFormatActive} % \changes{3.1}{2017/01/13}{Added} % Turn on alternate formatting, engage the formatting macros. % % \begin{macrocode} \newcommand*\AltFormatActive {% \global\@nameauth@AltFormattrue% \global\@nameauth@DoAlttrue% } % \end{macrocode} % \end{macro} % % \begin{macro}{\AltFormatActive*} % \changes{3.1}{2017/01/13}{Added} % Turn on alternate formatting, disengage the formatting macros. % % \begin{macrocode} \WithSuffix{\newcommand*}\AltFormatActive* {% \global\@nameauth@AltFormattrue% \global\@nameauth@DoAltfalse% } % \end{macrocode} % \end{macro} % % \begin{macro}{\AltFormatInactive} % Turn off alternate formatting altogether. % \changes{3.1}{2017/01/13}{Added} % % \begin{macrocode} \newcommand*\AltFormatInactive {\global\@nameauth@AltFormatfalse\global\@nameauth@DoAltfalse} % \end{macrocode} % \end{macro} % % \begin{macro}{\AltOn} % Locally turn on alternate formatting. % \changes{3.1}{2017/01/13}{Added} % % \begin{macrocode} \newcommand*\AltOn {% \if@nameauth@InHook \if@nameauth@AltFormat\@nameauth@DoAlttrue\fi \fi } % \end{macrocode} % \end{macro} % % \begin{macro}{\AltOff} % Locally turn off alternate formatting. % \changes{3.1}{2017/01/13}{Added} % % \begin{macrocode} \newcommand*\AltOff {% \if@nameauth@InHook \if@nameauth@AltFormat\@nameauth@DoAltfalse\fi \fi } % \end{macrocode} % \end{macro} % % \begin{macro}{\AltCaps} % \changes{3.1}{2017/01/13}{Added} % \changes{3.2}{2017/03/22}{Use \cmd{\MakeUppercase}} % Alternate discretionary capping macro triggered by \cmd{\CapThis}. % % \begin{macrocode} \newcommand*\AltCaps[1] {% \if@nameauth@InHook \if@nameauth@DoCaps\MakeUppercase{#1}\else#1\fi \else #1% \fi } % \end{macrocode} % \end{macro} % % \begin{macro}{\textSC} % \changes{3.1}{2017/01/13}{Added} % Alternate formatting macro: small caps when active. % % \begin{macrocode} \newcommand*\textSC[1] {\if@nameauth@DoAlt\textsc{#1}\else#1\fi} % \end{macrocode} % \end{macro} % % \begin{macro}{\textUC} % \changes{3.1}{2017/01/13}{Added} % \changes{3.2}{2017/03/22}{Use \cmd{\MakeUppercase}} % Alternate formatting macro: uppercase when active. % % \begin{macrocode} \newcommand*\textUC[1] {\if@nameauth@DoAlt\MakeUppercase{#1}\else#1\fi} % \end{macrocode} % \end{macro} % % \begin{macro}{\textIT} % \changes{3.1}{2017/01/13}{Added} % Alternate formatting macro: italic when active. % % \begin{macrocode} \newcommand*\textIT[1] {\if@nameauth@DoAlt\textit{#1}\else#1\fi} % \end{macrocode} % \end{macro} % % \begin{macro}{\textBF} % \changes{3.1}{2017/01/13}{Added} % Alternate formatting macro: boldface when active. % % \begin{macrocode} \newcommand*\textBF[1] {\if@nameauth@DoAlt\textbf{#1}\else#1\fi} % \end{macrocode} % \end{macro} % % \subsubsection{Name Decisions} % % \begin{macro}{\LocalNameTest} % \changes{3.5}{2020/11/23}{Added} % Causes decision paths in the name decision macros to be in a local scope. % % \begin{macrocode} \newcommand*\LocalNameTest{\global\@nameauth@GlobalScopefalse} % \end{macrocode} % \end{macro} % % \begin{macro}{\GlobalNameTest} % \changes{3.5}{2020/11/23}{Added} % Causes decision paths in the name decision macros to have no scoping. % % \begin{macrocode} \newcommand*\GlobalNameTest{\global\@nameauth@GlobalScopetrue} % \end{macrocode} % \end{macro} % % \begin{macro}{\LocalNames} % \changes{2.3}{2016/01/05}{Added} % \changes{2.4}{2016/03/15}{Ensure global} % \cmd{\LocalNames} sets |@nameauth@LocalNames| true so \cmd{\ForgetName} % and \cmd{\SubvertName} do not affect both main and front matter % name systems at once, only the current one. % % \begin{macrocode} \newcommand*\LocalNames{\global\@nameauth@LocalNamestrue} % \end{macrocode} % \end{macro} % % \begin{macro}{\GlobalNames} % \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. % % \begin{macrocode} \newcommand*\GlobalNames{\global\@nameauth@LocalNamesfalse} % \end{macrocode} % \end{macro} % % \subsubsection[Name Parser]{User-Accessible Name Parser} % \label{sec:NameParser} % % \begin{macro}{\NameParser} % \changes{3.0}{2016/10/26}{Added} % \changes{3.03}{2016/11/01}{Restrict first names} % \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} % Print a name form based on the current state of the % \textsf{nameauth} flags in the locked path. Used only % in the hook macros, within the local scope of \cmd{\@nameauth@Parse}. % % \begin{macrocode} \newcommand*\NameParser {% \if@nameauth@InHook \let\SNN\rootb% \@nameauth@Choice % \end{macrocode} % Non-Western names. % We test both \cmd{\argc} and \cmd{\suffb} as needed. % % \begin{macrocode} {% \ifx\argc\@empty \let\FNN\suffb \else \let\FNN\argc \fi \ifx\FNN\@empty \SNN% \else \if@nameauth@FullName \if@nameauth@RevThis \FNN\Space\SNN \else \SNN\Space\FNN% \fi \else \if@nameauth@FirstName \if@nameauth@EastFN \FNN \else \SNN \fi \else \SNN% \fi \fi \fi }% % \end{macrocode} % Non-Western names, obsolete syntax. % Using \cmd{\argc} in this path affects indexing. % % \begin{macrocode} {% \let\FNN\argc% \if@nameauth@FullName% \if@nameauth@RevThis \FNN\Space\SNN \else \SNN\Space\FNN \fi \else \if@nameauth@FirstName \if@nameauth@EastFN \FNN \else \SNN \fi \else \SNN% \fi \fi }% % \end{macrocode} % Western names. % We test for \cmd{\argc} and swap it for \cmd{\arga}, % and account for \cmd{\suffb}. % % \begin{macrocode} {% \ifx\argc\@empty \let\FNN\arga \else \let\FNN\argc \fi \unless\ifx\suffb\@empty \def\SNN{\rootb\Space\suffb}% \if@nameauth@ShortSNN \let\SNN\rootb \fi \fi \if@nameauth@FullName \if@nameauth@RevThis \SNN\SpaceW\FNN% \else \if@nameauth@RevThisComma \SNN\RevSpace\FNN% \else \FNN\SpaceW\SNN% \fi \fi \else \if@nameauth@FirstName \FNN \else \let\SNN\rootb \SNN \fi \fi }% \fi } % \end{macrocode} % \end{macro} % % \subsection[User Macros: Name Args]{For Users: Macros That Take Name Arguments} % \label{sec:UserInterface} % % The rest of the \textsf{nameauth} macros all take name arguments. They all % update \cmd{\NameauthPattern}, \texttt{\textbackslash ifNameauthWestern}, % and \texttt{\textbackslash ifNameauthObsolete} when called. The file % \texttt{examples.tex} iterates through all possible argument variations of % these macros except the debugging macros, the non-printing arguments of % \cmd{\AKA}, and \cmd{\PName}. It thus tests for spurious spaces and any % possible bad output. % % \subsubsection{Basic Interface} % % \begin{macro}{\Name} % \cmd{\Name} calls \cmd{\NameauthName}, the interface hook. % % \begin{macrocode} \newcommand\Name{\NameauthName} % \end{macrocode} % \end{macro} % % \begin{macro}{\Name*} % \cmd{\Name*} sets up a long name reference and calls \cmd{\NameauthLName}, % the interface hook. % % \begin{macrocode} \WithSuffix{\newcommand*}\Name* {\@nameauth@FullNametrue\NameauthLName} % \end{macrocode} % \end{macro} % % \begin{macro}{\FName} % \changes{0.9}{2012/02/10}{Added} % \cmd{\FName} sets up a short name reference and calls \cmd{\NameauthFName}, % the interface hook. % % \begin{macrocode} \newcommand\FName {\@nameauth@FirstNametrue\NameauthFName} % \end{macrocode} % \end{macro} % % \begin{macro}{\FName*} % \cmd{\FName} and \cmd{\FName*} are identical in function. % % \begin{macrocode} \WithSuffix{\newcommand*}\FName*{\FName} % \end{macrocode} % \end{macro} % % \subsubsection{Quick Interface} % % \begin{environment}{nameauth} % \changes{1.6}{2013/03/10}{Environment added} % \changes{2.0}{2015/11/11}{Better arg handling} % \changes{2.41}{2016/03/17}{No local \cmd{\newtoks}} % \changes{3.5}{2020/11/23}{Fix namespace} % \changes{3.7}{2023/02/03}{Improve warnings} % Here we create macro shorthands. First we define a macro \cmd{\<} that % takes four arguments, delimited by three ampersands and \texttt{>}. % This macro is local to the \texttt{nameauth} environment, % but the shorthand macros that it creates are global. % % \begin{macrocode} \newenvironment{nameauth} {% \begingroup% \let\ex\expandafter% \csdef{<}##1&##2&##3&##4>{% \protected@edef\@arga@{\trim@spaces{##1}}% \protected@edef\@larga@{L\trim@spaces{##1}}% \protected@edef\@sarga@{S\trim@spaces{##1}}% \protected@edef\@testb@{\trim@spaces{##2}}% \protected@edef\@testd@{\trim@spaces{##4}}% \@nameauth@etoksb\ex{##2}% \@nameauth@etoksc\ex{##3}% \@nameauth@etoksd\ex{##4}% % \end{macrocode} % The first argument must have some text to create a set of control % sequences with it. The third argument is the required name argument. % Redefining a shorthand creates a warning. % % \begin{macrocode} \ifx\@arga@\@empty \PackageError{nameauth}% {environment nameauth: Macro name missing; \expandafter\detokenize\expandafter{##3}}% \fi \@nameauth@Error{##3}{macro: \ex\zap@space\string\ \@empty##1}% \ifcsname\@arga@\endcsname \PackageWarning{nameauth} {Environment nameauth: shorthand macro already exists}% \fi % \end{macrocode} % Set up shorthands according to name form. We use \cmd{\expandafter} % due to \cmd{\protected@edef} in the naming macros. We begin with % non-Western names that use the new syntax. We use one \cmd{\ex} per % token because we only have one argument to expand first. % % \begin{macrocode} \ifx\@testd@\@empty \ifx\@testb@\@empty \ex\csgdef\ex{\ex\@arga@\ex}% \ex{\ex\NameauthName\ex{\the\@nameauth@etoksc}}% \ex\csgdef\ex{\ex\@larga@\ex}% \ex{\ex\@nameauth@FullNametrue% \ex\NameauthLName\ex{\the\@nameauth@etoksc}}% \ex\csgdef\ex{\ex\@sarga@\ex}% \ex{\ex\@nameauth@FirstNametrue% \ex\NameauthFName\ex{\the\@nameauth@etoksc}}% \else % \end{macrocode} % Next we have Western names with no alternate names. % Here we have two arguments to expand in reverse order, % so we need three uses, then one use of \cmd{\ex} per token. % % \begin{macrocode} \ex\ex\ex\csgdef\ex\ex\ex{\ex\ex\ex\@arga@\ex\ex\ex}% \ex\ex\ex{\ex\ex\ex\NameauthName% \ex\ex\ex[\ex\the\ex\@nameauth@etoksb\ex]% \ex{\the\@nameauth@etoksc}}% \ex\ex\ex\csgdef\ex\ex\ex{\ex\ex\ex\@larga@\ex\ex\ex}% \ex\ex\ex{\ex\ex\ex\@nameauth@FullNametrue% \ex\ex\ex\NameauthLName% \ex\ex\ex[\ex\the\ex\@nameauth@etoksb\ex]% \ex{\the\@nameauth@etoksc}}% \ex\ex\ex\csgdef\ex\ex\ex{\ex\ex\ex\@sarga@\ex\ex\ex}% \ex\ex\ex{\ex\ex\ex\@nameauth@FirstNametrue% \ex\ex\ex\NameauthFName% \ex\ex\ex[\ex\the\ex\@nameauth@etoksb\ex]% \ex{\the\@nameauth@etoksc}}% \fi \else % \end{macrocode} % Below are ``native'' Eastern names with alternates and % the older syntax. We again have two arguments to expand first. % % \begin{macrocode} \ifx\@testb@\@empty \ex\ex\ex\csgdef\ex\ex\ex{\ex\ex\ex\@arga@\ex\ex\ex}% \ex\ex\ex{\ex\ex\ex\NameauthName% \ex\ex\ex{\ex\the\ex\@nameauth@etoksc\ex}% \ex[\the\@nameauth@etoksd]}% \ex\ex\ex\csgdef\ex\ex\ex{\ex\ex\ex\@larga@\ex\ex\ex}% \ex\ex\ex{\ex\ex\ex\@nameauth@FullNametrue% \ex\ex\ex\NameauthLName% \ex\ex\ex{\ex\the\ex\@nameauth@etoksc\ex}% \ex[\the\@nameauth@etoksd]}% \ex\ex\ex\csgdef\ex\ex\ex{\ex\ex\ex\@sarga@\ex\ex\ex}% \ex\ex\ex{\ex\ex\ex\@nameauth@FirstNametrue% \ex\ex\ex\NameauthFName% \ex\ex\ex{\ex\the\ex\@nameauth@etoksc\ex}% \ex[\the\@nameauth@etoksd]}% \else % \end{macrocode} % Here are Western names with alternates. We have three arguments % to expand, so we have seven uses, three uses, and one use of \cmd{\ex}. % % \begin{macrocode} \ex\ex\ex\ex\ex\ex\ex\csgdef\ex\ex\ex\ex\ex\ex\ex{% \ex\ex\ex\ex\ex\ex\ex\@arga@\ex\ex\ex\ex\ex\ex\ex}% \ex\ex\ex\ex\ex\ex\ex{\ex\ex\ex\ex\ex\ex\ex\NameauthName% \ex\ex\ex\ex\ex\ex\ex[\ex\ex\ex\the% \ex\ex\ex\@nameauth@etoksb\ex\ex\ex]% \ex\ex\ex{\ex\the\ex\@nameauth@etoksc\ex}% \ex[\the\@nameauth@etoksd]}% \ex\ex\ex\ex\ex\ex\ex\csgdef\ex\ex\ex\ex\ex\ex\ex{% \ex\ex\ex\ex\ex\ex\ex\@larga@\ex\ex\ex\ex\ex\ex\ex}% \ex\ex\ex\ex\ex\ex\ex{% \ex\ex\ex\ex\ex\ex\ex\@nameauth@FullNametrue% \ex\ex\ex\ex\ex\ex\ex\NameauthLName% \ex\ex\ex\ex\ex\ex\ex[\ex\ex\ex\the\ex\ex\ex% \@nameauth@etoksb\ex\ex\ex]% \ex\ex\ex{\ex\the\ex\@nameauth@etoksc\ex}% \ex[\the\@nameauth@etoksd]}% \ex\ex\ex\ex\ex\ex\ex\csgdef\ex\ex\ex\ex\ex\ex\ex{% \ex\ex\ex\ex\ex\ex\ex\@sarga@\ex\ex\ex\ex\ex\ex\ex}% \ex\ex\ex\ex\ex\ex\ex{% \ex\ex\ex\ex\ex\ex\ex\@nameauth@FirstNametrue% \ex\ex\ex\ex\ex\ex\ex\NameauthFName% \ex\ex\ex\ex\ex\ex\ex[\ex\ex\ex\the\ex\ex\ex% \@nameauth@etoksb\ex\ex\ex]% \ex\ex\ex{\ex\the\ex\@nameauth@etoksc\ex}% \ex[\the\@nameauth@etoksd]}% \fi \fi\ignorespaces% }\ignorespaces% } {\endgroup\ignorespaces} % \end{macrocode} % \end{environment} % % \subsubsection{Debugging Macros} % % \begin{macro}{\ShowPattern} % \changes{3.3}{2020/02/20}{Added} % \changes{3.7}{2023/02/03}{Redesigned} % This displays the pattern that the name arguments generate; % useful for debugging. We test for bad input, then load the argument % values into the appropriate macros. We determine the name type % and produce the output of the appropriate name control sequence. % % \begin{macrocode} \newcommandx*\ShowPattern[3][1=\@empty, 3=\@empty] {% \@nameauth@Error{#2}{macro: \string\ShowPattern}% \@nameauth@LoadArgs{#1}{#2}{#3}% \@nameauth@Choice{}{}{}\NameauthPattern% } % \end{macrocode} % \end{macro} % % \newpage % % \begin{macro}{\ShowIdxPageref} % \changes{3.3}{2020/02/20}{Added} % \changes{3.5}{2020/11/23}{Fix name space, use Boolean flags} % \changes{3.7}{2023/02/03}{Use common back-end} % This displays (expanded, as printed) the index entry that will be % generated, but not exactly what is in the \texttt{idx} file. % Test for bad input, load the argument values into % the appropriate macros, then call the back-end. % % \begin{macrocode} \newcommandx*\ShowIdxPageref[3][1=\@empty, 3=\@empty] {% \@nameauth@Error{#2}{macro: \string\ShowIdxPageref}% \@nameauth@LoadArgs{#1}{#2}{#3}% \global\@nameauth@LongIdxDebugtrue% \@nameauth@IdxPageref{#1}{#2}{#3}% } % \end{macrocode} % \end{macro} % % \begin{macro}{\ShowIdxPageref*} % \changes{3.3}{2020/02/20}{Added} % \changes{3.5}{2020/11/23}{Fix name space, use Boolean flags} % \changes{3.7}{2023/02/03}{Use common back-end} % Display a basic index entry with no tag. % Test for bad input, load the argument values into % the appropriate macros, then call the back-end. % % \begin{macrocode} \WithSuffix{\newcommandx*}\ShowIdxPageref*[3][1=\@empty, 3=\@empty] {% \@nameauth@Error{#2}{macro: \string\ShowIdxPageref*}% \@nameauth@LoadArgs{#1}{#2}{#3}% \@nameauth@IdxPageref{#1}{#2}{#3}% } % \end{macrocode} % \end{macro} % % \begin{macro}{\ShowNameInfo} % \changes{3.7}{2023/02/03}{Added} % Show how the name arguments are being interpreted by the % \textsf{nameauth} macros, but as detokenized text, % % \begin{macrocode} \newcommandx*\ShowNameInfo[3][1=\@empty, 3=\@empty] {% % \end{macrocode} % Test for bad input, then load the argument values into % the appropriate macros. % % \begin{macrocode} \@nameauth@Error{#2}{macro: \string\ShowNameInfo}% \@nameauth@LoadArgs{#1}{#2}{#3}% % \end{macrocode} % We produce what we know about the name arguments. % First is non-Western names using the current syntax. % % \begin{macrocode} \@nameauth@Choice {% (SNN: \expandafter\detokenize\expandafter{\@nameauth@B})% \unless\ifx\@nameauth@SB\@empty \ (Affix [FNN, other]: \expandafter\detokenize\expandafter{\@nameauth@SB})% \fi \unless\ifx\@nameauth@C\@empty \ (Alt: \expandafter\detokenize\expandafter{\@nameauth@C})% \fi }% % \end{macrocode} % Next is non-Western names using the obsolete syntax. % % \begin{macrocode} {% (SNN: \expandafter\detokenize\expandafter{\@nameauth@B})% \unless\ifx\@nameauth@C\@empty \ (Alt [FNN, other]: \expandafter\detokenize\expandafter{\@nameauth@C})% \fi }% % \end{macrocode} % % \newpage \noindent % Finally we have Western names. % % \begin{macrocode} {% (FNN: \expandafter\detokenize\expandafter{\@nameauth@A}) (SNN: \expandafter\detokenize\expandafter{\@nameauth@B})% \unless\ifx\@nameauth@SB\@empty \ (Affix: \expandafter\detokenize\expandafter{\@nameauth@SB})% \fi \unless\ifx\@nameauth@C\@empty \ (Alt: \expandafter\detokenize\expandafter{\@nameauth@C})% \fi }% } % \end{macrocode} % \end{macro} % % \begin{macro}{\ShowNameState} % \changes{3.7}{2023/02/03}{Added} % This macro tells the user what control sequence patterns % exist for any given name. % % \begin{macrocode} \newcommandx\ShowNameState[3][1=\@empty, 3=\@empty] {% % \end{macrocode} % Create a local scope to kill any local definitions on exit. % Test for bad input, then load the argument values into % the appropriate macros. % % \begin{macrocode} \begingroup% \@nameauth@Error{#2}{macro: \string\NamePatterns}% \@nameauth@LoadArgs{#1}{#2}{#3}% % \end{macrocode} % Parse the name arguments and determine name type. We use this method % instead of examining the Boolean flags because it is more efficient here. % % \begin{macrocode} \@nameauth@Choice {\def\@nameauth@nametype{nw}} {\def\@nameauth@nametype{nw,os}} {\def\@nameauth@nametype{w}} % \end{macrocode} % Check to see what control sequences exist and collect the information. % % \begin{macrocode} \ifcsname\NameauthPattern!MN\endcsname \def\@nameauth@mainname{main}% \fi \ifcsname\NameauthPattern!NF\endcsname \def\@nameauth@frontname{front}% \fi \ifcsname\NameauthPattern!PN\endcsname \edef\@nameauth@testex {\csname\NameauthPattern!PN\endcsname}% \ifx\@nameauth@testex\@nameauth@Exclude \def\@nameauth@excl{excl}% \else \def\@nameauth@xref{xref}% \fi \fi \ifcsname\NameauthPattern!PRE\endcsname \def\@nameauth@pre{pretag}% \fi \ifcsname\NameauthPattern!TAG\endcsname \def\@nameauth@tag{idxtag}% \fi \ifcsname\NameauthPattern!DB\endcsname \def\@nameauth@db{namedb}% \fi % \end{macrocode} % If either a main name or a front name exist, create a macro % that reflects this condition. % % \begin{macrocode} \ifdefined \@nameauth@mainname \def\@nameauth@namecs{}\fi \ifdefined \@nameauth@frontname \def\@nameauth@namecs{}\fi % \end{macrocode} % If an xref and an exclusion exist for a name, something went wrong. % % \begin{macrocode} \ifdefined \@nameauth@xref \ifdefined \@nameauth@excl \PackageWarning{nameauth} {Both xref and exclusion exist for \NameauthPattern}% \fi \fi % \end{macrocode} % Determine the state of the ``index finite state machine''. % % \begin{macrocode} \ifdefined \@nameauth@namecs \def\@nameauth@idxstate{2}% \ifdefined \@nameauth@xref \def\@nameauth@idxstate{4}% \fi \ifdefined \@nameauth@excl \def\@nameauth@idxstate{6}% \fi \else \def\@nameauth@idxstate{1}% \ifdefined \@nameauth@xref \def\@nameauth@idxstate{3}% \fi \ifdefined \@nameauth@excl \def\@nameauth@idxstate{5}% \fi \fi % \end{macrocode} % Display the output. % % \begin{macrocode} Pattern: {\NameauthPattern} Type: {\@nameauth@nametype} Index state: {\@nameauth@idxstate} Systems:% \ifdefined \@nameauth@mainname\ \@nameauth@mainname \fi \ifdefined \@nameauth@frontname\ \@nameauth@frontname \fi \ifdefined \@nameauth@xref\ \@nameauth@xref \fi \ifdefined \@nameauth@excl\ \@nameauth@excl \fi \ifdefined \@nameauth@pre\ \@nameauth@pre \fi \ifdefined \@nameauth@tag\ \@nameauth@tag \fi \ifdefined \@nameauth@db\ \@nameauth@db \fi \endgroup% } % \end{macrocode} % \end{macro} % % \subsubsection{Indexing} % % \begin{macro}{\IndexName} % \changes{1.26}{2012/04/24}{Fix affixes} % \changes{2.0}{2015/11/11}{Fix spaces, tagging} % \changes{2.6}{2016/09/19}{Fix commas} % \changes{3.0}{2016/10/26}{Redesigned} % \changes{3.1}{2017/01/13}{Better tests} % \changes{3.5}{2020/11/23}{New warnings, new exclusion test, % improve logic, fix namespace} % \changes{3.7}{2023/02/03}{Fix warnings} % This creates an index entry with page references. It warns if % the \cmd{\SkipIndex} prefix macro was used before it was called. % It issues additional warnings if the \texttt{verbose} option is selected. % It prints nothing. % % \begin{macrocode} \newcommandx*\IndexName[3][1=\@empty, 3=\@empty] {% % \end{macrocode} % Process and load the arguments into the appropriate macros; % test for malformed input. % % \begin{macrocode} \@nameauth@LoadArgs{#1}{#2}{#3}% \@nameauth@Error{#2}{macro \string\IndexName}% % \end{macrocode} % Warn if \cmd{\SkipIndex} was called before \cmd{\IndexName} and reset % it unless the \texttt{oldreset} option was used. % % \begin{macrocode} \if@nameauth@SkipIndex \PackageWarning{nameauth} {\string\SkipIndex precedes \string\IndexName; check for issues}% \unless\if@nameauth@OldReset \@nameauth@SkipIndexfalse% \fi \fi % \end{macrocode} % Warn if \cmd{\SeeAlso} was called before \cmd{\IndexName} and reset it. % % \begin{macrocode} \unless\if@nameauth@OldReset \if@nameauth@SeeAlso \global\@nameauth@SeeAlsofalse% \PackageWarning{nameauth}{\string\SeeAlso was reset}% \fi \fi % \end{macrocode} % 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} % Non-Western names. % We ignore \cmd{\@nameauth@C} and handle \cmd{\@nameauth@SB} appropriately. % % \begin{macrocode} {% \def\@nameauth@Temp{\expandafter\detokenize\expandafter{#2}}% \ifcsname\@nameauth@csb!PN\endcsname \if@nameauth@Verbose \edef\@nameauth@testex {\csname\@nameauth@csb!PN\endcsname}% \ifx\@nameauth@testex\@nameauth@Exclude \PackageWarning{nameauth} {\string\IndexName: exclusion exists \@nameauth@Temp}% \else \PackageWarning{nameauth} {\string\IndexName: xref exists \@nameauth@Temp}% \fi \fi \else \ifx\@nameauth@SB\@empty \@nameauth@Index{\@nameauth@csb}{\@nameauth@B}% \else \@nameauth@Index{\@nameauth@csb} {\@nameauth@B\@nameauth@space\@nameauth@SB}% \fi \fi }% % \end{macrocode} % Non-Western names, obsolete syntax. % Using \cmd{\@nameauth@C} in this path affects indexing. % % \begin{macrocode} {% \def\@nameauth@Temp{\expandafter\detokenize\expandafter{#2 #3}}% \ifcsname\@nameauth@csbc!PN\endcsname \if@nameauth@Verbose \edef\@nameauth@testex {\csname\@nameauth@csbc!PN\endcsname}% \ifx\@nameauth@testex\@nameauth@Exclude \PackageWarning{nameauth} {\string\IndexName: exclusion exists \@nameauth@Temp}% \else \PackageWarning{nameauth} {\string\IndexName: xref exists \@nameauth@Temp}% \fi \fi \else \@nameauth@Index{\@nameauth@csbc} {\@nameauth@B\@nameauth@space\@nameauth@C}% \fi }% % \end{macrocode} % Western names. % We ignore \cmd{\@nameauth@C} and handle \cmd{\@nameauth@SB} appropriately. % % \begin{macrocode} {% \def\@nameauth@Temp{\expandafter\detokenize\expandafter{#1 #2}}% \ifcsname\@nameauth@csab!PN\endcsname \if@nameauth@Verbose \edef\@nameauth@testex {\csname\@nameauth@csab!PN\endcsname}% \ifx\@nameauth@testex\@nameauth@Exclude \PackageWarning{nameauth} {\string\IndexName: exclusion exists \@nameauth@Temp}% \else \PackageWarning{nameauth} {\string\IndexName: xref exists \@nameauth@Temp}% \fi \fi \else \ifx\@nameauth@SB\@empty \@nameauth@Index{\@nameauth@csab} {\@nameauth@B,\@nameauth@space\@nameauth@A}% \else \@nameauth@Index{\@nameauth@csab} {\@nameauth@B,\@nameauth@space% \@nameauth@A,\@nameauth@space\@nameauth@SB}% \fi \fi }% } % \end{macrocode} % \end{macro} % % \begin{macro}{\IndexRef} % \changes{3.0}{2016/10/26}{Added} % \changes{3.1}{2017/01/13}{Better tests} % \changes{3.3}{2020/02/20}{Global flag reset} % \changes{3.5}{2020/11/23}{Strict \textit{see} refs, new warnings, % new exclusion test, improve logic, fix namespace} % \changes{3.7}{2023/02/03}{Fix warnings} % Create a cross-reference that is not already an exclusion or % a cross-reference. Print nothing. % % \begin{macrocode} \newcommandx*\IndexRef[4][1=\@empty, 3=\@empty] {% % \end{macrocode} % Process and load the arguments into the appropriate macros. % % \begin{macrocode} \@nameauth@LoadArgs{#1}{#2}{#3}% \protected@edef\@nameauth@Target{#4}% % \end{macrocode} % Test for malformed input. % % \begin{macrocode} \@nameauth@Error{#2}{macro \string\IndexRef}% \@nameauth@Xreftrue% % \end{macrocode} % % \newpage \noindent % Warn if \cmd{\SkipIndex} was called before \cmd{\IndexName}, % and reset it unless the \texttt{oldreset} option was used. % % \begin{macrocode} \if@nameauth@SkipIndex \PackageWarning{nameauth} {\string\SkipIndex preceded \string\IndexRef; check for issues}% \unless\if@nameauth@OldReset \@nameauth@SkipIndexfalse% \fi \fi \@nameauth@Choice % \end{macrocode} % Non-Western name, new syntax. First check if % an xref or excluded, and if so, do nothing except issue % warnings if so desired. % % \begin{macrocode} {% \def\@nameauth@Temp{\expandafter\detokenize\expandafter{#2}}% \ifcsname\@nameauth@csb!PN\endcsname \if@nameauth@Verbose \edef\@nameauth@testex {\csname\@nameauth@csb!PN\endcsname}% \ifx\@nameauth@testex\@nameauth@Exclude \PackageWarning{nameauth} {\string\IndexRef: exclusion exists \@nameauth@Temp}% \else \PackageWarning{nameauth} {\string\IndexRef: xref exists \@nameauth@Temp}% \fi \fi % \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. % % \begin{macrocode} \else \ifx\@nameauth@SB\@empty \if@nameauth@SeeAlso \@nameauth@Index{\@nameauth@csb} {\@nameauth@B|seealso{\@nameauth@Target}}% \csgdef{\@nameauth@csb!PN}{}% \else \unless\if@nameauth@OldSee \unless\ifcsname\@nameauth@csb!MN\endcsname \unless\ifcsname\@nameauth@csb!NF\endcsname \@nameauth@Index{\@nameauth@csb} {\@nameauth@B|see{\@nameauth@Target}}% \csgdef{\@nameauth@csb!PN}{}% \else \PackageWarning{nameauth} {\string\IndexRef: extant name; no xref \@nameauth@Temp}% \fi \else \PackageWarning{nameauth} {\string\IndexRef: extant name; no xref \@nameauth@Temp}% \fi \else \if@nameauth@Verbose \PackageWarning{nameauth} {\string\IndexRef: non-strict xref \@nameauth@Temp}% \fi \@nameauth@Index{\@nameauth@csb} {\@nameauth@B|see{\@nameauth@Target}}% \csgdef{\@nameauth@csb!PN}{}% \fi \fi % \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. % % \begin{macrocode} \else \if@nameauth@SeeAlso \@nameauth@Index{\@nameauth@csb} {\@nameauth@B\@nameauth@space% \@nameauth@SB|seealso{\@nameauth@Target}}% \csgdef{\@nameauth@csb!PN}{}% \else \unless\if@nameauth@OldSee \unless\ifcsname\@nameauth@csb!MN\endcsname \unless\ifcsname\@nameauth@csb!NF\endcsname \@nameauth@Index{\@nameauth@csb} {\@nameauth@B\@nameauth@space% \@nameauth@SB|see{\@nameauth@Target}}% \csgdef{\@nameauth@csb!PN}{}% \else \PackageWarning{nameauth} {\string\IndexRef: extant name; no xref \@nameauth@Temp}% \fi \else \PackageWarning{nameauth} {\string\IndexRef: extant name; no xref \@nameauth@Temp}% \fi \else \if@nameauth@Verbose \PackageWarning{nameauth} {\string\IndexRef: non-strict xref \@nameauth@Temp}% \fi \@nameauth@Index{\@nameauth@csb} {\@nameauth@B\@nameauth@space% \@nameauth@SB|see{\@nameauth@Target}}% \csgdef{\@nameauth@csb!PN}{}% \fi \fi \fi \fi }% % \end{macrocode} % Eastern or ancient name, obsolete syntax. First check if an xref or excluded. % % \begin{macrocode} {% \def\@nameauth@Temp{\expandafter\detokenize\expandafter{#2 #3}}% \ifcsname\@nameauth@csbc!PN\endcsname \if@nameauth@Verbose \edef\@nameauth@testex {\csname\@nameauth@csbc!PN\endcsname}% \ifx\@nameauth@testex\@nameauth@Exclude \PackageWarning{nameauth} {\string\IndexRef: exclusion exists \@nameauth@Temp}% \else \PackageWarning{nameauth} {\string\IndexRef: xref exists \@nameauth@Temp}% \fi \fi % \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. % % \begin{macrocode} \else \if@nameauth@SeeAlso \@nameauth@Index{\@nameauth@csbc} {\@nameauth@B\@nameauth@space% \@nameauth@C|seealso{\@nameauth@Target}}% \csgdef{\@nameauth@csbc!PN}{}% \else \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}}% \csgdef{\@nameauth@csbc!PN}{}% \else \PackageWarning{nameauth} {\string\IndexRef: extant name; no xref \@nameauth@Temp}% \fi \else \PackageWarning{nameauth} {\string\IndexRef: extant name; no xref \@nameauth@Temp}% \fi \else \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}}% \csgdef{\@nameauth@csbc!PN}{}% \fi \fi \fi }% % \end{macrocode} % Western name, without and with affix. First check if an xref or excluded. % % \begin{macrocode} {% \def\@nameauth@Temp{\expandafter\detokenize\expandafter{#1 #2}}% \ifcsname\@nameauth@csab!PN\endcsname \if@nameauth@Verbose \edef\@nameauth@testex {\csname\@nameauth@csab!PN\endcsname}% \ifx\@nameauth@testex\@nameauth@Exclude \PackageWarning{nameauth} {\string\IndexRef: exclusion exists \@nameauth@Temp}% \else \PackageWarning{nameauth} {\string\IndexRef: xref exists \@nameauth@Temp}% \fi \fi % \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. % % \begin{macrocode} \else \ifx\@nameauth@SB\@empty \if@nameauth@SeeAlso \@nameauth@Index{\@nameauth@csab} {\@nameauth@B,\@nameauth@space% \@nameauth@A|seealso{\@nameauth@Target}}% \csgdef{\@nameauth@csab!PN}{}% \else \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}}% \csgdef{\@nameauth@csab!PN}{}% \else \PackageWarning{nameauth} {\string\IndexRef: extant name; no xref \@nameauth@Temp}% \fi \else \PackageWarning{nameauth} {\string\IndexRef: extant name; no xref \@nameauth@Temp}% \fi \else \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}}% \csgdef{\@nameauth@csab!PN}{}% \fi \fi % \end{macrocode} % When the suffix is non-empty, either create a \textit{see also} % or a \textit{see} reference. We permit the latter when a name exists % only if the \texttt{oldsee} option is used; then issue a warning. % % \begin{macrocode} \else \if@nameauth@SeeAlso \@nameauth@Index{\@nameauth@csab} {\@nameauth@B,\@nameauth@space% \@nameauth@A,\@nameauth@space% \@nameauth@SB|seealso{\@nameauth@Target}}% \csgdef{\@nameauth@csab!PN}{}% \else \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,\@nameauth@space% \@nameauth@SB|see{\@nameauth@Target}}% \csgdef{\@nameauth@csab!PN}{}% \else \PackageWarning{nameauth} {\string\IndexRef: extant name; no xref \@nameauth@Temp}% \fi \else \PackageWarning{nameauth} {\string\IndexRef: extant name; no xref \@nameauth@Temp}% \fi \else \if@nameauth@Verbose \PackageWarning{nameauth} {\string\IndexRef: non-strict xref \@nameauth@Temp}% \fi \@nameauth@Index{\@nameauth@csab} {\@nameauth@B,\@nameauth@space% \@nameauth@A,\@nameauth@space% \@nameauth@SB|see{\@nameauth@Target}}% \csgdef{\@nameauth@csab!PN}{}% \fi \fi \fi \fi }% \@nameauth@Xreffalse% \if@nameauth@OldReset \@nameauth@SeeAlsofalse% \else \global\@nameauth@SeeAlsofalse% \fi } % \end{macrocode} % \end{macro} % % \begin{macro}{\ExcludeName} % \changes{0.94}{2012/02/15}{Added} % \changes{2.3}{2016/01/05}{New xref test} % \changes{3.0}{2016/10/26}{Redesigned} % \changes{3.3}{2020/02/20}{Better warnings} % \changes{3.5}{2020/11/23}{New warnings, new exclusion test, % fix bug in old syntax, new logic, fix namespace} % \changes{3.7}{2023/02/03}{Fix warnings, optimized} % Prevent a name from being indexed by initializing a regular % cross-reference control sequence with the value of % \cmd{\@nameauth@Exclude}. % % \begin{macrocode} \newcommandx*\ExcludeName[3][1=\@empty, 3=\@empty] {% % \end{macrocode} % Process and load the arguments into the appropriate macros. % % \begin{macrocode} \@nameauth@LoadArgs{#1}{#2}{#3}% \@nameauth@Error{#2}{macro \string\ExcludeName}% % \end{macrocode} % Parse the name arguments and create an excluded xref, % unless one already exists. % % \begin{macrocode} \@nameauth@Choice {\def\@nameauth@Temp{\expandafter\detokenize\expandafter{#2}}} {\def\@nameauth@Temp{\expandafter\detokenize\expandafter{#2 #3}}} {\def\@nameauth@Temp{\expandafter\detokenize\expandafter{#1 #2}}}% % \end{macrocode} % % \newpage \noindent % Verbose warnings say that an extant name is being excluded; % the operation is allowed. % % \begin{macrocode} \if@nameauth@Verbose \ifcsname\NameauthPattern!MN\endcsname \PackageWarning{nameauth} {\string\ExcludeName: extant name \@nameauth@Temp}% \fi \ifcsname\NameauthPattern!NF\endcsname \PackageWarning{nameauth} {\string\ExcludeName: extant name \@nameauth@Temp}% \fi \fi % \end{macrocode} % One cannot exclude an extant cross-reference or exclusion. % Verbose warnings only. % % \begin{macrocode} \ifcsname\NameauthPattern!PN\endcsname \if@nameauth@Verbose \edef\@nameauth@testex {\csname\NameauthPattern!PN\endcsname}% \ifx\@nameauth@testex\@nameauth@Exclude \PackageWarning{nameauth} {\string\ExcludeName: exclusion exists \@nameauth@Temp}% \else \PackageWarning{nameauth} {\string\ExcludeName: xref exists \@nameauth@Temp}% \fi \fi \else \csxdef{\NameauthPattern!PN}{\@nameauth@Exclude}% \fi } % \end{macrocode} % \end{macro} % % \begin{macro}{\IncludeName} % \changes{3.0}{2016/10/26}{Added} % \changes{3.3}{2020/02/20}{Added warnings} % \changes{3.5}{2020/11/23}{New exclusion test, optimize logic, % fix namespace} % \changes{3.7}{2023/02/03}{Fix warnings, optimized} % This macro allows a name to be indexed once again only if % it had been excluded. % % \begin{macrocode} \newcommandx*\IncludeName[3][1=\@empty, 3=\@empty] {% % \end{macrocode} % Process and load the arguments into the appropriate macros. % Get the current name type, pattern, and contents if a warning % is needed. % % \begin{macrocode} \@nameauth@LoadArgs{#1}{#2}{#3}% \@nameauth@Error{#2}{macro \string\IncludeName}% \@nameauth@Choice {\def\@nameauth@Temp{\expandafter\detokenize\expandafter{#2}}} {\def\@nameauth@Temp{\expandafter\detokenize\expandafter{#2 #3}}} {\def\@nameauth@Temp{\expandafter\detokenize\expandafter{#1 #2}}}% % \end{macrocode} % Test whether the name is an exclusion or a regular xref. % If the former, delete its control sequence. If the latter, % do nothing and issue a warning. % % \begin{macrocode} \ifcsname\NameauthPattern!PN\endcsname \edef\@nameauth@testex {\csname\NameauthPattern!PN\endcsname}% \ifx\@nameauth@testex\@nameauth@Exclude \global\csundef{\NameauthPattern!PN}% \else \if@nameauth@Verbose \PackageWarning{nameauth} {\string\IncludeName: extant xref \@nameauth@Temp}% \fi \fi \fi } % \end{macrocode} % \end{macro} % % \begin{macro}{\IncludeName*} % \changes{3.0}{2016/10/26}{Added} % \changes{3.5}{2020/11/23}{Improve logic, fix namespace} % \changes{3.7}{2023/02/03}{Optimized} % This macro allows any name to be indexed by voiding any exclusion or % cross-reference. % % \begin{macrocode} \WithSuffix{\newcommandx*}\IncludeName*[3][1=\@empty, 3=\@empty] {% \@nameauth@LoadArgs{#1}{#2}{#3}% \@nameauth@Error{#2}{macro \string\IncludeName*}% \@nameauth@Choice{}{}{}% \global\csundef{\NameauthPattern!PN}% } % \end{macrocode} % \end{macro} % % \begin{macro}{\PretagName} % \changes{2.0}{2015/11/11}{Added} % \changes{3.5}{2020/11/23}{New warnings, new exclusion test, % improve logic, fix namespace} % \changes{3.7}{2023/02/03}{Fix warnings, optimized} % This creates an index entry tag that is applied before a name % by \cmd{\@nameauth@Index}. % % \begin{macrocode} \newcommandx*\PretagName[4][1=\@empty, 3=\@empty] {% % \end{macrocode} % Process and load the arguments into the appropriate macros. % % \begin{macrocode} \@nameauth@LoadArgs{#1}{#2}{#3}% \@nameauth@Error{#2}{macro \string\PretagName}% % \end{macrocode} % Sort only when permitted. % Get the current name type, pattern, and contents if a warning % is needed. % % \begin{macrocode} \if@nameauth@Pretag \@nameauth@Choice {\def\@nameauth@Temp{\expandafter\detokenize\expandafter{#2}}} {\def\@nameauth@Temp{\expandafter\detokenize\expandafter{#2 #3}}} {\def\@nameauth@Temp{\expandafter\detokenize\expandafter{#1 #2}}}% % \end{macrocode} % Create the sort tag. Verbose warnings let us know if we are % sorting either exclusions or cross-references. % % \begin{macrocode} \if@nameauth@Verbose \edef\@nameauth@testex {\csname\NameauthPattern!PN\endcsname}% \ifx\@nameauth@testex\@nameauth@Exclude \PackageWarning{nameauth} {\string\PretagName: tag exclusion \@nameauth@Temp}% \else \PackageWarning{nameauth} {\string\PretagName: tag xref \@nameauth@Temp}% \fi \fi \csgdef{\NameauthPattern!PRE}{#4\@nameauth@Actual}% \else \PackageWarning{nameauth} {\string\PretagName: deactivated}% \fi } % \end{macrocode} % \end{macro} % % \begin{macro}{\TagName} % \changes{1.2}{2012/02/25}{Added} % \changes{1.9}{2015/07/09}{Fix cs collisions} % \changes{2.0}{2015/11/11}{Redesign tagging} % \changes{3.5}{2020/11/23}{New warnings, new exclusion test, % improve logic, fix namespace} % \changes{3.7}{2023/02/03}{Optimized} % This creates an index entry tag for a name that is not either % an exclusion or a cross-reference. % % \begin{macrocode} \newcommandx*\TagName[4][1=\@empty, 3=\@empty] {% % \end{macrocode} % Process and load the arguments into the appropriate macros. % Get the current name type, pattern, and contents if a warning % is needed. % % \begin{macrocode} \@nameauth@LoadArgs{#1}{#2}{#3}% \@nameauth@Error{#2}{macro \string\TagName}% \@nameauth@Choice {\def\@nameauth@Temp{\expandafter\detokenize\expandafter{#2}}} {\def\@nameauth@Temp{\expandafter\detokenize\expandafter{#2 #3}}} {\def\@nameauth@Temp{\expandafter\detokenize\expandafter{#1 #2}}}% % \end{macrocode} % Verbose warnings let us know if we are sorting either % exclusions or cross-references. Do not create a tag if % that is the case; otherwise, create a tag. % % \begin{macrocode} \ifcsname\NameauthPattern!PN\endcsname \if@nameauth@Verbose \edef\@nameauth@testex {\csname\NameauthPattern!PN\endcsname}% \ifx\@nameauth@testex\@nameauth@Exclude \PackageWarning{nameauth} {\string\TagName: no tag, exclusion \@nameauth@Temp}% \else \PackageWarning{nameauth} {\string\TagName: no tag, xref \@nameauth@Temp}% \fi \fi \else \csgdef{\NameauthPattern!TAG}{#4}% \fi } % \end{macrocode} % \end{macro} % % \begin{macro}{\UntagName} % \changes{1.2}{2012/02/25}{Added} % \changes{1.9}{2015/07/09}{Global undef, no cs collisions} % \changes{2.0}{2015/11/11}{Redesign tagging} % \changes{3.5}{2020/11/23}{Improve logic, fix namespace} % \changes{3.7}{2023/02/03}{Optimized} % This deletes an index tag. % % \begin{macrocode} \newcommandx*\UntagName[3][1=\@empty, 3=\@empty] {% \@nameauth@LoadArgs{#1}{#2}{#3}% \@nameauth@Error{#2}{macro \string\UntagName}% \@nameauth@Choice{}{}{}% \global\csundef{\NameauthPattern!TAG}% } % \end{macrocode} % \end{macro} % % \subsubsection{Name Data Tags} % % \begin{macro}{\NameAddInfo} % \changes{2.4}{2016/03/15}{Added} % \changes{3.5}{2020/11/23}{Improve logic, fix namespace} % \changes{3.7}{2023/02/03}{Optimized} % This creates a macro that expands to information associated with % a given name, similar to an index tag, but usable in the body text. % % \begin{macrocode} \newcommandx\NameAddInfo[4][1=\@empty, 3=\@empty] {% \@nameauth@LoadArgs{#1}{#2}{#3}% \@nameauth@Error{#2}{macro \string\NameAddInfo}% \@nameauth@Choice{}{}{}% \csgdef{\NameauthPattern!DB}{#4}% } % \end{macrocode} % \end{macro} % % \begin{macro}{\NameQueryInfo} % \changes{2.4}{2016/03/15}{Added} % \changes{3.1}{2017/01/13}{Short macro} % \changes{3.3}{2020/02/20}{Lock added} % \changes{3.5}{2020/11/23}{Improve logic, fix namespace} % \changes{3.7}{2023/02/03}{Optimized} % This prints the information created by \cmd{\NameAddInfo} if it exists. % % \begin{macrocode} \newcommandx*\NameQueryInfo[3][1=\@empty, 3=\@empty] {% \unless\if@nameauth@BigLock \@nameauth@LoadArgs{#1}{#2}{#3}% \@nameauth@Error{#2}{macro \string\NameQueryInfo}% \@nameauth@Choice{}{}{}% \ifcsname\NameauthPattern!DB\endcsname \csname\NameauthPattern!DB\endcsname% \fi \fi } % \end{macrocode} % \end{macro} % % \begin{macro}{\NameClearInfo} % \changes{2.4}{2016/03/15}{Added} % \changes{3.5}{2020/11/23}{Improve logic, fix namespace} % \changes{3.7}{2023/02/03}{Optimized} % This deletes a text tag. It has the same structure as \cmd{\UntagName}. % % \begin{macrocode} \newcommandx*\NameClearInfo[3][1=\@empty, 3=\@empty] {% \@nameauth@LoadArgs{#1}{#2}{#3}% \@nameauth@Error{#2}{macro \string\NameClearInfo}% \@nameauth@Choice{}{}{}% \global\csundef{\NameauthPattern!DB}% } % \end{macrocode} % \end{macro} % % \subsubsection{Name Decisions} % % \begin{macro}{\IfMainName} % \changes{2.3}{2016/01/05}{Added} % \changes{3.5}{2020/11/23}{Improve logic, fix namespace, % local or global scope} % \changes{3.7}{2023/02/03}{Optimized} % This macro expands one path if a main matter name exists, or else the % other. The state of \texttt{\textbackslash if@nameauth@GlobalScope} % determines whether or not the paths are in a local scope. First we % load the arguments into the standard macros, check for error, and % get the current name pattern. % % \begin{macrocode} \newcommandx\IfMainName[5][1=\@empty, 3=\@empty] {% \@nameauth@LoadArgs{#1}{#2}{#3}% \@nameauth@Error{#2}{macro \string\IfMainName}% \@nameauth@Choice{}{}{}% % \end{macrocode} % Take this path if the pattern exists. % % \begin{macrocode} \ifcsname\NameauthPattern!MN\endcsname \if@nameauth@GlobalScope #4\else {#4}\fi \else % \end{macrocode} % Take this path if the pattern does not exist. % % \begin{macrocode} \if@nameauth@GlobalScope #5\else {#5}\fi \fi }% % \end{macrocode} % \end{macro} % % \begin{macro}{\IfFrontName} % \changes{2.3}{2016/01/05}{Added} % \changes{3.5}{2020/11/23}{Improve logic, fix namespace, % local or global scope} % \changes{3.7}{2023/02/03}{Optimized} % This macro expands one path if a front matter name exists, or else the % other. The state of \texttt{\textbackslash if@nameauth@GlobalScope} % determines whether or not the paths are in a local scope. First we % load the arguments into the standard macros, check for error, and % get the current name pattern. % % \begin{macrocode} \newcommandx\IfFrontName[5][1=\@empty, 3=\@empty] {% \@nameauth@LoadArgs{#1}{#2}{#3}% \@nameauth@Error{#2}{macro \string\IfFrontName}% \@nameauth@Choice{}{}{}% % \end{macrocode} % Take this path if the pattern exists. % % \begin{macrocode} \ifcsname\NameauthPattern!NF\endcsname \if@nameauth@GlobalScope #4\else {#4}\fi \else % \end{macrocode} % Take this path if the pattern does not exist. % % \begin{macrocode} \if@nameauth@GlobalScope #5\else {#5}\fi \fi } % \end{macrocode} % \end{macro} % % \newpage % % \begin{macro}{\IfAKA} % \changes{2.3}{2016/01/05}{Added} % \changes{2.4}{2016/03/15}{Test for excluded} % \changes{3.0}{2016/10/26}{Redesigned} % \changes{3.5}{2020/11/23}{New exclusion test, optimize logic, % fix namespace, local or global scope} % \changes{3.7}{2023/02/03}{Optimized} % This macro expands one path if a cross-reference exists, another if % it does not exist, and a third if it is excluded. The state of % \texttt{\textbackslash if@nameauth@GlobalScope} determines whether or not % the paths are in a local scope. First we load the arguments into % the standard macros, check for error, and get the current name pattern. % % \begin{macrocode} \newcommandx\IfAKA[6][1=\@empty, 3=\@empty] {% \@nameauth@LoadArgs{#1}{#2}{#3}% \@nameauth@Error{#2}{macro \string\IfAKA}% \@nameauth@Choice{}{}{}% \ifcsname\NameauthPattern!PN\endcsname \edef\@nameauth@testex {\csname\NameauthPattern!PN\endcsname}% % \end{macrocode} % Take this path if the pattern is an exclusion. % % \begin{macrocode} \ifx\@nameauth@testex\@nameauth@Exclude \if@nameauth@GlobalScope #6\else {#6}\fi \else % \end{macrocode} % Take this path if the pattern exists. % % \begin{macrocode} \if@nameauth@GlobalScope #4\else {#4}\fi \fi \else % \end{macrocode} % Take this path if the pattern does not exist. % % \begin{macrocode} \if@nameauth@GlobalScope #5\else {#5}\fi \fi } % \end{macrocode} % \end{macro} % % \begin{macro}{\ForgetName} % \changes{1.9}{2015/07/09}{Global undef} % \changes{2.3}{2016/01/05}{Global or local} % \changes{3.5}{2020/11/23}{Improve logic, fix namespace} % \changes{3.7}{2023/02/03}{Optimized} % This undefines a control sequence to force a ``first use''. % % \begin{macrocode} \newcommandx*\ForgetName[3][1=\@empty, 3=\@empty] {% % \end{macrocode} % Process and load the arguments into the appropriate macros. % % \begin{macrocode} \@nameauth@LoadArgs{#1}{#2}{#3}% \@nameauth@Error{#2}{macro \string\ForgetName}% % \end{macrocode} % Now we parse the arguments, destroying the control sequences either % by current name system type or completely. |@nameauth@LocalNames| toggles % current system or both, while we select the type of name with % |@nameauth@MainFormat|. % % \begin{macrocode} \@nameauth@Choice{}{}{}% \if@nameauth@LocalNames \if@nameauth@MainFormat \global\csundef{\NameauthPattern!MN}% \else \global\csundef{\NameauthPattern!NF}% \fi \else \global\csundef{\NameauthPattern!MN}% \global\csundef{\NameauthPattern!NF}% \fi } % \end{macrocode} % \end{macro} % % \begin{macro}{\SubvertName} % \changes{0.9}{2012/02/10}{Added} % \changes{2.3}{2016/01/05}{Global or local} % \changes{3.1}{2017/01/13}{Fix old syntax} % \changes{3.5}{2020/11/23}{Improve logic, fix namespace} % \changes{3.7}{2023/02/03}{Optimized} % This defines a control sequence to force a ``subsequent use''. % % \begin{macrocode} \newcommandx*\SubvertName[3][1=\@empty, 3=\@empty] {% \@nameauth@LoadArgs{#1}{#2}{#3}% \@nameauth@Error{#2}{macro \string\SubvertName}% % \end{macrocode} % Now we parse the arguments, defining the control sequences either % by current name system type or completely. |@nameauth@LocalNames| toggles % current system or both, while we select the type of name with % |@nameauth@MainFormat|. % % \begin{macrocode} \@nameauth@Choice{}{}{}% \if@nameauth@LocalNames \if@nameauth@MainFormat \csgdef{\NameauthPattern!MN}{}% \else \csgdef{\NameauthPattern!NF}{}% \fi \else \csgdef{\NameauthPattern!MN}{}% \csgdef{\NameauthPattern!NF}{}% \fi } % \end{macrocode} % \end{macro} % % \subsubsection{Pseudonyms} % % \begin{macro}{\AKA} % \changes{1.26}{2012/04/24}{Fix affixes} % \changes{1.5}{2013/02/22}{Reversing/caps} % \changes{2.0}{2015/11/11}{Trim spaces; fix tags} % \changes{2.1}{2015/11/24}{Fix Unicode} % \changes{2.3}{2016/01/05}{Fix starred mode} % \changes{2.41}{2016/03/17}{Fix token regs} % \changes{2.6}{2016/09/19}{Fix index commas} % \changes{3.0}{2016/10/26}{Redesigned} % \changes{3.1}{2017/01/13}{Can skip index} % \changes{3.3}{2020/02/20}{Global flag reset} % \changes{3.5}{2020/11/23}{Fix namespace} % \cmd{\AKA} prints an alternate name and creates index cross-references. % % \begin{macrocode} \newcommandx*\AKA[5][1=\@empty, 3=\@empty, 5=\@empty] {% % \end{macrocode} % Prevent entering \cmd{\AKA} via itself or \cmd{\@nameauth@Name}. % Prevents and resets \cmd{\JustIndex}. Tell the formatting system % that \cmd{\AKA} is running. % % \begin{macrocode} \if@nameauth@BigLock \@nameauth@Locktrue% \fi \unless\if@nameauth@Lock \@nameauth@Locktrue% \@nameauth@InAKAtrue% \if@nameauth@OldReset \@nameauth@JustIndexfalse% \else \global\@nameauth@JustIndexfalse% \fi % \end{macrocode} % Test for malformed input. % % \begin{macrocode} \@nameauth@Error{#2}{macro \string\AKA}% \@nameauth@Error{#4}{macro \string\AKA}% % \end{macrocode} % Names occur in horizontal mode; we ensure that. Next we make copies % of the target name arguments and we parse and print the cross-reference name. % % \begin{macrocode} \leavevmode\hbox{}% \protected@edef\@nameauth@Ai{\trim@spaces{#1}}% \protected@edef\@nameauth@Bi{\@nameauth@Root{#2}}% \protected@edef\@nameauth@Si{\@nameauth@Suffix{#2}}% \@nameauth@Parse{#3}{#4}{#5}{!PN}% % \end{macrocode} % \noindent Create an index cross-reference based on the arguments. % % \begin{macrocode} \unless\if@nameauth@SkipIndex \ifx\@nameauth@Ai\@empty \ifx\@nameauth@Si\@empty \IndexRef[#3]{#4}[#5]{\@nameauth@Bi}% \else \IndexRef[#3]{#4}[#5] {\@nameauth@Bi\@nameauth@space\@nameauth@Si}% \fi \else \ifx\@nameauth@Si\@empty \IndexRef[#3]{#4}[#5] {\@nameauth@Bi,\@nameauth@space\@nameauth@Ai}% \else \IndexRef[#3]{#4}[#5] {\@nameauth@Bi,\@nameauth@space \@nameauth@Ai,\@nameauth@space\@nameauth@Si}% \fi \fi \fi % \end{macrocode} % Reset all the ``per name'' Boolean values. The default is global. % % \begin{macrocode} \@nameauth@Flags% \@nameauth@Lockfalse% \@nameauth@InAKAfalse% % \end{macrocode} % Close the ``locked'' branch and call the full stop detection. % This conditional statement must be on one line. % % \begin{macrocode} \fi \if@nameauth@Punct\expandafter\@nameauth@CheckDot\fi } % \end{macrocode} % \end{macro} % % \begin{macro}{\AKA*} % \changes{0.9}{2012/02/10}{Added} % This starred form sets a Boolean to print only the alternate name argument, % if that exists, and calls \cmd{\AKA}. % % \begin{macrocode} \WithSuffix{\newcommand*}\AKA*{\@nameauth@AltAKAtrue \AKA} % \end{macrocode} % \end{macro} % % \begin{macro}{\PName} % \changes{2.3}{2016/01/05}{Work with hooks} % \changes{3.1}{2017/01/13}{Can skip index} % \changes{3.5}{2020/11/23}{Warning and flag resets added} % \changes{3.7}{2023/02/03}{Fix warnings} % \cmd{\PName} is a convenience macro that calls \cmd{\NameauthName}, then \cmd{\AKA}. % % \begin{macrocode} \newcommandx*\PName[5][1=\@empty,3=\@empty,5=\@empty] {% % \end{macrocode} % If we used \cmd{\JustIndex}, we ignore and reset its flag to false. % % \begin{macrocode} \if@nameauth@OldReset \@nameauth@JustIndexfalse% \else \global\@nameauth@JustIndexfalse% \fi % \end{macrocode} % If we used \cmd{\SkipIndex}, we reset the flag of \cmd{\SeeAlso} and % activate \cmd{\SkipIndex} for both \cmd{\NameauthName} and \cmd{\AKA}. % % \begin{macrocode} \if@nameauth@SkipIndex \unless\if@nameauth@OldReset \global\@nameauth@SeeAlsofalse% \fi \NameauthName[#1]{#2} (\SkipIndex\AKA[#1]{#2}[#3]{#4}[#5])% \else % \end{macrocode} % Otherwise, if we used \cmd{\SeeAlso} we set the flag of \cmd{\SeeAlso} % false for \cmd{\NameauthName} and true for \cmd{\AKA}. The ``normal'' % case after that is trivial. % % \begin{macrocode} \if@nameauth@SeeAlso \@nameauth@SeeAlsofalse\NameauthName[#1]{#2} \@nameauth@SeeAlsotrue(\AKA[#1]{#2}[#3]{#4}[#5])% \else \NameauthName[#1]{#2} (\AKA[#1]{#2}[#3]{#4}[#5])% \fi \fi % \end{macrocode} % Warn if \cmd{\SkipIndex} remains in effect (potentially due to % the \texttt{oldreset} option). Normally, this state should not occur. % % \begin{macrocode} \if@nameauth@SkipIndex \PackageWarning{nameauth} {\string\SkipIndex still active after \string\PName; check}% \fi } % \end{macrocode} % \end{macro} % % \begin{macro}{\PName*} % This sets up a long name reference and calls \cmd{\PName}. % % \begin{macrocode} \WithSuffix{\newcommand*}\PName*{\@nameauth@FullNametrue \PName} % \end{macrocode} % \end{macro} % % \Finale % \endinput % %<*compat> %< %<*examples> %< \< Bailey & Betsey & Bailey & > \end{nameauth} \begin{nameauth} \< Wash & George & Washington & > \< Aris & & Aristotle & > \< Plato & & Plato & > \< Aeth & & Æthelred, II & > \< Sun & & Sun, Yat-sen & > \< Linc & Abraham & Lincoln & > \< MLK & Martin Luther & King, Jr. & > \< Soto & Hernando & de Soto & > \< Goethe & J.W. von & Goethe & > \< Patton & George S. & Patton, Jr. & > \< Ike & Dwight D. & Eisenhower & > \end{nameauth} \begin{nameauth} \< Luth & Martin & \noexpand\textSC{Luther} & > \< Cath & Catherine \noexpand\AltCaps{d}e' & \noexpand\textSC{Medici} & > \end{nameauth} \begin{nameauth} \< Jeff & Thomas & \noexpand\textSC{Jefferson}\noexpand\GEN{} & > \end{nameauth} \begin{nameauth} \< Scipio & \noexpand\SCIPi & \noexpand\SCIPii & > \< TGrac & \noexpand\TSemp & Gracchus & > \end{nameauth} \begin{nameauth} \< OScipio & Lucius & \noexpand\CSB & > % O for Oxford \end{nameauth} \begin{nameauth} \< Shak & \noexpand\WM & \noexpand\SHK & > \end{nameauth} \begin{nameauth} \< deSmet & Pierre-Jean & \noexpand\Fbox{\noexpand\AltCaps{d}e~Smet} & > \end{nameauth} % % We could add name info database tags (text tags) either % in the preamble or in the document environment. We will do % the latter in this example file. % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % Below we establish sort tags for names. % % Sort these names under: US Presidents. \PretagName[George]{Washington}{US Presidents!Washington, George} \PretagName[Abraham]{Lincoln}{US Presidents!Lincoln, Abraham} % Sort these names under: Philosophers. \PretagName{Aristotle}{Philosophers!Aristotle} \PretagName{Plato}{Philosophers!Plato} % Sort these names under: Black Americans, famous. \PretagName[Frederick]{Douglass} {Black Americans, famous!Douglass, Frederick} \PretagName[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[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 Collected Examples} \author{Charles P. Schaum} \date{2023/02/03} \begin{document} \maketitle \phantomsection \pdfbookmark[1]{\contentsname}{toc} \tableofcontents \newpage \section{Minimal Example} \begin{enumerate*} \item[\textbf{1.}] \Doug\ rose to eminence by sheer force of character and talents that neither slavery nor caste proscription could crush. \item[\textbf{2.}] \Doug's early life is perhaps the most complete indictment of the slave system ever presented at the bar of public opinion. \item[\textbf{3.}] \Doug\ was born in February, l8l7. His earliest memories centered around the cabin of his grandmother, \Bailey.\\ \end{enumerate*} \index{example, minimal} \ForgetName[Frederick]{Douglass} \ForgetName[Betsey]{Bailey} \noindent \begin{enumerate*} \item[\textbf{2.}] \Doug's early life is perhaps the most complete indictment of the slave system ever presented at the bar of public opinion. \item[\textbf{3.}] \Doug\ was born in February, l8l7. His earliest memories centered around the cabin of his grandmother, \Bailey. \item[\textbf{1.}] \Doug\ rose to eminence by sheer force of character and talents that neither slavery nor caste proscription could crush. \end{enumerate*} \section{Multiple Indexes} 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 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.\\ \TagName[George]{Washington}{!as general} We can reminisce about \LWash[General]. \UntagName[George]{Washington} When speaking of \Linc, we can refer to \LLinc[Abe]. \subsection{Philosophers} 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. \subsection{Further Discussion} \TagName[George]{Washington}{!as general} \TagName[Dwight D.]{Eisenhower}{!as general} \LWash, \LPatton, and \LIke\ were high-ranking generals.\\ \TagName[Dwight D.]{Eisenhower}{!as president} \UntagName[George]{Washington} \Wash\ and \Ike\ also were US presidents. \small % Instead of pre-tagging Ike we do the following: \index[per]{US Presidents!other|see{Eisenhower, Dwight D., president}} \section{More Complex Hooks} % First save main- and front-matter hooks. Then change % first-use hooks for both main matter and front matter. \let\OldFormat\NamesFormat \let\OldFrontNames\FrontNamesFormat \renewcommand*\NamesFormat[1]{\textbf{#1}\unless\ifinner \marginpar{\raggedleft\scriptsize #1}\fi} \renewcommand*\FrontNamesFormat[1]{\textit{#1}\unless\ifinner \marginpar{\raggedleft\scriptsize #1}\fi} \index{complex hooks, intro} The new format (front matter):\NamesInactive \Name{Vlad, III}[III Dracula], known as \IndexRef{Vlad, Ţepeş}{Vlad III}\SubvertThis\Name*{Vlad, Ţepeş} (\Name*{Vlad, Ţepeş}[the Impaler]) after his death, was the son of \Name{Vlad, II}[II Dracul], a member of the Order of the Dragon. Later references to ``\Name*{Vlad, III}'' and ``\Name{Vlad, III}'' appear thus. The new format (main matter):\NamesActive \Name{Vlad, III}[III Dracula], known as \IndexRef{Vlad, Ţepeş}{Vlad III}\SubvertThis\Name*{Vlad, Ţepeş} (\Name*{Vlad, Ţepeş}[the Impaler]) after his death, was the son of \Name{Vlad, II}[II Dracul], a member of the Order of the Dragon. Later references to ``\Name*{Vlad, III}'' and ``\Name{Vlad, III}'' appear thus. \let\NamesFormat\OldFormat \let\FrontNamesFormat\OldFrontNames We are back in the old format. in the front matter we see: \NamesInactive \ForgetThis\Name{Vlad, III}[III Dracula], \Name*{Vlad, III}, and \Name{Vlad, III}. in the main matter we see: \NamesActive \ForgetThis\Name{Vlad, III}[III Dracula], \Name*{Vlad, III}, and \Name{Vlad, III}. \section{Life Dates in Hooks} % Add data tags to names. \NameAddInfo[George]{Washington}{ (1732--99)} \NameAddInfo[Mustafa]{Kemal}{ (1881--1938)} \NameAddInfo{Atat\"urk}{ (in 1934, a special surname)} % Ensure that Atat\"urk is a cross-reference that % has no page entries in the index. \IndexRef{Atat\"urk}{Kemal, Mustafa} % Manually suppress data tag in ``first'' reference \newif\ifNoTag % Redesign formatting hook to usually print a tag % only in ``first'' reference. On exit, It resets % the flag that suppresses tags, making that flag % work only once per name use. \renewcommand*\NamesFormat[1] {% #1% \ifcsname\NameauthPattern!DB\endcsname \unless\ifNoTag \expandafter\csname\NameauthPattern!DB\endcsname% \fi \global\NoTagfalse% \fi } \ForgetThis\Name[George]{Washington} held office as the first US president from 1789 to 1797. \Name[George]{Washington} was the only president whose term in office was completely in the eighteenth century. If we need to trigger the first use hook at some point, we can suppress dates and get an automatic long reference via: \NoTagtrue\ForgetThis\Name[George]{Washington}. Or we can trigger the first-use hook in a subsequent name use and still have dates: \ForceName\Name[George]{Washington}. \index{life dates} We can add name info tags to names used only as cross- references. For example, \Name[Mustafa]{Kemal} was granted the name \Name{Atat\"urk}. We mention \Name[Mustafa]{Kemal} and \Name{Atat\"urk} again. Likewise, we can trigger a first use, but with no data tag tag: \NoTagtrue\ForgetThis\Name{Atat\"urk}. \section{Alternate Formatting} \AltFormatActive \renewcommand*\NamesFormat{} \renewcommand*\MainNameHook{\AltOff} \noindent \ForgetThis\Name[Konrad]{\noexpand\textSC{Zuse}}; \Name[Konrad]{\noexpand\textSC{Zuse}}\\ \ForgetThis\Name[Ada]{\noexpand\textIT{Lovelace}}; \Name[Ada]{\noexpand\textIT{Lovelace}}\\ \ForgetThis\Name[Charles]{\noexpand\textBF{Babbage}}; \Name[Charles]{\noexpand\textBF{Babbage}}\\ \ForgetThis\Name{\noexpand\textUC{Kanade}, Takeo}; \Name{\noexpand\textUC{Kanade}, Takeo} \index{formatting, alternate} \renewcommand*\MainNameHook{\sffamily\AltOff} \ForgetThis\Luth\ was a leading figure in the Protestant Reformation. \Luth\ believed that one is declared righteous in a forensic sense by divine grace through faith created by the Holy Spirit via the Gospel and the Sacraments. \ForgetThis\Cath\ was not only Queen of France in her own right, but she also guided the reigns of her three sons. \CapThis\LCath[\noexpand\AltCaps{d}e'] was blamed for the St.\ Bartholomew's Day massacre that saw the murder of thousands of Huguenots. \index{formatting, alternate} \section{Grammatical Inflections in Names} \newif\ifGenitive \newif\ifDoGenitive \newcommand*\GEN{\ifDoGenitive\textSC{'s}\fi} \renewcommand*\NamesFormat[1] {\ifGenitive\DoGenitivetrue\fi#1\global\Genitivefalse} \renewcommand*\MainNameHook[1] {\ifGenitive\DoGenitivetrue\fi\AltOff#1\global\Genitivefalse} Consider \Genitivetrue\Jeff\ legacy as the author of the colonies' Declaration of Independence and his impact as third president of the United States. \Jeff\ was a complex historical figure whose actions defy a consistent moral compass both in public policy and in personal affairs. \index{inflections, grammatical} \section{Sample Reference Work I} % Make a cross-reference from a variant name form to the % form of the head-words \IndexRef[Heinrich Wilhelm]{\noexpand\textSC{R\"uhmann}} {\noexpand\textSC{R\"uhmann}, Heinz} % Define the formatting hooks. Since we use the `altformat' % option, alternate formatting is turned off in later % name uses. \renewcommand*\NamesFormat{} \renewcommand*\MainNameHook{\AltOff} % Typeset head-words with a slanted font. \newcommand{\RefArticle}[3] {% \def\check{#2}% \ifx\check\empty \noindent\ForgetThis\textsl{#1}\ #3 \else \noindent\ForgetThis\textsl{#1}\ #2\ #3 \fi\medskip } \index{reference work} \RefArticle {\RevComma\Name[Greta]{\noexpand\textSC{Garbo}}} {} {(18 September 1905\,--\,15 April 1990) was a Swedish film actress during the 1920s and 1930s. \Name[Greta]{\noexpand\textSC{Garbo}}\dots} \RefArticle {\Name{\noexpand\textSC{Misora}, Hibari}} {(W:\,``\RevName\Name*{\noexpand\textSC{Misora}, Hibari}'';} {29 May 1937\,--\,24 June 1989) was a Japanese singer and actress noted for her positive message. \Name{\noexpand\textSC{Misora}, Hibari}\dots} \RefArticle {\RevComma\Name[Heinz]{\noexpand\textSC{R\"uhmann}}} {(\SubvertThis\ForceName \FName[Heinrich Wilhelm]{\noexpand\textSC{R\"uhmann}};} {7 March 1902\,--\,3 October 1994) was a German actor in over 100 films. \Name[Heinz]{\noexpand\textSC{R\"uhmann}}\dots} \section{Roman Names: Student Reference} % Global Boolean flags need to be defined only once. \newif\ifNoPraenomen \newif\ifNoCognomen \newif\ifNoGens \newif\ifNoAgnomen % Local Boolean flags need to be defined only once. \newif\ifXPrae \newif\ifXCogn \newif\ifXGens \newif\ifXAgno % Name variant macros need to be defined uniquely for each % name. First is Scipio. Second is Gracchus. \newcommand*\SCIPi {% \ifXGens Publius\else \ifXPrae Cornelius\else Publius Cornelius% \fi \fi } \newcommand*\SCIPii {% \ifXAgno Scipio\else Scipio Africanus% \fi } \newcommand*\TSemp {% \ifXGens Tiberius\else \ifXPrae Sempronius\else Tiberius Sempronius% \fi \fi } % We add the name data tag. \NameAddInfo[\noexpand\TSemp]{Gracchus} { (consul, 177 \textsc{bc})} % Although it is helpful to set everything up % In the preamble, it is not absolutely necessary. % Here we define the simpler set of formatting hooks % for Scipio, although the complex hooks will work % for both equally as well. \renewcommand*\NamesFormat[1] {% \ifNoPraenomen\XPraetrue\fi% \ifNoGens\XGenstrue\fi% \ifNoCognomen\XCogntrue\fi% \ifNoAgnomen\XAgnotrue\fi% #1% \global\NoPraenomenfalse% \global\NoGensfalse% \global\NoCognomenfalse% \global\NoAgnomenfalse% } \renewcommand*\MainNameHook[1] {% \ifNoPraenomen\XPraetrue\fi% \ifNoGens\XGenstrue\fi% \ifNoCognomen\XCogntrue\fi% \ifNoAgnomen\XAgnotrue\fi% #1% \global\NoPraenomenfalse% \global\NoGensfalse% \global\NoCognomenfalse% \global\NoAgnomenfalse% } \index{Roman names, student} \Scipio\ was born around 236 \textsc{bc} into the Scipiones branch of the Cornelii clan. \NoAgnomentrue\Scipio\ rose to military fame during the Second Punic War. Thereafter he was known as \Scipio. He flourished during the Egyptian reigns of \Name{Ptolemy, IV}[IV Philopator] and \Name{Ptolemy, V}[V Epiphanes], and the Syrian reigns of \Name{Seleucus, III}[III Ceraunus] and \Name{Antiochus, III}[III the Great]. % We make no change to \MainNameHook, but we do % change \NamesFormat to display any extant % name data tags. \renewcommand*\NamesFormat[1] {% \ifNoPraenomen\XPraetrue\fi% \ifNoGens\XGenstrue\fi% \ifNoCognomen\XCogntrue\fi% \ifNoAgnomen\XAgnotrue\fi% #1% \ifcsname\NameauthPattern!DB\endcsname \expandafter\csname\NameauthPattern!DB\endcsname% \fi \global\NoPraenomenfalse% \global\NoGensfalse% \global\NoCognomenfalse% \global\NoAgnomenfalse% } \TGrac\ served as tribune of the plebs in 184 \textsc{bc}. \NoGenstrue\STGrac\ was elected praetor for 180 \textsc{bc}, after which he was appointed governor of Hispania Citerior. serving with the rank of proconsul. In 177 \textsc{bc}, he was elected consul, again in 163 \textsc{bc}. \section{Roman Names: Scholarly Work} % Name variant macros need to be defined % uniquely for each name. \newcommand*\CSB {% \ifXGens \ifXAgno Scipio\else Scipio Barbatus\fi \else \ifXCogn Cornelius\else \ifXAgno Cornelius Scipio\else Cornelius Scipio Barbatus% \fi \fi \fi } \index{Roman names, scholar} \OScipio\ was born around 337 \textsc{bc} into the Scipiones branch of the Cornelii clan, one of the large patrician clans. \NoGenstrue\NoAgnomentrue\OScipio\ was one of the two elected consuls in 298 \textsc{bc} and served during the Third Samnite War. \section{Reference Work II} % Boolean flags; the first sets up headwords and the second % indicates that a non-Western form should not be reversed. \newif\ifHeadword \newif\ifAncientName % Sorting and tagging the names: % Adding name information: \NameAddInfo{Aristotle}{ (384--322 \textsc{bc})} \NameAddInfo[Charles]{\noexpand\textBF{Babbage}}{ (1791--1871)} \NameAddInfo{\noexpand\textUC{Kanade}, Takeo}{ (1945-- )} \NameAddInfo[Ada]{\noexpand\textIT{Lovelace}} { (Augusta Ada King, Countess of Lovelace [née Byron]; 1815--52)} % Redefining the formatting hooks: \makeatletter \renewcommand\NamesFormat[1] {% \ifHeadword \ifNameauthWestern \@nameauth@RevThisCommatrue% \bfseries \NameParser% \normalfont% \ifcsname\NameauthPattern!DB\endcsname \expandafter\csname\NameauthPattern!DB\endcsname% \fi \else \bgroup% \bfseries \NameParser% \unless\ifAncientName \normalfont; W:\AltOff\space \@nameauth@RevThistrue \NameParser% \fi \normalfont% \ifcsname\NameauthPattern!DB\endcsname \expandafter\csname\NameauthPattern!DB\endcsname% \fi \egroup% \fi \else \NameParser% \fi \global\Headwordfalse% \global\AncientNamefalse% } \makeatother \renewcommand\MainNameHook{\AltOff} % Define related macros: \newcommand\Headword{\Headwordtrue\ForgetThis} \renewcommand{\RefArticle}[2] {% \noindent\Headword #1 #2% \medskip } \index{reference work} \RefArticle{\AncientNametrue\Name{Aristotle}}{was the first to offer a system of logic, most notably syllogistic logic, that would become the basis for discrete states and circuitry of digital computers. \Name{Aristotle}\dots} \RefArticle{\Name[Charles]{\noexpand\textBF{Babbage}}}{designed and built the Difference Engine and began work on the Analytical Engine. \Name[Charles]{\noexpand\textBF{Babbage}}\dots} \RefArticle{\Name{\noexpand\textUC{Kanade}, Takeo}}{is one of the foremost pioneers in the field of computer vision. \Name{\noexpand\textUC{Kanade}, Takeo}\dots} \RefArticle{\Name[Ada]{\noexpand\textIT{Lovelace}}}{collaborated with \Name*[Charles]{\noexpand\textBF{Babbage}}* and wrote what some consider to be the first computer program for the Analytical Engine. \Name[Ada]{\noexpand\textIT{Lovelace}}\dots} \index{reference work} \section{Marginalia} % Global Boolean flags need to be defined only once. \newif\ifSpecialFN \newif\ifSpecialSN \newif\ifRevertSN % Name variant macros need to be defined % uniquely for each name. % For a long name, we want to use ``William'' in the text % and ``Wm.'' in the margin. \newcommand*\WM {% \ifSpecialFN Wm.\else William\fi } % The first surname use will be ``Shakespeare'', but ``the % Bard'' thereafter. We allow for alternate caps. % We can get ``Shakespeare'' thereafter by toggling a flag. \newcommand*\SHK {% \ifRevertSN \textSC{Shakespeare}\else \ifSpecialSN \noexpand\AltCaps{t}he Bard\else \textSC{Shakespeare}% \fi \fi } % Here is how we toggle that flag. \newcommand*\Revert{\RevertSNtrue} % 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] {% \RevertSNfalse\SpecialFNfalse\SpecialSNfalse% #1% \unless\ifinner \marginpar {% \footnotesize\raggedleft% \SpecialFNtrue\SpecialSNfalse% \NameParser% }% \fi \global\RevertSNfalse% } \renewcommand*\MainNameHook[1] {% \AltOff\SpecialFNfalse\SpecialSNtrue% #1% \unless\ifinner \unless\ifRevertSN \marginpar {% \footnotesize\raggedleft% \SpecialFNfalse\SpecialSNfalse% \NameParser% }% \fi \fi \global\RevertSNfalse% } \makeatother \index{special uses} \ForgetThis\Shak\ is the national poet of England in much the same way that \Name[Robert]{\textSC{Burns}} is that of Scotland. With the latter's rise of influence in the 1800s, \Revert\Shak\ became known as ``\Shak''. \section{Customization, Easy} \makeatletter \newcommand*\Fbox[1]{% \if@nameauth@DoAlt\protect\fbox{#1}\else#1\fi } \makeatother \renewcommand*\NamesFormat{} \renewcommand*\FrontNamesFormat{} \renewcommand*\MainNameHook{\AltOff} \renewcommand*\FrontNameHook{\AltOff} \index{customization, easy} \deSmet\ was a Jesuit missionary who arrived in North America in 1821 at the age of twenty, after a year of seminary education. \CapThis\deSmet\ was ordained in 1827 and worked among American Indian nations after 1837. We can show the forms \LdeSmet\ and \SdeSmet. \section{Customization, Complicated} \newif\ifFbox % Replaces \if@nameauth@DoAlt \newif\ifFirstCap % Replaces \if@nameauth@DoCaps \newif\ifInHook % Replaces \if@nameauth@InHook \Fboxtrue % Replaces \AltFormatActive % Alternate formatting macro definition \renewcommand*\Fbox[1]{% \ifFbox\protect\fbox{#1}\else#1\fi } % 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 \index{customization, complicated} \ForgetThis\deSmet\ was a Jesuit missionary who arrived in North America in 1821 at the age of twenty, after a year of seminary education. \CapThis\deSmet\ was ordained in 1827 and worked among American Indian nations after 1837. We can show the forms \LdeSmet\ and \SdeSmet. \newif\ifCaps % Replaces \if@nameauth@DoAlt \Capstrue % Replaces \AltFormatActive % Alternate formatting macro definition \renewcommand*\textSC[1]{\ifCaps\textsc{#1}\else#1\fi} % Redefinition of \AltCaps and \CapThis \renewcommand*\AltCaps[1]{% \ifInHook \ifFirstCap\MakeUppercase{#1}\else#1\fi \else #1% \fi } \renewcommand*\CapThis{\FirstCaptrue} \renewcommand*\NamesFormat[1] {\InHooktrue#1\global\FirstCapfalse} \renewcommand*\MainNameHook[1] {\Capsfalse\InHooktrue#1\global\FirstCapfalse} \let\FrontNamesFormat\Namesformat \let\FrontNameHook\MainNameHook \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. \renewcommand*\NamesFormat{} \newcommand*\FrontNamesFormat{} \renewcommand*\MainNameHook{} \renewcommand*\FrontNameHook{} \section{Customization, Complete} \makeatletter % Change the general-case name macro to show % a name in a framed, colored box. \newcommandx*\MyName[3][1=\@empty, 3=\@empty]{% \global\@nameauth@toksa\expandafter{#1}% \global\@nameauth@toksb\expandafter{#2}% \global\@nameauth@toksc\expandafter{#3}% \fcolorbox{black}{gray!25!white}{\@nameauth@Name[#1]{#2}[#3]}% } % Likewise change the macro for when names are forced long. \newcommandx*\MyLName[3][1=\@empty, 3=\@empty]{% \global\@nameauth@toksa\expandafter{#1}% \global\@nameauth@toksb\expandafter{#2}% \global\@nameauth@toksc\expandafter{#3}% \fcolorbox{black}{green!25!white}{\@nameauth@Name[#1]{#2}[#3]}% } % Likewise change the macro when personal names are desired. \newcommandx*\MyFName[3][1=\@empty, 3=\@empty]{% \global\@nameauth@toksa\expandafter{#1}% \global\@nameauth@toksb\expandafter{#2}% \global\@nameauth@toksc\expandafter{#3}% \fcolorbox{black}{yellow!25!white}{\@nameauth@Name[#1]{#2}[#3]}% } \makeatother % Change the formatting hooks, but do not use alternate. % formatting, which is separate from that above. \renewcommand*\NamesFormat[1]{\scshape#1} \renewcommand*\MainNameHook[1]{#1} % Change the naming macro hooks. \renewcommand*\NameauthName{\MyName} \renewcommand*\NameauthLName{\MyLName} \renewcommand*\NameauthFName{\MyFName} \index{customization, insane} \ForgetThis\Name[Adolf]{Harnack} was a theologian who stressed the Fatherhood of God and the brotherhood of man. \Name[Adolf]{Harnack} flourished in the early twentieth century. We also produce \Name*[Adolf]{Harnack} and \FName[Adolf]{Harnack}. \AltFormatInactive \makeatletter \renewcommand*\NameauthName{\@nameauth@Name} \renewcommand*\NameauthLName{\@nameauth@Name} \renewcommand*\NameauthFName{\@nameauth@Name} \makeatother \renewcommand*\NamesFormat{} \renewcommand*\MainNameHook{} \section{\protect\LaTeX\ Engines} We use \texttt{american} for the language; one should use one's own. We use Latin Modern. We could load \textsf{tikz} using \texttt{\textbackslash ifDoTikZ} to avoid crashing some \texttt{dvi} viewers in a \texttt{dvi}-only workflow. \index{\protect\LaTeX\ engines} \begin{quote}\small \begin{Verbatim} \IfFileExists{iftex.sty}{\usepackage{iftex}}{} \unless\ifdefined\RequireTUTeX \usepackage{ifxetex} \usepackage{ifluatex} \usepackage{ifpdf} \fi \newif\ifDoTikZ % Is loading TikZ okay? \ifxetex \usepackage{fontspec} \usepackage{polyglossia} \setdefaultlanguage{american} % Use own language \usepackage{tikz} \DoTikZtrue % PDF: yes TikZ okay. \else \ifluatex \ifpdf \usepackage{fontspec} \usepackage{polyglossia} \setdefaultlanguage{american} % Use own language \usepackage{tikz} \DoTikZtrue % PDF: yes TikZ okay. \else \IfFileExists{utf8-2018.def}{} {\usepackage[utf8]{inputenc}} \usepackage[TS1,T1]{fontenc} \usepackage[american]{babel} % Use own language \usepackage{lmodern} % Perhaps add \usepackage{tikz} with caveats. \fi \else \IfFileExists{utf8-2018.def}{} {\usepackage[utf8]{inputenc}} \usepackage[TS1,T1]{fontenc} \usepackage[american]{babel} % Use own language \usepackage{lmodern} \ifpdf \usepackage{tikz} \DoTikZtrue % PDF: yes TikZ okay. \fi \fi \fi \end{Verbatim} \end{quote} \newpage In the body text we can use something like the test below for:\quad \fbox{\ifxetex doing \texttt{pdf} things\else \ifpdf doing \texttt{pdf} things\else doing \texttt{dvi} things\fi \fi} \begin{quote}\small \begin{Verbatim} \ifxetex doing \texttt{pdf} things \else \ifpdf doing \texttt{pdf} things \else doing \texttt{dvi} things \fi \fi \end{Verbatim} \end{quote} The following equivalent conditional statements can help a macro or just the body text to work under multiple engines: \begin{quote}\small \begin{Verbatim} \ifxetex xelatex% \else \ifluatex \ifpdf lualatex (pdf)% \else lualatex (dvi)% \fi \else \ifpdf pdflatex% \else latex (dvi)% \fi \fi \fi \end{Verbatim} \begin{Verbatim} \unless\ifxetex \unless\ifluatex \ifpdf pdflatex% \else latex (dvi)% \fi \else \ifpdf lualatex (pdf)% \else lualatex (dvi)% \fi \fi \else xelatex% \fi \end{Verbatim} \end{quote} \section{Miscellaneous Tests: Spaces} Here we test to see if any unwanted spaces exist in macros that take name arguments. If everything is OK, two vertical bars should either immediately precede and follow the arguments, or have no space between them. This section also tests if all possible argument combinations work in most macros that take name arguments. We disable indexing here.\\ \IndexInactive \hbox to 0.7\textwidth{\Verb+\Name[FNN]{SNN,Affix}[Alternate]+\dotfill |\Name[FNN]{SNN,Affix}[Alternate]|}\par \hbox to 0.7\textwidth{\Verb+\Name*[FNN]{SNN,Affix}+\dotfill |\Name*[FNN]{SNN,Affix}|}\par \hbox to 0.7\textwidth{\Verb+\DropAffix\Name*[FNN]{SNN,Affix}+\dotfill |\DropAffix\Name*[FNN]{SNN,Affix}|}\par \hbox to 0.7\textwidth{\Verb+\Name[FNN]{SNN,Affix}+\dotfill |\Name[FNN]{SNN,Affix}|}\par \hbox to 0.7\textwidth{\Verb+\FName[FNN]{SNN,Affix}[Alternate]+\dotfill |\FName[FNN]{SNN,Affix}[Alternate]|}\par \hbox to 0.7\textwidth{\Verb+\FName[FNN]{SNN,Affix}+\dotfill |\FName[FNN]{SNN,Affix}|}\medskip \hbox to 0.7\textwidth{\Verb+\Name{SNN,Affix}[Alternate]+\dotfill |\Name{SNN,Affix}[Alternate]|}\par \hbox to 0.7\textwidth{\Verb+\Name*{SNN,Affix}+\dotfill |\Name*{SNN,Affix}|}\par \hbox to 0.7\textwidth{\Verb+\Name{SNN,Affix}+\dotfill |\Name{SNN,Affix}|}\par \hbox to 0.7\textwidth{\Verb+\FName{SNN,Affix}+\dotfill |\FName{SNN,Affix}|}\par \hbox to 0.7\textwidth{\Verb+\ForceFN\FName{SNN,Affix}[Alternate]+\dotfill |\ForceFN\FName{SNN,Affix}[Alternate]|}\par \hbox to 0.7\textwidth{\Verb+\ForceFN\FName{SNN,Affix}+\dotfill |\ForceFN\FName{SNN,Affix}|}\medskip \newpage \hbox to 0.7\textwidth{\Verb+\ForgetThis\Name{SNN}[Alternate]+\dotfill |\ForgetThis\Name{SNN}[Alternate]|}\par \hbox to 0.7\textwidth{\Verb+\Name*{SNN}[Alternate]+\dotfill |\Name*{SNN}[Alternate]|}\par \hbox to 0.7\textwidth{\Verb+\Name{SNN}[Alternate]+\dotfill |\Name{SNN}[Alternate]|}\par \hbox to 0.7\textwidth{\Verb+\FName{SNN}[Alternate]+\dotfill |\FName{SNN}[Alternate]|}\par \hbox to 0.7\textwidth{\Verb+\ForceFN\FName{SNN}[Alternate]+\dotfill |\ForceFN\FName{SNN}[Alternate]|}\medskip \hbox to 0.7\textwidth{\Verb+\IndexName[FNN]{SNN,Affix}[Alternate]+\dotfill |\IndexName[FNN]{SNN,Affix}[Alternate]|}\par \hbox to 0.7\textwidth{\Verb+\IndexName[FNN]{SNN,Affix}+\dotfill |\IndexName[FNN]{SNN,Affix}|}\par \hbox to 0.7\textwidth{\Verb+\IndexName{SNN,Affix}[Alternate]+\dotfill |\IndexName{SNN,Affix}[Alternate]|}\par \hbox to 0.7\textwidth{\Verb+\IndexName{SNN,Affix}+\dotfill |\IndexName{SNN,Affix}|}\par \hbox to 0.7\textwidth{\Verb+\IndexName{SNN}[Alternate]+\dotfill |\IndexName{SNN}[Alternate]|}\medskip \hbox to 0.7\textwidth{\Verb+\IndexRef[FNN]{SNN,Affix}[Alternate]{Target}+\dotfill |\IndexRef[FNN]{SNN,Affix}[Alternate]{Target}|}\par \hbox to 0.7\textwidth{\Verb+\IndexRef[FNN]{SNN,Affix}{Target}+\dotfill |\IndexRef[FNN]{SNN,Affix}{Target}|}\par \hbox to 0.7\textwidth{\Verb+\IndexRef{SNN,Affix}[Alternate]{Target}+\dotfill |\IndexRef{SNN,Affix}[Alternate]{Target}|}\par \hbox to 0.7\textwidth{\Verb+\IndexRef{SNN,Affix}{Target}+\dotfill |\IndexRef{SNN,Affix}{Target}|}\par \hbox to 0.7\textwidth{\Verb+\IndexRef{SNN}[Alternate]{Target}+\dotfill |\IndexRef{SNN}[Alternate]{Target}|}\medskip \hbox to 0.7\textwidth{\Verb+\ExcludeName[FNN]{SNN,Affix}[Alternate]+\dotfill |\ExcludeName[FNN]{SNN,Affix}[Alternate]|}\par \hbox to 0.7\textwidth{\Verb+\ExcludeName[FNN]{SNN,Affix}+\dotfill |\ExcludeName[FNN]{SNN,Affix}|}\par \hbox to 0.7\textwidth{\Verb+\ExcludeName{SNN,Affix}[Alternate]+\dotfill |\ExcludeName{SNN,Affix}[Alternate]|}\par \hbox to 0.7\textwidth{\Verb+\ExcludeName{SNN,Affix}+\dotfill |\ExcludeName{SNN,Affix}|}\par \hbox to 0.7\textwidth{\Verb+\ExcludeName{SNN}[Alternate]+\dotfill |\ExcludeName{SNN}[Alternate]|}\medskip \hbox to 0.7\textwidth{\Verb+\IncludeName[FNN]{SNN,Affix}[Alternate]+\dotfill |\IncludeName[FNN]{SNN,Affix}[Alternate]|}\par \hbox to 0.7\textwidth{\Verb+\IncludeName[FNN]{SNN,Affix}+\dotfill |\IncludeName[FNN]{SNN,Affix}|}\par \hbox to 0.7\textwidth{\Verb+\IncludeName{SNN,Affix}[Alternate]+\dotfill |\IncludeName{SNN,Affix}[Alternate]|}\par \hbox to 0.7\textwidth{\Verb+\IncludeName{SNN,Affix}+\dotfill |\IncludeName{SNN,Affix}|}\par \hbox to 0.7\textwidth{\Verb+\IncludeName{SNN}[Alternate]+\dotfill |\IncludeName{SNN}[Alternate]|}\medskip \hbox to 0.7\textwidth{\Verb+\IncludeName*[FNN]{SNN,Affix}[Alternate]+\dotfill |\IncludeName*[FNN]{SNN,Affix}[Alternate]|}\par \hbox to 0.7\textwidth{\Verb+\IncludeName*[FNN]{SNN,Affix}+\dotfill |\IncludeName*[FNN]{SNN,Affix}|}\par \hbox to 0.7\textwidth{\Verb+\IncludeName*{SNN,Affix}[Alternate]+\dotfill |\IncludeName*{SNN,Affix}[Alternate]|}\par \hbox to 0.7\textwidth{\Verb+\IncludeName*{SNN,Affix}+\dotfill |\IncludeName*{SNN,Affix}|}\par \hbox to 0.7\textwidth{\Verb+\IncludeName*{SNN}[Alternate]+\dotfill |\IncludeName*{SNN}[Alternate]|}\medskip \hbox to 0.7\textwidth{\Verb+\PretagName[FNN]{SNN,Affix}[Alternate]{Sort}+\dotfill |\PretagName[FNN]{SNN,Affix}[Alternate]{Sort}|}\par \hbox to 0.7\textwidth{\Verb+\PretagName[FNN]{SNN,Affix}{Sort}+\dotfill |\PretagName[FNN]{SNN,Affix}{Sort}|}\par \hbox to 0.7\textwidth{\Verb+\PretagName{SNN,Affix}[Alternate]{Sort}+\dotfill |\PretagName{SNN,Affix}[Alternate]{Sort}|}\par \hbox to 0.7\textwidth{\Verb+\PretagName{SNN,Affix}{Sort}+\dotfill |\PretagName{SNN,Affix}{Sort}|}\par \hbox to 0.7\textwidth{\Verb+\PretagName{SNN}[Alternate]{Sort}+\dotfill |\PretagName{SNN}[Alternate]{Sort}|}\medskip \hbox to 0.7\textwidth{\Verb+\TagName[FNN]{SNN,Affix}[Alternate]{Tag}+\dotfill |\TagName[FNN]{SNN,Affix}[Alternate]{Tag}|}\par \hbox to 0.7\textwidth{\Verb+\TagName[FNN]{SNN,Affix}{Tag}+\dotfill |\TagName[FNN]{SNN,Affix}{Tag}|}\par \hbox to 0.7\textwidth{\Verb+\TagName{SNN,Affix}[Alternate]{Tag}+\dotfill |\TagName{SNN,Affix}[Alternate]{Tag}|}\par \hbox to 0.7\textwidth{\Verb+\TagName{SNN,Affix}{Tag}+\dotfill |\TagName{SNN,Affix}{Tag}|}\par \hbox to 0.7\textwidth{\Verb+\TagName{SNN}[Alternate]{Tag}+\dotfill |\TagName{SNN}[Alternate]{Tag}|}\medskip \hbox to 0.7\textwidth{\Verb+\UntagName[FNN]{SNN,Affix}[Alternate]+\dotfill |\UntagName[FNN]{SNN,Affix}[Alternate]|}\par \hbox to 0.7\textwidth{\Verb+\UntagName[FNN]{SNN,Affix}+\dotfill |\UntagName[FNN]{SNN,Affix}|}\par \hbox to 0.7\textwidth{\Verb+\UntagName{SNN,Affix}[Alternate]+\dotfill |\UntagName{SNN,Affix}[Alternate]|}\par \hbox to 0.7\textwidth{\Verb+\UntagName{SNN,Affix}+\dotfill |\UntagName{SNN,Affix}|}\par \hbox to 0.7\textwidth{\Verb+\UntagName{SNN}[Alternate]+\dotfill |\UntagName{SNN}[Alternate]|}\medskip \hbox to 0.7\textwidth{\Verb+\NameAddInfo[FNN]{SNN,Affix}[Alternate]{Info}+\dotfill |\NameAddInfo[FNN]{SNN,Affix}[Alternate]{Info}|}\par \hbox to 0.7\textwidth{\Verb+\NameAddInfo[FNN]{SNN,Affix}{Info}+\dotfill |\NameAddInfo[FNN]{SNN,Affix}{Info}|}\par \hbox to 0.7\textwidth{\Verb+\NameAddInfo{SNN,Affix}[Alternate]{Info}+\dotfill |\NameAddInfo{SNN,Affix}[Alternate]{Info}|}\par \hbox to 0.7\textwidth{\Verb+\NameAddInfo{SNN,Affix}{Info}+\dotfill |\NameAddInfo{SNN,Affix}{Info}|}\par \hbox to 0.7\textwidth{\Verb+\NameAddInfo{SNN}[Alternate]{Info}+\dotfill |\NameAddInfo{SNN}[Alternate]{Info}|}\medskip \hbox to 0.7\textwidth{\Verb+\NameQueryInfo[FNN]{SNN,Affix}[Alternate]+\dotfill |\NameQueryInfo[FNN]{SNN,Affix}[Alternate]|}\par \hbox to 0.7\textwidth{\Verb+\NameQueryInfo[FNN]{SNN,Affix}+\dotfill |\NameQueryInfo[FNN]{SNN,Affix}|}\par \hbox to 0.7\textwidth{\Verb+\NameQueryInfo{SNN,Affix}[Alternate]+\dotfill |\NameQueryInfo{SNN,Affix}[Alternate]|}\par \hbox to 0.7\textwidth{\Verb+\NameQueryInfo{SNN,Affix}+\dotfill |\NameQueryInfo{SNN,Affix}|}\par \hbox to 0.7\textwidth{\Verb+\NameQueryInfo{SNN}[Alternate]+\dotfill |\NameQueryInfo{SNN}[Alternate]|}\medskip \newpage \hbox to 0.7\textwidth{\Verb+\NameClearInfo[FNN]{SNN,Affix}[Alternate]+\dotfill |\NameClearInfo[FNN]{SNN,Affix}[Alternate]|}\par \hbox to 0.7\textwidth{\Verb+\NameClearInfo[FNN]{SNN,Affix}+\dotfill |\NameClearInfo[FNN]{SNN,Affix}|}\par \hbox to 0.7\textwidth{\Verb+\NameClearInfo{SNN,Affix}[Alternate]+\dotfill |\NameClearInfo{SNN,Affix}[Alternate]|}\par \hbox to 0.7\textwidth{\Verb+\NameClearInfo{SNN,Affix}+\dotfill |\NameClearInfo{SNN,Affix}|}\par \hbox to 0.7\textwidth{\Verb+\NameClearInfo{SNN}[Alternate]+\dotfill |\NameClearInfo{SNN}[Alternate]|}\medskip \hbox to 0.7\textwidth{\Verb+\ForgetName[FNN]{SNN,Affix}[Alternate]+\dotfill |\ForgetName[FNN]{SNN,Affix}[Alternate]|}\par \hbox to 0.7\textwidth{\Verb+\ForgetName[FNN]{SNN,Affix}+\dotfill |\ForgetName[FNN]{SNN,Affix}|}\par \hbox to 0.7\textwidth{\Verb+\ForgetName{SNN,Affix}[Alternate]+\dotfill |\ForgetName{SNN,Affix}[Alternate]|}\par \hbox to 0.7\textwidth{\Verb+\ForgetName{SNN,Affix}+\dotfill |\ForgetName{SNN,Affix}|}\par \hbox to 0.7\textwidth{\Verb+\ForgetName{SNN}[Alternate]+\dotfill |\ForgetName{SNN}[Alternate]|}\medskip \Verb+\LocalNames+\LocalNames\par \hbox to 0.7\textwidth{\Verb+\SubvertName[FNN]{SNN,Affix}[Alternate]+\dotfill |\SubvertName[FNN]{SNN,Affix}[Alternate]|}\par \hbox to 0.7\textwidth{\Verb+\SubvertName[FNN]{SNN,Affix}+\dotfill |\SubvertName[FNN]{SNN,Affix}|}\par \hbox to 0.7\textwidth{\Verb+\SubvertName{SNN,Affix}[Alternate]+\dotfill |\SubvertName{SNN,Affix}[Alternate]|}\par \hbox to 0.7\textwidth{\Verb+\SubvertName{SNN,Affix}+\dotfill |\SubvertName{SNN,Affix}|}\par \hbox to 0.7\textwidth{\Verb+\SubvertName{SNN}[Alternate]+\dotfill |\SubvertName{SNN}[Alternate]|}\par \Verb+\GlobalNames+\GlobalNames\medskip \hbox to 0.7\textwidth{\Verb+\IfMainName[FNN]{SNN,Affix}[Alternate]{Y}{N}+\dotfill |\IfMainName[FNN]{SNN,Affix}[Alternate]{Y}{N}|}\par \hbox to 0.7\textwidth{\Verb+\IfMainName[FNN]{SNN,Affix}{Y}{N}+\dotfill |\IfMainName[FNN]{SNN,Affix}{Y}{N}|}\par \hbox to 0.7\textwidth{\Verb+\IfMainName{SNN,Affix}[Alternate]{Y}{N}+\dotfill |\IfMainName{SNN,Affix}[Alternate]{Y}{N}|}\par \hbox to 0.7\textwidth{\Verb+\IfMainName{SNN,Affix}{Y}{N}+\dotfill |\IfMainName{SNN,Affix}{Y}{N}|}\par \hbox to 0.7\textwidth{\Verb+\IfMainName{SNN}[Alternate]{Y}{N}+\dotfill |\IfMainName{SNN}[Alternate]{Y}{N}|}\medskip \hbox to 0.7\textwidth{\Verb+\IfFrontName[FNN]{SNN,Affix}[Alternate]{Y}{N}+\dotfill |\IfFrontName[FNN]{SNN,Affix}[Alternate]{Y}{N}|}\par \hbox to 0.7\textwidth{\Verb+\IfFrontName[FNN]{SNN,Affix}{Y}{N}+\dotfill |\IfFrontName[FNN]{SNN,Affix}{Y}{N}|}\par \hbox to 0.7\textwidth{\Verb+\IfFrontName{SNN,Affix}[Alternate]{Y}{N}+\dotfill |\IfFrontName{SNN,Affix}[Alternate]{Y}{N}|}\par \hbox to 0.7\textwidth{\Verb+\IfFrontName{SNN,Affix}{Y}{N}+\dotfill |\IfFrontName{SNN,Affix}{Y}{N}|}\par \hbox to 0.7\textwidth{\Verb+\IfFrontName{SNN}[Alternate]{Y}{N}+\dotfill |\IfFrontName{SNN}[Alternate]{Y}{N}|}\medskip \hbox to 0.7\textwidth{\Verb+\SeeAlso\IndexRef[FNN]{SNN,Affix}{Target}+\dotfill |\SeeAlso\IndexRef[FNN]{SNN,Affix}{Target}|}\par \hbox to 0.7\textwidth{\Verb+\ExcludeName{SNN,Affix}+\dotfill |\ExcludeName{SNN,Affix}|}\par \hbox to 0.7\textwidth{\Verb+\IfAKA[FNN]{SNN,Affix}[Alternate]{Y}{N}{X}+\dotfill |\IfAKA[FNN]{SNN,Affix}[Alternate]{Y}{N}{X}|}\par \hbox to 0.7\textwidth{\Verb+\IfAKA[FNN]{SNN,Affix}{Y}{N}{X}+\dotfill |\IfAKA[FNN]{SNN,Affix}{Y}{N}{X}|}\par \hbox to 0.7\textwidth{\Verb+\IfAKA{SNN,Affix}[Alternate]{Y}{N}{X}+\dotfill |\IfAKA{SNN,Affix}[Alternate]{Y}{N}{X}|}\par \hbox to 0.7\textwidth{\Verb+\IfAKA{SNN,Affix}{Y}{N}{X}+\dotfill |\IfAKA{SNN,Affix}{Y}{N}{X}|}\par \hbox to 0.7\textwidth{\Verb+\IfAKA{SNN}[Alternate]{Y}{N}{X}+\dotfill |\IfAKA{SNN}[Alternate]{Y}{N}{X}|}\medskip \hbox to \textwidth{\Verb+\AKA[FNN1]{SNN1,Affix1}[FNN2]{SNN2,Affix2}[Alternate2]+\dotfill |\AKA[FNN1]{SNN1,Affix1}[FNN2]{SNN2,Affix2}[Alternate2]|}\par \hbox to \textwidth{\Verb+\AKA[FNN1]{SNN1,Affix1}[FNN2]{SNN2,Affix2}+\dotfill |\AKA[FNN1]{SNN1,Affix1}[FNN2]{SNN2,Affix2}|}\par \hbox to \textwidth{\Verb+\DropAffix\AKA[FNN1]{SNN1,Affix1}[FNN2]{SNN2,Affix2}+\dotfill |\DropAffix\AKA[FNN1]{SNN1,Affix1}[FNN2]{SNN2,Affix2}|}\par \hbox to \textwidth{\Verb+\AKA*[FNN1]{SNN1,Affix1}[FNN2]{SNN2,Affix2}[Alternate2]+\dotfill |\AKA*[FNN1]{SNN1,Affix1}[FNN2]{SNN2,Affix2}[Alternate2]|}\par \hbox to \textwidth{\Verb+\AKA*[FNN1]{SNN1,Affix1}[FNN2]{SNN2,Affix2}+\dotfill |\AKA*[FNN1]{SNN1,Affix1}[FNN2]{SNN2,Affix2}|}\medskip \hbox to \textwidth{\Verb+\AKA[FNN1]{SNN1,Affix1}{SNN3,Affix3}[Alternate3]+\dotfill |\AKA[FNN1]{SNN1,Affix1}{SNN3,Affix3}[Alternate3]|}\par \hbox to \textwidth{\Verb+\AKA[FNN1]{SNN1,Affix1}{SNN3,Affix3}+\dotfill |\AKA[FNN1]{SNN1,Affix1}{SNN3,Affix3}|}\par \hbox to \textwidth{\Verb+\AKA*[FNN1]{SNN1,Affix1}{SNN3,Affix3}+\dotfill |\AKA*[FNN1]{SNN1,Affix1}{SNN3,Affix3}|}\par \hbox to \textwidth{\Verb+\ForceFN\AKA*[FNN1]{SNN1,Affix1}{SNN3,Affix3}[Alternate3]+\dotfill |\ForceFN\AKA*[FNN1]{SNN1,Affix1}{SNN3,Affix3}[Alternate3]|}\par \hbox to \textwidth{\Verb+\ForceFN\AKA*[FNN1]{SNN1,Affix1}{SNN3,Affix3}+\dotfill |\ForceFN\AKA*[FNN1]{SNN1,Affix1}{SNN3,Affix3}|}\medskip \hbox to \textwidth{\Verb+\AKA[FNN1]{SNN1,Affix1}{SNN4}[Alternate4]+\dotfill |\AKA[FNN1]{SNN1,Affix1}{SNN4}[Alternate4]|}\par \hbox to \textwidth{\Verb+\AKA*[FNN1]{SNN1,Affix1}{SNN4}[Alternate4]+\dotfill |\AKA*[FNN1]{SNN1,Affix1}{SNN4}[Alternate4]|}\par \hbox to \textwidth{\Verb+\ForceFN\AKA*[FNN1]{SNN1,Affix1}{SNN4}[Alternate4]+\dotfill |\ForceFN\AKA*[FNN1]{SNN1,Affix1}{SNN4}[Alternate4]|}\medskip \phantomsection \addcontentsline{toc}{section}{Index of Persons} \printindex[per] \renewcommand\indexname{Index of Subjects} \phantomsection \addcontentsline{toc}{section}{Index of Subjects} \printindex \end{document} %examplesvb % \endinput