Desarrollo de documentación. Trucos y consejos

1.  Descargando los archivos del sitio web

Usando CVS anónimo

Los colaboradores deberían utilizar Servidor CVS anónimo. Este servidor contiene los mismos archivos que el repositorio CVS oficial que es utilizado por los desarrolladores de Gentoo. El repositorio CVS anónimo es actualizado cada hora.

Cree un directorio dedicado únicamente al desarrollo de la documentación, luego, descargue los archivos del sitio web.

$ cvs -d :pserver:anonymous@anoncvs.gentoo.org/var/cvsroot co gentoo/xml

Para actualizar su copia del repositorio, ejecute cvs update -dP en el directorio gentoo/xml.

Repositorio para desarrolladores Gentoo

Si no ha descargado el módulo gentoo, hágalo ahora:

$ export CVSROOT=<su apodo>@cvs.gentoo.org:/var/cvsroot
$ cvs co gentoo/xml

Para actualizar el repositorio, ejecute cvs update -dP en el directorio gentoo/xml.

Repositorio CVS en línea

Puede solicitar nuestro Repositorio CVS en línea para proveer las diferencias entre versiones individuales. El repositorio principal en inglés está completamente disponible. El repositorio en línea es actualizado cada hora.

2.  Configurando su entorno local

Instalando gorg

Nuestra documentación GuideXML es transformada en HTML por el paquete www-servers/gorg. Es necesario instalarlo.

Siga estas indicaciones para configurar gorg. Necesitará definir el directorio raíz web en el cual ha obtenido nuestro repositorio CVS (.../gentoo/xml/htdocs). Los otros parámetros sólo son útiles si quiere servir una copia local de www.gentoo.org.

Configurando su Entorno XML

Su sistema necesita conocer la ubicación de los DTDs que utiliza nuestra documentación. Edite /etc/xml/catalog como el usuario root y agregue las siguientes líneas:

<rewriteURI uriStartString="/dtd/" rewritePrefix="/usr/portage/metadata/dtd/"/>

Si su archivo /etc/xml/catalog está vacío o no contiene entradas, necesita insertar el elemento <rewriteURI> dentro del elemento <catalog>.

<?xml version="1.0"?>
<!DOCTYPE catalog PUBLIC "-//OASIS//DTD Entity Resolution XML Catalog V1.0//EN" "http://www.oasis-open.org/committees/entity/release/1.0/catalog.dtd">
<catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog">
  <rewriteURI uriStartString="/dtd/" rewritePrefix="/usr/portage/metadata/dtd/"/>
</catalog>

Algunos archivos especifican el DTD en línea con un uri como este: http://www.gentoo.org/dtd/guide.dtd. Puede reescribir estas referencias para evitar accesos innecesarios y lentos a Internet al momento de la validación:

<rewriteURI uriStartString="http://www.gentoo.org/dtd/" rewritePrefix="/usr/portage/metadata/dtd/"/>

Probando una Guía Gentoo

Para probar una Guía Gentoo, primero utilice xmllint (de dev-libs/libxml2) para verificar que el documento contiene XML válido:

$ xmllint --valid --noout alsa-guide.xml

Si xmllint no muestra ninguna salida, entonces la estructura del archivo es válida. Ahora es necesario convertir el documento a HTML:

$ gorg < alsa-guide.xml > alsa-guide.html

Si el comando anterior no muestra errores, puede entonces apuntar su navegador a alsa-guide.html para ver el documento en formato HTML. Si se muestran errores modifique su documento hasta que funcione.

Navegando en su copia local del sitio web de Gentoo

Ya que ha descargado el sitio web de Gentoo desde nuestro servidor CVS, entonces puede utilizar gorg para navegar en su copia local. Asegúrese que ha descargado el índice de noticias si desea que la página principal de su copia local luzca como la página principal del sitio de Gentoo.

3.  Preguntas Frecuentes

¿Cómo convierto un archivo a UTF-8?

Existen algunas herramientas que le pueden ayudar. Una herramienta popular es app-text/recode. Otra es iconv, que forma parte de sys-libs/glibc.

El uso de recode es bastante sencillo. Basta con decirle qué codificación utiliza el documento y a qué codificación quiere transformarlo.

Por ejemplo, para convertir un documento desde ISO-8859-15 (también conocido como Latin-9) a UTF-8, basta con utilizar:

