FAQ de la traducción al español de los manuales de GNOME

Su revisión es $Revision: 1.3 $, fechada en $Date: 2000/05/19 18:34:46 $

La última versión de este FAQ estará disponible próximamente en la página principal de LILO.

Puedes mandar tus dudas y sugerencias al coordinador o suscribirte a la lista de LILO y mandar tus preguntas a ella. Las correcciones serán siempre bien recibidas.

Cualquier editor capaz de manejar texto plano (Incluso el wordpad de Windows sirve), saber de lo que habla el documento que quieres traducir y un conocimiento somero del inglés.

Necesitarás jade, jadetex, sgml-common, docbook, stylesheets, y el estilo de la documentación gnome gdp-both.dsl. Además, si quieres utilizar png's en vez de gifs necesitaras png-support-3.1.dtd. Estos dos últimos archivos los podrás encontrar en la página del proyecto GDP.

Todas estos paquetes forman parte de sgmltools-2.x. Te recomiendo que trates de bajarte las fuentes de este paquete más que la versión binaria de cada herramienta por separado (Esto último supone bajarse más del doble de megas).

Por ejemplo, en ftpsearch.lycos.com, vete a búsqueda avanzada, introduce sgml-tools-2*.src.rpm (O su equivalente en *.deb o *.tar.gz) y fija como límite de dominio "es" (O el que te sea más cercano). Te saldrán un montón de sitios donde puedes conseguirlo.

También puedes bajarte cada paquete del servidor sourceware de Cygnus. Sigue el enlace que hay en la página del proyecto GDP.

Para los que trabajen con Windows, todo el software mencionado anteriormente existe para este s.o: busca los paquetes acabados en zip o visita las páginas de cada herramienta para más información.

Un intérprete de sgml (Si bien esto no es del todo correcto: realmente es un intérprete del lenguaje en el que se definen los estilos de representación de sgml).

Básicamente, coge un sgml y lo traduce a rtf, tex, sgml, xml, dvi, ps, pdf, o html.

Además, el el paquete vienen algunas herramientas que jade necesita, como nsgml (un programa que verifica si el sgml es correcto).

Para sacar postscript, jade lo que hace es transformar el sgml en *.tex e invocar a LaTeX (Necesitar evidentemente tener tetex instalado), Jadetex hace de "traductor" de sgml LaTeX.

Algunos estilos comunes a todos los sgml. Y una herramienta para no tener que tocar los archivos de catálogo directamente.

El paquete "docbook" puede contener dependiendo de la distribución la versión de DocBook 3.0, la 3.1 o ambas. Es muy recomendable que obtengas al menos la versión 3.1.

DocBook es una definición de un tipo de documento (DTD) para escribir documentación técnica sobre software y hardware.

Un buen montón de estilos para DocBook y algunos sgml de ejemplo.

Lo primero que deberías hacer es darte una vuelta por la página del proyecto GNOME-ES, donde se recogen todos los documentos ya traducidos o que están siendo traducidos en este momento. Si tu documento no aparece en la lista, ponte en contacto con Manuel Barreiro, que es coordinador del proyecto GNOME-ES y solicitarle que dé de alta tu traducción.

Si en el documento que pensabas traducir ya está trabajando otro grupo, dirígete a ellos y pregunta si necesitan ayuda.

Seguir estas pequeñas normas de cortesía puede ahorrar duplicidad de esfuerzos y horas de trabajo que se pueden emplear en algo más provechoso...

Aunque un mismo documento de GNOME se pueda encontrar en distintos formatos, todos ellos se obtienen de un original escrito en sgml. A partir de una única "fuente" (El documento en sgml) se pueden obtener el resto de los formatos habituales (pdf, ps, html)

Tras aclarar este punto, se hacen evidentes las ventajas de trabajar sobre el original escrito en sgml: independencia del formato y coherencia entre el documento fuente y la traducción.

Para más información acerca de sgml y en concreto de DocBook consulta la página de DocBook.

La documentación (Tutoriales, ayuda en linea...) de GNOME está escrita en sgml, usando DocBook junto con una definición de estilo personalizada.

