Primeros pasos con DocBook

Uso manual de jade/OpenJade

Esta es la forma rápida y directa que debiera funcionar bien con todas las distribuciones, sea cual sea la que Usted esté usando.

1. Cree un directorio base para almacenar todo, tal como /usr/local/sgml/. A partir de ahora lo llamaremos $_toolroot.

2. Instale Jade, DocBook DTD, y DSSSL de forma que la base de cada uno esté bajo $_toolroot (creando $_toolroot/jade-1.2.1, $_toolroot/dtd, $_toolroot/dssl).

3. Necesitará definir la variable de entorno SGML_CATALOG_FILES apuntando a los catálogos que tiene bajo $_toolroot. Para ello utilice esta orden: bash$ export SGML_CATALOG_FILES = $_toolroot/dtd/docbook.cat:$_toolroot/dsssl/docbook/catalog:$_toolroot/jade-1.2.1/dsssl/catalog

4. Ya puede empezar a utilizar Jade. Para crear ficheros HTML individuales:

   $_toolroot/jade-1.2.1/jade/jade -t sgml -i html -d $_toolroot/dsssl/docbook/html/docbook.dsl howto.sgml

5. Para crear un único fichero HTML grande, añada -V nochunks a la orden jade.

sgmltools

Al contrario que en versiones anteriores de sgmltools, necesitará la versión 2.x de sgmltools para trabajar con DocBook. Puesto que algunas de las distribuciones más importantes vienen con sgmltools 1.x, tendrá que eliminar el paquete sgmltools 1.x e instalar, o bien una versión 2.0 , o bien una versión CVS. Para conseguir la última versión de código fuente CVS, puede utilizar las órdenes siguientes:

bash$ CVSROOT=:pserver:cvs@cvs.sgmltools.org:/home/cvs 
bash$ export CVSROOT 
bash$ cvs login 
bash$ cvs -z6 get sgmltools 

La contraseña de CVS es 'cvs'. Una vez descargado utilice simplemente

 
bash$ ./compile 
bash$ make 
bash# make install 

para instalar sgmltools. Para los sistemas basados en Red Hat (que utilizan RPM) puede usar la orden rpmfind para conseguir el último sgmltools. El programa rpmfind lo encontrará en http://www.rpmfind.net/. Asegúrese de obtener sgmltools y no sgml-tools, ya que el último es sgml-tools 1.0.9 y sólo trabaja con documentos LinuxDoc. Para sistemas basados en Debian, que ejecuten 2.2 «Potato» y superiores, apt-get le devolverá el paquete correcto:

bash# apt-get install sgmltools-2

Al igual que ocurre con Linux Red Hat, el paquete sgml-tools está obsoleto. Procure conseguir sgmltools-2.

Cygnus DocBook Tools.

Estas son las herramientas que ofrece Red Hat 6.2. Asegúrese de que los siguientes paquetes están instalados:

• sgml-common

• docbook

• stylesheets

Red Hat tiene la última version en su sitio web: http://www.redhat.com/support/errata/RHBA-2000022-01.html.

Descargue/obtenga/busque en la red los RPMs e instálelos del modo habitual (entre como root, y a continuación rpm -Uvh filename). Una vez los RPMs están instalados, puede usar las siguientes órdenes para exportar DocBook:

bash$ db2html nombre_de_fichero 

Convierte DocBook en HTML. Se crea un subdirectorio con el nombre del fichero (menos la extensión .sgml) y los ficheros HTML se almacenan allí.

bash$ db2pdf nombre_de_fichero

Convierte DocBook en un fichero PDF.

Documentos nuevos

Puede comenzar fácilmente un nuevo CÓMO utilizando LyX. Use la orden de menú File->New >From Template... para mostrar los listados de plantillas. Seleccione Templates a la derecha de la pantalla y seleccione docbook_template.lyx en el listado de ficheros. Seleccione OK, y obtendrá un documento nuevo. Introduzca la información, como título, resumen y nombre de autor, y comience a escribir.

Documentos ya existentes

Si tiene un documento LyX, TeX, o un documento de texto, puede importarlo a LyX con la orden File->import. Una vez importado vaya a Layout->Document... En la ventana emergente, en Style, seleccione SGML (DocBook Article). Se le preguntará si quiere convertir todo el texto; contéstele afirmativamente. Tendrá que volver a aplicar la mayoría de las etiquetas, pero es una forma secilla de seleccionar texto y cambiar el estilo. Muchas funciones LyX tienen acceso directo desde el teclado para ayudarle.

Exportar documentos a SGML

Una vez que el documento está escrito o convertido, guárdelo en formato LyX . Esto le permitirá editar futuras versiones fácilmente. Después, vaya a File->Export->as DocBook... y el fichero será exportado a DocBook

Introducción

Si ha instalado una distribución reciente, probablemente ya tendrá instalado PSGML para utilizarlo con Emacs. Para verificarlo, arranque Emacs y busque la documentación PSGML ( C-h i m psgml).

De ahora en adelante, damos por hecho que tiene instalado PSGML para utilizarlo con una versión reciente de Emacs GNU. Si todo esto no le ha quedado claro, vea el capítulo gratruíto del libro en formato CD de Bob Ducharme, SGML: http://www.snee.com/bob/sgmlfree/.

Actualizar su .emacs para usar PSGML

Si quiere que Emacs GNU entre en modo PSGML cuando abra un fichero con extensión .sgml y que esté listo para editar SGML, asegúrese de que PSGML pueda encontrar la DTD Docbook. Si su distribución ya tiene incorporado PSGML para ulilizarlo con Emacs GNU, probablemente no tendrá ningún problema con esto. Si no es así, puede que necesite definir una variable de entorno que le diga a PSGML dónde buscar el catálogo SGML (la lista de los DTDs).

