summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/testidx/testidx-manual.tex
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/doc/latex/testidx/testidx-manual.tex')
-rw-r--r--Master/texmf-dist/doc/latex/testidx/testidx-manual.tex406
1 files changed, 381 insertions, 25 deletions
diff --git a/Master/texmf-dist/doc/latex/testidx/testidx-manual.tex b/Master/texmf-dist/doc/latex/testidx/testidx-manual.tex
index fc5546094f8..5311acae3a8 100644
--- a/Master/texmf-dist/doc/latex/testidx/testidx-manual.tex
+++ b/Master/texmf-dist/doc/latex/testidx/testidx-manual.tex
@@ -1,8 +1,9 @@
\documentclass[widecs]{nlctdoc}
\usepackage[marginpar=1in]{geometry}
-\usepackage[utf8]{inputenc}
\usepackage[T1]{fontenc}
+\usepackage[utf8]{inputenc}
+
\usepackage{metalogo}
\usepackage{cmap}
\usepackage{upquote}
@@ -26,12 +27,12 @@
\begin{document}
- \title{testidx.sty v1.0:
+ \title{testidx.sty v1.1:
dummy text for testing indexes}
\author{Nicola L.C. Talbot\\[10pt]
\url{http://www.dickimaw-books.com/}}
- \date{2016-10-17}
+ \date{2017-08-11}
\maketitle
\tableofcontents
@@ -43,10 +44,83 @@ The \styfmt{testidx} package is for testing indexes (\cs{index},
and \app{xindy}).
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 English not lorum ipsum, as this makes it
+The filler text is mostly English not lorum ipsum, as this makes it
slightly easier to check the words in the index against the words in
the document. (For those who don't understand English, it's at least
-no worse than lorum ipsum.)
+no worse than lorum ipsum.) There are some terms (words, phrases or proper
+nouns) that include extended Latin characters or digraphs to allow
+for testing with a variety of Latin alphabets. The dummy text is
+designed to cause problems that can occur in real documents to help
+test your chosen indexing application or index style. The main
+issues this package tries to replicate are:
+\begin{itemize}
+\item Multiple encaps. For example, the word \qt{paragraph} is
+indexed within the same block using no encap and each of the three
+test encap values. This causes the \app{makeindex} warning
+\qt{Conflicting entries: multiple encaps for the same page under
+same key.}
+
+\item An explicit range formation conflicting with a mid-range encap.
+The word \qt{range} has an explicit range formation (starting in
+block~4 and ending in block~9), but \qt{range} is also indexed in
+block~5 with one of the test encap values. This causes the
+\app{makeindex} warning \qt{Inconsistent page encapsulator \ldots\
+within range.}
+
+\item Page breaking mishaps. This is largely dependent on the font
+size and page geometry, but the dummy text contains some long
+paragraphs and has enough entries to result in at least some awkward
+page breaks. These may include a page or column break between an
+index group heading and the first entry in that group or between an
+index item and the first sub-item following it. Also check for
+indexing that occurs in paragraphs that span page breaks to ensure
+the location number is correct.
+
+\item Untidy page lists. This again depends on the font size and
+page geometry, but some entries are sporadically indexed throughout
+the dummy text, which can lead to a long list that can't be formed
+into a neat range.
+
+\item Mid-list cross-referencing. The word \qt{lyuk} is indexed
+and then cross-referenced in block~3, and indexed again in block~7.
+This can result in the rather odd occurrence of a cross-reference
+appearing in the middle of the location list for that entry, depending on the
+indexing method.
+
+\item Collation-level homographs. (Same spelling except for
+accents.) The words \qt{resume}
+and \qt{r\'esum\'e} are both indexed. These should be treated as
+separate entries in the index, even if the comparator considers
+them identical. Different indexing methods may
+produce different ordering or may even merge the two words, so check
+they are both present.
+
+\item Compound entries. The index contains a mixture of
+single words, compound words, names, titles and phrases. The ordering may vary
+depending on the sorting method. For example, check the ordering
+of \qt{sea}, \qt{sea lion}, \qt{seaborne} and \qt{seal}, and
+also the words starting with \qt{vice}, such as \qt{vice admiral},
+\qt{viceroy} and \qt{vice-president}.
+
+\item Long entries can cause awkward line breaks and justification
+in a multicolumn index with narrow columns.
+
+\item Interference caused by whatsits. Block~8 has a whatsit caused
+by the indexing that interferes with limits of a summation in an
+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.
+\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
+\sty{testidx-glossaries} which provides a similar way of testing the
+\sty{glossaries} or \sty{glossaries-extra} package.
Example document:
\begin{verbatim}
@@ -110,7 +184,7 @@ attributes (encaps) used in the dummy text. For example:
:close "}"
:attr "tstidxencapiii")
-(markup-locref-list :sep ",")
+(markup-locref-list :sep ", ")
(markup-range :sep "--")
\end{filecontents*}
@@ -243,9 +317,45 @@ quote '+'
\end{document}
\end{verbatim}
+The \styfmt{testidx-glossaries} package automatically loads
+\styfmt{testidx} and will also load either \sty{glossaries} or
+\sty{glossaries-extra}. For example:
+\begin{verbatim}
+\documentclass{report}
+
+\usepackage[T1]{fontenc}
+\usepackage{testidx-glossaries}
+
+\renewcommand*{\glstreenamefmt}[1]{#1}
+
+\tstidxmakegloss
+
+\begin{document}
+
+\testidx
+
+\tstidxprintglossaries
+
+\end{document}
+\end{verbatim}
+This automatically sets the \texttt{mcolsindexgroup} glossary style
+to mimic the style commonly used with indexes.
+This document can be built using:
+\begin{verbatim}
+pdflatex myDoc
+makeglossaries myDoc
+pdflatex myDoc
+\end{verbatim}
+Note that the \texttt{mcolsindexgroup} style sets the \texttt{name}
+field in \cs{glstreenamefmt}, which defaults to bold. This has been
+redefined in the above example to simply do its argument.
+
\section{Package Options}
\label{sec:pkgopt}
+\subsection{\texorpdfstring{\styfmt{testidx}}{testidx} options}
+\label{sec:testidxpkgopt}
+
The following package options are provided:
\begin{description}
\item[\pkgopt{german} or \pkgopt{ngerman}]
@@ -350,21 +460,178 @@ code (e.g.\ \verb"\tstidxsty[emph]{testidx}").
(Default.) Cancels the \pkgopt{notestencaps} option.
This option ensures that \ics{testidx} uses the three test
encaps.
+
+\item[\pkgopt{prefix}]
+(Default.) Inserts a prefix in the sort value for certain (symbol) entries to
+keep them together in the index. These entries represent markers
+(prefixed with \ics{tstidxindexmarkerprefix}) and maths symbols (prefixed with
+\ics{tstidxmathsymprefix}).
+
+\item[\pkgopt{noprefix}]
+Doesn't insert a prefix for the markers and maths symbol entries.
+This option doesn't alter the entries starting with a
+hyphen (such as \texttt{-l}) which always have that prefix
+since it's part of the display name.
+
+\item[\pkgopt{diglyphs}]
+Words with \tstidxqt{ll}, \tstidxqt{ij} and \tstidxqt{dz} digraphs
+will have the two characters forming the digraph replaced with a
+single UTF-8 glyph. This option only works if UTF-8 is supported
+\emph{and the document font recognises the glyphs}. (The trigraph
+\tstidxqt{dzw} and other digraphs,
+such as \tstidxqt{th} aren't affected by this option.)
+
+\item[\pkgopt{nodiglyphs}]
+(Default.) Don't use single glyphs for the \tstidxqt{ll},
+\tstidxqt{ij} and \tstidxqt{dz} digraphs. (This option doesn't
+affect other glyphs, such as \ae\ or \th, that are more commonly
+used in some languages.)
\end{description}
+\subsection{\texorpdfstring{\styfmt{testidx-glossaries}}{testidx-glossaries}
+ options}
+\label{sec:testidxglospkgopt}
+
+Most of the package options provided by \styfmt{testidx} can also be
+used with \styfmt{testidx-glossaries}. The \pkgopt{verbose} option
+has a slightly different effect. With \styfmt{testidx}, that option
+shows the indexing command within the text. However, the
+\sty{glossaries} package requires entries to first be defined and
+doesn't use \cs{index} but uses its own internal custom commands
+that depend on the indexing method, so for
+\styfmt{testidx-glossaries}, the \pkgopt{verbose} option instead
+writes information in the transcript file (\texttt{.log}) when the
+dummy entries are defined. For example:
+\begin{verbatim}
+Package testidx-glossaries Info: new term label={packages},
+(testidx-glossaries) name={packages},
+(testidx-glossaries) text={packages},
+(testidx-glossaries) parent={},
+(testidx-glossaries) see={}
+(testidx-glossaries) on input line 1.
+\end{verbatim}
+When used with the \pkgopt{tex} option, the \pkgopt{verbose}
+option will additionally write information while \TeX\ is
+sorting, since this can take a while and may give the appearance
+that the build process has hung.
+
+When used with the \pkgopt{bib2gls} option, the \pkgopt{verbose}
+option will show the syntax used by \ics{tstidxmakegloss}
+to load each resource. If you search the \texttt{.log} file for
+instances of \ics{GlsXtrLoadResource}, you'll find the commands
+needed to replicate the behaviour of \cs{tstidxmakegloss}.
+
+In addition to the options listed above, the following options are
+also available for \styfmt{testidx-glossaries}:
+\begin{description}
+\item[\pkgopt{extra}]
+Load the \sty{glossaries-extra} package.
+
+\item[\pkgopt{noextra}]
+Don't load the \sty{glossaries-extra} package. Just load the
+base \sty{glossaries} package. (Default.)
+
+\item[\pkgopt{makeindex}]
+(Default.) Passes the \pkgopt{makeindex} option to
+\sty{glossaries}. This option also sets up \ics{tstidxmakegloss}
+to use \ics{makeglossaries}, \ics{tstidxprintglossaries} to use
+\ics{printglossaries} and \ics{tstidxprintglossary} to use
+\ics{printglossary}. Use \app{makeglossaries} (or
+\app{makeglossaries-lite}) in the build process.
+
+\item[\pkgopt{xindy}] Passes the \pkgopt{xindy} option to
+\sty{glossaries}. This option also sets up \ics{tstidxmakegloss}
+to use \ics{makeglossaries}, \ics{tstidxprintglossaries} to use
+\ics{printglossaries} and \ics{tstidxprintglossary} to use
+\ics{printglossary}. Use \app{makeglossaries} (or
+\app{makeglossaries-lite}) in the build process.
+
+\item[\pkgopt{tex}] This option also sets up \ics{tstidxmakegloss}
+to use \ics{makenoidxglossaries}, \ics{tstidxprintglossaries} to use
+\ics{printnoidxglossaries} and \ics{tstidxprintglossary} to use
+\ics{printnoidxglossary}. (\TeX\ is used for to sort and collate the
+entries. Don't use \app{makeglossaries} or \app{makeglossaries-lite}
+in the build process.)
+
+\item[\pkgopt{bib2gls}] Passes the \pkgopt{record} option to
+\sty{glossaries-extra}. (This option automatically implements the
+\pkgopt{extra} option.) This option also sets up
+\ics{tstidxmakegloss} to use \ics{GlsXtrLoadResources},
+\ics{tstidxprintglossaries} to use
+\ics{printunsrtglossaries} and \ics{tstidxprintglossary} to use
+\ics{printunsrtglossary}. Use \app{bib2gls} in the build process.
+Note that this option ignores the commands
+\ics{tstidxindexmarkerprefix} and \ics{tstidxmathsymprefix}.
+
+\item[\pkgopt{manual}] Indicates that the test document
+doesn't use \cs{tstidxmakegloss}. (This disables the check
+that ensures that command has been used.) Use this option if you
+want to customize the glossary set-up. This option may be used in
+addition to the above options, but it will disable
+\cs{tstidxmakegloss}, \cs{tstidxprintglossary} and
+\cs{tstidxprintglossaries}.
+
+The sample files can be loaded using
+\begin{definition}[\DescribeMacro\tstidxloadsamples]
+\cs{tstidxloadsamples}
+\end{definition}
+(which \cs{tstidxmakegloss} does implicitly) except in the case of
+\pkgopt{bib2gls} where the sample files need to be loaded in
+\cs{GlsXtrLoadResource}.
+
+\item[\pkgopt{seekey}]
+(Default.)
+Use the \texttt{see} key for cross-references instead of using \ics{glssee}.
+If the \texttt{seealso} key has been defined (\sty{glossaries-extra}
+v1.16+), then this will be used for the \qt{see also}
+cross-references (otherwise \verb|see=[\seealsoname]|\marg{label}
+will be used).
+
+\item[\pkgopt{noseekey}]
+Use \ics{glssee} for cross-references and don't set the \texttt{see}
+(or \texttt{seealso}) key.
+
+\item[\pkgopt{noglsnumbers}] Passes the \pkgopt{glsnumbers=false} option to
+\sty{glossaries}.
+
+\item[\pkgopt{glsnumbers}] Passes the \pkgopt{glsnumbers=true} option to
+\sty{glossaries}. (This is the default for the \sty{glossaries}
+package.)
+
+\item[\pkgopt{desc}] Provide descriptions for the dummy entries.
+This setting automatically implements the \sty{glossaries}
+package's \pkgopt{nopostdot=false} option and sets the
+\texttt{indexgroup} glossary style.
+
+\item[\pkgopt{nodesc}]
+(Default.) Don't provide descriptions for the dummy entries.
+(The \texttt{description} field is set to empty.)
+This setting automatically implements the \sty{glossaries}
+package's \pkgopt{nopostdot} option and sets the
+\texttt{mcolindexgroup} glossary style. (The \sty{glossary-mcols} package
+is automatically loaded.)
+\end{description}
+
+Both the \texttt{mcolindexgroup} and \texttt{indexgroup} styles set
+the \texttt{name} field in \ics{glstreenamefmt}, which by default
+uses \cs{textbf}. This can be redefined as appropriate.
+You can switch to a different glossary style using
+\cs{setglossarystyle}\marg{style-name}.
+
\section{Basic Commands}
\label{sec:basic}
This section only covers the basic commands provided by
-\styfmt{testidx}. For more advanced commands, see the documented
-code.
+\styfmt{testidx} and \styfmt{testidx-glossaries}.
+For more advanced commands, see the documented code.
\begin{definition}[\DescribeMacro\testidx]
\cs{testidx}\oarg{blocks}
\end{definition}
-This is the principle command provided by this package. It
+This is the principle command provided by the \sty{testidx} package. It
generates the predefined dummy text that's interspersed
-with indexing commands. There are \number\tstidxmaxblocks\
+with indexing commands. (The text varies slightly according to the
+document settings.) There are \number\tstidxmaxblocks\
blocks in total. This number can be accessed through the register:
\begin{definition}[\DescribeMacro\tstidxmaxblocks]
\cs{tstidxmaxblocks}
@@ -386,15 +653,37 @@ displayed material. The starred form won't eliminate
paragraph breaks \emph{within} the blocks, just those
used as separators between the blocks.
+If you use \sty{testidx-glossaries}, you additionally need
+\begin{definition}[\DescribeMacro\tstidxmakegloss]
+\cs{tstidxmakegloss}\oarg{options}
+\end{definition}
+in the preamble. This loads the files that provide the dummy entries
+and uses \cs{makeglossaries} or \cs{makenoidxglossaries} or
+\cs{GlsXtrLoadResources} depending on the package options. The
+optional argument \meta{options} is appended to the optional argument of
+\cs{GlsXtrLoadResources} if the \pkgopt{bib2gls} package option has
+been used, otherwise \meta{options} is ignored.
+
+To display the glossary, either use
+\begin{definition}[\DescribeMacro\tstidxprintglossaries]
+\cs{tstidxprintglossaries}
+\end{definition}
+or
+\begin{definition}[\DescribeMacro\tstidxprintglossary]
+\cs{tstidxprintglossary}\marg{options}
+\end{definition}
+where you want the glossary to be displayed. This will use the
+appropriate command according to the package set up.
+
The intention of the dummy text is to provide an index that should
-typically span at least three pages for A4 or letter paper,
-to allow testing of headers and footers across a double-paged
-spread. Some of the indexing commands intentionally cause
-warnings from \app{makeindex} to test for certain situations.
-Phrases are indexed as well as just individual words to
-increase the chances of indexed terms spanning a page
-break. However, the page dimensions, fonts and other material in the
-document will obviously alter where the page breaks occur.
+typically span at least three pages for A4 or letter paper, to allow
+testing of headers and footers across a double-paged spread and to
+test the effects of page breaking. Some of the indexing commands intentionally
+cause warnings from \app{makeindex} to test for certain situations.
+Phrases are indexed as well as just individual words to increase the
+chances of indexed terms spanning a page break. However, the page
+dimensions, fonts and other material in the document will obviously
+alter where the page breaks occur.
You can display only a subset of the blocks using the optional
argument, which may be a comma-separated list of block identifiers
@@ -439,7 +728,7 @@ your intention. Just remember to stay within the range
1--\cs{tstidxmaxblocks} as you'll get an error if you
go out of those bounds.
-The actual indexing is performed using:
+With just \sty{testidx}, the actual indexing is performed using:
\begin{definition}[\DescribeMacro\tstindex]
\cs{tstindex}\marg{text}
\end{definition}
@@ -447,6 +736,10 @@ This defaults to just \cs{index}\marg{text} but may be redefined. For
example, if you are testing multiple indexes, you can
redefine \cs{tstindex} to use a specific index.
+With \sty{testidx-glossaries}, the above command isn't used.
+Instead \cs{gls}, \cs{glspl}, \cs{glsadd} or \cs{glssee} will be
+used depending on the context.
+
The dummy text includes markers to identify where the instances
of \cs{tstindex} have been used. To reduce the possibility of
package conflict, \styfmt{testidx} loads a bare minimum of
@@ -457,7 +750,9 @@ commands, so the markers are fairly primitive. If you prefer
fancier markers, you can change them by redefining the
commands listed below. Multiple markers in the dummy text
indicate multiple instances of \cs{tstindex} without any
-intervening text.
+intervening text. (Naturally, \sty{testidx-glossaries} requires more
+packages as it loads \sty{glossaries}, and possibly also
+\sty{glossaries-extra}.)
\begin{definition}[\DescribeMacro\tstidxmarker]
\cs{tstidxmarker}
@@ -562,7 +857,7 @@ text colour.
If you are using \app{xindy}, you'll need to add these
to a \texttt{.xdy} file that can be loaded using \app{xindy}'s
-\texttt{-M} switch. For example, include the following
+\texttt{-M} switch. For example, with just \sty{testidx}, include the following
in your \texttt{.xdy} file:
\begin{verbatim}
; list of allowed attributes
@@ -593,6 +888,35 @@ haven't already done so:
(markup-locref-list :sep ",")
(markup-range :sep "--")
\end{verbatim}
+If you use \sty{testidx-glossaries}, the \sty{glossaries} package
+provides commands to add information to the automatically generated
+\texttt{.xdy} file. For example:
+\begin{verbatim}
+\GlsAddXdyAttribute{tstidxencapi}
+\GlsAddXdyAttribute{tstidxencapii}
+\GlsAddXdyAttribute{tstidxencapiii}
+\end{verbatim}
+If you want to provide your own custom cross-reference class
+you can use
+\begin{definition}[\DescribeMacro\tstidxSetSeeEncap]
+\cs{tstidxSetSeeEncap}\marg{encap name}
+\end{definition}
+to change the \texttt{see} encap to \meta{encap name} and
+\begin{definition}[\DescribeMacro\tstidxSetSeeAlsoEncap]
+\cs{tstidxSetSeeAlsoEncap}\marg{encap name}
+\end{definition}
+to change the \texttt{seealso} encap to \meta{encap name}.
+For example:
+\begin{verbatim}
+\tstidxSetSeeAlsoEncap{uncheckedseealso}
+\end{verbatim}
+and in the \texttt{.xdy} file:
+\begin{verbatim}
+(define-crossref-class "uncheckedseealso" :unverified)
+(markup-crossref-list :class "uncheckedseealso"
+ :open "\seealso" :close "{}")
+\end{verbatim}
+which creates an unverified alternative to \texttt{seealso}.
The \cs{tstindex} command is sometimes placed before the term
or phrase being indexed and sometimes afterwards. To clarify
@@ -624,12 +948,18 @@ for better consistency. These markup commands typically
won't need changing, but if they do, see the documented code
for further detail.)
-Example:
+In the case of \sty{testidx-glossaries}, the above example would be
+\begin{verbatim}
+\gls{DonaldKnuth}\glsadd{people.DonaldKnuth}
+\end{verbatim}
+(\cs{index} isn't used).
+
+Example (using just \sty{testidx}):
\begin{verbatim}
\renewcommand*{\tstindex}[1]{}
\textsf{\testidx[1,\tstidxmaxblocks]}
\end{verbatim}
-produces the two paragraphs (first and last blocks) shown below:
+This produces the two paragraphs (first and last blocks) shown below:
\medskip\par
\renewcommand*{\tstindex}[1]{}
@@ -654,7 +984,8 @@ close a range.
If you need to change the indexing special characters, you
can redefine the commands listed in this section. Remember
that you will also need to make the relevant changes to your
-indexing style file.
+indexing style file. (These commands only apply to \sty{testidx} not
+\sty{testidx-glossaries}.)
\begin{definition}[\DescribeMacro\tstidxquote]
\cs{tstidxquote}
@@ -757,6 +1088,30 @@ Or
\end{document}
\end{verbatim}
+If the UTF-8 mode is on, you can additionally use the
+\pkgopt{diglyphs} package option to replace 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
+\begin{verbatim}
+\documentclass{article}
+
+\usepackage{fontspec}
+\setmainfont{Linux Libertine O}
+
+\usepackage{makeidx}
+\usepackage[diglyphs]{testidx}
+
+\makeindex
+
+\begin{document}
+\testidx
+
+\printindex
+\end{document}
+\end{verbatim}
+
\end{description}
When the ASCII mode is on, words or phrases with UTF-8
@@ -806,7 +1161,8 @@ example will appear in the \texttt{.idx} file as:
\begin{flushleft}\ttfamily
\cs{indexentry}\{\AA ngstr\"om, Anders Jonas\}\marg{location}
\end{flushleft}
-Regular \LaTeX\ requires the \sty{inputenc} package to support
+Regular \LaTeX\ (\app{latex} or \app{pdflatex}) requires the
+\sty{inputenc} package to support
UTF-8 characters, but each UTF-8 character is treated as
two tokens (the first and second octets) where the first token is an
active character that takes the second token as the argument.