Las fuentes de la documentación pueden venir en formato de texto plano, página de man y html. Sin embargo, la mayoría de la documentación de Postgres se escribirá usando Standard Generalized Markup Language (SGML) DocBook Document Type Definition (DTD). La mayoría de la documentación ha sido convertida o será convertida a SGML.
El propósito de SGML es el de permitir a un autor especificar la estructura y el contenido de un documento (por ejemplo, usando el DTD DocBook) y permitir que el estilo del documento defina cómo se verá el resultado final (por ejemplo, utilizando las hojas de estilo de Norm Walsh).
La documentación se ha reunido desde varias fuentes. Debido a que integramos y asimilamos la documentación existente y la convertimos en un conjunto coherente, las versiones antiguas pasarán a ser obsoletas y serán borradas de la distribución . Sin embargo, esto no ocurrirá inmediatamente y tampoco ocurrirá con todos los documentos al mismo tiempo. Para facilitar la transición y ayudar a los desarrolladores y escritores de guías, hemos definido un esquema de transición.
Actualmente hay cuatro documentos escritos con DocBook. Cada uno de ellos tiene un documento fuente que lo contiene y que define el entorno de Docbook y otros ficheros fuente del documento. Estos ficheros fuente se encuentran en doc/src/sgml/ junto con la mayoría de otros ficheros fuente usados para la documentación. La fuente primera de ficheros fuente son:
Este es el documento integrado, incluyendo todos los otros documentos como partes. La salida es generada en HTML, ya que la interfaz del navegador hace fácil moverse por toda la documentación sólo con pulsaciones del ratón. Los otros documentos están disponibles tanto en formato HTML como en copias impresas.
Es el tutorial introductorio, con ejemplos. No incluye elementos de programación y su intención es la de ayudar al lector no familiarizado con SQL. Este es el documento "getting started", cómo empezar .
Es la Guía del usuario. Incluye información sobre tipos de datos e interfaces a nivel de usuario. Este es el sitio donde emplazar información de "porqués".
El Manual de referencia. Incluye sintaxis de Postgres SQL . Este es el lugar donde recoger información de los "cómo".
Es la Guía del programador. Incluye información sobre la extensibilidad de Postgres y sobre las interfaces de programación.
La Guía del administrador. Abarca la instalación y notas de la versión.
DocBook tiene un un rico conjunto de etiquetas y conceptos y un gran número de ellos son muy útiles para documentación bien formada. Sólo recientemente el conjunto de la documentación de Postgres ha sido adaptada a SGML y en un futuro próximo varias partes de ese conjunto serán seleccionadas y y mantenidas como ejemplos del uso de DocBook . También se incluirá abajo un pequeño sumario de etiquetas de DocBook.
Actualmente la documentación de Postgres se ha escrito usando un editor de textos normal (o emacs/psgml, véase más abajo) con el marcado del contenido utilizando etiquetas SGML de DocBook.
SGML y DocBook no se ven afectados debido a las numerosas herramientas de autor de código abierto. El conjunto de herramientas más usado es el paquete de edición emacs/xemacs con la extensión psgml. En algunos sistemas (por ejemplo, RedHat Linux) estas herramientas se encuentran en la instalación de la distribución.
emacs (y xemacs) tienen un modo de trabajo (major mode) SGML. Si se configura correctamente le permitirá utilizar emacs para insertar etiquetas y controlar la consistencia de las marcas.
Introduzca las siguientes líneas en su fichero ~/.emacs (ajustando el path si fuera necesario):
; ********** for SGML mode (psgml)
(setq sgml-catalog-files "/usr/lib/sgml/CATALOG")
(setq sgml-local-catalogs "/usr/lib/sgml/CATALOG")
(autoload 'sgml-mode "psgml" "Major mode to edit SGML files." t )
y añada una entrada en el mismo fichero
para SGML en la definición existente para
auto-mode-alist:
(setq
auto-mode-alist
'(("\\.sgml$" . sgml-mode)
))
Cada fichero fuente SGML tiene el siguiente bloque
al final del fichero:
!-- Mantenga este comentario al final del fichero
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
sgml-parent-document:nil
sgml-default-dtd-file:"./reference.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:("/usr/lib/sgml/catalog")
sgml-local-ecat-files:nil
End:
--
La distribución de Postgres incluye un fichero DTD de definiciones, reference.ced.
Cuando esté usando emacs/psgml, una manera cómoda de trabajar con los ficheros separados de partes del libro es insertar una declaración DOCTYPE mientras los está editando. Si, por ejemplo, usted estuviera trabajando sobre este fichero fuente, que es un apéndice, usted especificaría que es una instancia "appendix" de un documento DocBook haciendo que la primera línea sea parecida a esto:
!doctype appendix PUBLIC "-//Davenport//DTD DocBook V3.0//EN"
Esa línea significa que cualquier cosa que sea capaz de leer SGML lo tomará
correctamente y se puede verificar el documento con "nsgmls -s docguide.sgml".