Por ejemplo:

 bash$ export
SGML_CATALOG_FILES=/usr/lib/sgml/catalog 

A continuación añada algo parecido a lo siguiente en su fichero .emacs:

 

;; *******************************************************************
;; configurar modo  psgml 
;; utilizar modo psgml-mode en lugar del modo nativo emacs sgml-mode
;;

(autoload 'sgml-mode "psgml" "Modo mayor para editar ficheros SGML." t )
(setq auto-mode-alist
  (append
  (list
    '("\\.sgm$" . sgml-mode)
    '("\\.sgml$" . sgml-mode)
    )
  auto-mode-alist))

;; establecer algunas variables psgml

(setq sgml-auto-activate-dtd t)
(setq sgml-omittag-transparent t)
(setq sgml-balanced-tag-edit t)
(setq sgml-auto-insert-required-elements t)
(setq sgml-live-element-indicator t)
(setq sgml-indent-step nil)

;; crear tipos de fuentes por asignar a categorías de marcado:

(make-face 'sgml-comment-face)
(make-face 'sgml-start-tag-face)
(make-face 'sgml-end-tag-face)
(make-face 'sgml-entity-face)
(make-face 'sgml-doctype-face) ; datos DOCTYPE
(make-face 'sgml-ignored-face) ; datos ignorados por PSGML
(make-face 'sgml-ms-start-face) ; comienzo de secciones marcadas
(make-face 'sgml-ms-end-face) ; fin de sección marcada
(make-face 'sgml-pi-face) ; instrucciones de procesamiento
(make-face 'sgml-sgml-face) ; la declaración SGML
(make-face 'sgml-shortref-face) ; referencias cortas

;; puede ver una lista de colores disponibles con la orden emacs-lisp:
;;
;; list-colors-display
;;
;; sírvase añadir sus propios colores, estos no están muy combinados
(set-face-foreground 'sgml-comment-face "coral")
;(set-face-background 'sgml-comment-face "cornflowerblue")
(set-face-foreground 'sgml-start-tag-face "slateblue")
;(set-face-background 'sgml-start-tag-face "cornflowerblue")
(set-face-foreground 'sgml-end-tag-face "slateblue")
;(set-face-background 'sgml-end-tag-face "cornflowerblue")
(set-face-foreground 'sgml-entity-face "lavender")
;(set-face-background 'sgml-entity-face "cornflowerblue")
(set-face-foreground 'sgml-doctype-face "lavender")
;(set-face-background 'sgml-doctype-face "cornflowerblue")
(set-face-foreground 'sgml-ignored-face "cornflowerblue")
;(set-face-background 'sgml-ignored-face "cornflowerblue")
(set-face-foreground 'sgml-ms-start-face "coral")
;(set-face-background 'sgml-ms-start-face "cornflowerblue")
(set-face-foreground 'sgml-ms-end-face "coral")
;(set-face-background 'sgml-ms-end-face "cornflowerblue")
(set-face-foreground 'sgml-pi-face "coral")
;(set-face-background 'sgml-pi-face "cornflowerblue")
(set-face-foreground 'sgml-sgml-face "coral")
;(set-face-background 'sgml-sgml-face "cornflowerblue")
(set-face-foreground 'sgml-shortref-face "coral")
;(set-face-background 'sgml-shortref-face "cornflowerblue")

;; asignar fuentes a categorías de marcado

(setq sgml-markup-faces '
  (
  (comment . sgml-comment-face)
  (start-tag . sgml-start-tag-face)
  (end-tag . sgml-end-tag-face)
  (entity . sgml-entity-face)
  (doctype . sgml-doctype-face)
  (ignored . sgml-ignored-face)
  (ms-start . sgml-ms-start-face)
  (ms-end . sgml-ms-end-face)
  (pi . sgml-pi-face)
  (sgml . sgml-sgml-face)
  (shortref . sgml-shortref-face)
  ))

;; le decimos a PSGML que advierta la nueva configuración de fuentes
(setq sgml-set-face t)
;; ... acabada la configuración del modo psgml
;; *******************************************************************

Ahora reinicie Emacs.

Prueba de fuego de SGML

Intente la siguiente prueba de fuego. Cree un nuevo archivo, /tmp/test.sgml, por ejemplo, e introduzca lo siguiente:

 
<!DOCTYPE test [ 
<!ELEMENT test - - (#PCDATA)> 
]> 

Introduzca C-cC-p. Si Emacs consigue analizar su DTD, aparecerá Parsing prolog...done en el minibuffer. Utilice C-c C-e RETURN para insertar un elemento <test> . Si todofunciona correctamente, debería ver en Emacs:

 
<!DOCTYPE test [ 
<!ELEMENT test - - (#PCDATA)> 
]> 
<test></test> 

Escribir un nuevo CÓMO en Docbook

Cree un nuevo archivo para su CÓMO e introduzca lo siguiente:

 
<!DOCTYPE ARTICLE PUBLIC "-//OASIS//DTD DocBook V3.1//EN"> 

Introduzca C-c C-p y contenga la respiración. Si todo funciona correctamente, verá a Emacs rumiando durante unos segundos y acto seguido, Parsing prolog...done en el minibuffer.

Finalmente, introduzca C-c C-e RETURN para insertar un elemento <article> y proceda a escribir su CÓMO.

Referencia rápida para Emacs con PSGML

Vea el manual básico de Nik Clayton's incluido en la documentación de FreeBSD: http://www.freebsd.org/tutorials/docproj-primer/psgml-mode.html