Guía Metadoc XML de Gentoo

1.  Introducción

¿Por qué se necesita MetadocXML?

MetadocXML no es realmente necesario, se trata de un recurso adicional para que el Proyecto de Documentación siga la pista de los documentos, incluso si están localizados fuera del ámbito normal [gentoo]/xml/htdocs/doc.

Gracias a MetadocXML, podemos:

• seguir la pista de los documentos localizados dentro de los espacios web de los proyectos (/proj) en lugar de centrarnos solo en el repositorio normal de documentación (/doc).
• clasificar la documentación en varias categorías (o subcategorías) con el beneficio adicional de que podemos generar automáticamente el índice de la documentación (y algunas cosas más).
• seguir la pista de la documentación de miembros de equipos no oficiales (por ejemplo, traductores).
• utilizar partes de grandes documentos (manuales) como guías individuales en ciertos temas.
• asignar incidencias (bugs) a documentos particulares para una rápida referencia y tener la posibilidad de enmascarar un documento en caso de una incidencia severa.
• comprobar de forma primitiva si un fichero traducido está en sincronía con su original en inglés o no.

Observará que la última ventaja mencionada es primitiva y probablemente no será ampliada. Algunos equipos de traducción usan guiones basados en trads-doc para gestionar los documentos traducidos, otros utilizan herramientas de traducción en línea. Si va a comenzar a realizar traducciones para Gentoo, asómese por #gentoo-doc o pida ayuda en la lista de correo gentoo-doc@gentoo.org.

Los equipos de traducción que no utilicen MetadocXML no se tienen porqué preocupar, no perderán ninguna funcionalidad ya que se construye contra la infraestructura existente, no hay cambios al formato GuideXML que necesite MetadocXML.

¿Cómo funciona MetadocXML?

Existe un único fichero central en el que se mantiene toda la meta-información sobre la documentación. A este fichero lo llamamos metadoc.xml. Este fichero debería estar localizado en su repositorio principal (/doc/${IDIOMA}) aunque no está escrito explícitamente.

Dentro de este fichero se almacena toda la meta-información:

• Miembros del equipo
• Categorías en las que los documentos participan
• Ficheros cubiertos
• Documentos cubiertos
• Incidencias (Bugs) que son parte de un documento

Además de metadoc.xml, puede haber un documento generado dinámicamente (este fichero normalmente se llama index.xml), una lista global de toda la documentación (normalmente list.xml) y una vista global de todos los miembros, ficheros e incidencias (normalmente overview.xml).

2.  El fichero metadoc.xml

Estructura XML

El fichero metadoc.xml comienza con el código de inicialización XML y la información de cabecera CVS de Gentoo:

<?xml version='1.0' encoding="UTF-8"?>
<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/metadoc.xml,v 1.25 2004/12/23 09:51:30 swift Exp $ -->
<!DOCTYPE metadoc SYSTEM "/dtd/metadoc.dtd">

A continuación, comienza la declaración MetadocXML.

<metadoc lang="en">

Los traductores deben hacer referencia al fichero principal /doc/en/metadoc.xml en el atributo parent. Esto hace que metadoc identifique fichero sin traducir y busque si las versiones de los documentos traducidos coinciden con las originales.

<metadoc lang="código de idioma" parent="/doc/en/metadoc.xml">

Dentro de la entidad metadoc, se deben declarar las siguientes entidades (en el orden dado):

• version para ayudar en el seguimiento de los cambios.
• members que declara todos los miembros de un equipo de traducción.
• categories que declara las posibles categorías utilizadas.
• files que contiene todos los ficheros cubiertos por el fichero Metadoc.
• docs que contiene todos los documentos cubiertos por el fichero Metadoc.

La entidad version

El número de versión debe incrementarse cada vez que se añade o elimina un fichero o un documento, también cuando se cambia una ruta o cualquier otra actualización que tenga algún impacto en las versiones traducidas.

La entidad members

Dentro de la entidad members, se pueden declarar dos 'tipos' de miembros: lead y member. Un lead debe ser conocido por el equipo de Relaciones con los Desarrolladores de Gentoo (Gentoo Developers Relations) ya que consta únicamente del alias del desarrollador líder y se busca en la lista de miembros de Gentoo. Un member puede ser tanto un desarrollador Gentoo (en cuyo caso solo se muestra el aliar) o un contribuyente.

En el caso de un contribuyente, la etiqueta member posee dos atributos: mail y fullname, que contienen la dirección de correo y el nombre completo del contribuyente.

<members>
  <lead>chiguire</lead>
  <lead>nimiux</lead>
  <member>yoswink</member>
  <member mail="contribuyente-gentoo@gmail.com" fullname="Juan Nadie">jnad</member>
</members>

La entidad categories

Dentro de la entidad categories se declaran únicamente entidades cat. Cada entidad cat cubre una categoría. Utiliza un parámetro obligatorio: id que se utiliza para hacer referencia a la categoría. Puede también definir un parámetro parent en el caso en que la categoría sea hija de otra categoría.

En este caso, la atributo parent hace referencia al atributo id de la categoría padre.

<categories>
  <cat id="faq">Preguntas de uso frecuente</cat>
  <cat id="install">Recursos relacionados con la instalación</cat>
  <cat id="install_guides">Guías de Instalación</cat>
</categories>

La entidad files

La entidad files contiene únicamente entidades file.