Sgml es una "meta-lenguaje" de marcas: permite construir a partir de él diferentes lenguajes similares definiendo reglas (Un lenguaje representativo obtenido de esta forma y con el que estarás familiarizado seguramente es html).

DocBook es uno de estos "lenguaje derivados" orientado a escribir documentación técnica de software y/o hardware.

DocBook (y sgml) sólo describe el contenido del documento: no describe cómo se visualiza. Por ejemplo, en vez de decir que una frase tiene tal tamaño con tal separación entre letras, dice qué esa frase es el título de una sección.

DocBook define qué función desempeña algo dentro del documento, si es un título, una entrada bibliográfica... Posteriormente, un "parser" de sgml/DocBook se encarga de interpretarlo y decidir qué forma le da al documento.

El "parser" acepta que el usuario defina cómo desea que se visualicen los documentos (Espaciado entre lineas, tipografía...) y el Gnome Documentation Project (GDP) ha definido su propio estilo, que comparte toda la documentación de GNOME y que debes utilizar para tirar tu traducción en formato ps, pdf, html...

Para más información acerca de sgml y en concreto de DocBook visita la página de DocBook.

Generalmente, lo que está accesible al público son los documentos en ps, pdf y html. Para obtener el sgml hay que recurrir al servidor cvs del proyecto GNOME.

La documentación suele estar disponible en el módulo gnome-docu o en el web-devel-2. Para localizar dentro de estos módulos el documento que deseamos traducir, podemos usar un interfaz web (Bonsai, por ejemplo) como el que se nos ofrece en la página de GNOME

Aunque explicar como funciona cvs escapa de los objetivos de este documento, se describirá a modo de ejemplo como obtener la última versión de gnome-libs-tutorial (De George Lebl, traducido por LILO):

Introduce las siguientes órdenes:

Como nos estamos conectando al servidor anónimo, cuandos nos pida clave simplemente pulsa enter.

Es posible que nos rechace a la primera, en ese caso sigue intentándolo: hay miles de premios. El siguiente paso consiste en bajarse el documento en sí y los gráficos que lo acompañan:

Piden que no se use "-z9" porque están bastante saturados.

Igual que en el anterior lo mismo tienes que ponerte cabezota para que te hagan caso (Piensa que el servidor cvs de gnome está bastante solicitado).

Date cuenta de que hemos hecho una bajada bastante selectiva: el sgml y los gif's solamente. Dentro de web-devel-2/content/doc/tutorials/gnome-libs/ hay bastantes más cosas como el documento en ps y html y los gráficos en eps: el resto no es imprescindible (Los gifs podemos transformarlos en eps para sacar ps, por ejemplo) y dejándolos nos ahorraremos tiempo de conexión.

No preocuparte: tal y como dije en un mensaje anterior:

> Aunque sgml no es complicado (Es similar a html) no es necesario
> que nadie aprenda su sintaxis: tan sólo ha de guiarse por el
> original. Si te encuentras, p.ej. con:

> <title>Application Programming Using the GNOME
> Libraries</title>

> Lo traduces por:

> <title>Programación de Aplicaciones Usando las Bibliotecas
> GNOME</title>

> No habría que preocuparse de que significa <title> o cosas así.

