l3doc adiciona barra invertida indesejada na caixa de margem de {function}

Question

Estou usando l3docpara documentar alguns pacotes (sei que não é oficialmente estável, mas gosto…). Cheguei ao problema que {function}{<list>}adiciona uma barra invertida para cada item <list>se um dos itens for uma macro começando com uma 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}

O exemplo mostra que usar um único item <list>funciona conforme o esperado, mas assim que adiciono uma macro à lista, todos os itens sãobarra invertida. {macro}não apresenta esse comportamento…

Há uma maneira de prevenir isto?

Answer 1

Parece-me que você está simplesmente fazendo mau uso do meio ambiente. O argumento esperado é uma função ou uma lista de funções. Mas nenhum dos elementos da lista que você passa é uma função no sentido de l3. (Mas o ambientepoderiadestina-se também a comandos em nível de documento - veja abaixo. Nesse caso,algunsdas coisas que você está passando são funções, mas não outras.)

Observe que mesmo nos casos em que você diz que funciona conforme o esperado, você não obtém itens formatados de forma consistente. Por exemplo, você é counterformatado em fonte serifada - não em máquina de escrever - porque não parece uma variável para o analisador. ( \l_tobi_counter_intpresumivelmente funcionaria aqui e é o equivalente a l3.)

O código que define os vários ambientes fornecidos pelol3docprocessa os argumentos de acordo com a sintaxe esperada para os tipos de coisas que o ambiente pretende documentar.

Assim, por exemplo, o functionambiente procura :em cada elemento da lista separada por vírgulas para separar o nome da especificação de seus argumentos. Essas informações são então automaticamente processadas e formatadas de maneira padrão.

Por exemplo,

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

detectará que está lidando com três variantes da mesma função, ou seja, casos onde variantes da função base foram geradas da maneira usual. Em seguida, formatará a primeira como variante básica e as duas restantes como variantes, combinando-as e distinguindo seus diferentes especificadores de argumento.

Uma lista separada por vírgulas destina-se a casos onde os itens listados são pequenas variações de um tema, por exemplo, a mesma função com especificações de argumentos diferentes ou uma forma variante de algum tipo. Mas um ambiente, um contador e uma macro não são deste tipo e não devem ser agrupados desta forma.

Não tenho certeza do que macrodeve ser usado. Não consigo encontrar muita documentação paral3doce não consegui descobrir na fonte da documentação do l3 qual deveria ser exatamente a distinção.

Meu primeiro pensamento foi que isso macropoderia ser destinado a comandos em nível de documento, mas, apesar do que eu disse acima,xparseA documentação do usa functionpara documentar comandos em nível de documento. Isso é confuso para mim porque não pensei que esses comandos fossemfunçõesde forma alguma. Achei que isso fazia parte da ideia de distinguir coisas de nível de documento das coisas de nível inferior l3, e que 'funções' se aplicavam apenas a estas últimas. Mas estou obviamente enganado sobre isso. (E, claro, macrotambém não faria muito sentido, já que funções são certamente macros.)

Aqui está o código de exemplo com o qual eu estava brincando.

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