summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/nameauth
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2015-12-02 22:26:53 +0000
committerKarl Berry <karl@freefriends.org>2015-12-02 22:26:53 +0000
commite34b6a9f256ced4540530861f54bb1fcb0b780d6 (patch)
treedaf54f408efb34c01f762a3c43dfa6f3ad23a32c /Master/texmf-dist/source/latex/nameauth
parent8612f7f48afa4bd985eb1ba2824afc9bc0d9737f (diff)
nameauth (2dec15)
git-svn-id: svn://tug.org/texlive/trunk@39001 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/source/latex/nameauth')
-rw-r--r--Master/texmf-dist/source/latex/nameauth/nameauth.dtx143
1 files changed, 116 insertions, 27 deletions
diff --git a/Master/texmf-dist/source/latex/nameauth/nameauth.dtx b/Master/texmf-dist/source/latex/nameauth/nameauth.dtx
index 2346ea5313b..1f69dbeec8f 100644
--- a/Master/texmf-dist/source/latex/nameauth/nameauth.dtx
+++ b/Master/texmf-dist/source/latex/nameauth/nameauth.dtx
@@ -168,7 +168,7 @@ Running "make install" installs the files in the local TeX tree.
%<package>\NeedsTeXFormat{LaTeX2e}[1999/12/01]
%<package>\ProvidesPackage{nameauth}
%<*package>
- [2015/11/29 v2.11 Name authority mechanism for consistency in text and index]
+ [2015/12/01 v2.2 Name authority mechanism for consistency in text and index]
%</package>
%<*driver>
\documentclass[11pt]{ltxdoc}
@@ -238,6 +238,7 @@ Running "make install" installs the files in the local TeX tree.
\< JWG & Johann Wolfgang von & Goethe & >
\< Harnack & Adolf & Harnack & >
\< Bier & Johann & Bier\-mann & >
+ \< Fukuyama & & \uppercase{Fukuyama}, T. & >
\end{nameauth}
\TagName[George]{Washington}{, president|hyperpage}
\TagName[Hernando]{de Soto}{|hyperpage}
@@ -327,6 +328,12 @@ Running "make install" installs the files in the local TeX tree.
\TagName[Jan]{Łukasiewicz}{|hyperpage}
\PretagName{Vlad, Ţepeş}{Vlad Tepes}
\TagName[Patrick]{Cousot}{|hyperpage}
+\PretagName[\normalfont{Mata}]{\textsc{Hari}}{Hari, Mata}%
+\TagName[\normalfont{Mata}]{\textsc{Hari}}{|hyperpage}
+\PretagName[\normalfont{Thurston}]{\textsc{Howell},\textsc{III}}{Howell, Thurston 3}
+\TagName[\normalfont{Thurston}]{\textsc{Howell},\textsc{III}}{*|hyperpage}
+\PretagName{\uppercase{Fukuyama}, T.}{Fukuyama, T}
+\TagName{\uppercase{Fukuyama}, T.}{|hyperpage}
\IndexActual{=}
\begin{document}
\DocInput{\jobname.dtx}
@@ -334,7 +341,7 @@ Running "make install" installs the files in the local TeX tree.
%</driver>
% \fi
%
-% \CheckSum{2691}
+% \CheckSum{2700}
%
% \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
@@ -370,6 +377,7 @@ Running "make install" installs the files in the local TeX tree.
% \changes{v1.9}{2015/07/09}{Better Eastern name support; fix |nameauth| bugs, global un-tagging}
% \changes{v2.0}{2015/11/11}{Use dtxgen template instead of dtxtut; update docs}
% \changes{v2.1}{2015/11/24}{Isolate Unicode issues}
+% \changes{v2.2}{2015/12/01}{Add interface hooks and docs; fix bugs}
% \GetFileInfo{\jobname.dtx}
% \DoNotIndex{\@empty, \@gobble, \@period, \@token, \trim@spaces, \zap@space}
% \DoNotIndex{\begingroup, \bfseries, \bgroup, \csdef, \csgdef, \csname, \csundef, \DeclareOption, \def, \detokenize, \edef, \egroup, \else, \endcsname, \endgroup, \endinput, \ExecuteOptions, \expandafter, \fi, \futurelet, \global, \hbox, \if, \ifcsname, \ifx, \ignorespaces, \index, \itshape, \leavevmode, \let, \newcommand, \newcommandx, \newenvironment, \newif, \nobreakspace, \PackageError, \PackageWarning, \ProcessOptions, \relax, \renewcommand, \RequirePackage, \scshape, \space, \textbackslash, \uppercase}
@@ -597,7 +605,7 @@ Running "make install" installs the files in the local TeX tree.
% \quad\bfseries\texttt{normalcaps} & \bfseries Do not perform any special capitalization.\\[1ex]
% \quad\texttt{allcaps} & Capitalize entire surnames, such as romanized Eastern names.\\[2ex]
% \end{tabular}\\
-% This only affects names printed in the body text. To get caps in both the body text and the index, the user should type in the caps manually\,---\,an easy task with the simplified interface. Section~\ref{sec:Eastern} details macros that enable capitalization on a section-level and per-name basis.\bigskip
+% This only affects names printed in the body text. See Section~\ref{sec:formatting} on how to get caps in both the body text and the index\,---\,easy with the simplified interface. Section~\ref{sec:Eastern} deals with capitalization on a section-level and per-name basis.\bigskip
%
% \noindent{\large\bfseries Reverse Name Order}\\[2ex]
% \begin{tabular}{p{0.22\textwidth}p{0.6\textwidth}}
@@ -1145,7 +1153,7 @@ Running "make install" installs the files in the local TeX tree.
% \end{quote}
% \NamesActive
%
-% Notice how capitalization is independent of formatting. The reversing and capitalization macros also work with \cmd{\AKA}. They affect only the text, not the index. Whoever wants all-cap forms in the index will have to capitalize everything manually or modify the macros.\clearpage
+% Notice how capitalization is independent of formatting. The reversing and capitalization macros also work with \cmd{\AKA}. They affect only the text, not the index. For caps in the text and index see Section~\ref{sec:formatting}.\clearpage
%
% \subsection{Other Naming Topics}
%
@@ -1367,6 +1375,63 @@ Running "make install" installs the files in the local TeX tree.
% \subsubsection{Custom Formatting}
% \label{sec:formatting}
%
+% There are two kinds of formatting at work:
+%
+% \begin{enumerate}\small\setlength{\itemsep}{0pt}
+% \item \textbf{Syntactic Formatting:} This includes reversing names, capitalizing the first letter in the \meta{SNN} field in the body text, and capitalizing the root when \meta{SNN} is a \meta{root, suffix} pair.
+% \item \textbf{Typographic Formatting:} This happens after a name has been parsed and reordered as needed into the final form it will take in the text.
+% \end{enumerate}
+%
+% Neither type of formatting makes it into the index. However, there are ways around that. One way to get formatting into the text and the index is to make it part of the name arguments, using \cmd{\PretagName} to get proper sorting:
+%
+% \begin{quote}\small
+% |\PretagName[\normalfont{Mata}]{\textsc{Hari}}{Hari, Mata}%|\\
+% |\Name[\normalfont{Mata}]{\textsc{Hari}}|
+% \end{quote}
+% You get \Name[\normalfont{Mata}]{\textsc{Hari}}, then \Name[\normalfont{Mata}]{\textsc{Hari}}. But it gets more complicated. If you use a comma-delimited suffix you need to format the name and suffix separately, as we see on the next page.
+%
+% \begin{quote}\small
+% |\PretagName{\uppercase{Fukuyama}, T.}{Fukuyama, T.}|\\
+% |\PretagName[\normalfont{Thurston}]%|\\
+% | {\textsc{Howell},\textsc{III}}{Howell, Thurston 3}|\\[1ex]
+% |\begin{nameauth}|\\
+% | \< Fukuyama & & \uppercase{Fukuyama}, T. & >|\\
+% |\end{nameauth}|
+% \end{quote}
+% |\Name[\normalfont{Thurston}]{\textsc{Howell},\textsc{III}}| produces\break \Name[\normalfont{Thurston}]{\textsc{Howell},\textsc{III}}, then \Name[\normalfont{Thurston}]{\textsc{Howell},\textsc{III}}. Likewise the simplified \cmd{\Fukuyama} produces \Fukuyama\ and \Fukuyama.\\
+%
+% \DescribeMacro{\NameauthName}
+% \DescribeMacro{\NameauthFName}
+% These two macros are hooks into the simplified interface. If the method above will not suffice, you can use the extant macros as building blocks or even create your own naming macros that comply at least to the following template:
+% \begin{quote}
+% |\makeatletter|\\
+% |\newcommandx*\MyName[3][1=\@empty, 3=\@empty]%|\\
+% | {|\meta{Something here}|}%|\\
+% |\newcommandx*\MyFName[3][1=\@empty, 3=\@empty]%|\\
+% | {|\meta{More stuff here}|}%|\\
+% |\makeatother|
+% \end{quote}
+% You can plug these macros into the simplified interface thus:
+% \begin{quote}
+% \makeatletter%
+% \newcommandx*\MyName[3][1=\@empty, 3=\@empty]{\meta{Something here}}%
+% \newcommandx*\MyFName[3][1=\@empty, 3=\@empty]{\meta{More stuff here}}%
+% \makeatother%
+% |\renewcommand*{\NameauthName}{\MyName}|\\
+% |\renewcommand*{\NameauthFName}{\MyFName}|\\
+% |\begin{nameauth}|\\
+% | \< Silly & No Particular & Name & >|\\
+% |\end{nameauth}|\\
+% |This is \Silly\ and \SSilly.|\\
+% \renewcommand*{\NameauthName}{\MyName}%
+% \renewcommand*{\NameauthFName}{\MyFName}%
+% \begin{nameauth}
+% \< Silly & No Particular & Name & >
+% \end{nameauth}
+% This is \Silly\ and \SSilly.
+% \end{quote}
+% Like \cmd{\NamesFormat} below, both \cmd{\NameauthName} and \cmd{\NameauthFName} respect scoping. Thus, \cmd{\Silly} now produces \IndexInactive\Silly\IndexActive.\\
+%
% \DescribeMacro{\NamesFormat}
% When formatting is active, \cmd{\NamesFormat} is called at the first instance of a name, and at every instance of a name when the \texttt{alwaysformat} option is used. Beyond using the package options, one also can redefine \cmd{\NamesFormat} to create custom effects. For example, one might change or suppress formatting in all footnotes:
%
@@ -1397,6 +1462,7 @@ Running "make install" installs the files in the local TeX tree.
%
% The |quote| environment used above permits local changes to \cmd{\NamesFormat} so they revert back to the default: \ForgetName{Vlad III, Dracula}\Name{Vlad III, Dracula} and \Name{Vlad III, Dracula}. For references to ``Vlad'' instead of ``\Name{Vlad III, Dracula}'' one could use |\Name{Vlad, III Dracula}|.\footnote{Do not mix \cmd{\Name}\texttt{\{Vlad III, Dracula\}} with \cmd{\Name}\texttt{\{Vlad, III Dracula\}} or the old syntax, lest errors bite! You would get multiple index entries with \cmd{\Name}, unwanted cross-references with \cmd{\AKA} and unexpected forms in the text. The simplified interface helps one to avoid this.}
%
+%
% \subsubsection{Disable Formatting}
% \label{sec:SectionFormat}
%
@@ -1943,11 +2009,30 @@ Running "make install" installs the files in the local TeX tree.
% \begin{macrocode}
\newif\if@nameauth@Accent
% \end{macrocode}
-% \clearpage\noindent
+% \subsection{Hooks}
+% \begin{macro}{\NamesFormat}
+% Change formatting of final complete name form in text. See Section~\ref{sec:formatting}.
+% \begin{macrocode}
+\newcommand*{\NamesFormat}{}
+% \end{macrocode}
+% \end{macro}
+% \begin{macro}{\NameauthName}
+% \changes{v2.2}{2015/12/01}{Added}
+% Hook into the simplified interface. See Section~\ref{sec:formatting}.
+% \begin{macrocode}
+\newcommand*{\NameauthName}{\Name}
+% \end{macrocode}
+% \end{macro}
+% \begin{macro}{\NameauthFName}
+% \changes{v2.2}{2015/12/01}{Added}
+% Hook into the simplified interface. See Section~\ref{sec:formatting}.
+% \begin{macrocode}
+\newcommand*{\NameauthFName}{\FName}
+% \end{macrocode}
+% \end{macro}
% \subsection{Package Options}
-% The following package options interact with many of the prior Boolean values. Suppressing and showing commas is set at load time. Most options can be changed with user interface macros. Avoid changing the internal Boolean values directly.
+% The following package options interact with many of the prior Boolean values.
% \begin{macrocode}
-\def\@nameauth@Actual{@}
\DeclareOption{comma}{\@nameauth@AlwaysCommatrue}
\DeclareOption{nocomma}{\@nameauth@AlwaysCommafalse}
\DeclareOption{mainmatter}{\@nameauth@DoFormattrue}
@@ -1965,10 +2050,10 @@ Running "make install" installs the files in the local TeX tree.
\DeclareOption{notreversed}%
{\@nameauth@RevAllfalse\@nameauth@RevAllCommafalse}
\DeclareOption{alwaysformat}{\@nameauth@AlwaysFormattrue}
-\DeclareOption{smallcaps}{\newcommand*{\NamesFormat}{\scshape}}
-\DeclareOption{italic}{\newcommand*{\NamesFormat}{\itshape}}
-\DeclareOption{boldface}{\newcommand*{\NamesFormat}{\bfseries}}
-\DeclareOption{noformat}{\newcommand*{\NamesFormat}{}}
+\DeclareOption{smallcaps}{\renewcommand*{\NamesFormat}{\scshape}}
+\DeclareOption{italic}{\renewcommand*{\NamesFormat}{\itshape}}
+\DeclareOption{boldface}{\renewcommand*{\NamesFormat}{\bfseries}}
+\DeclareOption{noformat}{\renewcommand*{\NamesFormat}{}}
\ExecuteOptions%
{nocomma,%
mainmatter,%
@@ -1988,7 +2073,11 @@ Running "make install" installs the files in the local TeX tree.
\RequirePackage{trimspaces}
\RequirePackage{xargs}
% \end{macrocode}
-% \clearpage\noindent
+% This macro determines the ``actual'' character for index sorting.
+% \begin{macrocode}
+\newcommand*\@nameauth@Actual{@}
+% \end{macrocode}
+% \clearpage
% \subsection{Internal Macros}
% \begin{macro}{\@nameauth@Clean}
% Thanks to \Name*[Heiko]{Oberdiek}, this macro produces a ``sanitized'' string, even using accented characters, based on the parameters of \cmd{\Name} and friends. With this we can construct a control sequence name and test for it to determine the existence of pseudonyms and the first or subsequent occurrences of a name.
@@ -2168,7 +2257,6 @@ Running "make install" installs the files in the local TeX tree.
% \end{macro}
% \clearpage\noindent
% \subsection{User Interface Macros}
-% The following macros have been documented previously. Either they call the internal macros or they set Boolean values.
% \begin{macro}{\CapThis}
% \changes{v0.94}{2012/02/15}{Added}
% Tells the root capping macro to cap an unaccented character.
@@ -2302,9 +2390,10 @@ Running "make install" installs the files in the local TeX tree.
%
% \begin{macro}{\IndexActual}
% \changes{v2.0}{2015/11/11}{Added}
-% turn on global indexing of names.
+% Change the ``actual'' character from the default.
% \begin{macrocode}
-\newcommand*{\IndexActual}[1]{\gdef\@nameauth@Actual{#1}}
+\newcommand*{\IndexActual}[1]%
+ {\global\renewcommand*\@nameauth@Actual{#1}}
% \end{macrocode}
% \end{macro}
%
@@ -3501,47 +3590,47 @@ Running "make install" installs the files in the local TeX tree.
\fi
\ifx\testd\@empty
\ifx\testb\@empty
- \ex\csgdef\ex{\ex\arga\ex}\ex{\ex\Name\ex{\the\tokc}}%
- \ex\csgdef\ex{\ex L\ex\arga\ex}\ex{\ex\Name\ex*\ex{\the\tokc}}%
- \ex\csgdef\ex{\ex S\ex\arga\ex}\ex{\ex\FName\ex{\the\tokc}}%
+ \ex\csgdef\ex{\ex\arga\ex}\ex{\ex\NameauthName\ex{\the\tokc}}%
+ \ex\csgdef\ex{\ex L\ex\arga\ex}\ex{\ex\NameauthName\ex*\ex{\the\tokc}}%
+ \ex\csgdef\ex{\ex S\ex\arga\ex}\ex{\ex\NameauthFName\ex{\the\tokc}}%
\else
\ex\ex\ex\csgdef\ex\ex\ex{\ex\ex\ex\arga\ex\ex\ex}%
- \ex\ex\ex{\ex\ex\ex\Name\ex\ex\ex[\ex\the\ex\tokb\ex]%
+ \ex\ex\ex{\ex\ex\ex\NameauthName\ex\ex\ex[\ex\the\ex\tokb\ex]%
\ex{\the\tokc}}%
\ex\ex\ex\csgdef\ex\ex\ex{\ex\ex\ex L\ex\ex\ex\arga%
- \ex\ex\ex}\ex\ex\ex{\ex\ex\ex\Name\ex\ex\ex*%
+ \ex\ex\ex}\ex\ex\ex{\ex\ex\ex\NameauthName\ex\ex\ex*%
\ex\ex\ex[\ex\the\ex\tokb\ex]\ex{\the\tokc}}%
\ex\ex\ex\csgdef\ex\ex\ex{\ex\ex\ex S\ex\ex\ex\arga%
- \ex\ex\ex}\ex\ex\ex{\ex\ex\ex\FName\ex\ex\ex[%
+ \ex\ex\ex}\ex\ex\ex{\ex\ex\ex\NameauthFName\ex\ex\ex[%
\ex\the\ex\tokb\ex]\ex{\the\tokc}}%
\fi
\else
\ifx\testb\@empty
\ex\ex\ex\csgdef\ex\ex\ex{\ex\ex\ex\arga\ex\ex\ex}%
- \ex\ex\ex{\ex\ex\ex\Name\ex\ex\ex{\ex\the\ex\tokc\ex}%
+ \ex\ex\ex{\ex\ex\ex\NameauthName\ex\ex\ex{\ex\the\ex\tokc\ex}%
\ex[\the\tokd]}%
\ex\ex\ex\csgdef\ex\ex\ex{\ex\ex\ex L\ex\ex\ex\arga%
- \ex\ex\ex}\ex\ex\ex{\ex\ex\ex\Name%
+ \ex\ex\ex}\ex\ex\ex{\ex\ex\ex\NameauthName%
\ex\ex\ex*\ex\ex\ex{\ex\the\ex\tokc\ex}\ex[\the\tokd]}%
\ex\ex\ex\csgdef\ex\ex\ex{\ex\ex\ex S\ex\ex\ex\arga%
- \ex\ex\ex}\ex\ex\ex{\ex\ex\ex\FName\ex\ex\ex{%
+ \ex\ex\ex}\ex\ex\ex{\ex\ex\ex\NameauthFName\ex\ex\ex{%
\ex\the\ex\tokc\ex}\ex[\the\tokd]}%
\else
\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\Name%
+ \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\tokb%
\ex\ex\ex]\ex\ex\ex{\ex\the\ex\tokc\ex}\ex[\the\tokd]}%
\ex\ex\ex\ex\ex\ex\ex\csgdef\ex\ex\ex\ex\ex\ex\ex{%
\ex\ex\ex\ex\ex\ex\ex L\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\Name\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\ex\ex\ex\ex[\ex\ex\ex\the\ex\ex\ex\tokb%
\ex\ex\ex]\ex\ex\ex{\ex\the\ex\tokc\ex}\ex[\the\tokd]}%
\ex\ex\ex\ex\ex\ex\ex\csgdef\ex\ex\ex\ex\ex\ex\ex{%
\ex\ex\ex\ex\ex\ex\ex S\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\FName\ex\ex\ex\ex\ex\ex\ex[%
+ \ex\ex\ex\ex\ex\ex\ex\NameauthFName\ex\ex\ex\ex\ex\ex\ex[%
\ex\ex\ex\the\ex\ex\ex\tokb\ex\ex\ex]%
\ex\ex\ex{\ex\the\ex\tokc\ex}\ex[\the\tokd]}%
\fi