From 02193cc5ca03abf234d3bc9d77b4821d85f58c62 Mon Sep 17 00:00:00 2001
From: Norbert Preining <norbert@preining.info>
Date: Fri, 28 Feb 2020 03:02:25 +0000
Subject: CTAN sync 202002280302

---
 macros/latex/contrib/nameauth/examples.tex | 100 +++++++++++++++++++++++------
 1 file changed, 81 insertions(+), 19 deletions(-)

(limited to 'macros/latex/contrib/nameauth/examples.tex')

diff --git a/macros/latex/contrib/nameauth/examples.tex b/macros/latex/contrib/nameauth/examples.tex
index 2a71bd75be..105403ef84 100644
--- a/macros/latex/contrib/nameauth/examples.tex
+++ b/macros/latex/contrib/nameauth/examples.tex
@@ -1,14 +1,34 @@
-%% This is an example file used with the nameauth package.
-%% See README and nameauth.pdf for copyright info.
-%%
+%--------:| ----------------------------------------------------------------
+%nameauth:| Name authority mechanism for consistency in text and index
+%  Author:| Charles P. Schaum
+%  E-mail:| charles dot schaum@comcast.net
+% License:| Released under the LaTeX Project Public License 1.3c or later
+%     See:| http://www.latex-project.org/lppl.txt
+%
+% This is an example file used with the nameauth package.
+% See README and nameauth.pdf for copyright info.
+%
 \documentclass[11pt]{article}
+%
+% This part of the document preamble exists only for backward compatibility in older
+% distributions of LaTeX. It includes the iftex package only if it exists.
+% If the iftex package is older than 2019, it includes the older packages
+% that aid using multiple engines.
+
 \IfFileExists{iftex.sty}{\usepackage{iftex}}{}
 \unless\ifdefined\RequireTUTeX
   \usepackage{ifxetex}
   \usepackage{ifluatex}
   \usepackage{ifpdf}
 \fi
-% Used to create both dvi and pdf output
+%
+% This template can be used when creating both dvi and pdf output. We
+% do not actually use the tikz package in this example file. We set
+% the condition for using tikz with a Boolean flag.
+% 
+% If compatibility with specific dvi viewers is not an issue, then
+% one might ignore the use of \ifDoTikZ altogether.
+%
 \newif\ifDoTikZ
 \ifxetex
   \usepackage{fontspec}
@@ -30,7 +50,10 @@
       \usepackage[TS1,T1]{fontenc}
       \usepackage[american]{babel}     % Use own language
       \usepackage{lmodern}
-      % Perhaps add \usepackage{tikz}
+%
+% There may be a need to include tikz using luatex in dvi mode;
+% that goes beyond the scope of the nameauth package.
+%
     \fi
   \else
     \IfFileExists{utf8-2018.def}{}
@@ -44,18 +67,28 @@
     \fi
   \fi
 \fi
+%
+% Below are the remainder of package inclusions.
+% 
 \usepackage{booktabs}
 \usepackage[textwidth=137mm,textheight=237mm,right=30mm,marginparwidth=30mm,nohead]{geometry}
+\usepackage{makeidx}
 \usepackage{nameauth}
 \usepackage{verbatim}
-\usepackage{makeidx}
-\usepackage{hyperref}
-
+\usepackage[colorlinks=true]{hyperref}
+%
+% We set up indexing, put margin paragraphs on the left, set up the counter for
+% line numbering in verbatim environments, and set up \ifNoTag for use in the
+% life dates text tagging example.
+%
 \makeindex
 \reversemarginpar
 \newcounter{VerbLine}
 \newif\ifNoTag
-
+%
+% We establish name shorthands. Note the heavy use of \noexpand in the macro arguments
+% below. This is intrinsic to the proper function of such arguments.
+%
 \begin{nameauth}
  \< Adams & John & \noexpand\textSC{Adams} & >
  \< SDJR & Sammy & \noexpand\textSC{Davis}, \noexpand\textSC{Jr}. & >
@@ -70,9 +103,13 @@
  \< Sutorius & Quintus & \noexpand\SUTOR & >
  \< Wash & George & Washington & >
 \end{nameauth}
-
+%
+% We set up a text tag here, but we will set more up in the body text.
+%
 \NameAddInfo{Demetrius, I}{ Soter}
-
+%
+% Below we establish sort tags for names. Note again the consistent use of \noexpand.
+%
 \PretagName[John]{\noexpand\textSC{Adams}}{Adams, John}
 \PretagName[Sammy]{\noexpand\textSC{Davis}, \noexpand\textSC{Jr}.}{Davis, Sammy, Jr.}
 \PretagName{Demetrius, I}{Demetrius 1}
@@ -93,24 +130,35 @@
 \TagName[Martin]{Van Buren}{, president}
 \TagName[Ulysses S.]{Grant}{, president}
 \TagName[George]{Washington}{, president}
