Gerar documentação de pacotes

Estamos diante de uma gama de provisões “normais”, além de várias esquisitices. Deve-se notar que a documentação de muitos pacotes está disponível no CTAN, sem a necessidade de mais esforços por parte do usuário — usualmente, é possível navegar in situ por tal documentação.

Contudo, se você encontrar um pacote que não ofereça documentação no acervo, ou se você precisar da documentação em um formato diferente do oferecido pelo acervo, geralmente você mesmo pode gerar a documentação a partir do que você baixar do acervo.

O mecanismo padrão para pacotes LaTeX é simplesmente executar o LaTeX no arquivo package.dtx como você faria para qualquer arquivo LaTeX comum (ou seja, repetidamente até que as advertências desaparecem).

Uma variante é aquela em que o processo de descompactação fornece um arquivo package.drv; se tal coisa aparecer, processe-a preferencialmente em relação ao package.dtx (parece que, quando o mecanismo de fonte documentada LaTeX foi discutido pela primeira vez, o mecanismo de .drv sugerido, mas hoje em dia ele não é muito utilizado).

Algumas vezes, o LaTeX vai reclamar que não consegue encontrar o package.ind (o índice da linha de código) e/ou package.gls (a lista de registros de alterações, não um glossário, como você poderia imaginar). Ambos os tipos de arquivo são processados com arquivos de estilo makeindex especiais; os comandos apropriados são:

makeindex -s gind package
makeindex -s gglo -o package.gls package.glo

Este autor acha que o segundo (o registro de alterações) é, geralmente, de utilidade limitada durante a leitura da documentação do pacote; no entanto, é valioso se você faz parte da equipe de desenvolvimento do pacote. Se você achar que não precisa, basta deixar de lado esse passo.

Outra “pegadinha” comum (e razoável) realizada pelos autores de pacotes é fornecer um arquivo separado package-doc.tex ou simplesmente manual manual.tex; se o arquivo package.dtx não ajudar, simplesmente procure por essas alternativas. Os arquivos são tratados da mesma forma que qualquer arquivo LaTeX “normal”.

This question on the Web: http://latex.net.br/faq/FAQ-install-doc.html