Las siguientes herramientas se utilizan para procesar la documentación. Algunas pueden ser opcionales, como se indica a continuación.
Esta es la definición de DocBook en sí. Actualmente utilizamos la versión 4.5; no puedes usar versiones posteriores ni anteriores. Necesitas la variante XML del DTD de DocBook, no la variante SGML.
Estas contienen las instrucciones de procesamiento para convertir las fuentes de DocBook a otros formatos, como HTML.
La versión mínima requerida actualmente es la 1.77.0, pero se recomienda usar la última versión disponible para obtener mejores resultados.
xmllint #
Esta biblioteca y la herramienta xmllint que contiene se
utilizan para procesar XML. Muchos desarrolladores ya tendrán
instalada Libxml2, porque también se utiliza
al compilar el código de PostgreSQL. Ten en cuenta, sin embargo,
que xmllint podría tener que instalarse desde un
paquete separado.
xsltproc #
xsltproc es un procesador XSLT, es decir, un programa para
convertir XML a otros formatos utilizando hojas de estilo XSLT.
Este es un programa para convertir, entre otras cosas, XML a PDF. Solo se necesita si quieres compilar la documentación en formato PDF.
Hemos documentado experiencias con varios métodos de instalación para las distintas herramientas necesarias para procesar la documentación. Estos se describen a continuación. Puede haber otras distribuciones empaquetadas para estas herramientas. Por favor, informa del estado de los paquetes a la lista de correo de documentación y agregaremos esa información aquí.
Para instalar los paquetes requeridos, usa:
yum install docbook-dtds docbook-style-xsl libxslt fop
Para instalar los paquetes requeridos con pkg, usa:
pkg install docbook-xml docbook-xsl libxslt fop
Al compilar la documentación desde el directorio doc
tendrás que usar gmake, porque el
makefile proporcionado no es adecuado para el comando make de FreeBSD.
Hay un conjunto completo de paquetes de las herramientas de documentación disponibles para Debian GNU/Linux. Para instalarlos, simplemente usa:
apt-get install docbook-xml docbook-xsl libxml2-utils xsltproc fop
Si usas MacPorts, lo siguiente te servirá para configurar todo:
sudo port install docbook-xml docbook-xsl-nons libxslt fop
Si usas Homebrew, usa esto:
brew install docbook docbook-xsl libxslt fop
Los programas suministrados por Homebrew requiren configurar la siguiente variable de entorno. Para máquinas basadas en Intel, usa esto:
export XML_CATALOG_FILES=/usr/local/etc/xml/catalog
En máquinas basadas en Apple Silicon, usa esto:
export XML_CATALOG_FILES=/opt/homebrew/etc/xml/catalog
Sin ella, xsltproc arrojará errores 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" ...
Aunque es posible usar las versiones proporcionadas por Apple
de xmllint y xsltproc
en lugar de las de MacPorts o Homebrew, de todos modos tendrás
que instalar el DTD y las hojas de estilo de DocBook, y configurar un archivo
de catálogo que apunte a ellos.
configure #
Antes de poder compilar la documentación, debes ejecutar el script
configure, tal como lo harías al compilar los propios
programas de PostgreSQL.
Verifica la salida cerca del final de la ejecución; debería verse algo así:
checking for xmllint... xmllint checking for xsltproc... xsltproc checking for fop... fop checking for dbtoepub... dbtoepub
Si no se encuentran xmllint o xsltproc,
no podrás compilar la documentación.
Solo se necesita fop para compilar la documentación en
formato PDF.
Solo se necesita dbtoepub para compilar la documentación
en formato EPUB.
Si es necesario, puedes indicarle a configure dónde encontrar
estos programas, por ejemplo:
./configure ... XMLLINT=/opt/local/bin/xmllint ...
Si prefieres compilar PostgreSQL usando
Meson, ejecuta en su lugar meson setup como se describe en
la Section 17.4, y luego consulta la
Section J.4.