From 35c007d48195f11757c61c71a9a0eb88420dc9d0 Mon Sep 17 00:00:00 2001 From: Karl Berry Date: Sun, 29 Sep 2019 21:15:10 +0000 Subject: testidx (29sep19) git-svn-id: svn://tug.org/texlive/trunk@52213 c570f23f-e606-0410-a88d-b1316a301751 --- .../doc/latex/testidx/testidx-manual.tex | 127 ++++++++++++++++++--- 1 file changed, 109 insertions(+), 18 deletions(-) (limited to 'Master/texmf-dist/doc/latex/testidx/testidx-manual.tex') diff --git a/Master/texmf-dist/doc/latex/testidx/testidx-manual.tex b/Master/texmf-dist/doc/latex/testidx/testidx-manual.tex index 5311acae3a8..a08bdfe22a9 100644 --- a/Master/texmf-dist/doc/latex/testidx/testidx-manual.tex +++ b/Master/texmf-dist/doc/latex/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