Herramientas

Hemos documentado nuestra experiencia con tres m�todos de instalaci�n para las diferentes herramientas que son necesarias para procesar la documentaci�n. Una es la instalaci�n desde RPMs en Linux, la segunda es la instalaci�n desde el porte a FreeBSD y la �ltima es una instalaci�n general desde distribuciones originales de las herramientas. Estas se describir�n m�s abajo.

Pueden existir otras distribuciones empaquetadas de estas herramientas. Por favor remita informaci�n sobre estado de los paquetes a las listas de correo y la incluirimos aqu�.

Instalaci�n de RPM Linux

La instalaci�n m�s sencilla para sistemas Linux compatibles con RedHat utiliza RPM, desarrollado por Mark Galassi de Cygnus. Tambi�n es posible instalar desde las fuentes, como se describe en secciones posteriores.

Instalando RPMs

  1. Instale los RPM para Jade y los paquetes relacionados.

  2. Instale las �ltimas hojas de estilo de Norm Walsh. Dependiendo de la antiguedad de los RPM, las �ltimas hojas de estilo pueden haber sido muy mejoradas respecto a aquellas que aparecen con los RPM.

  3. Actualice su src/Makefile.custom para que incluyan las definiciones de HSTYLE y de PSTYLE que apuntan a las hojas de estilo.

Instalaci�n en FreeBSD

Hay un gran conjunto de portes de la documentaci�n de las herramientas disponibles para FreeBSD. De hecho, postgresql.org, en el que la documentaci�n se actualiza autom�ticamente cada tarde, es una m�quina con FreeBSD.

Instalando los "portes" de FreeBSD

  1. Para compilar la documentaci�n sobre FreeBSD se necesita instalar unos cuantos "portes".

    % cd /usr/ports/devel/gmake && make install
    % cd /usr/ports/textproc/docproj && make install
    % cd /usr/ports/textproc/docbook && make install
    % cd /usr/ports/textproc/dsssl-docbook-modular && make install
          

  2. Fijar las variables de entorno para acceder al conjunto de herramientas de jade .

    Nota

    Esto no era requerido para la m�quina FreeBSD de postgresql.org, as� que puede que esto no sea necesario.

    export SMGL_ROOT=/usr/local/share/sgml                                          
    SGML_CATALOG_FILES=/usr/local/share/sgml/jade/catalog                           
    SGML_CATALOG_FILES=/usr/local/share/sgml/html/catalog:$SGML_CATALOG_FILES       
    SGML_CATALOG_FILES=/usr/local/share/sgml/iso8879/catalog:$SGML_CATALOG_FILES    
    SGML_CATALOG_FILES=/usr/local/share/sgml/transpec/catalog:$SGML_CATALOG_FILES   
    SGML_CATALOG_FILES=/usr/local/share/sgml/docbook/catalog:$SGML_CATALOG_FILES    
    export SGML_CATALOG_FILES
          
    (esto es para sintaxis sh/bash. Aj�stelo para csh/tcsh).

  3. Make necesita algunos argumentos especiales o estos han de ser a�adidos a su Makefile.custom:

    HSTYLE=/usr/local/share/sgml/docbook/dsssl/modular/html/ 
    PSTYLE=/usr/local/share/sgml/docbook/dsssl/modular/print/
          
    Por descontado que necesitar� usar gmake, no s�lo 'make', para compilar.

Instalaci�n en Debian

Hay un juego completo de paquetes de la documentaci�n de las herramientas disponible para Debian.

Instalando los paquetes Debian

  1. Instale jade, docbook y unzip:

    apt-get install jade
    apt-get install docbook
    apt-get install docbook-stylesheets
          

  2. Instale las �ltimas hojas de estilo.

    1. Verifique que unzip est� instalado o instale el paquete:

      apt-get install unzip
      	

    2. Consiga el fichero comprimido con las �ltimas hojas de estilo en http://www.nwalsh.com/docbook/dsssl y descompr�malo (quiz�s en /usr/share).

  3. Edite src/Makefile.custom y a��dale las definiciones de HSTYLE y PSTYLE adecuadas:

    HSTYLE= /usr/share/docbook/html
    PSTYLE= /usr/share/docbook/print
          

