☰

Indexproblem bei Verwendung von l3doc zum Schreiben von LaTeX-Dokumenten

tag-icon • tag-icon indexing latex3 documentation
Indexproblem bei Verwendung von l3doc zum Schreiben von LaTeX-Dokumenten

Normalerweise schreibe ich l3docDokumente für mein Paket. In den Dokumenten muss ich Makros, Umgebungen und Optionen des Pakets beschreiben. Ich habe angefangen, functionnur die Umgebung zu verwenden. Nach dem Tipp von @egreg (danke!) habe ich die Umgebung gefunden environment. Da ich das Dokument für nicht gefunden habe l3doc, stoße ich auf weitere Probleme. Hier ist ein Beispiel:

\documentclass{l3doc}
\usepackage{lipsum} % to generate some text

\begin{document}

\lipsum

\begin{function}{\macro}
this is a macro.
\end{function}

\begin{environment}{env}
this is an env.
\end{environment}

\begin{function}{opt}
\begin{syntax}
    opt = \meta{a}
\end{syntax}
this is an opt.
\end{function}

\PrintIndex

\end{document}

Ich kompiliere es mit dem folgenden Befehl:

pdflatex example
makeindex -s l3doc.ist example
pdflatex example
pdflatex example

Das Ergebnis sieht wie folgt aus: Ergebnis

Es gibt mehrere Probleme:

  1. Sie sehen, dass der Eintrag envzweimal wiederholt wird.
  2. Die Seitenzahl des Eintrags envist falsch.
  3. Der Eintrag sollte unter und nicht optindiziert werden . Da es sich um eine Option und nicht um eine Umgebung handelt, kann ich nicht verwenden . Ich brauche .OPenvironmentsyntax

Vielen Dank für jede Hilfe.

Antwort1

Das Problem besteht darin, dass es l3docsich eher um ein internes Projekt handelt und nicht das, was wir als stabil oder ordentlich dokumentiert betrachten – kurz gesagt handelt es sich um einen Haufen Hacks und Add-ons zur Dokumentation, mit denen wir experimentiert haben und die wir für unsere eigenen Sachen nützlich fanden, aber nie dazu kamen, eine ordentliche Dokumentation dafür fertigzustellen und zu schreiben.

Sie können die dort vorhandene Dokumentation durch Setzen erreichen, l3doc.dtxaber dann werden Sie verstehen, was ich meine: In der Benutzeroberfläche ist nicht alles dokumentiert und der Code ist größtenteils ohne Kommentare oder zusätzliche Informationen. Trotzdem könnte er Ihnen einige zusätzliche Informationen liefern, aber seien Sie sich bewusst, dass wir diese Schnittstellen ändern oder ergänzen können.

Zu Ihren oben genannten Problemen: l3doc.isthat/hatte einen Fehler, da es levelchar auf gesetzt hat, #der Code jedoch immer noch von einem levelchar von ausgeht >. Intern haben wir die Verwendung eingestellt l3doc.istund verwenden stattdessen gind.istaus der LaTeX2e-Distribution. Wenn Sie dies verwenden oder das levelchar in korrigieren, l3doc.istwerden Sie sehen, dass der envEintrag korrekt ausgegeben wird. Es gibt immer noch 2 Einträge, aber einer ist dann ein Untereintrag unter der Hauptüberschrift „Umgebungen“.

Was das Problem mit betrifft opt: Sie verwenden, functionaber das ist nur für Befehle und entfernt einfach das erste Zeichen zum Sortieren, da angenommen wird, dass es ein Backslash ist; daher wird Ihr Eintrag unter dem zweiten Zeichen sortiert, das "p" ist. Sie haben Pech, wir haben keine Umgebung zum Dokumentieren von Optionen.

Momentan gibt es \DescribeOptionein Kommando, aber das war es auch schon, und wir sind nicht sicher, ob es spätere Versionen überleben wird.

Aktualisieren

Mir ist gerade aufgefallen, dass ich die zweite Frage nicht beantwortet habe: „Warum wird envals Seitenzahl „1“ statt 2 angezeigt?“

Das ist es nicht, es zeigt eine Codezeilennummer von 1 (aufrechte Ziffer) und keine Seitenzahl gemäß der Standardpaketkonvention doc. Mit anderen Worten, dies war als Codedokumentationsumgebung und nicht als Benutzeroberflächenbeschreibungsumgebung gedacht.

Im Grunde ein Mangel (wenn nicht sogar ein Bug), der uns wieder zu dem Punkt bringt, dass dies wirklich kein fertiges Produkt ist … aber es wird klar, dass wir wahrscheinlich etwas dagegen tun sollten.

verwandte Informationen