1. Descargando los archivos del sitio web
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.
Listado de Código 1.1: Descargando 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:
Listado de Código 1.2: Descargando el módulo gentoo |
$ 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.
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
Nuestra documentación GuideXML es transformada en HTML por el paquete www-servers/gorg Es necesario instalarlo.
Nota: Necesita al menos la versión gorg-0.6.3. Quizás necesite desenmascarar el paquete para su arquitectura. |
Siga las indicaciones en la página de gorg para configurarlo. Necesita establecer el directorio web raíz de gorg al directorio donde descargó el repositorio CVS (.../gentoo/xml/htdocs). El resto de los parámetros sólo son necesarios si desea servir una copia local de www.gentoo.org.
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:
Listado de Código 2.1: agregando catálogos al /etc/xml/catalog |
<rewriteURI uriStartString="/dtd/" rewritePrefix="/usr/portage/metadata/dtd/"/>
|
Nota: También puede reescribir las rutas para que apunten a los DTDs descargados en su copia del repositorio CVS. |
Si su archivo /etc/xml/catalog está vacío o no contiene entradas, necesita insertar el elemento <rewriteURI> dentro del elemento <catalog>.
Listado de Código 2.2: /etc/xml/catalog mínimo |
<?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:
Listado de Código 2.3: Modificación extra al /etc/xml/catalog |
<rewriteURI uriStartString="http://www.gentoo.org/dtd/" rewritePrefix="/usr/portage/metadata/dtd/"/>
|
Para probar una Guía Gentoo, primero utilice xmllint (de dev-libs/libxml2) para verificar que el documento contiene XML válido:
Listado de Código 2.4: Utilizando xmllint para validar GuideXML |
$ 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:
Listado de Código 2.5: Convirtiendo 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.
Nota: Los enlaces a capítulos en el Manual Gentoo no serán generados ya que éstos, en la versión en-línea, se acceden a través del archivo maestro y a través de los parámetros chap y part. |
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, explicado en página principal de gorg, si desea que la página principal de su copia local luzca como la página principal del sitio de Gentoo.
¿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:
Listado de Código 3.1: Utilizando recode en un documento |
(l9 = ISO-8859-15, u8 = UTF-8) $ recode l9..u8 archivo.xml |
4. Consejos para enviar un Documento
Asegúrese que el atributo <guide link> apunte a la dirección correcta para la guía. Generalmente esta ruta es /doc/${LANG}/nombrearchivo.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}/nombrearchivo.xml or nombrearchivo.xml. Generalmente la GDP recomienda el uso de la anterior.
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.
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.
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 Comúnes 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 (podrías ser regañado si se te 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, ejémplos 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 frecuente es actualizar el número de versión como si fuese un número decimal. No lo es. La versión 3.9 se actualizará a la 3.10, no a la 4.0, y tampoco a la 3.91.
El contenido de este documento está registrado bajo los términos de la licencia Creative Commons - Reconocimiento / Compartir Igual