Instalaci�n manual de las herramientas

Esta es una breve descripci�n del proceso de obtener e instalar el software que necesitar� para editar la fuente DocBook con Emacs y tratarla con las hojas de estilo DSSSL de Norman Walsh par crear ficheros HTML y RTF.

La manera m�s f�cil de obtener las herramientas SGML y DocBook quiz�s sea tomar sgmltools desde sgmltools. sgmltools necesita la versi�n GNU de m4. Para confirmar que tiene la versi�n correcta de m4 pruebe

gnum4 --version
    

Si instala GNU m4, inst�lelo con el nombre gnum4 y sgmltools lo encontrar�. Despu�s de la instalaci�n usted tendr� sgmltools, jade y las hojas de estilo DocBook de Norman Walsh. Las instrucciones de abajo son para instalar estas herramientas de modo separado.

Requisitos previos

Lo que usted necesita es:

  • Una instalaci�n funcionando de GCC 2.7.2

  • Una instalaci�n trabajando de Emacs 19.19 o posterior

  • La utilidad unzip para descomprimir ficheros

Debe conseguir:

  • Jade de James Clark (la versi�n 1.1 en el fichero jade1_1.zip en el momento de escribir esto)

  • DocBook versi�n 3.0

  • Modular Stylesheets de Norman Walsh (la versi�n 1.19 fue originalmente usada para producir estos documentos)

  • PSGML de Lennar Staflin (la versi�n 1.0.1 en psgml-1.0.1.tar.gz era la que estaba disponible en el momento de escribir esto)

URLs importantes:

Instalaci�n de Jade

Instalaci�n de Jade

  1. Lea las instrucciones de instalaci�n en la URL mostrada arriba.

  2. Descomprima la distribuci�n con unzip en el lugar adecuado . El comando para para hacer esto puede ser como este:

    unzip -aU jade1_1.zip
           

  3. Jade no ha sido construido usando GNU autoconf, de modo que tendr� que editar un Makefile por su cuenta. Ya que James Clark ha sido lo suficientemente bueno como para preparar su kit para ello, es una buena idea crear un directorio (con un nombre como la aquitectura de su m�quina, por ejemplo) bajo el directorio principal de Jade, copiar desde �l el fichero Makefile al directorio reci�n creado, editarlo y desde ah� mismo ejecutar make.

    Makefile necesitar ser. Hay un fichero llamado Makefile.jade en el directorio principal cuyo cometido es ser usado con make -f Makefile.jade cuando se construye Jade (a diferencia de SP, el parser SGML sobre el que est� construido Jade). Aconsejamos que no se haga esto, ya que deber� cambiar m�s cosas que lo que hay en Makefile.jade.

    Recorra el fichero Makefile, leyendo las instrucciones de Jame y haciendo los cambios necesarios. Hay algunas variables que necesitan ser fijadas. Aqu� se muestra un sumario de las m�s representativas con sus valores m�s t�picos:

    prefix = /usr/local
    XDEFINES = -DSGML_CATALOG_FILES_DEFAULT=\"/usr/local/share/sgml/catalog\"
    XLIBS = -lm
    RANLIB = ranlib
    srcdir = ..
    XLIBDIRS = grove spgrove style
    XPROGDIRS = jade
           
    Observe la especificaci�n de d�nde encontrar el cat�logo SGML por defecto de los ficheros de soporte (quiz�s tenga que cambiarlo a algo m�s adecuado para su instalaci�n). Si su sistema no necesita los ajustes mencionados arriba para la librer�a de funciones matem�ticas y para el comando ranlib, d�jelos tal y como est�n en Makefile.

  4. Escriba make para compilar Jade y las herramientas de SP.

  5. Una vez que est� compilado, make install har� la instalaci�n.

