As seguintes ferramentas são usadas para construir a documentação. Algumas podem ser opcionais, conforme observado.
Esta é a definição do próprio DocBook. No momento é usada a versão 4.5; não podem ser usadas versões posteriores ou anteriores. É necessária a variante XML do DocBook DTD (Document Type Definition), e não a variante SGML.
Contêm as instruções de processamento para converter os arquivos-fonte do DocBook para outros formatos, como HTML.
No momento, a versão mínima exigida é a 1.77.0, mas é recomendável usar a versão mais recente disponível para obter melhores resultados.
xmllint #
Esta biblioteca, e a ferramenta xmllint que
ela contém, são usadas para processar o XML.
Muitos desenvolvedores já devem ter a
Libxml2 instalada, porque também é
usada na construção do código-fonte do
PostgreSQL.
Note, no entanto, que xmllint pode precisar
ser instalada a partir de um subpacote separado.
xsltproc #
O xsltproc é um processador XSLT,
ou seja, um programa para converter XML para
outros formatos usando folhas de estilo XSLT.
Este é um programa para converter, entre outras coisas, XML em PDF. Só é necessário se for desejado gerar a documentação no formato PDF.
Estão detalhados abaixo diferentes métodos de instalação para as várias ferramentas necessárias para processar a documentação. Podem existir outros tipos de distribuição dessas ferramentas. Qualquer alteração no status de um pacote pode ser informada à lista de discussão da documentação, para que esta informação seja incluída aqui.
Para instalar os pacotes necessários, deve-se executar:
yum install docbook-dtds docbook-style-xsl libxslt fop
Para instalar os pacotes necessários usando pkg,
deve-se executar:
pkg install docbook-xml docbook-xsl libxslt fop
Ao construir a documentação a partir do diretório
doc, será necessário usar o
gmake, porque o Makefile
fornecido não é adequado para o make do
FreeBSD.
Há um conjunto completo de pacotes de ferramentas de documentação disponíveis para o Debian GNU/Linux. Para instalar, basta executar:
apt-get install docbook-xml docbook-xsl libxml2-utils xsltproc fop
Se for usado o MacPorts, siga os passos abaixo para configurá-lo:
sudo port install docbook-xml docbook-xsl-nons libxslt fop
Se for usado o Homebrew, use isto:
brew install docbook docbook-xsl libxslt fop
Os programas fornecidos pelo Homebrew exigem que a seguinte variável de ambiente seja definida: Para máquinas baseadas em Intel, deve ser usado o seguinte:
export XML_CATALOG_FILES=/usr/local/etc/xml/catalog
Para máquinas baseadas no Apple Silicon, deve ser usado o seguinte:
export XML_CATALOG_FILES=/opt/homebrew/etc/xml/catalog
Sem isto, o xsltproc lançará erros como este:
I/O error : Attempt to load network entity http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd postgres.sgml:21: warning: failed to load external entity "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" ...
Embora seja possível usar as versões fornecidas pela Apple
do xmllint e do xsltproc
em vez de usar as versões do MacPorts ou do Homebrew, ainda será
necessário instalar o DTD e as folhas de estilo do DocBook e
configurar um arquivo de catálogo que aponte para eles.
configure #
Antes de construir a documentação, é necessário executar o script
configure, como faria ao construir os próprios
programas do PostgreSQL.
Verifique a saída perto do final da execução; deve ser algo
parecido com:
checking for xmllint... xmllint checking for xsltproc... xsltproc checking for fop... fop checking for dbtoepub... dbtoepub
Se não for encontrado o xmllint ou o
xsltproc, a documentação não poderá ser construída.
O fop só é necessário para construir a
documentação no formato PDF.
O dbtoepub só é necessário para construir a
documentação no formato EPUB.
Se for necessário, poderá ser informado ao configure
onde encontrar estes programas. Por exemplo:
./configure ... XMLLINT=/opt/local/bin/xmllint ...
Se for preferido construir o PostgreSQL
usando o Meson, deve-se executar o meson setup
conforme descrito em Construção e Instalação com Meson,
e depois ver Construção da documentação com Meson.