4

I am using the l3doc class for a write-up the document needs to index both macros as well as normal indices, i.e; cases with normal words not commands.

\documentclass{l3doc}
\usepackage{makeidx}
\def\thepage{\Alph{part}-\arabic{page}}
\usepackage{hyperref}
\begin{document}
\tableofcontents

\part {First Part}
\section{first section}
\subsection{first subsection}
Just a test
\cmd{\chapter}
\index{Book Class>chapter}
\index{chapter design}
\cs{l_tmpa_tl}
\cs{tl_new:N}

\newpage

\part{Second Part}
\cs{l_tmpa_seq}
\cs{seq_new:N}

\printindex

\end{document} 

The l3doc is using Roman letters to force the sorting of l3 functions and variables and this causes an issue with normal indices (see image).

enter image description here

I have added a bounty in order to attract more attention I am simply looking for a macro say Index[options] that can have a similar functionality as index, when using the l3doc class. This to be used for non-command entries. Using \NewDocElement I have macros for everything else, except this. So \Index[module={Gods}]{Greece>Zeus} would print a three level entry and be sorted properly. I know I can use NewDocElement and define custom commands for this, but I want to give this flexibility to the author, as there are so many variations.

13
  • \def\@ywrindex#1{% \protected@write\@indexfile{}% {\string\indexentry{#1}{\thepage}}% \endgroup \@esphack} \def\yindex{\@bsphack\begingroup \@sanitize\@ywrindex} \def\@yindex#1{\endgroup\@esphack} (from latex.ltx)?
    – cfr
    Commented Mar 30 at 7:30
  • @cfr Thanks. I had something similar, which fixes some of the issues,i.e., indexed in roman rather than ttfamily and the levels. Remaining problem is to trick hypdoc and l3doc to provide the right link to the page. I think the solution is to also redefine the hypdoc/hyperref hdpindex to another name |yhdpindex{usage}}{MMMMI-66} and also to find out where the target is inserted and to insert in your code.
    – yannisl
    Commented Mar 30 at 8:46
  • 1
    Yes, but the primary purpose of l3doc is to document the LaTeX 3 project's documentation of LaTeX 3. So doc is designed for flexibility, but l3doc is not.
    – cfr
    Commented Mar 30 at 21:16
  • 1
    @cfr Managed to crack it thus: \def\term#1{{\uwave{\textbf{#1}}}} \NewDocumentCommand\Index{O{term}m} { \yindex{#2 \encapchar hdpindex{#1}} } I will post a bit of explanatory notes in an answer in a few hours. Please also post an answer so I can award the bounty to you. I used uwave to make it look a bit different (ulem package). I am not using it though in my final code.
    – yannisl
    Commented Apr 2 at 5:41
  • 1
    @cfr Maybe over the weekend, I just got too busy the last couple of days.
    – yannisl
    Commented Apr 4 at 14:42

2 Answers 2

1
+100

Methods I and II are the joint antithesis of l3. This seems permissible given that l3doc.cls is not wholeheartedly committed when it comes to indexing, either.

Method I

Method I creates a single index which includes your additional entries in the usage index. This creates hyperlinked entries with the target structure e.g. Gods>Greek>Zeus. I'm not sure what module=Gods is for exactly, so I ignored the module bit, but presumably you can define something to do whatever it is meant to do once you have the basic indexing figured out.

The only requirement is that you use \myindex{<entry>} rather than index{<entry>} for the entries you don't want l3doc to hijack. Obviously, you could use \Index if preferred. I chose to avoid that because the doc package uses CamelCase commands, including for indexing, and I'm pretty sure I would end up confused. Likely you're less easily addled, but I'd recommend at least using \newcommand\Index prior to \def\Index.

