☰

Problema de índice ao usar l3doc para escrita de documentos LaTeX

tag-icon • tag-icon indexing latex3 documentation
Problema de índice ao usar l3doc para escrita de documentos LaTeX

Eu uso l3docpara escrever documentos para o meu pacote. No documento preciso descrever macros, ambientes e opções do pacote. Comecei a usar functionapenas o ambiente. Depois que veio a dica do @egreg (Obrigado!), encontrei o ambiente environment. Como não encontrei o documento para l3doc. Eu encontro mais problemas. Aqui está um exemplo:

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

Eu compilo usando o comando abaixo:

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

O resultado é assim: resultado

Existem vários problemas:

  1. Você pode ver que a entrada envse repete duas vezes.
  2. O número da página da entrada envestá errado.
  3. A entrada optdeve ser indexada em Ovez de P. Como é uma opção e não um ambiente, não posso usar environment. Eu preciso de syntax.

Obrigado por qualquer ajuda.

Responder1

O problema é que isso l3docé algo interno ao projeto e não é realmente o que consideramos estável ou devidamente documentado --- em resumo, é um monte de hacks e complementos para documentação que experimentamos e achamos úteis para nossas próprias coisas, mas nunca consegui finalizar e escrever uma documentação adequada para isso.

Você pode acessar a documentação que está lá, por meio da composição, l3doc.dtxmas verá o que quero dizer: nem tudo está documentado na interface do usuário e o código está praticamente sem comentários ou informações adicionais. No entanto, isso pode fornecer algumas informações extras, mas esteja ciente de que podemos alterar ou adicionar informações a essas interfaces.

Quanto às questões acima: l3doc.istteve/teve um bug ao definir levelchar como, #no entanto, o código ainda está assumindo um levelchar de >. Internamente paramos de usar l3doc.iste passamos a usar gind.ista distribuição LaTeX2e. Se você usar isso, ou corrigir o levelchar, l3doc.istverá a enventrada saindo corretamente, ainda haverá 2 entradas, mas uma será uma subentrada sob o título principal "ambientes".

Quanto ao problema com opt: você usa, functionmas esse é apenas para comandos e simplesmente remove o primeiro caractere para fins de classificação, assumindo que seja uma barra invertida; portanto, sua entrada é classificada no segundo caractere, que é "p". Você está sem sorte, não temos um ambiente para documentar opções.

No momento há \DescribeOptioncomando, mas isso é tudo e não temos certeza se este sobreviverá a versões posteriores.

Atualizar

Acabei de perceber que não respondi à segunda pergunta: "Por que está envmostrando o número de página" 1 "em vez de 2?"

Bem, não é, está mostrando um número de linha de código 1 (dígito vertical) e não um número de página usando a docconvenção de pacote padrão. Em outras palavras, isso foi concebido como um ambiente de documentação de código e não como um ambiente de descrição de interface de usuário.

Basicamente, uma falha (se não um bug) que nos leva de volta ao ponto de que este não é realmente um produto acabado... mas fica claro que provavelmente deveríamos fazer algo a respeito.

informação relacionada