Cada entidad file hace referencia a un solo fichero XML. Tiene un atributo obligatorio id que se debe usar como clave primaria para buscar el fichero. Metadoc comparará el nombre del fichero definido con el mismo atributo id en el fichero metadoc padre (definido en el elemento raíz) para averiguar si el fichero es una traducción on no. Los nombres de los ficheros deben ser idénticos en el segundo caso.

El propio fichero metadoc se puede listar y aparecerá en la página con la vista general (overview).

<files>
  <file id="metadoc">/doc/es/metadoc.xml</file>
  <file id="ati-faq">/doc/es/ati-faq.xml</file>
</files>

La entidad docs

La entidad docs debe contener únicamente entidades doc.

Cada entidad doc tiene un atributo id obligatorio que se usará como clave primaria del documento. Cada entidad doc tiene un atributo obligatorio fileid, que hace referencia al atributo id de una entidad file que corresponde con el fichero principal del documento.

En el caso de un capítulo de manual, la entidad doc debe contener una entidad bookref que hace referencia a la página principal del manual (el fichero XML principal del manual). Esta entidad contiene dos atributos llamados vpart y vchap que hacen referencia a la parte y capítulo correspondientes del documento dentro del manual.

Dentro de la entidad doc, pueden existir otras dos entidades:

• Una o más entidades memberof, que hacen referencia a la categoría o categoría en las que se localiza el documento (observar que un documento puede estar en varias categorías a la vez)
• Una entidad bugs que contiene una o más entidades bug. Una entidad bug hace referencia a un número de bug que cubre una incidencia con el documento. En el caso de una incidencia importante, se puede añadir el atributo stopper="yes" a la entidad bug para que el documento no aparezca en la página índice que se genera.

<docs>
  <doc fileid="ldap-howto">
    <memberof>sysadmin_specific</memberof>
    <bugs>
      <bug>102481</bug>
      <bug stopper="yes">1151330</bug>
    </bugs>
  </doc>
  <doc fileid="uml">
    <memberof>sysadmin_general</memberof>
  </doc>
</docs>

Fichero ejemplo metadoc.xml

El sitio de Gentoo utiliza un fichero metadoc.xml para agregar la información contenida en su documentación. Puede ver la versión actual en línea.

3.  Fichero adicionales MetadocXML

Índice generado automáticamente

Si se desea un índice generado automáticamente, se debe comenzar el documento con el siguiente código:

<?xml version='1.0' encoding='UTF-8'?>
<?xml-stylesheet href="/xsl/metadoc.xsl" type="text/xsl"?>
<?xml-stylesheet href="/xsl/guide.xsl"   type="text/xsl"?>

<!-- $Header$ -->

<!DOCTYPE dynamic SYSTEM "/dtd/metadoc.dtd">

<!-- Sustituya "/doc/es/metadoc.xml" por la localización de su fichero metadoc -->
<dynamic metadoc="/doc/es/metadoc.xml">
<title>Recursos de documentación de Gentoo</title>
<intro>

(...)

</intro>

<catid>faq</catid>
<catid>install</catid>

</dynamic>

Entre las etiquetas intro debe escribir una o más secciones que siempre aparecerán al comienzo de la página. Probablemente quiera escribir una introducción y alguna información adicional para que el lector sepa con quién contactar en caso de errores en la traducción u otras cuestiones.

Dentro de las etiquetas intro puede utilizar texto GuideXML que comience con la etiqueta section.

Las etiquetas catid hacen referencia a las categorías principales utilizadas or el índice dinámico. Debe listar cada categoría posible que no sea terminal y que esté declarada en su fichero metadoc. No liste categorías que son hijas de otras categorías.

Documento tipo lista generado dinámicamente

Un documento tipo lista que se genera dinámicamente comienza de forma similar a un fichero índice generado automáticamente.

<?xml version='1.0' encoding='UTF-8'?>
<?xml-stylesheet href="/xsl/metadoc.xsl" type="text/xsl"?>
<?xml-stylesheet href="/xsl/guide.xsl"   type="text/xsl"?>

<!-- $Header$ -->

<!DOCTYPE dynamic SYSTEM "/dtd/metadoc.dtd">

<!-- Sustituya "/doc/es/metadoc.xml" por la localización de su fichero metadoc -->
<dynamic metadoc="/doc/es/metadoc.xml">
<title>Listado de documentación Gentoo</title>

Sin embargo, no posee la etiqueta intro. Lo que se necesita añadir en este caso son todas las categorías de primer nivel que se van a usar en el listado. Para diferenciar este documento del índice (que también mostrará la información de resumen en cada documento), las categorías se añaden entre etiquetas list dentro de una etiqueta listing:

<listing>
  <list>faq</list>
  <list>install</list>
</listing>

Documento tipo sumario generado automáticamente

El documento tipo sumario (vista general) comienza de forma similar a los dos documentos descritos automáticamente:

<?xml version='1.0' encoding='UTF-8'?>
<?xml-stylesheet href="/xsl/metadoc.xsl" type="text/xsl"?>
<?xml-stylesheet href="/xsl/guide.xsl"   type="text/xsl"?>

<!-- $Header$ -->

<!DOCTYPE dynamic SYSTEM "/dtd/metadoc.dtd">

<!-- Sustituya "/doc/es/metadoc.xml" por la localización de su fichero metadoc -->
<dynamic metadoc="/doc/es/metadoc.xml">
<title>Vista general de la documentación</title>

Puede, de nuevo, escribir una pequeña introducción en formato GuideXML entre las etiquetas XML intro, comenzando con una etiqueta section. Una vez terminado, una etiqueta <overview/> simple será suficiente.

<intro>
(...)
</intro>

<overview/>

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.