l3doc agrega una barra invertida no deseada en el cuadro de margen de {función}

Question

Lo estoy usando l3docpara documentar algunos paquetes (sé que no es oficialmente estable, pero me gusta…). Llegué al problema que {function}{<list>}agrega una barra invertida para cada elemento <list>si uno de los elementos es una macro que comienza con una barra invertida.

\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}

El ejemplo muestra que usar un solo elemento <list>funciona como se esperaba, pero tan pronto como agrego una macro a la lista, todos los elementos sonbarra invertida. {macro}no muestra este comportamiento...

¿Hay alguna manera de prevenir esto?

Answer 1

Me parece que simplemente estás haciendo un mal uso del medio ambiente. El argumento esperado es una función o una lista de funciones. Pero ninguno de los elementos de la lista que pasa es una función en el sentido de l3. (Pero el medio ambientepuedeTambién debe estar destinado a comandos a nivel de documento; consulte a continuación. En ese caso,algunode las cosas que estás pasando son funciones, pero no otras).

Tenga en cuenta que incluso en los casos en los que dice que funciona como se esperaba, no obtiene elementos formateados de manera consistente. Por ejemplo, se le da counterformato en fuente serif, no en máquina de escribir, porque no parece una variable para el analizador. ( \l_tobi_counter_intpresumiblemente funcionaría aquí y es el equivalente a l3).

El código que define los distintos entornos proporcionados porl3docprocesa los argumentos de acuerdo con la sintaxis esperada para los tipos de cosas que el entorno pretende documentar.

Entonces, por ejemplo, el functionentorno busca :en cada elemento de la lista separada por comas para separar el nombre de la especificación de sus argumentos. Luego, esta información se procesa y formatea automáticamente de forma estándar.

Por ejemplo,

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

detectará que se trata de tres variantes de la misma función, es decir, casos en los que se han generado variantes de la función base de la forma habitual. Luego formateará la primera como variante básica y las dos restantes como variantes, combinándolas y distinguiendo sus diferentes especificadores de argumentos.

Una lista separada por comas está pensada para casos en los que los elementos enumerados son variaciones menores de un tema, por ejemplo, la misma función con diferentes especificaciones de argumentos o una forma variante de algún tipo. Pero un entorno, un contador y una macro no son de este tipo y no deberían agruparse de esta manera.

No estoy del todo seguro de macropara qué debería usarse. No puedo encontrar mucha documentación paral3docy no he podido descifrar en la fuente de la documentación de l3 cuál se supone que es exactamente la distinción.

Lo primero que pensé fue que macropodría estar destinado a comandos a nivel de documento pero, a pesar de lo que dije anteriormente,xparseLa documentación se utiliza functionpara documentar comandos a nivel de documento. Esto me confunde porque no pensé que estos comandos fueranfuncionesen absoluto. Pensé que esto era parte de la idea de distinguir el material a nivel de documento del material l3 de nivel inferior, y que las "funciones" se aplicaban sólo a este último. Pero obviamente estoy equivocado en esto. (Y, por supuesto, macrotampoco tendría necesariamente mucho sentido, ya que las funciones son ciertamente macros).

Aquí está el código de ejemplo con el que estaba jugando.

\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}