Sí, aunque como si no existiese: no es software abierto :-(. Se llame framemaker y se puede sacar de Cygnus. No tengo ni idea de si es bueno o no (No lo he usado nunca).

Emacs/Xemacs, naturalmente. Su modo de edición de sgml es fantástico (psgml) y además permite que Ispell corrija la ortografía (En castellano) de lo que estamos escribiendo, a pesar de que Ispell no entiende sgml todavía.

Para configurar psgml edita tu $HOME/.emacs e inserta lo siguiente (Quizás tengas que editar los paths):

(setq sgml-set-face t)
(setq sgml-catalog-files (quote ("CATALOG" "/usr/lib/sgml/CATALOG")))
(setq sgml-local-catalogs (quote ("\"/usr/lib/sgml/CATALOG\"")))

En vez de setq puedes usar el interfaz custom-set-varibles si tu Emacs lo soporta.

Para la corrección ortográfica basta con seleccionar el diccionario de castellano, hacer un M-x sgml-hide-tags (Oculta las marcas del buffer que estemos editando) y un M-x ispell-buffer o M-x ispell-region.

Un pequeño inciso: puede que "español", "castellano" o "spanish" no sea uno de los diccionarios permitidos de tu interfaz Emacs/Ispell. En tal caso tendremos que modificar la lista ispell-dictionary-alist en ispell.el o "sobreescribirla" en $HOME/.emacs, para añadir una nueva entrada para "español" (Evidentemente, deberemos disponer del diccionario "spanish" para Ispell).

Aunque no se pretende aquí explicar pormenorizadamente como funciona el interfaz Emacs/Ispell y la sintaxis de ispell-dictionary-alist (Para eso están los manuales), a continuación se incluye una configuración sencilla para los que no quieran quemar media neurona:

(setq ispell-dictionary-alist
'((nil ; español por defecto
   "[a-zA-ZáéíóúÁÉÍÓÚñÑüÜ]"
   "[^a-zA-ZáéíóúÁÉÍÓÚñÑüÜ]"
   "[']" t ("-C" "-d" "spanish") "~latin1")
  ("spanish"; podemos seleccionar español
   "[a-zA-ZáéíóúÁÉÍÓÚñÑüÜ]"
   "[^a-zA-ZáéíóúÁÉÍÓÚñÑüÜ]"
   "[']" t ("-C" "-d" "spanish") "~latin1")
  ("english" ; de vez en cuando, hay que escribir en inglés...
   "[A-Za-z]" "[^A-Za-z]" "[']" nil ("-B") nil)))

Donde realmente destaca Emacs/psgml es a la hora de escribir textos en sgml: su modo de terminación automática de marcas es la bomba.

$ db2html -d el-directorio/gdp-both.dsl gnome-libs-tutorial.sgml

Donde el-directorio es donde guardaste gdp-both.dsl.

Primero debes copiar gdp-both.dsl sobre /usr/lib/sgml/stylesheets/cygnus-both.dsl (Del paquete stylesheets. Asegúrate de que tienes una copia de seguridad de éste). Esto es así porque db2ps no acepta "-d" como el anterior :-(.

Sencillo: sigue las instrucciones que aparecen en la página del proyecto GDP.

Este es un problema de tetex: jadetex vuelca unos enormes documentos Tex y este error lo que indica es que tetex no está configurado para ser capaz de manejarlos.

Para arreglarlo basta que sigas estos dos pasos:

Te has olvidado de editar la marca <book>/<article>, dejalá como:

<book lang="es" id="index">

Jadetex no ha sido "compilado" con el soporte babel/spanish. Debes editar jadetex.dtx (Viene con jade).

En la linea que aparezca:

\RequirePackage[german,french,english]{babel}

Mete:

\RequirePackage[spanish,german,french,english]{babel}

Y haz un make -f Makefile.jadetex (También viene con jade). Esto creará jadetex.fmt y pdfjadetex.fmt. Sobreescribe los antiguos con estos nuevos.

No has instalado correctamente DocBook y/o stylesheets. Jade ha de ser capaz de encontrar los archivos de ambos paquetes. Instala los archivos en /usr/lib/sgml/ o utiliza la variable de entorno SGML_PATH.

Un recurso interesante en español es la lista sgml-es, especializada en todo lo referente a sgml/xml y a la que te puedes suscribir mandando un mensaje a sgml-esp-request@hispalinux.ctv.es con "subject" subscribe.

Si prefieres investigar un poco por tu cuenta, el mejor documento sobre DocBook/sgml que posiblemente puedas encontrar es DocBook: The Definitive Guide, de Norman Walsh y Leonard Muellner: un libro publicado por O'Reilly y que puedes consultar en linea en la página de DocBook. Como sospecharás, es bastante grande y con multitud de enlaces: te recomiendo que uses wget para bajártelo. Por ejemplo:

Una guía mucho más asequible y práctica es Get Going With DocBook: Notes for Hackers, de Mark Galassi que puedes obtener en multitud de formatos (sgml también: como no) de la página web del autor.

De todos modos, estos libros explican DocBook "desde los cimientos": para hacer la traducción no es necesario conocer la sintaxis de DocBook porque tenemos el original como "plantilla".