Instalaci�n del DTD de DocBook

Instalaci�n del DTD de DocBook

  1. Es conveniente que emplace los ficheros que constituyen el DTD de DocBook en el directorio en el que compil� Jade, /usr/local/share/sgml/ si ha seguido nuestra recomendaci�n. Adem�s de los ficheros de DocBook, necesitar� el fichero catalog en su sitio para el mapa de las especificaciones del tipo de documento y las referencias externas de las entidades a los ficheros actuales en ese directorio. Tambi�n necesitar� el mapa de caracteres ISO y posiblemente una o m�s versiones de HTML.

    Una manera para instalar las diferentes DTD y ficheros de soporte y para ajustar el fichero catalog es juntarlos todos en el directorio mencionado m�s arriba, usar un �nico fichero llamado CATALOG que los describa a todos y entonces crear el fichero catalog como un puntero a catalog a�adiendo la l�nea:

    CATALOG /usr/local/share/sgml/CATALOG
           

  2. El fichero CATALOG contendr�a tres tipos de l�neas. La primera (opcional) la declaracion SGML :

    SGMLDECL docbook.dcl
           
    Despu�s, las diferentes referencias a DTD y ficheros de las entidades. Para los ficheros DocBook las l�neas ser�an como estas:
    PUBLIC "-//Davenport//DTD DocBook V3.0//EN" docbook.dtd
    PUBLIC "-//USA-DOD//DTD Table Model 951010//EN" cals-tbl.dtd
    PUBLIC "-//Davenport//ELEMENTS DocBook Information Pool V3.0//EN" dbpool.mod
    PUBLIC "-//Davenport//ELEMENTS DocBook Document Hierarchy V3.0//EN" dbhier.mod
    PUBLIC "-//Davenport//ENTITIES DocBook Additional General Entities V3.0//EN" dbgenent.mod
           

  3. Por supuesto que en el kit de DocBook hay un fichero que contiene todo esto. Observe que el �ltimo elemento en cada una de esas l�neas es un nombre de fichero, que aqu� se da sin el path. Puede poner los ficheros en subdirectorios de su directorio SGML si quiere y modificar la referencia en el fichero CATALOG. DocBook tambi�n referencia el conjunto de caracteres ISO de las entidades, por lo que necesitar� traerlos e instalarlos (est�n disponibles desde varias fuentes y se pueden encontrar f�cilmente en las URLs mostradas m�s arriba), adem�s de su entradas:

    PUBLIC "ISO 8879-1986//ENTITIES Added Latin 1//EN" ISO/ISOlat1
           
    Observe que el nombre de fichero contiene un directorio, dici�ndonos que hemos puesto los ficheros de entidades ISO en un subdirectorio ISO. Nuevamente las entradas oportunas en el cat�logo deben acompa�ar a la entidad que se haya tra�do.

Instalaci�n de las hojas de estilo DSSSL de Norman Walsh

Instalaci�n de las hojas de estilo DSSSL de Norman Walsh

  1. Lea las instrucciones de instalaci�n en la URL mostrada m�s arriba.

  2. Para instalar las hojas de estilo de Norman, simplemente descomprima los ficheros de la distribuci�n en el lugar adecuado. Un buen lugar para hacerlo ser�a /usr/local/share, que emplaza los los ficheros en un directorio bajo /usr/local/share/docbook. El comando ser�a algo parecido a esto:

    unzip -aU db119.zip
           

  3. Una manera de probar la instalaci�n es compilar los formularios HTML y RTF de la Gu�a de usuarios de PostgreSQL.

    1. Para compilar los ficheros HTML vaya al directorio fuente de SGML , doc/src/sgml, y escriba

      jade -t sgml -d /usr/local/share/docbook/html/docbook.dsl -D ../graphics postgres.sgml
      	 

      book1.htm es el nodo m�s alto de la salida...

    2. Para generar el RTF preparado ser importado a su procesador de textos favorito, escriba:

      jade -t rtf -d /usr/local/share/docbook/print/docbook.dsl -D ../graphics postgres.sgml
      	 

