From bbbe8128e7ae9d816a221377dbf5ff3969bb203b Mon Sep 17 00:00:00 2001
From: Norbert Preining <norbert@preining.info>
Date: Mon, 30 Sep 2019 03:00:43 +0000
Subject: CTAN sync 201909300300

---
 macros/latex/contrib/testidx/testidx-manual.tex | 127 ++++++++++++++++++++----
 1 file changed, 109 insertions(+), 18 deletions(-)

(limited to 'macros/latex/contrib/testidx/testidx-manual.tex')

diff --git a/macros/latex/contrib/testidx/testidx-manual.tex b/macros/latex/contrib/testidx/testidx-manual.tex
index 5311acae3a..a08bdfe22a 100644
--- a/macros/latex/contrib/testidx/testidx-manual.tex
+++ b/macros/latex/contrib/testidx/testidx-manual.tex
@@ -27,12 +27,12 @@
 
 \begin{document}
 
- \title{testidx.sty v1.1: 
+ \title{testidx.sty v1.2: 
 dummy text for testing indexes}
  \author{Nicola L.C. Talbot\\[10pt]
 \url{http://www.dickimaw-books.com/}}
 
- \date{2017-08-11}
+ \date{2019-09-29}
  \maketitle
  \tableofcontents
 
@@ -41,7 +41,11 @@ dummy text for testing indexes}
 
 The \styfmt{testidx} package is for testing indexes (\cs{index},
 \env{theindex} and indexing applications, such as \app{makeindex}
-and \app{xindy}).
+and \app{xindy}). See also
+\href{http://tug.org/TUGboat/tb38-3/tb120talbot.pdf}{Testing
+indexes: \texttt{testidx.sty}} in 
+\href{http://tug.org/TUGboat/Contents/contents38-3.html}{TUGboat issue 38:3, 2017}.
+
 As with packages like \sty{lipsum} and \sty{blindtext}, this package
 provides dummy text, but it's interspersed with \cs{index} commands.
 The filler text is mostly English not lorum ipsum, as this makes it
@@ -112,13 +116,23 @@ equation.
 \item Symbols and numbers that don't have a natural word order.
 The numbers may or may not be ordered numerically, depending on the
 indexing method.
+
+\item An item with just a single sub-item. (Perhaps the document
+author intended to index more sub-items but they weren't needed in
+the end.) Ideally this needs to be flagged and have the hierarchy
+removed. There are actually two lonely sub-items. The first is
+\qt{properties} as a sub-item of \qt{document}. In this case the
+parent \qt{document} has also been indexed and has a location. The
+second is \qt{lonely} as a sub-item of \qt{sub-items}. In this case
+the parent \qt{sub-items} hasn't been indexed and so doesn't have a
+location.
 \end{itemize}
 In addition, words containing extended Latin characters, digraphs and a
 trigraph are indexed to help test various Latin alphabets, such as
 Swedish, Icelandic, Welsh, Dutch, Polish and Hungarian. These may or
 may not be recognised by indexing applications.
 
-Version 1.1 now comes with a supplementary package
+As from version 1.1, \sty{testidx} now comes with a supplementary package
 \sty{testidx-glossaries} which provides a similar way of testing the
 \sty{glossaries} or \sty{glossaries-extra} package.
 
@@ -150,6 +164,24 @@ There will be warnings about multiple encaps. This is intentional
 to test how the indexing applications deal with this problem.
 \end{important}
 
+Note that as from 2018, \LaTeX\ now automatically provides limited
+UTF-8 support even if the document doesn't load \sty{inputenc}. Therefore
+the above document will use the ASCII indexing tests with pre-2018
+\LaTeX, but will use the UTF-8 indexing tests with newer versions of
+the \LaTeX\ kernel (because \cs{inputencodingname} is now defined as
+\texttt{utf8}). If you specifically want to test ASCII indexing
+then you either need to switch to ASCII encoding:
+\begin{verbatim}
+\usepackage[ascii]{inputenc}
+\usepackage{makeidx}
+\usepackage{testidx}
+\end{verbatim}
+or use \sty{testidx}'s \pkgopt{ascii} option:
+\begin{verbatim}
+\usepackage{makeidx}
+\usepackage[ascii]{testidx}
+\end{verbatim}
+
 If you want to use \app{xindy}, you'll need to define the 
 attributes (encaps) used in the dummy text. For example:
 \begin{verbatim}
@@ -272,7 +304,7 @@ For example:
 \usepackage{filecontents}
 \usepackage{makeidx}
 \usepackage{ngerman}
-\usepackage[german]{testidx}
+\usepackage[german,ascii]{testidx}
 
 \begin{filecontents*}{\jobname.ist}
 quote '+'
@@ -302,7 +334,7 @@ Alternatively:
 \usepackage{filecontents}
 \usepackage{makeidx}
 \usepackage{babel}
-\usepackage{testidx}
+\usepackage[ascii]{testidx}
 
 \begin{filecontents*}{\jobname.ist}
 quote '+'
@@ -324,7 +356,7 @@ The \styfmt{testidx-glossaries} package automatically loads
 \documentclass{report}
 
 \usepackage[T1]{fontenc}
-\usepackage{testidx-glossaries}
+\usepackage[ascii]{testidx-glossaries}
 
 \renewcommand*{\glstreenamefmt}[1]{#1}
 
@@ -358,6 +390,15 @@ redefined in the above example to simply do its argument.
 
 The following package options are provided:
 \begin{description}
+\item[\pkgopt{ascii}] Use only ASCII tests even if the document
+supports UTF-8. Any characters outside
+that range are produced with \LaTeX\ commands.
+
+\item[\pkgopt{noascii}] (Default.) Don't enforce ASCII tests. This option 
+doesn't actually provide UTF-8 support but will simply
+determine whether or not to use ASCII tests depending on the
+document's input encoding.
+
 \item[\pkgopt{german} or \pkgopt{ngerman}]
 This redefines the indexing \qt{quote} character to use \texttt{+}
 instead of the double-quote character. Remember to add this
@@ -412,6 +453,10 @@ This option may also be implemented using
 \begin{definition}[\DescribeMacro\testidxSanitizeOff]
 \cs{testidxSanitizeOff}
 \end{definition}
+Note that as from \LaTeX\ 2019/10/01 UTF-8 characters are no longer
+expanded while they are written to the \texttt{.idx} file. This
+means that there may be no difference between \pkgopt{sanitize} and
+\pkgopt{nosanitize} depending on the \LaTeX\ kernel in use.
 
 \item[\pkgopt{showmarks}]
 (Default.) Show the location of the \cs{index} commands
@@ -1026,12 +1071,16 @@ The \qt{close range} character. The default is:
 \label{sec:exlatin}
 
 The dummy text includes words or phrases that have extended
-Latin characters. There are two modes:
+Latin characters. (The document encoding should be correctly set
+before loading \sty{testidx}.) There are two modes:
 
 \begin{description}
-\item[ASCII] This mode is on \emph{unless} you are using
-\XeLaTeX\ or \LuaLaTeX, or the document has loaded 
-\sty{inputenc} with the encoding set to \pkgopt{utf8}.
+\item[ASCII] This mode is on by default \emph{unless} you are using
+\XeLaTeX\ or \LuaLaTeX, or the document has the encoding set to \pkgopt{utf8}.
+Note that with new versions of \LaTeX, \cs{inputencodingname} is now
+automatically defined as \pkgopt{utf8} by the kernel. You can
+explicitly switch this mode on with the \pkgopt{ascii} package
+option.
 
 Example that will switch on ASCII mode:
 \begin{verbatim}
@@ -1049,12 +1098,30 @@ Example that will switch on ASCII mode:
 \printindex
 \end{document}
 \end{verbatim}
+(With new versions of \LaTeX\ this document will start with
+\cs{inputencodingname} set to \texttt{utf8} and then it will be
+changed to \texttt{latin1} when \sty{inputenc} is loaded.)
+
+Alternatively use the \pkgopt{ascii} package option:
+\begin{verbatim}
+\documentclass{article}
 
-\item[UTF-8] This mode is on \emph{if} you are using
-\XeLaTeX\ or \LuaLaTeX, or if the document has loaded 
-\sty{inputenc} with the encoding set to \pkgopt{utf8}.
+\usepackage{makeidx}
+\usepackage[ascii]{testidx}
 
-Example that will switch on UTF-8 mode:
+\makeindex
+
+\begin{document}
+\testidx
+
+\printindex
+\end{document}
+\end{verbatim}
+
+\item[UTF-8] This mode is on by default \emph{if} you are using
+\XeLaTeX\ or \LuaLaTeX, or if \cs{inputencodingname} is set to \pkgopt{utf8}.
+
+Example that will switch on UTF-8 mode (\XeLaTeX\ or \LuaLaTeX):
 \begin{verbatim}
 \documentclass{article}
 
@@ -1070,7 +1137,7 @@ Example that will switch on UTF-8 mode:
 \printindex
 \end{document}
 \end{verbatim}
-Or
+Or (\sty{inputenc} sets the encoding to UTF-8):
 \begin{verbatim}
 \documentclass{article}
 
@@ -1084,6 +1151,23 @@ Or
 \begin{document}
 \testidx
 
+\printindex
+\end{document}
+\end{verbatim}
+Or with new versions of the \LaTeX\ kernel (which automatically
+provides UTF-8 support):
+\begin{verbatim}
+\documentclass{article}
+
+\usepackage[T1]{fontenc}
+\usepackage{makeidx}
+\usepackage{testidx}
+
+\makeindex
+
+\begin{document}
+\testidx
+
 \printindex
 \end{document}
 \end{verbatim}
@@ -1093,7 +1177,7 @@ If the UTF-8 mode is on, you can additionally use the
 \tstidxqt{ll}, \tstidxqt{ij} and \tstidxqt{dz} digraphs with 
 a single glyph, but you'll need a font that supports
 those glyphs. (The trigraph \tstidxqt{dzw} and other digraphs,
-such as \tstidxqt{th} aren't affected by this option.) For example
+such as \tstidxqt{th} aren't affected by this option.) For example:
 \begin{verbatim}
 \documentclass{article}
 
@@ -1174,7 +1258,7 @@ above will appear in the \texttt{.idx} file as:
 \end{verbatim}
 (where 3 is the page number).
 
-Since this can confuse the indexing application,
+Since this expansion can confuse the indexing application,
 \styfmt{testidx} provides a \pkgopt{sanitize} package option
 which will first sanitize the UTF-8 characters before
 indexing them. This option is on by default for regular \LaTeX\ and
@@ -1188,6 +1272,13 @@ if you want to test how your indexing command (whatever
 \cs{tstindex} is defined as) behaves with these characters, then 
 switch it off.
 
+\begin{important}
+As from \LaTeX\ 2019/10/01 this behaviour has changed and the UTF-8
+characters are no longer expanded while they are written to the
+\texttt{.idx} file. This means that the tests may produce different
+results depending on the \LaTeX\ kernel in use.
+\end{important}
+
 Note that this \pkgopt{sanitize} option isn't adjusting the
 definition of \cs{index} or \cs{tstindex}, but is essentially
 pretending that the user is doing something like:
-- 
cgit v1.2.3