-
+%
+% We set up line numbering in verbatim environments.
+%
 \makeatletter
 \newcommand*\ClearNum{\def\verbatim@processline{\the\verbatim@line\par}}
 \newcommand*\StartNum{\setcounter{VerbLine}{0}\def\verbatim@processline{\stepcounter{VerbLine}\leavevmode\llap{\footnotesize\normalfont\theVerbLine\quad}\the\verbatim@line\par}}
 \newcommand*\ContinueNum{\def\verbatim@processline{\stepcounter{VerbLine}\leavevmode\llap{\footnotesize\normalfont\theVerbLine\quad}\the\verbatim@line\par}}
 \makeatother
-
+%
+% The default verbatim format is no line numbers.
+% We add title, author, and date.
+%
 \ClearNum
 \title{\bfseries Longer Examples}
 \author{Charles P. Schaum}
-\date{2020/02/20}
+\date{2020/02/26}
 
 \begin{document}
 \maketitle
 
+\tableofcontents
+\bigskip
+
+{\large\bfseries\hyperlink{Index}{Index}}
+\newpage
+
 \section{Particles}
 
-First we use variants with the \(\langle alternate\rangle\) argument:
+First we use variants with the \(\langle Alternate\rangle\) argument:
 \begin{quote}\small
 \StartNum
 \begin{verbatim}
@@ -165,8 +213,9 @@ First we use variants with the \(\langle alternate\rangle\) argument:
 \endgroup
 \newpage
 
+\section{Roman Names}
 \begingroup
-We want all names in the index, so we define macros that expand one or two components: \textit{praenomen} and \textit{nomen}, \textit{cognomen} and \textit{agnomen}. We begin by defining a name with macros using \verb+\noexpand+ to prevent error:
+We want all names in the index, so we define two macros that expand to be one or two components: \textit{praenomen} and \textit{nomen}; \textit{cognomen} and \textit{agnomen}. Below we want to index under the \textit{cognomen}. We begin by defining a name with macros using \verb+\noexpand+ to prevent error:
 \newif\ifSkipGens
 \newif\ifNoGens
 \newif\ifSkipAgnomen
@@ -176,9 +225,17 @@ We want all names in the index, so we define macros that expand one or two compo
 \newcommand*\SCIPii{\ifNoAgnomen Scipio\else
                     Scipio Africanus\fi}
 \newcommand*\ScipioOnly{\SkipAgnomentrue\Scipio}
+%
+% This form of \NamesFormat produces the longest possible name form in the first mention.
+%
 \renewcommand*\NamesFormat[1]%
   {\ifSkipGens\NoGenstrue\fi\ifSkipAgnomen\NoAgnomentrue\fi#1%
   \global\SkipGensfalse\global\SkipAgnomenfalse}
+%
+% If we always wanted to skip the nomen or agnomen in subsequent references, we could
+% force either \NoGenstrue or \NoAgnomentrue in \MainNameHook. The form below is
+% neutral to such preferences and thus, one must set them manually.
+%
 \renewcommand*\MainNameHook[1]%
   {\ifSkipGens\NoGenstrue\fi\ifSkipAgnomen\NoAgnomentrue\fi#1%
   \global\SkipGensfalse\global\SkipAgnomenfalse}
@@ -217,10 +274,14 @@ We want all names in the index, so we define macros that expand one or two compo
  \end{quote}
  
  The index entry is fairly lengthy by necessity, governed by the global state of the Boolean flags, and expanding to:
- \begin{quote}
+\begin{quote}
  \texttt{\ShowIdxPageref[\noexpand\SCIPi]{\noexpand\SCIPii}}
- \end{quote}
+\end{quote}
 
+%
+% We can keep the redefined formatting macros above.
+%
+If we want to index under the \textit{nomen}, we take a slightly different approach:
  \begin{quote}\small
  \StartNum
  \begin{verbatim}
@@ -254,7 +315,7 @@ We want all names in the index, so we define macros that expand one or two compo
 
 \section{Alternate Formatting: Inflections}
 
-In this section we use a scope to contain \verb+\AltFormatActive+ as we show how to implement a simple grammatical inflection.
+In this section we use a scope to contain \verb+\AltFormatActive+ as we show how to implement a simple grammatical inflection. Notice the similarities between handling the Roman names above and the grammatical inflections below this points to a general method when introducing variations into the name macro arguments, while keeping index entries consistent.
 
 \begingroup\AltFormatActive
 \newif\ifGenitive
@@ -1371,6 +1432,7 @@ The following equivalent conditional statements can help a macro or just the bod
 \end{verbatim}
 \end{quote}
 
+\def\indexname{\hypertarget{Index}{Index}}
 \newpage
 \printindex
 
-- 
cgit v1.2.3

