Documentação nos pacotes do Projeto GNU

Esta é uma dica breve sobre documentação nos pacotes de código do Projeto GNU, e não se aterá no momento aos pormenores para a instalação de binários do zero. Praticamente todos os pacotes a possuem.

Dentro deles, além do código-fonte do software em si, há ainda o código-fonte dos manuais. Um pouco mais além que os tradicionais arquivos README e INSTALL.

Há um utilitário, ainda do mesmo projeto, para trabalhar os fontes destes manuais: o texinfo.

Os arquivos desta finalidade costumam usar a extensão ".texi" e possuem uma linguagem de marcação própria, com direito à diretivas de processamento.

Estes arquivos costumam ficar dentro do diretório doc/, que surge após a descompactação dos códigos-fontes.

Geralmente, estão disponíveis (ou são possíveis de serem gerados) seis formatos:

• manpage;
• info;
• HTML;
• PS;
• DVI;
• PDF.

Recordo-me de ter visto formato ASCII (TXT) em alguns sources, mas não tenho exemplos no momento de onde e quando foram vistos.

Os arquivos de manpages costumam terminar com um número entre 1 e 8. São os mesmos invocados pelo comando man. Serão compactados em formato ".gz".

Os arquivos formato info são de um formato de documentação de terminal da GNU de mesmo nome. Estas páginas são invocadas pelo comando info. Ex.:

info coreutils

Os formatos PDF e HTML são os mesmos conhecidos.

O formato PS (PostScript) é o mesmo de arquivos criados pelo software Ghostscript.

O formato DVI (Device Independent Format, nada a ver com a interface de vídeo) é um formato de saída de arquivo usado por programas "compiladores" de texto, como sistemas semelhantes ao LaTeX ou o TeX Live.

Muito usado por acadêmicos para criar arquivos com gráficos diversos e fórmulas matemáticas, com extrema qualidade visual. Os arquivos DVI podem ser convertidos em arquivos PS, que por sua vez, podem ser convertidos em PDF.

Texinfo acaba dependendo, portanto, de vários outros pacotes para criar esta documentação, a maioria ligados ao TeX, quando estes se fizerem necessários.

Por exemplo:

• TeX Live: http://www.tug.org/texlive/
• Ghostscript: http://pages.cs.wisc.edu/~ghost/

No caso da compilação do zero do TeX Live, há alguns requisitos que devem ser cumpridos para a compilação.

Será usado, como exemplo, o GNU Parted.

Estando tudo pronto para o uso do Texinfo, seguem-se estes procedimentos:

1. Baixar o GNU Parted (usar a versão atual), descompactar e acessar o diretório:

wget -c http://ftp.gnu.org/gnu/parted/parted-X.XX.tar.gz
tar -zxvf parted-X.XX.tar.gz
$ cd parted-X.XX

2. Executar o script configure:

./configure

"Configure" possui algumas opções, que podem ser conhecidas com "./configure --help". Dentre as várias:

--mandir=DIR      man documentation  [DATAROOTDIR/man]
--docdir=DIR      documentation root [DATAROOTDIR/doc/make]
--infodir=DIR     info documentation [DATAROOTDIR/info]
--htmldir=DIR     html documentation [DOCDIR]
--dvidir=DIR      dvi documentation  [DOCDIR]
--pdfdir=DIR      pdf documentation  [DOCDIR]
--psdir=DIR       ps documentation   [DOCDIR]

Se usadas após "./configure", elas determinam para quais diretórios esta documentação dirá, se executado quando executado make install. Senão, será usado o que estiver definido por padrão ou conforme a opção "--prefix".

Depois de executado configure, os comandos para a criação de cada um destes manuais serão (salvo variações):

make dvi  #Para a criação de documentação em formato .dvi
make ps  #Para a criação de documentação em formato .ps
make pdf  #Para a criação de documentação em formato .pdf
make html  #Para a criação de documentação em formato .html

Estes comandos podem ser executados dentro do diretório ./doc:

cd doc
$ make ps
$ make pdf
...

E serão criados longos arquivos ".pdf", ".ps" ou ".dvi" para leitura na própria máquina, ou impressão ocasional de alguma página, bem como possivelmente, o formato de hipertexto (HTML) para o mesmo fim.

Vale lembrar que estes manuais são, geralmente, muito mais completos e aprofundados que os de formato manpage. Este foi o fato que me chamou a atenção e pelo qual atribuí maior importância.

Talvez seja o mesmo conteúdo do formato info. Quem não está habituado a esse aplicativo, estranhará como estão dispostos os hiperlinks no texto.

E com isto, pode-se obter a última versão de um manual, tal qual como se faz com a última versão de um software via código-fonte.