% \iffalse meta-comment
%
% Copyright (C) 2025 Alan J. Cain
%
% This file may be distributed and/or modified under the conditions of the LaTeX Project Public License, either version
% 1.3c of this license or (at your option) any later version. The latest version of this license is in:
%
% http://www.latex-project.org/lppl.txt
%
% and version 1.3c or later is part of all distributions of LaTeX version 2008-05-04 or later.
%
% \fi
%
% \iffalse
%<*driver>
\PassOptionsToPackage{inline}{enumitem}
\documentclass{l3doc}
\makeatletter
\ExplSyntaxOn
\cs_gset:Npn \l@subsection { \@dottedtocline{2}{2.5em}{2.8em} } % #2 = 1.5em
\cs_gset:Npn \l@subsubsection { \@dottedtocline{3}{5.3em}{3.2em} } % #2 = 1.5em
\ExplSyntaxOff
\makeatother
\usepackage{xcolor}
\definecolor{linkcolor}{rgb}{0.0,0.4,0.7}
\colorlet{citecolor}{linkcolor}
\colorlet{urlcolor}{linkcolor}
\hypersetup{
linkcolor=linkcolor,%
citecolor=citecolor,%
urlcolor=urlcolor,%
}
\newcommand*\fullref[2]{%
\hyperref[#2]{#1\penalty 200\ \ref*{#2}}%
}
\numberwithin{figure}{section}
\numberwithin{table}{section}
\usepackage{mathtools}
\DeclarePairedDelimiter{\abs}{\lvert}{\rvert}
\DeclarePairedDelimiter{\set}{\lbrace}{\rbrace}
\newcommand*\key[1]{\texttt{#1}}
\newcommand*\val[1]{\texttt{#1}}
\newcommand*\keyval[2]{\texttt{#1=#2}}
\newcommand*\ttdashdash{\texttt{-}\texttt{-}\hskip 0pt\relax}
\NewDocumentCommand{\default}{ m }{(\textit{Default:} #1)}
\newcommand*\mcode[1]{\texttt{#1}}
\newcommand*\param[1]{\texttt{\##1}}
\newcommand*\MakeIndex{\textit{MakeIndex}}
\newcommand*\upmendex{\texttt{upmendex}}
\newcommand*\xindy{\texttt{xindy}}
\usepackage{siunitx}
\sisetup{
mode=match,
}
\DeclareSIUnit\point{pt}
\DeclareSIUnit\spoint{sp}
\newcommand*\purl[1]{\textsc{url:}~\url{#1}}
\usepackage{listings}
\usepackage{indextra}
\begin{document}
\DocInput{indextra.dtx}
\end{document}
%</driver>
% \fi
%
%
%
% \GetFileInfo{indextra.sty}
%
% \makeatletter
% \lstset{
% language=[LaTeX]TeX,
% columns=fullflexible,
% keepspaces=true,
% commentstyle=\slshape,
% basicstyle=\ttfamily\lst@ifdisplaystyle\small\fi,
% }
% \makeatother
%
%
%
% \title{^^A
% \pkg{indextra} ^^A
% --- Enhanced index typesetting^^A
% \thanks{This file describes \fileversion, last revised \filedate.}^^A
% }
%
% \author{^^A
% Alan J. Cain^^A
% }
%
% \date{Released \filedate}
%
% \maketitle
%
%
%
% \begin{abstract}
% This package provides some enhanced features for typesetting indexes, notably: (1) Continuation text when entries or
% sub-entries continue from one page or column to the next. (2) An interface for accessing marks created from index
% entries, so that (for example) a running head can include the range of index entries that appears on the page.
% \end{abstract}
%
%
%
% \tableofcontents
%
%
%
% \begin{documentation}
%
% \section{Introduction}
%
% By default, an index in a \LaTeX\ document is typeset in two columns and provides no indication if a page or column
% break occurs inside an index entry or sub-entry. The package
% \pkg{repeatindex}\footnote{\purl{https://ctan.org/pkg/repeatindex}} handles a page or column break that occurs between
% sub-entries within the same entry by repeating the keyword of the main entry. But it does not repeat the keyword of a
% sub-entry when a page or column break occurs within it. Nor does it repeat the keyword of an entry (at the top level)
% % if the break occurs mid-way through a long list of pages or ranges for that entry directly.
% In \emph{The \TeX book}, Knuth described a plain \TeX\ method to create continuation texts using the mark mechanism
% \cite[pp.~261--3]{knuth_texbook}, which does not have these limitations. But there are still situations in which this
% method can cause problems: for instance, if the keyword in the index entry spans two or more lines, it may break
% across a page or column and the continuation text would appear in the middle of the keyword.
%
% The \pkg{indextra} package is intended to create suitable continuation texts for all of these possibilities. An
% example is shown in \fullref{Figure}{fig:indextra-doc-demo}, where the list of locations within a sub-entry is too
% long to fit in the left-hand column. At the top of the right-hand column, \pkg{indextra} has indicated that both the
% main entry and the sub-entry have both been continued. If there had been a page break as well as a column break, the
% same indicators would have been placed at the start of the left-hand column of the next page.
%
% \begin{figure}[t]
% \centering
% \includegraphics{indextra-doc-demo.pdf}
% \caption{An example of how \pkg{indextra} continues an entry and a sub-entry after a column or page break.}
% \label{fig:indextra-doc-demo}
% \end{figure}
%
% \pkg{indextra} tries to break columns intelligently. If only one line of a multi-line index entry would fit in the
% remaining space of the current column, the column break is inserted first, since there would be no saving in space
% because the continutation text would occupy (at least) one line of the next column. Similarly, it will not break a
% column before or during any cross-references in the index entry.
%
% \pkg{indextra} also supplies a system for retrieving index entry keywords as marks, for use in running heads to show
% the range of index entries on the current page. The keywords of the first and last top-level entries on each page are
% available as \cs{indextrafirstmark} and \cs{indextralastmark}.
%
% \medskip
% \noindent\textit{Caveat:}~~Although \pkg{indextra} has been used successfully for the indexes of the author's
% books,\footnote{Available on the Internet Archive under Creative Commons licences:\par
% (1)~A.J. Cain, \textit{Form \& Number: A History of Mathematical Beauty}. Lisbon, 2024.
% \purl{https://archive.org/details/cain_formandnumber_ebook_large}\par
% (2)~G.H. Hardy, \textit{An Annotated Mathematician's Apology}. With annotations and commentary by A.J. Cain. Lisbon,
% 2019. \purl{https://archive.org/details/hardy_annotated}} in its current state it should be regarded as
% semi-experimental, requiring further development, and having many limitations and some incompatibilites (see
% \fullref{Subsection}{subsec:limitations}).
%
%
%
% \section{Requirements}
%
% \pkg{indextra} does not depend on any other packages, but requires a recent \LaTeX\ kernel with \pkg{expl3} support.
% (Any kernel version since 2020-02-02 should suffice.)
%
%
%
% \section{Installation}
%
% To install \pkg{indextra} manually, run \texttt{tex indextra.ins} and copy the file \texttt{indextra.sty} to somewhere
% \LaTeX\ can find it, \texttt{indextra.ist} to somewhere \MakeIndex\ and/or \upmendex\ can find it, and
% \texttt{indextra.xdy} to somewhere \xindy\ can find it. To build the documentation, first compile
% \texttt{indextra-doc-demo.tex} to a PDF, then compile \texttt{indextra-doc.tex}.
%
%
%
% \section{Getting started}
%
% \subsection{\LaTeX}
%
% On the \LaTeX\ side, simply use the package with \lstinline!\usepackage{indextra}!. (There are no package options.)
% Use \cs{makeindex} and \cs{index} as as usual. Note that \pkg{indextra} is incompatible with \pkg{imakeindex}.
%
% If the \pkg{hyperref} package is used, set \keyval{hyperindex}{false} in its package options or in \cs{hypersetup},
% because \pkg{indextra} has its own mechanism to add index hyperlinks, activated by its own \key{hyperindex} key.
%
%
%
% \subsection{Index generation}
%
% The \file{.ind} file (generated by \MakeIndex, \upmendex, or \xindy) must be specially formatted for \pkg{indextra}.
% The style file \file{indextra.ist} is supplied for use with \MakeIndex\ and \upmendex. It can be used with:\par
% \texttt{makeindex -s indextra.ist \meta{filename}.idx}\par
% \noindent or\par
% \texttt{upmendex -s indextra.ist \meta{filename}.idx}\par
% \noindent Also supplied is a barebones \xindy\ module \file{indextra.xdy} style file, which should be used with other
% modules to set up sorting and attributes. The module \file{indextra.xdy} should be specified last when invoking
% \xindy, to override any previous specification of how to write to the \file{.idx} file. For example, one might
% use:\par
% \texttt{xindy -M makeidx.xdy -M utf8.xdy -M indextra.xdy \meta{filename}.idx}
%
%
%
% \section{Configuration}
%
% \begin{function}{\indextrasetup}
% \begin{syntax}
% \cs{indextrasetup}\marg{options}
% \end{syntax}
% This command is used to specify options. The argument \meta{options} is a key--value list. The options are described
% in the subsections below and are summarized in \fullref{Table}{tbl:keys-summary}.
% \end{function}
%
% \begin{table}[t]
% \addtolength{\leftskip}{-12mm}%
% \addtolength{\textwidth}{12mm}%
% \caption{Summary of keys that can be set using \cs{indextrasetup}.}
% \label{tbl:keys-summary}
% \begin{tabular*}{\textwidth}{lll@{\extracolsep{\fill}}}
% \toprule
% \textsf{Key name} & \textsf{Value} & \textsf{Default} \\
% \midrule
% \key{before code} & \LaTeX\ code & \val{\cs{begin}\{theindex\}} \\
% \key{after code} & \LaTeX\ code & \val{\cs{end}\{theindex\}} \\
% \key{level 0 style} & \LaTeX\ code & \val{\cs{parindent}=0em\cs{hangindent}=3.75em} \\
% \key{level 1 style} & \LaTeX\ code & \val{\cs{parindent}=1.5em\cs{hangindent}=5.25em} \\
% \key{level 2 style} & \LaTeX\ code & \val{\cs{parindent}=3em\cs{hangindent}=6.75em} \\
% \key{separator keyword crossref} & \LaTeX\ code & \cs{break} \\
% \key{separator keyword location} & \LaTeX\ code & \cs{space}\cs{space} \\
% \key{separator crossref crossref} & \LaTeX\ code & \cs{break} \\
% \key{separator crossref location} & \LaTeX\ code & \cs{break} \\
% \key{separator location location} & \LaTeX\ code & \val{,\textvisiblespace} \\
% \key{crossref macros} & List of macros & \cs{see}\cs{seealso} \\
% \key{hyperindex} & \(\set{\val{true},\val{false}}\) & \val{true} \\
% \key{bookmarks} & \(\set{\val{true},\val{false}}\) & \val{true} \\
% \bottomrule
% \end{tabular*}
% \end{table}
%
%
%
% \subsection{Before and after code}
%
% \DescribeOption{before code}
% This option specifies code that is executed at the start of the index (more specifically,
% at the start of the \env{theindextra} environment in the generated \file{.ind} file). The code will be executed before
% \pkg{indextra} sets various parameters and makes available the commands described in
% \fullref{Section}{sec:ind-macros}. The user may wish to use this option to set up running heads using \pkg{indextra}'s
% marks (see \fullref{Subsection}{subsec:example-marks} for an example). \default{\cs{begin}\mcode{\{theindex\}}}
%
% \DescribeOption{after code}
% This option specifies code that is executed at end start of the index (more specifically,
% at the end of the \env{theindextra} environment in the generated \file{.ind} file).
% \default{\cs{begin}\mcode{\{theindex\}}}
%
%
%
% \subsection{Styles}
%
% \DescribeOption{level \(n\) style} The style applied to an index entry at level \(n = 0,1,2\) (that is, respectively
% to an entry, a sub-entry, and a sub-sub-entry).
%
% \noindent
% \begin{tabular}{@{}r@{~}l}
% (\textit{Default:} & \keyval{level 0 style}{\cs{parindent}=0em\allowbreak\cs{hangindent}=3.75em}; \\
% & \keyval{level 1 style}{\cs{parindent}=1.5em\cs{hangindent}=5.25em}; \\
% & \keyval{level 2 style}{\cs{parindent}=3em\allowbreak\cs{hangindent}=6.75em})
% \end{tabular}
%
%
%
% \subsection{Separators}
%
% \pkg{indextra} always typesets cross-references before locations in each index entry, sub-entry, or sub-sub-entry. The
% following options specify the separators to be used.
%
% \DescribeOption{separator keyword crossref}
% The separator to be placed between the keyword of an index entry and a cross-reference. \default{\cs{break}}
%
% \DescribeOption{separator keyword location}
% The separator to be placed between the keyword of an index entry and a location (that is, a page or range of pages),
% when the first location immediately follows the keyword (when there are no cross-references).
% \default{\cs{space}\cs{space}}
%
% \DescribeOption{separator crossref crossref}
% The separator to be placed between the two cross-references in an index entry. \default{\cs{break}}
%
% \DescribeOption{separator crossref location}
% The separator to be placed between the last cross-reference in an entry and the first location. \default{\cs{break}}
%
% \DescribeOption{separator location location}
% The separator to be placed between two locations in an index entry. \default{\texttt{,\textvisiblespace}}
%
%
%
% \subsection{Specification of cross-references}
%
% \DescribeOption{crossref macros}
% A list of macros that signify cross-references. \default{\cs{see}\cs{seealso}}
%
%
%
% \subsection{Hyperlinks}
%
% \DescribeOption{hyperindex}
% A boolean \val{true}/\val{false} that indicates whether index locations should be hyperlinked if the \cs{hyperpage}
% macro from the \pkg{hyperref} package is available. Note that a user redefinition of \cs{indextrapage} or
% \cs{indextrarange} (see \fullref{Subsection}{subsec:user-redefinable-page-range}) will override this setting. If
% hyperlinks are required in this case, the user's redefinition should create them. \default{\val{true}}
%
%
%
% \subsection{Bookmarks}
%
% \DescribeOption{bookmarks}
% A boolean \val{true}/\val{false} that indicates whether the beginning of each group of index entries (usually terms
% beginning with a particular letter) should be bookmarked if the \cs{belowpdfbookmark} macro from the \pkg{hyperref}
% package is available. \default{\val{true}}
%
%
%
% \subsection{Headings}
%
% \DescribeOption{headings} A boolean \val{true}/\val{false} that indicates whether there should be a heading at the
% beginning of each group of index entries (usually terms beginning with a particular letter). This heading will be
% created by the user-redefinable macro \cs{indextramakegroupheading} (see
% \fullref{Subsection}{subsec:user-redefinable-heading}). \default{\val{true}}
%
%
%
% \section{Marks}
%
% \pkg{indextra} uses the keyword of each (top-level) index entry to insert a mark. The following macros make available
% the first and last marks on the current page. They are intended for use in a running header to show the range of
% entries on the current page.
%
% \begin{function}{\indextrafirstmark}
% The first mark on the current page, with the macro \cs{indextramakemark} applied.
% \end{function}
%
% \begin{function}{\indextralastmark}
% The last mark on the current page, with the macro \cs{indextramakemark} applied.
% \end{function}
%
%
%
% \section{User-redefinable macros}
%
% \subsection{Keywords}
%
% The following macros is used to typeset keywords of entries, sub-entries, and sub-sub-entries. It can be redefined by
% the user.
%
% \begin{function}{\indextrakeyword}
% \begin{syntax}
% \cs{indextrakeyword}\marg{level}\marg{keyword}
% \end{syntax}
% This macro is used to typeset a keyword for an entry of level \meta{level}. The default definition simply yields
% \meta{keyword}. Users may wish to use a redefinition to apply styling or for other purposes. The result will already
% have the code specified in \key{level \meta{level} style} applied.
% \end{function}
%
%
%
% \subsection{Page and range typesetting}
% \label{subsec:user-redefinable-page-range}
%
% The following two macros are actually used to typeset locations. They can be redefined by the user.
%
% \begin{function}{\indextrapage}
% \begin{syntax}
% \cs{indextrapage}\marg{encapsulation}\marg{page}
% \end{syntax}
% This command is used to typeset a reference to a single page. The default definition is effectively
% \meta{encapsulation}\texttt{\{}\meta{page}\texttt{\}}, but using the configuration option \keyval{hyperindex}{true}
% will create a hyperlink to the actual page. Any redefinition of this command will override the effect of
% \keyval{hyperindex}{true}, so if the user still wishes the reference to be a hyperlink to the actual page, the new
% definition must create the hyperlink.
% \end{function}
%
% \begin{function}{\indextrarange}
% \begin{syntax}
% \cs{indextrarange}\marg{encapsulation}\marg{start}\marg{end}
% \end{syntax}
% This command is used to typeset a reference to a range of pages. The default definition is effectively
% \meta{encapsulation}\texttt{\{}\meta{page}\texttt{\}}\ttdashdash\meta{encapsulation}\texttt{\{}\meta{page}\texttt{\}},
% but using the configuration option \keyval{hyperindex}{true} will create a hyperlink to the actual pages. Users may
% wish to redefine \cs{indextrarange} to abbreviate ranges (so that, for instance, 1024--1025 is replaced by 1024--5).
% Any redefinition of this command will override the effect of \keyval{hyperindex}{true}, so if the user still wishes
% the references to be hyperlinks to the actual pages, the new definition must create the hyperlinks.
% \end{function}
%
%
%
% \subsection{Continuation text}
%
% \pkg{indextra} inserts continuation text for each entry, sub-entry, and sub-sub-entry that has been interrupted by a
% page or column break. The following macro creates the continuation text and can be redefined by the user.
%
% \begin{function}{\indextramakecontinuation}
% \begin{syntax}
% \cs{indextramakecontinuation}\marg{level}\marg{keyword}
% \end{syntax}
% This macro is used to generate a continuation text when the entry at \meta{level} with the supplied \meta{keyword}
% contains a column break. The default definition simply yields \meta{keyword}\texttt{ (cont.)}. Users may wish to use
% a redefinition to apply styling. The continuation text will already have the code specified in \key{level
% \meta{level} style} applied.
% \end{function}
%
%
%
% \subsection{Marks}
%
% \begin{function}{\indextramakemark}
% \begin{syntax}
% \cs{indextramakemark}\marg{text}
% \end{syntax}
% This command is applied to any mark retrieved via either \cs{indextrafirstmark} or \cs{indextralastmark}. The
% default definition simply yields \meta{text}. A redefinition could be used to abbreviate or otherwise process
% \meta{text}.
% \end{function}
%
%
%
% \subsection{Headings}
% \label{subsec:user-redefinable-heading}
%
% If the option \keyval{headings}{true} is set, the following macro generates the group heading and can be
% redefined by the user.
%
% \begin{function}{\indextramakegroupheading}
% \begin{syntax}
% \cs{indextramakegroupheading}\marg{group}
% \end{syntax}
% This macro is used to generate a heading for \meta{group}. The default definition yields \cs{textbf}\marg{group}.
% Users may wish to use a redefinition to apply a different style. Note that even if this command is redefined to
% yield nothing, an extra vertical space will still be produced in the index where the heading would have been. To
% disable headings and avoid this extra space, set \keyval{headings}{false} using \cs{indextrasetup}.
% \end{function}
%
%
%
% \section{Macros used in the generated \texorpdfstring{\file{.ind}}{.ind} file}
% \label{sec:ind-macros}
%
% For completeness, this section documents the commands and the enclosing environment used in the generated \file{.ind}
% file. None of these is intended to be used or redefined by the user.
%
% \begin{environment}{theindextra}
% Environment containing the generated index.
% \end{environment}
%
% The commands below are only defined inside the \env{theindextra} environment.
%
% \begin{function}{\indextrastyleversion}
% \begin{syntax}
% \cs{indextrastyleversion}\marg{version}
% \end{syntax}
% Specify the \pkg{indextra} version of the style used to generate the \file{.ind} file. (This macro exists in case
% future updates change the required format of the \file{.ind} file.)
% \end{function}
%
% \begin{function}{\indextraprocessortype}
% \begin{syntax}
% \cs{indextraprocessortype}\marg{type}
% \end{syntax}
% Specify the type of the processor used to generate the \file{.ind} file. (Different encapsulations of ranges, which
% must be handled differently, are generated by \MakeIndex/\upmendex\ and by \xindy.) \marg{type} is either
% \mcode{ist}, indicating that \MakeIndex\ or \upmendex\ was used, or \mcode{xdy}, indicating that \xindy\ was used.
% \end{function}
%
% \begin{function}{\indextraentry}
% \begin{syntax}
% \cs{indextraentry}\marg{level}\marg{keyword}\marg{crossrefs-and-locations}
% \end{syntax}
% This command typesets an index entry, sub-entry, or sub-sub-entry (if \meta{level} is respectively \mcode{0},
% \mcode{1}, or \mcode{2}) with the given \meta{keyword}. The parameter \meta{crossrefs-and-locations} is a
% comma-separated list of cross-references (using macros such as \cs{see} or \cs{seealso} as specified in the
% \key{crossref macros} option) and locations (meaning pages or ranges).
% \end{function}
%
% \begin{function}{\indextraspace}
% \begin{syntax}
% \cs{indextraspace}
% \end{syntax}
% This command produces a space of one line in the index.
% \end{function}
%
% \begin{function}{\indextragroup}
% \begin{syntax}
% \cs{indextragroup}\marg{letter}
% \end{syntax}
% This command begins the new group \meta{letter}. Depending on configuration, it may produce a heading and/or a
% bookmark.
% \end{function}
%
%
%
% \section{Usage notes and caveats}
% \label{sec:usage-notes}
%
% \subsection{Typesetting process}
%
% \pkg{indextra} works by tracking how much space is left in each column and intially typesetting each index entry into
% a buffer and measuring it. If there is enough space left in the column, the buffer contents are added to the output
% and the amount of space left is adjusted appropriately. Otherwise, enough of the buffer as will fit is split off and
% output, then a column break is called, the continuation text is added to the top of the remaining content in the
% buffer, and the process continues in a new column.
%
% This process relies on the fact that an index is a highly structured text with a restricted format. Any `exotic' index
% entries may break the process.
%
%
%
% \subsection{Limitations and incompatibilies}
% \label{subsec:limitations}
%
% \begin{itemize}
%
% \item When choosing where to break a column, \pkg{indextra} only considers the current entry at the current level.
% It does not, for example, automatically decide to insert a column break before a one-line top-level entry
% that contains a sub-entry, even though this would be a more desirable result.
%
% \item \pkg{indextra} cannot cope with \cs{verb} commands in index keywords. (But succeeding in generating such an
% \file{.ind} via the usual \LaTeX\ indexing commands would be a challenge.)
%
% \item \pkg{indextra} is incompatible with \pkg{imakeidx}, which uses the \pkg{multicols} package to set the index
% instead of the native \LaTeX\ two-column mode. In particular, \LaTeX\ marks cannot be set from within
% the \env{multicols} environment.
%
% \item \pkg{indextra} should not be used with \pkg{repeatindex}, and in any case replaces its functionality.
%
% \item \pkg{indextra} cannot be used if the usual indexing system is heavily customized. For example, the
% \cls{l3doc} class uses its own specialized implementation of indexing and so \pkg{indextra} cannot be used
% alongside it.
%
% \end{itemize}
%
%
%
% \subsection{Example of using marks}
% \label{subsec:example-marks}
%
% One could incorporate marks into the index running heads using by appending suitable code to the default value
% (\cs{begin}\mcode{\{theindex\}}) of the \key{before code} key:
% \iffalse
%<*example>
% \fi
\begin{lstlisting}
\indextrasetup{
before code={%
\begin{theindex}%
\markboth
{\MakeUppercase\indexname~%
\noexpand\indextrafirstmark--\noexpand\indextralastmark}
{\MakeUppercase\indexname~%
\noexpand\indextrafirstmark--\noexpand\indextralastmark}%
},
}
\end{lstlisting}
% \iffalse
%</example>
% \fi
% (The \cs{noexpand} macros ensure that \cs{indextrafirstmark} and \cs{indextralastmark} are expanded when
% the page is shipped out, not when \cs{markboth} is used.)
%
%
%
% \begin{thebibliography}{1}
%
% \bibitem{knuth_texbook}
% D.E.~Knuth.
% \newblock \emph{{T}he {\TeX book}}.
% \newblock Addison--Wesley, 2021.
% \newblock \emph{{C}omputers {\&} {T}ypesetting}, vol.~A.
%
% \end{thebibliography}
%
%
%
% \end{documentation}
%
%
%
% \begin{implementation}
%
%
%
% \section{Implementation}
%
% \begin{macrocode}
%<*package>
%<@@=indextra>
% \end{macrocode}
%
%
%
% \subsection{Initial set-up}
%
% Package identification/version information.
% \begin{macrocode}
\NeedsTeXFormat{LaTeX2e}[2020-02-02]
\ProvidesExplPackage{indextra}{2025-02-26}{0.21.2}
{Enhanced index typesetting}
% \end{macrocode}
%
%
%
% \subsection{User configuration}
%
% Set up the key--value options and the variables in which the settings will be stored.
%
% \begin{variable}{
% \l_@@_before_code_tl,
% \l_@@_after_code_tl,
% }
% Token list keys that store code to be executed before and after the index is typeset.
% \begin{macrocode}
\keys_define:nn { indextra }
{
before~code .tl_set:N = \l_@@_before_code_tl,
after~code .tl_set:N = \l_@@_after_code_tl,
before~code .initial:n = {\begin{theindex}},
after~code .initial:n = {\end{theindex}},
}
% \end{macrocode}
% \end{variable}
%
%
% \begin{variable}{
% \l_@@_level_0_style_tl,
% \l_@@_level_1_style_tl,
% \l_@@_level_2_style_tl,
% }
% Token list keys that store the style to be applied to entries at each level.
% \begin{macrocode}
\keys_define:nn { indextra }
{
level~0~style .tl_set:c = {l_@@_level_0_style_tl},
level~1~style .tl_set:c = {l_@@_level_1_style_tl},
level~2~style .tl_set:c = {l_@@_level_2_style_tl},
level~0~style .initial:n = {\parindent=0em\hangindent=3.75em},
level~1~style .initial:n = {\parindent=1.5em\hangindent=5.25em},
level~2~style .initial:n = {\parindent=3em\hangindent=6.75em},
}
% \end{macrocode}
% \end{variable}
%
%
% \begin{variable}{
% \l_@@_separator_kw_cr_tl,
% \l_@@_separator_kw_loc_tl,
% \l_@@_separator_cr_cr_tl,
% \l_@@_separator_cr_loc_tl,
% \l_@@_separator_loc_loc_tl,
% }
% Token list keys to store separators. Macros are abbreviated as follows \mcode{kw}: keyword; \mcode{cr}:
% cross-reference; \mcode{loc}: location (page or range).
% \begin{macrocode}
\keys_define:nn { indextra }
{
separator~keyword~crossref .tl_set:N = \l_@@_separator_kw_cr_tl,
separator~keyword~location .tl_set:N = \l_@@_separator_kw_loc_tl,
separator~crossref~crossref .tl_set:N = \l_@@_separator_cr_cr_tl,
separator~crossref~location .tl_set:N = \l_@@_separator_cr_loc_tl,
separator~location~location .tl_set:N = \l_@@_separator_loc_loc_tl,
separator~keyword~crossref .initial:n = {\break},
separator~keyword~location .initial:n = {\space\space},
separator~crossref~crossref .initial:n = {\break},
separator~crossref~location .initial:n = {\break},
separator~location~location .initial:n = {,~},
}
% \end{macrocode}
% \end{variable}
%
%
% \begin{variable}{
% \l_@@_crossref_macros_tl,
% }
% Token list key to store macros that should count as cross-references.
% \begin{macrocode}
\keys_define:nn { indextra }
{
crossref~macros .tl_set:N = \l_@@_crossref_macros_tl,
crossref~macros .initial:n = {\see\seealso},
}
% \end{macrocode}
% \end{variable}
%
%
% \begin{variable}{
% \l_@@_hyperindex_bool,
% }
% Boolean indicating whether locations should be hyperlinked to pages, if \cs{hyperpage} is available and the user has
% not redefined \cs{indextrapage} and \cs{indextrarange}.
% \begin{macrocode}
\keys_define:nn { indextra }
{
hyperindex .bool_set:N = \l_@@_hyperindex_bool,
hyperindex .initial:n = {true},
}
% \end{macrocode}
% \end{variable}
%
%
% \begin{variable}{
% \l_@@_bookmarks_bool,
% }
% Boolean indicating whether groups should be bookmarked, if \cs{belowpdfbookmark} is available.
% \begin{macrocode}
\keys_define:nn { indextra }
{
bookmarks .bool_set:N = \l_@@_bookmarks_bool,
bookmarks .initial:n = {true},
}
% \end{macrocode}
% \end{variable}
%
%
% \begin{variable}{
% \l_@@_headings_bool,
% }
% Boolean indicating whether group headings should appear.
% \begin{macrocode}
\keys_define:nn { indextra }
{
headings .bool_set:N = \l_@@_headings_bool,
headings .initial:n = {true},
}
% \end{macrocode}
% \end{variable}
%
%
% \begin{macro}{
% \indextrasetup,
% }
% User command to set key--value configuration.
% \begin{macrocode}
\NewDocumentCommand{\indextrasetup}{ m }
{
\keys_set:nn{ indextra }{ #1 }
}
% \end{macrocode}
% \end{macro}
%
%
%
% \subsection{Environment and commands for the \texorpdfstring{\file{.ind}}{.ind} file}
%
% Define the environment and commands used in the generated \file{.ind} file.
%
% \begin{macro}{
% theindextra
% }
% This environment is the analogue of the \env{theindex} environment defined by basic \LaTeX.
% \begin{macrocode}
\NewDocumentEnvironment{theindextra}{}
{ \@@_main_begin: }
{ \@@_main_end: }
%
% \end{macrocode}
% \end{macro}
%
% \begin{macro}{
% \@@_main_begin:
% }
% This macro (locally) sets various \TeX\ dimensions and defines the commands that are actually used in the index,
% namely \cs{indextrastyleversion}, \cs{indextraprocessortype}, \cs{indextraspace}, \cs{indextragroup}, and
% \cs{indextraentry}.%
% \begin{macrocode}
\cs_new:Npn \@@_main_begin:
{
% \end{macrocode}
% Open a group and execute code for before the index has been typeset.
% \begin{macrocode}
\group_begin:
\tl_use:N\l_@@_before_code_tl
% \end{macrocode}
% Set \cs{splittopskip}, \cs{topskip}, and \cs{parskip} to the needed values, and set
% \cs{g_@@_remaining_space_dim}, which tracks the space left in the current column, to the initial value of
% \cs{@colht}, which will be the height of the column after any initial two-column text has been typeset.
% \begin{macrocode}
\dim_gset:Nn\g_@@_remaining_space_dim{\@colht}
\dim_set:Nn\splittopskip{.7\baselineskip}
\dim_set:Nn\topskip{.7\baselineskip}
\dim_set:Nn\parskip{0pt}
% \end{macrocode}
% Make available the appropriate macros.
% \begin{macrocode}
\cs_set_eq:NN\indextrastyleversion\@@_style_version:n
\cs_set_eq:NN\indextraprocessortype\@@_processor_type:n
\cs_set_eq:NN\indextraspace\@@_space:
\cs_set_eq:NN\indextragroup\@@_group:n
\cs_set_eq:NN\indextraentry\@@_entry:nnn
% \end{macrocode}
% If user settings require it, or \cs{belowpdfbookmark} is unavailable, disable group bookmarks and/or headings.
% \begin{macrocode}
\bool_if:nF
{ \l_@@_bookmarks_bool && \cs_if_exist_p:N\belowpdfbookmark }
{
\cs_set_eq:NN\@@_bookmark_stored_group:\prg_do_nothing:
}
\bool_if:NF\l_@@_headings_bool
{
\cs_set_eq:NN\@@_typeset_stored_group_heading:\prg_do_nothing:
}
% \end{macrocode}
% Depending on user configuration, if \cs{hyperpage} is available and \cs{indextrapage} or \cs{indextrapage} have not
% been redefined, then change them to create hyperlinks.
% \begin{macrocode}
\bool_if:nT{ \l_@@_hyperindex_bool && \cs_if_exist_p:N\hyperpage }
{
\cs_if_eq:NNT\indextrapage\@@_page_basic:nn
{
\cs_set_eq:NN\indextrapage\@@_page_hyperref:nn
}
\cs_if_eq:NNT\indextrarange\@@_range_basic:nnn
{
\cs_set_eq:NN\indextrarange\@@_range_hyperref:nnn
}
}
}
% \end{macrocode}
% \end{macro}
%
% \begin{macro}{
% \@@_main_end:
% }
% Execute code for after the index has been typeset and close the group opened in \cs{@@_main_begin:}.
% \begin{macrocode}
\cs_new:Npn \@@_main_end:
{
\tl_use:N\l_@@_after_code_tl
\group_end:
}
% \end{macrocode}
% \end{macro}
%
% \begin{macrocode}
\msg_new:nnn{ indextra }{ incompatible_version }
{ The~.ind~file~was~generated~using~a~style~from~a~different~version~of~indextra. }
% \end{macrocode}%
%
% \begin{macro}{
% \@@_style_version:n,
% }
% Specify the version of \pkg{indextra}'s index processor style file (\file{.ist} or \file{.xdy}) that was used to
% generate the \file{.ind} file. If is incompatible with version of \pkg{indextra} in use, an error will result.
% \begin{macrocode}
\cs_new:Npn\@@_style_version:n #1
{
\str_if_eq:nnF{#1}{0.1}
{
\msg_error:nn{ indextra }{ incompatible_version }
}
}
% \end{macrocode}
% \end{macro}
%
%
%
% \begin{macro}{
% \@@_processor_type:n,
% }
% Set the type of the processor used to generate the \file{.ind} file. \MakeIndex\ and \upmendex\ produce ranges of
% the form \cs{encapsulation}\texttt{\{}\meta{start}\ttdashdash\meta{end}\texttt{\}}, while \xindy\ produces ranges of
% the form \cs{encapsulation}\texttt{\{}\texttt{\}}\ttdashdash\cs{encapsulation}\texttt{\{}\texttt{\}}. These kinds of
% ranges must be parsed differently, and while the kind of range could be detected when typesetting each location,
% there are efficiency savings from using a dedicated parser in each case. \param{1} should be either \mcode{ist},
% indicating that the processor was either \MakeIndex\ or \upmendex, or \mcode{xdy}, that the processor was \xindy.
% This macro will be set equal to \cs{indextrasetprocessortype} inside the \env{theindextra} environment.
% \begin{macrocode}
\cs_new:Npn\@@_processor_type:n #1
{
\cs_set_eq:Nc\@@_typeset_aux_location:n
{ @@_typeset_#1_location:n }
}
% \end{macrocode}
% \end{macro}
%
%
%
%
% \subsection{Column handling}
%
% \begin{variable}{
% \g_@@_remaining_space_dim,
% }
% Dimension variable to hold the amount of space left in the current column.
% \begin{macrocode}
\dim_new:N\g_@@_remaining_space_dim
% \end{macrocode}
% \end{variable}
%
% \begin{macro}{
% \@@_new_column:
% }
% Fill any remaining space in the current column, start a new column, and set \cs{g_@@_remaining_space_dim} to
% \cs{@colht} (which is the amount of space available in the new column).
% \begin{macrocode}
\cs_new:Npn\@@_new_column:
{
\vfill
\newpage
\dim_gset:Nn\g_@@_remaining_space_dim{\@colht}
}
% \end{macrocode}
% \end{macro}
%
%
%
% \subsection{Spaces}
%
% \begin{macro}{
% \@@_space:,
% }
% Create a space in the index, which will usually signify the end of one letter group and the beginning of another.
% This takes up space in the column, so the space (a \cs{strut}) is typeset via the same mechanism as index entries,
% namely \cs{@@_typeset_buffer:}.
% \begin{macrocode}
\cs_new:Npn\@@_space:
{
\dim_compare:nNnT{\g_@@_remaining_space_dim}<{\baselineskip}{
\@@_new_column:
}
\vbox_set:Nn\l_@@_buffer_box{\leavevmode\strut\par}
\@@_typeset_buffer:
}
% \end{macrocode}
% \end{macro}
%
%
%
% \subsection{Groups}
%
% \begin{variable}{
% \l_@@_group_tl
% }
% Token-list variable to store the current group.
% \begin{macrocode}
\tl_new:N\l_@@_group_tl
% \end{macrocode}
% \end{variable}
%
%
% \begin{macro}{
% \@@_group:,
% }
% Begin a letter group in the index. The macro simply stores the group title; the bookmark and/or heading will be
% created by the next index entry. This macro will be set equal to \cs{indextragroup} inside the \env{theindextra}
% environment.
% \begin{macrocode}
\cs_new:Npn\@@_group:n #1
{
\tl_set:Nn\l_@@_group_tl{#1}
}
% \end{macrocode}
% \end{macro}
%
%
% \begin{variable}{
% \g_@@_group_bookmark_int
% }
% Integer variable to index groups; used in the creation of bookmarks in \cs{@@_bookmark_stored_group:}.
% \begin{macrocode}
\int_new:N\g_@@_group_bookmark_int
% \end{macrocode}
% \end{variable}
%
%
% \begin{macro}{
% \@@_bookmark_stored_group:
% }
% If \cs{l_@@_group_tl} is non-empty, create a bookmark below the current level (i.e., using \cs{belowpdfbookmark}),
% using \cs{l_@@_group_tl} for the bookmark text. The variable \cs{g_@@_group_bookmark_int} is incremented at each
% call and used to create distinct bookmark names. (One cannot use the the content of \cs{l_@@_group_tl} for the
% bookmark name, because (1) it might not be suitable as a name, and (2) there may be two indexes (e.g. names and
% subjects) which contain the same groups.)
% \begin{macrocode}
\cs_new:Npn\@@_bookmark_stored_group:
{
\tl_if_empty:NF\l_@@_group_tl
{
\int_gincr:N\g_@@_group_bookmark_int
\belowpdfbookmark
{\tl_use:N\l_@@_group_tl}
{pdf:indextra:\int_value:w\g_@@_group_bookmark_int}
}
}
% \end{macrocode}
% \end{macro}
%
%
% \begin{macro}{
% \@@_typeset_stored_group_heading:
% }
% If \cs{l_@@_group_tl} is non-empty, typeset its contents as a heading for the group.
% \begin{macrocode}
\cs_new:Npn\@@_typeset_stored_group_heading:
{
\tl_if_empty:NF\l_@@_group_tl
{
\group_begin:
\noindent\strut
\indextramakegroupheading{\tl_use:N\l_@@_group_tl}
\strut\par
\group_end:
}
}
% \end{macrocode}
% \end{macro}
%
%
% \begin{macro}{
% \indextramakegroupheading
% }
% Typeset a heading for the letter group passed as \param{1}.
% \begin{macrocode}
\cs_new:Npn\indextramakegroupheading #1
{
\textbf{#1}
}
% \end{macrocode}
% \end{macro}
%
%
%
%
%
% \subsection{Entries}
%
% \begin{variable}{
% \l_@@_level_int
% }
% Integer variable to hold the level of the current entry.
% \begin{macrocode}
\int_new:N\l_@@_level_int
% \end{macrocode}
% \end{variable}
%
%
% \begin{variable}{
% \l_@@_saved_keyword_0,
% \l_@@_saved_keyword_1,
% \l_@@_saved_keyword_2,
% }
% Token list variables to save keywords at each level.
% \begin{macrocode}
\tl_new:c{l_@@_saved_keyword_0}
\tl_new:c{l_@@_saved_keyword_1}
\tl_new:c{l_@@_saved_keyword_2}
% \end{macrocode}
% \end{variable}
%
%
% \begin{variable}{
% \l_@@_crossref_seq,
% \l_@@_location_seq,
% }
% Comma-separated list variables to hold the cross-references and locations of the current entry. These will be
% populated via a call to \cs{@@_filter_crossref_location_seqs:n}
% \begin{macrocode}
\seq_new:N\l_@@_crossref_seq
\seq_new:N\l_@@_location_seq
% \end{macrocode}
% \end{variable}
%
%
% \begin{macro}{
% \@@_entry:nnn,
% }
% Typeset an index entry. The three parameters are the level (\param{1}), the keyword (\param{2}), and the rest of the
% entry (\param{3}), which should be a comma-separated list of cross-references and/or locations.
% \begin{macrocode}
\cs_new:Npn\@@_entry:nnn #1#2#3
{
% \end{macrocode}
% First save the level and the keyword, and sort the rest of the entry into the cross-reference and location seqs.
% \begin{macrocode}
\int_set:Nn\l_@@_level_int{#1}
\tl_set:cn{l_@@_saved_keyword_#1}{#2}
\@@_filter_crossref_location_seqs:n{#3}
% \end{macrocode}
% Typeset the entire entry (prefixed by any stored group heading) into \cs{l_@@_buffer_box}. The bookmarking command
% is also executed here, since it is the contents of this box that will ultimately be shipped out.
% \begin{macrocode}
\vbox_set:Nn\l_@@_buffer_box{
\@@_bookmark_stored_group:
\@@_typeset_stored_group_heading:
\group_begin:
\@@_set_style:n{#1}
\leavevmode
\strut
\indextrakeyword{#1}{#2}
\@@_typeset_between:
\@@_typeset_locations:
\strut
\par
\goodbreak
\group_end:
}
% \end{macrocode}
% Now typeset some material into \cs{l_tmpa_box} and \cs{l_tmpb_box}, the dimensions of which will be used in
% computing the minimum acceptable portion of the entry to typeset into the current column. First, typeset the part of
% the entry where a column break is unacceptable (prefixed by any stored group heading) into \cs{l_tmpa_box}.
% \begin{macrocode}
\vbox_set:Nn\l_tmpa_box{
\@@_typeset_stored_group_heading:
\group_begin:
\@@_set_style:n{#1}
\leavevmode
\strut
\indextrakeyword{#1}{#2}
\@@_typeset_between:
\@@_typeset_first_location:
\strut
\par
\group_end:
}
% \end{macrocode}
% Typeset any stored group heading into \cs{l_tmpb_box}.
% \begin{macrocode}
\vbox_set:Nn\l_tmpb_box{
\@@_typeset_stored_group_heading:
}
% \end{macrocode}
% Measuring \cs{l_tmpa_box}, \cs{l_tmpb_box}, and \cs{l_@@_buffer_box}, check whether there is enough space in the
% current column to typeset any stored heading and the minimum acceptable portion of the entry. Basically, a split
% should not occur within the part typeset into \cs{l_tmpa_box}, and if the entry as a whole is longer than one line,
% then at least two lines should be typeset (because if only one line can fit into the current column, there is
% probably no overall saving of space by putting it in the current column with a continuation in the next column).
% Note that if there is no stored heading, the height and depth of \cs{l_tmpb_box} are both \qty{0}{\point}, so no
% conditional is needed.
% \begin{macrocode}
\dim_compare:nNnT
{\g_@@_remaining_space_dim}
<
{
\dim_min:nn{
\dim_max:nn{
\box_ht:N\l_tmpa_box
+\box_dp:N\l_tmpa_box
}{
\box_ht:N\l_tmpb_box
+\box_dp:N\l_tmpb_box
+2\baselineskip
}
}{
\box_ht:N\l_@@_buffer_box
+\box_dp:N\l_@@_buffer_box
}
}
{
% \end{macrocode}
% \textit{Case: not enough space in the current column.} Start a new column and, unless this is a top-level
% entry, insert the appropriate continuation into the \cs{l_@@_buffer_box}.
% \begin{macrocode}
\@@_new_column:
\int_compare:nNnT{#1}>{0}{
\@@_vbox_prepend:Nn\l_@@_buffer_box{
\@@_make_continuation:n{\l_@@_level_int-1}
}
}
}
% \end{macrocode}
% \cs{l_@@_buffer_box} now contains the material that should be typeset onto the page, and there is enough space in
% the current column to typeset a minimal acceptable portion of it. Typesetting is handled by \cs{@@_set_buffer:},
% which may use \tn{vsplit}, which produces a warning `\texttt{Underfull \tn{vbox} (badness 10000)}' with even a
% \qty{1}{\spoint} mismatch between available breakpoints and desired height. For efficiency, \cs{@@_set_buffer:} uses
% an approximation to the desired height, so set \tn{vbadness} to 10000 to suppress these warnings.
% \begin{macrocode}
\group_begin:
\int_set:Nn\vbadness{10000}
\@@_typeset_buffer:
\group_end:
% \end{macrocode}
% Finally, clear any stored group.
% \begin{macrocode}
\tl_clear:N\l_@@_group_tl
}
% \end{macrocode}
% \end{macro}
%
%
%
% \subsubsection{Filtering cross-references and locations}
%
% In each entry, cross-references and locations may be mixed up and need to be filtered into separate lists.
%
% \begin{macro}{
% \@@_filter_crossref_location_seqs:n
% }
% Use the supplied list of cross-references and location (\param{1}), which is a clist, to populate
% \cs{l_@@_crossref_seq} and \cs{l_@@_location_seq}. The list of macros that are the first tokens in
% cross-references is contained in \cs{l_@@_crossref_macros_tl}. All that is required is to check whether the head
% token in each item in the \param{1} is in \cs{l_@@_crossref_macros_tl}. and assign that item to the correct seq.
% \begin{macrocode}
\cs_new:Npn\@@_filter_crossref_location_seqs:n #1
{
\seq_clear:N\l_@@_crossref_seq
\seq_clear:N\l_@@_location_seq
\clist_map_inline:nn{#1}
{
\tl_if_in:NoTF
\l_@@_crossref_macros_tl{ \tl_head:w ##1 {} \q_stop }
{
\seq_put_right:Nn\l_@@_crossref_seq{##1}
}
{
\seq_put_right:Nn\l_@@_location_seq{##1}
}
}
}
% \end{macrocode}
% \end{macro}
%
%
%
% \subsubsection{Style}
%
% \begin{macro}{
% \@@_set_style:n,
% }
% Set up the style for an index entry at the given level.
% \begin{macrocode}
\cs_new:Npn \@@_set_style:n #1
{
\tl_use:c{l_@@_level_#1_style_tl}
}
% \end{macrocode}
% \end{macro}
%
%
%
% \subsubsection{Typesetting keywords}
%
% \begin{macro}{
% \indextrakeyword
% }
% Take a level (\param{1}) and a keyword (\param{2}) and return a (possibly styled) keyword.
% \begin{macrocode}
\cs_new:Npn\indextrakeyword #1#2
{
#2
}
% \end{macrocode}
% \end{macro}
%
%
%
% \subsubsection{Typesetting cross-references}
%
% \begin{macro}{
% \@@_typeset_between:
% }
% Typeset everything between the keyword and the locations. If there are no cross-references, this means typesetting
% just the keyword--location separator; otherwise, it means typesetting the cross-references with the relevant
% separators before, after, and between.
% \begin{macrocode}
\cs_new:Npn\@@_typeset_between:
{
\seq_if_empty:NTF\l_@@_crossref_seq
{
\tl_use:N\l_@@_separator_kw_loc_tl
}
{
\tl_use:N\l_@@_separator_kw_cr_tl
\seq_use:Nn
\l_@@_crossref_seq
{ \tl_use:N\l_@@_separator_cr_cr_tl }
\seq_if_empty:NF\l_@@_location_seq
{ \tl_use:N\l_@@_separator_cr_loc_tl }
}
}
% \end{macrocode}
% \end{macro}
%
%
%
% \subsubsection{Typesetting locations}
%
% \begin{variable}{
% \l_@@_first_item_bool,
% }
% Boolean variable to track whether the current location is the first one in the entry, so that a separator can be
% inserted before every non-first location.
% \begin{macrocode}
\bool_new:N\l_@@_first_item_bool
% \end{macrocode}
% \end{variable}
%
% \begin{macro}{
% \@@_typeset_locations:
% }
% Typeset locations stored in \cs{l_@@_locations_seq}. Using \cs{seq_use:Nn} is not enough, because each entry must be
% processed separately. Thus separators must be inserted `manually'.
% \begin{macrocode}
\cs_new:Npn\@@_typeset_locations:
{
\bool_set_true:N\l_@@_first_item_bool
\seq_map_inline:Nn\l_@@_location_seq
{
\bool_if:nF{\l_@@_first_item_bool}
{ \tl_use:N\l_@@_separator_loc_loc_tl }
\@@_typeset_aux_location:n{##1}
\bool_set_false:N\l_@@_first_item_bool
}
}
% \end{macrocode}
% \end{macro}
%
% \begin{macro}{
% \@@_typeset_first location:
% }
% Typeset the first location stored in \cs{l_@@_locations_seq}.
% \begin{macrocode}
\cs_new:Npn\@@_typeset_first_location:
{
\exp_args:Ne\@@_typeset_aux_location:n
{\seq_item:Nn\l_@@_location_seq{1}}
}
% \end{macrocode}
% \end{macro}
%
% \begin{macro}{
% \@@_is_nonrange_p:w
% }
% To be called in the form \cs{@@_is_nonrange_p:w}\meta{parameter}\ttdashdash\cs{q_stop}; uses \TeX\ parsing to check
% whether \meta{parameter} does not contain a range marker \ttdashdash.
% \begin{macrocode}
\cs_new:Npn\@@_is_nonrange_p:w #1--#2\q_stop
{
\tl_if_empty_p:n{#2}
}
% \end{macrocode}
% \end{macro}
%
% \begin{macro}{
% \cs_new:Npn\@@_typeset_ist_location:n
% }
% Typeset a \MakeIndex- or \upmendex-style location. The location might be a
% \begin{itemize}
% \item a single page;
% \item an encapsulated single page \cs{encapsulation}\mcode{\{}\meta{page}\mcode{\}};
% \item a range; or
% \item an encapsulated range \cs{encapsulation}\mcode{\{}\meta{start}\ttdashdash\meta{end}\mcode{\}}.
% \end{itemize}
% \begin{macrocode}
\cs_new:Npn\@@_typeset_ist_location:n #1
{
% \end{macrocode}
% Check for an encapsulation (a leading control sequence, comparing catcode with \cs{prg_do_nothing:} simply as a
% convenience). Either call \cs{@@_typeset_ist_encap_page_or_range:Nn} with this encapsulation or with a `do-nothing'
% encapsulation and the braced parameter.
% \begin{macrocode}
\tl_if_head_eq_catcode:nNTF{#1}\prg_do_nothing:
{
\@@_typeset_ist_encap_page_or_range:Nn #1
}
{
\@@_typeset_ist_encap_page_or_range:Nn \prg_do_nothing:{#1}
}
}
% \end{macrocode}
% \end{macro}
%
% \begin{macro}{
% \@@_typeset_ist_encap_page_or_range:Nn
% }
% Take an encapsulation and a parameter and typeset the parameter as a page or range, as appropriate.
% \begin{macrocode}
\cs_new:Npn\@@_typeset_ist_encap_page_or_range:Nn #1#2
{
\bool_if:nTF{\@@_is_nonrange_p:w #2--\q_stop}
{
% \end{macrocode}
% \textit{Case: not a range.} Parameter \param{2} a single page.
% \begin{macrocode}
\indextrapage{#1}{#2}
}
{
% \end{macrocode}
% \textit{Case: range.} Parameter \param{2} is a range. Call \cs{@@_typeset_ist_encap_range:w} to parse and
% typeset it.
% \begin{macrocode}
\@@_typeset_ist_encap_range:w#1\q_mark #2\q_stop
}
}
% \end{macrocode}
% \end{macro}
%
% \begin{macro}{
% \@@_typeset_ist_encap_range:w
% }
% This is effectively just a helper macro so that \TeX\ parsing can be used to convert the parameters into the form
% required by \cs{indextrarange}.
% \begin{macrocode}
\cs_new:Npn\@@_typeset_ist_encap_range:w #1\q_mark #2--#3\q_stop
{
\indextrarange{#1}{#2}{#3}
}
% \end{macrocode}
% \end{macro}
%
% \begin{macro}{
% \cs_new:Npn\@@_typeset_xdy_location:n
% }
% Typeset a \xindy-style location. The location might be
% \begin{itemize}
% \item a single page;
% \item an encapsulated single page \cs{encapsulation}\mcode{\{}\meta{page}\mcode{\}};
% \item a range; or
% \item an encapsulated range \cs{encapsulation}\mcode{\{}\meta{start}\mcode{\}}\ttdashdash\cs{encapsulation}\mcode{\{}\meta{end}\mcode{\}}.
% \end{itemize}
% \begin{macrocode}
\cs_new:Npn\@@_typeset_xdy_location:n #1
{
\bool_if:nTF{\@@_is_nonrange_p:w #1--\q_stop}
{
% \end{macrocode}
% \textit{Case: not a range.} Check for an encapsulation (a leading control sequence, comparing catcode with
% \cs{prg_do_nothing:} simply as a convenience). Either call \cs{@@_typeset_ist_encap_page_or_range:Nn} with this
% encapsulation or with a `do-nothing' encapsulation and the braced parameter.
% \begin{macrocode}
\tl_if_head_eq_catcode:nNTF{#1}\prg_do_nothing:
{
\indextrapage #1
}
{
\indextrapage \prg_do_nothing:{#1}
}
}
{
% \end{macrocode}
% \textit{Case: range.}
% \begin{macrocode}
\@@_typeset_xdy_range:w #1\q_stop
}
}
% \end{macrocode}
% \end{macro}
%
% \begin{macro}{
% \@@_typeset_xdy_range:w
% }
% To be called in the form \cs{@@_typeset_xdy_range:w}\meta{parameter}\cs{q_stop}, so that \param{1} and \param{2}
% will be the start and end of the range, possibly with encapsulations. Check \param{1} for a leading control
% sequence. If it exists, assume the same holds for \param{2}, and the parameters are of the form
% \cs{encapsulation}\texttt{\{}\meta{start}\texttt{\}} and \cs{encapsulation}\texttt{\{}\meta{end}\texttt{\}} and can
% be passed to \cs{@@_typeset_xdy_encap_range:w}. Otherwise, each parameter is a page, so call \cs{indextrarange} with
% `do-nothing' encapsulations and braced parameters.
% \begin{macrocode}
\cs_new:Npn\@@_typeset_xdy_range:w #1--#2\q_stop
{
\tl_if_head_eq_catcode:nNTF{#1}\prg_do_nothing:
{
\@@_typeset_xdy_encap_range:NnNn #1#2
}
{
\indextrarange\prg_do_nothing:{#1}{#2}
}
}
% \end{macrocode}
% \end{macro}
%
% \begin{macro}{
% \@@_typeset_xdy_encap_range:NnNn
% }
% This is effectively just a helper macro so that \TeX\ parsing can be used to convert the parameters into the form
% required by \cs{indextrarange}.
% \begin{macrocode}
\cs_new:Npn\@@_typeset_xdy_encap_range:NnNn #1#2#3#4
{
\indextrarange{#1}{#2}{#4}
}
% \end{macrocode}
% \end{macro}
%
%
%
% \begin{macro}{
% \@@_page_basic:nn,
% \@@_range_basic:nnn,
% \@@_page_hyperref:nn,
% \@@_range_hyperref:nnn,
% }
% Default macros for typesetting a page and a range, depending on whether \pkg{hyperref} is loaded.
% \begin{macrocode}
\cs_new:Npn\@@_page_basic:nn #1#2
{
#1{#2}
}
\cs_new:Npn\@@_range_basic:nnn #1#2#3
{
#1{#2}--#1{#3}
}
\cs_new:Npn\@@_page_hyperref:nn #1#2
{
#1{\hyperpage{#2}}
}
\cs_new:Npn\@@_range_hyperref:nnn #1#2#3
{
#1{\hyperpage{#2}}--#1{\hyperpage{#3}}
}
% \end{macrocode}
% \end{macro}
%
% Set \cs{indextrapage} and \cs{indextrarange} to the `basic' versions of the above macros. They may be set to the
% `hyperref' versions at the start of the \env{theindextra} environment depending on user settings.
% \begin{macrocode}
\cs_set_eq:NN\indextrapage\@@_page_basic:nn
\cs_set_eq:NN\indextrarange\@@_range_basic:nnn
% \end{macrocode}
%
%
% \subsection{Continuations}
%
% \begin{macro}{
% \@@_make_continuation:n
% }
% Return a continuation text for the level specified in \param{1}, indicating that this (and higher) levels are
% continued from the previous column. The continuation text is created using the stored keywords with
% \cs{indextramakecontinuation} applied to each.
% \begin{macrocode}
\cs_new:Npn\@@_make_continuation:n #1
{
\int_step_inline:nnn{0}{#1}{
\group_begin:
\@@_set_style:n{##1}
\leavevmode\strut
\indextramakecontinuation{##1}{\tl_use:c{l_@@_saved_keyword_##1}}
\strut\par
\group_end:
}
}
% \end{macrocode}
% \end{macro}
%
% \begin{macro}{
% \indextramakecontinuation
% }
% Take a level (\param{1}) and a keyword (\param{2}) and return a continuation text.
% \begin{macrocode}
\cs_new:Npn\indextramakecontinuation #1#2
{
#2~(cont.)
}
% \end{macrocode}
% \end{macro}
%
%
%
% \subsection{Marks}
%
% Define a new mark class for use by \pkg{indextra}.
% \begin{macrocode}
\mark_new_class:n{indextra}
% \end{macrocode}
%
% \begin{macro}{
% \@@_mark_insert:
% }
% Insert the top-level saved keyword as a mark.
% \begin{macrocode}
\cs_new:Npn\@@_mark_insert:
{
\mark_insert:nn{indextra}{\tl_use:c{l_@@_saved_keyword_0}}
}
% \end{macrocode}
% \end{macro}
%
% \begin{macro}{
% \indextramakemark
% }
% Macro to process an \pkg{indextra} mark for use. Any mark retrieved by \cs{indextrafirstmark} or
% \cs{indextralastmark} will have \cs{indextramakemark} applied.
% \begin{macrocode}
\cs_new:Npn\indextramakemark #1
{
#1
}
% \end{macrocode}
% \end{macro}
%
% \begin{macro}{
% \indextrafirstmark,
% \indextralastmark,
% }
% Retrieve the first and last \pkg{indextra} marks on the page, where `first' and `last' have their standard \LaTeX\
% meanings. The marks will be processed by \cs{indextramakemark}.
% \begin{macrocode}
\cs_new:Npn\indextrafirstmark
{
\indextramakemark{ \mark_use_first:nn{page}{indextra} }
}
\cs_new:Npn\indextralastmark
{
\indextramakemark{ \mark_use_last:nn{page}{indextra} }
}
% \end{macrocode}
% \end{macro}
%
%
%
% \subsection{Buffer}
%
% \begin{variable}{
% \l_@@_buffer_box,
% }
% Box variable to hold remaining material to be typeset for the current index entry, sub-entry, or sub-sub-entry.
% \begin{macrocode}
\box_new:N\l_@@_buffer_box
% \end{macrocode}
% \end{variable}
%
% \begin{macro}{
% \@@_typeset_buffer:
% }
% Output material that has been typeset into \cs{l_@@_buffer_box} and update \cs{g_@@_remaining_space_dim} as
% necessary. If necessary, split off as much material as will fit in the current column from \cs{l_@@_buffer_box},
% typeset it, add continuation text to the top of \cs{l_@@_buffer_box}, then recursively call this macro. The
% recursion ends when all material in \cs{l_@@_buffer_box} has been output.
% \begin{macrocode}
\cs_new:Npn\@@_typeset_buffer:
{
% \end{macrocode}
% Insert a mark. This is either on the first call, or a recursive call, in which case the current position is at the
% top of the column. A mark should be inserted in any case.
% \begin{macrocode}
\@@_mark_insert:
% \end{macrocode}
% Check whether it is necessary to split off some material for this column and start a new one. There is no need to
% check about the minimum acceptable split: if necessary, a new column has already been started in \cs{@@_entry:nnn}.
% \begin{macrocode}
\dim_compare:nNnT
{\g_@@_remaining_space_dim}
<
{\box_ht:N\l_@@_buffer_box+\box_dp:N\l_@@_buffer_box}
{
% \end{macrocode}
% \textit{Case: A split is necessary.} Compute an approximation (definitely too large, but acceptably so) to the
% amount to be split off, then split and rebox.
% \begin{macrocode}
\dim_set:Nn
\l_tmpa_dim{\g_@@_remaining_space_dim-.3\baselineskip}
\vbox_set_split_to_ht:NNn
\l_tmpa_box\l_@@_buffer_box{\l_tmpa_dim}
\vbox_set:Nn
\l_tmpa_box{\vbox_unpack_drop:N\l_tmpa_box}
% \end{macrocode}
% Update \cs{g_@@_remaining_space_dim} and output the split material.
% \begin{macrocode}
\dim_gset:Nn\g_@@_remaining_space_dim
{
\g_@@_remaining_space_dim
-\box_ht:N\l_tmpa_box
-\box_dp:N\l_tmpa_box
}
\vbox_unpack_drop:N\l_tmpa_box
% \end{macrocode}
% Add a continuation text to the top of \cs{l_@@_buffer_box}, start a new column, and recurse.
% \begin{macrocode}
\@@_vbox_prepend:Nn
\l_@@_buffer_box
{\@@_make_continuation:n{\l_@@_level_int}}
\@@_new_column:
\@@_typeset_buffer:
}
{
% \end{macrocode}
% \textit{Case: No split is necessary.} Update \cs{g_@@_remaining_space_dim} and output the buffer contents.
% \begin{macrocode}
\dim_gset:Nn\g_@@_remaining_space_dim
{
\g_@@_remaining_space_dim
-\box_ht:N\l_@@_buffer_box
-\box_dp:N\l_@@_buffer_box
}
\vbox_unpack_drop:N\l_@@_buffer_box
}
}
% \end{macrocode}
% \end{macro}
%
%
% \begin{macro}{
% \@@_vbox_prepend
% }
% Takes a vertical box variable as \param{1} and typeset the material in \param{2} into it above the original content.
% \begin{macrocode}
\cs_new:Npn\@@_vbox_prepend:Nn #1#2
{
\vbox_set:Nn #1{
\vbox{#2}
\vbox_unpack_drop:N #1
}
}
% \end{macrocode}
% \end{macro}
%
% \begin{macrocode}
%</package>
% \end{macrocode}
%
%
%
% \subsection{Style files}
%
% \subsubsection{\texorpdfstring{\file{.ist}}{ist} -- \MakeIndex, \upmendex}
%
% \begin{macrocode}
%<*ist>
% \end{macrocode}
%
% \begin{macrocode}
page_precedence "ArRn"
preamble "\\begin{theindextra}\n \\indextrastyleversion{0.1}\n \\indextraprocessortype{ist}\n"
postamble "\n\n\n\\end{theindextra}\n"
group_skip "\n\n\n \\indextraspace"
heading_prefix "\n\n\n \\indextragroup{"
heading_suffix "}\n"
headings_flag 1
item_0 "\n \\indextraentry{0}{"
item_1 "\n \\indextraentry{1}{"
item_01 "\n \\indextraentry{1}{"
item_x1 "}{}\n \\indextraentry{1}{"
item_2 "\n \\indextraentry{2}{"
item_12 "\n \\indextraentry{2}{"
item_x2 "}{}\n \\indextraentry{2}{"
delim_0 "}{"
delim_1 "}{"
delim_2 "}{"
delim_t "}"
encap_prefix "\\"
encap_infix "{"
encap_suffix "}"
% \end{macrocode}
%
% \begin{macrocode}
%</ist>
% \end{macrocode}
%
%
%
% \subsubsection{\texorpdfstring{\file{.xdy}}{xdy} -- \xindy}
%
% \begin{macrocode}
%<*xdy>
% \end{macrocode}
%
% \begin{macrocode}
(define-attributes (("textit" "defterm")))
(markup-index :open "\begin{theindextra}~n \indextrastyleversion{0.1}~n \indextraprocessortype{xdy}~n"
:close "~n~n\end{theindextra}~n"
:tree)
(markup-letter-group-list :sep "~n \indextraspace~n")
(markup-letter-group :open-head "~n % "
:close-head "~n"
:group "default")
(markup-letter-group :open-head "~n \indextragroup{"
:close-head "}~n~n")
(markup-indexentry :open " \indextraentry{0}{"
:close "}%~n"
:depth 0)
(markup-indexentry :open "}%~n \indextraentry{1}{"
:close ""
:depth 1)
(markup-indexentry :open "}%~n \indextraentry{2}{"
:close ""
:depth 2)
(markup-keyword-list :open "" :close "}{" :sep ";")
(markup-locclass-list :open "" :sep ", " :close "")
(markup-locref-list :open "" :sep ", " :close "")
(markup-range :sep "--")
(markup-locref :open "\textit{" :close "}" :attr "textit")
(markup-locref :open "\defterm{" :close "}" :attr "defterm")
(markup-crossref-list :class "see"
:open "\see{"
:sep "}{}, \see{"
:close "}{}")
(markup-crossref-list :class "seealso"
:open "\seealso{"
:sep "}{}, \seealso{"
:close "}{}")
% \end{macrocode}
%
% \begin{macrocode}
%</xdy>
% \end{macrocode}
%
% \end{implementation}
%
% \PrintIndex
%
%
%
% \iffalse
%<*metadriver>
\input{indextra.dtx}
%</metadriver>
%
%<*demo>
\documentclass{article}
\usepackage[
paperwidth=105mm,
paperheight=100mm,
inner=5mm,
width=90mm,
height=90mm,
top=5mm,
nohead,
nofoot,
columnsep=5mm,
twocolumn,
]{geometry}
\usepackage{xcolor}
\definecolor{bg}{gray}{0.9}
\pagecolor{bg}
\parindent=1em
\usepackage{indextra}
\indextrasetup{
before code={},
after code={},
}
\newcommand\see[1]{\textit{see}~`#1'}
\newcommand\seealso[1]{\textit{see also}~`#1'}
\raggedright
\pagestyle{empty}
\begin{document}
\begin{theindextra}
\indextrastyleversion{0.1}
\indextraprocessortype{ist}
\indextraentry{0}{neutron}{855, 862, 885--886}%
\indextraentry{0}{\textit{New Astronomy} (Kepler)}{\see{\textit{Astronomia Nova}}{}}%
\indextraentry{0}{Newtonian physics}{298, 376, 390, 589, 813, 830, 834, 842, 891, 894--895}%
\indextraentry{0}{\textit{Nicomachean Ethics} (Aristotle)}{85}%
\indextraentry{0}{Nim}{11}%
\indextraentry{0}{nine-point circle}{584, 641, 662--663}%
\indextraentry{0}{Nobel Prize}{}%
\indextraentry{1}{chemistry}{495, 566, 815, 865, 937}%
\indextraentry{1}{literature}{485}%
\indextraentry{1}{peace}{865}%
\indextraentry{1}{physics}{502, 598, 727, 834, 836, 838, 851, 853--854, 856, 865, 867, 877, 893, 903, 905, 918, 921}%
\indextraentry{0}{nobility}{188, 240, 250, 464}%
\indextraentry{0}{non-aesthetic property}{700, 715}%
\indextraentry{0}{non-associative algebra}{848}%
\indextraentry{0}{non-commutativity}{643}%
\indextraentry{0}{non-constructive proof}{787}%
\indextraentry{0}{non-determinism}{595}%
\indextraentry{0}{non-euclidean geometry}{380, 401, 404--408, 436, 628, 643, 880, 896}%
\indextraentry{0}{non-linearity}{882}%
\indextraentry{0}{non-measurable set}{672}%
\indextraentry{0}{non-sensory property}{695}%
\indextraentry{0}{non-visual thinking}{633}%
\indextraentry{0}{nonagon}{220}%
\end{theindextra}
\end{document}
% </demo>
% \fi