Documentação de pacotes

Estas FAQs frequentemente sugerem pacotes que vão “solucionar” problemas específicos. Em alguns casos, a resposta fornece uma fórmula para o trabalho. Em outros casos, ou quando a solução requer detalhamento, como o pobre usuário descobre o que fazer?

Se você tiver sorte, o pacote que você precisa já está em sua instalação. Se você tiver muita sorte, você está usando uma distribuição que dá acesso à documentação do pacote e a documentação está disponível de uma forma que pode ser facilmente exibida.

Nas distribuições baseadas em texlive, a ajuda deve estar disponível a partir do comando texdoc como em:

texdoc footmisc

Se o texdoc não puder encontrar nenhuma documentação, ele pode iniciar um navegador da Web para verificar a entrada do pacote no catálogo do CTAN. O catálogo possui uma entrada para documentação de pacote, e a maioria dos autores responde à solicitação de documentação de pacotes da equipe do CTAN, de modo que você frequentemente encontrará documentação dessa maneira.

Nos sistemas MiKTeX, a mesma função é fornecida por mthelp.

Observe que o site texdoc.net fornece acesso à documentação que você teria caso tivesse uma instalação completa do texlive; no site, você pode simplesmente pedir um pacote (como pediria ao texdoc, ou você pode usar o índice de documentação do site para encontrar o que deseja. (Isso é útil para alguns de nós: muitas pessoas não têm uma instalação completa de (La)TeX em seu celular … ainda.)

Se sua sorte (conforme definido acima) não for suficiente, você vai ter que encontrar documentação por outros meios. Ou seja, você terá que encontrar a documentação por si mesmo. O restante desta resposta oferece uma série de técnicas possíveis. A forma mais comum de documentação de complementos de LaTeX está dentro do arquivo dtx no qual o código é distribuído (veja documented LaTeX sources). Tais arquivos são supostamente processáveis pelo próprio LaTeX, mas há soluços ocasionais no caminho para a documentação legível. Problemas comuns são que o próprio pacote é necessário para processar sua documentação (portanto, deve ser descompactado antes do processamento) e que o arquivo dtx não vai funcionar com LaTeX. Neste segundo caso, o arquivo ins geralmente produzirá um arquivo drv (ou similarmente nomeado), o qual você poderá processar com LaTeX. (Às vezes, o autor do pacote chega a mencionar este probleminha em um arquivo README do pacote.)

Outra forma comum é o arquivo de documentação separado; particularmente se um pacote for “conceitualmente grande” (e, portanto, precisar de muita documentação), a documentação seria um peso muito grande para o arquivo dtx. Exemplos de tais casos são o memoir class, o conjunto KOMA-script (cujos desenvolvedores se esforçam para produzir documentação detalhada em Alemão e Inglês), a documentação do pgf (que daria um livro substancial) e o pacote fancyhdr (cuja documentação deriva de um tutorial definitivo de um periódico de matemática). Mesmo que a documentação não esteja separadamente identificada em um arquivo README, não deve ser muito difícil reconhecer sua existência.

Documentação dentro do próprio pacote é a terceira forma comum. Tal documentação geralmente aparece em comentários no início do arquivo, embora pelo menos um autor eminente a coloque regularmente após o comando \endinput no pacote. (Isso é desejável, já que o \endinput é um fim de arquivo ‘lógico’ end-of-e o (La)TeX não lê além dele: assim, tal documentação não ‘custa’ qualquer tempo de carregamento do pacote.)

As sugestões acima cobrem a maioria das formas possíveis de encontrar documentação. Se, apesar de seus melhores esforços, você não conseguir encontrá-la em nenhum dos lugares acima, há a terrível possibilidade de o autor não ter se preocupado em documentar seu pacote (baseado na filosofia “se foi difícil de escrever, tem que ser difícil de usar”). A maioria dos mortais comuns buscará apoio de algum usuário mais experiente nesta fase, embora seja possível prosseguir da maneira que o autor original aparentemente esperava … lendo o código dele.

This answer last edited: 2012-11-09

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