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 ) |
(setq auto-mode-alist '(("\\.sgml$" . sgml-mode) )) |
!-- 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" |