Instalaci�n de PSGML

Instalaci�n de PSGML

  1. Lea las instrucciones de instalaci�n en la URL mostrada m�s arriba.

  2. Desempaquete el fichero de la distribuci�n, ejecute configure, make y make install para colocar en su sitio los ficheros compilados y las librer�as.

  3. Despu�s a�ada las l�neas siguientes al fichero /usr/local/share/emacs/site-lisp/site-start.el de modo que Emacs pueda cargar correctamente PSGML cuando lo necesite:

    (setq load-path
          (cons "/usr/local/share/emacs/site-lisp/psgml" load-path))
    (autoload 'sgml-mode "psgml" "Major mode to edit SGML files." t)
           

  4. Si necesita usar PSGML cuando tambi�n est� editando HTML a�ada esto:

    (setq auto-mode-alist
          (cons '("\\.s?html?\\'" . sgml-mode) auto-mode-alist))
           

  5. Hay una cosa importante que debe tener en cuenta con PSGML: su autor asume que su directorio principal para el DTD SGML es /usr/local/lib/sgml. Si, como en los ejemplos de cap�tulo, utiliza /usr/local/share/sgml, debe corregirlo adecuadamente.

    1. Puede fijar la variable de entorno SGML_CATALOG_FILES.

    2. Puede personalizar su instalaci�n de PSGML (el manual le dir� c�mo).

    3. Puede incluso editar el fichero fuente psgml.el antes de compilar e instalar PSGML, de modo que cambie los path para que se adecuen a los suyos por defecto.

Instalaci�n de JadeTeX

Si quiere, tambi�n puede instalar JadeTeX para usar TeX como utilidad para formatear Jade. Tenga en cuenta que es todav�a un software sin depurar y generar� salidas impresas inferiores a las obtenidas desde RTF. A pesar de todo, funciona bien, especialmente para los documentos m�s simples que no usan tablas y adem�s, como JadeTeX y las hojas de estilo, est� en un proceso continuo de mejora a medida que pasa el tiempo.

Para instalar y utilizar JadeTeX necesitar� que TeX y LaTeX2eest�n funcionando correctamente, incluyendo los paquetes tools y graphics, Babel, AMS fonts y AMS-LaTeX, PSNFSS y el kit de las 35 fuentes, dvips para generar PostScript, los paquetes de macros fancyhdr, hyperref, minitoc, url y ot2enc y por supuesto JadeTeX. Todos ellos se pueden encontrar en el site CTAN m�s pr�ximo.

JadeTeX, en el momento de escribir esto, no viene con una gu�a de instalaci�n, pero hay fichero makefile que muestra qu� es necesario. Tambi�n incluye un directorio llamado cooked donde encontrar� algunos de los paquetes de macro que necesita (aunque no todos y tampoco completos).

Antes de compilar el fichero de formato jadetex.fmt, es posible que quiera editar el fichero jadetex.ltx para cambiar la configuraci�n de Babel para ajustarla a su instalaci�n. La l�nea a cambiar se parece a esta:

\RequirePackage[german,french,english]{babel}[1997/01/23]
     
y obviamente debe poner s�lo los idiomas que necesite y configurar Babel para ello.

Con JadeTeX en funcionamiento, deber�a poder generar y formatear las salidas de TeX para los manuales de PostgreSQL pasando los comandos (como m�s arriba, en el directorio doc/src/sgml)

jade -t tex -d /usr/local/share/docbook/print/docbook.dsl -D ../graphics postgres.sgml
jadetex postgres.tex
jadetex postgres.tex
dvips postgres.dvi
     
Por supuesto, cuando haga esto TeX parar� durante la segunda ejecuci�n diciendo que su capacidad se ha sobrepasado. Esto es debido al modo en que JadeTeX genera informaci�n de referencias cruzadas. TeX puede ser compilado de manera que utilice estructuras de datos mayores. Los detalles de esto variar�n de acuerdo a su instalaci�n.