\documentclass{l3doc}
\usepackage{makeidx}
\def\thepage{\Alph{part}-\arabic{page}}
% ateb: https://tex.stackexchange.com/a/714572/  addaswyd o gwestiwn yannisl: https://tex.stackexchange.com/q/712156/
\makeatletter
\def\makemyindex{% modified from latex.ltx
  \def\myindex{\@bsphack\begingroup
    \@sanitize
    \@mywrindex}\typeout
  {Writing index file \jobname-my.idx}%
  \let\makemyindex\@empty
}
\@onlypreamble\makemyindex
\def\@mywrindex#1{% ditto
  \protected@write\@indexfile{}%
  {\string\indexentry{#1|hdpindex{usage}}{\thepage}}%
  \endgroup
  \@esphack}
\def\myindex{\@bsphack\begingroup \@sanitize\@myindex}
\def\@myindex#1{\endgroup\@esphack}
\makeatother
\usepackage{bookmark}% optional
\makemyindex
\begin{document}
\tableofcontents

\part {First Part}
\section{first section}
\subsection{first subsection}
Just a test
\cmd{\chapter}
\myindex{Book Class>chapter}
\myindex{chapter design}
\cs{l_tmpa_tl}
\cs{tl_new:N}

\newpage

\part{Second Part}
\cs{l_tmpa_seq}
\cs{seq_new:N}

\myindex{Gods>Greek>Zeus}

\printindex

\end{document}

Method II

This method produces a second index, printed using \printmyindex, with the entries set using \myindex as before. It likewise produces hyperlinked entries with the target structure. The prologue and title are separately configurable.

This method takes an additional write. However, that's probably not a major issue unless you are using glossaries for multiple glossaries. An alternative would be splitidx but I didn't attempt to get l3doc, doc, splitidx and hyperref to play nicely together. I worry l3doc may still be at the parallel play stage ....

Note that \printmyindex is a modified form of \PrintIndex rather than \printindex. This is because I modified the command from doc.sty which uses the former rather than the latter. It also hard codes the title for reasons I'm not entirely clear about. So if the index name causes problems, you might need to hard code it.

\documentclass{l3doc}
\usepackage{makeidx}
\def\thepage{\Alph{part}-\arabic{page}}
\makeatletter
% ateb: https://tex.stackexchange.com/a/714572/  addaswyd o gwestiwn yannisl: https://tex.stackexchange.com/q/712156/
\def\makemyindex{%
  \newwrite\@myindexfile
  \immediate\openout\@myindexfile=\jobname-my.idx
  \def\myindex{\@bsphack\begingroup
    \@sanitize
    \@mywrindex}\typeout
  {Writing index file \jobname-my.idx}%
  \let\makemyindex\@empty
}
\@onlypreamble\makemyindex
\def\@mywrindex#1{%
  \protected@write\@myindexfile{}%
  {\string\indexentry{#1|hdpindex{usage}}{\thepage}}%
  \endgroup
  \@esphack}
\def\myindex{\@bsphack\begingroup \@sanitize\@myindex}
\def\@myindex#1{\endgroup\@esphack}
\def\printmyindex{% modified from doc.sty
  \let\index@prologue@orig\index@prologue
  \let\index@prologue\myindex@prologue
  \@input@{\jobname-my.ind}%
  \let\index@prologue\index@prologue@orig
  \global\let\printmyindex\@empty}
\newcommand\myindex@prologue{%
  \section*{\myindexname}%
  \markboth{\myindexname}{\myindexname}%
  A prefix, prologue, introduction and foreward.%
}
\makeatother
\usepackage{bookmark}
\makemyindex
\newcommand\myindexname{Another Index}
\begin{document}
\tableofcontents

\part {First Part}
\section{first section}
\subsection{first subsection}
Just a test
\cmd{\chapter}
\myindex{Book Class>chapter}
\myindex{chapter design}
\cs{l_tmpa_tl}
\cs{tl_new:N}

\newpage

\part{Second Part}
\cs{l_tmpa_seq}
\cs{seq_new:N}

\myindex{Gods>Greek>Zeus}

\printindex
\printmyindex

\end{document}

[Due to an Okular bug, no images are provided. The first should show the integrated index; the second shows 'Index' with the standard prologue followed by 'Another Index' with the alternate prologue.]

4
  • Thanks. About the Index, in my code I normally keep the convention, doc<Name>, i.e., docIndex. Indexes as well as writes the<Name>, docIndex* only writes the name no index; idx<Name> only indexes. Also regarding the text in level1 in the index I always use uppercase first letter only (like in section titles). I also hear you on hardcoded names and agree totally.
    – yannisl
    Commented Apr 2 at 6:24
  • I kep the Index in the OP, so as not to change the original question.
    – yannisl
    Commented Apr 2 at 6:25
  • @yannisl It's not really the capitalisation: it's that doc already has Indexs everywhere ;).
    – cfr
    Commented Apr 2 at 6:26
  • Very true, and very confusing to be honest.
    – yannisl
    Commented Apr 2 at 6:28
0

To address the issue with the sorting of normal indices caused by the Roman letter numbering used for the l3 functions and variables, you can modify the way page numbering is handled. Instead of redefining \thepage, you can customize the \pagenumbering command to achieve your desired numbering style only for the l3 functions and variables.

5
  • 1
    The Roman numbering is inserted by l3doc so the sorting of entries marked by (usage) is in a different place than those by codeline. See in l3 code ` Remove R so I is treated in sequence I J K not I II III page_precedence "rnaA"`
    – yannisl
    Commented Apr 2 at 2:09
  • [@yannisl] And the real issue here, as I understand it, is that l3doc hijacks \@wrindex in a way which makes it difficult to write standard entries to the index at all. With just doc version 3 (e.g. in ltxdoc), for example, you don't have the same problem because \@wrindex is still available and you can write what you want. But l3doc is intended to be used for documentation with indices in a specific, standard form, so the need for that kind of flexibility doesn't seem to have been expected.
    – cfr
    Commented Apr 2 at 4:10
  • As it’s currently written, your answer is unclear. Please edit to add additional details that will help others understand how this addresses the question asked. You can find more information on how to write good answers in the help center.
    – Community Bot
    Commented Apr 2 at 5:59
  • @cfr True l3 did not expect this type of flexibility. However I have at least two package written in expl3 language, one managing unicode scripts, that I need to have this flexibility. Another one provides color palettes and I index the color names including a little box with the color. doc v3, solved the problem partially with the NewDocElement.
    – yannisl
    Commented Apr 2 at 6:32
  • @yannisl Yes, but you don't have to use l3doc. ltxdoc and doc v3 (or, even, v2 with doctools) is rather more flexible. And yes, NewDocElement is good, but I wish v3 hadn't broken old code!
    – cfr
    Commented Apr 2 at 6:37

You must log in to answer this question.

Not the answer you're looking for? Browse other questions tagged .