summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/nameauth/README.md
diff options
context:
space:
mode:
Diffstat (limited to 'macros/latex/contrib/nameauth/README.md')
-rw-r--r--macros/latex/contrib/nameauth/README.md122
1 files changed, 66 insertions, 56 deletions
diff --git a/macros/latex/contrib/nameauth/README.md b/macros/latex/contrib/nameauth/README.md
index 4f7b180364..dbcf3b3971 100644
--- a/macros/latex/contrib/nameauth/README.md
+++ b/macros/latex/contrib/nameauth/README.md
@@ -1,6 +1,6 @@
# 1. Short Description
-The `nameauth` package automates the correct formatting and indexing of names for professional writing. This aids the use of a name authority and the editing process without needing to retype name references.
+The `nameauth` package automates the correct formatting and indexing of names for professional writing. This aids the use of a name authority and the editing process without needing to retype name instances.
# 2. Files in Zip Archive
@@ -35,7 +35,7 @@ If not using the tools above, one can download `nameauth.zip` from [CTAN](https:
**Please inspect the included `Makefile` before using it.**
-`Makefile` has an extensive comment on usage, as well as many other comments. This file lists all the programs that must be installed in order to use GNU make file, helping one to check for prerequisites and dependencies. This method is designed for a POSIX-compliant environment, such as GNU/Linux, various BSDs, MacOS, and WSL or Cygwin on Windows.
+`Makefile` has an extensive comment on usage, as well as many other comments. This file lists all the programs that must be installed in order to use the GNU make file, helping one to check for prerequisites and dependencies. This method is designed for a POSIX-compliant environment, such as GNU/Linux, various BSDs, MacOS, and WSL or Cygwin on Windows.
### 4.2.2 Prepare to Install, No Building
@@ -43,7 +43,7 @@ One does not need to build `nameauth` completely from source (although it may be
make unpack
-This target only unpack the supplied generated files from `nameauth.dtx`. It does not try to create the documentation. One will have the following files now:
+This target only unpacks the supplied generated files from `nameauth.dtx`. It does not try to create the documentation. One will have the following files now:
| Filename | Description | TDS-where to |
| :------------- | :------------------------- | :----------- |
@@ -67,11 +67,11 @@ Take a look at **4.2.3 Specific Build Cases** and, depending on the use case, sk
### 4.2.3 Specific Build Cases: Program Extensions
-Windows presents some interesting cases. Both Cygwin and WSL provide POSIX environments that include respective TeX distros of their own. Yet they also will operate with native Windows-based TeX distros like MiokTeX and TeXlive.
+Windows presents some interesting cases. Both Cygwin and WSL provide POSIX environments that include respective TeX distros of their own. Yet they also will operate with native Windows-based TeX distros like MikTeX and TeXlive.
When using the TeX distros built in to Cygwin and WSL exclusively, one can treat it basically as a POSIX-compliant environment.
-Even when using Cygwin and a Windows-based TeX distro, one can treat package building as being mostly the same as a POSIX environment if all the preqequisite programs are installed. Installation, however, must be manual.
+Even when using Cygwin and a Windows-based TeX distro, one can treat package building as being mostly the same as a POSIX environment if all the prerequisite programs are installed. Installation, however, must be manual.
When one uses WSL with a Windows-based TeX distro, the `Makefile` will test whether an ".exe" extension is needed by the programs used in the building process.
@@ -87,19 +87,19 @@ With both Cygwin and WSL, tests will determine if the standard POSIX method is c
Here is a table showing the feasibility of a few scenarios:
-| Platform | TeX Distro Platform | Build package and zip with make | Install package with make |
-| :------- | :------------------------ | :------------------------------ | :------------------------------ |
-| POSIX | POSIX | Yes<sup>1</sup> | Yes |
-| Cygwin | Cygwin (distro packages) | Not tested; likely<sup>1</sup> | Not tested; likely <sup>2</sup> |
-| Cygwin | MikTeX (Windows) | Yes<sup>1, 3</sup> | No;<sup>4</sup> do manually |
-| Cygwin | TeXlive (Windows) | Not tested; likely<sup>1</sup> | Not tested; do manually |
-| Cygwin | Both Cygwin and Windows | Not tested; not recommended | Not tested; not recommended |
-| WSL | WSL Linux distro packages | Yes<sup>1</sup> | Yes<sup>5</sup> |
-| WSL | MikTeX (Windows) | Yes<sup>1, 3</sup> | No;<sup>4</sup> do manually |
-| WSL | TeXlive (Windows) | Not tested; likely<sup>1</sup> | Not tested; do manually |
-| WSL | Both WSL and Windows | Not tested; not recommended | Not tested; not recommended |
-| WSL/Cyg | Both WSL and Cygwin | Not tested; not recommended | Not tested; not recommended |
-| GNUWin | any (Windows) | Not tested; not recommended | Not tested; not recommended |
+| Platform | TeX Distro Platform | Make builds pkg/zip | Make installs package |
+| :------- | :------------------ | :----------------------------- | :------------------------------ |
+| POSIX | POSIX | Yes<sup>1</sup> | Yes |
+| Cygwin | Cygwin (packages) | Not tested; likely<sup>1</sup> | Not tested; likely <sup>2</sup> |
+| Cygwin | MikTeX (Windows) | Yes<sup>1, 3</sup> | No;<sup>4</sup> do manually |
+| Cygwin | TeXlive (Windows) | Not tested; likely<sup>1</sup> | Not tested; do manually |
+| Cygwin | Cygwin and Windows | Not tested; not recommended | Not tested; not recommended |
+| WSL | WSL Linux packages | Yes<sup>1</sup> | Yes<sup>5</sup> |
+| WSL | MikTeX (Windows) | Yes<sup>1, 3</sup> | No;<sup>4</sup> do manually |
+| WSL | TeXlive (Windows) | Not tested; likely<sup>1</sup> | Not tested; do manually |
+| WSL | WSL and Windows | Not tested; not recommended | Not tested; not recommended |
+| WSL/Cyg | WSL and Cygwin | Not tested; not recommended | Not tested; not recommended |
+| GNUWin | any (Windows) | Not tested; not recommended | Not tested; not recommended |
<sup>1</sup> All dependencies must be met. Bear in mind MacOS quirks.
@@ -127,7 +127,7 @@ Assuming that one has a use case where one can use GNU make, one can choose the
If, for some reason, this fails, do a manual install (below).
-Note that these make targets depend on `package`, which does not do a clean build. To ensure a clean build, use `make release inst` or `make release install`.
+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
@@ -181,22 +181,22 @@ One may skip past building to **4.3.3 Installation Prerequisites** below.
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 |
+| 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:
@@ -304,17 +304,17 @@ Create the directories in the left-hand column, or whatever one needs to do in o
* The documentation now builds only with `pdflatex`, but the examples and tests can use any LaTeX engine. This is because several typesetting decisions that are quite helpful for the manual work only with `pdflatex`.
-* This release was tested on Linux (Pop! OS; vanilla TL 2022 and 2017) and Windows 10 (MikTeX with both Cygwin and WSL). The tests using TL 2017 include my published book manuscript, *Breath of God, Yet Work of Man: Scripture, Philosophy, Dialogue, and Conflict*, with Dr. Albert B. Collver III.
+* 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 2022 on Pop! OS. The most recent `equivs` file was used to meet package equivalencies. See also [this page](https://tug.org/texlive/debian.html).
+* 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 2022 and TL 2017 are managed on Pop! OS using [tl-switch](https://github.com/ServusCarolus/tl-switch).
+* 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`, which also uses `compat.tex`, usually should be enough to illustrate various non-trivial features of this package. It includes most of the longer examples in the manual, edited to fit together in a single document.
+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.
@@ -324,6 +324,8 @@ To test `nameauth`, either test the files right after installing, or create a ne
* 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
@@ -331,19 +333,19 @@ To test `nameauth`, either test the files right after installing, or create a ne
make examples ENGINE=dvilualatex
make examples ENGINE=latex
-* If one wants to change engines and re-test the file, type `make exclean`.
-
* To generate additional test files, type `make tests`.
- This will produce many test files numbered by chapter and example within that chapter from the `nameauth.dtx` file. It will compile all of the test files using `pdflatex`. One can add the value of ENGINE:
+ 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 one wants to change engines and re-test the files, type `make testclean`.
-
* If, for some reason, one wanted to make the manual illustrations (usually not required), one would type `make images`.
## 6.2 Manual Method
@@ -369,7 +371,7 @@ Another step is used only with `latex` and `dvilualatex`. We default to `dvipdfm
dvipdfmx examples
-If one changes LaTeX engines, one must remove all of the auxiliary files.
+If one changes LaTeX engines, one first must remove all of the auxiliary files.
### 6.2.2 Tests
@@ -396,7 +398,7 @@ This step is used only when using `latex` and `dvilualatex`.
dvipdfmx test01-01
-If one changes LaTeX engines, one must remove all of the auxiliary files.
+If one changes LaTeX engines, one first must remove all of the auxiliary files.
### 6.2.3 Images
@@ -427,27 +429,35 @@ Compile the test files:
# 7. Additional Notes
-In version 3.7 I spent over seven months analyzing and optimizing both code and documentation. Stepping away from this package for a bit gave me the perspective and clarity to improve it greatly.
+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/).
-* I cast aside a number of stale presuppositions that had built up over time. I explored all the ways that one could use certain features and fixed the bugs that appeared by using a better general approach.
+Improvements in version 3.7 include:
-* I brought back some thorough tests reminiscent of early package versions, but moved to the examples file.
+* Rejection of stale assumptions that had built up over time, based either on initial ignorance or on features that have since changed in LaTeX.
-* I rewrote the documentation to remove a lot of idiosyncratic formatting. It looks much cleaner, both as source code and as typeset documentation.
+* The examples file contains some tests that used to be in the documentation.
-* Extensive rewriting has led to the TOC becoming the principal expression of scope and sequence. The goal was greater rigor in keeping the easy stuff easy and the complex stuff more accessible.
+* Major rewrite of documentation.
-* The package itself has been reorganized to follow the same sequence as the documentation, letting the rhythm of repetition aid learning. One sees this right away in the TOC.
+* The table of contents better frflects scope and sequence.
-* Several macros have been optimized, leading to simpler and cleaner designs that are easier to debug.
+* The package itself has been reorganized to follow the same scope and sequence as the documentation.
-* A few bugs that could result from directly changing internal package flags have been fixed, allowing the user-accessible parser to work in all cases as intended.
+* Several macros have been optimized, leading to simpler and cleaner designs that are easier to debug. Additional bug fixes ensure stability,
-* Any name arguments shown in warnings are detokenized in order to prevent potential errors. Regressions caused by a reverted edit in an earlier version that I failed to catch caused several package warnings to halt with errors. These "lameauth" errors are fixed.
+* Name arguments shown in package warnings are detokenized in order to prevent potential errors.
# 8. Copyright
-Copyright (C) 2023 by Charles P. Schaum <charles[dot]schaum@comcast.net>
+Copyright (C) 2024 by Charles P. Schaum <charles[dot]schaum@comcast.net>
This file may be distributed and/or modified under the
conditions of the LaTeX Project Public License, either version 1.3