% \iffalse meta-comment % % Copyright (C) 2024 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 (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 | Cygwin and Windows | Not tested; not recommended | Not tested; not recommended | | WSL | WSL Linux packages | Yes1 | Yes5 | | WSL | MikTeX (Windows) | Yes1, 3 | No;4 do manually | | WSL | TeXlive (Windows) | Not tested; likely1 | Not tested; do manually | | WSL | WSL and Windows | Not tested; not recommended | Not tested; not recommended | | WSL/Cyg | WSL and Cygwin | Not tested; not recommended | Not tested; not recommended | | GNUWin | any (Windows) | Not tested; not recommended | Not tested; not recommended | 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. If one desires a clean build that is followed by an install, 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 2023 and 2017) and Windows 10 (MikTeX using shells from both Cygwin and WSL). The tests using TL 2017 include my published book manuscript, *Breath of God, Yet Work of Man: Scripture, Philosophy, Dialogue, and Conflict*, with Dr. Albert B. Collver III. * The CTAN release was created with vanilla TL 2023 on Pop! OS. The most recent `equivs` file was used to meet package equivalences. See also [this page](https://tug.org/texlive/debian.html). * TeXlive 2023 and TL 2017 are managed on Pop! OS using [tl-switch](https://github.com/ServusCarolus/tl-switch). * 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`, also includes `compat.tex`; they should be in the same directory when compiled. The examples document should be enough to illustrate various non-trivial features of this package. It includes most of the longer examples in the manual, edited to fit together in a single document. It also includes other material and tests. In addition to this file, a special run of `nameauth.dtx` that defines the macro `\NameauthDoTestFiles` will generate many separate test files. Normally they are written out to `nameauth.tmp` and read in again as verbatim text. They are not included in the package archive by default in order to minimize clutter. 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`. * If one wants to change engines and re-test the file, type `make exclean`. * To create `examples.pdf` with other LaTeX engines, one can do the following: make examples ENGINE=xelatex make examples ENGINE=lualatex make examples ENGINE=dvilualatex make examples ENGINE=latex * To generate additional test files, type `make tests`. This will produce many test files numbered by chapter and example within that chapter from the `nameauth.dtx` file. By default it will compile all of the test files using `pdflatex`. * If one wants to change engines and re-test the files, type `make testclean`. * One can add the value of ENGINE: make tests ENGINE=xelatex make tests ENGINE=lualatex make tests ENGINE=dvilualatex make tests ENGINE=latex * 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 first 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 first 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 Version 4.0 switches from `xargs` and `suffix` to `xparse`. Should any modifications still require `xargs` and `suffix`, one can use the `oldargs` package option. Improvements in version 4.0 include: * Change to `xparse`, which increases power and flexibility going forward. * Further changes to the manual that make it more readable and consistent. Version 3.7 remains here: [style](https://www.tug.org/svn/texlive/branches/branch2022.final/Master/texmf-dist/tex/latex/nameauth/), [docs](https://www.tug.org/svn/texlive/branches/branch2022.final/Master/texmf-dist/doc/latex/nameauth/), and [source](https://www.tug.org/svn/texlive/branches/branch2022.final/Master/texmf-dist/source/latex/nameauth/). Improvements in version 3.7 include: * Rejection of stale assumptions that had built up over time, based either on initial ignorance or on features that have since changed in LaTeX. * The examples file contains some tests that used to be in the documentation. * Major rewrite of documentation. * The table of contents better frflects scope and sequence. * The package itself has been reorganized to follow the same scope and sequence as the documentation. * Several macros have been optimized, leading to simpler and cleaner designs that are easier to debug. Additional bug fixes ensure stability, * Name arguments shown in package warnings are detokenized in order to prevent potential errors. # 8. Copyright Copyright (C) 2024 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) 2024 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> [2024/02/09 4.0 Name authority mechanism for consistency in text and index] % % %<*driver> %^^A %%%%%%%%%%%%% Stuff Needed in the Document Preamble %%%%%%%%%%%%%%%%% \documentclass[11pt]{ltxdoc} %^^A %%%%% General layout %%%%% %^^A Set up page layout to fit both letter and DIN A4. \usepackage[paperheight=279.4mm,paperwidth=210mm, textheight=239.4mm,textwidth=140mm, right=20mm,marginparwidth=40mm,nohead]{geometry} %^^A Permit horizontal boxes to be overfull. \hfuzz=3pt %^^A Define negative skip values if needed. \newcommand\negsmallskip{\vspace{-\smallskipamount}} \newcommand\negmedskip{\vspace{-\medskipamount}} \newcommand\negbigskip{\vspace{-\bigskipamount}} %^^A Redefine emphasis in the body text because italic has dedicated uses. \let\oldemph\emph \let\emph\textbf %^^A %%%%% Detecting LaTeX engine used %%%%% %^^A Since we only use pdflatex to make the documentation, %^^A this section is not as much of a big deal as it used to be. %^^A We still use these macros for some detection examples. %^^A We need etoolbox for this functionality. \usepackage{etoolbox} %^^A Provide a macro to check against latex versions and set a flag. %^^A This must be done in the document preamble. %^^A We use the date 2018/10/05 because that is when unicode %^^A processing changed for the better. %^^A We use the date 2018/04/30 because that is when xparse %^^A added the ! modifier. \makeatletter \@ifl@t@r\fmtversion{2018/10/05}{\def\nameauthltx{}}{} \@ifl@t@r\fmtversion{2018/04/30}{\def\nameauthxp{}}{} \makeatother %^^A %%%%% Set up fonts and typography %%%%% %^^A Again, this is specific to our use of pdflatex. %^^A We do not load inputenc unless we are using an old distro. \IfFileExists{utf8-2018.def}{}{\usepackage[utf8]{inputenc}} \usepackage[LGR,TS1,T1]{fontenc} %^^A We load textcomp for backward compatibility. \usepackage{textcomp} %^^A We demonstrate hyphenation only with English and German. %^^A Otherwise we don't hyphenate any other languages. \usepackage[ngerman,latin,polutonikogreek,american]{babel} \newcommand\de[1]{\foreignlanguage{ngerman}{#1}} \newcommand{\la}[1]{\foreignlanguage{latin}{#1}} \newcommand{\el}[1]{\foreignlanguage{polutonikogreek}{#1}} %^^A The Latin Modern font gives us the glyphs that we need. \usepackage{lmodern} %^^A This bit is for an example that involves accents and names. \usepackage{newunicodechar} \DeclareTextSymbolDefault{\textlongs}{TS1} \DeclareTextSymbol{\textlongs}{TS1}{115} \newunicodechar{ſ}{\textlongs} %^^A Load the dangerous bend symbol and microtypography.. \usepackage{manfnt} \usepackage{microtype} %^^A Do not automatically put extra space after a full stop. \frenchspacing %^^A %%%%% Set up specific document elements %%%%% %^^A ----- TOC and index ----- %^^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 We do not use \DisableCrossrefs \CodelineIndex \RecordChanges %^^A ----- Color and graphical diagram elements ----- %^^A Color helps categorize information. \usepackage{xcolor} \colorlet{nared}{red!60!black} \colorlet{nagreen}{green!35!black} \colorlet{nablue}{blue!50!black} \colorlet{nabrown}{brown!50!black} \colorlet{naslate}{cyan!45!black} \colorlet{nagrey}{black!7!white} %^^A Use color for yes/no indicators in tables. \newcommand\NO{\bgroup \color{black!20!white}\lower 0.075ex\hbox{\rule{1.5ex}{1.5ex}}\egroup} \newcommand\YES{\bgroup \color{black!80!white}\lower 0.075ex\hbox{\rule{1.5ex}{1.5ex}}\egroup} %^^A Diagrams \usepackage{tikz} \usepackage{tcolorbox} %^^A Set basic format for tcolorboxes drawn by TikZ. \tcbset{fonttitle=\bfseries\sffamily,box align=top,lower separated=false} %^^A ----- Hyperlinks and URLs ----- %^^A Have documentation with hyperlinks \usepackage[numbered]{hypdoc} %^^A Change URL color \hypersetup{urlcolor=violet} %^^A ----- Tables, lists, quotes, center ----- \usepackage{booktabs} \usepackage{colortbl} \usepackage[inline]{enumitem} \setlist{rightmargin=\leftmargin,itemsep=0pt} %^^A Make default font small for quote and center environments \apptocmd{\quote}{\small}{}{} \apptocmd{\center}{\small}{}{} %^^A ----- Verbatim environments ----- %^^A Let verbatim environments be fancy. \usepackage{fancyvrb} %^^A Define fancyvrb defaults. \fvset{gobble=2,numbers=left,fontsize=\small} %^^A ----- Font debugging; only for dev use ----- %^^A These two macros help track down any unintended changes to font sizes. %^^A One can use these only once each. \let\savegraf\everypar \makeatletter \newcommand\FontDebugStart {%^^A \let\oldep\everypar%^^A \newtoks\everypar%^^A \oldep{\the\everypar \llap{\color{red}\hbox to \marginparwidth {\f@size\hfill}}}%^^A } \newcommand\FontDebugStop {%^^A \let\oldep\savegraf%^^A \oldep{\the\everypar}%^^A } \makeatother %^^A ----- Various text elements ----- %^^A Show a ``dangerous bend'' in the margin. \newcommand*\Warn {%^^A \unless\ifinner {\marginpar{\raggedleft\strut\small\raise0.7ex\hbox{\dbend}}}%^^A \fi } %^^A Put information in the margin. \newcommand*\Info[1] {%^^A \unless\ifinner {\marginpar{\raggedleft\footnotesize#1}}%^^A \fi } \newcommand\Same {\Info{Same name patterns\break and index entries\break as above.}} %^^A Show a name pattern in margin. \newcommand*\PatInfo[1] {%^^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}\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 \begin{tcolorbox}[colback=white,colframe=darkgray]%^^A \begingroup\begin{tabular}{@{}ll@{}} \else \begin{tcolorbox}[colback=white,colframe=darkgray, adjusted title={\bfseries\hfil #1}]%^^A \begingroup\begin{tabular}{@{}ll@{}} \fi } {\end{tabular}\endgroup\end{tcolorbox}\medskip} %^^A Print a quote and the source. \renewcommand{\hrulefill}{% \leavevmode\leaders\hrule height 1.5pt\hfill\kern0pt } \newenvironment{Quote}[1] {%^^A \def\QuoteName{#1}%^^A \vfill\noindent\hfil\hbox to 0.9\textwidth{\hrulefill} \begin{quote}} {\negmedskip\end{quote}\begin{quote}\hfill---\QuoteName\end{quote}} %^^A Used for one or more examples \newenvironment{Block} {%^^A \begin{quote} \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 appearing in both text and index, fix any concerns about macro expansion by using \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}} \newcommand\UseB{\leavevmode\hbox to 5em{\hfill}} %^^A ----- Names, the reason for it all ----- %^^A Include specifically the current version of the package. \usepackage{\jobname}[2024/02/09] %^^A Set up the ``actual'' character \IndexActual{=} %^^A Redefine name formatting for this manual. \renewcommand*\FrontNamesFormat[1]{\color{red}\sffamily #1} \renewcommand*\FrontNameHook[1]{\color{darkgray}\sffamily #1} \renewcommand*\NamesFormat[1]{\color{blue}\sffamily #1} \renewcommand*\MainNameHook[1]{\sffamily #1} %^^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 angelicus}}{Doctor angelicus} \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[Leif]{Erikson}{|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}{ the Great, 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[Frenec]{Liszt}{\dag|hyperpage} \TagName[Titus]{Livius}{|hyperpage} \TagName{Llywelyn, ap Gruffudd}{, prince|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{3388} % % \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} % \changes{4.0}{2024/02/09}{Improve manual, \texttt{Readme.md}, \texttt{compat.tex}} % % \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, % \NewDocumentCommand, \newenvironment, \newif, % \nobreakspace, \PackageError, \PackageWarning, % \ProcessOptions, \relax, \renewcommand, % \RequirePackage, \scshape, \textbackslash, \uppercase} % %^^A %%%%%%%%%%%%%%% Macros That Must Be Defined Here %%%%%%%%%%%%%%%%%%%% % %^^A Lengths to size tcboxes % % \newlength{\nameboxi} % \newlength{\nameboxii} % \newlength{\nameboxiii} % %^^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 instances. % \end{abstract} % %^^A %%%%%%%%%%%%%%%%%%%%%%%%%%%%%% TOC %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % % \begingroup % \small % \hypertarget{TOC}{}^^A % \tableofcontents % \endgroup % % \begin{InfoBox}[Disclaimer] % This manual mentions names of historical figures both living and deceased. We intend to use all names herein with respect, for teaching purposes only, and never express or imply any disrespect or bias. % \end{InfoBox} % % \begin{InfoBox}[Compatibility] % Starting with version 4.0, \textsf{nameauth} uses \textsf{xparse} for starred macros and name arguments. Benefits include better macro design, more control over arguments, less code duplication, and better customization. % \begin{itemize} % \item Use with a pre-2017 \TeX\ distribution might cause occasional errors. See also Sections~\ref{sec:FinalOptargs}, \ref{sec:ChangeParse} and~\ref{sec:CompatON}. % \item Older user customizations using \textsf{xargs} may still work with the \texttt{oldargs} option. See Sections~\ref{sec:OptionCompat} and~\ref{sec:ChangeParse}. % \end{itemize} % If one should require version 3.7, see section 7 of \texttt{README.md}. % \end{InfoBox} % % \begin{InfoBox}[Fair Use] % Other works quoted herein either are in the public domain or they are copyrighted works cited under the terms of fair use, to which the present author claims no copyright. The purpose is to show the power of words and names. % \end{InfoBox} % % \begin{Quote}{\Name[Leonard]{Bernstein}\break % \hbox{}\hfill ``What Makes Opera Grand?'', \textit{Vogue} % (December 1958)} % \textls[-15]{Any great work of art \dots revives and readapts time and space, and the measure of its success is the extent to which it makes you an inhabitant of that world\,---\,the extent to which it invites you in and lets you breathe its strange, special air.}^^A % \index{creatives, quotes of\noexpand\string|hyperpage} % \end{Quote} % % \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. Books can contain hundreds of names and index entries. The \textsf{nameauth} package assists academic and business writing to minimize the work of managing many names: % % \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 similar information in \textit{The Chicago Manual of Style} (15\textsuperscript{th} ed., Chicago: Chicago UP, 2003, 309f., 755f.) or newer editions; referenced as [\hypertarget{Chicago}{Chicago}]. % % \subsection{Simple Example} % \label{sec:QuickExample} % \begingroup % \renewcommand{\NamesFormat}{} % \renewcommand{\MainNameHook}{} % % We begin with an excerpt from a biography written by \Name[Charles W.]{Chesnutt}[Charles Waddell], a prominent African-American author at the turn of the twentieth century.\footnote{\Name[Charles W.]{Chesnutt}, \textit{Frederick Douglass} (Boston: Small, Maynard, 1899). See also \href{https://docsouth.unc.edu/neh/chesnutt/summary.html} {\bfseries this web page}.} % We create a new document, use only the default \textsf{nameauth} options, and create no extra formatting for names (cf. Section~\ref{sec:Formatting}). % % The \texttt{nameauth} environment (Section~\ref{sec:QuickUIStart}) in the preamble resembles a \texttt{tabular} with four columns. In column one we define the naming macros. In columns two and three we define the names that the macros will display. We leave column four empty. % % We use \cmd{\Forgetname} (Section~\ref{sec:NameControl}) in Group 2 to ``forget'' about the names in Group 1. When we reorder the statements, the names change form automatically. % % \ifdefined\NameauthDoTestFiles \edef\NameauthTestFile{test01_01.tex}\else % \edef\NameauthTestFile{\jobname.tmp}\fi % % \begin{VerbatimOut}{\NameauthTestFile} % \documentclass{article} % \input{compat.tex} % Included with nameauth; example file aids % % compatibility across different LaTeX versions and engines. % \usepackage{makeidx} % \usepackage{nameauth} % \usepackage[inline]{enumitem} % \makeindex % % \begin{nameauth} % % Col. 1 Col. 2 Col. 3 Col. 4 % \< Doug & Frederick & Douglass & > % \< Bailey & Betsey & Bailey & > % \end{nameauth} % % \begin{document} % % \textbf{Group 1}\\ % \begin{enumerate*} % \item[\textbf{1.}] \Doug\ rose to eminence by sheer force % of character and talents that neither slavery nor caste % proscription could crush. % \item[\textbf{2.}] \Doug's early life is perhaps the most % complete indictment of the slave system ever presented at % the bar of public opinion. % \item[\textbf{3.}] \Doug\ was born in February, l8l7. His % earliest memories centered around the cabin of his % grandmother, \Bailey. % \end{enumerate*} % % \textbf{Group 2}\\ % \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} % \VerbatimInput[gobble=0]{\NameauthTestFile} % % \textbf{Group 1}\\ % \begin{enumerate*} % \item[\textbf{1.}] \Doug\ rose to eminence by sheer force % of character and talents that neither slavery nor caste % proscription could crush. % \item[\textbf{2.}] \Doug's early life is perhaps the most % complete indictment of the slave system ever presented at % the bar of public opinion. % \item[\textbf{3.}] \Doug\ was born in February, l8l7. His % earliest memories centered around the cabin of his % grandmother, \Bailey. % \end{enumerate*} % % \textbf{Group 2}\\ % \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} % % \endgroup % % \begin{Quote}{\ForgetThis\Doug\break % \hbox{}\hfill motto, \textit{The North Star} (Rochester, NY, 1847)} % Right Is of No Sex\,---\,Truth Is of No Color\,---\,God Is the Father % of Us All, and All We Are Brethren.\negmedskip^^A % \index{north star, concept of\noexpand\string|hyperpage}^^A % \index{civil rights leaders, quotes of\noexpand\string|hyperpage} % \end{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*{\hfil 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*{\hfil Scope and Sequence} % % The table of contents indicates what topics are covered, the simpler and frequent to the complex and infrequent. Later topics require knowledge from multiple sections. The end of each major section includes a return link to the table of contents. % % \subsubsection*{\hfil Key Concepts} % % Starting in Section~\ref{sec:BasicStart}, we use debugging macros to show \emph{name control patterns} in the margins (Section~\ref{sec:NamePatterns}). These patterns are the key to how names work in \textsf{nameauth}. Through Section~\ref{sec:NameMedieval} we show \emph{basic index entries} in the margins in order to illustrate the things for which one should look when debugging. % % \subsubsection*{\hfil 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*{\hfil Example Files} % % The files \texttt{examples.tex} and \texttt{compat.tex} are located with this manual. For generating package testing files, see \texttt{README.md}, also located with this manual. % % \vfill % % \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. % The rest of the manual requires these to be understood. % % \subsubsection{Name Arguments} % \label{sec:NameArgs} % % Below we show how familiar categories of names map to name arguments in the appropriate macros, as defined by the current syntax. We use the excellent advice in [\hyperlink{Mulvany}{Mulvany}, 152--82] and [\hyperlink{Chicago}{Chicago}], adapting them for use in \LaTeX. % \medskip % % \begingroup\small % \setbox0\hbox{Family / clan name\ } % \global\setlength{\nameboxi}{\wd0} % \setbox0\hbox{nomen / cognomen\ } % \global\setlength{\nameboxii}{\wd0} % \setbox0\hbox{notable attribute\ } % \global\setlength{\nameboxiii}{\wd0} % \endgroup % % \noindent\begin{tcolorbox}[colframe=naslate, % adjusted title={\large Western Name: % \oarg{FNN}\marg{SNN, Affix}\oarg{Alternate}}] % \centering\small^^A %^^A % \tcbox[equal height group=A,on line,tikznode,colback=white, % adjusted title={\centering\bfseries\sffamily Forename(s):\meta{FNN}}] % {\hbox to \nameboxi {\hfil Personal name(s):\hfil}\\ % \textit{baptismal name}\\ % \textit{Christian name}\\ % \textit{multiple names}\\ % \textit{praenomen}\footnotemark}\hfill^^A %^^A % \tcbox[equal height group=A,on line,tikznode,colback=white, % adjusted title={\bfseries\sffamily Surname(s):\meta{SNN}}] % {\hbox to \nameboxii {\hfil Family name:\hfil}\\ % \textit{of father, mother}\\ % \textit{ancestor, vocation}\\ % \textit{origin, region}\\ % \textit{nomen\,/\,cognomen}\\ % \textit{patronym}}\hfill^^A %^^A % \tcbox[equal height group=A,on line,tikznode,colback=white,colframe=nared, % adjusted title={\bfseries\sffamily Qualifier:\meta{Affix}}] % {\hbox to \nameboxiii {\hfil Sobriquet\,/\,title:\hfil}\\ % \textit{Sr., Jr., III\dots}\\ % \textit{notable attribute}\\ % \textit{origin, region}} % % \begin{tcolorbox}[colback=white,colframe=nared, % adjusted title={\bfseries\sffamily Alias:\meta{Alternate}}] % \centering Replaces \meta{FNN} only in the text. % \end{tcolorbox} % % \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={\large ``Native'' Eastern Name}: % \marg{SNN, Affix}\oarg{Alternate}] % \centering\small^^A %^^A % \tcbox[equal height group=B,on line,tikznode,colback=white, % adjusted title={\bfseries\sffamily Family:\meta{SNN}}] % {\hbox to \nameboxi {\hfil Family\,/\,clan name\hfil}}\hfill^^A %^^A % \tcbox[equal height group=B,on line,tikznode,colback=white, % adjusted title={\bfseries\sffamily Personal:\meta{Affix}}] % {\hbox to \nameboxii {\hfil Usually one name\hfil}}\hfill^^A %^^A % \tcbox[equal height group=B,on line,tikznode,colback=white,colframe=nared, % adjusted title={\bfseries\sffamily Alias:\meta{Alternate}}] % {\hbox to \nameboxiii {\hfil Replaces \meta{Affix}\hfil}\\ % only in text.\footnotemark} % \end{tcolorbox} % \footnotetext{The obsolete syntax uses \meta{Alternate} instead of % \meta{Affix} for a personal name (Section~\ref{sec:Obsolete}).} % % \begin{tcolorbox}[colframe=naslate, % adjusted title={\large Royal/Medieval/Ancient Name}: % \marg{SNN, Affix}\oarg{Alternate}] % \centering\small^^A %^^A % \tcbox[equal height group=C,on line,tikznode,colback=white, % adjusted title={\bfseries\sffamily Personal:\meta{SNN}}] % {\hbox to \nameboxi {\hfil Given name(s)\hfil}\\ % \phantom{Family\,/\,clan name}}\hfill^^A %^^A % \tcbox[equal height group=C,on line,tikznode,colback=white,colframe=nared, % adjusted title={\bfseries\sffamily Qualifier:\meta{Affix}}] % {\hbox to \nameboxii {\hfil Sobriquet\,/\,title:\hfil}\\ % \textit{Sr., Jr., III\dots}\\ % \textit{notable attribute}\\ % \textit{origin, region}\\ % \textit{patronym}}\hfill^^A %^^A % \tcbox[equal height group=C,on line,tikznode,colback=white,colframe=nared, % adjusted title={\bfseries\sffamily Alias:\meta{Alternate}}] % {\hbox to \nameboxiii {\hfil Replaces \meta{Affix}\hfil}\\ % only in text.\footnotemark} % \end{tcolorbox} % \footnotetext{The obsolete syntax uses \meta{Alternate} instead of % \meta{Affix} for a qualifier (Section~\ref{sec:Obsolete}).} % % \newpage % % \subsubsection{Name Ambiguity} % % \begin{itemize} % \item \textbf{Name forms are ambiguous.} % % In Western culture, one often sees forenames followed by a surname. Patronyms, as in \Name[Leif]{Erikson} and \Name{Llywelyn, ap Gruffudd}, and other exceptions exist.\footnote{Indexed here under \Name[Leif]{Erikson} and \Name{Llywelyn, ap Gruffudd}. See also \href{https://www.theindexer.org/wp-content/uploads/2020/07/welsh-personal-names.pdf} {\bfseries this document} on indexing Welsh names.} % Some readers might assume the following: % % \begin{center} % \renewcommand\NamesFormat{\color{blue}\sffamily} % \renewcommand\MainNameHook{\color{blue}\sffamily} % \begin{tabular}{lll}\toprule % \rowcolor{nagrey}\bfseries Forename & \bfseries Forename & \bfseries Surname\\ % \SubvertThis\FName[M.T.]{Cicero}[Marcus] & % \FName[M.T.]{Cicero}[Tullius] & % \Name[M.T.]{Cicero}\\\midrule % \rowcolor{nagrey}\bfseries Forename & & \bfseries Surname\\ % \SubvertThis\Name{Pontius, Pilate} & & % \ForceFN\FName{Pontius, Pilate}\\ % \SubvertThis\Name{Jesus, Christ} & & % \ForceFN\FName{Jesus, Christ}\\\bottomrule % \end{tabular} % \end{center} % % Even though all these initial assumptions are false, Western naming conventions tend to dominate the general readership market and, \textit{mutatis mutandis}, they affect the use and indexing of names. % % \item \textbf{Cultural context resolves ambiguity.} % % Here we see how the names above have meaning in their proper context. The words themselves \textit{as signs} do not offer the as many clues about their meaning until the signs become part of a cultural landscape. % % \begin{center} % \renewcommand\NamesFormat{\sffamily} % \renewcommand\MainNameHook{\sffamily} % \begin{tabular}{lll}\toprule % \rowcolor{nagrey}\bfseries Personal Name & % \bfseries Clan Name & \bfseries Branch Family or Nickname\\ % \SubvertThis\FName[M.T.]{Cicero}[Marcus] & % \FName[M.T.]{Cicero}[Tullius] & % \Name[M.T.]{Cicero}\\ % & \SubvertThis\Name{Pontius, Pilate} & % \ForceFN\FName{Pontius, Pilate}\\\midrule % \rowcolor{nagrey}\bfseries Personal Name & & \bfseries Sobriquet\\ % \SubvertThis\Name{Jesus, Christ} & & % \ForceFN\FName{Jesus, Christ}\\\bottomrule % \end{tabular} % \end{center} % % \item \textbf{This package embraces such ambiguities.} % % Roman \textit{praenomina} did not have the same significance as Western forenames.\footnote{See \href{https://en.wikipedia.org/wiki/Praenomen}{Wikipedia}. Roman names in particular are sensitive to the historical and political development of Rome and its empire, the history of Roman families and culture, as well as other factors.} % Yet the family name (\textit{nomen}) of the man we call \Name[M.T.]{Cicero} is \FName[M.T.]{Cicero}[Tullius]. In English, he used to be known as \IndexRef{Tully}{Cicero, M.T.}\Name{Tully}. In this manual we choose the popular case for the \textit{cognomen} \Name[M.T.]{Cicero} as a Western surname. Scholarly publications can take at least two different approaches (see Section~\ref{sec:Romani}). % % The name \Name*{Pontius, Pilate} has no personal name, which fits with Roman naming trends. \Name{Pontius, Pilate} is a clan name. Most texts and inscriptions favor the \textit{cognomen} \ForceFN\FName{Pontius, Pilate}[Pilatus], denoting martial prowess. % % \Name*{Jesus, Christ} is a name derived from Greek \el{Ἰησοῦς Χριστός}, from \textit{Y'shua ha-Mashiach}, Joshua the Anointed One. The personal name is \Name{Jesus, Christ}. Other added names are titles or descriptors. % % \item \textbf{Macros can modify names in the text to fit cultural norms.} % % Name forms in the text are independent of their index entries. This is necessary for special cases like Hungarian names. Thus, a text oriented to Hungarian readers can talk about \RevName\Name[Frenec]{Liszt}\dag\ (\IndexRef[Franz]{Liszt}{Liszt, Frenec}\Name[Franz]{Liszt}) in the body text, but he can be indexed as \ShowIdxPageref*[Frenec]{Liszt}. One can do something similar with East Asian names, if Western index entries are required. % % \item \textbf{Name arguments determine index entry forms.} % % The way that one puts names into macro name arguments absolutely determines the entry form in the index:\medskip % % \begingroup\IndexInactive\footnotesize % \renewcommand\NamesFormat{} % \renewcommand\MainNameHook{} % \begin{tabular}{l@{\ }l@{\ }l}\toprule % \rowcolor{nagrey}\bfseries Printed Name & % \bfseries Macro and Arguments & \bfseries Western Index Entry\\ % \Name[Person]{Family, Affix} & |\Name[Person]{Family, Affix}| & % \ShowIdxPageref*[Person]{Family, Affix}\\ % \Name[Person]{Family} & |\Name[Person]{Family}| & % \ShowIdxPageref*[Person]{Family}\\ % \RevName\Name*[Person]{Family} & |\RevName%| & % \ShowIdxPageref*[Person]{Family}\\ % & |\Name[Person]{Family}|\\\midrule % \rowcolor{nagrey}\bfseries Printed Name & % \bfseries Macro and Arguments & \bfseries Nonwestern Index Entry\\ % \Name{Family, Person} & |\Name{Family, Person}| & % \ShowIdxPageref*{Family, Person}\\ % \RevName\Name*{Family, Person} & |\RevName%| & % \ShowIdxPageref*{Family, Person}\\ % & |\Name{Family, Person}|\\ % \Name{Person, Affix} & |\Name{Person, Affix}| & % \ShowIdxPageref*{Person, Affix}\\ % \Name{Person} & |\Name{Person}| & % \ShowIdxPageref*{Person}\\\bottomrule % \end{tabular}\IndexActive % \endgroup\bigskip % % The following choices reflect non-scholarly English-language books. Later sections will show different ways to encode name arguments for scholarly works or non-English books. % % \begin{center}\footnotesize % \renewcommand\NamesFormat{\sffamily} % \renewcommand\MainNameHook{\sffamily} % \begin{tabular}{lll}\toprule % \rowcolor{nagrey}\bfseries Printed Name & % \bfseries Macro and Arguments & \bfseries Western Index Entry\\ % \ForgetThis\Name[M.T.]{Cicero} & \cmd{\Name[M.T.]\{Cicero\}} & % \ShowIdxPageref*[M.T.]{Cicero}\\\midrule % \rowcolor{nagrey}\bfseries Printed Name & % \bfseries Macro and Arguments & \bfseries Nonwestern Index Entry\\ % \ForgetThis\Name{Pontius, Pilate} & \cmd{\Name\{Pontius, Pilate\}} & % \ShowIdxPageref*{Pontius, Pilate}\\ % \ForgetThis\Name{Jesus, Christ} & \cmd{\Name\{Jesus, Christ\}} & % \ShowIdxPageref*{Jesus, Christ}\\\bottomrule % \end{tabular} % \end{center} % % \item \textbf{Name complexity creates \textsf{nameauth} complexity.} % % We might take names for granted until we have to consider them, use them in multicultural contexts, index them, and so on. Even if one does not use the \textsf{nameauth} package, one cannot escape this complexity. % % Indeed, it is only through the process of making \textsf{nameauth} that the present author became aware of the many intricate and fascinating complexities of names. The hope is that this package might facilitate accurate and respectful cross-cultural use of names in quality publications. % \end{itemize} % % \begin{Quote}{\Name[Theodore]{Roosevelt}\break\hbox{}\hfill % Introduction, \textit{The Papers and Writings of Abraham Lincoln} (1905)} % It is a very poor thing, whether for nations or individuals, to advance the history of great deeds done in the past as an excuse for doing poorly in the present; but it is an excellent thing to study the history of the great deeds of the past, and of the great men who did them, with an earnest desire to profit thereby so as to render better service in the present. In their essentials, the men of the present day are much like the men of the past, and the live issues of the present can be faced to better advantage by men who have in good faith studied how the leaders of the nation faced the dead issues of the past.\negmedskip^^A % \index{politicians, quotes of\noexpand\string|hyperpage} % \end{Quote} % % \newpage % % \subsection{Basic Interface} % \label{sec:BasicStart} % % The description of macro arguments in this section applies to all \textsf{nameauth} macros that take name arguments (Sections~\ref{sec:NameArgs} and~\ref{sec:NameArgMacros}), making this section critical to using and mastering \textsf{nameauth}. % % \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} % % \begin{tcolorbox}[colframe=naslate]\centering % \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. Both \cmd{\FName} and \cmd{\FName*} print long names in first uses, then just a forename in later uses.\footnote{The intent is that one can just add an \texttt{F} to either \cmd{\Name} or \cmd{\Name*}.} % The affix in a surname only appears in long name instances. % % \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} % \ForgetName[George]{Washington} % \FUse \Name [George]{Washington}\dotfill^^A % |\Name [George]{Washington}|\break % \LUse \Name*[George]{Washington}\dotfill^^A % |\Name*[George]{Washington}|\break % \LUse \Name [George]{Washington}\dotfill^^A % |\Name [George]{Washington}|\break % \LUse \FName[George]{Washington}\dotfill^^A % |\FName[George]{Washington}| % \end{Block} % % \begin{Block} % \FUse \Name [George S.]{Patton, Jr.}\dotfill^^A % |\Name [George S.]{Patton, Jr.}|\break % \LUse \Name*[George S.]{Patton, Jr.}\dotfill^^A % |\Name*[George S.]{Patton, Jr.}|\break % \LUse \Name [George S.]{Patton, Jr.}\dotfill^^A % |\Name [George S.]{Patton, Jr.}|\break % \LUse \FName[George S.]{Patton, Jr.}\dotfill^^A % |\FName[George S.]{Patton, Jr.}| % \end{Block} % % \subsubsection*{\hfil Affixes and Alternate Forms} % % In a long name instance, \cmd{\DropAffix} drops the affix from a Western surname. The \meta{Alternate} argument appears only in long names or forename-only names in the text. Otherwise, the automatic shortening of names will display only a short surname. % % \begin{itemize} % \item Drop the affix in a long name instance (forced by \cmd{\Name*}): % \BothInfo{\ShowPattern[George S.]{Patton, Jr.}\break % \ShowPattern[J.D.]{Rockefeller, IV}\break % \ShowPattern[Clive Staples]{Lewis}} % {\ShowIdxPageref*[George S.]{Patton, Jr.}\break % \ShowIdxPageref*[J.D.]{Rockefeller, IV}\break % \ShowIdxPageref*[Clive Staples]{Lewis}} % \begin{Block} % \FUse \ForgetThis\DropAffix\Name*[George S.]{Patton, Jr.}\\ % \UseB |\DropAffix\Name*[George S.]{Patton, Jr.}|\\ % \LUse \DropAffix\Name*[George S.]{Patton, Jr.}\\ % \UseB |\DropAffix\Name*[George S.]{Patton, Jr.}| % \end{Block} % % \item Use an alternate forename in a long- or forename instance: % \begin{Block} % \FUse \Name[J.D.]{Rockefeller, IV}[John Davison]\\ % \UseB |\Name[J.D.]{Rockefeller, IV}[John Davison]|\\ % \LUse \FName[George S.]{Patton, Jr.}[George]\\ % \UseB |\FName[George S.]{Patton, Jr.}[George]| % \end{Block} % % \item Drop the affix and alter the forenames: % \begin{Block} % \FUse \ForgetThis\DropAffix\Name*[J.D.]{Rockefeller, IV}[Jay]\\ % \UseB |\DropAffix\Name*[J.D.]{Rockefeller, IV}[Jay]|\\ % \LUse \DropAffix\Name*[J.D.]{Rockefeller, IV}[Jay]\\ % \UseB |\DropAffix\Name*[J.D.]{Rockefeller, IV}[Jay]| % \end{Block} % % \item Use multiple alternate forenames for the same person: % \begin{Block} % \FUse \Name [Clive Staples]{Lewis}\\ % \UseB |\Name [Clive Staples]{Lewis}|\\ % \LUse \Name*[Clive Staples]{Lewis}[C.S.]\\ % \UseB |\Name*[Clive Staples]{Lewis}[C.S.]|\\ % \LUse \FName[Clive Staples]{Lewis}[Jack]\\ % \UseB |\FName[Clive Staples]{Lewis}[Jack]| % \end{Block} % \end{itemize} % % \begin{InfoBox} % To sort the index consistently and properly, all names should be sorted by their longest unique name forms and by the Arabic equivalents of Roman numerals. See Section~\ref{sec:NameMedieval}, \ref{sec:IndexSort}, \ref{sec:IndexInitials}, \ref{sec:VarNames}. and all of Section~\ref{sec:AdvancedFormat}. For example: % % \begin{center} % |\PretagName[J.D.]{Rockefeller, IV}{Rockefeller, John D 4}| % \end{center} % \end{InfoBox} % % \begin{Quote}{\ForgetThis\Wash, Farewell Address (1796)} % The alternate domination of one faction over another, sharpened by the spirit of revenge, \dots is itself a frightful despotism. But this leads at length to a more formal and permanent despotism. The disorders and miseries, which result, gradually incline the minds of men to seek security and repose in the absolute power of an individual; and sooner or later the chief of some prevailing faction, more able or more fortunate than his competitors, turns this disposition to the purposes of his own elevation, on the ruins of Public Liberty.^^A % \index{politicians, quotes of\noexpand\string|hyperpage} % \end{Quote} % % \newpage % % \subsubsection[Reversed Western]{Reversed Western Names} % % \begin{tcolorbox}[colframe=naslate]\centering % \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} % % 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} % \BothInfo{\ShowPattern[Frenec]{Molnár}\break % \ShowPattern[Hideyo]{Noguchi}} % {\ShowIdxPageref*[Hideyo]{Noguchi}\break % \ShowIdxPageref*[Frenec]{Molnár}} % \FUse \Name [Frenec]{Molnár}\dotfill |\Name [Frenec]{Molnár}|\\ % \FUse \Name [Hideyo]{Noguchi}\dotfill |\Name [Hideyo]{Noguchi}|\\ % \LUse \Name*[Hideyo]{Noguchi}[Doctor]\dotfill |\Name*[Hideyo]{Noguchi}[Doctor]| % \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 either a Hungarian or ``non-native'' Eastern name in the text while keeping Western forms in the index: % % \begin{Block} % \LUse\Same \RevName\Name*[Frenec]{Molnár}\dag\\ % \UseB |\RevName\Name*[Frenec]{Molnár}\dag|\\ % \LUse \RevName\Name [Frenec]{Molnár}\dag\\ % \UseB |\RevName\Name [Frenec]{Molnár}\dag|\\ % \LUse \CapName\RevName\Name*[Hideyo]{Noguchi}[Sensei]\dag\\ % \UseB |\CapName\RevName\Name*[Hideyo]{Noguchi}[Sensei]\dag|\\ % \LUse \CapName\RevName\Name [Hideyo]{Noguchi}[Sensei]\dag\\ % \UseB |\CapName\RevName\Name [Hideyo]{Noguchi}[Sensei]\dag| % \end{Block} % % These macros, as is the case with many \textsf{nameauth} macros, work properly in context, not arbitrarily. \emph{They always have Western index entries,} regardless of how they appear in the text. % % \subsubsection{Eastern Names} % % All nonwestern name forms in \textsf{nameauth} have the syntax: \meta{SNN,Affix}. In Eastern names, \meta{SNN} refers to a family name and \meta{Affix} to a personal name. Otherwise, \meta{SNN} refers to a person's name and \meta{Affix} to added information. Knowing this difference helps one avoid nonsense names.\medskip % % \begin{tcolorbox}[colframe=naslate]\centering % \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 nonwestern form: \meta{SNN Affix}. % \item Names with the form \meta{SNN, Affix} can use the \meta{Alternate} % argument to swap \meta{Affix} with \meta{Alternate}. % \item They have nonwestern name patterns and index entry forms. % \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} % \ForgetName {Miyazaki, Hayao} % \FUse \Name {Miyazaki, Hayao}\dotfill |\Name {Miyazaki, Hayao}|\\ % \LUse \Name {Miyazaki, Hayao}\dotfill |\Name {Miyazaki, Hayao}|\\ % \LUse \Name*{Miyazaki, Hayao}[Sensei]\dotfill |\Name*{Miyazaki, Hayao}[Sensei]|\\ % \LUse \FName{Miyazaki, Hayao}\dotfill |\FName{Miyazaki, Hayao}| % \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\Same \ForceFN\FName{Miyazaki, Hayao}\dotfill^^A % |\ForceFN\FName{Miyazaki, Hayao}|\\ % \LUse \CapName\Name*{Miyazaki, Hayao}[Sensei]\dotfill^^A % |\CapName\Name*{Miyazaki, Hayao}[Sensei]|\\ % \LUse \ForceFN\FName{Miyazaki, Hayao}[Sensei]\dotfill^^A % |\ForceFN\FName{Miyazaki, Hayao}[Sensei]|\\ % \LUse \RevName\Name*{Miyazaki, Hayao}[Mr.]\dotfill^^A % |\RevName\Name*{Miyazaki, Hayao}[Mr.]| % \end{Block} % % If ``native'' Eastern names are reversed, they will have Western name order in the text, but \emph{they will retain Eastern-form index entries.} % % \newpage % % \subsubsection[Ancient Names]{Royal, Medieval, and Ancient Names} % % \begin{tcolorbox}[colframe=naslate]\centering % \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 ``nonwestern'' 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 nonwestern forms: \meta{SNN Affix} % or \meta{SNN}. % \item Names with the form \meta{SNN, Affix} can use the \meta{Alternate} % argument to swap \meta{Affix} with \meta{Alternate}. % \item Names with the form \meta{SNN} should not use \meta{Alternate} % (cf. Section~\ref{sec:Obsolete}). % \item They have nonwestern name patterns and index entry forms. % \item One generally does not reverse these names (Section~\ref{sec:RevNames}). % \end{itemize} % % \subsubsection*{\hfil No School Like the Old School} % % \begin{itemize} % \item \cmd{\FName} normally prints \meta{SNN} to avoid nonsense names % in the text. % \BothInfo{\ShowPattern{Elizabeth, I}\break % \ShowPattern{John, Eriugena}\break % \ShowPattern{Aristotle}} % {\ShowIdxPageref*{Elizabeth, I}\break % \ShowIdxPageref*{John, Eriugena}\break % \ShowIdxPageref*{Aristotle}} % \begin{Block} % \FUse \Name {Elizabeth, I}\dotfill |\Name {Elizabeth, I}|\\ % \LUse \Name {Elizabeth, I}\dotfill |\Name {Elizabeth, I}|\\ % \LUse \FName{Elizabeth, I}\dotfill |\FName{Elizabeth, I}| % \end{Block} % % \item Here we work with titles and sobriquets: % \begin{Block} % \FUse \ForgetThis\Name{Elizabeth, I}[I ``Gloriana'']\\ % \UseB |\ForgetThis\Name{Elizabeth, I}[I ``Gloriana'']|\\ % \LUse \ForceFN\FName{Elizabeth, I}[Gloriana]\\ % \UseB |\ForceFN\FName{Elizabeth, I}[Gloriana]| % \end{Block} % % \item Here we show a non-royal: % \begin{Block} % \FUse \Name {John, Eriugena}[Scotus Eriugena]\\ % \UseB |\Name {John, Eriugena}[Scotus Eriugena]|\\ % \LUse \Name*{John, Eriugena}\dotfill |\Name*{John, Eriugena}|\\ % \LUse \Name {John, Eriugena}\dotfill |\Name {John, Eriugena}|\\ % \LUse \ForceFN\FName{John, Eriugena}\dotfill |\ForceFN\FName{John, Eriugena}| % \end{Block} % % \item These are nonsensical name forms: % \begin{Block} % \LUse \ForceFN\FName{Elizabeth, I}\dotfill |\ForceFN\FName{Elizabeth, I}|\\ % \LUse \RevName\Name*{John, Eriugena}\dotfill |\RevName\Name*{John, Eriugena}| % \end{Block} % % \item The trivial case: % \begin{Block} % \FUse \Name{Aristotle}\dotfill |\Name{Aristotle}|\\ % \LUse \Name{Aristotle}\dotfill |\Name{Aristotle}| % \end{Block} % \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: % % \begin{quote} % \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} % \end{quote} % % Usually we leave \meta{arg4} empty, apart from specific contexts. That field permanently displays only alternate names, or is used with the obsolete syntax (Section~\ref{sec:Obsolete}). Here is another way of thinking about arguments in the \texttt{nameauth} environment that relates back to what we have seen: % % \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. % % 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} % \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} % \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} % \begin{tabular}{rll}\toprule % \rowcolor{nagrey}^^A % \bfseries Output & & \bfseries Macro\\ % % \Wash & Quick: & \cmd{\Wash}\\ % & Basic: & % \cmd{\Name}\texttt{[George]\{Washington\}}\\ % % \rowcolor{nagrey}^^A % \LWash & Quick: & \cmd{\LWash}\\ % \rowcolor{nagrey}^^A % & Basic: & % \cmd{\Name*}\texttt{[George]\{Washington\}}\\ % % \SWash & Quick: & \cmd{\SWash}\\ % & Basic: & % \cmd{\FName}\texttt{[George]\{Washington\}}\\ % % \rowcolor{nagrey}^^A % \ForgetThis\Wash & Quick: & \cmd{\ForgetThis}\cmd{\Wash}\\ % \rowcolor{nagrey}^^A % & Basic: & % \cmd{\ForgetName}\texttt{[George]\{Washington\}}\\ % \rowcolor{nagrey}^^A % & & % \cmd{\Name}\texttt{[George]\{Washington\}}\\ % % \ForgetThis\Wash & Quick: & \cmd{\ForgetThis}\cmd{\Wash}\\ % & Basic: & % \cmd{\ForgetThis}^^A % \cmd{\Name}\texttt{[George]\{Washington\}}\\ % % \rowcolor{nagrey}^^A % \SubvertThis\Wash & Quick: & \cmd{\SubvertThis}\cmd{\Wash}\\ % \rowcolor{nagrey}^^A % & Basic: & % \cmd{\SubvertName}\texttt{[George]\{Washington\}}\\ % \rowcolor{nagrey}^^A % & & % \cmd{\Name}\texttt{[George]\{Washington\}}\\ % % \SubvertThis\Wash & Quick: & \cmd{\SubvertThis}\cmd{\Wash}\\ % & Basic: & % \cmd{\SubvertThis}\cmd{\Name}\texttt{[George]\{Washington\}}\\ % % \rowcolor{nagrey}^^A % \JustIndex\Wash(unseen in text) & Quick: & \cmd{\JustIndex}\cmd{\Wash}\\ % \rowcolor{nagrey}^^A % & Basic: & % \cmd{\IndexName}\texttt{[George]\{Washington\}}\\\bottomrule % \end{tabular} % \end{center} % % \newpage % % \subsubsection[Name Variants]{Quick Name Variant Overview} % % After setting up the previous \texttt{nameauth} environment, we use the resulting name shorthands. Below we show more ``prefix macros'' that affect name forms in the text. We hide the use of \cmd{\ForgetThis} (Section~\ref{sec:NameControl}), which creates first instances. % % \begin{itemize} % \item Western Names: \hfill Sections~\ref{sec:Naming}, % \ref{sec:FName} % \BothInfo{\ShowPattern[George]{Washington}\break % \ShowPattern[George S.]{Patton, Jr.}\break % \ShowPattern[J.D.]{Rockefeller, IV}\break % \ShowPattern[Clive Staples]{Lewis}\break % \ShowPattern[Hideyo]{Noguchi}\break % \ShowPattern{Miyazaki, Hayao}} % {\ShowIdxPageref*[George]{Washington}\break % \ShowIdxPageref*[George S.]{Patton, Jr.}\break % \ShowIdxPageref*[J.D.]{Rockefeller, IV}\break % \ShowIdxPageref*[Clive Staples]{Lewis}\break % \ShowIdxPageref*[Hideyo]{Noguchi}\break % \ShowIdxPageref*{Miyazaki, Hayao}} % \begin{Block} % \FUse \ForgetThis\Wash \dotfill \cmd{\Wash}\\ % \LUse \LWash \dotfill \cmd{\LWash}\\ % \LUse \Wash \dotfill \cmd{\Wash}\\ % \LUse \SWash \dotfill \cmd{\SWash} % \end{Block} % % \item Nicknames and Affixes: \hfill Sections~\ref{sec:FName}, % \ref{sec:Affix} % \begin{Block} % \FUse \ForgetThis\DropAffix\Patton \dotfill \cmd{\DropAffix}\cmd{\Patton}\\ % \LUse \LPatton \dotfill \cmd{\LPatton}\\ % \LUse \Patton \dotfill \cmd{\Patton}\\ % \LUse \DropAffix\LPatton \dotfill \cmd{\DropAffix}\cmd{\LPatton}\\ % \LUse \DropAffix\LPatton[George]\dotfill^^A % \cmd{\DropAffix}\cmd{\LPatton[George]}\\ % \LUse \SPatton\dotfill \cmd{\SPatton}\\ % \LUse \SPatton[George]\dotfill \cmd{\SPatton[George]} % \end{Block} % % \begin{Block} % \FUse \ForgetThis\JRIV[John Davison]\dotfill^^A % \cmd{\JRIV[John Davison]}\\ % \LUse \LJRIV \dotfill \cmd{\LJRIV}\\ % \LUse \DropAffix\LJRIV[Jay]\dotfill \cmd{\DropAffix}\cmd{\LJRIV[Jay]} % \end{Block} % % \begin{Block} % \FUse \ForgetThis\Lewis\dotfill \cmd{\Lewis}\\ % \LUse \LLewis[C.S.]\dotfill \cmd{\LLewis[C.S.]}\\ % \LUse \LLewis[Jack]\dotfill \cmd{\LLewis[Jack]}\\ % \LUse \SLewis\dotfill \cmd{\SLewis}\\ % \LUse \SLewis[Jack]\dotfill \cmd{\SLewis[Jack]}\\ % \LUse \LCSL\dotfill \cmd{\LCSL}\\ % \LUse \SCSL\dotfill \cmd{\SCSL} % \end{Block} % % \item ``Native'' Eastern Names: \hfill Section~\ref{sec:Eastern} % \begin{Block} % \FUse \ForgetThis\CapName\Miyazaki\dotfill \cmd{\CapName}\cmd{\Miyazaki}\\ % \LUse \CapName\LMiyazaki\dotfill \cmd{\CapName}\cmd{\LMiyazaki}\\ % \LUse \CapName\Miyazaki\dotfill \cmd{\CapName}\cmd{\Miyazaki}\\ % \LUse \RevName\LMiyazaki\dotfill \cmd{\RevName}\cmd{\LMiyazaki}\\ % \LUse \RevName\LMiyazaki[Mr.]\dotfill \cmd{\RevName}\cmd{\LMiyazaki[Mr.]}\\ % \LUse \SMiyazaki\dotfill \cmd{\SMiyazaki}\\ % \LUse \ForceFN\SMiyazaki\dotfill \cmd{\ForceFN}\cmd{\SMiyazaki} % \end{Block} % % \item Reversed Western Names: \hfill Section~\ref{sec:RevNames} % \begin{Block} % \FUse \ForgetThis\Noguchi\dotfill \cmd{\Noguchi}\\ % \LUse \LNoguchi\dotfill \cmd{\LNoguchi}\\ % \LUse \LNoguchi[Doctor]\dotfill \cmd{\LNoguchi[Doctor]}\\ % \LUse \SNoguchi\dotfill \cmd{\SNoguchi}\\ % \LUse \RevName\LNoguchi\dag\dotfill \cmd{\RevName}\cmd{\LNoguchi}\cmd{\dag}\\ % \LUse \CapName\RevName\LNoguchi\dag\dotfill^^A % \cmd{\CapName}\cmd{\RevName}\cmd{\LNoguchi}\cmd{\dag}\\ % \LUse \CapName\Noguchi\dag\dotfill \cmd{\CapName}\cmd{\Noguchi}\cmd{\dag} % \end{Block} % % \item Western Names Reversed by Surname: \hfill Section \ref{sec:LastFirst} % \begin{Block} % \FUse \ForgetThis\RevComma\LWash\dotfill \cmd{\RevComma}\cmd{\LWash}\\ % \LUse \RevComma\LWash\dotfill \cmd{\RevComma}\cmd{\LWash} % \end{Block} % % \item Particles: \hfill Section~\ref{sec:NameParticles} % \BothInfo{\ShowPattern[Hernando]{de~Soto}\break % \ShowPattern{Aristotle}\break % \ShowPattern{Æthelred, II}\break % \ShowPattern{John, Eriugena}} % {\ShowIdxPageref*[Hernando]{de~Soto}\break % \ShowIdxPageref*{Aristotle}\break % \ShowIdxPageref*{Æthelred, II}\break % \ShowIdxPageref*{John, Eriugena}} % \begin{Block} % \FUse \ForgetThis\Soto\dotfill \cmd{\Soto}\\ % \LUse \Soto\dotfill \cmd{\Soto}\\ % \LUse \CapThis\Soto\dotfill \cmd{\CapThis}\cmd{\Soto} % \end{Block} % % \item Royal and Medieval Names: \hfill Section~\ref{sec:NameMedieval} % \begin{Block} % \FUse \ForgetThis\Aeth\footnote % {Regarding the margin note that shows name control sequences, % with \texttt{pdflatex} and \texttt{latex}, in % \texttt{\ShowPattern{Æthelred, II}} the glyphs \texttt{ÃĘ} % correspond to \cmd{\IeC\{}\cmd{\AE\}}.}\dotfill \cmd{\Aeth}\\ % \LUse \Aeth\dotfill \cmd{\Aeth}\\ % \LUse \LAeth[II, ``Unræd'']\dotfill |\LAeth[II, ``Unræd'']| % \end{Block} % % \begin{Block} % \FUse \ForgetThis\Eriugena[Scotus Eriugena]\dotfill^^A % \cmd{\Eriugena[Scotus Eriugena]}\\ % \LUse \LEriugena\dotfill \cmd{\LEriugena}\\ % \LUse \Eriugena\dotfill \cmd{\Eriugena} % \end{Block} % % \begin{Block} % \FUse \ForgetThis\Aris\dotfill \cmd{\Aris}\\ % \LUse \Aris\dotfill \cmd{\Aris} % \end{Block} % \end{itemize} % % \subsubsection[\protect\textit{Alternate} Field] % {\protect\meta{Alternate} Name Field Tips} % \label{sec:ArgIV} % % Two shorthands above use \meta{arg4}, the final field in each row of the \texttt{nameauth} environment. These are \cmd{\CSL} and \cmd{\MSens}. They correspond to similar name shorthands \cmd{\Lewis} and \cmd{\Miyazaki}, which leave \meta{arg4} empty. Here is how they are related: % % \begin{itemize} % \item They share identical name control patterns % (Section~\ref{sec:NamePatterns}). % \BothInfo{\ShowPattern[Clive Staples]{Lewis}\break % \ShowPattern{Miyazaki, Hayao}} % {\ShowIdxPageref*[Clive Staples]{Lewis}\break % \ShowIdxPageref*{Miyazaki, Hayao}} % \begin{Block} % \ForgetName{Miyazaki, Hayao}\ForgetName[Clive Staples]{Lewis} % \FUse \MSens\dotfill \cmd{\MSens}\\ % \LUse \Miyazaki\dotfill \cmd{\Miyazaki}\\ % \FUse \CSL\dotfill \cmd{\CSL}\\ % \LUse \Lewis\dotfill \cmd{\Lewis} % \end{Block} % % \item Usually, one leaves \meta{arg4} empty and adds alternate names in % brackets as needed: \LLewis[C.S.] \cmd{\LLewis[C.S.]} % % \item By using \meta{arg4}, one trades less work for more ambiguity: Can % one add an alternate name or not? To answer that, one should keep track % of all name shorthands that use \meta{arg4}. % % \item Failure to keep track of such macros creates output like \LCSL[Jack] % \cmd{\LCSL[Jack]} and \LMSens[Sensei] \cmd{\LMSens[Sensei]}. % The reason why these macro versions produce undesired output is because % \meta{arg4} permanently populates \meta{Alternate}. % % \item Remember that \meta{arg4} can be used for the obsolete % syntax, as mentioned previously, but we do not cover that here. % \end{itemize} % % \begin{Quote}{\Name[Harold]{Urey} (1961)} % The space program is not only scientific in purpose but also is an expression of man's insistent determination to do the nearly impossible\,---\,to explore the unknown, even at great risk.\negmedskip^^A % \index{scientists, quotes of\noexpand\string|hyperpage} % \end{Quote} % % \newpage % % \subsection{Select Macro Overview} % \label{sec:SelectOver} % % \subsubsection[With Name Args]{Macros with Name Arguments} % \label{sec:NameArgMacros} % % All macros that take name arguments (Section~\ref{sec:NameArgs}) can have final optional arguments (Section~\ref{sec:FinalOptargs}) and update \cmd{\NameauthPattern} (Section~\ref{sec:DataTemp}). The \meta{xref args} are the same as \meta{name args} for a cross-reference to a \meta{target} (Section~\ref{sec:IndexRef}). % \begin{center} % \begin{tabular}{lrcll}\toprule % \rowcolor{nagrey}^^A % \llap{\colorbox{nagrey}{\hbox to 2.65cm{\strut\hfill}}\qquad\qquad}^^A % Optional Prefix & Macro & Star & Arguments & \\ % % \llap{\colorbox{white}{\hbox to 2.65cm{\strut\hfill Naming}}\qquad\qquad}^^A % \meta{prefix macros} & % \cmd{\Name} & \texttt{*} & \meta{name args} & \\ % \llap{\colorbox{white}{\hbox to 2.65cm{\strut\hfill}}\qquad\qquad}^^A % \meta{prefix macros} & % \cmd{\FName} & \texttt{*} & \meta{name args} & \\ % % \rowcolor{nagrey}^^A % \llap{\colorbox{nagrey}{\hbox to 2.65cm{\strut\hfill Page entry}}\qquad\qquad}^^A % \cmd{\SeeAlso} & \cmd{\IndexName} & & % \meta{name args} & \\ % \rowcolor{nagrey}^^A % \llap{\colorbox{nagrey}{\hbox to 2.65cm{\strut\hfill Only cross-ref}}\qquad\qquad}^^A % \cmd{\SeeAlso} & \cmd{\IndexRef} & & % \meta{xref args} & \meta{target}\\ % % \llap{\colorbox{white}{\hbox to 2.65cm{\strut\hfill Stop page entry}}\qquad\qquad}^^A % & \cmd{\ExcludeName} & & % \meta{name args} & \\ % \llap{\colorbox{white}{\hbox to 2.65cm{\strut\hfill Allow page entry}}\qquad\qquad}^^A % & \cmd{\IncludeName} & % \texttt{*} & \meta{name args} & \\ % % \rowcolor{nagrey}^^A % \llap{\colorbox{nagrey}{\hbox to 2.65cm{\strut\hfill Sort index}}\qquad\qquad}^^A % & \cmd{\PretagName} & & \meta{name args} & % \meta{sort key} \\ % \rowcolor{nagrey}^^A % \llap{\colorbox{nagrey}{\hbox to 2.65cm{\strut\hfill Make index tag}}\qquad\qquad}^^A % & \cmd{\TagName} & & \meta{name args} & % \meta{tag} \\ % \rowcolor{nagrey}^^A % \llap{\colorbox{nagrey}{\hbox to 2.65cm{\strut\hfill Delete index tag}}\qquad\qquad}^^A % & \cmd{\UntagName} & & \meta{name args} & \\ % % \llap{\colorbox{white}{\hbox to 2.65cm{\strut\hfill Make name tag}}\qquad\qquad}^^A % & \cmd{\NameAddInfo} & & % \meta{name args} & \meta{tag} \\ % \llap{\colorbox{white}{\hbox to 2.65cm{\strut\hfill Show name tag}}\qquad\qquad}^^A % & \cmd{\NameQueryInfo} & & % \meta{name args} & \\ % \llap{\colorbox{white}{\hbox to 2.65cm{\strut\hfill Delete name tag}}\qquad\qquad}^^A % & \cmd{\NameClearInfo} & & % \meta{name args} & \\ % % \rowcolor{nagrey}^^A % \llap{\colorbox{nagrey}{\hbox to 2.65cm{\strut\hfill Delete name cs}}\qquad\qquad}^^A % & \cmd{\ForgetName} & & \meta{name args} & \\ % \rowcolor{nagrey}^^A % \llap{\colorbox{nagrey}{\hbox to 2.65cm{\strut\hfill Create name cs}}\qquad\qquad}^^A % & \cmd{\SubvertName} & & % \meta{name args} & \\ % % \llap{\colorbox{white}{\hbox to 2.65cm{\strut\hfill Name cs tests}}\qquad\qquad}^^A % & \cmd{\IfMainName} & & % \meta{name args} & \marg{y}\marg{n}\\ % \llap{\colorbox{white}{\hbox to 2.65cm{\strut\hfill}}\qquad\qquad}^^A % & \cmd{\IfFrontName} & & \meta{name args} & % \marg{y}\marg{n}\\ % \llap{\colorbox{white}{\hbox to 2.65cm{\strut\hfill}}\qquad\qquad}^^A % & \cmd{\IfAKA} & & \meta{name args} & \marg{y}\marg{n}\marg{x}\\ % % \rowcolor{nagrey}^^A % \llap{\colorbox{nagrey}{\hbox to 2.65cm{\strut\hfill Debugging}}\qquad\qquad}^^A % & \cmd{\ShowPattern} & & \meta{name args} & \\ % \rowcolor{nagrey}^^A % \llap{\colorbox{nagrey}{\hbox to 2.65cm{\strut\hfill}}\qquad\qquad}^^A % & \cmd{\ShowIdxPageref} & \texttt{*} & \meta{name args} & \\ % \rowcolor{nagrey}^^A % \llap{\colorbox{nagrey}{\hbox to 2.65cm{\strut\hfill}}\qquad\qquad}^^A % & \cmd{\ShowNameInfo} & & \meta{name args} & \\ % \rowcolor{nagrey}^^A % \llap{\colorbox{nagrey}{\hbox to 2.65cm{\strut\hfill}}\qquad\qquad}^^A % & \cmd{\ShowNameState} & & \meta{name args} &\\\bottomrule % \end{tabular} % \end{center} % % Optional prefix macros are shown in the next subsection. Not shown above are \cmd{\AKA}, \cmd{\AKA*}, \cmd{\PName}, and \cmd{\PName*} (Section~\ref{sec:AKA}). % % \begin{Quote}{\Name[John F.]{Kennedy}, Inaugural Address (1961)} % The world is very different now. For man holds in his mortal hands the power to abolish all forms of human poverty and all forms of human life. And yet the same revolutionary beliefs for which our forebears fought are still at issue around the globe\,---\,the belief that the rights of man come not from the generosity of the state, but from the hand of God.^^A % \index{politicians, quotes of\noexpand\string|hyperpage} % \end{Quote} % % \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{itemize}[rightmargin=0em] % \item Capitalization in the Text\negmedskip % \begin{itemize}[leftmargin=6.5em]\small % \item[\cmd{\CapName}] Capitalize entire \meta{SNN}. Overrides \cmd{\CapThis}. % \item[\cmd{\CapThis}] Capitalize first letter of all name components. % \item[\cmd{\AccentCapThis}] Fallback when Unicode detection cannot be done. % \end{itemize} % % \item Reversing in the Text\negmedskip % \begin{itemize}[leftmargin=6.5em]\small % \item[\cmd{\RevName}] Reverse order of any name. Overrides \cmd{\RevComma} % \item[\cmd{\RevComma}] Reverse only Western names to \meta{SNN}, \meta{FNN}. % \end{itemize} % % \item Commas in the Text\negmedskip % \begin{itemize}[leftmargin=6.5em]\small % \item[\cmd{\ShowComma}] Add comma between \meta{SNN} and \meta{Affix}. % \item[\cmd{\NoComma}] No comma between \meta{SNN} and \meta{Affix}. Overrides \cmd{\ShowComma}. % \end{itemize} % % \item Name Breaks in the Text\negmedskip % \begin{itemize}[leftmargin=6.5em]\small % \item[\cmd{\DropAffix}] Drop affix only for a long Western name instance. % \item[\cmd{\KeepAffix}] Insert non-breaking space (NBSP) between \meta{SNN}, \meta{FNN/Affix}. % \item[\cmd{\KeepName}] Insert NBSP between all name elements. Overrides \cmd{\KeepAffix}. % \end{itemize} % % \item Forcing Name Forms via Control Sequence\negmedskip % \begin{itemize}[leftmargin=6.5em]\small % \item[\cmd{\ForgetThis}] Force first name instance. Negates \cmd{\SubvertThis}. % \item[\cmd{\SubvertThis}] Force subsequent name instance. % \end{itemize} % % \item Forcing Name Forms via Boolean Flags\negmedskip % \begin{itemize}[leftmargin=6.5em]\small % \item[\cmd{\ForceName}] Force first-use formatting hooks. % \item[\cmd{\ForceFN}] Print \meta{Affix}/\meta{Alternate} in nonwestern short forms. % \end{itemize} % % \item Indexing\negmedskip % \begin{itemize}[leftmargin=6.5em]\small % \item[\cmd{\SeeAlso}] For \cmd{\IndexName}, \cmd{\AKA}, and \cmd{\PName}; make a \textit{see also} xref. % \item[\cmd{\SkipIndex}] For naming macros; do not create index entry (once). % \item[\cmd{\JustIndex}] For naming macros; index only (once); negated by \cmd{\AKA}, \cmd{\PName}. % \end{itemize} % \end{itemize} % % \noindent Some important notes include: % % \begin{itemize} % \item Prefix macros stack:\\[0.4ex] % \CapThis\RevName\SkipIndex\Name[bar]{foo}\dotfill^^A % |\CapThis\RevName\SkipIndex\Name[bar]{foo}| % \item The Boolean flags governed by the prefix macros are reverted after % the appropriate macros produce output in the text (or index) unless the % output of the naming macros is suppressed via \cmd{\JustIndex}. % \item Even after using \cmd{\JustIndex}, several name form modifiers are reset. % This prevents errors when handling the next name. % \item Except for \cmd{\SeeAlso}, use prefix macros only before a naming % macro that is designed to print output in the text. % \item Use \cmd{\SeeAlso} only with \cmd{\IndexRef}, \cmd{\AKA}, and % \cmd{\PName}. Otherwise it will be ignored and reset by \cmd{\IndexName} % and the naming macros. % \end{itemize} % % \noindent Macros that do not take name arguments include prefix macros (Section~\ref{sec:PrefixMacs}), helper macros (Section~\ref{sec:Helpers}), most internal package macros, and formatting macros (Sections~\ref{sec:Formatting} and~\ref{sec:AdvancedFormat}). % % \newpage % % \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} % \LEliz[I ``Gloriana'']\dotfill |\LEliz[I ``Gloriana'']| % \end{Block} % % We can display the same thing with different macros. This next example does not offer more features; it only offers more complexity: % % \begin{Block} % \LEliz\ ``\ForceFN\SEliz[Gloriana]''\dotfill^^A % |\LEliz\ ``\ForceFN\SEliz[Gloriana]''| % \end{Block} % % The next example offers more features and better automation. Based on Section~\ref{sec:NameAncient} we use name tags and change the formatting hooks to match this manual's conventions. The key here is that \emph{we make a few key changes once,} which then govern many appearances of names: % % \begingroup % \begin{quote} % \begin{Verbatim} % \NameAddInfo{Elizabeth, I}{ ``Gloriana''} % \renewcommand*\NamesFormat[1] % { % \color{blue}\sffamily #1 % \ifcsname\NameauthPattern!DB\endcsname % \expandafter\csname\NameauthPattern!DB\endcsname % \fi % } % \renewcommand*\MainNameHook{\sffamily} % \end{Verbatim} % \end{quote} % % \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} % \FUse \ForgetThis\LEliz\dotfill |\ForgetThis\LEliz|\\ % \LUse \LEliz\dotfill |\LEliz|\\ % \LUse \Eliz\dotfill |\Eliz| % \end{Block} % \endgroup % % Section~\ref{sec:NameParticles} shows a similar trade-off between simplicity and automation with an example using the name of poet \Name[e.e.]{cummings}. Moving on to Section~\ref{sec:Romani}, complexity increases, yet the state of any given name remains well-defined. % % \begin{InfoBox}[Avoid the Rabbit Hole] % \begin{itemize}[leftmargin=1em] % \item In \textsf{nameauth}, names are nouns that have state and modifiers. % \item In \textsf{nameauth}, names are verbs capable of changing their environment. % \item There are trade-offs between ease of use and automation. % \item Simple examples often are not easy to automate. % \item Automation works best with a few key changes. % \item Most use-cases can be as simple as Section~\ref{sec:QuickExample}. % \item Use the simple approach unless a complex approach is needed. % \end{itemize} % \end{InfoBox} % % \ReturnLink % % \newpage % % \section{Package Options} % \label{sec:PkgOptions} % % There are many options for use in \textsf{nameauth}, which can be divided into specific areas of functionality. These range from defaults that make conforming to certain standards easier to backward compatibility with old versions. The expected syntax follows: % % \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} % % \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} % % \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} % % \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}\textls[-5]{Capitalize entire surnames, e.g., Romanized % Eastern names, throughout the document.}\medskip\\ % \end{tabular} % % \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} % % \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 nonwestern, 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} % % \noindent These options do not affect the index and are mutually exclusive (Sections~\ref{sec:RevNames} and~\ref{sec:LastFirst}). Use \texttt{allrevcomma} option only for listing Western names by surname. % % \subsection{Indexing} % % \subsubsection{Toggle Indexing} % % \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} % %^^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} % % \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} % % \noindent The default allows \cmd{\PretagName} to create sort keys used with \texttt{makeindex}. The \texttt{nopretag} option disables the sorting mechanism and causes \cmd{\PretagName} only to emit warnings, as might be needed with, e.g., \texttt{xindy}. See Section~\ref{sec:IndexSort}. % % \subsubsection{Verbose Warnings} % % \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} % % \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} % % \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} % % \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} % % \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} % % \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} % % \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} % % \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} % % \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} % % \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} % \label{sec:OptionCompat} % % \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.\smallskip\\ % \leavevmode\color{nared}\quad\texttt{oldargs} & % \leavevmode\color{nared}Load the \textsf{xargs} and \textsf{suffix} % packages in order to permit user-supplied modifications to work as % in version 3.7 and before. The package macros will still use % \textsf{xparse} because of its advantages.\medskip\\ % \end{tabular} % % Using these options may increase the chance of undocumented behavior.\footnote{Previously, the prefix macros and mechanisms for long and short names used Boolean flags locally. With continued use of this package, it became clear that such local scope could produce unexpected results. Those results, in turn, could mask problems caused by some flags not being reset by \cmd{\AKA}, \cmd{\AKA*}, and \cmd{\JustIndex}. The result was undocumented behavior.} % They are included for the sake of approximate backward compatibility with older documents, illustrated by the following table: % % \begin{center} % \begin{tabular}{lll}\toprule % \rowcolor{nagrey}^^A % \bfseries Version & \bfseries Needed Options & \bfseries Possible Options \\ % % 2.6 & \ttfamily oldreset,oldtoks,oldsee, & \ttfamily oldargs \\ % & \ttfamily oldAKA,oldpass & \\ % % \rowcolor{nagrey}^^A % 3.0--3.2 & \ttfamily oldreset,oldtoks,oldsee, & \ttfamily oldargs \\ % \rowcolor{nagrey}^^A % & \ttfamily oldpass & \\ % % 3.3--3.4 & \ttfamily oldreset,oldtoks,oldsee & \ttfamily oldargs \\ % % \rowcolor{nagrey}^^A % 3.5--3.7 & \ttfamily & \ttfamily oldargs \\\bottomrule % \end{tabular} % \end{center} % % \ReturnLink % % \begin{Quote}{\ForgetThis\MLK[Dr. Martin Luther], \textit{Stride Towards Freedom} (1958)} % \IndexName{Jesus, Christ}^^A % We believe firmly in the revelation of God in Jesus Christ. I can see no conflict between our devotion to Jesus Christ and our present action. In fact, I can see a necessary relationship. If one is truly devoted to the religion of Jesus he will seek to rid the earth of social evils. The gospel is social as well as personal.^^A % \index{civil rights leaders, quotes of\noexpand\string|hyperpage}^^A % \index{theologians, quotes of\noexpand\string|hyperpage} % \end{Quote} % % \newpage % % \section{Feature Priority} % \label{sec:Priorities} % % \begin{center} % \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}\\[1ex] % % \rowcolor{black!6!white} % \cmd{\JustIndex} & \cmd{\CapName} & \cmd{\RevName} & \cmd{\SubvertThis}\\ % \rowcolor{black!6!white} % & & & \cmd{\ForceName}\\ % \rowcolor{black!6!white} % & & & \cmd{\NoComma}\\[1ex] % % \rowcolor{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}\\[1ex] % % \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 their related macros. Package options are shown in boldface. % % \begin{itemize} % \item Lighter-colored rows show higher priority. Darker-colored rows show % lower priority. Higher-priority options and macros have the ability to override % lower-priority ones. % \item All options and macros in a given row have equal priority and are % able to countermand each other within a given column. % \item Priority affects macros and options within columns. % \cmd{\IndexInactive} overrides \cmd{\JustIndex}, which overrides % \cmd{\SkipIndex}. If \cmd{\IndexInactive} is invoked, \cmd{\JustIndex} % will have no effect. % \item Section~\ref{sec:IdxPrefix} shows the complex interaction between % \cmd{\SkipIndex} and \cmd{\JustIndex}. It it is best to use \cmd{\SkipIndex} % and \cmd{\JustIndex} only before a naming macro that can print to the text. % \item Priority usually does not affect macros and options in different % columns. Yet the macros themselves can have specific effects that change % the expected behavior of macros in other columns. % % For example, \cmd{\JustIndex} prevents a name from being displayed in % the text. Even if \cmd{\IndexInactive} overrides \cmd{\JustIndex} with % respect to indexing, it has no effect on the fact that the name will not % be printed. % % Also, \cmd{\JustIndex} resets the effects of \cmd{\ForgetThis} and % \cmd{\SubvertThis} because those prefix macros should precede only naming % macros that produce output in the text. % % Due to this behavior, even though \cmd{\JustIndex} does not ``override'' % the caps and reversing macros and options, nevertheless it simply prevents % any other macros related to the display of a name from taking effect. % \end{itemize} % % \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} % \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} % \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} % \begin{tabular}{ll}\toprule % \rowcolor{nagrey}^^A % \Name [Albert]{Einstein} & |\Name [Albert]{Einstein}| or |\Einstein|\\ % \rowcolor{nagrey}^^A % \LEinstein & |\Name*[Albert]{Einstein}| or |\LEinstein|\\ % \rowcolor{nagrey}^^A % \Einstein & |\Name [Albert]{Einstein}| or |\Einstein|\\ % % \Name [J.E.]{Carter, Jr.} & |\Name [J.E.]{Carter, Jr.}| or |\Carter|\\ % \LCarter[James Earl] & |\Name*[J.E.]{Carter, Jr.}[James Earl]|\\ % & or |\LCarter[James Earl]|\\ % \Carter & |\Name [J.E.]{Carter, Jr.}| or |\Carter|\\ % % \rowcolor{nagrey}^^A % \Confucius & |\Name {Confucius}| or |\Confucius|\\ % \rowcolor{nagrey}^^A % \Confucius & |\Name {Confucius}| or |\Confucius|\\ % % \ForgetThis\Name {Miyazaki, Hayao} & % |\Name {Miyazaki, Hayao}| or |\Miyazaki|\\ % \Name*{Miyazaki, Hayao}[Sensei] & |\Name*{Miyazaki, Hayao}[Sensei]|\\ % \Name {Miyazaki, Hayao} & |\Name {Miyazaki, Hayao}| or |\Miyazaki|\\ % % \rowcolor{nagrey}^^A % \ForgetThis\Eliz & |\Name {Elizabeth, I}| or |\Eliz|\\ % \rowcolor{nagrey}^^A % \Name*{Elizabeth, I} & |\Name*{Elizabeth, I}| or |\LEliz|\\ % \rowcolor{nagrey}^^A % \Name {Elizabeth, I} & |\Name {Elizabeth, I}| or |\Eliz|\\\bottomrule % \end{tabular} % \end{center} % % With the quick interface, the best way to get alternate names follows patterns like ``\LCarter[James Earl]'' |\LCarter[James Earl]| and ``\LMiyazaki[Sensei]'' |\LMiyazaki[Sensei]|. The alternate forename is not shown in subsequent short name instances e.g., ``\Carter[James Earl]'' |\Carter[James Earl]|. Thus, one must use either long-name instances or forename instances to see the alternate names. % % \newpage % % \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 instance macros will permit all name types, but the normal behavior prints forenames only with Western names. With nonwestern names only \meta{SNN} is printed. This is designed to prevent Western writers from causing unintended offense in Eastern contexts. It also prevents the display of nonsense names in the context of ancient and royal names. % % \DescribeMacro{\ForceFN} % To get an Eastern personal name or any affixed components of an ancient name, or to get \meta{Alternate} to display in their place, one must precede these macros with \cmd{\ForceFN}. See also Section~\ref{sec:NameMedieval} for more uses of \cmd{\ForceFN}. % % \begin{center} % \vspace{3ex} % \PatInfo{\ShowPattern[Albert]{Einstein}\break % \ShowPattern[J.E.]{Carter, Jr.}\break % \ShowPattern{Confucius}\break % \ShowPattern{Miyazaki, Hayao}\break % \ShowPattern{Elizabeth, I}} % \vspace{-3ex} % \begin{tabular}{ll}\toprule % \rowcolor{nagrey}^^A % \SEinstein & |\FName[Albert]{Einstein}| or |\SEinstein|\\ % % \SCarter[Jimmy] & |\FName[J.E.]{Carter, Jr.}[Jimmy]|\\ % & or |\SCarter[Jimmy]|\\ % % \rowcolor{nagrey}^^A % \FName{Confucius} & |\FName{Confucius}| or |\SConfucius |\\ % % \FName{Miyazaki, Hayao} & |\FName{Miyazaki, Hayao}| or |\SMiyazaki|\\ % % \rowcolor{nagrey}^^A % \ForceFN\FName{Miyazaki, Hayao} & |\ForceFN\FName{Miyazaki, Hayao}|\\ % \rowcolor{nagrey}^^A % & or |\ForceFN\SMiyazaki|\\ % % \ForceFN\FName{Miyazaki, Hayao}[Sensei] & % |\ForceFN\FName{Miyazaki, Hayao}[Sensei]|\\ % & or |\ForceFN\SMiyazaki[Sensei]|\\ % % \rowcolor{nagrey}^^A % \SEliz & |\FName{Elizabeth, I}| or |\SEliz|\\ % \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.\negmedskip^^A % \index{politicians, quotes of\noexpand\string|hyperpage} % \end{Quote} % % \subsection{Technical Details} % \label{sec:TechDetails} % % \subsubsection[Final Optargs]{Final Optional Arguments} % \label{sec:FinalOptargs} % % Macros that take name arguments (see also Section~\ref{sec:NameArgMacros}) sometimes use a final optional argument. Using these arguments with the current syntax gives: % % \begin{center}\IndexInactive\footnotesize % \renewcommand\NamesFormat{} % \renewcommand\MainNameHook{} % \begin{tabular}{l@{\ }l@{\ }l}\toprule % \rowcolor{nagrey}\bfseries Printed Name & % \bfseries Macro and Arguments & \bfseries Western Index Entry\\ % \ForgetThis\Name[Person]{Family, Affix}[Alias] & |\Name[Person]{Family, Affix}[Alias]| & % \ShowIdxPageref*[Person]{Family, Affix}\\ % \ForgetThis\Name[Person]{Family}[Alias] & |\Name[Person]{Family}[Alias]| & % \ShowIdxPageref*[Person]{Family}\\ % \RevName\Name*[Person]{Family}[Alias] & |\RevName%| & % \ShowIdxPageref*[Person]{Family}\\ % & |\Name[Person]{Family}[Alias]|\\\midrule % \rowcolor{nagrey}\bfseries Printed Name & % \bfseries Macro and Arguments & \bfseries Nonwestern Index Entry\\ % \ForgetThis\Name{Family, Person}[Alias] & |\Name{Family, Person}[Alias]| & % \ShowIdxPageref*{Family, Person}\\ % \RevName\Name*{Family, Person}[Alias] & |\RevName%| & % \ShowIdxPageref*{Family, Person}\\ % & |\Name{Family, Person}[Alias]|\\ % \ForgetThis\Name{Person, Affix}[Alias] & |\Name{Person, Affix}[Alias]| & % \ShowIdxPageref*{Person, Affix}\\\bottomrule % \end{tabular}\IndexActive % \end{center} % % Since May 2018, \textsf{xparse} offers two approaches that have their own pros and cons. Below \cmd{\Namei} works the same as \textsf{nameauth}. \cmd{\Nameii} takes the alternate route. If one builds this package with a \LaTeX\ distro from before 2018, \cmd{\Nameii} will not appear, and \cmd{\Namei} will work like \cmd{\Nameii} in newer versions. It was for the sake of stability and consistency that \textsf{nameauth} used \textsf{xargs} and \textsf{suffix} in its early days. Now that all the issues with \textsf{xparse} have been addressed, the latter is the best choice going forward. % % \begin{quote} % \begin{Verbatim} % \NewDocumentCommand {\Namei}{O{} m O{}} % {\def\Opt{#3}\ifx\Opt\empty #1\ #2\else \Opt\ #2\fi} % % Cannot use this definition before May 2018. % \NewDocumentCommand{\Nameii}{O{} m !O{}} % {\def\Opt{#3}\ifx\Opt\empty #1\ #2\else \Opt\ #2\fi} % % |\Namei: | \Namei[Person1]{Family1} [something1]\\[1ex] % |\Nameii:| \Nameii[Person2]{Family2} [something2] % \end{Verbatim} % % \ifdefined\nameauthxp%^^A % \NewDocumentCommand {\Namei}{O{} m O{}} % {\def\Opt{#3}\ifx\Opt\empty #1\ #2\else \Opt\ #2\fi} % \NewDocumentCommand{\Nameii}{O{} m !O{}} % {\def\Opt{#3}\ifx\Opt\empty #1\ #2\else \Opt\ #2\fi} % |\Namei: | \Namei[Person1]{Family1} [something1]\\[1ex] % |\Nameii:| \Nameii[Person2]{Family2} [something2]%^^A % \else % \NewDocumentCommand {\Namei}{O{} m O{}} % {\def\Opt{#3}\ifx\Opt\empty #1\ #2\else \Opt\ #2\fi} % |\Namei: | \Namei[Person1]{Family1} [something1]\\[1ex] % |\Nameii:| (\LaTeX\ too old)%^^A % \fi % \end{quote} % % \begin{itemize} % \item \cmd{\Namei} ignores spaces between the mandatory argument and the final optional argument. % \begin{itemize} % \item Subsequent text in brackets will be interpreted as a name argument, even if unintended. % \item Yet we avoid errors from unintended spaces when using alternate names and the obsolete syntax. % \end{itemize} % % \item \cmd{\Nameii} treats spaces between the mandatory argument and the final optional argument as significant. % \begin{itemize} % \item Subsequent text in brackets will be seen as a name argument only if no spaces occur between the mandatory argument and final optional argument. % \item Yet when using alternate names and the obsolete syntax, with unintended spaces we could ``lose'' names from the arguments and see unwanted results in the text. % \end{itemize} % \end{itemize} % % In the next example we show the default approach of \textsf{nameauth} in practice using the basic name interface. \cmd{\ForgetName} (Section~\ref{sec:NameControl}) lets us simulate first instances of names, even if they have appeared already. % % \begin{quote} % \ForgetName[Albert]{Einstein} \ForgetName{Miyazaki, Hayao} % \renewcommand\NamesFormat{} % \renewcommand\MainNameHook{} % % \begin{itemize} % \item[We want:] ``Albert Einstein [then] said''; % ``Miyazaki Hayao [apparently] said''. % \item[Also:] ``Einstein [then] said''; % ``Miyazaki [apparently] said''. % \item[Macros:] |``\Name[Albert]{Einstein} [then] said'';|\\ % |``\Name{Miyazaki, Hayao} [apparently] said''.| % \item[We get:] ``\Name[Albert]{Einstein} [then] said''; % ``\Name{Miyazaki, Hayao} [apparently] said''. % \item[Repeat:] ``\Name[Albert]{Einstein} [then] said''; % ``\Name{Miyazaki, Hayao} [apparently] said''. % \end{itemize} % % \ForgetName[Albert]{Einstein} \ForgetName{Miyazaki, Hayao} % \begin{itemize} % \item Add explicit spaces:\\ % ``\Name[Albert]{Einstein}\ [then] said''; % ``\Name {Miyazaki, Hayao}\ [apparently] said''.\\ % |``\Name[Albert]{Einstein}\ [then] said'';|\\ % |``\Name {Miyazaki, Hayao}\ [apparently] said''.| % \item Add curly braces:\\ % ``\Name[Albert]{Einstein}{} [then] said''; % ``\Name{Miyazaki, Hayao}{} [apparently] said''.\\ % |``\Name[Albert]{Einstein}{} [then] said'' and|\\ % |``\Name{Miyazaki, Hayao}{} [apparently] said''.| % \end{itemize} % \end{quote} % % Now we show how the \textsf{nameauth} default argument handling works with the quick naming interface: % % \begin{quote} % \begin{Verbatim} % \begin{nameauth} % \< Einstein & Albert & Einstein & > % \< Miyazaki & & Miyazaki, Hayao & > % \end{nameauth} % \end{Verbatim} % \end{quote} % % \begin{quote} % \renewcommand\NamesFormat{} % \renewcommand\MainNameHook{} % % \ForgetName[Albert]{Einstein} \ForgetName{Miyazaki, Hayao} % \begin{itemize} % \item[We want:] ``Albert Einstein [then] said''; % ``Miyazaki Hayao [apparently] said''. % \item[Also:] ``Einstein [then] said''; % ``Miyazaki [apparently] said''. % \item[Macros:] |``\Einstein [then] said'';|\\ % |``\Miyazaki [apparently] said''.| % \item[We get:] ``\Einstein [then] said''; % ``\Miyazaki [apparently] said''. % \item[Repeat:] ``\Einstein [then] said''; % ``\Miyazaki [apparently] said''. % \end{itemize} % % \ForgetName[Albert]{Einstein} \ForgetName{Miyazaki, Hayao} % \begin{itemize} % \item Add explicit spaces:\\ % ``\Einstein\ [then] said''; % ``\Miyazaki\ [apparently] said''.\\ % |``\Einstein\ [then] said'' and|\\ % |``\Miyazaki\ [apparently] said''.| % \item Add curly braces:\\ % ``\Einstein{} [then] said''; % ``\Miyazaki{} [apparently] said''.\\ % |``\Einstein{} [then] said'' and|\\ % |``\Miyazaki{} [apparently] said''.| % \end{itemize} % \end{quote} % % Section~\ref{sec:ChangeParse} shows how one can customize and change argument handling, addressing some of the same issues and caveats illustrated above. % % \begin{Quote}{\ForgetThis\Miyazaki\break % \hbox{}\hfill Proposal for \textit{Princess Mononoke}} % We depict hatred, but it is to depict that there are more important things. We depict a curse, to depict the joy of liberation.\negmedskip^^A % \index{creatives, quotes of\noexpand\string|hyperpage} % \end{Quote} % % \newpage % % \subsubsection[Name Arg Caveats]{Name Argument Caveats} % % To get consistent index entries, all \textsf{nameauth} macros that take name arguments trim extra spaces around each name argument, shown in gray below: % \begin{quote} % \def\gbox{\colorbox{nagrey}{\strut\quad\strut}} % \cmd{\Name}\texttt{[}\gbox\meta{\color{nared}FNN}\gbox\texttt{]}^^A % \texttt{\{}\gbox\meta{SNN}\gbox\texttt{\color{nared},}\gbox^^A % \meta{\color{nared}Affix}\gbox\texttt{\}}^^A % \texttt{[}\gbox\meta{\color{nared}Alternate}\gbox\texttt{]} % \end{quote} % We show this in practice while suppressing name formatting: % % \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:\\ % \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} % \VerbatimInput[gobble=0]{\jobname.tmp} % \renewcommand*\NamesFormat{} % \renewcommand*\MainNameHook{} % % \vspace{3ex} % \BothInfo{\ShowPattern[Martin Luther]{King, Jr.}\break % \ShowPattern[ Martin Luther ]{ King , Jr. }} % {\ShowIdxPageref*[Martin Luther]{King, Jr.}\break % \ShowIdxPageref*[ Martin Luther ]{ King , Jr. }} % \vspace{-3ex} % \input{\jobname.tmp} % \end{quote} % % We resume name formatting to show names that look the same, but are different. Non-breaking spaces, explicit spaces, thin spaces, and macros that expand to spaces \emph{are not trimmed}. They produce different name patterns, shown below: % % \begin{center}\IndexInactive % \begin{tabular}{lll}\toprule % \rowcolor{nagrey}^^A % \bfseries Output & \bfseries Macro & \bfseries Name Pattern\\ % % \Name{foo~bar} & |\Name{foo~bar}| & \ttfamily\ShowPattern{foo~bar} \\ % % \rowcolor{nagrey}^^A % \Name{foo\ bar} & |\Name{foo\ bar}| & \ttfamily\ShowPattern{foo\ bar} \\ % % \Name{foo\space bar} & |\Name{foo\space bar}| & % \ttfamily\ShowPattern{foo\space bar} \\\bottomrule % \end{tabular}\IndexActive % \end{center} % % Name patterns, not name appearance, determine if names are the same (Section~\ref{sec:NamePatterns}). There may be cases where one might leverage that point. % % \subsubsection{Full Stop Detection} % % Western names tend to use full stops in various cases, including the following: % % \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} % % If name contains a full stop at the end, followed by a full stop in the text. the \textsf{nameauth} macros try to prevent two adjacent full stops. All macros that take name arguments and print names in the text check if the printed name ends with a full stop. They also check the lookahead token for a full stop. If both cases are true, they gobble the lookahead token. % % \newpage % % We show this behavior in the example below. \cmd{\ForgetName} (Section~\ref{sec:NameControl}) lets us simulate the first instances of names. The table tells us whether or not the full stop on the lookahead token is gobbled, why that is the case, as well as the output of the name in the text and its correlating source. % % \begin{quote} % \begin{Verbatim} % \begin{nameauth} % \< MLK & Martin Luther & King, Jr. & > % \end{nameauth} % \end{Verbatim} % \end{quote} % % \ForgetName[Martin Luther]{King, Jr.} % % \begin{center} % \begin{tabular}{ll}\toprule % \rowcolor{nagrey}^^A % \bfseries Full Stop Gobbled & \bfseries Long Name Form, First Use\\ % Dr. \Name[Martin Luther]{King, Jr.}. & % |Dr. \Name[Martin Luther]{King, Jr.}.| \\ % % \rowcolor{nagrey}^^A % \bfseries Full Stop Gobbled & \bfseries Force Long Name Form \\ % Dr. \Name*[Martin Luther]{King, Jr.}. & % |Dr. \Name*[Martin Luther]{King, Jr.}.| \\ % Dr. \LMLK. & % |Dr. \LMLK.| \\ % % \rowcolor{nagrey}^^A % \bfseries Full Stop Gobbled & \bfseries Alternate FNN with Initials \\ % \FName[Martin Luther]{King, Jr.}[M.L.]. & % |\FName[Martin Luther]{King, Jr.}[M.L.].| \\ % \SMLK[M.L.]. & % |\SMLK[M.L.].| \\ % % \rowcolor{nagrey}^^A % \bfseries Full Stop Remains & \bfseries Affix Auto-Drops \\ % Dr. \Name[Martin Luther]{King, Jr.}. & % |Dr. \Name[Martin Luther]{King, Jr.}.| \\ % % \rowcolor{nagrey}^^A % \bfseries Full Stop Remains & \bfseries Force Affix to Drop \\ % \DropAffix\Name*[Martin Luther]{King, Jr.}. & % |\DropAffix\Name*[Martin Luther]{King, Jr.}.| \\ % \DropAffix \LMLK. & % |\DropAffix \LMLK.| \\\bottomrule % \end{tabular} % \end{center} % % \subsubsection[Grouping, Spaces]{Grouping and Spaces} % \label{sec:GroupSpace} % % 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} % \begin{tabular}{lllll}\toprule % \rowcolor{nagrey}^^A % & \bfseries Macro & \bfseries Result & \bfseries Name Pattern & \bfseries Type\\ % % 1 & |\Name[one]{two}| & \Name[one]{two} & % \ttfamily\ShowPattern[one]{two} & Western\\ % % \rowcolor{nagrey}^^A % 2 & |\Name[{one}]{{t}w{o}}| & \Name[{one}]{{t}w{o}} & % \ttfamily\ShowPattern[{one}]{{t}w{o}} & Western\\ % % 3 & |\Name{{one}, two}| & \Name{{one}, two} & % \ttfamily\ShowPattern{{one}, two} & nonwestern\\ % % \rowcolor{nagrey}^^A % 4 & |\Name{{one}, {two}}| & \Name{{one}, {two}} & % \ttfamily\ShowPattern{{one}, {two}} & nonwestern\\ % % 5 & |\Name{{one, two}}| & \Name{{one, two}} & % \ttfamily\ShowPattern{{one, two}} & abnormal\\\bottomrule % \end{tabular} % \end{center} % % These names have different patterns and different index entries, even if they look similar in the text (Sections~\ref{sec:NamePatterns}, \ref{sec:IndexSort}). Similar issues pertain to grouping used with alternate formatting (Section~\ref{sec:AltFormat}). Consistency is key. % % The grouping used in name~5 creates an abnormality . Here we illustrate that with the output of \cmd{\ShowNameInfo} (Section~\ref{sec:DebuggingMacros}). Normally, the comma should delimit or segment the argument into two names: % % \begin{quote} % |\Name{one, two} | \ShowNameInfo{one, two}\\ % |\Name{{one, two}}| \ShowNameInfo{{one, two}} % \end{quote} % \IndexActive % % Curly braces can change the lookahead token and defeat punctuation detection (as well as create a new, unique name). Using spaces between a name and a full stop can have a similar effect. The next table shows us several actions that allow or inhibit full stop detection. We se ethe results of each action, the action taken, and both output and source related to that action. % % \begin{center} % \begin{tabular}{ll}\toprule % \rowcolor{nagrey}^^A % \bfseries Full Stop Remains & \bfseries Not Contained in Group \\ % Dr. {\Name*[Martin Luther]{King, Jr.}}. & % |Dr. {\Name*[Martin Luther]{King, Jr.}}.| \\ % Dr. {\LMLK}. & % |Dr. {\LMLK}.| \\ % % \rowcolor{nagrey}^^A % \bfseries Full Stop Gobbled & \bfseries Contained in Group \\ % Dr. {\Name*[Martin Luther]{King, Jr.}.} & % |Dr. {\Name*[Martin Luther]{King, Jr.}.}| \\ % Dr. {\LMLK.} & % |Dr. {\LMLK.}| \\ % % \rowcolor{nagrey}^^A % \bfseries Full Stop Remains & \bfseries Grouped in Affix; New Name \\ % Dr. \SkipIndex\Name*[Martin Luther]{King, {Jr.}}. & % |Dr. \Name*[Martin Luther]{King, {Jr.}}.| \\ % % \rowcolor{nagrey}^^A % \bfseries Full Stop Gobbled & \bfseries Not Grouped in Affix; New Name \\ % Dr. \SkipIndex\Name*[Martin Luther]{King, {Jr}.}. & % |Dr. \Name*[Martin Luther]{King, {Jr}.}.| \\ % % \rowcolor{nagrey}^^A % \bfseries Full Stop Remains & \bfseries Intervening Space \\ % Dr. \Name*[Martin Luther]{King, Jr.} . & % |Dr. \Name*[Martin Luther]{King, Jr.} .| \\ % % \rowcolor{nagrey}^^A % \bfseries Full Stop Gobbled & \bfseries After Shorthand \\ % Dr. \LMLK . & % |Dr. \LMLK .| \\ % % \rowcolor{nagrey}^^A % \bfseries Full Stop Remains & \bfseries After Shorthand with Optional Argument \\ % Dr. \LMLK[M.L.] . & % |Dr. \LMLK[M.L.] .| \\ % % \rowcolor{nagrey}^^A % \bfseries Fixed; Space Removed & \\ % Dr. \LMLK[M.L.]. & % |Dr. \LMLK[M.L.].| \\\bottomrule % \end{tabular} % \end{center} % % \subsubsection{Formatting Initials} % % This can be a thorny topic. Some publishers are dead-set on having a space between initials. Many designers find that practice to be inelegant at best. [\hyperlink{Bringhurst}{Bringhurst}] wisely advises one to omit spaces between initials. % % Fighting with one's editor does little good. If a style guide requires spaces, try thin spaces. The quick interface simplifies the task. Below we use no formatting: % % \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 entry order (Section~\ref{sec:IndexInitials}). % % \ReturnLink % % \section{Language Topics} % \label{sec:Lang} % % Here we cover technical issues related to the use of names in various languages and cultures. Specifically, we show how they should be represented in English, but this material can apply to other language standards as well. % % \subsection[Active Characters]{Caveats with Active Characters} % % Active characters affect name patterns and index sorting, depending on the \LaTeX\ engine being used. We use \cmd{\PretagName} (Section~\ref{sec:IndexSort}; cf.~\ref{sec:Unicode}) to get correct sorting and \cmd{\SkipIndex} (Section~\ref{sec:IdxPrefix}) to suppress bogus index entries: % % \newpage % % \begin{enumerate}\small % \item \Name*{Æthelred, II}\dotfill |\Name*{Æthelred, II}| % \PatInfo{\ShowPattern{Æthelred, II} \textrm{(1)}\break % \ShowPattern{\AE thelred, II} \textrm{(2)}\break % \ShowPattern{Bo\"ethius} \textrm{(3)}\break % \ShowPattern{Boëthius} \textrm{(4)}\break % \ShowPattern{Bo{\"e}thius} \textrm{(5)}} % \item[] We have seen this name earlier, as the formatting shows.\footnote{Regarding the margin note that shows name control sequences, with \texttt{pdflatex} and \texttt{latex}, in \texttt{\ShowPattern{Æthelred, II}} the glyphs \texttt{ÃĘ} correspond to \cmd{\IeC\{}\cmd{\AE\}}. Likewise in \texttt{\ShowPattern{Boëthius}} the glyphs \texttt{Ãń} correspond to \cmd{\IeC\{}\cmd{\"e\}}.} % \item[] We 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 ë. It cannot have the same index entry as \Name{Bo\"ethius} above. % \item \SkipIndex\Name{Bo{\"e}thius}\dotfill |\SkipIndex\Name{Bo{\"e}thius}| % \item[] Yet another different name by virtue of grouping tokens (Section~\ref{sec:GroupSpace}). The index entry for this one is again different. % \end{enumerate} % % \subsection{Hyphenation} % % In modern English, names can be hyphenated to reflect their cultural origins. With \textsf{nameauth}, one can handle such names by using default hyphenation, optional hyphens, or packages like \textsf{babel} and \textsf{polyglossia}. % \IndexName[John]{\noexpand\de{Strietelmeier}} % % \subsubsection*{\hfil Default Hyphenation} % % Here\PatInfo{\ShowPattern[John]{Strietelmeier}} we use the default hyphenation. Using \cmd{\textls} from \textsf{microtype} we get the name to break badly. We use \cmd{\SkipIndex} to omit this version from the index. % % \begin{VerbatimOut}{\jobname.tmp} % \textls[20]{In English, some names come from other cultures. % Names like \SkipIndex\Name[John]{Strietelmeier} % can break badly in some cases.} % \end{VerbatimOut} % % \begin{quote} % \VerbatimInput[gobble=0]{\jobname.tmp} % % \input{\jobname.tmp} % \end{quote} % % \subsubsection*{\hfil Discretionary Hyphens} % % We\PatInfo{\ShowPattern[John]{Strie\-tel\-meier}} create a different name from that above. One must use the discretionary hyphens consistently in the macro arguments. We use \cmd{\Name[John]\{Strie\textbackslash-tel\textbackslash-meier\}} to omit this version from the index. We see that it breaks properly. % % \begin{VerbatimOut}{\jobname.tmp} % \textls[20]{In English, some names come from other cultures. % Names like \SkipIndex\Name[John]{Strie\-tel\-meier} % can break badly in some cases.} % \end{VerbatimOut} % % \begin{quote} % \VerbatimInput[gobble=0]{\jobname.tmp} % % \input{\jobname.tmp} % \end{quote} % % \subsubsection*{\hfil Language Packages} % % Here\PatInfo{\textls[-5]{\ShowPattern[John]{\de{Strietelmeier}}}} we use an approach with macros in name arguments that can be applied to \textsf{babel} and \textsf{polyglossia}. This approach has issues that we discuss in Sections~\ref{sec:NameParticles}, \ref{sec:AltFormat}, and elsewhere, showing how to prevent errors. % % \NameArgWarning % % Since the leading element of \meta{SNN} is a macro, using \cmd{\CapThis} would halt \LaTeX\ with errors unless we used alternate formatting (Section~\ref{sec:AltFormat}): % % \begin{VerbatimOut}{\jobname.tmp} % \textls[20]{In English, some names come from other cultures. % Names like \Striet\ or \Name[John]{\noexpand\de{Strietelmeier}} % break badly in some cases.} % \end{VerbatimOut} % % \begin{quote} % \begin{Verbatim} % \newcommand\de[1]{\foreignlanguage{ngerman}{#1}} % % or polyglossia: \newcommand\de[1]{\textgerman{#1}} % % \begin{nameauth} % \< Striet & John & \noexpand\de{Strietelmeier} & > % \end{nameauth} % % \PretagName[John]{\noexpand\de{Strietelmeier}} % {Strietelmeier, John} % \end{Verbatim} % \VerbatimInput[gobble=0,firstnumber=10]{\jobname.tmp} % % \input{\jobname.tmp} % \end{quote} % % \subsection{Affixes Need Commas} % \label{sec:Affix} % \negmedskip % % \begin{InfoBox} % Regarding an \meta{SNN, Affix} pair, the key to avoiding error is to apply macros to \meta{SNN} and \meta{Affix} as if they were independent arguments.^^A % \end{InfoBox} % % 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 delimits or segments the name argument. Spaces around the comma are ignored. See Section~\ref{sec:Noexpand} for more information when using macros in name arguments. Below we see the basics of commas in name arguments. % % \begin{center} % \vspace{1ex} % \BothInfo{\ShowPattern[Oskar]{Hammerstein, II}\break % \ShowPattern{Louis, XIV}\break % \ShowPattern{Sun, Yat-sen}} % {\ShowIdxPageref*[Oskar]{Hammerstein, II}\break % \ShowIdxPageref*{Louis, XIV}\break % \ShowIdxPageref*{Sun, Yat-sen}} % \vspace{-1ex} % \ForgetName{Sun, Yat-sen} % \begin{tabular}{ll}\toprule % \rowcolor{nagrey}^^A % \Name[Oskar]{Hammerstein, II} & |\Name[Oskar]{Hammerstein, II}|\\ % \rowcolor{nagrey}^^A % \Name[Oskar]{Hammerstein, II} & |\Name[Oskar]{Hammerstein, II}|\\ % % \Name{Louis, XIV} & |\Name{Louis, XIV}|\\ % \Name{Louis, XIV} & |\Name{Louis, XIV}|\\ % % \rowcolor{nagrey}^^A % \Name{Sun, Yat-sen} & |\Name{Sun, Yat-sen}|\\ % \rowcolor{nagrey}^^A % \Name{Sun, Yat-sen} & |\Name{Sun, Yat-sen}|\\\bottomrule % \end{tabular} % \end{center} % % Western names with affixes must use \meta{SNN,Affix},^^A % \PatInfo{\ShowPattern[Oskar]{Hammerstein}[II]} never the obsolete syntax, which is meant for nonwestern names and is discouraged. We get \SkipIndex\Name[Oskar]{Hammerstein}[II] and a bad index entry from, e.g., \cmd{\SkipIndex}\cmd{\Name[Oskar]\{Hammerstein\}[II]}. % % \DescribeMacro{\KeepAffix} % If the name displayed in the text shows both \meta{SNN} and \meta{Affix}, then \cmd{\KeepAffix} turns the space \emph{between} \meta{SNN} and \meta{Affix} into a non-breaking space. \cmd{\KeepAffix}\cmd{\Name\{Louis, XIV\}} will not break between \Name{Louis, XIV} and \ForceFN\FName{Louis, XIV}. All name types that use \meta{Affix} are supported. % % \DescribeMacro{\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 with multiple names, such as French and German forenames, as well as Spanish surnames. \cmd{\KeepName} works with all name types. % % \DescribeMacro{\DropAffix} % If \cmd{\DropAffix} precedes only a Western name, it will suppress the affix after the surname in a first or long instance. We get ``\DropAffix\Name*[Oskar]{Hammerstein, II}'' From |\DropAffix\Name*[Oskar]{Hammerstein, II}|. % % With nonwestern names, the \meta{Affix} in the \meta{SNN, Affix} pair drops automatically in the text for subsequent uses, making \cmd{\DropAffix} redundant. We see that above in the case of \Name*{Louis,XIV}, who becomes \Name{Louis,XIV}. % % \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} % \begin{tabular}{ll}\toprule % \rowcolor{nagrey}^^A % \ShowComma\LPatton & |\ShowComma\LPatton|\\ % \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 nonwestern names, are encoded using comma-delimited syntax (compare the obsolete syntax in Section~\ref{sec:Obsolete}). They have nonwestern index entries: \meta{SNN} \meta{Affix} (no comma between name elements). The current syntax permits alternate names; the obsolete does not. % % \begin{SyntaxBox} % \cmd{\Name}\marg{SNN, Affix}\oarg{Alternate} % \end{SyntaxBox} % % Even in some academic texts, one sees nonwestern names encoded with Western forms.\footnote{\textls[-5]{Jaroslav Pelikan, \textit{The Christian Tradition}, 5 vols. (Chicago: Chicago UP, 1971–1989); Immanuel Geiss, \textit{Personen: Die biographische Dimension der Weltgeschichte}, Geschichte Griffbereit vol. 2 (Munich: Wissen Media Verlag, 2002).} At this time, \href{https://www.nndb.com/}{\bfseries NNDB} sorts \Name{Kim, Jong Un} under U, not K.} % The \textsf{nameauth} package seeks to remedy that issue, which has more to do with outsourcing indexes to non-expert providers than with scholars. For example, the macro |\Name*{Sun, Yat-sen}| \Name*{Sun, Yat-sen} ensures correct forms in the text and the index. We get cross-cultural sensitivity and scholarly accuracy. % % \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}. % % Both\Info{\cmd{\global}} \cmd{\AllCapsActive} and \cmd{\AllCapsInactive} can be used either as a pair or singly within an explicitly local scope. Use \cmd{\global} to force a global effect. % \medskip % % \begin{center} % \begin{tabular}{ll}\toprule % \rowcolor{nagrey}^^A % \LNoguchi & |\LNoguchi| \\ % % \CapName\LNoguchi & |\CapName\LNoguchi}|\\ % % \rowcolor{nagrey}^^A % \LMiyazaki & |\LMiyazaki| \\ % % \CapName\LMiyazaki & |\CapName\LMiyazaki|\\\bottomrule % \end{tabular} % \end{center} % \vspace{-14ex} % \BothInfo{\ShowPattern[Hideyo]{Noguchi}\break % \ShowPattern{Miyazaki, Hayao}} % {\ShowIdxPageref*[Hideyo]{Noguchi}\break % \ShowIdxPageref*{Miyazaki, Hayao}} % \vspace{14ex} % % \subsection{Reversed Names} % \label{sec:RevNames} % % Sometimes a publisher expects Western-style index entries. Sometimes certain names have specific forms in the index, The reversing option and macros can adapt forms in the text to the index entries required in such cases. % % \DescribeMacro{\ReverseActive} % In addition to the \texttt{allreversed} option for reversing name order (Section~\ref{sec:PkgOptions}), \cmd{\ReverseActive} and \cmd{\ReverseInactive} do the same for blocks of text. % \DescribeMacro{\ReverseInactive} % These all have priority over the use of \cmd{\RevName}, used once per name. % \DescribeMacro{\RevName} % These macros do not affect the index. They work also with \cmd{\AKA} and friends. \emph{Reversing only affects long name forms,} which is why we show only long names below. In this manual, reversed Western forms are shown with a dagger (\dag). % % 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. % % \begin{center} % \vspace{3ex} % \BothInfo{\ShowPattern[Hideyo]{Noguchi}\break \ShowPattern{Miyazaki, Hayao}} % {\ShowIdxPageref*[Hideyo]{Noguchi}\break \ShowIdxPageref*{Miyazaki, Hayao}} % \vspace{-3ex} % \begin{tabular}{ll}\toprule % \rowcolor{nagrey}^^A % \bfseries Output & \bfseries Macro \\ % % \LNoguchi & |\LNoguchi| \\ % \LNoguchi[Doctor] & |\LNoguchi[Doctor]| \\ % \strut Bad result: \fbox{\LNoguchi[Sensei]} & |\LNoguchi[Sensei]| \\ % % \rowcolor{nagrey}^^A % \RevName\LNoguchi\dag & |\RevName\LNoguchi\dag| \\ % \rowcolor{nagrey}^^A % \strut Bad result: \fbox{\RevName\LNoguchi[Doctor]} & |\RevName\LNoguchi[Doctor]| \\ % \rowcolor{nagrey}^^A % \RevName\LNoguchi[Sensei]\dag & |\RevName\LNoguchi[Sensei]| \\ % % \LMiyazaki & |\LMiyazaki| \\ % \LMiyazaki[Sensei] & |\LMiyazaki[Sensei]| \\ % \strut Bad result: \fbox{\LMiyazaki[Mr.]} & |\LMiyazaki[Mr.]| \\ % % \rowcolor{nagrey}^^A % \RevName\LMiyazaki & |\RevName\LMiyazaki| \\ % \rowcolor{nagrey}^^A % \RevName\LMiyazaki[Mr.] & |\RevName\LMiyazaki[Mr.]| \\ % \rowcolor{nagrey}^^A % \strut Bad result: \fbox{\RevName\LMiyazaki[Sensei]} & % |\RevName\LMiyazaki[Sensei]| \\\bottomrule % \end{tabular} % \end{center} % \negmedskip % % \begin{SyntaxBox}[Reversing Western Names] % \cmd{\RevName}\cmd{\Name}\oarg{FNN}\marg{SNN}\oarg{Alternate} % \end{SyntaxBox} % % Avoid using \meta{Affix} with such names. For example, |\RevName\LPatton\dag| produces ``\RevName\LPatton\dag''. The name looks wrong unless one uses either \cmd{\RevComma} or \cmd{\DropAffix}. This name has a Western index entry. % % \begin{SyntaxBox}[Reversing Eastern Names] % \cmd{\RevName}\cmd{\Name}\marg{SNN, Affix}\oarg{Alternate} % \end{SyntaxBox} % % The index entry of this name form looks like \meta{SNN} \meta{FNN} (no comma). This name has a nonwestern index entry. % % \begin{InfoBox} % Reversing ancient names works the same as reversing Eastern names. The problem is that, in most cases, one produces a nonsense name. % \end{InfoBox} % \negmedskip % % \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. % % 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} % \begin{tabular}{lll}\toprule % \rowcolor{nagrey}^^A % \Name*[Oskar]{Hammerstein, II} & % \RevComma\Name*[Oskar]{Hammerstein, II} & change\\ % \rowcolor{nagrey}^^A % \LNoguchi & \RevComma\LNoguchi & change\\ % % \LAeth & \RevComma\LAeth & no change\\ % \Name*{Sun, Yat-sen} & % \RevComma\Name*{Sun, Yat-sen} & no change\\\bottomrule % \end{tabular} % \end{center}^^A % \vspace{-12ex} % \PatInfo{\ShowPattern[Oskar]{Hammerstein, II}\break % \ShowPattern[Hideyo]{Noguchi}\break % \ShowPattern{Æthelred,II}\break % \ShowPattern{Sun, Yat-sen}} % \vspace{12ex} % % \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} % % According to [\hyperlink{Mulvany}{Mulvany}, 152–82], one may treat name 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. Capitalization may vary. % \item \textit{Le}, \textit{La}, and \textit{L'} always are capitalized % unless preceded by \textit{de}. % \item Modern Romance languages keep particles with the surname. % \item German and medieval Romance languages keep particles with forenames. % \item Modern Welsh, Irish, and Scots names often merge particles with % surnames: FitzRoy or Fitzroy; O'Leary; McDonald, MacLeish. % \end{itemize} % % \begin{center} % \vspace{2ex} % \BothInfo{\ShowPattern[Martin]{Van Buren}\break % \ShowPattern[Hernando]{de~Soto}\break % \ShowPattern[J.W. von]{Goethe}} % {\ShowIdxPageref*[Martin]{Van Buren}\break % \ShowIdxPageref*[Hernando]{de~Soto}\break % \ShowIdxPageref*[J.W. von]{Goethe}} % \vspace{-2ex} % \begin{tabular}{lll}\toprule % \rowcolor{nagrey}^^A % \bfseries Body Text & \bfseries Index & \bfseries Macro \\ % % \ForgetThis\VBuren & \ShowIdxPageref*[Martin]{Van Buren} & % \cmd{\ForgetThis}\cmd{\VBuren} \\ % \VBuren & \ShowIdxPageref*[Martin]{Van Buren} & \cmd{\VBuren} \\ % % \rowcolor{nagrey}^^A % \ForgetThis\Soto & \ShowIdxPageref*[Hernando]{de~Soto} & % \cmd{\ForgetThis}\cmd{\Soto} \\ % \rowcolor{nagrey}^^A % \CapThis\Soto & \ShowIdxPageref*[Hernando]{de~Soto} & % \cmd{\CapThis}\cmd{\Soto} \\ % % \ForgetThis\JWG & \ShowIdxPageref*[J.W. von]{Goethe} & % \cmd{\ForgetThis}\cmd{\JWG}\\ % % \JWG & \ShowIdxPageref*[J.W. von]{Goethe} & \cmd{\JWG}\\\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]{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.,: % % \begin{itemize} % \item[] \CapThis\Soto\ was a famous Spanish explorer. % \item[] |\CapThis\Soto\ was a famous Spanish explorer.|\medskip % % \item With \texttt{latex} and \texttt{pdflatex}, using \cmd{\CapThis} % should work with all of the Unicode characters available in the T1 % encoding. For a broader set of characters, consider using \texttt{xelatex} % and \texttt{lualatex}. % % \item 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 and not needed. % % \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} % \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} % % \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} % % \ReturnLink % % \newpage % % \addtocontents{toc}{\protect\goodbreak} % \section{Debugging} % \label{sec:Debugging} % % From this point onward, concepts that we introduced earlier will mesh together in complex ways, starting with indexing. Name patterns govern those interactions, illustrated by debugging macros. We explain what the debugging macros communicate, then we describe the macros. % % \leavevmode^^A % \PatInfo{\ShowPattern[George]{Washington}\\ % \ShowPattern{Miyazaki, Hayao}} % Previously, we have seen simple name patterns displayed in the margin, which look like the examples to the left of this paragraph. Now we show full name patterns, which indicate the ``system'' or data set to which they belong. Name patterns are control sequences that usually expand to the empty string. % They look like this:\footnote{To fit the information in the margin, we display them by taking the output of \cmd{\ShowPattern} and manually adding the system to correspond to the package internals.} % % \begin{quote} % \ttfamily\begin{tabular}{@{\qquad}l@{\quad \% }l} % \ShowPattern[George]{Washington}!MN & name, main matter\\ % \ShowPattern{Miyazaki, Hayao}!NF & name, front matter\\ % \ShowPattern[Jay]{Rockefeller}!PN & index cross-reference\\ % \ShowPattern[W.E.B.]{Du~Bois}!PRE & index sort tag\\ % \ShowPattern{Gregory, I}!TAG & index tag\\ % \ShowPattern[Schuyler]{Colfax}!DB & name tag\\ % \end{tabular} % \end{quote} % \negmedskip % % \begin{InfoBox} % From this point onward, we show index entries in the body text instead of the margin due to their increasing complexity. % \end{InfoBox} % \negmedskip % % \subsection[Name Patterns]{Name Pattern Overview} % \label{sec:NamePatterns} % % Below we show how macro arguments generate name patterns. The \meta{Alternate} argument only affects patterns when using the obsolete syntax (Section~\ref{sec:Obsolete}). The patterns govern names in both the text and the index. The colon at the beginning of each pattern prevents any collisions with extant macros: % % \begin{center} % \begin{tabular}{lll}\toprule % \rowcolor{nagrey}^^A % \bfseries Macro Arguments & \bfseries Patterns & \bfseries Name Type\\ % % \oarg{FNN}\marg{SNN} & % :\meta{FNN}!\meta{SNN} & Western\\ % \oarg{FNN}\marg{SNN}\oarg{Alt} & % :\meta{FNN}!\meta{SNN} & Western\\ % \oarg{FNN}\marg{SNN, Affix} & % :\meta{FNN}!\meta{SNN},\meta{Affix} & Western\\ % \oarg{FNN}\marg{SNN, Affix}\oarg{Alt} & % :\meta{FNN}!\meta{SNN},\meta{Affix} & Western\\ % % \rowcolor{nagrey}^^A % \hphantom{\oarg{FNN}}\marg{SNN, Affix} & % :\meta{SNN},\meta{Affix} & nonwestern\\ % \rowcolor{nagrey}^^A % \hphantom{\oarg{FNN}}\marg{SNN, Affix}\oarg{Alt} & % :\meta{SNN},\meta{Affix} & nonwestern\\ % % \hphantom{\oarg{FNN}}\marg{SNN}\oarg{Alt} & % :\meta{SNN},\meta{Alt} & old syntax\\ % % \rowcolor{nagrey}^^A % \hphantom{\oarg{FNN}}\marg{SNN} & % :\meta{SNN} & nonwestern\\\bottomrule % \end{tabular} % \end{center} % % \DescribeMacro{\NameauthPattern} % Every time a macro that takes name arguments is called (Section~\ref{sec:NameArgMacros}), the internal name category logic will \cmd{\let} the current name pattern to \cmd{\NameauthPattern}, making it available to formatting hooks (cf. Section~\ref{sec:DataTagHooks}). % % The name category logic is provided by \cmd{\@nameauth@Choice}, which determines the type of name (Western or nonwestern) by its arguments. Various \textsf{nameauth} macros append the appropriate ``system'' or name data set indicator to the pattern. We use this concept starting here, but mostly in Section~\ref{sec:AdvancedFormat}. % % Below are name patterns generated from name elements. We mark reversed Western names with a dagger (\dag) and names using the obsolete syntax with a double dagger (\ddag). We show that name patterns depend on name arguments, not on the appearance of a name. The obsolete nonwestern syntax and the current syntax share the same patterns. % % \begin{center} % \begin{tabular}{lll}\toprule % \rowcolor{nagrey}^^A % \bfseries Body Text & \bfseries \cmd{\ShowPattern} & \bfseries Macro\\ % % \Harnack[Adolf von] & \texttt{\ShowPattern[Adolf]{Harnack}} & % \cmd{\Harnack[Adolf von]}\\ % \LHarnack & \texttt{\ShowPattern[Adolf]{Harnack}} & % \cmd{\LHarnack}\\ % % \rowcolor{nagrey}^^A % \ForgetThis\Patton & \texttt{\ShowPattern[George S.]{Patton, Jr.}} & % \cmd{\ForgetThis}\cmd{\Patton}\\ % \rowcolor{nagrey}^^A % \DropAffix\LPatton & \texttt{\ShowPattern[George S.]{Patton, Jr.}} & % \cmd{\DropAffix}\cmd{\LPatton}\\ % % \ForgetThis\Noguchi & \texttt{\ShowPattern[Hideyo]{Noguchi}} & % \cmd{\ForgetThis}\cmd{\Noguchi}\\ % \RevName\LNoguchi\dag & \texttt{\ShowPattern[Hideyo]{Noguchi}} & % \cmd{\RevName}\cmd{\LNoguchi}\cmd{\dag}\\ % % \rowcolor{nagrey}^^A % \ForgetThis\Yamt & \texttt{\ShowPattern{Yamamoto,Isoroku}} & % \cmd{\ForgetThis}\cmd{\Yamt}\\ % \rowcolor{nagrey}^^A % \RevName\LYamt & \texttt{\ShowPattern{Yamamoto,Isoroku}} & % \cmd{\RevName}\cmd{\LYamt}\\ % % \Name{Henry,VIII} & \texttt{\ShowPattern{Henry,VIII}} & % \cmd{\Name\{Henry,VIII\}}\\ % \Name*{Henry}[VIII]\ddag & \texttt{\ShowPattern{Henry,VIII}} & % \cmd{\Name*\{Henry\}[VIII]}\cmd{\ddag}\\ % % \rowcolor{nagrey}^^A % \Dem[I Soter] & \texttt{\ShowPattern{Demetrius,I}} & \cmd{\Dem[I Soter]}\\ % \rowcolor{nagrey}^^A % \LDem & \texttt{\ShowPattern{Demetrius,I}} & \cmd{\LDem}\\ % % \ForgetThis\Aris & \texttt{\ShowPattern{Aristotle}} & % \cmd{\ForgetThis}\cmd{\Aris}\\ % \Aris & \texttt{\ShowPattern{Aristotle}} & % \cmd{\Aris}\\\bottomrule % \end{tabular} % \end{center} % % Six suffixes are appended to these patterns to create six ``systems'' or data sets. The \meta{pattern} element in the next table is the output of \cmd{\ShowPattern}. Within that \meta{pattern} is a leading colon, name elements with spaces removed, and delimiters that separate those elements. Western names use an exclamation point and a comma. Nonwestern names only use a comma. For the use of ID, see \cmd{\ShowNameState} on page~\pageref{page:NameState}. For the way that exclusions use the cross-reference system as a special case for preventing index interaction, see Section~\ref{sec:IdxFine}. % % \begin{center} % \begin{tabular}{llll}\toprule % \rowcolor{nagrey}^^A % \bfseries Description & \bfseries Pattern & \bfseries ID & \bfseries Example\\ % % Front-matter names & \meta{pattern}\texttt{!NF} & % front & \texttt{\ShowPattern[Adolf]{Harnack}{!NF}}\\ % % \rowcolor{nagrey}^^A % Main-matter names & \meta{pattern}\texttt{!MN} & main & % \texttt{\ShowPattern[Hideyo]{Noguchi}{!MN}}\\ % % Index cross-refs & \meta{pattern}\texttt{!PN} & % xref & \texttt{\ShowPattern{Yamamoto, Isoroku}{!PN}}\\ % % \rowcolor{nagrey}^^A % Exclusions & \meta{pattern}\texttt{!PN} & % excl & (like xref, special value)\\ % % Index sort tags & \meta{pattern}\texttt{!PRE} & pretag & % \texttt{\ShowPattern{Henry, VIII}{!PRE}}\\ % % \rowcolor{nagrey}^^A % Index data tags & \meta{pattern}\texttt{!TAG} & % idxtag & \texttt{\ShowPattern{Demetrius, I}{!TAG}}\\ % % Name data tags & \meta{pattern}\texttt{!DB} & namedb & % \texttt{\ShowPattern{Aristotle}{!DB}}\\\bottomrule % \end{tabular} % \end{center} % % Next we see what macros write patterns to what systems. \cmd{\IndexName} does not generate a name pattern. This lets cross-references determine the index control logic. % % \begin{center} % \begin{tabular}{lcccccc}\toprule[1pt] % \bfseries Macros & \bfseries \ttfamily \,!NF\, & \bfseries \ttfamily \,!MN\, & % \bfseries \ttfamily \,!PN\, & \bfseries \ttfamily !PRE & % \bfseries \ttfamily !TAG & \bfseries \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.\medskip % % \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{Quote}{\Name[Mark]{Twain}, \textit{The Innocents Abroad} (1869)} % Virtue never has been as respectable as money.^^A % \index{creatives, quotes of\noexpand\string|hyperpage} % \end{Quote} % % \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{Quote}{\Name[W.H.]{Auden}, \textit{Paris Review} interview (1972) p. 206} % I don't think the mystical experience can be verbalized. When the ego disappears, so does power over language.^^A % \index{creatives, quotes of\noexpand\string|hyperpage} % \end{Quote} % % \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}. % % \DescribeMacro{\ShowIdxPageref} % \cmd{\ShowIdxPageref} displays a full index entry in the text as if it were only a page entry, 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 a sort tag (Section~\ref{sec:IndexSort}), we get the following: % % \begin{quote} % |\PretagName[Hernando]{de~Soto}{Desoto, Hernando}| % % \IndexActual{@}\UntagName[Hernando]{de~Soto} % |\ShowIdxPageref[Hernando]{de~Soto}|\\ % \ShowIdxPageref[Hernando]{de~Soto} % \end{quote} % % We could not create index entries within the quote above in this \texttt{dtx} file because we changed \cmd{\IndexActual}. A \texttt{dtx} file uses a different default for \cmd{\IndexActual} (see Section~\ref{sec:IndexTag}). Here we get instead: % % \begin{quote} % |\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} % |\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}. % % \begin{itemize}\small % \item \Name*[J.E.]{Carter, Jr.}[James Earl]\dotfill^^A % |\Name*[J.E.]{Carter, Jr.}[James Earl]| % \item[] |\ShowNameInfo[J.E.]{Carter, Jr.}[James Earl]|:\\ % \ShowNameInfo[J.E.]{Carter, Jr.}[James Earl] % % \item \Name*{Miyazaki, Hayao}[Sensei]\dotfill^^A % |\Name*{Miyazaki, Hayao}[Sensei]| % \item[] |\ShowNameInfo{Miyazaki, Hayao}[Sensei]|:\\ % \ShowNameInfo{Miyazaki, Hayao}[Sensei] % % \item \Name*{Elizabeth, I}[I, ``Gloriana'']\dotfill^^A % |\Name*{Elizabeth, I}[I, ``Gloriana'']| % \item[] |\ShowNameInfo{Elizabeth, I}[I, ``Gloriana'']|:\\ % \ShowNameInfo{Elizabeth, I}[I, ``Gloriana''] % % \item \Name*{Henry}[VIII]\ddag\dotfill |\Name*{Henry}[VIII]\ddag| % \item[] |\ShowNameInfo{Henry}[VIII]| (obsolete syntax):\\ % \ShowNameInfo{Henry}[VIII] % % \item \Name*{Confucius}\dotfill |\Name*{Confucius}| % \item[] |\ShowNameInfo{Confucius}|:\\ % \ShowNameInfo{Confucius} % \end{itemize} % % For the following examples we activate alternate formatting % (Section~\ref{sec:AltFormat}), which permits typesetting more complex name forms seen in European academic writing. This use of small caps may generate harmless font substitution warnings. % % \AltFormatActive % \begin{itemize}\small % \item \ForgetThis\LStriet\\ % |\ForgetThis\Name[John]{\noexpand\de{Strietelmeier}| % \item[] |\ShowNameInfo[John]{\noexpand\de{Strietelmeier}}|:\\ % \ShowNameInfo[John]{\noexpand\de{Strietelmeier}} % % \item \Cath\\ % |\Name[Catherine \noexpand\AltCaps{d}e']{\noexpand\textSC{Medici}}| % \item[] |\ShowNameInfo[Catherine \noexpand\AltCaps{d}e']|\\ % |{\noexpand\textSC{Medici}}|:\\ % \ShowNameInfo[Catherine \noexpand\AltCaps{d}e']{\noexpand\textSC{Medici}} % % \item \Luth\\ % |\Name[Martin]{\noexpand\textSC{Luther}}| % \item[] |\ShowNameInfo[Martin]{\noexpand\textSC{Luther}}|:\\ % \ShowNameInfo[Martin]{\noexpand\textSC{Luther}} % % \item Using \cmd{\noexpand} before macros in name arguments ``fixates'' them, ensuring consistency (important for name patterns and the index): % \begin{itemize} % \item |\ShowNameInfo[John]{\noexpand\de{Strietelmeier}}| % \item[] \ShowNameInfo[John]{\noexpand\de{Strietelmeier}} % \item |\ShowNameInfo[John]{\de{Strietelmeier}}| % \item[] \footnotesize\ShowNameInfo [John]{\de{Strietelmeier}} % \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 % \negbigskip % % \NameArgWarning % % \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} % % \cmd{\ShowNameState} produces a line of text with the following information: % % \begin{itemize} % \item Base name pattern, the base control pattern that % \textsf{nameauth} sees. This would be the output of \cmd{\ShowPattern}. % \item Type of name, referring to how the name in the argument was parsed. % % \begin{itemize}[leftmargin=3.7em] % \item[w :] Western (regardless of whether it is reversed) % \item[nw :] nonwestern (regardless of whether it is reversed)\\ % current syntax % \item[nw,os :] nonwestern name, obsolete syntax (Section~\ref{sec:Obsolete}) % \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 example we show names in indexing states from one to six, and we illustrate all name types and many of the control systems. All extant names have index tags due to being used in a \texttt{dtx} file with the \textsf{ltxdoc} class and the \textsf{hypdoc} package (Section~\ref{sec:SpecialTag}). Otherwise, names need not always have a control pattern in the \texttt{idxtag} system. % % \begin{itemize} % \item Some yet unused name:\dotfill |\ShowNameState{Not Seen, Yet}|\\ % \ShowNameState{Not Seen, Yet} % % \item New and extant names: % \begin{itemize} % \item \Name*[Rudolph]{Carnap}\dotfill |\Name*[Rudolph]{Carnap}|\\ % \ShowNameState[Rudolph]{Carnap} % % \item \Name*{Henry, VIII}\dotfill |\Name*{Henry, VIII}|\\ % \ShowNameState{Henry, VIII} % % \item \Name*{Henry}[VIII]\ddag\dotfill |\Name*{Henry}[VIII]\ddag|\\ % \ShowNameState{Henry}[VIII] % % \item \Name*{Thomas, à~Kempis}\dotfill |\Name*{Thomas, à~Kempis}|\\ % \ShowNameState{Thomas, à~Kempis} % \end{itemize} % % \item Name used only in xref:\dotfill^^A % |\IndexRef{Sun King}{Louis XIV}|\IndexRef{Sun King}{Louis XIV}\\ % \ShowNameState{Sun King} % % \item Name used after xref exists:\\ % \Name*{Sun King}\dotfill |\Name*{Sun King}|\\ % \ShowNameState{Sun King} % % \item Unused name excluded from index:\dotfill^^A % \ExcludeName{Santa, Claus}|\ExcludeName{Santa, Claus}|\\ % \ShowNameState{Santa, Claus} % % \item Previously excluded name gets used:\\ % \Name*{Thomas,\`a~Kempis}\dotfill |\Name*{Thomas,\`a~Kempis}|\\ % \ShowNameState{Thomas,\`a~Kempis} % \end{itemize} % \negbigskip % % \ReturnLink\smallskip % % \AltFormatActive % \begin{Quote}{\ForgetThis\Luth\break % \hbox{}\hfill \textit{\de{Von der Freiheit eines Christenmenschen}} (1520)} % \de{Eyn Chriſten menſch iſt eyn freyer herr / % u\raise 0.2ex\hbox{\kern -1.1ex\textsuperscript{e}\kern 1pt}ber alle % ding / und niemande unterthan. Eyn Chriſten menſch iſt eyn dienſtpar % knecht aller ding und yderman unterthan.} % % (A Christian person is a free lord, above all things, and subject to no one. A Christian person is a willing servant of all things and is subject to % everyone.)^^A % \index{theologians, quotes of\noexpand\string|hyperpage} % \end{Quote} % \AltFormatInactive % % \newpage % % \section{Indexing Macros} % \label{sec:Indexing} % \IndexWarnVerbose % % Indexing pulls together all the concepts from the previous sections, yet applies them to the index. In this section we enable (and trigger) verbose index warnings. % % \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}. % % \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. % \vspace{3ex} % \Info{\hrule\strut Test indexing rules:\break % \Name{Yamaha, Torakusu}\label{page:Idx1}\break % create index entry:\break % \cmd{\IndexName}\break % \texttt{\{Nippon Gakki\}}\IndexName{Nippon Gakki}\strut\hrule} % \vspace{-3ex} % % \ifdefined\NameauthDoTestFiles \edef\NameauthTestFile{test07_01.tex}\else % \edef\NameauthTestFile{\jobname.tmp}\fi % % \begin{VerbatimOut}{\NameauthTestFile} % \documentclass{article} % \input{compat.tex} % Included with nameauth; example file aids % % compatibility across different LaTeX versions and engines. % % \usepackage{makeidx} % Must have for defining \seealso macro. % \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} % \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. % % \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. % % One can use \cmd{\IndexProtect} right before \cmd{\printindex} to protect the index against bogus output. For example: % % \vspace{4ex} % \Info{\hrule\strut Test indexing rules:\break % \Name{Yamaha, Torakusu}\label{page:Idx2}\strut\hrule} % \vspace{-4ex} % \begin{itemize} % \item |\Name{foo\Name{bar}}| in the text generates \Name{foo\Name{bar}}. % Notice that the internal locks prevent |\Name{bar}| from producing % output in the text. % \item The first \LaTeX\ pass creates |\indexentry{foo\Name {bar}}| % in the \texttt{idx} file. With enough passes, using also % \texttt{makeindex}, in the \texttt{ind} file we get both % |\item foo\Name {bar}| from the text and an additional % |\item bar| from the macro executed in the index. % \item That gives one index entry ``foo{\NamesFormat bar}'' and % another entry ``bar''. % \item Using \cmd{\IndexProtect} \cmd{\printindex} still permits % the index entry generated by |\item foo\Name {bar}|, but it does not % allow |\Name {bar}| to generate any output or additional entries % in the index. % \item We get only one entry ``foo'', similar to what we see in the text. % This manual uses the tag \S\ for \cmd{\Name\{foo}\cmd{\Name\{bar\}\}}, % not shown in the example for the sake of clarity. % \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 nonwestern syntax (Section~\ref{sec:Obsolete}). Indexing follows [\hyperlink{Mulvany}{Mulvany}, 152--82]. The points below deal with macros explained in Section~\ref{sec:IdxPrefix}. % % \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 entries. \textit{See also} references occur at the end of an entry with page entries or sub-entries. % % \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 might forget that the latter has four arguments, at least two of which are required. Missing text and bad xrefs can result. % % \begin{itemize} % \item Define \textit{see} references \emph{before} making any % \cmd{\Name} entries for them. % \vspace{-1ex} % \Info{\hrule\strut Test indexing rules:\break % Creating \textit{see also} xref\break\footnotesize % \cmd{\SeeAlso}\cmd{\IndexRef}\break\ttfamily % \{Yamaha, Torakusu\}\break % \{Nippon Gakki\}\SeeAlso\IndexRef{Yamaha, Torakusu}{Nippon Gakki}^^A % \label{page:Idx3}\strut\hrule} % \vspace{1ex} % \item Define \textit{see also} references \emph{after} all % \cmd{\Name} instances to the respective names have been created. % \item \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} % \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} % \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. % % \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 prevent and permit all indexing, \cmd{\ExcludeName} only excludes a specific name from being printed as a page entry or cross-reference in the index. See the following example, as well as examples in Sections~\ref{sec:NameParticles} and \ref{sec:VarNames}. Indexing remains active: % % \begin{VerbatimOut}{\jobname.tmp} % \ExcludeName{Mr. Baseball} % In this example we cannot get page entries for % \Name{Mr. Baseball}, the nickname of % \Name[Bob]{Uecker}, because it was excluded. % \end{VerbatimOut} % % \begin{quote} % \vspace{3ex} % \PatInfo{\ShowPattern{Mr. Baseball}!PN\break % \ShowPattern[Bob]{Uecker}!MN} % \vspace{-3ex} % \VerbatimInput[gobble=0]{\jobname.tmp} % % \input{\jobname.tmp} % \end{quote} % % \DescribeMacro{\IncludeName} % Use the following macros to break a few indexing rules. They remove 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 entries to a name in the index that had been used as a cross-reference. % % Analogously, \cmd{\ForgetName} (Section~\ref{sec:NameControl}) removes name control patterns, allowing one to create a cross-reference. Section~\ref{sec:RuleStates} explains this behavior as a set of states. Below we run some tests (cf. Section~\ref{sec:NameTests}) and produce a few warnings because verbose warnings are active here. % \vspace{3ex} % \Info{\hrule\strut Test indexing rules:\break % \Name{Yamaha, Torakusu}\label{page:Idx4}\strut\hrule} % \vspace{-3ex} % % \begin{VerbatimOut}{\jobname.tmp} % \begin{itemize} % \item \Name*{Mr. Baseball} is % \IfAKA{Mr. Baseball} % {\meta{an xref}}{\meta{a name}}{\meta{excluded}}. % % \item Making an xref fails.\IndexRef{Mr. Baseball}{Uecker, Bob} % \Name*{Mr. Baseball} is still % \IfAKA{Mr. Baseball} % {\meta{an xref}}{\meta{a name}}{\meta{excluded}}. % % \item The inclusion macro\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. % % \item Instead, we forget the name\ForgetName{Mr. Baseball} % to destroy the name pattern 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}}}} % {\meta{excluded}}. % % \item Making another xref\IndexRef{Mr. Baseball}{Uecker, Bob} creates % \IfAKA{Mr. Baseball} % {\meta{an xref}}{\meta{a name}}{\meta{excluded}}. % \end{itemize} % \end{VerbatimOut} % % \begin{quote} % \VerbatimInput[gobble=0]{\jobname.tmp} % % \input{\jobname.tmp} % \end{quote} % % Cross-references get more protection than exclusions: % \vspace{-1ex} % \PatInfo{\ShowPattern[J.D.]{Rockefeller, IV}!MN\break % \ShowPattern[Jay]{Rockefeller}!PN\break % \ShowPattern[Jay]{Rockefeller}!MN} % \vspace{1ex} % \begin{VerbatimOut}{\jobname.tmp} % \begin{itemize} % \item \DropAffix\LJRIV[Jay] was indexed as % ``\ShowIdxPageref*[J.D.]{Rockefeller, IV}. % % \item We create the % xref\IndexRef[Jay]{Rockefeller}{Rockefeller, J.D., IV}. % % \item The test calls \SJRIV[Jay] an % \IfAKA[Jay]{Rockefeller}{\meta{xref}}{\meta{name}}{}. % % \item After being ``included''\IncludeName[Jay]{Rockefeller} % he still is an % \IfAKA[Jay]{Rockefeller}{\meta{xref}}{\meta{name}}{}. % % \item After ``forced inclusion''\IncludeName*[Jay]{Rockefeller} % he can be a \IfAKA[Jay]{Rockefeller}{\meta{xref}}{\meta{name}}{} % and create page entries. % \end{itemize} % \end{VerbatimOut} % % \begin{quote} % \VerbatimInput[gobble=0]{\jobname.tmp} % % \input{\jobname.tmp} % \end{quote} % % \begin{InfoBox} % Using \cmd{\IncludeName*} is necessary when creating index sub-entries for a name using \cmd{\IndexTag}. If one creates a cross-reference in any sub-entry of a name, \cmd{\IncludeName*} will permit additional page entries to be made for the other sub-entries of that name or for the name itself. See Section~\ref{sec:CatSub}. % \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}. % % \DescribeMacro{\SeeAlso} % Put \cmd{\SeeAlso} before \cmd{\IndexRef}, \cmd{\AKA}, and \cmd{\PName} (Section~\ref{sec:AKA}) to make a \textit{see also} reference for a name that has appeared already in the index. If enabled before invoking \cmd{\PName}, \cmd{\SeeAlso} will be disabled when the regular name is generated, then enabled when the cross-reference is generated. % \vspace{3ex} % \Info{\hrule\strut Test indexing rules:\break % \Name{Nippon Gakki}\label{page:Idx5}\strut\hrule} % \vspace{-3ex} % % \begin{VerbatimOut}{\jobname.tmp} % One can refer to \Name[the]{Rat Pack} as a group of entertainers % including \Name[Sammy]{Davis, Jr.}, \Name[Dean]{Martin}, and % \Name[Frank]{Sinatra}. No more page entries for % \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} % \VerbatimInput[gobble=0]{\jobname.tmp} % % \input{\jobname.tmp} % \end{quote} % % Currently \cmd{\IndexName} and other \textsf{nameauth} macros that create index entries will reset the Boolean flag governed by \cmd{\SeeAlso} unless one uses the \texttt{oldreset} option. preventing a stray use of the macro from affecting the index. % % \DescribeMacro{\SkipIndex} % The prefix macro \cmd{\SkipIndex} will suppress indexing for just one instance of a name displayed by a naming macro. |\SkipIndex\Name[Monty]{Python}| produces \SkipIndex\Name[Monty]{Python} in the text, but with no index entry. \cmd{\SkipIndex} works with the naming macros. Side effects include: % % \begin{itemize} % \item Unless the \texttt{oldreset} option is used, both \cmd{\IndexName} % and \cmd{\IndexRef} issue warnings if \cmd{\SkipIndex} precedes them. % Then, both \cmd{\IndexName} and \cmd{\IndexRef} ignore \cmd{\SkipIndex} % and reset its flag. % % \item When the \texttt{oldreset} option is used, both \cmd{\PName} % and \cmd{\PName*} issue warnings when % {\ttfamily \string \if@nameauth@SkipIndex} is true on exit. % \end{itemize} % % \DescribeMacro{\JustIndex} % This prefix macro makes \cmd{\Name}, \cmd{\Name*}, \cmd{\FName}, and the quick interface shorthand macros act similar to \cmd{\IndexName}. \cmd{\JustIndex} suppresses name output in the text, but flags for long and first name forms are reset as if the naming macro had produced output. Using the \texttt{oldreset} option prevents these flags from being reset, completely mimicking a call to \cmd{\IndexName}. % % \begin{center} % \begin{tabular}{lll}\toprule % \rowcolor{nagrey}^^A % \bfseries Option & \bfseries Output & \bfseries Source\\ % % default & \JustIndex\SWash \Wash & |\JustIndex\SWash \Wash|\\ % % default & \JustIndex\LWash \Wash & |\JustIndex\LWash \Wash|\\ % % \rowcolor{nagrey}^^A % \makeatletter\global\@nameauth@OldPasstrue\makeatother^^A % \ttfamily oldpass & \JustIndex\SWash \Wash & % |\JustIndex\SWash \Wash|\\ % \rowcolor{nagrey}^^A % \ttfamily oldpass & \JustIndex\LWash \Wash & % |\JustIndex\LWash \Wash|\\\bottomrule % \makeatletter\global\@nameauth@OldPassfalse\makeatother^^A % \end{tabular} % \vspace{-16ex}\PatInfo{\ShowPattern[George]{Washington}!MN}\vspace{14ex} % \end{center} % % There are potential side effects related to \cmd{\JustIndex}: % % \begin{itemize} % \item Both \cmd{\AKA} and \cmd{\PName} ignore \cmd{\JustIndex} % and go on about their business. They also set % \cmd{\@nameauth@JustIndexfalse}. % \item \cmd{\JustIndex} resets the flags set by \cmd{\ForgetThis} % and \cmd{\SubvertThis}, preventing them from passing through. % \item The following three lines are equivalent: % \begin{itemize} % \phantomsection % \Info{\hrule\strut Test indexing rules:\break % Creating \textit{see} xref\break\footnotesize % \cmd{\IndexRef}\ttfamily \{Nippon Gakki\}\break % \{Yamaha Corp.\}^^A % \IndexRef{Nippon Gakki}{Yamaha Corp.}^^A % \label{page:Idx6}\strut\hrule} % \item\cmd{\JustIndex} \cmd{\SkipIndex} % \cmd{\Name\{A\}} \cmd{\Name\{B\}} % \item\cmd{\SkipIndex} \cmd{\JustIndex} % \cmd{\Name\{A\}} \cmd{\Name\{B\}} % \item\cmd{\JustIndex} \cmd{\Name\{A\}} % \cmd{\SkipIndex} \cmd{\Name\{B\}} % \end{itemize} % \cmd{\JustIndex} takes priority with \cmd{\Name\{A\}} and passes % \cmd{\SkipIndex} to \cmd{\Name\{B\}} % (see also Section~\ref{sec:Priorities}). % \item \cmd{\JustIndex} and the naming macros do not replace \cmd{\IndexRef}. % \end{itemize} % % \subsection{Automatic Rules} % \label{sec:IdxRules} % % Below we indicate what to expect regarding index rules in any given state. Here we do not attempt to concatenate page ranges. Above, we put a series of names and cross-references in margin notes, Here is the result: % % \begin{center}\footnotesize % \begin{tabular}{rp{0.3\textwidth}p{0.5\textwidth}}\toprule % \rowcolor{nagrey}^^A % \bfseries Page & \bfseries Macro & \bfseries Index Result\\ % % \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}\\ % % \rowcolor{nagrey}^^A % \pageref{page:Idx2} & % \cmd{\Name\{Yamaha, Torakusu\}} & % \ShowIdxPageref*{Yamaha, Torakusu}, \pageref{page:Idx1}, % \pageref{page:Idx2}\par % \ShowIdxPageref*{Nippon Gakki}, \pageref{page:Idx1}\\ % % \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}\\ % % \rowcolor{nagrey}^^A % \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}\\ % % \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}\\ % % \rowcolor{nagrey}^^A % \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. % % 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} % \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} % \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} % {\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} % % \IndexRef{\textit{Doctor angelicus}}{Thomas Aquinas} % % Perhaps the greatest medieval theologian was % \Name{Thomas, Aquinas}, later known as % \Name{\textit{Doctor angelicus}}. % \end{quote} % % To give \Name{\textit{Doctor angelicus}} page entries and a \textit{see also} reference, we omit line~2 above, wait until the end of the body text, after both names are fully indexed, and then use: % \fbox{\cmd{\SeeAlso}\cmd{\IndexRef\{}\cmd{\textit\{Doctor angelicus\}\}\{Thomas Aquinas\}}}. % % \subsubsection*{\hfil Name Particles} % % Spaces change sorting. For example, the sort tag \texttt{De\textvisiblespace Soto} precedes \texttt{deal} due to the space therein. The sort tag \texttt{DeSoto} falls as expected between \texttt{derp} and \texttt{determinism}. % % \subsubsection*{\hfil Collating Sequences} % % German \textsf{ä ö ü ß} map to English \textsf{ae oe ue ss}. Yet Norwegian \textsf{æ ø å} follow \textsf{z} in that order. Check a style guide regarding collating sequences, spaces, and sorting. This is where using \texttt{xindy} can be very helpful. See also Section~\ref{sec:NameParticles}. % % \subsubsection*{\hfil Alternate Formatting} % % Additional examples starting with Section~\ref{sec:RealAltEx} deal with index sorting as it relates to alternate formatting, ``Continental'' practice, and macros in name arguments. Please ensure that such macros expand to the form desired in the index in order to get proper sorting with \cmd{\PretagName}. % % \begin{Quote}{\Name[Publius]{Vegetius Renatus}, \textit{De re militari} (c. 390)} % Igitur qui desiderat pacem, praeparet bellum. % % (Accordingly, the person who would desire peace prepares for war.)^^A % \index{Romans, quotes of\noexpand\string|hyperpage} % \end{Quote} % % \subsubsection{Sorting Initials} % \label{sec:IndexInitials} % \negbigskip % % \begin{InfoBox} % In order to sort the index consistently and properly, all names % should be sorted by their longer name forms, not their initials. % \end{InfoBox} % % Sorting \Name*[J.D.]{Rockefeller, IV} |\Name*[J.D.]{Rockefeller, IV}| presents a problem that does not occur with \Name*[Clive Staples]{Lewis} |\Name*[Clive Staples]{Lewis}|. In the case of \Name*[J.D.]{Rockefeller, IV}[Jay], the initials will appear in the index, while with \Name*[Clive Staples]{Lewis}[C.S.], the longer names will appear in the index. % % In \textsf{nameauth} we have a specific way to do that once per name, and all the remaining names will be sorted as expected. Before we use a name like \Name[J.D.]{Rockefeller, IV}, preferably in the preamble, we use the following macro: % % \begin{quote} % |\PretagName[J.D.]{Rockefeller, IV}{Rockefeller, John D 4}| % % \begin{itemize} % \item The index entry is ``\ShowIdxPageref*[J.D.]{Rockefeller, IV}''. % % \item In the ``pretag'' we spell out the first forename % and add enough of the second to get a unique sorting key. % % \item We turn the Roman numeral affix into an Arabic numeral % so that it does not sort like letters. % \end{itemize} % \end{quote} % % For more examples 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 data tags are information added automatically to index page entries for names used with \textsf{nameauth} macros. % % \subsubsection{General Approach} % % \DescribeMacro{\TagName} % This macro creates a tag that persists until one changes it with \cmd{\TagName} or destroys it with \cmd{\UntagName}. % \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} % \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 helpful in the indexes of academic texts by adding dates, titles, etc. \cmd{\TagName} causes the \textsf{nameauth} indexing macros to append % {\ttfamily\fbox{\textvisiblespace the Great, pope}} % to the index entries created in the next example: % % \begin{quote} % \vspace{3.5ex} % \PatInfo{\ShowPattern{Gregory, I}!TAG\break % \ShowPattern{Gregory, I}!MN} % \vspace{-3.5ex} % \begin{Verbatim} % \TagName{Gregory, I}{ the Great, pope} % Pope \Name*{Gregory, I} was known as \Name*{Gregory, I} % [the Great]. % \end{Verbatim} % % Pope \Name*{Gregory, I} was known as \Name*{Gregory, I} % [the Great]. % \end{quote} % % See Section~\ref{sec:NameAncient} for more ways to deal with ancient names. \cmd{\TagName} works with all names that produce index page entries. It does not work with with cross-references produced by \cmd{\IndexRef}, \cmd{\AKA}, etc. % Tags can hold different kinds of information, but they should not be verbose. They can include daggers, asterisks, and so on. For example, all fictional names in the index of this manual are tagged with \S. One must add any desired spaces to the start of the tag. % % \subsubsection[Identical Names]{Disambiguating Identical Names} % % 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} % \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, neither \textsf{nameauth} nor regular use of \cmd{\index} creates hyperlinked page entries. Index data tags in the || section of the \texttt{dtx} file, which reads the ``commented'' part of the \texttt{dtx} file into a \texttt{document} environment, take the form: % % \begin{quote} % \cmd{\TagName}\meta{name args}\texttt{\{\textbar hyperpage\}} % \end{quote} % % Within the ``commented'' part of the package documentation in this \texttt{dtx} file, the vertical bar is active. Hence, we use: % % \begin{quote} % \cmd{\TagName}\meta{name args}\texttt{\{}\cmd{\noexpand}\cmd{\string\textbar hyperpage\}}\\[0.5ex] % or\\[0.5ex] % \cmd{\index\{}\meta{entry argument}\cmd{\noexpand}\cmd{\string \textbar hyperpage\}} % \end{quote} % % 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} % \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} % % \subsubsection*{\hfil Manual Breaks and Entries} % % The \textsf{microtype} package and its \texttt{Spacing} environment may be the best solution to fix index entries and sub-entries that break badly across columns or pages. Yet we could add manual breaks after editing is complete. % % We must create a helper macro that takes an argument and adds a break after that argument. That is how macros like \cmd{\textbf} use implied page entries in the index, e.g.: \cmd{\index\{Doe, John\string|textbf\}}. % % Below we use \cmd{\newpage} to jump to a new column. See also the \textsf{multicol} and \textsf{idxlayout} packages, as well as classes like \textsf{memoir}. On line~1 we define the \cmd{\Endbreak} macro that will break the column after the end of an index entry. % % \begin{quote} % |\newcommand*{\EndBreak}[1]{#1\newpage}| % \end{quote} % % We use \cmd{\EndBreak} after the last page in a given entry. This method works for both manual index entries and for the \textsf{nameauth} macros. If all instances of \cmd{\Name\{Some, Name\}} on the same page have that same index tag, there will be no duplicate page entries, hyperlinks will work, and the index will break as indicated: % % \begin{center} % \begin{tabular}{rll}\toprule % \rowcolor{nagrey}^^A % \bfseries Page & \bfseries Macro & \bfseries Index Result\\ % % 10 & \cmd{\Name\{Some, Name\}} & Some Name, 10\\ % & \cmd{\index\{Topic\}} & Topic, 10\\ % % \rowcolor{nagrey}^^A % 15 & \cmd{\Name\{Some, Name\}} & Some Name, 10, 15\\ % \rowcolor{nagrey}^^A % & \cmd{\index\{Topic\}} & Topic, 10, 15\\ % % 18 & \cmd{\TagName\{Some, Name\textbar EndBreak\}\%} & \\ % & \cmd{\Name\{Some, Name\}} & % Some Name, 10, 15, 18\meta{break}\\ % & % \cmd{\index\{Topic\textbar EndBreak\}} & % Topic, 10, 15, 18\meta{break}\\\bottomrule % \end{tabular} % \end{center} % % We do not have to supply an argument to \cmd{\EndBreak} because, as with the font switching example above, the page entry is implied. % % We can intermix \textsf{nameauth} macros with manual index entries. We may need to look at the \texttt{idx} or \texttt{ind} files to craft matching entries on the page where the break occurs. Instead of using \cmd{\TagName}, we also can do this: % % \begin{center} % \begin{tabular}{rll}\toprule % \rowcolor{nagrey}^^A % \bfseries Page & \bfseries Macro & \bfseries Index Result\\ % % 18 & \cmd{\SkipIndex}\cmd{\Name\{Some, Name\}\%}\hfill\hbox{} & \\ % & \cmd{\index\{Some Name\textbar EndBreak\}}\dotfill \hbox{} & % Some Name, 10, 15, 18\meta{break}\\\bottomrule % \end{tabular} % \end{center} % % Results for manual entries may vary, depending on what distribution of \LaTeX\ is being used and how old it is. Any name with active characters needs to be handled differently before 2018 than after 2018. All instances of \cmd{\index\{Some Name\textbar EndBreak\}} must fall on the same page. % % We do not\Warn\ recommend breaking an index entry in the middle. There are several discussions, such as \href{https://tex.stackexchange.com/questions/86646/indexing-subentries-and-see-also}{\bfseries this page} and \href{https://tex.stackexchange.com/questions/231840/what-is-the-proper-use-of-several-seealso-in-the-same-index-entry-with-makeinde}{\bfseries that page}. A ``quick and dirty'' version corresponding to the \cmd{\EndBreak} macro follows: % % \begin{quote} % \begin{Verbatim} % \makeatletter % \newcommand*{\MidBreak}[1]{#1\newpage\@gobble} % \makeatother % \end{Verbatim} % \end{quote} % % Nevertheless, it is clear from some discussions that such macros can be rather fiddly at times and can produce unexpected results. One is advised to take caution when breaking index entries midway or otherwise modifying them in this manner. % % \subsection[Categories/Sub-entries]{Categories and Sub-entries} % \label{sec:CatSub} % % Indexes can have categories and sub-entries such as the following: % % \begin{itemize} % \item[] \meta{category 1} % \begin{itemize} % \item[] \meta{name entry} % \begin{itemize} % \item[] \meta{name sub-entry 1} % \item[] \meta{name sub-entry 2}\dots % \end{itemize} % \item[] \meta{name entry}\dots % \end{itemize} % \item[] \meta{category 2}\dots % \end{itemize} % % To get \textsf{nameauth} to work with this structure, one must use both \cmd{\PretagName} and \cmd{\TagName}. For example, to sort a name under \meta{category}, use something like: % % \begin{SyntaxBox} % \cmd{\PretagName}\oarg{FNN}\marg{SNN}\texttt % {\{}\meta{category 1}\texttt{!}\meta{SNN}\texttt % {, }\meta{FNN}\texttt{\}}\\ % \cmd{\PretagName}\marg{SNN, Affix}\texttt % {\{}\meta{category 1}\texttt{!}\meta{SNN} \meta{Affix}\texttt{\}} % \end{SyntaxBox} % % Whenever one wants to generate a sub-entry for a name, one can use \cmd{\TagName} to create that sub-entry when needed via something like: % % \begin{SyntaxBox} % \cmd{\TagName}\oarg{FNN}\marg{SNN}\texttt % {\{!}\meta{name sub-entry}\texttt{\}}\\ % \cmd{\TagName}\marg{SNN, Affix}\texttt % {\{!}\meta{name sub-entry}\texttt{\}} % \end{SyntaxBox} % % One is not restricted to Western or nonwestern name arguments; the boxes above are meant just to show the basic tag formats. % % \newpage % % One could use \Warn\cmd{\TagName} to change to another sub-entry or the default tag as needed, or use \cmd{\UntagName} to remove the tag. If a sub-entry contains a cross-reference via \cmd{\IndexRef}, it is necessary to follow that with \cmd{\IncludeName*} to permit any further page entries in other sub-entries or the main name entry. Below we demonstrate how one would implement sub-entries using index tags in a normal \LaTeX\ document. We cannot show categories when using \texttt{gind.ist}. % % 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; example file aids % % compatibility across different LaTeX versions and engines. % \usepackage[a6paper,landscape,left=1cm,right=1cm]{geometry} % \usepackage{makeidx} % \usepackage{nameauth} % % \makeindex % % \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} % \VerbatimInput[gobble=0]{\NameauthTestFile} % \end{quote} % % \newpage % % Below we show only the index from this example. % A few notable features include: % % \begin{itemize} % \item \Patton\ uses a regular index tag instead of a subcategory. % That is a way to `cheat'' and get more groupings of entries % than allowed categories. % \item \Ike\ illustrates multiple subcategories for a name. A % cross-reference from a sub-entry of US presidents points to him. % \item \Wash\ illustrates having both a super-category and a subcategory. % \item \Ike, \Patton, and \Sun\ are not sorted under categories. The % other names are sorted under categories. % \end{itemize} % \JustIndex\MLK \JustIndex\Doug \JustIndex\Aeth \JustIndex\Soto % \JustIndex\Aris \JustIndex\Plato \JustIndex\Linc % % \begin{tcolorbox}[colback=white] % \IfFileExists{cat01.pdf}{\includegraphics[scale=0.85]{cat01.pdf}} % {\hbox{\vbox to 8cm{\hbox{\hfill}}}} % \end{tcolorbox} % \JustIndex\Wash \JustIndex\Ike % \IndexWarnTerse % % \ReturnLink % % \begin{Quote}{\Linc, \textit{Gettysburg Address} (19 November 1863)} % Four score and seven years ago our fathers brought forth on this continent, a new nation, conceived in Liberty, and dedicated to the proposition that all men are created equal. \dots It is for us the living, rather, to be dedicated here to the unfinished work which they who fought here have thus far so nobly advanced. It is rather for us to be here dedicated to the great task remaining before us\,---\,that from these honored dead we take increased devotion to that cause for which they gave the last full measure of devotion\,---\,that we here highly resolve that these dead shall not have died in vain\,---\,that this nation, under God, shall have a new birth of freedom\,---\,and that government of the people, by the people, for the people, shall not perish from the earth.^^A % \index{politicians, quotes of\noexpand\string|hyperpage} % \end{Quote} % % \newpage % % \section{Name Tags} % \label{sec:DataTags} % % \DescribeMacro{\NameAddInfo} % All valid names in \textsf{nameauth} can have name tags; no restrictions exist. Unlike index tags, name tags are not printed automatically with every name managed by \textsf{nameauth}. Sections~\ref{sec:NameTests} and~\ref{sec:DataTagHooks} have more examples. The macro is \cmd{\long}, allowing for some complexity in the \meta{tag} argument: % % \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 name tag but does not print whenever \Wash\ \cmd{\Wash} is used. The name tag needs to be displayed using the helper macro below. % % \DescribeMacro{\NameQueryInfo} % To print a name tag for a given name, we use \cmd{\NameQueryInfo}, a helper macro that prints a name tag in the name info data set: % % \begin{SyntaxBox} % \cmd{\NameQueryInfo}\oarg{FNN}\marg{SNN|,| Affix}\oarg{Alternate} % \end{SyntaxBox} % % \cmd{\NameQueryInfo[George]\{Washington\}} prints the name tag for \LWash: % \NameQueryInfo[George]{Washington}. In Section~\ref{sec:DataTagHooks} and thereafter we show how one can automate the retrieval of name tags using formatting hooks, Yet therein also lies a caution: % % \begin{itemize} % \item When using the recommended template for a formatting hook (Section~\ref{sec:DataTemp}), one can use \cmd{\noexpand} in arguments for \cmd{\NameAddInfo}, \cmd{\NameQueryInfo}, and \cmd{\NameClearInfo} without restriction. % % \item When using designs based on older templates, using \cmd{\noexpand} may cause \cmd{\NameQueryInfo} to print nothing if one uses the basic interface. Using the quick interface will work as expected. % \end{itemize} % % One can insert a space at the start of a name tag; use signs like asterisks, daggers, and the like; and even create footnotes, such as footnote \addtocounter{footnote}{1}\arabic{footnote}\addtocounter{footnote}{-1} (below): % % \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} % \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} % % \newpage % % The previous\Warn{} example cannot be used in a formatting hook (Section~\ref{sec:DataTagHooks}). Within the formatting hooks, one is in a ``locked path'' that prevents calling a naming macro. This prevents a stack overflow. |\Name*[Ulysses S.]{Grant}| would not print inside a formatting hook, although |\NameQueryInfo[Ulysses S.]{Grant}| would print. % % Name\Warn{} tags can call each other. To protect against a stack overflow, use Boolean flags and conditional statements. Below, \cmd{\NameQueryInfo} calls a tag that sets a Boolean flag true, which causes the \emph{other} tag to stop any recursion and exit. % % \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} % \VerbatimInput[gobble=0]{\jobname.tmp} % % \input{\jobname.tmp} % \end{quote} % % \DescribeMacro{\NameClearInfo} % \cmd{\NameAddInfo} will replace one name tag with another name tag, but it does not delete a tag. That is the role of \cmd{\NameClearInfo}. The syntax is: % % \begin{SyntaxBox} % \cmd{\NameClearInfo}\oarg{FNN}\marg{SNN|,| Affix}\oarg{Alternate} % \end{SyntaxBox} % % We now revisit \LWash\ and his associated name tag. \PatInfo{\ShowPattern[George]{Washington}!DB} % % \begin{VerbatimOut}{\jobname.tmp} % The name tag is: \fbox{\NameQueryInfo[George]{Washington}}\quad % Clearing data.\NameClearInfo[George]{Washington}\quad % The name tag is empty: \fbox{\NameQueryInfo[George]{Washington}} % \end{VerbatimOut} % % \begin{quote} % \VerbatimInput[gobble=0]{\jobname.tmp} % % \input{\jobname.tmp} % \end{quote} % \ReturnLink % % \begin{Quote}{\ForgetThis\Name{Confucius}, \textit{The Analects}, C II (475–221 \textsc{bc})} % He who exercises government by means of his virtue may be compared to the north polar star, which keeps its place and all the stars turn towards it.^^A % \index{north star, concept of\noexpand\string|hyperpage}^^A % \index{philosophers, quotes of\noexpand\string|hyperpage} % \end{Quote} % % \newpage % % \section[Formatting and Decisions]{Basic Formatting and Name Decisions} % \label{sec:FormatChoice} % % \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={\large\hfil Syntactic Changes; % No Formatting/Post-Processing}]\centering % \begin{tabular}{llll}\toprule % \bfseries First Instance & \bfseries Macro & \bfseries Later Instance & \bfseries Macro\\\midrule % \ForgetThis\Patton & \cmd{\Patton} & \Patton & \cmd{\Patton}\\ % \ForgetThis\LPatton & \cmd{\LPatton} & \LPatton & \cmd{\LPatton}\\ % \ForgetThis\SPatton & \cmd{\SPatton} & \SPatton & \cmd{\SPatton}\\\midrule % \ForgetThis\Yamt & \cmd{\Yamt} & \Yamt & \cmd{\Yamt}\\ % \ForgetThis\LYamt & \cmd{\LYamt} & \LYamt & \cmd{\LYamt}\\ % \ForgetThis\SYamt & \cmd{\SYamt} & \SYamt & \cmd{\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 First instance of a name % \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 Subsequent instance of a name % \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}). % % \DescribeMacro{\NamesActive} % Independent ``main-matter'' and ``front-matter'' systems are used to format first and subsequent name uses. % \DescribeMacro{\NamesInactive} % \cmd{\NamesInactive} and the \texttt{frontmatter} option enable the front-matter system. \cmd{\NamesActive} switches names to the main-matter system. The \texttt{mainmatter} option is the default setting for names. % % These\Info{\cmd{\global}} two macros can be used explicitly as a pair or singly within an explicit local scope. Use \cmd{\global} to force a global effect. % % \newpage % % \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. Especially with the macros in this section, the naming scheme is unfortunate because package development involved some groping in the dark regarding the concepts.} % Section~\ref{sec:NamePatterns} shows how name control sequences are keyed either to the main-matter system or to the front-matter system. The two formatting systems are distinct, useful for separate document elements. We color-code them and ``forget'' any previous name uses: % % \begin{quote} % \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={\large\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} % % \begin{tcolorbox}[colframe=blue,colback=white, % adjusted title={\large\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} % \end{quote} % % We used the \textsf{xcolor} package with the following macros: % \begin{quote} % \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} % \Name[Rudolph]{Carnap}^^A % \PatInfo{\ShowPattern[Rudolph]{Carnap}!MN} % \cmd{\Name[Rudolph]\{Carnap\}} \\[1ex] % \ForceName\Name[Rudolph]{Carnap} % \cmd{\ForceName}\cmd{\Name[Rudolph]\{Carnap\}} % \end{quote} % % Below\Info{\texttt{alwaysformat}} we simulate \texttt{alwaysformat} via package internals. Only the ``first use'' formatting hooks are used: % % \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 % % \subsubsection*{\hfil Hook caveats} % % The internal name parser determines what syntactic name elements exist and how they are constituted. It passes that information to macros that determine the form of nonwestern or Western names to be displayed. They in turn call the format hook dispatcher for post-processing, which calls the formatting hooks using the pattern: % % \begin{quote} % \cmd{\bgroup}\meta{Hook}\texttt{\{\#1\}}\cmd{\egroup}. % \end{quote} % % One can create formatting hooks that take either no argument or one argument. Since the formatting hooks are already defined, one must not use \cmd{\newcommand} to create new hooks. Instead, use \cmd{\renewcommand} e.g.: % % \begin{quote} % \cmd{\renewcommand*}\cmd{\NamesFormat\{}\meta{content}\texttt{\}}\\ % \cmd{\renewcommand*}\cmd{\NamesFormat[1]\{}\meta{content}\texttt{\}} % \end{quote} % % A hook that takes one argument can use, change, or discard it and invoke \cmd{\NameParser} (Section~\ref{sec:SpecialUses}). Due to package design using local scope, both the following achieve exactly the same effect: % % \begin{quote} % \cmd{\renewcommand*}\cmd{\NamesFormat\{}\cmd{\itshape}\texttt{\}}\\ % \cmd{\renewcommand*}\cmd{\NamesFormat\{}\cmd{\textit}\texttt{\}} % \end{quote} % % \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} % \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} % \VerbatimInput[gobble=0]{\jobname.tmp} % \end{quote} % \input{\jobname.tmp} % % \begin{Quote}{\ForgetThis\Name[M.T.]{Cicero}[Marcus Tullius], \textit{De oratore} B II; C IX, \S 36 (55 \textsc{BC})} % By what other voice, too, than that of the orator, is history, the evidence of time, the light of truth, the life of memory, the directress of life, the herald of antiquity, committed to immortality?^^A % \index{Romans, quotes of\noexpand\string|hyperpage} % \end{Quote} % % \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}). % % \DescribeMacro{\ForgetName} % This macro takes the same arguments as \cmd{\Name}, but it prints no output. It ``forgets'' a name, forcing a ``pre-first use'' state. The next instance of that name will display as if the name did not yet exist: % % \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 entries. % % \DescribeMacro{\ForgetThis} % This prefix macro causes the next instance of a naming macro or shorthand to ``forget'' a name before printing it. After knowing \Einstein, we forget him and again have a first instance via |\ForgetThis\Einstein|: \ForgetThis\Einstein. \cmd{\ForgetThis} no longer affects the index unless one uses the \texttt{oldreset} option. % % \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} % \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} % If one is within a group or local scope, one may have to add % \cmd{\global} to \cmd{\NamesInactive}: % \begin{itemize}[rightmargin=2\leftmargin] % \item[] |\global\NamesInactive|\global\NamesInactive % \item[] |\Name[Charlie]{Chaplin}|\dotfill \Name[Charlie]{Chaplin} % \item[] |\CheckChuck|\dotfill \CheckChuck % \end{itemize} % % \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[] |\SubvertName[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 Instance:] \ForgetThis\Bailey \dotfill \cmd{\Bailey}\\ % \ForgetThis\LBailey \dotfill \cmd{\LBailey}\\ % \ForgetThis\SBailey \dotfill \cmd{\SBailey}\\ % Name control pattern created with text output. % Index state 2, 4, or 6 (Section~\ref{sec:RuleStates}). % Name form: long. First-use hooks. % % \item[Later Instance:] \Bailey \dotfill \cmd{\Bailey}\\ % \LBailey \dotfill \cmd{\LBailey}\\ % \SBailey \dotfill \cmd{\SBailey}\\ % No change to name pattern. Index state 2, 4, or 6. % Name form: short. Subsequent-use hooks. % % \item[Forgotten:] (no output)\ForgetName[Betsey]{Bailey} \dotfill^^A % \cmd{\ForgetName[Betsey]\{Bailey\}}\\ % Name pattern deleted. Index state 1, 3, or 5 % (Section~\ref{sec:RuleStates}). % next instance usually will be a first use, e.g.: \Bailey. % % \item[Subverted:] (no output)\SubvertName[Betsey]{Bailey} \dotfill^^A % \cmd{\SubvertName[Betsey]\{Bailey\}}\\ % Name pattern created. Index state 2, 4, or 6. % next instance usually will be a later use, e.g.: \Bailey, \LBailey, \SBailey. % % \item[\cmd{\ForgetThis}:] % \ForgetThis\Bailey \dotfill \cmd{\ForgetThis}\cmd{\Bailey}\\ % \ForgetThis\LBailey \dotfill \cmd{\ForgetThis}\cmd{\LBailey}\\ % \ForgetThis\SBailey \dotfill \cmd{\ForgetThis}\cmd{\SBailey}\\ % Name pattern deleted, then created again. Index state 2, 4, or 6. % Name form and format: same as first use above. next instance usually % will be a later use, e.g.: \Bailey, \LBailey, \SBailey. % % \item[\cmd{\SubvertThis}:] % \SubvertThis\Bailey \dotfill \cmd{\SubvertThis}\cmd{\Bailey}\\ % \SubvertThis\LBailey \dotfill \cmd{\SubvertThis}\cmd{\LBailey}\\ % \SubvertThis\SBailey \dotfill \cmd{\SubvertThis}\cmd{\SBailey}\\ % Name pattern created. Index state 2, 4, or 6. % Name form and format: same as later use above. next instance usually % will be a later use, e.g.: \Bailey, \LBailey, \SBailey. % % \item[Format as First:] % \ForceName\Bailey \dotfill \cmd{\ForceName}\cmd{\Bailey}\\ % \ForceName\LBailey \dotfill \cmd{\ForceName}\cmd{\LBailey}\\ % \ForceName\SBailey \dotfill \cmd{\ForceName}\cmd{\SBailey}\\ % No change to name pattern. Index state 2, 4, or 6. % Name form: short or long. Name format: First-use hooks. % \end{itemize} % % \begin{Quote}{\Name[Hubert H.]{Humphrey}, speech (26 March 1966)} % In real life, unlike in Shakespeare, the sweetness of the rose depends upon the name it bears. Things are not only what they are. They are, in very important respects, what they seem to be.^^A % \index{politicians, quotes of\noexpand\string|hyperpage}^^A % \index{Shakespearian rose, references to\noexpand\string|hyperpage} % \end{Quote} % % \newpage % % \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. % % \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. % % \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} % \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} % \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} % \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 an instance of former pro-wrestler and % Minnesota governor \Name[Jesse]{Ventura}, |\Name[Jesse]{Ventura}|. % \item We establish his lesser-known legal name as an alias: % ``\IndexRef[James]{Janos}{Ventura, Jesse}\Name[James]{Janos}'',\\ % |\IndexRef[James]{Janos}{Ventura,|\,|Jesse}\Name[James]{Janos}|. % \item We get the result: % ``\IfAKA[James]{Janos} % {\Name*[Jesse]{Ventura} is a stage name} % {\Name*[Jesse]{Ventura} is a regular name} % {}''. % If we do not use \cmd{\ExcludeName}, we can leave the % \meta{excl} branch empty: % \end{enumerate} % % \begin{quote} % \begin{Verbatim} % \IfAKA[James]{Janos} % {\Name*[Jesse]{Ventura} is a stage name} % {\Name*[Jesse]{Ventura} is a regular name} % {} % \end{Verbatim} % \end{quote} % % \newpage % % We can combine all these macros to create a complete, unified test: % % \begin{quote} % \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 tags to ensure that the information associated with a given name is not anachronistic. % % For example, we know that certain people are associated with chronological events. We associate those people and events to the information presented in a name tag via name testing macros: % % \begin{VerbatimOut}{\jobname.tmp} % \NameAddInfo{Saul, of Tarsus} % {\IfMainName{Jesus, Christ} % {\IfMainName[Lucius]{Sergius Paulus} % {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 missionary journeys before being % sent to Rome for trial in an appeal to Caesar. % While in Cyprus, \Name{Saul, of Tarsus} converted % \Name[Lucius]{Sergius Paulus}, who became a patron. % % \Name{Saul, of Tarsus} \NameQueryInfo{Saul, of Tarsus}. % Under the name \Name{Paul} he wrote his letters. % \end{VerbatimOut} % % \begin{quote} % \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} % % \subsubsection*{\hfil Caveats} % % Using these tests inside other macros or passing control sequences to them may create false results (see \textit{The \TeX book}, 212--15). This was especially the case before 2018 with names using diacritical marks and other letters outside the basic Latin characters. That is why \textsf{nameauth} uses token registers to save name arguments. % % 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; example file aids % % compatibility across different LaTeX versions and 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} % \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} % % % 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} % % \newpage % % Overlay three fully illustrates how all these features integrate. This could allow a presenter to maintain information used in different presentations, making each element or slide a ``drop-in'' unit that can figure out how to present names, name forms, and related information without extensive retyping. % % \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 (published 1597)} % 'Tis but thy name that is my enemy;\dots\\ % What's in a name? That which we call a rose\\ % By any other name would smell as sweet;\\ % So Romeo would, were he not Romeo call'd,\\ % Retain that dear perfection which he owes\\ % Without that title. Romeo, doff thy name,\\ % And for that name which is no part of thee\\ % Take all myself.\negmedskip^^A % \index{creatives, quotes of\noexpand\string|hyperpage}^^A % \index{Shakespearian rose, references to\noexpand\string|hyperpage} % \end{Quote} % \AltFormatInactive % % \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 an alternate name in the \texttt{nameauth} environment: % % \begin{quote} % \vspace{4ex} % \PatInfo{\ShowPattern[Mike]{Tyson}!MN} % \vspace{-4ex} % \begin{Verbatim} % \begin{nameauth} % \< Tyson & Mike & Tyson & > % \< Iron & Mike & Tyson & Iron Mike > % \end{nameauth} % % \IndexRef{Iron Mike}{Tyson, Mike} % \end{Verbatim} % \end{quote} % % Because \cmd{\Iron} uses the \meta{Alternate} column, all index page entries are the same as those for \cmd{\Tyson}, the canonical name. Adding the cross-reference via \cmd{\IndexRef} produces ``Iron Mike \textit{see} Tyson, Mike'' in the index. % % \begin{quote} % \begin{tabular}{rlrl}\toprule % \rowcolor{nagrey}^^A % \bfseries Output & \bfseries Macro & % \bfseries Output & \bfseries Macro\\ % % \LIron \qquad & \cmd{\LIron} & % \LTyson[Iron Mike] & \cmd{\LTyson[Iron Mike]}\\ % % \rowcolor{nagrey}^^A % \Iron & \cmd{\Iron} & \Tyson & \cmd{\Tyson}\\ % % \SIron & \cmd{\SIron} & \STyson & \cmd{\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} % \vspace{4ex} % \PatInfo{\ShowPattern{Elizabeth, I}!MN} % \vspace{-4ex} % \begin{Verbatim} % \begin{nameauth} % \< Eliz & & Elizabeth, I & > % \end{nameauth} % % \IndexRef{Gloriana}{Elizabeth I} % \IndexRef[Good Queen]{Bess}{Elizabeth I} % % \LEliz[I, ``Gloriana''] was known also as % \ForceFN\SEliz[``Good Queen Bess'']. % \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} % \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 % some name authorities, we decide that the the canonical % name will be: \ForgetThis\DuBois\ \cmd{\DuBois}. % % \item We use the non-breaking space (the tilde active character) because % internally, \textsf{nameauth} removes all regular spaces from % name patterns. Both \cmd{\Name[W.E.B.]\{Du Bois\}} and % \cmd{\Name[W.E.B.]\{DuBois\}} have the same name control pattern: % \texttt{\ShowPattern[W.E.B.]{DuBois}} (Section~\ref{sec:NamePatterns}). % The name pattern \texttt{\ShowPattern[W.E.B.]{Du~Bois}} differs from % both of the other names. % % \item Another reason to use the non-breaking space is that it prevents % a line break between the particle \textit{Du} and the name \textit{Bois}. % % \item The sort key that could be applicable to both names is % \texttt{\{DuBois, William\}}. Had we used the sort key % \texttt{\{Du Bois, William\}}, the name would be sorted before % \texttt{dual}, which is not in order (Section~\ref{sec:IndexInitials}). % % \item Instead of using \cmd{\SkipIndex}\cmd{\AltDuBois} many times, we % create a cross-reference before the alternate name is used to prevent % index page entries from being created for the alternate form: % \IndexRef[W.E.B.]{DuBois}{Du Bois, W.E.B.}\\[1ex] % | \IndexRef[W.E.B.]{DuBois}{Du Bois, W.E.B.}| % % \item With the following setup we keep full stop detection, modify name % forms, and check if the name straddles a page break in order to append % |\JustIndex\DuBois| if needed: % % \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} % \VerbatimInput[gobble=0]{\jobname.tmp} % % \input{\jobname.tmp} % \end{quote} % % \item The macro below loses full stop detection, but it does % automatically handle the name spanning a page break, just like the % regular naming macros. Yet it is rather inelegant. % % \begin{quote} % \begin{Verbatim} % \newcommand\NewDuBois[2]{% % \def\Test{#1}% % \def\Long{L}% % \def\Short{S}% % \JustIndex\DuBois% % \ifx\Test\Long \LAltDuBois[#2] \else % \ifx\Test\Short \SAltDuBois[#2] \else % \AltDuBois \fi\fi % \JustIndex\DuBois} % \ForgetThis\NewDuBois{}{William E.B.}\\ % \NewDuBois{L}{}\\ % \NewDuBois{S}{William} % \end{Verbatim} % % \newcommand\NewDuBois[2]{^^A % \def\Test{#1}^^A % \def\Long{L}^^A % \def\Short{S}^^A % \JustIndex\DuBois^^A % \ifx\Test\Long \LAltDuBois[#2] \else % \ifx\Test\Short \SAltDuBois[#2] \else % \AltDuBois[#2] \fi\fi % \JustIndex\DuBois} % \ForgetThis\NewDuBois{}{William E.B.}\\ % \NewDuBois{L}{}\\ % \NewDuBois{S}{William} % \end{quote} % \end{itemize} % % \begin{Quote}{\ForgetThis\DuBois\break % \hbox{}\hfill \textit{Darkwater} (1920), C II: The Souls of White Folk} % The cause of war is preparation for war.\negmedskip^^A % \index{civil rights leaders, quotes of\noexpand\string|hyperpage} % \end{Quote} % % \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 present a childish facade. % \end{VerbatimOut} % % \begin{quote} % \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} % We consider the work of \ForgetThis\Name[e.e.]{cummings}. % \SubvertThis\CapThis\Name[e.e.]{cummings's} % motif of the goat-footed balloon man has underlying % sexual themes that nevertheless present a childish facade. % \end{VerbatimOut} % % \begin{quote} % \vspace{4.5ex} % \PatInfo{\ShowPattern[e.e.]{cummings's}} % \vspace{-4.5ex} % \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. % % \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} % \vspace{5ex} % \PatInfo{\ShowPattern[J.E.]{Carter, Jr.}!MN\hfill % \textrm{(1--2)}\break % \ShowPattern[Jimmy]{Carter}!PN\hfill \textrm{(3, 6)}\break % \ShowPattern[Jimmy]{Carter}!MN\hfill \textrm{(4)}\break % \ShowPattern[J.E.]{Carter, Jr.}!PN\hfill % \textrm{(5)}} % \vspace{-5ex} % \item We use the canonical name to create page entries: % \item[] \Name*[J.E.]{Carter, Jr.}\dotfill |\Name*[J.E.]{Carter, Jr.}| % % \item Variants that use \meta{Alternate} in the text create page % entries under the canonical form, not the variant form: % \item[] \DropAffix\Name*[J.E.]{Carter, Jr.}[Jimmy]\dotfill^^A % |\DropAffix\Name*[J.E.]{Carter, Jr.}[Jimmy]| % \item[] |\ShowIdxPageref*[J.E.]{Carter, Jr.}[Jimmy]|\dotfill^^A % \ShowIdxPageref*[J.E.]{Carter, Jr.}[Jimmy] % % \item We must create a \textit{see} reference from an alternate form % to a canonical form \emph{before} using the alternate form in a naming % macro, or it will be ignored and a warning will result: % \item[] |\IndexRef[Jimmy]{Carter}{Carter, J.E., Jr.}|^^A % \IndexRef[Jimmy]{Carter}{Carter, J.E., Jr.} % % \newpage % % \item No page entries will occur below because we made the % \textit{see} reference first. Note how the alternate form is an % independent name: % \item[] \Name[Jimmy]{Carter}\dotfill |\Name[Jimmy]{Carter}| % % \item If we want to index the alternate name, we have to use the % canonical name instead of the alternate name: % \item[] |\IndexName[J.E.]{Carter, Jr.}| % % \item If instead we wanted to make a \textit{see also} reference, we % would use both the canonical name and the alternate name, then create % the cross-reference \emph{after} all uses of the alternate name % (at the end of the document), e.g.: % \item[] |\SeeAlso\IndexRef[Jimmy]{Carter}{Carter, J.E., Jr.}| % \end{enumerate} % % \subsubsection*{\hfil Multiple Connections} % % Below, two names are indexed with page numbers. They have \textit{see also} cross-references to each other. One of those names also has a \textit{see} reference to it: % % \begin{enumerate} % \vspace{5ex} % \PatInfo{\ShowPattern{Maimonides}!MN \textrm{(1)}\break % \ShowPattern{Moses, ben-Maimon}!PN \textrm{(2)}\break % \ShowPattern{Moses, ben-Maimon}!MN \textrm{(3)}\break % \ShowPattern{Rambam}!MN \textrm{(4)}\break % \ShowPattern{Rambam}!PN \textrm{(5)}} % \vspace{-5ex} % \item We use the canonical name to set up page entries: % \item[] \Name{Maimonides}\dotfill |\Name{Maimonides}| % % \item \Name{Maimonides} has two other names, one more used than the % other. We set up his least-used name as the \textit{see} % reference: % \item[] |\IndexRef{Moses, ben-Maimon}{Maimonides}|^^A % \IndexRef{Moses, ben-Maimon}{Maimonides} % % \item We have a main name with a page entry and a ``\textit{see} % reference'' to that name. No page entries will occur below because % we made the xref first: % \item[] \Name{Moses, ben-Maimon}\dotfill |\Name{Moses, ben-Maimon}| % % \item Before creating \textit{see also} cross-references, we use the other % alias so that all the page entries precede the % cross-references: % \item[] \Name{Rambam}\dotfill |\Name{Rambam}| % % \item All \textit{see also} references must come after all page entries. % For example, one could put both of these macros at the end of the % document: % \item[] |\SeeAlso\IndexRef{Maimonides}{Rambam}|\\ % \SeeAlso\IndexRef{Maimonides}{Rambam}^^A % |\SeeAlso\IndexRef{Rambam}{Maimonides}|^^A % \SeeAlso\IndexRef{Rambam}{Maimonides} % \end{enumerate} % % \subsubsection*{\hfil Multiple Targets} % % There 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} % \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. % % \subsection{Using a Name Authority} % % Below are a couple of names from a name authority created for a translation of \textit{De Diaconis et Diaconissis Veteris Ecclesiae Liber Commentarius} by \Name[Caspar]{Ziegler}, of which the present author was the editor.\footnote{The book, \textit{The Diaconate of the Ancient and Medieval Church} had been typeset using \LaTeX, but then had to be converted to a different format.} % % Constructing that name authority of over 500 names was a challenge. The deceased translator left names in abbreviated Latin. He left many place-names in Latin and incorrectly translated some others. To get valid names that one can research, the present author recommends: % % \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 entries, then place % \cmd{\SeeAlso}\cmd{\IndexRef}\meta{name args} as needed % at the end of the document, before \cmd{\printindex}. % \item Use \cmd{\CapThis} (Section~\ref{sec:NameParticles}). % \end{enumerate*} % % \begin{quote} % \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} % % \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}. % % \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: % % \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; example file aids % % compatibility across different LaTeX versions and 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 instances of % ``\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 instances of % ``\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} % \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 instances of % ``\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 instances of % ``\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{Name Tags in Hooks} % \label{sec:DataTagHooks} % % By recalling name tags (Section~\ref{sec:DataTags}) in formatting hooks, one can automate how they either appear with a name or not. This package is all about automation and the associated trade-offs. % % Formatting hooks are called within a local scope. They take zero or one argument (Section~\ref{sec:Formatting}). When they take one argument, they have the option to print that argument, add information to the argument, or discard the argument. Yet macros used in formatting hooks can present challenges that we show how to manage: % % \begin{itemize} % \item When \cmd{\noexpand} is used in a name argument, \cmd{\NameQueryInfo} % and perhaps other macros may not produce output within a formatting hook % when using the basic interface, but the quick interface works fine. % \item Macros that are used to make local changes in formatting hooks should % never make the same changes outside of that context, else spurious index % entries will occur. % \end{itemize} % % \DescribeMacro{\@nameauth@toksa} % Three token registers contain each of the name arguments used in a macro that takes them. % \DescribeMacro{\@nameauth@toksb} % They are needed to manage the proper expansion of name arguments, especially in the index. % \DescribeMacro{\@nameauth@toksc} % Historically, these registers have been necessary for names that contain accents and diacritics. In Section~\ref{sec:AKA}, these registers correspond to the \emph{last} three name arguments. They can be used, if needed, in formatting hooks by \textsf{nameauth} macros that take name arguments. % % Their chief use, historically speaking, was to facilitate retrieving name tags via \cmd{\NameQueryInfo}. That use has been superseded by \cmd{\NameauthPattern}, which is described in Section~\ref{sec:NamePatterns}. % % \newpage % % \subsubsection{Hook Templates} % \label{sec:DataTemp} % % \begingroup ^^A Local formatting hook change % % \subsubsection*{\hfil Recommended Template} % % The hook below prints the name tag with the first use of a name in the main-matter system, if such a tag exists. It is simple, it avoids the \cmd{\NameQueryInfo} problem, and it is easy to debug. % % \begin{quote} % \begin{Verbatim} % \renewcommand*\NamesFormat[1] % {% % #1% % \ifcsname\NameauthPattern!DB\endcsname % \expandafter\csname\NameauthPattern!DB\endcsname% % \fi % } % \end{Verbatim} % \end{quote} % % \subsubsection*{\hfil Older Templates} % % Two other hook designs were used in the past to display name tags. They are included here only for the sake of illustration. After showing the templates, we test all three of them to show why we recommend the template above. % % We use \(\epsilon\)-\TeX\ features next. See \href{https://tex.stackexchange.com/questions/140785/how-is-unexpanded-defined}{\bfseries this page} on the use of \cmd{\unexpanded} and \href{https://tex.stackexchange.com/questions/61223/explanations-about-begingroup-edef-x-endgroup}{\bfseries another page} pertinent to the structure of this hook. We print the name, expand the arguments of \cmd{\NameQueryInfo}, and use those arguments to print the tag. % % \begin{quote} % \vspace{3ex}\Info{Alternate A}\vspace{-3ex} % \begin{Verbatim} % \makeatletter % \renewcommand*\NamesFormat[1]{% % \begingroup% % \protected@edef\temp{\endgroup% % {#1\noexpand\NameQueryInfo % [\unexpanded\expandafter{\the\@nameauth@toksa}] % {\unexpanded\expandafter{\the\@nameauth@toksb}} % [\unexpanded\expandafter{\the\@nameauth@toksc}]% % }% % }% % \temp% % } % \makeatother % \end{Verbatim} % \end{quote} % % The older form of this hook was the first to be used in \textsf{nameauth}, % based on \href{https://www.tug.org/TUGboat/tb09-1/tb20bechtolsheim.pdf}{\bfseries this \texttt{pdf} article} from \textit{TUGboat} that gives a tutorial on \cmd{\expandafter}. As one can see, it is more tedious, but gets the same result as above: % % \begin{quote} % \vspace{3ex}\Info{Alternate B}\vspace{-3ex} % \begin{Verbatim} % \let\ex\expandafter % \makeatletter % \renewcommand*\NamesFormat[1]{% % #1% % \ex\ex\ex\ex\ex\ex\ex\NameQueryInfo% % \ex\ex\ex\ex\ex\ex\ex[\ex\ex\ex\the% % \ex\ex\ex\@nameauth@toksa\ex\ex\ex]% % \ex\ex\ex{\ex\the\ex\@nameauth@toksb\ex}% % \ex[\the\@nameauth@etoksc]% % } % \makeatother % \end{Verbatim} % \end{quote} % % \subsubsection*{\hfil Template Test} % % We set up the following test for our three templates, with indexing suppressed: % % \begin{itemize} % \item A macro in a name argument is preceded by \cmd{\noexpand}. That % occurs with greater frequency in advanced formatting. % \item If we see the outcome, ``Test passed'', we have success. % \item If we see the outcome, ``Test'', we have failure. % \end{itemize} % % \IndexInactive % \begin{VerbatimOut}{\jobname.tmp} % \newcommand\testname{Test} % \NameAddInfo{\noexpand\testname}{ passed} % \begin{nameauth} % \< Test & & \noexpand\testname & > % \end{nameauth} % \end{VerbatimOut} % % \begin{quote} % The macro \cmd{\testname} contains the first part of our test output. % The name tag contains the second part. We will use both name % interfaces with all three templates. % % \VerbatimInput[gobble=0]{\jobname.tmp} % \end{quote} % % \input{\jobname.tmp} % % \begin{itemize} % \item The recommended hook gives us:\\ % \renewcommand*\NamesFormat[1] % {^^A % #1^^A % \ifcsname\NameauthPattern!DB\endcsname % \expandafter\csname\NameauthPattern!DB\endcsname^^A % \fi % } % \begin{tabular}{lll} % \cmd{\ForgetThis}\cmd{\Name\{}\cmd{\noexpand}\cmd{\testname\}} & % \ForgetThis\Name{\noexpand\testname} & success \\ % \cmd{\ForgetThis}\cmd{\Test} & \ForgetThis\Test & success \\ % \end{tabular} % % \item Alternate A gives us:\\ % \makeatletter % \renewcommand*\NamesFormat[1]{^^A % \begingroup^^A % \protected@edef\temp{\endgroup^^A % {#1\noexpand\NameQueryInfo % [\unexpanded\expandafter{\the\@nameauth@toksa}] % {\unexpanded\expandafter{\the\@nameauth@toksb}} % [\unexpanded\expandafter{\the\@nameauth@toksc}]^^A % }^^A % }^^A % \temp^^A % } % \makeatother % \begin{tabular}{lll} % \cmd{\ForgetThis}\cmd{\Name\{}\cmd{\noexpand}\cmd{\testname\}} & % \ForgetThis\Name{\noexpand\testname} & failure \\ % \cmd{\ForgetThis}\cmd{\Test} & \ForgetThis\Test & success \\ % \end{tabular} % % \item Alternate B gives us:\\ % \let\ex\expandafter % \makeatletter % \renewcommand*\NamesFormat[1]{^^A % #1^^A % \ex\ex\ex\ex\ex\ex\ex\NameQueryInfo^^A % \ex\ex\ex\ex\ex\ex\ex[\ex\ex\ex\the^^A % \ex\ex\ex\@nameauth@toksa\ex\ex\ex]^^A % \ex\ex\ex{\ex\the\ex\@nameauth@toksb\ex}^^A % \ex[\the\@nameauth@etoksc]^^A % } % \makeatother % \begin{tabular}{lll} % \cmd{\ForgetThis}\cmd{\Name\{}\cmd{\noexpand}\cmd{\testname\}} & % \ForgetThis\Name{\noexpand\testname} & failure \\ % \cmd{\ForgetThis}\cmd{\Test} & \ForgetThis\Test & success \\ % \end{tabular} % \end{itemize} % % \endgroup ^^A Local formatting hook change % % \subsubsection[Ancient Names]{Application: Ancient Names} % \label{sec:NameAncient} % % \begingroup%^^A Local format hook redefinition % % \renewcommand*\NamesFormat{}^^A % \renewcommand*\MainNameHook{}^^A % Ancient names tend to be the most fluid regarding the meaning and use of affixes. Certain scholarly contexts add more information to a name when it is first introduced. Here we look at ways to address that need. For the sake of clarity, here the examples do not use the formatting conventions of this manual. % % First we explore the easiest way to handle royal or ancient variants by manually adding any epithets or sobriquets to a standard name form: % % \begin{itemize} % \item We use \cmd{\PretagName}\PatInfo{\ShowPattern{Antiochus, IV}!PRE} % to sort especially Roman numerals in the index. For example: % \cmd{\PretagName\{Antiochus, IV\}\{Antiochus 4\}} % \item We use \cmd{\TagName}\PatInfo{\ShowPattern{Antiochus, IV}!TAG} to % ensure that any ``long form'' information is displayed in the index: % \cmd{\TagName\{Antiochus, IV]\}\{ Epiphanes, king\}}. % \item Using \cmd{\PretagName} and \cmd{\TagName} in the preamble ensures % consistency. % \item We use \meta{Alternate} to add ``long form'' information in the text, % e.g:\PatInfo{\ShowPattern{Antiochus, IV}!MN} % \end{itemize} % \begin{Block} % \cmd{\Name\ \{Antiochus, IV\}[IV Epiphanes]}\dotfill % \Name{Antiochus, IV}[IV Epiphanes]\\ % \cmd{\Name*\{Antiochus, IV\}}\dotfill \Name*{Antiochus, IV}\\ % \cmd{\Name\ \{Antiochus, IV\}}\dotfill \Name{Antiochus, IV} % \end{Block} % % \newpage % % Next we show a snippet that uses the quick interface with this same method. We trigger a first use, followed by long and short subsequent uses: % % \begin{quote} % \vspace{3ex} % \PatInfo{\ShowPattern{Demetrius, I}!PRE\break % \ShowPattern{Demetrius, I}!TAG\break % \ShowPattern{Demetrius, I}!MN} % \vspace{-3ex} % \begin{Verbatim} % \PretagName{Demetrius, I}{Demetrius 1} % \TagName{Demetrius, I}{ Soter, king} % \begin{nameauth} % \< Dem & & Demetrius, I & > % \end{nameauth} % \end{Verbatim} % \end{quote} % % \begin{Block} % |\ForgetName{Demetrius, I}|\ForgetName{Demetrius, I}\\ % \cmd{\Dem[I Soter]}\dotfill \Dem[I Soter]\\ % \cmd{\LDem}\dotfill \LDem\\ % \cmd{\Dem}\dotfill \Dem % \end{Block} % % As discussed in Section~\ref{sec:Complexity}, simple examples do not lend themselves to automation. Below we trade automation, where we do not need to add information manually to the \meta{Alternate} argument, for a complex initial setup that uses name tags and the recommended template: % % \begin{quote} % \vspace{3ex} % \PatInfo{\ShowPattern{Demetrius, I}!DB} % \vspace{-3ex} % \begin{Verbatim}[firstnumber=last] % \NameAddInfo{Demetrius, I}{ Soter} % \renewcommand*\NamesFormat[1] % {% % #1% % \ifcsname\NameauthPattern!DB\endcsname % \expandafter\csname\NameauthPattern!DB\endcsname% % \fi % } % \renewcommand*\MainNameHook{} % \end{Verbatim} % \end{quote} % \NameAddInfo{Demetrius, I}{ Soter} % \renewcommand*\NamesFormat[1] % {^^A % #1^^A % \ifcsname\NameauthPattern!DB\endcsname % \expandafter\csname\NameauthPattern!DB\endcsname^^A % \fi % } % \renewcommand*\MainNameHook{} % % \begin{Block} % |\ForgetName{Demetrius, I}|\ForgetName{Demetrius, I}\\ % \cmd{\Dem}\dotfill \Dem\\ % \cmd{\LDem}\dotfill \LDem\\ % \cmd{\Dem}\dotfill \Dem % \end{Block} % % In both cases, the index entry in a normal document would be sorted like the following: % \begingroup % \IndexActual{@}^^A % \TagName{Demetrius, I}{ Soter, king}^^A % \texttt{\ShowIdxPageref{Demetrius, I}}.^^A % \TagName{Demetrius, I}{ Soter, king\string|hyperpage} % \endgroup % % The first use of a name, or one after the use of \cmd{\ForgetName} or \cmd{\ForgetThis}, shows the most information. A long instance of an extant name shows a little less info, and a short instance shows the least. Every difference in name form corresponds with a macro in a known state. % \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 tags, we can do something similar here. % % First we must create any name tags that might be used. Whether it is in the preamble or in the body text, the main point is that the tag can only be used if it exists. The tags have a leading space because they are printed conditionally. % % 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; example file aids % % compatibility across different LaTeX versions and engines. % \usepackage{makeidx} % \usepackage{nameauth} % % \makeindex % % % Add name 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 name tag in ``first'' instance % \newif\ifNoTag % % % Redesign formatting hook to usually print a tag % % only in ``first'' instance. 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 instance via: % \NoTagtrue\ForgetThis\Name[George]{Washington}. Or we can trigger % the first-use hook in a subsequent name use and still have dates: % \ForceName\Name[George]{Washington}. % % 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 name 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} % \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} % \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 instance via: % \NoTagtrue\ForgetThis\Name[George]{Washington}. Or we can trigger % the first-use hook in a subsequent name use and still have dates: % \ForceName\Name[George]{Washington}. % \end{quote} % % Since we already set up a cross-reference with \cmd{\IndexRef}, we can use just the the naming macros with ``Atat\"urk'' and get the desired formatting without any page entries in the index: % % \begin{quote} % \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 name 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} % \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*}. % % \DescribeMacro{\AltFormatActive*} % The starred form \cmd{\AltFormatActive*} enables alternate formatting but deactivates the built-in alternate formatting macros, preventing them from changing their arguments. It countermands both the \texttt{altformat} option and \cmd{\AltFormatActive}. It causes \cmd{\CapThis} only to work via \cmd{\AltCaps}. % % \newpage % % \DescribeMacro{\AltFormatInactive} % This macro both disables and deactivates alternate formatting. This reverts globally to standard formatting and the normal function of \cmd{\CapThis}. % % Most \textsf{nameauth} macros that turn things on and off have a local scope unless one uses \cmd{\global}. These alternate formatting macros have global scope to eliminate implied scope becoming a point of failure, creating spurious index entries.\medskip % % \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}} % \label{sec: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.\medskip % % \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. % % \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} % \VerbatimInput[gobble=0]{\jobname.tmp} % % \input{\jobname.tmp}^^A % \index{Shakespearian rose, references to\noexpand\string|hyperpage} % \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} % \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. % % 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. % % 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. % % If one uses the \texttt{altformat} option or \cmd{\AltFormatActive}, the formatting ``power'' goes to the formatting macros by default in order to have formatted names in the index. Otherwise, the normal formatting regime isolates formatting in the text, as the Anglosphere seems wont to do. % % 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; example file aids % % compatibility across different LaTeX versions and 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} % \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; example file aids % % compatibility across different LaTeX versions and 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} % \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.2\textwidth}{\LCath[\noexpand\AltCaps{d}e']} % |\LCath[\noexpand\AltCaps{d}e']| % \item \parbox{0.2\textwidth}{\CapThis\LCath[\noexpand\AltCaps{d}e']} % |\CapThis\LCath[\noexpand\AltCaps{d}e']| % \end{itemize} % \endgroup^^A Local format hook redefinition % % % \subsubsection{Inflected Names} % \label{sec:InflNames} % \begingroup^^A Local format hook redefinition % % Next we design grammatical inflections for use with alternate formatting. We do not use the general formatting conventions in this manual. We shall build on this example in order to design the more complex hooks used for Roman names. % % 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; example file aids % % compatibility across different LaTeX versions and 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' \textit{Declaration of Independence} and his impact % as third president of the United States. \Jeff\ was a complex % historical figure whose actions defy a consistent moral compass % both in public policy and in personal affairs. % % \printindex % \end{document} % \end{VerbatimOut} % % \begin{quote} % \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' \textit{Declaration of Independence} and his impact % as third president of the United States. \Jeff\ was a complex % historical figure whose actions defy a consistent moral compass % both in public policy and in personal affairs. % \end{quote} % \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 instances. % % \item Since some \LaTeX\ fonts do not combine small caps and boldface, % we instead use slanted text to set the head-words off from the articles. % That font switch is done in the macro that formats the articles % (\cmd{\RefArticle}). % \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; example file aids % % compatibility across different LaTeX versions and 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} % \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 (1908)} % I read in a book once that a rose by any other name would smell as sweet, but I've never been able to believe it. I don't believe a rose \textsc{would} be as nice if it was called a thistle or a skunk cabbage.^^A % \index{creatives, quotes of\noexpand\string|hyperpage}^^A % \index{Shakespearian rose, references to\noexpand\string|hyperpage} % \end{Quote} % % \newpage % % \subsection{Roman Names} % \label{sec:Romani} % % Roman names tend to be among the most variable in terms of treatment. As far as \textsf{nameauth} is concerned, they range from being treated as Western names to being treated in very special ways. Below we show some variations. % % \subsubsection[General Market]{Casual Reading / General Book Market} % % \begin{itemize} % \item Treat as a Western name, especially among well-known Roman names like % \Name*[M.T.]{Cicero}[Marcus Tullius], where the final name, \Cicero, is a % surname and the rest forenames:\footnote{Philip J. Adler, \textit{World % Civilizations}, 3rd ed. (Belmont, Calif.: Thomson/Wadsworth, 2003).} % % \begin{quote} % \begin{Verbatim} % \TagName[Julius]{Caesar}{, imperator} % for index % \Name[Julius]{Caesar}[Gaius Julius]\\ % \Name*[Julius]{Caesar}\\ % \Name[Julius]{Caesar} % \end{Verbatim} % \Name[Julius]{Caesar}[Gaius Julius]^^A % \PatInfo{\ShowPattern[Julius]{Caesar}[Gaius Julius]!MN}\\ % \Name*[Julius]{Caesar}\\ % \Name[Julius]{Caesar}\\[1ex] % Index: \ShowIdxPageref*[Julius]{Caesar}^^A % \end{quote} % % \item Treat as a Western name; put \textit{nomen} and \textit{cognomen} in % \meta{SNN}:\footnote{Paul L. Maier, \textit{In the Fullness of Time: A % Historian Looks at Christmas, Easter, and the Early Church}, revised ed. % (San Francisco: Harper, 1991).} % % \begin{quote} % \begin{Verbatim} % \ForgetThis\Name[Lucius]{Sergius Paulus}\\ % \Name[Lucius]{Sergius Paulus} % \end{Verbatim} % \ForgetThis\Name[Lucius]{Sergius Paulus}^^A % \PatInfo{\ShowPattern[Lucius]{Sergius Paulus}!MN}\\ % \Name[Lucius]{Sergius Paulus}\\[1ex] % Index: \ShowIdxPageref*[Lucius]{Sergius Paulus}^^A % \end{quote} % % \item Treat as ancient names, especially those with no \textit{praenomen}: % % \begin{quote} % \begin{Verbatim} % \ForgetThis\Name{Pontius, Pilate}[Pilatus]\\ % \Name*{Pontius, Pilate}\\ % \ForceFN\FName{Pontius, Pilate} % \end{Verbatim} % \ForgetThis\Name{Pontius, Pilate}[Pilatus]^^A % \PatInfo{\ShowPattern{Pontius, Pilate}[Pilatus]!MN}\\ % \Name*{Pontius, Pilate}\\ % \ForceFN\FName{Pontius, Pilate}\\[1ex] % Index: \ShowIdxPageref*{Pontius, Pilate} % \end{quote} % \end{itemize} % % There is also a method where Roman names are indexed as mononyms using the most recognizable of their names.\footnote{Justo L. González, \textit{The Story of Christianity}, 2 vols. (San Francisco: Harper, 1984).} That method is ill-suited for \textsf{nameauth}. % % \begin{Quote}{\ForgetThis\Name[Julius]{Caesar}, % \textit{\la{De bello gallico}} 3.16.6 (58–49 \textsc{bc})} % \la{Fere libenter homines, id quod volunt, credunt.} % % (In general, people willingly believe what they want [to believe].)^^A % \index{Romans, quotes of\noexpand\string|hyperpage} % \end{Quote} % % \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. \href{https://en.wikipedia.org/wiki/Patrician_(ancient_Rome)}{This page} offers a good overview. % The exact roles of names changed over time. \href{https://en.wikipedia.org/wiki/Roman_naming_conventions}{Another page} gives an overview of Roman naming conventions. % A very \href{https://www.youtube.com/watch?v=RMLb1jVl_Uo}{helpful video} can be found on the YouTube channel PolýMATHY by \Name[Luke]{Ranieri}. % % Some reference works treat the \textit{cognomen} as if it were a Western surname.\footnote{See Geiss, \textit{Geschichte Griffbereit}; Kinder and Hilgemann, \textit{dtv-Atlas zur Weltgeschichte}, 2 vols., 29th printing (1964; Munich: Deutscher Taschenbuch Verlag, 1993). See also \href{https://books.infotoday.com/books/Indexing-names.shtml}{\bfseries this page}.} % Using this approach, Roman names encoded with \textsf{nameauth} have this form: % % \begin{quote} % 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} % % \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; example file aids % % compatibility across different LaTeX versions and 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 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% % } % % \NoAgnomentrue\Scipio\ was born around 236 \textsc{bc} % into the Scipiones branch of the Cornelii clan. % \NoAgnomentrue\Scipio\ rose to military fame during the % Second Punic War. Thereafter he was known as \Scipio. % 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 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} % \VerbatimInput[gobble=0, firstline=75, lastline=87]{\NameauthTestFile} % % \newpage % % \VerbatimInput[gobble=0, firstline=88, lastline=110]{\NameauthTestFile} % % \NoAgnomentrue\Scipio\ was born around 236 \textsc{bc} % into the Scipiones branch of the Cornelii clan. % \NoAgnomentrue\Scipio\ rose to military fame during the % Second Punic War. Thereafter he was known as \Scipio. % 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 tags instead of \meta{Alternate} in the first-use formatting hook. Here we show the changes needed to add name tags to the first-use formatting hook. Even though we are changing the formatting hooks throughout the document, none of the changes cause different index entries and will be unnoticed in the finished document. % % \NameAddInfo[\noexpand\TSemp]{Gracchus} % { (consul, 177 \textsc{bc})} % \renewcommand*\NamesFormat[1] % {^^A % \ifNoPraenomen\XPraetrue\fi^^A % \ifNoGens\XGenstrue\fi^^A % \ifNoCognomen\XCogntrue\fi^^A % \ifNoAgnomen\XAgnotrue\fi^^A % #1^^A % \ifcsname\NameauthPattern!DB\endcsname % \expandafter\csname\NameauthPattern!DB\endcsname^^A % \fi % \global\NoPraenomenfalse^^A % \global\NoGensfalse^^A % \global\NoCognomenfalse^^A % \global\NoAgnomenfalse^^A % } % \begin{quote} % \VerbatimInput[gobble=0,firstline=111]{\NameauthTestFile} % % \TGrac\ served as tribune of the plebs in 184 \textsc{bc}. % \TGrac\ was elected praetor for 180 \textsc{bc}, % after which he was appointed governor of Hispania Citerior, % serving with the rank of proconsul. In 177 \textsc{bc}, % he was elected consul, again in 163 \textsc{bc}. % \end{quote} % % 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} % % \begingroup % \renewcommand*\NamesFormat[1]{\color{blue}\sffamily #1} % \renewcommand*\MainNameHook[1]{\sffamily #1} % \begin{Quote}{\ForgetThis\Scipio\break % \hbox{}\hfill attributed by \Name[Titus]{Livius} in % \textit{\la{Ab urbe condita}} B 30 (27–9 \textsc{bc})} % \la{Bellum parate, quoniam pacem pati non potuistis.} % % (Prepare for war, for it seems that you are unable to tolerate peace.)\footnote{Here we enclosed this quote in a group and redefined the formatting hooks locally.}^^A % \index{Romans, quotes of\noexpand\string|hyperpage} % \end{Quote} % \endgroup % % \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; example file aids % % compatibility across different LaTeX versions and 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} % \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} % \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. % % \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. % % These flags also persist after the macro that uses name arguments exits, unlike many other flags. This allows one to poll the last macro that took naming arguments, which may or may not be the last name printed in the text. % % To illustrate how one might poll these flags, either in a formatting hook or after a macro that takes name arguments exits, we set up the following macros and show how the flags are set. Notice that the name type is a function solely of the name arguments used, not how the name eventually ends up printed in the text, and not based on the name control sequence. % % \begin{VerbatimOut}{\jobname.tmp} % \newcommand\ShowType % {% % \ifNameauthWestern Western name\else % \ifNameauthObsolete nonwestern name using obsolete syntax\else % nonwestern name using current syntax\fi % \fi % } % % First, we begin with a Western name: % % \Name*[Albert]{Einstein} is a \ShowType. % % Even though this name is reversed in the text, it is still Western: % % \RevName\Name*[Frenec]{Liszt}\dag\ is a \ShowType. % % Here we present the same name twice, but using the two different % syntax versions for nonwestern names: % % \Name*{Henry, VIII} is a \ShowType. % % \Name*{Henry}[VIII]\ddag\ is a \ShowType. % % Finally, even though we do not print the name, % \IndexName{Elizabeth, I} we get a \ShowType. % \end{VerbatimOut} % % \begin{quote} % \VerbatimInput[gobble=0]{\jobname.tmp} % % \newcommand\ShowType % {%^^A % \ifNameauthWestern Western name\else % \ifNameauthObsolete nonwestern name using obsolete syntax\else % nonwestern name using current syntax\fi % \fi % } % % First, we begin with a Western name: % % \Name*[Albert]{Einstein} is a \ShowType. % % Even though this name is reversed in the text, it is still Western: % % \RevName\Name*[Frenec]{Liszt}\dag\ is a \ShowType. % % Here we present the same name twice, but using the two different % syntax versions for nonwestern names: % % \Name*{Henry, VIII} is a \ShowType. % % \Name*{Henry}[VIII]\ddag\ is a \ShowType. % % Finally, even though we do not print the name, % \IndexName{Elizabeth, I} we get a \ShowType. % \end{quote} % % \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: % % Since we are using the \texttt{altformat} option or \cmd{\AltFormatActive}, we can expect that formatting is activated by default. We design a subsequent-use hook that deactivates alternate formatting inside of it: % % \begin{SyntaxBox} % \cmd{\renewcommand*}\meta{SubsequentHook}\texttt{[1]\{\dots}\cmd % {\AltOff}\cmd{\NameParser}\texttt{\dots\}} % \end{SyntaxBox} % % \newpage % % If we had used \cmd{\AltFormatActive*}, where the formatting macros are enabled, but \emph{deactivated} by default, then we might want instead a first-use hook that activates the macros: % % \begin{SyntaxBox} % \cmd{\renewcommand*}\meta{FirstHook}\texttt{[1]\{\dots}\cmd{\AltOn}\cmd % {\NameParser}\texttt{\dots\}} % \end{SyntaxBox} % % \ifdefined\NameauthDoTestFiles \edef\NameauthTestFile{test11_09.tex}\else % \edef\NameauthTestFile{\jobname.tmp}\fi % % \begin{VerbatimOut}{\NameauthTestFile} % \documentclass{article} % \input{compat.tex} % Included with nameauth; example file aids % % compatibility across different LaTeX versions and engines. % \usepackage{makeidx} % \usepackage[altformat]{nameauth} % % \makeindex % % % Boolean flags; the first sets up headwords and the second % % indicates that a nonwestern 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% % % } % % \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} % \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 % } % % \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} % % \newpage % % \subsubsection{Marginalia} % % \ifdefined\NameauthDoTestFiles \edef\NameauthTestFile{test11_10.tex}\else % \edef\NameauthTestFile{\jobname.tmp}\fi % % \begin{VerbatimOut}{\NameauthTestFile} % \documentclass{article} % \input{compat.tex} % Included with nameauth; example file aids % % compatibility across different LaTeX versions and 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=54]{\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. % % In the hooks we print the default name in the body text. If allowed, we print a margin paragraph with an alternate full name using \cmd{\NameParser}. Both hooks set \cmd{\RevertSNfalse} on exit, so that \cmd{\Revert} works on a per-name basis. % % \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} % \VerbatimInput[gobble=0,firstline=55,lastline=96]{\NameauthTestFile} % \end{quote} % % Finally, we put all these macros to work in the text: % % \begin{quote} % \VerbatimInput[gobble=0,firstline=97]{\NameauthTestFile} % % \ForgetThis\Shak\ is the national poet of England % in much the same way that \Name[Robert]{\textSC{Burns}} % is that of Scotland. With the latter's rise of influence % in the 1800s, \Revert\Shak\ became known as ``\Shak''. % \end{quote} % % \endgroup^^A Local format hook redefinition % \AltFormatInactive % % \ReturnLink % % \AltFormatActive % \begin{Quote}{\ForgetThis\Shak\break % \hbox{}\hfill ``Julius Caesar'', Act III, Scene II (first performed 1599)} % \textbf{Antony:} Friends, Romans, countrymen, lend me your ears;\\ % I come to bury Caesar, not to praise him.\\ % The evil that men do lives after them;\\ % The good is oft interred with their bones;\\ % So let it be with Caesar. The noble Brutus\\ % Hath told you Caesar was ambitious:\\ % If it were so, it was a grievous fault,\\ % And grievously hath Caesar answer'd it.\\ % Here, under leave of Brutus and the rest---\\ % For Brutus is an honourable man;\\ % So are they all, all honourable men---\\ % Come I to speak in Caesar's funeral.\\ % He was my friend, faithful and just to me:\\ % But Brutus says he was ambitious;\\ % And Brutus is an honourable man.\negmedskip^^A % \index{creatives, quotes of\noexpand\string|hyperpage} % \end{Quote} % \AltFormatInactive % % \newpage % % \section{Planned Obsolescence} % % \subsection[Pseudonyms]{Almost Obsolete: Pseudonym Macros} % \label{sec:AKA} % % The macros described in this section were early features of \textsf{nameauth}. They do not work like many of the other macros that display names and may be removed in the future. We retain them at present for backward compatibility. % % \subsubsection{Special Syntax} % % To save space, we show \meta{SAFX} as the equivalent of \meta{SNN|,| Affix}. The macros in this section all take arguments of the form: % % \begin{SyntaxBoxii} % Target Name & Cross-Reference Name\\\midrule % \oarg{FNN}\marg{SAFX} & \oarg{xref FNN}\marg % {xref SAFX}\oarg{xref Alternate}\\ % \end{SyntaxBoxii} % % \begin{itemize} % \item The target name comes first, which is the opposite of % \cmd{\IndexRef}. There the target name comes last because it is text % passed to the index macros. % \item The cross-reference comes last to allow for the widest range of % name forms (again, the opposite of \cmd{\IndexRef}). % We avoid two optional arguments in succession by preventing the target % from having a final optional argument. Neither \meta{Alternate} nor % the obsolete syntax cannot be used with the target name. Both can be % used with the cross-reference. % \item \meta{SAFX} and \meta{xref SAFX} can have comma-delimited suffixes. % \item One cannot use \cmd{\TagName} with a cross-reference, but one can % sort a cross-reference with \cmd{\PretagName} % (Section~\ref{sec:IndexSort}): % \end{itemize} % % \subsubsection{The Macros} % % \DescribeMacro{\AKA} % The \textit{also known as} macro and its starred form display an alias in the text and create a cross-reference in the index. % \DescribeMacro{\AKA*} % They format names differently than the naming macros because they use the name patterns for cross-references as a means to account for the name forms that they print in the test. % % \begin{SyntaxBox} % \cmd{\AKA\ }\oarg{FNN}\marg{SAFX}\oarg{xref FNN}\marg % {xref SAFX}\oarg{xref Alternate}\\ % \cmd{\AKA*}\oarg{FNN}\marg{SAFX}\oarg{xref FNN}\marg % {xref SAFX}\oarg{xref Alternate}\\ % \end{SyntaxBox} % \negmedskip % % \begin{itemize} % \item Both macros create a cross-reference in the index to the % target name. % \item \cmd{\AKA} prints a long form of the cross-reference name in % the text. \cmd{\SeeAlso} works with \cmd{\AKA}, \cmd{\AKA*}, % \cmd{\PName}, and \cmd{\PName*}. % \item If \meta{xref Alternate} is present in a Western name form, then % instead of \meta{xref FNN}, \meta{xref Alternate} will be printed % in the text. % \item If \meta{xref Alternate} is present in a nonwestern name form, % then instead of \meta{xref Affix} (if present), \meta{xref Alternate} % will be printed in the text. % \item If \meta{xref Alternate} is present without either \meta{xref FNN} % or \meta{xref Affix}, the obsolete syntax is used. % \item \cmd{\AKA*} is analogous to \cmd{\FName}. \cmd{\ForceFN} works % with it. The \texttt{oldAKA} option implies \cmd{\ForceFN} with every % use of \cmd{\AKA*}. % \item Neither \cmd{\AKA} nor its derivatives permit the effects of % \cmd{\ForgetThis} and \cmd{\SubvertThis} to ``pass through'' because % they produce output in the text. The \texttt{oldreset} option negates % this. % \end{itemize} % % Below we make cross-references to \Name[Bob]{Hope} \cmd{\Name[Bob]\{Hope\}}; all of the forms listed create the cross-reference ``\ShowIdxPageref*[Leslie Townes]{Hope} \textit{see} \ShowIdxPageref*[Bob]{Hope}''. % % \begin{center}\small % \vspace{2ex} % \Info{\strut\footnotesize Name Pattern(s):\hfill \break % \ttfamily \ShowPattern[Bob]{Hope}!MN\break % \ShowPattern[Leslie Townes]{Hope}!PN} % \vspace{-2ex} % \begin{tabular}{ll}\toprule % \rowcolor{nagrey}^^A % \AKA[Bob]{Hope}[Leslie Townes]{Hope}& % |\AKA[Bob]{Hope}[Leslie Townes]{Hope}|\\ % % \RevComma\AKA[Bob]{Hope}[Leslie Townes]{Hope}& % |\RevComma\AKA[Bob]{Hope}[Leslie Townes]{Hope}|\\ % % \rowcolor{nagrey}^^A % \AKA[Bob]{Hope}[Leslie Townes]{Hope}[Lester T.]& % |\AKA[Bob]{Hope}[Leslie Townes]{Hope}[Lester T.]|\\ % % \AKA*[Bob]{Hope}[Leslie Townes]{Hope}& % |\AKA*[Bob]{Hope}[Leslie Townes]{Hope}|\\ % % \rowcolor{nagrey}^^A % \AKA*[Bob]{Hope}[Leslie Townes]{Hope}[Lester]& % |\AKA*[Bob]{Hope}[Leslie Townes]{Hope}[Lester]|\\\bottomrule % \end{tabular} % \end{center} % % We display other name forms after referring to some names to ensure that they have sensible page entries: % % \begin{quote} % \begin{tabular}{ll} % \ForgetThis\Name{Louis, XIV}& % |\ForgetThis\Name{Louis, XIV}|\\ % \Name{Lao-tzu} & |\Name{Lao-tzu}|\\ % \Name[Lafcadio]{Hearn} & |\Name[Lafcadio]{Hearn}|\\ % \Name[Charles]{du~Fresne}& % |\Name[Charles]{du~Fresne}|\\ % \end{tabular} % \end{quote} % Caps and reversing macros work on the arguments that are printed % in the text. % % \begin{center} % \vspace{2ex} % \PatInfo{\ShowPattern{Louis, XIV}!MN\break % \ShowPattern{Lao-tzu}!MN\break % \ShowPattern[Lafcadio]{Hearn}!MN\break % \ShowPattern[Charles]{du~Fresne}!MN\break % \ShowPattern{Sun King}!PN\break % \ShowPattern{Li, Er}!PN\break % \ShowPattern{du~Cange}!PN\break % \ShowPattern{Koizumi, Yakumo}!PN} % \vspace{-2ex} % \begin{tabular}{ll}\toprule % \rowcolor{nagrey}^^A % \AKA{Louis, XIV}{Sun King} & |\AKA{Louis, XIV}{Sun King}|\\ % \rowcolor{nagrey}^^A % \AKA{Louis, XIV}{Sun King} & |\AKA*{Louis, XIV}{Sun King}|\\ % % \AKA{Lao-tzu}{Li, Er} & |\AKA{Lao-tzu}{Li, Er}|\\ % \AKA*{Lao-tzu}{Li, Er} & |\AKA*{Lao-tzu}{Li, Er}|\\ % % \rowcolor{nagrey}^^A % \AKA[Charles]{du~Fresne}{du~Cange}& % |\AKA[Charles]{du~Fresne}{du~Cange}|\\ % \rowcolor{nagrey}^^A % \CapThis\AKA[Charles]{du~Fresne}{du~Cange}& % |\CapThis\AKA[Charles]{du~Fresne}{du~Cange}|\\ % % \CapName\AKA[Lafcadio]{Hearn}{Koizumi, Yakumo}& % |\CapName\AKA[Lafcadio]{Hearn}{Koizumi, Yakumo}|\\ % \RevName\AKA[Lafcadio]{Hearn}{Koizumi, Yakumo}& % |\RevName\AKA[Lafcadio]{Hearn}{Koizumi, Yakumo}|\\\bottomrule % \end{tabular} % \end{center} % % % \DescribeMacro{\PName} % These convenience macros were an early feature of \textsf{nameauth}. They print a main name followed by a cross-reference in parentheses. % \DescribeMacro{\PName*} % If one is inclined to view \cmd{\AKA} as rubbish, these two macros are a biological hazard. % % \begin{SyntaxBox} % \cmd{\PName\ }\oarg{FNN}\marg{SAFX}\oarg{xref\,FNN}\marg % {xref\,SAFX}\oarg{xref\,Alternate}\\ % \cmd{\PName*}\oarg{FNN}\marg{SAFX}\oarg{xref\,FNN}\marg % {xref\,SAFX}\oarg{xref\,Alternate}\\ % \end{SyntaxBox} % % \cmd{\PName*} is like \cmd{\Name*} to the extent that it prints a long form % of \meta{FNN}\meta{SAFX}. It does not affect the cross-reference % \meta{xref FNN}\meta{xref SAFX}\meta{xref Alternate}. % % \begin{itemize} % \item Most prefix macros only affect \meta{FNN}\meta{SAFX}, % not the cross-reference. % \item The cross-reference always has a long form. % \item \cmd{\SkipIndex} keeps both names out of the index. % \item \meta{Alternate} and the obsolete syntax work only with % the cross-reference. % \end{itemize} % % If we attempted to use |\PName*{William, I}[William]{the Conqueror}|, this macro would put ``\SkipIndex\PName*{William, I}[William]{the Conqueror}'' in the body text, but its index entry would be incorrect: ``\ShowIdxPageref*[William]{the Conqueror} \textit{see} \ShowIdxPageref*{William, I}''. We use \cmd{\ForgetName\{William, I\}}^^A % \ForgetName{William, I} to prepare for the following example. We do not show the name patterns in the margin. % % \begingroup\small % \begin{itemize}[leftmargin=2cm] % \item[Macro:] \cmd{\PName[Mark]\{Twain\}[Samuel L.]\{Clemens\}} % \item[Text:] \ForgetThis\PName[Mark]{Twain}[Samuel L.]{Clemens}\\ % \PName[Mark]{Twain}[Samuel L.]{Clemens} % \item[Macro:] \cmd{\PName*[Mark]\{Twain\}[Samuel L.]\{Clemens\}} % \item[Text:] \PName*[Mark]{Twain}[Samuel L.]{Clemens} % \item[Index:] \ShowIdxPageref*[Samuel L.]{Clemens} \textit{see} % \ShowIdxPageref*[Mark]{Twain} % \item[Macro:] \cmd{\PName\{Voltaire\}[François-Marie]\{Arouet\}} % \item[Text:] \PName{Voltaire}[François-Marie]{Arouet} % \item[Index:] \ShowIdxPageref*[François-Marie]{Arouet} \textit{see} % \ShowIdxPageref*{Voltaire} % \item[Macro:] \cmd{\PName\{William, I\}\{William, the Conqueror\}} % \item[Text:] \PName{William, I}{William, the Conqueror}\\ % \PName{William, I}{William, the Conqueror} % \item[Index:] \ShowIdxPageref*{William, the Conqueror} \textit{see} % \ShowIdxPageref*{William, I} % \item[Macro:] \cmd{\PretagName\{}\cmd{\textit\{Doctor mellifluus\}\}^^A % \{Doctor mellifluus\}}\\ % \cmd{\PName\{Bernard, of Clairvaux\}\{}\cmd{\textit\{Doctor mellifluus\}} % \item[Text:] \PName{Bernard, of Clairvaux}{\textit{Doctor mellifluus}}\\ % \PName{Bernard, of Clairvaux}{\textit{Doctor mellifluus}} % \item[Index:] \ShowIdxPageref*{\textit{Doctor mellifluus}} \textit{see} % \ShowIdxPageref*{Bernard, of Clairvaux} % \item[Macro:] \cmd{\ForgetThis}\cmd{\PName\{Lao-tzu\}\{Li, Er\}} % \item[Text:] \ForgetThis\PName{Lao-tzu}{Li, Er} % \item[Index:] \ShowIdxPageref*{Li, Er} \textit{see} % \ShowIdxPageref*{Lao-tzu} % \end{itemize} % \endgroup % % While these macros certainly work, much like the obsolete syntax, they can be criticized as a design idea that originally seemed to hold promise, yet disappointed in practice due to using the cross-reference system for name formatting. % % \subsubsection[Workarounds]{Formatting Workarounds} % % By default, the macros in this section use only the formatting hooks for subsequent instances of names (Section~\ref{sec:Formatting}). % % First, the \texttt{formatAKA}\Info{\texttt{formatAKA}} option will permit \cmd{\ForceName} to force the ``first-use'' formatting hooks to be employed, but under different conditions. The name patterns that control these uses (Section~\ref{sec:NamePatterns}) apply only to cross-references; they are a distinct system of patterns that differs from normal names and ignores the difference between main-matter and front-matter name formatting. % % \begin{center} % \makeatletter\@nameauth@AKAFormattrue\makeatother % \global\NamesInactive % \begin{tabular}{>{\columncolor{nagrey}}rll} % \rowcolor{nagrey}^^A % & |\ForgetThis\Eliz| & |\AKA{Elizabeth,I}%|\\ % \rowcolor{nagrey}^^A % & & |[Good Queen]{Bess}|\\[0.5ex] % % Front Matter: & \ForgetThis\Eliz & % \AKA{Elizabeth,I}[Good Queen]{Bess}\\[0.5ex] % \global\NamesActive^^A % \strut Main Matter: & \ForgetThis\Eliz & % \AKA{Elizabeth, I}[Good Queen]{Bess}\\[0.5ex] % With \cmd{\ForceName}: & & % \ForceName\AKA{Elizabeth, I}[Good Queen]{Bess}\\ % \end{tabular} % \vspace{-14ex} % \PatInfo{\ShowPattern{Elizabeth, I}!NF\break % \ShowPattern[Good Queen]{Bess}!PN\break % \ShowPattern{Elizabeth, I}!MN} % \vspace{14ex} % \end{center} % % The first appearance of \AKA{Elizabeth,I}[Good Queen]{Bess} above uses \cmd{\FrontNamesFormat} as its formatting hook because it is the first occurrence of the alternate name in the front matter. After that, even though \AKA{Elizabeth,I}[Good Queen]{Bess} occurs for the first time in the main matter, it uses the subsequent-use \cmd{\MainNameHook} because we are not using the regular name patterns. We need to use \cmd{\ForceName}, which triggers the expected use of \cmd{\NamesFormat}, the first-use main-matter hook. % % Second,\Info{\texttt{alwaysformat}} we can use the \texttt{alwaysformat} option to force only the use of \cmd{\NamesFormat} and \cmd{\FrontNamesFormat}. Of course, this can look like rubbish in certain circumstances. % % \begin{quote} % \makeatletter\@nameauth@AlwaysFormattrue\makeatother % \ForgetThis\LEliz\ was known as ``\AKA{Elizabeth,I}[Good Queen]{Bess}''. % Again we mention Queen \Eliz, ``\AKA{Elizabeth, I}[Good Queen]{Bess}''. % Using \cmd{\ForceName}: \ForceName\AKA{Elizabeth, I}[Good Queen]{Bess}. % \end{quote} % % \subsection{Obsolete Syntax} % \label{sec:Obsolete} % % This nonwestern syntax limits alternate names and cross-references, prevents the use of comma-delimited names, and complicates indexing. It is a ``ghost of \textsf{nameauth} past'' that remains for the sake of backward compatibility and to prevent ``holes'' where naming macro arguments are discarded without apparent reason. % % \begin{SyntaxBox} % \cmd{\Name}\marg{SNN}\oarg{Alternate} % \end{SyntaxBox} % % The genesis of this syntax was the use of the \meta{Alternate} field for variant forenames in Western names, personal names in Eastern names, and sobriquets, titles, and so on in ancient names. Yet this prevented using alternate names for nonwestern names and it limited those names to an unacceptable second-tier status. Developing the comma delimiter in \meta{SNN, Affix} presented significant challenges, but it was worth overcoming them to put all name forms on equal footing. % % We show this syntax for the sake of completeness, but we strongly encourage using the comma-delimited syntax instead. % % \begin{itemize} % \item One must \emph{leave empty} the first optional \meta{FNN} argument. % \item One must \emph{never} use the comma-delimited argument \meta{Affix}. % \item These names \emph{always} use \meta{Alternate}, which acts like % \meta{Affix} usually does, and affects both name and index patterns % (Section~\ref{sec:NamePatterns}). % \item These names take the form \meta{SNN Alternate} in the index. % \item In this manual we designate these names with a double dagger (\ddag). % \end{itemize} % % \begin{quote} % \begin{Verbatim} % \Name{Henry}[VIII] % Ancient % \Name{Chiang}[Kai-shek] % Eastern % \begin{nameauth} % \< Dagb & & Dagobert & I > % Ancient % \< Yosh & & Yoshida & Shigeru > % Eastern % \< Fukuyama & & % \noexpand\textUC{Fukuyama} & Takeshi > % Alt. format % \end{nameauth} % \end{Verbatim} % \end{quote} % % \AltFormatActive % After studying in the US during the 1930s, in 1954 Rev. % \Fukuyama\ddag\ \cmd{\Fukuyama}\cmd{\ddag} published % \textit{Nihon Fukuin R\=uteru Ky\=okai Shi} (History % of the Evangelical Lutheran Church in Japan). % \AltFormatInactive % % \newpage % % \begin{center} % \begin{tabular}{ll}\toprule % \rowcolor{nagrey}^^A % \ForgetThis\Name{Henry}[VIII]\ddag & % |\ForgetThis\Name{Henry}[VIII]\ddag|\\ % \rowcolor{nagrey}^^A % \Name{Henry}[VIII]\ddag & % |\Name{Henry}[VIII]\ddag|\\ % % \ForgetThis\Name{Chiang}[Kai-shek]\ddag & % |\ForgetThis\Name{Chiang}[Kai-shek]\ddag|\\ % \Name{Chiang}[Kai-shek]\ddag & % |\Name{Chiang}[Kai-shek]\ddag|\\ % % \rowcolor{nagrey}^^A % \Dagb\ddag & |\Dagb\ddag|\\ % \rowcolor{nagrey}^^A % \Dagb\ddag & |\Dagb\ddag|\\ % % \CapName\Yosh\ddag & |\CapName\Yosh\ddag|\\ % \CapName\RevName\LYosh\ddag & |\CapName\RevName\LYosh\ddag|\\ % % \rowcolor{nagrey}^^A % & |\AltFormatActive| \AltFormatActive\\ % \rowcolor{nagrey}^^A % \ForgetThis\Fukuyama\ddag & |\ForgetThis\Fukuyama\ddag|\\ % \rowcolor{nagrey}^^A % \Fukuyama\ddag & |\Fukuyama\ddag|\\ % \rowcolor{nagrey}^^A % & |\AltFormatInactive| \AltFormatInactive\\\bottomrule % \end{tabular} % \end{center} % % Regardless of its flaws, the obsolete syntax shares name patterns, index tags, name tags, and index entries with the current syntax: % % \begin{quote} % \begin{tabular}{@{}lll} % Obsolete syntax: & \ForgetThis\Name{Henry}[VIII]\ddag & % \cmd{\ForgetThis}\cmd{\Name\{Henry\}[VIII]}\cmd{\ddag}\\[1ex] % & \ShowPattern{Henry}[VIII] & \cmd{\ShowPattern\{Henry\}[VIII]}\\[1ex] % Current syntax: & \Name{Henry, VIII} & \cmd{\Name\{Henry, VIII\}}\\[1ex] % & \ShowPattern{Henry, VIII} & \cmd{\ShowPattern\{Henry, VIII\}}\\ % \end{tabular} % \end{quote} % % We do not expect people to use the obsolete syntax much anymore. Here we list more advantages to using the current syntax and avoiding the old. % % \begin{itemize} % \item Only the newer syntax permits such variants: % \item[] \Name*{Henry, VIII}[Tudor]\dotfill \cmd{\Name*\{Henry, VIII\}[Tudor]} % \item The proper form for the old syntax is, e.g.: % \item[] \Name*{Henry}[VIII]\dotfill \cmd{\Name*\{Henry\}[VIII]} % \IndexInactive % \item Next we see malformed Western names: % \item[] \Name[Henry]{VIII}\dotfill \cmd{\Name[Henry]\{VIII\}}\\ % \Name[Henry]{VIII}\dotfill \cmd{\Name[Henry]\{VIII\}}\\ % \Name*[Henry]{VIII}[Tudor]\dotfill \cmd{\Name*[Henry]\{VIII\}[Tudor]}\\ % \Name[Henry]{VIII}[Tudor]\dotfill \cmd{\Name[Henry]\{VIII\}[Tudor]} % \item These malformed names have the same index entry\dotfill^^A % \ShowIdxPageref*[Henry]{VIII} % \IndexActive % \end{itemize} % % \ReturnLink % % \begin{Quote}{\Name[Salman]{Rushdie}, \textit{The Satanic Verses} (1988)} % Names, once they are in common use, quickly become mere sounds, their etymology being buried, like so many of the earth's marvels, beneath the dust of habit.\negmedskip^^A % \index{creatives, quotes of\noexpand\string|hyperpage} % \end{Quote} % % \newpage % % \begingroup^^A General format hook redefinition. % \section{Advanced Customization} % \label{sec:AdvCustomize} % % Here we discuss package internals to help users customize and add features. We set aside the common formatting in this manual and reset the formatting hooks to the default settings. We use alternate formatting for much of this section: % % \begin{VerbatimOut}{\jobname.tmp} % \renewcommand*\NamesFormat{} % \renewcommand*\FrontNamesFormat{} % \renewcommand*\MainNameHook{\AltOff} % \renewcommand*\FrontNameHook{\AltOff} % \end{VerbatimOut} % % \begin{quote} % \VerbatimInput[gobble=0]{\jobname.tmp} % \end{quote} % \input{\jobname.tmp} % % \AltFormatActive % \begingroup^^A Local format hook redefinition % % \subsection{Using Package Internals} % % We start with alternate formatting (Section~\ref{sec:AltFormat}), changing the ``back-end'' macros to our custom code. Here, we need only check \texttt{\textbackslash if@nameauth@DoAlt}, which is toggled by \cmd{\AltOn} and \cmd{\AltOff}. % Instead of using \cmd{\textSC} and friends, we define a new macro that works in similar fashion. \cmd{\Fbox} draws a frame around the name: % % \ifdefined\NameauthDoTestFiles \edef\NameauthTestFile{test13_01.tex}\else % \edef\NameauthTestFile{\jobname.tmp}\fi % % \begin{VerbatimOut}{\NameauthTestFile} % \documentclass{article} % \input{compat.tex} % Included with nameauth; example file aids % % compatibility across different LaTeX versions and engines. % \usepackage{makeidx} % \usepackage[altformat]{nameauth} % % \makeindex % % % 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} % % \begin{quote} % \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} % \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 % % \begingroup % \renewcommand*\NamesFormat[1]{\color{blue}\sffamily #1} % \renewcommand*\MainNameHook[1]{\sffamily #1} % \begin{Quote}{\ForgetThis\Name{Maimonides}, % \textit{Guide for the Perplexed} (1190)} % For a truth, once established by proof, does neither gain force nor certainty by the consent of all scholars, nor lose by the general dissent.\footnote{Here we enclosed this quote in a group and redefined the formatting hooks locally.}^^A % \index{theologians, quotes of\noexpand\string|hyperpage} % \index{philosophers, quotes of\noexpand\string|hyperpage} % \end{Quote} % \endgroup % % \newpage % % The final step is redefining the hooks, which can be quite simple: % % \begin{quote} % \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}} % Alternate formatting can work with greater customization, but that is more labor-intensive and requires one to keep track of more details. We still recommend using \cmd{\AltFormatActive} to mitigate errors. The following example shows greater customization that remains compatible with package internals. % % Three Boolean flags replace package internals. The flag \texttt{\textbackslash ifFbox} activates formatting, \cmd{\CapThis} sets \texttt{\textbackslash ifFirstCap} true, and \texttt{\textbackslash ifInHook} is set manually, instead of being set by the hook dispatcher. % % \ifdefined\NameauthDoTestFiles \edef\NameauthTestFile{test13_02.tex}\else % \edef\NameauthTestFile{\jobname.tmp}\fi % % \begin{VerbatimOut}{\NameauthTestFile} % \documentclass{article} % \input{compat.tex} % Included with nameauth; example file aids % % compatibility across different LaTeX versions and engines. % \usepackage{makeidx} % \usepackage[altformat]{nameauth} % % \makeindex % % \newif\ifFbox % Replaces \if@nameauth@DoAlt \AltOn \AltOff % \newif\ifFirstCap % Replaces \if@nameauth@DoCaps \AltCaps % \newif\ifInHook % Replaces \if@nameauth@InHook hook dispatcher % \Fboxtrue % Replaces \AltFormatActive % % % Alternate formatting macro definition % \newcommand*\Fbox[1]{% % \ifFbox\protect\fbox{#1}\else#1\fi % } % % % Redefinition of \AltCaps and \CapThis % \renewcommand*\AltCaps[1]{% % \ifInHook % \ifFirstCap\MakeUppercase{#1}\else#1\fi % \else % #1% % \fi % } % \renewcommand*\CapThis{\FirstCaptrue} % % \renewcommand*\NamesFormat[1] % {\InHooktrue\NameParser\global\FirstCapfalse} % % \renewcommand*\MainNameHook[1] % {\Fboxfalse\InHooktrue\NameParser\global\FirstCapfalse} % % \let\FrontNamesFormat\Namesformat % \let\FrontNameHook\MainNameHook % % % Quick interface definition % \begin{nameauth} % \< deSmet & Pierre-Jean & % \noexpand\Fbox{\noexpand\AltCaps{d}e~Smet} & > % \end{nameauth} % % % Sorting and tagging % \PretagName[Pierre-Jean]% % {\noexpand\Fbox{\noexpand\AltCaps{d}e~Smet}}% % {de~Smet, Pierre-Jean} % % \begin{document} % % \deSmet\ was a Jesuit missionary who arrived in North % America in 1821 at the age of twenty, after a year of seminary % education. \CapThis\deSmet\ was ordained in 1827 and worked % among American Indian nations after 1837. We can show the forms % \LdeSmet\ and \SdeSmet. % % \printindex % \end{document} % \end{VerbatimOut} % % \begin{quote} % \VerbatimInput[gobble=0,lastline=11]{\NameauthTestFile} % \end{quote} % % The formatting macro is like what we have seen, except it refers to \texttt{\textbackslash ifFbox}. We define \cmd{\Fbox} locally in this manual, but \cmd{\noexpand} helps isolate those effects. % % \begin{quote} % \VerbatimInput[gobble=0,firstline=12,lastline=16]{\NameauthTestFile} % \end{quote} % % Our \cmd{\AltCaps} works like the built-in version, except it does not use the internal macros and flags. We redefine \cmd{\CapThis} to use our flag instead of the internal flag: % % \begin{quote} % \VerbatimInput[gobble=0,firstline=17,lastline=26]{\NameauthTestFile} % \end{quote} % % We have to reproduce the logic and macros that the package would have provided. That means defining everything from scratch. To emphasize these differences, instead of displaying the macro argument, we use \cmd{\NameParser} to do that. % % Changes to \texttt{\textbackslash ifInHook} (default false) and \texttt{\textbackslash ifFbox} (default true) are local to the scope in which the hook macros are called. \texttt{\textbackslash ifFirstCap} must be set globally. Below we reproduce the logic of \cmd{\AltOff} before \cmd{\NameParser} in \cmd{\MainNameHook}: % % \begin{quote} % \VerbatimInput[gobble=0,firstline=27,lastline=32]{\NameauthTestFile} % \end{quote} % % By using the same hook logic and \cmd{\noexpand}, the same macros used before now use a different ``back end'' without creating spurious index entries. % % \newcommand*\Fbox[1]{^^A % \ifFbox\protect\fbox{#1}\else#1\fi % } % \renewcommand*\AltCaps[1]{^^A % \ifInHook % \ifFirstCap\MakeUppercase{#1}\else#1\fi % \else % #1^^A % \fi % } % \renewcommand*\CapThis{\FirstCaptrue} % \renewcommand*\NamesFormat[1] % {\InHooktrue\NameParser\global\FirstCapfalse} % \renewcommand*\MainNameHook[1] % {\Fboxfalse\InHooktrue\NameParser\global\FirstCapfalse} % \let\FrontNamesFormat\Namesformat % \let\FrontNameHook\MainNameHook % % \begin{quote} % \VerbatimInput[gobble=0,firstline=33]{\NameauthTestFile} % % \deSmet\ was a Jesuit missionary who arrived in North % America in 1821 at the age of twenty, after a year of seminary % education. \CapThis\deSmet\ was ordained in 1827 and worked % among American Indian nations after 1837. We can show the forms % \LdeSmet\ and \SdeSmet. % \end{quote} % % \ifdefined\NameauthDoTestFiles \edef\NameauthTestFile{test13_03.tex}\else % \edef\NameauthTestFile{\jobname.tmp}\fi % % \begin{VerbatimOut}{\NameauthTestFile} % \documentclass{article} % \input{compat.tex} % Included with nameauth; example file aids % % compatibility across different LaTeX versions and engines. % \usepackage{makeidx} % \usepackage[altformat]{nameauth} % % \makeindex % % \newif\ifCaps % Replaces \if@nameauth@DoAlt % \newif\ifFirstCap % Replaces \if@nameauth@DoCaps % \newif\ifInHook % Replaces \if@nameauth@InHook % \Capstrue % Replaces \AltFormatActive % % % Alternate formatting macro definition % \renewcommand*\textSC[1]{\ifCaps\textsc{#1}\else#1\fi} % % % Redefinition of \AltCaps and \CapThis % \renewcommand*\AltCaps[1]{% % \ifInHook % \ifFirstCap\MakeUppercase{#1}\else#1\fi % \else % #1% % \fi % } % \renewcommand*\CapThis{\FirstCaptrue} % % \renewcommand*\NamesFormat[1] % {\InHooktrue#1\global\FirstCapfalse} % % \renewcommand*\MainNameHook[1] % {\Capsfalse\InHooktrue#1\global\FirstCapfalse} % % \let\FrontNamesFormat\Namesformat % \let\FrontNameHook\MainNameHook % % \begin{nameauth} % \< Luth & Martin & \noexpand\textSC{Luther} & > % \< Cath & Catherine \noexpand\AltCaps{d}e' % & \noexpand\textSC{Medici} & > % \end{nameauth} % \PretagName[Martin]{\noexpand\textSC{Luther}}{Luther, Martin} % \PretagName[Catherine \noexpand\AltCaps{d}e'] % {\noexpand\textSC{Medici}}{Medici, Catherine de} % % \begin{document} % % \ForgetThis\Luth\ was a leading figure in the Protestant % Reformation. \Luth\ believed that one is declared % righteous in a forensic sense by divine grace through faith % created by the Holy Spirit via the Gospel and the Sacraments. % % \ForgetThis\Cath\ was not only Queen of France in her own right, % but she also guided the reigns of her three sons. % \CapThis\LCath[\noexpand\AltCaps{d}e'] % was blamed for the St.\ Bartholomew's Day massacre that saw the % murder of thousands of Huguenots. % % \printindex % \end{document} % \end{VerbatimOut} % % \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 ``back-end'' macros with other documents that were designed for the built-in macros used in alternate formatting, as the next example shows: % % \begin{quote} % \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. % % \subsubsection{Names In Boxes} % % Since \textsf{nameauth} uses \textsf{xparse}, the next examples use it also. Here we look at decorationin the sense of putting a name into something around it. This could be useful if, in certain parts of a document, one wanted to turn names into hyperlinks or some other kind of feature. Here we simply put names into colored boxes. % % \ifdefined\NameauthDoTestFiles \edef\NameauthTestFile{test13_04.tex}\else % \edef\NameauthTestFile{\jobname.tmp}\fi % % \begin{VerbatimOut}{\NameauthTestFile} % \documentclass{article} % \input{compat.tex} % Included with nameauth; example file aids % % compatibility across different LaTeX versions and engines. % \usepackage{makeidx} % \usepackage[altformat]{nameauth} % \usepackage{xcolor} % % \makeindex % % \makeatletter % % Change the general-case name macro to show % % a name in a framed, colored box. % % \NewDocumentCommand{\MyName}{O{} m O{}}{% % \global\@nameauth@toksa\expandafter{#1}% % \global\@nameauth@toksb\expandafter{#2}% % \global\@nameauth@toksc\expandafter{#3}% % \fcolorbox{black}{gray!25!white}{\@nameauth@Name[#1]{#2}[#3]}% % } % % % Likewise change the macro for when names are forced long. % \NewDocumentCommand{\MyLName}{O{} m O{}}{% % \global\@nameauth@toksa\expandafter{#1}% % \global\@nameauth@toksb\expandafter{#2}% % \global\@nameauth@toksc\expandafter{#3}% % \fcolorbox{black}{green!25!white}{\@nameauth@Name[#1]{#2}[#3]}% % } % % % Likewise change the macro when personal names are desired. % \NewDocumentCommand{\MyFName}{O{} m O{}}{% % \global\@nameauth@toksa\expandafter{#1}% % \global\@nameauth@toksb\expandafter{#2}% % \global\@nameauth@toksc\expandafter{#3}% % \fcolorbox{black}{yellow!25!white}{\@nameauth@Name[#1]{#2}[#3]}% % } % \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; \Name*[Adolf]{Harnack}[Adolf von]; \FName[Adolf]{Harnack}. % % \printindex % \end{document} % \end{VerbatimOut} % % \begin{quote} % \VerbatimInput[gobble=0]{\NameauthTestFile} % % \makeatletter % \NewDocumentCommand{\MyName}{O{} m O{}}{^^A % \global\@nameauth@toksa\expandafter{#1}^^A % \global\@nameauth@toksb\expandafter{#2}^^A % \global\@nameauth@toksc\expandafter{#3}^^A % \fcolorbox{black}{gray!25!white}{\@nameauth@Name[#1]{#2}[#3]}^^A % } % % \NewDocumentCommand{\MyLName}{O{} m O{}}{^^A % \global\@nameauth@toksa\expandafter{#1}^^A % \global\@nameauth@toksb\expandafter{#2}^^A % \global\@nameauth@toksc\expandafter{#3}^^A % \fcolorbox{black}{green!25!white}{\@nameauth@Name[#1]{#2}[#3]}^^A % } % % \NewDocumentCommand{\MyFName}{O{} m O{}}{^^A % \global\@nameauth@toksa\expandafter{#1}^^A % \global\@nameauth@toksb\expandafter{#2}^^A % \global\@nameauth@toksc\expandafter{#3}^^A % \fcolorbox{black}{yellow!25!white}{\@nameauth@Name[#1]{#2}[#3]}^^A % } % % \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; \Name*[Adolf]{Harnack}[Adolf von]; \FName[Adolf]{Harnack}. % \end{quote} % % After the name is printed in the body text, the internal macros \emph{globally} set \cmd{\@nameauth@FullNamefalse} and \cmd{\@nameauth@FirstNamefalse}, as well as other flags related to the prefix macros. This prevents certain cases of undocumented behavior in versions of \textsf{nameauth} before 3.3, where resetting flags locally could cause unexpected name forms. If an existing document leverages the local resetting of flags, one can use the \texttt{oldreset} option. % % 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}. % % \newpage % % \subsubsection{Change Parsing} % \label{sec:ChangeParse} % % In Section~\ref{sec:FinalOptargs} we saw reasons why \textsf{nameauth} ignores spaces before final optional arguments. Here we show how to change that. With \textsf{xparse} since May 2018, the \texttt{!O\{\}} specifier makes spaces significant before an optional argument. Before then, the example below got the same result through undocumented behavior, now fixed. % % \begin{VerbatimOut}{\jobname.tmp} % \makeatletter % \@ifl@t@r\fmtversion{2018/04/30}{\def\nameauthxp{}}{} % \makeatother % % \makeatletter % \ifdefined\nameauthxp % \NewDocumentCommand{\MyName}{O{} m !O{}}{% % \global\@nameauth@toksa\expandafter{#1}% % \global\@nameauth@toksb\expandafter{#2}% % \global\@nameauth@toksc\expandafter{#3}% % \@nameauth@Name[#1]{#2}[#3]% % } % \else % \NewDocumentCommand{\MyName}{O{} m O{}}{% % \global\@nameauth@toksa\expandafter{#1}% % \global\@nameauth@toksb\expandafter{#2}% % \global\@nameauth@toksc\expandafter{#3}% % \@nameauth@Name[#1]{#2}[#3]% % } % \fi % \makeatother % % \let\NameauthName\MyName % \let\NameauthLName\MyName % \let\NameauthFName\MyName % % \ForgetName[Albert]{Einstein} % \ForgetName{Miyazaki, Hayao} % % We want ``Albert Einstein [reportedly] said'', % ``Miyazaki Hayao [supposedly] said'', % ``Einstein [reportedly] said'', and % ``Miyazaki [supposedly] said''. % % We get ``\Name[Albert]{Einstein} [reportedly] said'', % ``\Name{Miyazaki, Hayao} [supposedly] said'', % ``\Name[Albert]{Einstein} [reportedly] said'', and % ``\Name{Miyazaki, Hayao} [supposedly] said''. % \end{VerbatimOut} % % \begin{quote} %^^A Display the appropriate verbatim text above. % \VerbatimInput[gobble=0]{\jobname.tmp} %^^A Redefine formatting macros. % \renewcommand\NamesFormat{} % \renewcommand\MainNameHook{} % % \makeatletter % \ifdefined\nameauthxp % \NewDocumentCommand{\MyName}{O{} m !O{}}{%^^A % \global\@nameauth@toksa\expandafter{#1}%^^A % \global\@nameauth@toksb\expandafter{#2}%^^A % \global\@nameauth@toksc\expandafter{#3}%^^A % \@nameauth@Name[#1]{#2}[#3]} % \else % \NewDocumentCommand{\MyName}{O{} m O{}}{%^^A % \global\@nameauth@toksa\expandafter{#1}%^^A % \global\@nameauth@toksb\expandafter{#2}%^^A % \global\@nameauth@toksc\expandafter{#3}%^^A % \@nameauth@Name[#1]{#2}[#3]} % \fi % \makeatother % % \let\NameauthName\MyName % \let\NameauthLName\MyName % \let\NameauthFName\MyName % % \ForgetName[Albert]{Einstein} % \ForgetName{Miyazaki, Hayao} % % We want ``Albert Einstein [reportedly] said'', % ``Miyazaki Hayao [supposedly] said'', % ``Einstein [reportedly] said'', and % ``Miyazaki [supposedly] said''. % % We get ``\Name[Albert]{Einstein} [reportedly] said'', % ``\Name{Miyazaki, Hayao} [supposedly] said'', % ``\Name[Albert]{Einstein} [reportedly] said'', and % ``\Name{Miyazaki, Hayao} [supposedly] said''. % \end{quote} % \endgroup^^A General format hook redefinition % % \ReturnLink % % \newpage % % \section{Technical Notes and Tips} % \label{sec:TechNotes} % % \subsection{Tips: General} % % \begin{itemize} % \item Technical details about package development and testing are in \texttt{README.md}. % \item Both \texttt{compat.tex} and \texttt{examples.tex} contain useful information. % \item Do not put naming macros withing a macro defined by \cmd{\edef}. % Yet naming macros can be passed as arguments to such a macro. % \item In \texttt{dtx} files, the \texttt{nameauth} environment and initial tagging % macros work easiest in the \texttt{} section preamble. Yet if any of these % contains one or more \cmd{\newif} statements, they must go in the ``commented part'' % since the preamble falls between \texttt{\textbackslash iffalse} and % \texttt{\textbackslash fi}. % \end{itemize} % % \subsection[Tips: Indexing]{Tips: Indexing and Sorting} % \label{sec:DebugSort} % % \begin{itemize} % \item Two names may look alike on the page, but their name patterns can % differ, creating spurious index entries. Check the \texttt{idx} file % to be sure. % \item To fix spurious entries, compare index entries with names in the text. % \begin{itemize} % \item Check if naming macros always use the same arguments. % \item Check sorting tags (\cmd{\PretagName} (Section~\ref{sec:IndexSort}). % \item Check use of active Unicode characters (Section~\ref{sec:Unicode}). % \item Use \cmd{\ShowPattern}, \cmd{\ShowIdxPageref}, and % \cmd{\ShowNameState}. % \item Did \cmd{\noexpand} precede macros in name arguments? % \end{itemize} % \item Check \textsf{nameauth} package warnings. Set the \texttt{verbose} % option, which will offer a number of ``informational'' warnings that % could be of assistance. % \item If an entry is sorted incorrectly in the index, check the following: % \begin{itemize} % \item Are there any active characters, spaces, or control sequences % in the name arguments? Use \cmd{\PretagName}. % \item Is alternate formatting used consistently? Are names used % within sections of alternate formatting used outside of them? % \item Are macros in the name arguments that can expand differently % under different conditions preceded by \cmd{\noexpand}? % \end{itemize} % \end{itemize} % % Using \cmd{\protected@edef} in macros can add spaces to index entries. The \textsf{nameauth} macros must use \cmd{\protected@edef} to work with classes that write index entries to \texttt{aux} files. One must check this in the \texttt{idx} file. We show this below: % % \begin{quote} % \begin{Verbatim} % \makeatletter % \newcommand\Idx[1]{\protected@edef\arg{#1}\index{\arg}} % \makeatother % \end{Verbatim} % % \cmd{\Idx\{}\cmd{\textsc\{football\}\}} produces:\\ % \hbox{}\qquad\cmd{\indexentry}\texttt % {\{\cmd{\textsc\textvisiblespace\textvisiblespace}\{football\}\}\{}\meta % {page}\texttt{\}}\\[1ex] % The macro \cmd{\index\{}\cmd{\textsc\{football\}\}} produces:\\ % \hbox{}\qquad\cmd{\indexentry}\texttt % {\{\cmd{\textsc}\{football\}\}\{}\meta{page}\texttt{\}} % \end{quote} % % \subsection[Tips: Name Args]{Tips: Macros in Name Arguments} % % \begin{itemize} % \item A missing square bracket or curly brace in name arguments can cause errors like % ``\texttt{Paragraph ended}'' and ``\texttt{Missing} \meta{grouping token} % \texttt{inserted.}'' % \item Use alternate formatting to avoid potential problems, especially % when using \cmd{\CapThis}, which segments arguments (Sections~\ref{sec:AltFormat}, % \ref{sec:AdvCustomize}). % \item Use \cmd{\noexpand}\meta{macro} in name macro arguments as % a best practice. % \item Macros used in name arguments must be defined either in the % preamble or in the outermost document scope to avoid errors. % \item Boolean flags (\texttt{\textbackslash if}\meta{flag}) used in % formatting hooks must be defined either in the preamble or in the % outermost document scope. % \item The \cmd{\global} modifier does not work with \cmd{\newif} and % \cmd{\newcommand}. Yet \cmd{\global} can precede the use of a macro % defined with \cmd{\newcommand}. % \textit{The \TeX book}, pages 275--277, shows what \cmd{\global} can % and cannot do. See more about this issue and \cmd{\newcommand} on % \href{https://tex.stackexchange.com/questions/51733/global-renewcommand-equivalent-of-global-def} % {\bfseries this page}. % \item Below we show general aspects of scoping to apply them to this package: % \end{itemize} % % \begin{VerbatimOut}{\jobname.tmp} % \newif\ifCondA % \newcommand\MacroA{} % \begingroup % \newif\ifCondB % \global\newif\ifCondC % \global\newcommand\MacroB{} % \newcommand\MacroC{\def\MacroD{}} % \global\MacroC % \global\CondAtrue % \endgroup % % \begin{itemize} % \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} % \end{VerbatimOut} % % \begin{quote} % \VerbatimInput[gobble=0]{\jobname.tmp} % % \input{\jobname.tmp} % \end{quote} % % Any macro that is used in the argument of a naming macro must be defined in all scopes in which that name is used. The names themselves are global, but macros in their arguments are not guaranteed to be so: % % \begin{VerbatimOut}{\jobname.tmp} % \begin{nameauth} % \< Testi & & \noexpand\TESTi & > % \< Testii & & \noexpand\TESTii & > % \end{nameauth} % \def\TESTi{Test One} % \indent \hbox to 10em{(Outer 1) \Testi\hfill} % \begingroup % (Inner 1) \Testi\\ % \def\TESTii{Test Two} % \hbox to 10em{(Inner 2) \Testii\hfill} % \endgroup % (Outer 2) \unless\ifdefined\TESTii \cmd{\TESTii} undefined\fi % \end{VerbatimOut} % % \begin{quote} % \IndexInactive % \VerbatimInput[gobble=0]{\jobname.tmp} % % \input{\jobname.tmp} % \end{quote} % % % \subsection[Active Unicode]{Active Unicode Characters} % \label{sec:Unicode} % % \subsubsection{General Information} % % Both \texttt{xelatex} and \texttt{lualatex} support Unicode natively. In \texttt{pdflatex}, this happens with active characters. There are features (e.g., in \textsf{microtype}) that require \texttt{pdflatex}. Both \texttt{makeindex} and \texttt{xindy} have their own design choices. % % With |\usepackage[T1]{fontenc}|, \texttt{latex} and \texttt{pdflatex} can use many active Unicode characters automatically. Use \cmd{\PretagName} to sort names with these characters (Section~\ref{sec:IndexSort}). More Unicode characters can be made available when using fonts with TS1 glyphs (pages 455--463 in \textit{The Latex Companion}). Compare \href{https://tug.ctan.org/info/symbols/comprehensive/}{\bfseries this page} or type either \texttt{texdoc comprehensive}, \texttt{texdoc symbols-A4}, or \texttt{texdoc symbols-letter} for more information. % % 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} % \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} % % Below we group characters that are supported in \texttt{pdflatex} % without additional modification by accents and diacritical marks: % % \begin{center}\large % \def\Bullet#1{\setbox0\hbox{#1}\raise 0.4ex\hbox % to\wd0{\hfil\tiny\textbullet\hfil}} % \def\bullet#1{\setbox0\hbox{#1}\raise 0.2ex\hbox % to\wd0{\hfil\tiny\textbullet\hfil}} % \begin{tabular}{ll}\toprule % \rowcolor{nagrey}^^A % \bfseries Capitals & \strut\\ % % acute & Á Ć \Bullet{D} É Ǵ \Bullet{H} Í \Bullet{J} \Bullet{K} Ĺ % Ń Ó Ŕ Ś \Bullet{T} Ú \Bullet{W} Ý Ź \strut\\ % % \rowcolor{nagrey}^^A % grave & À \Bullet{C} \Bullet{D} È \Bullet{G} \Bullet{H} Ì \Bullet{J} % \Bullet{K} \Bullet{L} \Bullet{N} Ò \Bullet{R} \Bullet{S} % \Bullet{T} Ù \Bullet{W} \Bullet{Y} \Bullet{Z} \strut\\ % % circumflex &  Ĉ \Bullet{D} Ê Ĝ Ĥ Î Ĵ \Bullet{K} \Bullet{L} % \Bullet{N} Ô \Bullet{R} Ŝ \Bullet{T} Û Ŵ Ŷ % \Bullet{Z} \strut\\ % % \rowcolor{nagrey}^^A % tilde & à \Bullet{C} \Bullet{D} \Bullet{E} \Bullet{G} \Bullet{H} % Ĩ \Bullet{J} \Bullet{K} \Bullet{L} Ñ Õ \Bullet{R} % \Bullet{S} \Bullet{T} Ũ \Bullet{W} \Bullet{Y} % \Bullet{Z} \strut\\ % % diaeresis\footnotemark & Ä \Bullet{C} \Bullet{D} Ë \Bullet{G} \Bullet{H} % Ï \Bullet{J} \Bullet{K} \Bullet{L} \Bullet{N} Ö \Bullet{R} % \Bullet{S} \Bullet{T} Ü \Bullet{W} Ÿ \Bullet{Z} \strut\\ % % \rowcolor{nagrey}^^A % cedilla & \Bullet{A} Ç \Bullet{D} \Bullet{E} Ģ \Bullet{H} \Bullet{I} % \Bullet{J} Ķ Ļ Ņ \Bullet{O} Ŗ Ş Ţ \Bullet{U} \Bullet{W} % \Bullet{Y} \Bullet{Z} \strut\\ % % macron & Ā \Bullet{C} \Bullet{D} Ē Ḡ \Bullet{H} Ī \Bullet{J} % \Bullet{K} \Bullet{L} \Bullet{N} Ō \Bullet{R} \Bullet{S} % \Bullet{T} Ū Ǣ Ȳ \Bullet{Z} \strut\\ % % \rowcolor{nagrey}^^A % breve & Ă \Bullet{C} \Bullet{D} \Bullet{E} Ğ \Bullet{H} Ĭ \Bullet{J} % \Bullet{K} \Bullet{L} \Bullet{N} Ŏ \Bullet{R} \Bullet{S} % \Bullet{T} Ŭ \Bullet{W} \Bullet{Y} \Bullet{Z} \strut\\ % % dot/dotless & Ḃ Ċ \Bullet{D} Ė Ġ \Bullet{H} İ \Bullet{J} \Bullet{K} % \Bullet{L} \Bullet{N} \Bullet{O} \Bullet{R} \Bullet{S} % \Bullet{T} \Bullet{U} \Bullet{W} \Bullet{Y} Ż \strut\\ % % \rowcolor{nagrey}^^A % ogonek & Ą \Bullet{C} \Bullet{D} Ę \Bullet{G} \Bullet{H} Į \Bullet{J} % \Bullet{K} \Bullet{L} \Bullet{N} Ǫ \Bullet{R} \Bullet{S} % \Bullet{T} Ų \Bullet{W} \Bullet{Y} \Bullet{Z} \strut\\ % % caron & Ǎ Č Ď Ě Ǧ \Bullet{H} Ǐ \Bullet{J} Ǩ Ľ Ň Ǒ Ř Š Ť Ǔ \Bullet{W} % \Bullet{Y} Ž \strut\\ % % \rowcolor{nagrey}^^A % various & Å Æ Ð (eth) Đ (stroke) IJ\ Ł % Ŋ Ø Œ Ő Ů Ű Ș Ț Þ \strut\\\midrule % % \\\midrule % % \rowcolor{nagrey}^^A % \bfseries Lowercase & \strut\\ % % acute & á ć \bullet{d} é ǵ \bullet{h} í \bullet{j} \bullet{k} ĺ % ń ó ŕ ś \bullet{t} ú \bullet{w} ý ź \strut\\ % % \rowcolor{nagrey}^^A % grave & à \bullet{c} \bullet{d} è \bullet{g} \bullet{h} ì \bullet{j} % \bullet{k} \bullet{l} \bullet{n} ò \bullet{r} \bullet{s} % \bullet{t} ù \bullet{w} \bullet{y} \bullet{z} \strut\\ % % circumflex & â ĉ \bullet{d} ê ĝ ĥ î ĵ \bullet{k} \bullet{l} \bullet{n} % ô \bullet{r} ŝ \bullet{t} û ŵ ŷ \bullet{z} \strut\\ % % \rowcolor{nagrey}^^A % tilde & ã \bullet{c} \bullet{d} \bullet{e} \bullet{g} \Bullet{h} ĩ % \bullet{j} \bullet{k} \bullet{l} ñ õ \bullet{r} \bullet{s} % \bullet{t} ũ \bullet{w} \bullet{y} \bullet{z} \strut\\ % % diaeresis & ä \bullet{c} \bullet{d} ë \bullet{g} \bullet{h} ï \bullet{j} % \bullet{k} \bullet{l} \bullet{n} ö \bullet{r} \bullet{s} % \bullet{t} ü \bullet{w} ÿ \bullet{z} \strut\\ % % \rowcolor{nagrey}^^A % cedilla & \bullet{a} ç \bullet{d} \bullet{e} ģ \bullet{h} \bullet{i} % \bullet{j} ķ ļ ņ \bullet{o} ŗ ş ţ \bullet{u} \bullet{w} % \bullet{y} \bullet{z} \strut\\ % % macron & ā \bullet{c} \bullet{d} ē ḡ \bullet{h} ī \bullet{j} % \bullet{k} \bullet{l} \bullet{n} ō \bullet{r} % \bullet{s} \bullet{t} ū ǣ ȳ \bullet{z} \strut\\ % % \rowcolor{nagrey}^^A % breve & ă \bullet{c} \bullet{d} \bullet{e} ğ \bullet {h} ĭ % \bullet{j} \bullet{k} \bullet{l} \bullet{n} ŏ \bullet{r} % \bullet{s} \bullet{t} ŭ \bullet{w} \bullet{y} % \bullet{z} \strut\\ % % dot/dotless & ḃ ċ \bullet{d} ė ġ \bullet{h} ı \bullet{j} \bullet{k} % \bullet{l} \bullet{n} \bullet{o} \bullet{r} \bullet{s} % \bullet{t} \bullet{u} \bullet{w} \bullet{y} ż \strut\\ % % \rowcolor{nagrey}^^A % ogonek & ą \bullet{c} \bullet{d} ę \bullet{g} \bullet{h} į \bullet{j} % \bullet{k} \bullet{l} \bullet{n} ǫ \bullet{r} \bullet{s} % \bullet{t} ų \bullet{w} \bullet{y} \bullet{z} \strut\\ % % caron & ǎ č ď ě ǧ \bullet{h} ǐ ǰ ǩ ľ ň ǒ ř š ť ǔ \bullet{w} % \bullet{y} ž \strut\\ % % \rowcolor{nagrey}^^A % various & å æ ð đ ij\ ł ŋ ø œ ő ů ű ș ß ț þ \strut\\\bottomrule % \end{tabular} % \footnotetext{A diaeresis mark is one way to indicate a sound change % (\textit{Umlaut}). German originally used a superscript \textsf{e} over % \textsf{a}, \textsf{o}, and \textsf{u}. The cursive form of \textsf{e} % simplified to a diaeresis in the 1800s. A diaeresis also signals % pronouncing a diphthong or digraph as two monophthongs, e.g., ``noëtic''.} % \end{center} % % \newpage % % \subsubsection[Compatibility]{Compatibility: Old and New} % \label{sec:CompatON} % % Changes in the way that \texttt{pdflatex} and \texttt{latex} handle Unicode characters since 2018 have made indexing simpler and more intuitive, e.g. % % \begin{center} % \begin{tabular}{rllrll}\toprule % \rowcolor{nagrey}^^A % \bfseries Pre-2018 & & \bfseries Index & % \bfseries Post-2018 & & \bfseries Index\\ % % ä & \textrightarrow & % \texttt{\cmd{\IeC\textvisiblespace}\{\cmd{\"a}\}} & % ä & \textrightarrow & \texttt{ä}\\ % % \rowcolor{nagrey}^^A % æ & \textrightarrow & % \texttt{\cmd{\IeC\textvisiblespace}\{\cmd{\ae\textvisiblespace}\}} & % æ & \textrightarrow & \texttt{æ}\\\bottomrule % \end{tabular} % \end{center} % % The \cmd{\IeC} macro plus its argument then would expand to \cmd{\T1} plus its argument, which would occur especially if accented characters were written out to a file, then read in again. This could cause a number of problems. % % There are two ways to test if one is working with a newer or older version of \texttt{pdflatex} or \texttt{latex}. The first involves \LaTeX\ kernel macros in the document preamble to check the format date. We check if the date is later than the first use of the file \texttt{utf8-2018.def}, If that is the case, we can define macros or set Boolean flags, which we can test repeatedly. For example, in the document preamble we could have: % % \begin{quote} % \begin{Verbatim} % \makeatletter % \@ifl@t@r\fmtversion{2018/10/05}{\def\nameauthltx{}}{} % \@ifl@t@r\fmtversion{2018/04/30}{\def\nameauthxp{}}{} % \makeatother % \end{Verbatim} % \end{quote} % % The tests above apply to two things that are pertinent to \textsf{nameauth}. The first is the presence of \texttt{utf8-2018.def}. The second involves changes in \textsf{xparse} that could impact \textsf{nameauth}, which we used silently in Section~\ref{sec:ChangeParse}. % Another test checks directly for the presence of \texttt{utf8-2018.def}: % % \begin{quote} % \begin{Verbatim} % \IfFileExists{utf8-2018.def} % {do if exists} % {do if absent} % \end{Verbatim} % \end{quote} % % Now we apply the test to an example. Before 2018, some index styles like \texttt{gind.ist} could not work with characters that contained macrons. Since 2018, those restrictions have been removed. % To create a document that can work with old or new versions of \texttt{pdflatex} and \texttt{latex}, one can choose to use macrons or not. In a recent version, one will see macrons in the following names, otherwise, no macron will be present. % \begin{quote} % \begin{Verbatim} % \ifdefined\nameauthltx \Name{Ghazāli} \else \Name{Ghazali}\fi % % \IfFileExists{utf8-2018.def}{\Name{Ghazāli}}{\Name{Ghazali}} % \end{Verbatim} % \ifdefined\nameauthltx \Name{Ghazāli} \else \Name{Ghazali}\fi % % \IfFileExists{utf8-2018.def}{\Name{Ghazāli}}{\Name{Ghazali}} % \end{quote} % % The challenge of compatibility arises in this manual in a few instances, which we summarize below to mention specific resources without going too far afield. % % \begin{itemize} % \item To use older distributions, one must include the \textsf{textcomp} % package for backward compatibility. Otherwise it is not needed in % recent \TeX\ distributions, e.g., since 2018. % \item Use of certain text elements, such as \cmd{\dotfill} within % tables, has become more permissive in recent \TeX\ distributions. % \item The file \texttt{examples.tex} (see \texttt{README.md}) includes % additional code snippets that deal with compatibility. % \item We \cmd{\input} the included snippet \texttt{compat.tex} in % \texttt{examples.tex} to permit use with different \LaTeX\ engines % and older \TeX\ distributions. % \end{itemize}\negbigskip % % \begin{InfoBox} % Users are encouraged to view and modify \texttt{compat.tex} to meet their own needs. % \end{InfoBox}\negbigskip % % \subsubsection[Fragility]{Fragility of Active Unicode} % % \TeX\ macros that partition their arguments can break active Unicode characters.The simple macro |\def\foo#1#2#3!{<#1#2><#3>}| takes three arguments, groups the first two, then the third, followed by a delimiter that ends the argument list: % % \begin{center} % \def\foo#1#2#3!{<#1#2><#3>} % \begin{tabular}{llll}\toprule % \rowcolor{nagrey}^^A % \bfseries Arg. & \bfseries Macro & \bfseries Engine & \bfseries Result\\ % % |abc| & |\foo abc!| & (any) & \foo abc!\\ % |{æ}bc| & |\foo {æ}bc!| & (any) & \foo {æ}bc!\\ % |\ae bc| & |\foo \ae bc!| & (any) & \foo \ae bc!\\ % % \rowcolor{nagrey}^^A % |æbc| & |\foo æbc!| & \texttt{xelatex} & % \ifxetex\foo æbc!\else<æb>\fi\\ % \rowcolor{nagrey}^^A % |æbc| & |\foo æbc!| & \texttt{lualatex} & % \ifluatex\foo æbc!\else<æb>\fi\\ % % |æbc| & |\foo æbc!| & \texttt{pdflatex} & \foo æbc!\\ % |æ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} (c. 388 \textsc{bc})} % \Name{Hermogenes}: I should explain to you, \Name{Socrates}, that our friend \Name{Cratylus} has been arguing about names; he says that they are natural and not conventional; not a portion of the human voice which men agree to use; but that there is a truth or correctness in them, which is the same for Hellenes as for barbarians.^^A % \index{philosophers, quotes of\noexpand\string|hyperpage} % \end{Quote} % % \newpage % % \StopEventually{^^A % \let\emph\oldemph % \newgeometry{textheight=239mm,left=20mm,right=20mm,nohead} % \IndexProtect\PrintChanges\newpage\PrintIndex % } % \iffalse %<*package> % \fi % % \section{Implementation} % % This package has been reorganized so that the manual and the package % have substantially the same ordering. This repetition should aid % understanding how the components work. % % \subsection{Boolean Flags} % % The \textsf{nameauth} package is a parser. The flags in this section % show and change 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 nonwestern name. The second shows the kind of nonwestern % 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 nonwestern 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}. The third toggles whether or not the % name argument token registers are set globally. The fourth toggles the % inclusion of \textsf{xargs} and \textsf{suffix} for legacy cases where % user customizations were made. % % \begin{macrocode} \newif\if@nameauth@OldReset \newif\if@nameauth@OldPass \newif\if@nameauth@OldToks \newif\if@nameauth@OldArgs % \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 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 Format]{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} \DeclareOption{oldargs}{\@nameauth@OldArgstrue} % \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{xparse} % \end{macrocode} % Test for the OldArgs flag and include legacy packages % if the flag is true. % % \begin{macrocode} \if@nameauth@OldArgs \RequirePackage{xargs} \RequirePackage{suffix} \fi % \end{macrocode} % % \newpage % % \addtocontents{toc}{\protect\goodbreak} % \subsection{Internal Macros} % \label{sec:InternalMacros} % % \subsubsection{Fundamental Macros} % % The following macros are the most essential to the concept of ``name''. % % \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} % % \newpage\noindent % % 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} % % \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 path is for nonwestern names. The \texttt{\#1} argument is % used both here and below when \cmd{\@nameauth@SB} is present. The % \texttt{\#1} path always corresponds to the present syntax. % Thus, when printing names in the text, the \texttt{\#1} argument % must test both \cmd{\@nameauth@C} and \cmd{\@nameauth@SB}, replacing % the latter with former ifit exists. With indexing and other macros, % 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 nonwestern names that use % the obsolete syntax. Here \cmd{\@nameauth@SB} % never occurs. For indexing and control sequences, one cannot ignore % the use of \cmd{\@nameauth@C} in this path. % % \begin{macrocode} \let\NameauthPattern\@nameauth@csbc% \NameauthWesternfalse \NameauthObsoletetrue% #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. That shows we are again using the current % syntax with a potential name swap. % % \begin{macrocode} \let\NameauthPattern\@nameauth@csb% \NameauthWesternfalse \NameauthObsoletefalse% #1% \fi \fi \else % \end{macrocode} % This decision path is for Western names. When printing % names in the text, somewhere in the \texttt{\#3} % argument one must test for \cmd{\@nameauth@C} and swap it for % \cmd{\@nameauth@A}. One also must check for and handle % \cmd{\@nameauth@SB}. Otherwise, for indexing and control sequences, % one ignores \cmd{\@nameauth@C} in this path and handles % \cmd{\@nameauth@SB} appropriately. % % \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} % \changes{4.0}{2024/02/09}{Use \textsf{xparse}} % \Name*[Marc van]{Dongen} provided the original basic structure. % Parsing, indexing, and formatting are more modularized than % in earlier versions. % % \begin{macrocode} \NewDocumentCommand{\@nameauth@Name}{O{} m O{}} {% % \end{macrocode} % Both \cmd{\@nameauth@Name} and \cmd{\AKA} engage the lock below, % preventing a stack overflow. Tell the formatting mechanism that % it is being called from % \cmd{\@nameauth@Name}. % % \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} % Nonwestern 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} % Nonwestern 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 nonwestern 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} % % \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 Format]{Alternate Formatting} % % \begin{macro}{\AltFormatActive} % \changes{3.1}{2017/01/13}{Added} % \changes{4.0}{2024/02/09}{Combine starred, un-starred macros} % \begin{macro}{\AltFormatActive*}\end{macro}\vspace{-2.7ex} % Turn on alternate formatting and % disengage the formatting macros if using the starred form or % engage the formatting macros if using the un-starred form. % % \begin{macrocode} \NewDocumentCommand{\AltFormatActive}{s} {% \global\@nameauth@AltFormattrue% \IfBooleanTF{#1} {\global\@nameauth@DoAltfalse} {\global\@nameauth@DoAlttrue}% } % \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} % Nonwestern 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} % Nonwestern 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} % \changes{4.0}{2024/02/09}{Combine starred, un-starred macros} % \begin{macro}{\Name*}\end{macro}\vspace{-2.7ex} % \cmd{\Name} calls \cmd{\NameauthName}, the interface hook, printing % a long name and calling \cmd{\NameauthLName} when using the starred form. % % \begin{macrocode} \NewDocumentCommand{\Name}{s} {% \IfBooleanTF{#1} {\@nameauth@FullNametrue\NameauthLName} {\NameauthName}% } % \end{macrocode} % \end{macro} % % \begin{macro}{\FName} % \changes{0.9}{2012/02/10}{Added} % \changes{4.0}{2024/02/09}{Combine starred, un-starred macros} % \begin{macro}{\FName*}\end{macro}\vspace{-2.7ex} % \cmd{\FName} sets up a short name instance and calls \cmd{\NameauthFName}, % the interface hook. Its starred form is identical in function. % % \begin{macrocode} \NewDocumentCommand{\FName}{s} {\@nameauth@FirstNametrue\NameauthFName} % \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 % nonwestern 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} % \changes{4.0}{2024/02/09}{Use \textsf{xparse}} % This displays the pattern that the name arguments generate; % useful for debugging. We test for bad input, then load the argument % values into the appropriate macros. We determine the name type % and produce the output of the appropriate name control sequence. % % \begin{macrocode} \NewDocumentCommand{\ShowPattern}{O{} m O{}} {% \@nameauth@Error{#2}{macro: \string\ShowPattern}% \@nameauth@LoadArgs{#1}{#2}{#3}% \@nameauth@Choice{}{}{}\NameauthPattern% } % \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} % \changes{4.0}{2024/02/09}{Combine starred, un-starred macros} % \begin{macro}{\ShowIdxPageref*}\end{macro}\vspace{-2.7ex} % Show an index page entry appearance for given name parameters. % \begin{macrocode} \NewDocumentCommand{\ShowIdxPageref}{s O{} m O{}} {% \IfBooleanTF {#1}% % \end{macrocode} % The starred form displays a basic index entry with no tag. % Test for bad input, load the argument values into % the appropriate macros, then call the back-end. % % \begin{macrocode} {% \@nameauth@Error{#3}{macro: \string\ShowIdxPageref*}% \@nameauth@LoadArgs{#2}{#3}{#4}% \@nameauth@IdxPageref{#2}{#3}{#4}% }% % \end{macrocode} % The un-starred form displays (expanded, as printed) the index % entry that will be generated, but not exactly what is in the % \texttt{idx} file. % Test for bad input, load the argument values into % the appropriate macros, then call the back-end. % % \begin{macrocode} {% \@nameauth@Error{#3}{macro: \string\ShowIdxPageref}% \@nameauth@LoadArgs{#2}{#3}{#4}% \global\@nameauth@LongIdxDebugtrue% \@nameauth@IdxPageref{#2}{#3}{#4}% }% } % \end{macrocode} % \end{macro} % % \begin{macro}{\ShowNameInfo} % \changes{3.7}{2023/02/03}{Added} % \changes{4.0}{2024/02/09}{Use \textsf{xparse}, improve output} % Show how the name arguments are being interpreted by the % \textsf{nameauth} macros, but as detokenized text, % % \begin{macrocode} \NewDocumentCommand{\ShowNameInfo}{O{} m O{}} {% % \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 nonwestern names using the current syntax. % % \begin{macrocode} \@nameauth@Choice {% (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} % Next is nonwestern names using the obsolete syntax. % % \begin{macrocode} {% (SNN: \expandafter\detokenize\expandafter{\@nameauth@B})% \unless\ifx\@nameauth@C\@empty \ (Alt*: \expandafter\detokenize\expandafter{\@nameauth@C})% \fi }% % \end{macrocode} % 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} % \changes{4.0}{2024/02/09}{Use \textsf{xparse}} % This macro tells the user what control sequence patterns % exist for any given name. % % \begin{macrocode} \NewDocumentCommand{\ShowNameState}{O{} m O{}} {% % \end{macrocode} % Create a local scope to kill any local definitions on exit. % Test for bad input, then load the argument values into % the appropriate macros. % % \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} % \changes{4.0}{2024/02/09}{Use \textsf{xparse}} % This creates an index entry with page entries. It warns if % the \cmd{\SkipIndex} prefix macro was used before it was called. % It issues additional warnings if the \texttt{verbose} option is selected. % It prints nothing. % % \begin{macrocode} \NewDocumentCommand{\IndexName}{O{} m O{}} {% % \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} % Nonwestern 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} % Nonwestern 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} % \changes{4.0}{2024/02/09}{Use \textsf{xparse}} % Create a cross-reference that is not already an exclusion or % a cross-reference. Print nothing. % % \begin{macrocode} \NewDocumentCommand{\IndexRef}{O{} m O{} m} {% % \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} % % 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} % Nonwestern 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} % \changes{4.0}{2024/02/09}{Use \textsf{xparse}} % Prevent a name from being indexed by initializing a regular % cross-reference control sequence with the value of % \cmd{\@nameauth@Exclude}. % % \begin{macrocode} \NewDocumentCommand{\ExcludeName}{O{} m O{}} {% % \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} % % 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} % \changes{4.0}{2024/02/09}{Combine starred, un-starred macros} % \begin{macro}{\IncludeName*}\end{macro}\vspace{-2.7ex} % Allow names to be included as page entries, even if they have been % used as cross-references. % \begin{macrocode} \NewDocumentCommand{\IncludeName}{s O{} m O{}} {% \IfBooleanTF {#1}% % \end{macrocode} % The starred form allows any name to be indexed by voiding any % exclusion or cross-reference. % Process and load the arguments into the appropriate macros. % Check for errors, get the current name pattern, then nuke it. % % \begin{macrocode} {% \@nameauth@LoadArgs{#2}{#3}{#4}% \@nameauth@Error{#3}{macro \string\IncludeName*}% \@nameauth@Choice{}{}{}% \global\csundef{\NameauthPattern!PN}% }% % \end{macrocode} % The un-starred form allows a name to be indexed once again only if % it had been excluded. % 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{#2}{#3}{#4}% \@nameauth@Error{#3}{macro \string\IncludeName}% \@nameauth@Choice {\def\@nameauth@Temp{\expandafter\detokenize\expandafter{#3}}} {\def\@nameauth@Temp{\expandafter\detokenize\expandafter{#3 #4}}} {\def\@nameauth@Temp{\expandafter\detokenize\expandafter{#2 #3}}}% % \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}{\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} % \changes{4.0}{2024/02/09}{Use \textsf{xparse}} % This creates an index entry tag that is applied before a name % by \cmd{\@nameauth@Index}. % % \begin{macrocode} \NewDocumentCommand{\PretagName}{O{} m O{} m} {% % \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} % \changes{4.0}{2024/02/09}{Use \textsf{xparse}} % This creates an index entry tag for a name that is not either % an exclusion or a cross-reference. % % \begin{macrocode} \NewDocumentCommand{\TagName}{O{} m O{} m} {% % \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} % % \newpage % % \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} % \changes{4.0}{2024/02/09}{Use \textsf{xparse}} % This deletes an index tag. % % \begin{macrocode} \NewDocumentCommand{\UntagName}{O{} m O{}} {% \@nameauth@LoadArgs{#1}{#2}{#3}% \@nameauth@Error{#2}{macro \string\UntagName}% \@nameauth@Choice{}{}{}% \global\csundef{\NameauthPattern!TAG}% } % \end{macrocode} % \end{macro} % % \subsubsection{Name 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} % \changes{4.0}{2024/02/09}{Use \textsf{xparse}} % 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} \NewDocumentCommand{\NameAddInfo}{O{} m O{} +m} {% \@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} % \changes{4.0}{2024/02/09}{Use \textsf{xparse}} % This prints the information created by \cmd{\NameAddInfo} if it exists. % % \begin{macrocode} \NewDocumentCommand{\NameQueryInfo}{O{} m O{}} {% \unless\if@nameauth@BigLock \@nameauth@LoadArgs{#1}{#2}{#3}% \@nameauth@Error{#2}{macro \string\NameQueryInfo}% \@nameauth@Choice{}{}{}% \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} % \changes{4.0}{2024/02/09}{Use \textsf{xparse}} % This deletes a text tag. It has the same structure as \cmd{\UntagName}. % % \begin{macrocode} \NewDocumentCommand{\NameClearInfo}{O{} m O{}} {% \@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} % \changes{4.0}{2024/02/09}{Use \textsf{xparse}} % 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} \NewDocumentCommand{\IfMainName}{O{} m O{} +m +m} {% \@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} % \changes{4.0}{2024/02/09}{Use \textsf{xparse}} % 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} \NewDocumentCommand{\IfFrontName}{O{} m O{} +m +m} {% \@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} % % \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} % \changes{4.0}{2024/02/09}{Use \textsf{xparse}} % 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} \NewDocumentCommand{\IfAKA}{O{} m O{} +m +m +m} {% \@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} % \changes{4.0}{2024/02/09}{Use \textsf{xparse}} % This undefines a control sequence to force a ``first use''. % % \begin{macrocode} \NewDocumentCommand{\ForgetName}{O{} m O{}} {% % \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} % \changes{4.0}{2024/02/09}{Use \textsf{xparse}} % This defines a control sequence to force a ``subsequent use''. % % \begin{macrocode} \NewDocumentCommand{\SubvertName}{O{} m O{}} {% \@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} % % \newpage % % \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} % \changes{4.0}{2024/02/09}{Combine starred, un-starred macros} % \begin{macro}{\AKA*}\end{macro}\vspace{-2.7ex} % \cmd{\AKA} prints an alternate name and creates index cross-references. % The starred form displays the alternate name like \cmd{\FName}. % % \begin{macrocode} \NewDocumentCommand{\AKA}{s O{} m O{} m O{}} {% % \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 \IfBooleanTF {#1}{\@nameauth@AltAKAtrue}{}% \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{#3}{macro \string\AKA}% \@nameauth@Error{#5}{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{#2}}% \protected@edef\@nameauth@Bi{\@nameauth@Root{#3}}% \protected@edef\@nameauth@Si{\@nameauth@Suffix{#3}}% \@nameauth@Parse{#4}{#5}{#6}{!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[#4]{#5}[#6]{\@nameauth@Bi}% \else \IndexRef[#4]{#5}[#6] {\@nameauth@Bi\@nameauth@space\@nameauth@Si}% \fi \else \ifx\@nameauth@Si\@empty \IndexRef[#4]{#5}[#6] {\@nameauth@Bi,\@nameauth@space\@nameauth@Ai}% \else \IndexRef[#4]{#5}[#6] {\@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}{\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} % \changes{4.0}{2024/02/09}{Combine starred, un-starred macros} % \begin{macro}{\PName*}\end{macro}\vspace{-2.7ex} % \cmd{\PName} is a convenience macro that calls \cmd{\NameauthName}, then \cmd{\AKA}. Its starred form prints a long name. % % \begin{macrocode} \NewDocumentCommand{\PName}{s O{} m O{} m O{}} {% % \end{macrocode} % If we have a starred form, we will display a long name. % If we used \cmd{\JustIndex}, we ignore and reset its flag to false. % % \begin{macrocode} \IfBooleanTF {#1}{\@nameauth@FullNametrue}{}% \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[#2]{#3} (\SkipIndex\AKA[#2]{#3}[#4]{#5}[#6])% \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[#2]{#3} \@nameauth@SeeAlsotrue(\AKA[#2]{#3}[#4]{#5}[#6])% \else \NameauthName[#2]{#3} (\AKA[#2]{#3}[#4]{#5}[#6])% \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} % % \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 Some Examples} \author{Charles P. Schaum} \date{2024/02/09} \begin{document} \maketitle \phantomsection \pdfbookmark[1]{\contentsname}{toc} \tableofcontents \newpage % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % \section{Minimal Example} \textbf{Group 1}\\ \begin{enumerate*} \item[\textbf{1.}] \Doug\ rose to eminence by sheer force of character and talents that neither slavery nor caste proscription could crush. \item[\textbf{2.}] \Doug's early life is perhaps the most complete indictment of the slave system ever presented at the bar of public opinion. \item[\textbf{3.}] \Doug\ was born in February, l8l7. His earliest memories centered around the cabin of his grandmother, \Bailey. \end{enumerate*} \medskip\noindent\textbf{Group 2}\\ \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*} % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % \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 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 instances of ``\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 instances of ``\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 name 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 name tag in ``first'' instance \newif\ifNoTag % Redesign formatting hook to usually print a tag % only in ``first'' instance. 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 instance via: \NoTagtrue\ForgetThis\Name[George]{Washington}. Or we can trigger the first-use hook in a subsequent name use and still have dates: \ForceName\Name[George]{Washington}. \index{life dates} 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 name 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 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} \NoAgnomentrue\Scipio\ was born around 236 \textsc{bc} into the Scipiones branch of the Cornelii clan. \NoAgnomentrue\Scipio\ rose to military fame during the Second Punic War. Thereafter he was known as \Scipio. 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 tags. \renewcommand*\NamesFormat[1] {% \ifNoPraenomen\XPraetrue\fi% \ifNoGens\XGenstrue\fi% \ifNoCognomen\XCogntrue\fi% \ifNoAgnomen\XAgnotrue\fi% #1% \ifcsname\NameauthPattern!DB\endcsname \expandafter\csname\NameauthPattern!DB\endcsname% \fi \global\NoPraenomenfalse% \global\NoGensfalse% \global\NoCognomenfalse% \global\NoAgnomenfalse% } \TGrac\ served as tribune of the plebs in 184 \textsc{bc}. \TGrac\ was elected praetor for 180 \textsc{bc}, after which he was appointed governor of Hispania Citerior, serving with the rank of proconsul. In 177 \textsc{bc}, he was elected consul, again in 163 \textsc{bc}. % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % \section{Roman Names: Scholarly Work} % 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 nonwestern 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% } \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 \AltOn \AltOff \newif\ifFirstCap % Replaces \if@nameauth@DoCaps \AltCaps \newif\ifInHook % Replaces \if@nameauth@InHook hook dispatcher \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} \subsection[With xparse]{With \textsf{xparse}} \makeatletter % Change the general-case name macro to show % a name in a framed, colored box. \NewDocumentCommand{\MyName}{O{} m O{}}{% \global\@nameauth@toksa\expandafter{#1}% \global\@nameauth@toksb\expandafter{#2}% \global\@nameauth@toksc\expandafter{#3}% \fcolorbox{black}{gray!25!white}{\@nameauth@Name[#1]{#2}[#3]}% } % Likewise change the macro for when names are forced long. \NewDocumentCommand{\MyLName}{O{} m O{}}{% \global\@nameauth@toksa\expandafter{#1}% \global\@nameauth@toksb\expandafter{#2}% \global\@nameauth@toksc\expandafter{#3}% \fcolorbox{black}{green!25!white}{\@nameauth@Name[#1]{#2}[#3]}% } % Likewise change the macro when personal names are desired. \NewDocumentCommand{\MyFName}{O{} m O{}}{% \global\@nameauth@toksa\expandafter{#1}% \global\@nameauth@toksb\expandafter{#2}% \global\@nameauth@toksc\expandafter{#3}% \fcolorbox{black}{yellow!25!white}{\@nameauth@Name[#1]{#2}[#3]}% } \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; \Name*[Adolf von]{Harnack}; \FName[Adolf]{Harnack}. \AltFormatInactive \makeatletter \renewcommand*\NameauthName{\@nameauth@Name} \renewcommand*\NameauthLName{\@nameauth@Name} \renewcommand*\NameauthFName{\@nameauth@Name} \makeatother \renewcommand*\NamesFormat{} \renewcommand*\MainNameHook{} \subsection[With xargs]{With \textsf{xargs}} \makeatletter % Change the general-case name macro to show % a name in a framed, colored box. \renewcommandx\MyName[3][1=\empty, 3=\empty]{% \global\@nameauth@toksa\expandafter{#1}% \global\@nameauth@toksb\expandafter{#2}% \global\@nameauth@toksc\expandafter{#3}% \fcolorbox{black}{gray!25!white}{\@nameauth@Name[#1]{#2}[#3]}% } % Likewise change the macro for when names are forced long. \renewcommandx\MyLName[3][1=\empty, 3=\empty]{% \global\@nameauth@toksa\expandafter{#1}% \global\@nameauth@toksb\expandafter{#2}% \global\@nameauth@toksc\expandafter{#3}% \fcolorbox{black}{green!25!white}{\@nameauth@Name[#1]{#2}[#3]}% } % Likewise change the macro when personal names are desired. \renewcommandx\MyFName[3][1=\empty, 3=\empty]{% \global\@nameauth@toksa\expandafter{#1}% \global\@nameauth@toksb\expandafter{#2}% \global\@nameauth@toksc\expandafter{#3}% \fcolorbox{black}{yellow!25!white}{\@nameauth@Name[#1]{#2}[#3]}% } \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; \Name*[Adolf von]{Harnack}; \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 for the font; that should be changed at the user's discretion. We could load \textsf{tikz} using \texttt{\textbackslash ifDoTikZ} to avoid crashing some \texttt{dvi} viewers in a \texttt{dvi}-only workflow. Below we list the salient points from \texttt{compat.tex}, included with \textsf{nameauth}. \index{\protect\LaTeX\ engines} \begin{quote}\small \VerbatimInput[gobble=0, firstline=29]{compat.tex} \end{quote} 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} \newpage \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, one should see two vertical bars \texttt{||} where no output in the text is produced, or no spaces between an enclosed name and the bars. This section also tests if most possible argument combinations work in most macros that take name arguments. \begin{quote} \Verb+\Name[FNNa]{SNNa,Affix}[Alternate]+\dotfill |\Name[FNNa]{SNNa,Affix}[Alternate]|\\ \Verb+\Name*[FNNa]{SNNa,Affix}+\dotfill |\Name*[FNNa]{SNNa,Affix}|\\ \Verb+\DropAffix\Name*[FNNa]{SNNa,Affix}[Alternate]+\dotfill |\DropAffix\Name*[FNNa]{SNNa,Affix}[Alternate]|\\ \Verb+\DropAffix\Name*[FNNa]{SNNa,Affix}+\dotfill |\DropAffix\Name*[FNNa]{SNNa,Affix}|\\ \Verb+\Name[FNNa]{SNNa,Affix}[Alternate]+\dotfill |\Name[FNNa]{SNNa,Affix}[Alternate]|\\ \Verb+\Name[FNNa]{SNNa,Affix}+\dotfill |\Name[FNNa]{SNNa,Affix}|\\ \Verb+\FName[FNNa]{SNNa,Affix}[Alternate]+\dotfill |\FName[FNNa]{SNNa,Affix}[Alternate]|\\ \Verb+\FName[FNNa]{SNNa,Affix}+\dotfill |\FName[FNNa]{SNNa,Affix}| \end{quote} \begin{quote} \Verb+\Name[FNNb]{SNNb}[Alternate]+\dotfill |\Name[FNNb]{SNNb}[Alternate]|\\ \Verb+\Name*[FNNb]{SNNb}+\dotfill |\Name*[FNNb]{SNNb}|\\ \Verb+\Name[FNNb]{SNNb}[Alternate]+\dotfill |\Name[FNNb]{SNNb}[Alternate]|\\ \Verb+\Name[FNNb]{SNNb}+\dotfill |\Name[FNNb]{SNNb}|\\ \Verb+\FName[FNNb]{SNNb}[Alternate]+\dotfill |\FName[FNNb]{SNNb}[Alternate]|\\ \Verb+\FName[FNNb]{SNNb}+\dotfill |\FName[FNNb]{SNNb}| \end{quote} \begin{quote} \Verb+\Name{SNNc,Affix}[Alternate]+\dotfill |\Name{SNNc,Affix}[Alternate]|\\ \Verb+\Name*{SNNc,Affix}+\dotfill |\Name*{SNNc,Affix}|\\ \Verb+\Name{SNNc,Affix}[Alternate]+\dotfill |\Name{SNNc,Affix}[Alternate]|\\ \Verb+\Name{SNNc,Affix}+\dotfill |\Name{SNNc,Affix}|\\ \Verb+\FName{SNNc,Affix}[Alternate]+\dotfill |\FName{SNNc,Affix}[Alternate]|\\ \Verb+\FName{SNNc,Affix}+\dotfill |\FName{SNNc,Affix}|\\ \Verb+\ForceFN\FName{SNNc,Affix}[Alternate]+\dotfill |\ForceFN\FName{SNNc,Affix}[Alternate]|\\ \Verb+\ForceFN\FName{SNNc,Affix}+\dotfill |\ForceFN\FName{SNNc,Affix}| \end{quote} \begin{quote} \Verb+\Name{SNNd}[Alternate]+\dotfill |\Name{SNNd}[Alternate]|\\ \Verb+\Name*{SNNd}[Alternate]+\dotfill |\Name*{SNNd}[Alternate]|\\ \Verb+\Name{SNNd}[Alternate]+\dotfill |\Name{SNNd}[Alternate]|\\ \Verb+\FName{SNNd}[Alternate]+\dotfill |\FName{SNNd}[Alternate]|\\ \Verb+\ForceFN\FName{SNNd}[Alternate]+\dotfill |\ForceFN\FName{SNNd}[Alternate]| \end{quote} \begin{quote} \Verb+\IndexName[FNNe]{SNNe,Affix}[Alternate]+\dotfill |\IndexName[FNNe]{SNNe,Affix}[Alternate]|\\ \Verb+\IndexName[FNNe]{SNNe,Affix}+\dotfill |\IndexName[FNNe]{SNNe,Affix}|\\ \Verb+\IndexName{SNNf,Affix}[Alternate]+\dotfill |\IndexName{SNNf,Affix}[Alternate]|\\ \Verb+\IndexName{SNNf,Affix}+\dotfill |\IndexName{SNNf,Affix}|\\ \Verb+\IndexName{SNNf}[Alternate]+\dotfill |\IndexName{SNNf}[Alternate]| \end{quote} \begin{quote} \Verb+\IndexRef[FNNg]{SNNg,Affix}[Alternate]{Target}+\dotfill |\IndexRef[FNNg]{SNNg,Affix}[Alternate]{Target}|\\ \Verb+\IndexRef[FNNg]{SNNg,Affix}{Target}+\dotfill |\IndexRef[FNNg]{SNNg,Affix}{Target}|\\ \Verb+\IndexRef{SNNh,Affix}[Alternate]{Target}+\dotfill |\IndexRef{SNNh,Affix}[Alternate]{Target}|\\ \Verb+\IndexRef{SNNh,Affix}{Target}+\dotfill |\IndexRef{SNNh,Affix}{Target}|\\ \Verb+\IndexRef{SNNh}[Alternate]{Target}+\dotfill |\IndexRef{SNNh}[Alternate]{Target}| \end{quote} \begin{quote} \Verb+\ExcludeName[FNNi]{SNNi,Affix}[Alternate]+\dotfill |\ExcludeName[FNNi]{SNNi,Affix}[Alternate]|\\ \Verb+\ExcludeName[FNNi]{SNNi,Affix}+\dotfill |\ExcludeName[FNNi]{SNNi,Affix}|\\ \Verb+\ExcludeName{SNNj,Affix}[Alternate]+\dotfill |\ExcludeName{SNNj,Affix}[Alternate]|\\ \Verb+\ExcludeName{SNNj,Affix}+\dotfill |\ExcludeName{SNNj,Affix}|\\ \Verb+\ExcludeName{SNNj}[Alternate]+\dotfill |\ExcludeName{SNNj}[Alternate]| \end{quote} \begin{quote} \Verb+\IncludeName[FNNi]{SNNi,Affix}[Alternate]+\dotfill |\IncludeName[FNNi]{SNNi,Affix}[Alternate]|\\ \Verb+\IncludeName[FNNi]{SNNi,Affix}+\dotfill |\IncludeName[FNNi]{SNNi,Affix}|\\ \Verb+\IncludeName{SNNj,Affix}[Alternate]+\dotfill |\IncludeName{SNNj,Affix}[Alternate]|\\ \Verb+\IncludeName{SNNj,Affix}+\dotfill |\IncludeName{SNNj,Affix}|\\ \Verb+\IncludeName{SNNj}[Alternate]+\dotfill |\IncludeName{SNNj}[Alternate]| \end{quote} \begin{quote} \Verb+\IncludeName*[FNNi]{SNNi,Affix}[Alternate]+\dotfill |\IncludeName*[FNNi]{SNNi,Affix}[Alternate]|\\ \Verb+\IncludeName*[FNNi]{SNNi,Affix}+\dotfill |\IncludeName*[FNNi]{SNNi,Affix}|\\ \Verb+\IncludeName*{SNNj,Affix}[Alternate]+\dotfill |\IncludeName*{SNNj,Affix}[Alternate]|\\ \Verb+\IncludeName*{SNNj,Affix}+\dotfill |\IncludeName*{SNNj,Affix}|\\ \Verb+\IncludeName*{SNNj}[Alternate]+\dotfill |\IncludeName*{SNNj}[Alternate]| \end{quote} \begin{quote} \Verb+\PretagName[FNNk]{SNNk,Affix}[Alternate]{Sorta}+\dotfill |\PretagName[FNNk]{SNNk,Affix}[Alternate]{Sorta}|\\ \Verb+\PretagName[FNNl]{SNNl,Affix}{Sortb}+\dotfill |\PretagName[FNNl]{SNNl,Affix}{Sortb}|\\ \Verb+\PretagName{SNNm,Affix}[Alternate]{Sortc}+\dotfill |\PretagName{SNNm,Affix}[Alternate]{Sortc}|\\ \Verb+\PretagName{SNNn,Affix}{Sortd}+\dotfill |\PretagName{SNNn,Affix}{Sortd}|\\ \Verb+\PretagName{SNNo}[Alternate]{Sorte}+\dotfill |\PretagName{SNNo}[Alternate]{Sorte}| \end{quote} \begin{quote} \Verb+\TagName[FNNa]{SNNa,Affix}[Alternate]{Tag}+\dotfill |\TagName[FNNa]{SNNa,Affix}[Alternate]{Tag}|\\ \Verb+\TagName[FNNa]{SNNa,Affix}{Tag}+\dotfill |\TagName[FNNa]{SNNa,Affix}{Tag}|\\ \Verb+\TagName[FNNb]{SNNb}[Alternate]{Tag}+\dotfill |\TagName[FNNb]{SNNb}[Alternate]{Tag}|\\ \Verb+\TagName[FNNb]{SNNb}{Tag}+\dotfill |\TagName[FNNb]{SNNb,Affix}{Tag}|\\ \Verb+\TagName{SNNc,Affix}[Alternate]{Tag}+\dotfill |\TagName{SNNc,Affix}[Alternate]{Tag}|\\ \Verb+\TagName{SNNc,Affix}{Tag}+\dotfill |\TagName{SNNc,Affix}{Tag}|\\ \Verb+\TagName{SNNd}[Alternate]{Tag}+\dotfill |\TagName{SNNd}[Alternate]{Tag}| \end{quote} \begin{quote} \Verb+\UntagName[FNNa]{SNNa,Affix}[Alternate]+\dotfill |\UntagName[FNNa]{SNNa,Affix}[Alternate]|\\ \Verb+\UntagName[FNNa]{SNNa,Affix}+\dotfill |\UntagName[FNNa]{SNNa,Affix}|\\ \Verb+\UntagName[FNNb]{SNNb}[Alternate]+\dotfill |\UntagName[FNNb]{SNNb}[Alternate]|\\ \Verb+\UntagName[FNNb]{SNNb}+\dotfill |\UntagName[FNNb]{SNNb,Affix}|\\ \Verb+\UntagName{SNNc,Affix}[Alternate]+\dotfill |\UntagName{SNNc,Affix}[Alternate]|\\ \Verb+\UntagName{SNNc,Affix}+\dotfill |\UntagName{SNNc,Affix}|\\ \Verb+\UntagName{SNNd}[Alternate]+\dotfill |\UntagName{SNNd}[Alternate]| \end{quote} \begin{quote} \Verb+\NameAddInfo[FNNa]{SNNa,Affix}[Alternate]{Info1}+\dotfill |\NameAddInfo[FNNa]{SNNa,Affixa}[Alternate]{Info1}|\\ \Verb+\NameAddInfo[FNNa]{SNNa,Affix}{Info2}+\dotfill |\NameAddInfo[FNNa]{SNNa,Affix}{Info2}|\\ \Verb+\NameAddInfo[FNNb]{SNNb}[Alternate]{Info3}+\dotfill |\NameAddInfo[FNNb]{SNNb}[Alternate]{Info3}|\\ \Verb+\NameAddInfo[FNNb]{SNNb}{Info4}+\dotfill |\NameAddInfo[FNNb]{SNNb}{Info4}|\\ \Verb+\NameAddInfo{SNNc,Affix}[Alternate]{Info5}+\dotfill |\NameAddInfo{SNNc,Affix}[Alternate]{Info5}|\\ \Verb+\NameAddInfo{SNNc,Affix}{Info6}+\dotfill |\NameAddInfo{SNNc,Affix}{Info6}|\\ \Verb+\NameAddInfo{SNNd}[Alternate]{Info7}+\dotfill |\NameAddInfo{SNNd}[Alternate]{Info7}| \end{quote} \begin{quote} \Verb+\NameQueryInfo[FNNa]{SNNa,Affix}[Alternate]+\dotfill |\NameQueryInfo[FNNa]{SNNa,Affix}[Alternate]|\\ \Verb+\NameQueryInfo[FNNa]{SNNa,Affix}+\dotfill |\NameQueryInfo[FNNa]{SNNa,Affix}|\\ \Verb+\NameQueryInfo[FNNb]{SNNb}[Alternate]+\dotfill |\NameQueryInfo[FNNb]{SNNb}[Alternate]|\\ \Verb+\NameQueryInfo[FNNb]{SNNb}+\dotfill |\NameQueryInfo[FNNb]{SNNb}|\\ \Verb+\NameQueryInfo{SNNc,Affix}[Alternate]+\dotfill |\NameQueryInfo{SNNc,Affix}[Alternate]|\\ \Verb+\NameQueryInfo{SNNc,Affix}+\dotfill |\NameQueryInfo{SNNc,Affix}|\\ \Verb+\NameQueryInfo{SNNd}[Alternate]+\dotfill |\NameQueryInfo{SNNd}[Alternate]| \end{quote} \begin{quote} \Verb+\NameClearInfo[FNNa]{SNNa,Affix}[Alternate]+\dotfill |\NameClearInfo[FNNa]{SNNa,Affix}[Alternate]|\\ \Verb+\NameClearInfo[FNNa]{SNNa,Affix}+\dotfill |\NameClearInfo[FNNa]{SNNa,Affix}|\\ \Verb+\NameClearInfo[FNNb]{SNNb}[Alternate]+\dotfill |\NameClearInfo[FNNb]{SNNb}[Alternate]|\\ \Verb+\NameClearInfo[FNNb]{SNNb}+\dotfill |\NameClearInfo[FNNb]{SNNb}|\\ \Verb+\NameClearInfo{SNNc,Affix}[Alternate]+\dotfill |\NameClearInfo{SNNc,Affix}[Alternate]|\\ \Verb+\NameClearInfo{SNNc,Affix}+\dotfill |\NameClearInfo{SNNc,Affix}|\\ \Verb+\NameClearInfo{SNNd}[Alternate]+\dotfill |\NameClearInfo{SNNd}[Alternate]| \end{quote} \begin{quote} \Verb+\ForgetName[FNNa]{SNNa,Affix}[Alternate]+\dotfill |\ForgetName[FNNa]{SNNa,Affix}[Alternate]|\\ \Verb+\ForgetName[FNNa]{SNNa,Affix}+\dotfill |\ForgetName[FNNa]{SNNa,Affix}|\\ \Verb+\ForgetName[FNNb]{SNNb}[Alternate]+\dotfill |\ForgetName[FNNb]{SNNb}[Alternate]|\\ \Verb+\ForgetName[FNNb]{SNNb}+\dotfill |\ForgetName[FNNb]{SNNb}|\\ \Verb+\ForgetName{SNNc,Affix}[Alternate]+\dotfill |\ForgetName{SNNc,Affix}[Alternate]|\\ \Verb+\ForgetName{SNNc,Affix}+\dotfill |\ForgetName{SNNc,Affix}|\\ \Verb+\ForgetName{SNNd}[Alternate]+\dotfill |\ForgetName{SNNd}[Alternate]| \end{quote} \begin{quote} \Verb+\LocalNames+\LocalNames\\ \Verb+\SubvertName[FNNa]{SNNa,Affix}[Alternate]+\dotfill |\SubvertName[FNNa]{SNNa,Affix}[Alternate]|\\ \Verb+\SubvertName[FNNb]{SNNb}[Alternate]+\dotfill |\SubvertName[FNNb]{SNNb}[Alternate]|\\ \Verb+\SubvertName{SNNc,Affix}[Alternate]+\dotfill |\SubvertName{SNNc,Affix}[Alternate]|\\ \Verb+\SubvertName{SNNd}[Alternate]+\dotfill |\SubvertName{SNNd}[Alternate]|\\ \Verb+\GlobalNames+\GlobalNames \end{quote} \begin{quote} \Verb+\IfMainName[FNNa]{SNNa,Affix}{Y}{N}+\dotfill |\IfMainName[FNNa]{SNNa,Affix}{Y}{N}|\\ \Verb+\IfMainName[FNNb]{SNNb}{Y}{N}+\dotfill |\IfMainName[FNNb]{SNNb}{Y}{N}|\\ \Verb+\IfMainName{SNNc,Affix}{Y}{N}+\dotfill |\IfMainName{SNNc,Affix}{Y}{N}|\\ \Verb+\IfMainName{SNNd}[Alternate]{Y}{N}+\dotfill |\IfMainName{SNNd}[Alternate]{Y}{N}| \end{quote} \begin{quote} \Verb+\IfFrontName[FNNa]{SNNa,Affix}[Alternate]{Y}{N}+\dotfill |\IfFrontName[FNNa]{SNNa,Affix}[Alternate]{Y}{N}|\\ \Verb+\IfFrontName[FNNb]{SNNb}[Alternate]{Y}{N}+\dotfill |\IfFrontName[FNNb]{SNNb}[Alternate]{Y}{N}|\\ \Verb+\IfFrontName{SNNc,Affix}[Alternate]{Y}{N}+\dotfill |\IfFrontName{SNNc,Affix}[Alternate]{Y}{N}|\\ \Verb+\IfFrontName{SNNd}[Alternate]{Y}{N}+\dotfill |\IfFrontName{SNNd}[Alternate]{Y}{N}| \end{quote} \begin{quote} \Verb+\SeeAlso\IndexRef[FNNp]{SNNp,Affix}{Target}+\dotfill |\SeeAlso\IndexRef[FNNp]{SNNp,Affix}{Target}|\\ \Verb+\ExcludeName{SNNq,Affix}+\dotfill |\ExcludeName{SNNq,Affix}|\\ \Verb+\IfAKA[FNNp]{SNNp,Affix}[Alternate]{Y}{N}{X}+\dotfill |\IfAKA[FNNp]{SNNp,Affix}[Alternate]{Y}{N}{X}|\\ \Verb+\IfAKA[FNNp]{SNNp,Affix}{Y}{N}{X}+\dotfill |\IfAKA[FNNp]{SNNp,Affix}{Y}{N}{X}|\\ \Verb+\IfAKA{SNNq,Affix}[Alternate]{Y}{N}{X}+\dotfill |\IfAKA{SNNq,Affix}[Alternate]{Y}{N}{X}|\\ \Verb+\IfAKA{SNNq,Affix}{Y}{N}{X}+\dotfill |\IfAKA{SNNq,Affix}{Y}{N}{X}|\\ \Verb+\IfAKA{SNNr}[Alternate]{Y}{N}{X}+\dotfill |\IfAKA{SNNr}[Alternate]{Y}{N}{X}| \end{quote} \begin{quote} \Verb+\AKA[FNN1]{SNN1,Affix1}%+\\ \Verb+ [FNN2]{SNN2,Affix2}[Alternate2]+\dotfill |\AKA[FNN1]{SNN1,Affix1}[FNN2]{SNN2,Affix2}[Alternate2]|\\ \Verb+\AKA[FNN1]{SNN1,Affix1}%+\\ \Verb+ [FNN2]{SNN2,Affix2}+\dotfill |\AKA[FNN1]{SNN1,Affix1}[FNN2]{SNN2,Affix2}|\\ \Verb+\DropAffix\AKA[FNN1]{SNN1,Affix1}%+\\ \Verb+ [FNN2]{SNN2,Affix2}+\dotfill |\DropAffix\AKA[FNN1]{SNN1,Affix1}[FNN2]{SNN2,Affix2}|\\ \Verb+\AKA*[FNN1]{SNN1,Affix1}%+\\ \Verb+ [FNN2]{SNN2,Affix2}[Alternate2]+\dotfill |\AKA*[FNN1]{SNN1,Affix1}[FNN2]{SNN2,Affix2}[Alternate2]|\\ \Verb+\AKA*[FNN1]{SNN1,Affix1}%+\\ \Verb+ [FNN2]{SNN2,Affix2}+\dotfill |\AKA*[FNN1]{SNN1,Affix1}[FNN2]{SNN2,Affix2}| \end{quote} \begin{quote} \Verb+\AKA[FNN1]{SNN1,Affix1}%+\\ \Verb+ {SNN3,Affix3}[Alternate3]+\dotfill |\AKA[FNN1]{SNN1,Affix1}{SNN3,Affix3}[Alternate3]|\\ \Verb+\AKA[FNN1]{SNN1,Affix1}%+\\ \Verb+ {SNN3,Affix3}+\dotfill |\AKA[FNN1]{SNN1,Affix1}{SNN3,Affix3}|\\ \Verb+\AKA*[FNN1]{SNN1,Affix1}%+\\ \Verb+ {SNN3,Affix3}+\dotfill |\AKA*[FNN1]{SNN1,Affix1}{SNN3,Affix3}|\\ \Verb+\ForceFN\AKA*[FNN1]{SNN1,Affix1}%+\\ \Verb+ {SNN3,Affix3}[Alternate3]+\dotfill |\ForceFN\AKA*[FNN1]{SNN1,Affix1}{SNN3,Affix3}[Alternate3]|\\ \Verb+\ForceFN\AKA*[FNN1]{SNN1,Affix1}%+\\ \Verb+ {SNN3,Affix3}+\dotfill |\ForceFN\AKA*[FNN1]{SNN1,Affix1}{SNN3,Affix3}| \end{quote} \begin{quote} \Verb+\AKA[FNN1]{SNN1,Affix1}{SNN4}[Alternate4]+\dotfill |\AKA[FNN1]{SNN1,Affix1}{SNN4}[Alternate4]|\\ \Verb+\AKA*[FNN1]{SNN1,Affix1}{SNN4}[Alternate4]+\dotfill |\AKA*[FNN1]{SNN1,Affix1}{SNN4}[Alternate4]|\\ \Verb+\ForceFN\AKA*[FNN1]{SNN1,Affix1}{SNN4}[Alternate4]+\dotfill |\ForceFN\AKA*[FNN1]{SNN1,Affix1}{SNN4}[Alternate4]| \end{quote} \begin{quote} \Verb+\AKA{SNN5,Affix5}%+\\ \Verb+ [FNN6]{SNN6,Affix6}[Alternate6]+\dotfill |\AKA{SNN5,Affix5}[FNN6]{SNN6,Affix6}[Alternate6]|\\ \Verb+\AKA{SNN5,Affix5}{SNN7,Affix7}+\dotfill |\AKA{SNN5,Affix5}{SNN7,Affix7}|\\ \Verb+\AKA{SNN5,Affix5}{SNN8}[Alternate8]+\dotfill |\AKA{SNN5,Affix5}{SNN8}[Alternate8]|\\ \end{quote} % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % \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