As seguintes ferramentas são utilizadas para processar a documentação. Algumas podem ser opcionais, conforme indicado.
Esta é a definição do próprio DocBook. Atualmente é utilizada a versão 4.2; não pode ser usada uma versão anterior ou posterior. Deve ser observado que também existe uma versão XML do DocBook — não utilize esta versão.
Estas entidades são requeridas pelo DocBook, mas são distribuídas em separado porque são mantidas pela ISO.
Este é o pacote básico para processar o SGML. Contém um analisador SGML, um processador DSSSL (ou seja, um programa para converter SGML em outros formatos utilizando as folhas de estilo DSSSL), assim como várias ferramentas relacionadas. O Jade agora é mantido pelo grupo OpenJade, e não mais por James Clark.
Contém instruções de processamento para converter os fontes em DocBook para outros formatos, tal como HTML.
Este pacote opcional é utilizado para criar as man pages, e contém vários pacotes de pré-requisitos próprios. Verifique o sítio na Web.
Se for desejado, também pode ser instalado o JadeTeX para utilizar o TeX como formatador para o Jade. O JadeTeX pode criar arquivos Postscript ou PDF (este último com marcadores).
Entretanto, a saída do JadeTeX é inferior à obtida pelo processador do RTF. Entre as áreas com problemas específicos estão as tabelas e vários artefatos de espaçamento vertical e horizontal. Além disso, não existe oportunidade para melhorar manualmente os resultados.
Existem experiências documentadas sobre vários métodos de instalação para as várias ferramentas necessárias para processar a documentação, as quais estão descritas abaixo. Podem haver outros pacotes contendo distribuições destas ferramentas. Por favor informe o status do pacote para a lista de discussão da documentação, e esta informação será incluída aqui.
A maioria dos fornecedores disponibiliza um conjunto completo de pacotes RPM para processar o DocBook em suas distribuições. Procure pela opção "SGML" ao instalar, ou pelos seguintes pacotes: sgml-common, docbook, stylesheets, openjade (ou jade). É possível que também seja necessário o pacote sgml-tools. Se estes pacotes não estiverem disponíveis na distribuição utilizada, então deve ser possível utilizar pacotes de alguma outra distribuição, razoavelmente compatível.
O próprio "Projeto de Documentação do FreeBSD" é um grande usuário do DocBook e, portanto, não é surpresa que exista um conjunto completo das ferramentas de documentação "portadas" disponível no FreeBSD. É necessário instalar as seguintes ferramentas para gerar a documentação no FreeBSD.
textproc/sp
textproc/openjade
textproc/iso8879
textproc/dsssl-docbook-modular
Aparentemente, não existe um DocBook V4.2 SGML DTD portado disponível atualmente, sendo necessário efetuar sua instalação manualmente.
Também podem ser de interesse vários outros aplicativos contidos em /usr/ports/print (tex, jadetex).
É possível que os aplicativos portados não atualizem o arquivo do catálogo principal em /usr/local/share/sgml/catalog. Certifique-se que a seguinte linha está presente:
CATALOG "/usr/local/share/sgml/docbook/4.2/docbook.cat"
Se não for desejado editar o arquivo, também pode ser definida a variável de ambiente SGML_CATALOG_FILES como uma lista separada por vírgulas de arquivos de catálogo (tal como mostrado acima).
Podem ser encontradas informações adicionais sobre as ferramentas de documentação do FreeBSD nas Instruções do Projeto de Documentação do FreeBSD.
Existe um conjunto completo de pacotes para as ferramentas de documentação disponível para o Debian GNU/Linux. Para instalar, deve simplesmente ser utilizado: [1]
apt-get install jade apt-get install docbook apt-get install docbook-stylesheets
O processo de instalação manual das ferramentas do DocBook é um tanto complexo e, portanto, havendo pacotes pré-construídos disponíveis estes devem ser utilizados. Aqui é descrita apenas a instalação padrão, com caminhos de instalação padrão razoáveis, e nenhuma funcionalidade "extravagante". Para obter detalhes, deve ser estudada a documentação do próprio pacote, e lido o material introdutório do SGML.
A instalação do OpenJade possui um processo de construção ./configure; make; make install ao estilo GNU. Os detalhes podem ser encontrados na distribuição do código fonte do OpenJade. De forma concisa:
./configure --enable-default-catalog=/usr/local/share/sgml/catalog make make install
Não se esqueça onde foi colocado o "catálogo padrão", pois será necessário abaixo. Também pode ser deixado de fora, mas deverá ser definida a variável de ambiente SGML_CATALOG_FILES para apontar para o arquivo sempre que o jade for utilizado posteriormente (Este método também é uma opção se OpenJade já estiver instalado, e for desejado instalar o restante do conjunto de ferramentas localmente).
Além disso, devem ser instalados os arquivos dsssl.dtd, fot.dtd, style-sheet.dtd e catalog do diretório dsssl em algum lugar, talvez no diretório /usr/local/share/sgml/dsssl. Provavelmente é mais fácil copiar todo o diretório:
cp -R dsssl /usr/local/share/sgml
Para terminar, deve ser criado o arquivo /usr/local/share/sgml/catalog e adicionada a seguinte linha ao mesmo:
CATALOG "dsssl/catalog"
(Esta é uma referência ao caminho relativo do arquivo instalado no passo 2. Assegure de ajustá-la se for escolhido um posicionamento diferente para a instalação).
Obter a distribuição DocBook V4.2.
Criar o diretório /usr/local/share/sgml/docbook-4.2 e torná-lo o diretório corrente (O local exato é irrelevante, mas este é razoável dentro do posicionamento que está sendo seguido).
$ mkdir /usr/local/share/sgml/docbook-4.2 $ cd /usr/local/share/sgml/docbook-4.2
Descompactar o arquivo.
$ unzip -a ...../docbook-4.2.zip
(Os arquivos serão descompactados no diretório corrente)
Editar o arquivo /usr/local/share/sgml/catalog (ou o que foi informado ao jade durante a instalação) e adicionar uma linha como esta:
CATALOG "docbook-4.2/docbook.cat"
Obter o arquivo Entidades caractere ISO 8879, e descompactá-lo colocando os arquivos no mesmo diretório onde foram colocados os arquivos do DocBook.
$ cd /usr/local/share/sgml/docbook-4.2 $ unzip ...../ISOEnts.zip
Executar o seguinte comando no diretório contendo os arquivos do DocBook e do ISO:
perl -pi -e 's/iso-(.*).gml/ISO\1/g' docbook.cat
(Este procedimento corrige uma discrepância entre os nomes utilizados no arquivo de catálogo do DocBook e os nomes verdadeiros dos arquivos das entidades caractere ISO).
Para instalar as folhas de estilo os arquivos deve ser descompactados e movidos para um lugar adequado como, por exemplo, /usr/local/share/sgml (O arquivo compactado cria automaticamente um subdiretório ao ser descompactado).
$ gunzip docbook-dsssl-1.xx.tar.gz $ tar -C /usr/local/share/sgml -xf docbook-dsssl-1.xx.tar
Também pode ser colocada a entrada usual do catálogo em /usr/local/share/sgml/catalog:
CATALOG "docbook-dsssl-1.xx/catalog
Como as folhas de estilo mudam muito freqüentemente, sendo alguma vezes benéfico tentar versões alternativas, o PostgreSQL não utiliza esta entrada do catálogo. Consulte a Seção G.2.5 para obter informações sobre como selecionar as folhas de estilo.
Para instalar e utilizar o JadeTeX, é necessário haver uma instalação do TeX e do LaTeX2e funcionando, incluindo os pacotes suportados tools e graphics, Babel, fontes AMS e AMS-LaTeX, a extensão PSNFSS e o kit que acompanha "as 35 fontes", o programa dvips para gerar PostScript, os pacotes de macros fancyhdr, hyperref, minitoc, url e ot2enc. Todos estes podem ser encontrados CTAN. A instalação do sistema básico do TeX está muito acima do escopo desta introdução. Devem existir pacotes binários disponíveis para qualquer sistema que possa executar o TeX.
Antes de ser possível utilizar o JadeTeX com os fontes da documentação do PostgreSQL, é necessário aumentar o tamanho das estruturas de dado internas do TeX. Os detalhes podem ser encontrados nas instruções de instalação do JadeTeX.
Após terminar esta parte pode ser instalado o JadeTeX:
$ gunzip jadetex-xxx.tar.gz $ tar xf jadetex-xxx.tar $ cd jadetex $ make install $ mktexlsr
Os dois últimos comando devem ser executados como root.
Para se poder construir a documentação, primeiro é necessário executar o script configure, como é feito para gerar os próprios programas do PostgreSQL. Deve ser verificado se a saída perto do fim da execução se parece com:
checking for onsgmls... onsgmls checking for openjade... openjade checking for DocBook V4.2... yes checking for DocBook stylesheets... /usr/lib/sgml/stylesheets/nwalsh-modular checking for sgmlspl... sgmlspl
Se não for encontrado nem o onsgmls nem o nsgmls, então as outras quatro linhas não serão vistas. O nsgmls é parte do pacote Jade. Se não for encontrado o "DocBook V4.2", então o kit DocBook DTD não foi instalado em um local onde o jade possa encontrá-lo, ou os arquivos do catálogo não foram definidos corretamente. Devem ser vistas as dicas de instalação acima. As folhas de estilo do DocBook são procuradas em vários locais relativamente padrão, mas se estiverem em algum outro local deve ser definida a variável de ambiente DOCBOOKSTYLE com o local correto, e executado novamente configure após isto.
| [1] |
Para gerar esta documentação foi necessário instalar também: libc6-dev, openjade, jadetex e opensp. (N. do T.) |
