Fuentes de la documentaci�n

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.

Estructura del documento

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:

postgres.sgml

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.

tutorial.sgml

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 .

user.sgml

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".

reference.sgml

El Manual de referencia. Incluye sintaxis de Postgres SQL . Este es el lugar donde recoger informaci�n de los "c�mo".

programming.sgml

Es la Gu�a del programador. Incluye informaci�n sobre la extensibilidad de Postgres y sobre las interfaces de programaci�n.

admin.sgml

La Gu�a del administrador. Abarca la instalaci�n y notas de la versi�n.

Estilos y convenciones

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.

Herramientas de autor para SGML

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/psgml

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".