(l9 = ISO-8859-15, u8 = UTF-8)
$ recode l9..u8 archivo.xml

4.  Consejos para enviar un Documento

Revisión de etiquetas <guide>

Asegúrese que el atributo <guide link> apunte a la dirección correcta para la guía. Generalmente esta ruta es /doc/${LANG}/nombredearchivo.xml. Si ha traducido un documento, siempre especifique la ruta absoluta al mismo (ej. /doc/${LANG}/). Si se encuentra escribiendo una guía que utilice los DTDs guide o book pueden entonces especificar las rutas como /doc/${LANG}/nombredearchivo.xml or nombredearchivo.xml. Generalmente la GDP recomienda el uso de la anterior.

Verificando Enlaces

Debe verificar que todos los hiper-vínculos en su documento funcionen. Si es un documento traducido, asegúrese que todos los enlaces a otros documentos traducidos apunten a archivos existentes.

Verificando Tabulaciones

Las tabulaciones están absolutamente prohibidas en documentos bajo GuideXML con la excepción de aquellos casos en que sea requerido (ej. si el documento le indica al usuario que utilice tabulaciones). Para validar que un documento no contenga tabulaciones, ejecute grep "CTRL+V<TAB>" archivo.xml. Arregle cualquier línea que grep haya mostrado.

Bugzilla

Una vez que haya terminado su documento, envíelo al Equipo de Documentación utilizando Bugzilla. Aquí, no tiene que especificar información como la plataforma, salida de emerge info, arquitectura, pasos para reproducir, etc. Si tiene un documento traducido, asegúrese de seleccionar el componente Doc Translations para su bug. Incluya también un sumario adecuado para su traducción utilizando el formato: "[es]" New translation: /doc/es/gnupg-user.xml". Reemplace [es] por el código de dos letras de su lenguaje.

Por defecto, el ticket será asignado a docs-team@gentoo.org. No hay necesidad de cambiar a quien será asignado el ticket.

Suba los archivos y/o parches al bug utilizando la opción de texto plano (text/plain). No seleccione "fuente XML (application/xml)" aún cuando se disponga a subir un archivo .xml. Los parches deben tener la opción "Patch" seleccionada. No envíe archivos comprimidos llenos de documentos; suba cada documento y/o parche individualmente.

5.  Errores Comunes y Peligrosos

Olvidar el aspecto multi-arquitectura del Manual de Gentoo

Los archivos en [gentoo]/xml/htdocs/doc/en/handbook que no terminen con el sufijo "-<arch>.xml" son leidos por todos los manuales, lo cual significa que cualquier cosa que contenga será multi-arquitectura.

Si necesita hacer modificaciones que afecten a una arquitectura en particular y teme necesitar situarlas en ese archivo, puede preguntar cómo solucionarlo en gentoo-doc@gentoo.org. A veces existe la manera sin ser demasiado compleja para usuarios de otras arquitecturas.

No saltar de versión/fecha o hacerlo de manera incorrecta

De acuerdo con la política, debe saltar (avanzar) de versión/fecha cuando se produzcan cambios. Aunque la versión es menos importante (el responsable del GDP podría regañarle si se le olvida) la fecha indica a nuestros usuarios cuando el documento ha sido actualizado por última vez.

Si está haciendo un cambio de contenido a un documento (tal como instrucciones, ejemplos de código, etc.), debe entonces incrementar la versión. Para cambios no relacionados con contenidos (ej. un error de escritura o arreglos al GuideXML), el salto de versión normalmente es innecesario.

Cuando esté actualizando el Manual, modifique la versión y la fecha solamente de los archivos que modifique. No salte la versión de un Manual-ARCH.xml a menos de que realmente haya cambiado su contenido.

Otro error común es actualizar la versión usando números con decimales. No debe hacer esto. La versión es un simple número entero. Cada actualización debe incrementar este número en uno. De 9 se debe pasar a 10, no a 9.1. Para documentos antiguos que todavía no estén usando esta forma de numerar las versiones, por favor, incremente el número al entero más cercano la próxima vez que envíes su trabajo. Por lo tanto, 4.67 debe pasar a 5, 1.2 a 2, y así sucesivamente.

El contenido de este documento, a no ser que se especifique expresamente, está registrado bajo los términos de la licencia CC-BY-SA-2.5. Se aplican las Pautas de Utilización del logotipo y nombre de Gentoo.