l3doc fügt unerwünschten Backslash in das Randfeld von {function} ein

Question

Ich verwende es l3doczur Dokumentation einiger Pakete (ich weiß, dass es nicht offiziell stabil ist, aber es gefällt mir …). Ich bin auf das Problem gestoßen, dass {function}{<list>}für jedes Element ein Backslash hinzugefügt wird, <list>wenn eines der Elemente ein Makro ist, das mit einem Backslash beginnt.

\documentclass{l3doc}

\begin{document}

\begin{function}{{environment}}
Description
\end{function}
\begin{function}{\command}
Description
\end{function}
\begin{variable}{counter}
Description
\end{variable}
\begin{function}{{environmentII}, counterII, \commandII}
Description for multiple items
\end{function}

\begin{macro}{{environment}}
Definition
\end{macro}
\begin{macro}{\command}
Definition
\end{macro}
\begin{macro}{counter}
Definition
\end{macro}
\begin{macro}{{environmentII}, counterII, \commandII}
Description for multiple items
\end{macro}

\end{document}

Das Beispiel zeigt, dass die Verwendung eines einzelnen Elements <list>wie erwartet funktioniert, aber sobald ich ein Makro zur Liste hinzufüge, werden alle Elementemit umgekehrtem Schrägstrich. {macro}zeigt dieses Verhalten nicht …

Gibt es eine Möglichkeit, dies zu verhindern?

Answer 1

Mir scheint, Sie missbrauchen die Umgebung einfach. Das erwartete Argument ist entweder eine Funktion oder eine Liste von Funktionen. Aber keines der Elemente in der Liste, die Sie übergeben, ist eine Funktion im Sinne von l3. (Aber die UmgebungMaiauch für Befehle auf Dokumentebene gedacht sein - siehe unten. In diesem Fallmancheder Dinge, die Sie übergeben, sind Funktionen, andere jedoch nicht.)

Beachten Sie, dass Sie selbst in den Fällen, in denen Sie sagen, dass es wie erwartet funktioniert, keine konsistent formatierten Elemente erhalten. Beispielsweise erhalten Sie countereine Formatierung in Serifenschrift – nicht in Schreibmaschinenschrift –, da es für den Parser nicht wie eine Variable aussieht. ( \l_tobi_counter_intwürde hier vermutlich funktionieren und ist das L3-Äquivalent.)

Der Code, der die verschiedenen Umgebungen definiert, die vonl3docverarbeitet die Argumente entsprechend der erwarteten Syntax für die Arten von Dingen, die die Umgebung dokumentieren soll.

functionSo sucht die Umgebung beispielsweise :in jedem Element der kommagetrennten Liste nach dem , um den Namen von der Spezifikation seiner Argumente zu trennen. Diese Information wird dann automatisch verarbeitet und standardmäßig formatiert.

Zum Beispiel,

\begin{function}{\Tobi_function_one:nn, \Tobi_function_one:Vn, \Tobi_function_one:VV}
Description for multiple items
\end{function}

erkennt, dass es sich um drei Varianten derselben Funktion handelt, d. h. Fälle, in denen Varianten der Basisfunktion auf die übliche Weise generiert wurden. Anschließend formatiert es die erste als Basisvariante und die beiden anderen als Varianten, kombiniert sie und unterscheidet ihre unterschiedlichen Argumentspezifizierer.

Eine durch Kommas getrennte Liste ist für Fälle gedacht, in denen die aufgelisteten Elemente geringfügige Variationen eines Themas sind, z. B. dieselbe Funktion mit unterschiedlichen Argumentspezifikationen oder eine Art Variantenform. Eine Umgebung, ein Zähler und ein Makro sind jedoch nicht von dieser Art und sollten nicht auf diese Weise gruppiert werden.

Ich bin mir nicht ganz sicher, wofür ich es macroverwenden soll. Ich kann nicht viel Dokumentation finden fürl3docund ich konnte aus der Quelle der Dokumentation für L3 nicht herausfinden, was genau der Unterschied sein soll.

Mein erster Gedanke war, dass dies macrofür Befehle auf Dokumentebene gedacht sein könnte, aber trotz allem, was ich oben gesagt habe,xparseDie Dokumentation von verwendet functionBefehle auf Dokumentebene. Das ist für mich verwirrend, weil ich nicht dachte, dass diese BefehleFunktionenüberhaupt. Ich dachte, dies sei Teil der Idee, Dinge auf Dokumentebene von Dingen auf niedrigerer Ebene (L3) zu unterscheiden, und dass „Funktionen“ nur auf Letzteres zutreffen. Aber da irre ich mich offensichtlich. (Und das macrowürde natürlich auch nicht unbedingt viel Sinn ergeben, da Funktionen sicherlich Makros sind.)

Hier ist der Beispielcode, mit dem ich gespielt habe.

\documentclass{l3doc}
\begin{document}
\begin{function}{\Tobi_function_prior:n}
  Description
\end{function}
\begin{function}{\command:}
  Description
\end{function}
\begin{variable}{\l_Tobi_variable_tl}
  Description
\end{variable}
\begin{function}{\Tobi_function_one:nn, \Tobi_function_one:Vn, \Tobi_function_one:VV}
  Description for multiple items
\end{function}
\begin{function}{\TobiDocumentCommand}
  \begin{syntax}
    \cs{TobiDocumentCommand}\marg{mandatory argument}
  \end{syntax}
\end{function}
\end{document}