Guía Gentoo de GuideXMLLa sintaxis de GuideXML es sencilla pero expresiva, por eso es fácil de aprender y al mismo tiempo proporciona todas las características necesarias para la creación de documentación Web. El número de etiquetas es muy pequeño -- solamente las necesarias. Esto hace muy fácil la transformación de la guía a otros formatos, tales como DocBook XML/SGML y páginas web (HTML). El objetivo es facilitar la creación y transformación de documentos guía, como este, en XML. Si planea contribuir a la documentación de Gentoo, o quiere probar la GuideXML, por favor lea nuestra guía de Trucos y Consejos, que contiene trucos y consejos para el desarrollo de documentación. Tal le interese mirar las fuentes XML de este documento mientras lo lee. Vamos a comenzar con el aprendizaje de la sintaxis de GuideXML. Comenzaremos con las etiquetas iniciales usadas en un documento de guía en XML:
En las primeras líneas, encontramos la etiqueta necesaria que
identifica este documento como un documento XML y especifica su
DTD. La línea <!-- $Header$ --> será modificada
automáticamente por el servidor CVS y sirve para llevar la cuenta de
las revisiones. Le sigue una etiqueta <guide> -- el
documento guía está encerrado completamente entre etiquetas
<guide> y </guide>.
Después, hay una etiqueta <title>, usada para colocar el título del documento de la guía. Luego, vienen las etiquetas <author>, que contienen información sobre los autores del documento. Cada etiqueta <author> permite un atributo opcional title, usado para especificar la relación del autor con el documento (autor, co-autor, editor, etc.). En este ejemplo en particular, los nombres de los autores están encerrados en otra etiqueta -- una etiqueta <mail>, usada para especificar una dirección email para esta persona en particular. La etiqueta <mail> es opcional y puede ser omitida, requiriéndose al menos un elemento <author> por cada documento de guía. Lo siguiente, llegamos a las etiquetas <abstract>, <version> y <date>, usadas para especificar un resumen del documento, la versión actual, y la fecha de la versión (en formato AAAA-MM-DD) respectivamente. Fechas que no sean válidas o que no estén en formato AAAA-MM-DD aparecerán textualmente en el nuevo documento. Esto es todo en cuanto a las etiquetas que deben aparecer al comienzo del documento. Estas etiquetas, salvo <title> y <mail>, no deberían aparecer en ningún otro lugar que no sea inmediatamente dentro de la etiqueta <guide>, y por consistencia, se recomienda (aunque no es obligatorio) que esas etiquetas, aparezcan antes que el contenido del documento. Finalmente encontramos la etiqueta <license version="3.0"/>, usada para publicar el documento bajo la licencia Creative Commons - Attribution / Share Alike como se requiere en la Política de documentación. Anteriormente, se utilizaba la etiqueta <license />, la cual indicaba la utilización de la versión 2.5 de la licencia. Esta versión todavía se permite y admite. Una vez que las etiquetas iniciales han sido especificadas, estamos listos para empezar a añadir los elementos estructurales del documento. Los documentos de guía están divididos en capítulos, y cada capítulo puede tener una o más secciones. Cada capítulo y cada sección tiene su título. Aquí hay un capítulo de ejemplo con una sola sección, consistente en un párrafo. Si agrega este XML al XML del ejemplo anterior y añade </guide> al final del fichero, tendrá un documento de guía válido (aunque mínimo):
Arriba, ajustamos el título del capítulo añadiendo un elemento hijo <title> al elemento <chapter>. Luego, creamos una sección añadiendo un elemento <section>. Si observa en el interior del elemento <section>, verá que contiene dos elementos hijos -- un elemento <title> y otro <body>. Mientras que el elemento <title> no es nada nuevo, el elemento <body> sí lo es -- es el contenido de texto de esta sección. Veamos dentro de poco qué etiquetas se permiten dentro de un elemento <body>.
Ahora, es el momento de aprender a maquetar los contenidos. Aquí está el código XML de un ejemplo de un elemento <body>:
Ahora, aquí se ve cómo se queda el elemento <body> antes descrito: Esto es un párrafo. /etc/passwd es un fichero. http://forums.gentoo.org es mi sitio web favorito. Escriba ls si lo quiere así. Yo de veras quiero irme a dormir ahora.
Hemos visto un montón de nuevas etiquetas en la sección anterior -- aquí está lo que necesita saber de ellas. Las etiquetas <p> (párrafo), <pre> (bloque de código), <note> (nota), <warn> (advertencia) y <impo> (importante) todas pueden contener una o más lineas de texto. Además, junto a los elementos <table> (los cuales veremos después), son las únicas etiquetas que deben aparecer inmediatamente dentro de un elemento <body>. Otra cosa -- estas etiquetas no deben ser apiladas -- en otras palabras, no deben apilarse, o sea, no ponga un elemento <note> dentro de un elemento <p>. Como puede imaginar, el elemento <pre> conserva los espacios en blanco exactamente igual, haciéndolo adecuado para ejemplos de código. Es obligatorio nombrar la etiqueta <pre> con un atributo caption:
Delegados de los 13 estados originales formaron el Congreso
Contento. Thomas Jefferson, un virgen y Benjamín Franklin fueron dos
de los cantantes de la Declaración de la Independencia. Franklin
descubrió la corriente eléctrica frotando dos gatos hacia atrás y
declaró "Un caballo dividido entre sí mismo no puede mantenerse de
pie." Franklin murió en 1790 y todavía lo está.
Los epígrafes son utilizados a veces al comienzo de algunos párrafos para ilustrar lo que viene. Es solo un párrafo con un atributo by que contiene la firma.
<path>, <c>, <b>, <e>, <sub> and <sup> Los elementos <path>, <c>, <b>, <e>, <sub> y <sup> pueden ser usados dentro de cualquier hijo de <body>, excepto dentro del elemento <pre>. Los elementos <path> se usan para marcar texto que hace referencia a ficheros en disco -- tanto si es una ruta absoluta o relativa, o si es simplemente un nombre de fichero. Este elemento generalmente se muestra con una fuente monoespaciada para diferenciarlo del tipo estándar del párrafo. El elemento <c> se usa para marcar una orden o entrada del usuario. Piense en <c> como un medio de avisar al lector que pueden escribir algo o que realizarán en algún tipo de acción. Por ejemplo, todos las etiquetas XML mostradas en este documento, están encerradas entre etiquetas <c> porque representan algo que el usuario podría escribir en algo que no es una línea de comandos. Usando elementos <c>, ayudará a sus lectores a que identifiquen rápidamente las órdenes que necesitan escribir. También porque los elementos <c> se diferencian del texto normal, casi no hará falta rodear la entrada del usuario con dobles comillas. Por ejemplo, no se refiera al elemento "<c>" como aparece en esta frase. Evitar el uso innecesario de dobles comillas hace que el documento sea más legible -- ¡y adorable! Tal como probablemente ha podido adivinar, la <b> se utiliza para enfatizar con negritas. <e> se usa para aplicar énfasis a una palabra o frase; por ejemplo: Yo realmente debería usar puntos y comas más a menudo. Como puede ver, este texto se distingue del párrafo normal con el énfasis. Esto ayuda a hacer darle más impacto a su prosa. Los elementos <sub> y <sup> se utilizan para especificar subíndice y superíndices. Ejemplos de código y codificación con colores Para incrementar la legibilidad de ejemplos de código, se permite el uso de las siguientes etiquetas dentro de bloques <pre>:
Ejemplo de un bloque <pre> codificado con colores:
Anteriormente echamos un vistazo a la etiqueta <mail> ; se usa para enlazar un texto con una dirección de corre electrónico, y tiene la forma <mail link="foo.bar@example.com">Mr. Foo Bar</mail>. Si desea mostrar la dirección de email, puede usar <mail>foo.bar@example.com</mail>, lo cual se vería como foo.bar@example.com.
Las formas abreviadas facilitan el uso de nombres y direcciones de
correo de desarrolladores Gentoo. Ambas formas
<mail>neysx</mail> y <mail
link="neysx"/> aparecerán como Xavier Neys. Si desea
usar un correo de un desarrollador Gentoo con un contenido distinto a
su nombre completo, use la segunda forma con algún contenido. Por
ejemplo, usar el primer nombre del desarrollador: <mail
link="neysx">Xavier</mail> aparece como Xavier.
La etiqueta <uri> se usa para apuntar a ficheros/localizaciones en Internet. Tiene dos formas -- la primera puede usarse cuando se quiere tener la URI mostrada en el cuerpo del texto, como en este enlace a http://forums.gentoo.org. Para crear este enlace, escribí <uri>http://forums.gentoo.org</uri>. La forma alternativa es cuando se quiere asociar una URI con otro texto -- por ejemplo, Foros de Gentoo. Para crear este enlace, escribí <uri link="http://forums.gentoo.org"> Foros de Gentoo</uri>. No necesita escribir http://www.gentoo.org/ para enlazar otras partes del sitio Web de Gentoo. Por ejemplo, para enlazar al índice principal de la documentación simplemente sería <uri link="/doc/es/index.xml">índice principal de la documentación</uri>. Hasta puede omitir index.xml cuando apunte directamente al índice de un directorio, ejemplo: <uri link="/doc/es/">índice principal de la documentación</uri>. El dejar la barra final ahorra una petición HTTP adicional. No debe usar una etiqueta <uri> con un atributo link que comience con mailto:. En este caso, haga uso de la etiqueta <mail>. Por favor evite el síndrome de haga clic aquí tal como nos recomienda el W3C. Así se inserta una imagen en un documento -- <figure link="mygfx.png" short="mi imagen" caption="mi imagen favorita de todos los tiempos"/>. El atributo link= apunta a la imagen, el atributo short= especifica una descripción corta (actualmente usada para el atributo alt= de HTML), y una leyenda. No es demasiado difícil :) También soportamos el estilo estándar de HTML con la etiqueta <img src="foo.gif"/> para añadir imágenes sin leyendas, bordes, etc. GuideXML soporta una sintaxis simplificada para tablas, similar al de HTML. Para comenzar una tabla, use la etiqueta <table>. Comience una hilera con una etiqueta <tr>. Sin embargo, para los datos propios de la tabla, no soportamos el uso de la etiqueta <td> de HTML; en cambio, use <th> para la cabecera y <ti> si va a insertar un bloque de información normal. Puede usar <th> en cualquier lugar donde se pueda usar <ti> -- no hay obligación que los elementos <th> aparezcan solo en la primera hilera. Los encabezados de tabla (<th>) y los ítems de tabla (<ti>) aceptan los atributos colspan y rowspan para que su contenido abarque columnas, hileras o ambas Además los ítems de tabla (<ti>) pueden alinearse a la derecha, a la izquierda o centrados con el atributo align.
Para crear listas, ordenadas o no, simplemente use las etiquetas <ol>, <ul> y <li> al estilo XHTML. Las listas solo deben aparecer dentro de las etiquetas <body> y <li> lo cual significa que pueden hacerse listas dentro de listas. No se olvide que está escribiendo XML y que debe colocar las etiquetas de cierre, incluyendo ítems en listas, a diferencia de HTML. También soportamos listas de definiciones (<dl>). Por favor note que ni la etiqueta de definición de término (<dt>) ni la de definición de datos (<dd>) aceptan etiquetas de otro nivel, como de párrafo o advertencia. Una lista de definición se parece a esta:
La siguiente lista, copiada de w3.org muestra que una lista de definición puede contener listas ordenadas y sin orden, sin embargo, no puede contener otra lista de definición.
Referencias Internas en el Documento GuideXML hace que sea realmente sencillo referenciar a otras partes del documento con hiperenlaces. Se puede crear un enlace que apunte al Capítulo Uno escribiendo <uri link="#doc_chap1">Capítulo Uno</uri>. Para apuntar a la sección dos del Capítulo Uno, se escribe <uri link="#doc_chap1_sect2">la sección dos del Capítulo Uno</uri>. Para hacer una referencia a la figura 3, se escribe <uri link="doc_fig3">figura 3</uri>. O para referirse al listado de código 2 , se escribe <uri link="doc_pre2">listado de código 2</uri>. Sin embargo, algunas guías cambian a menudo y al emplear este 'conteo' pueden producirse enlaces rotos. Para hacer frente a esto, se puede definir un nombre para el <capítulo>, <sección> o <tr> con el atributo id y después apuntarlo así:
Renuncias de responsabilidad y documentos obsoletos El atributo disclaimer puede ser aplicado a guías y manuales para desplegar un aviso predefinido de renuncia de responsabilidad al comienzo del documento. Los textos de renuncia de responsabilidad disponibles son:
Al marcar un documento como obsoleto, tal vez desee agregar un enlace a una versión nueva. El atributo redirect hace justamente eso. El usuario puede ser redirigido automáticamente a la página nueva, pero no debe depender de este comportamiento.
Los documentos FAQ (preguntas de uso frecuente) necesitan comenzar con una lista de preguntas enlazadas a sus respuestas. Se pierde mucho tiempo creando este tipo de lista y se pueden cometer errores. Este tipo de lista puede ser creada automáticamente si usa el elemento faqindex como el primer capítulo del documento. Este elemento tiene la misma estructura que un chapter y permite un texto introductorio. Se espera que la estructura del documento se divida en capítulos (al menos uno), que contenga secciones, cada sección con una pregunta especificada en su elemento title y con la respuesta en su body. El índice aparecerá como una sección por capítulo y un enlace por pregunta. Una mirada rápida a FAQ y sus fuentes nos proporcionará todas las explicaciones necesarias. Para documentación de alto volumen, como las Instrucciones de Instalación se necesitaba un formato más amplio. Diseñamos unas mejoras compatibles con GuideXML que nos permiten escribir documentación modular y multi-página. El primer cambio responde a la necesidad de un documento "maestro". Este documento realmente no comprende verdadero contenido, sino enlaces a los módulos individuales del documento. La sintaxis no difiere mucho de GuideXML:
Por los momentos no se ven diferencias sustanciales (excepto por la etiqueta <book> en vez de <guide>). En vez de comenzar con los <chapter>s (capítulos) individuales, definimos un <part>, el cual equivale a una parte separada de un libro:
Cada "part" se acompaña de un <title> y un resumen (<abstract>) que proporciona una introducción resumida a la parte. Dentro de cada parte, definimos los capítulos individuales (<chapter>s). Cada capítulo debe ser un documento separado. Como resultado, no es de sorprenderse que podamos agregar una etiqueta especial (<include>) para permitir la inclusión del documento separado.
Diseñando los capítulos individuales El contenido de un capítulo individual se estructura de la siguiente manera:
En cada capítulo se pueden definir secciones (<section>s) que equivale a un capítulo (<chapter>) en una Guía y subsecciones (<subsection>s), que equivalen a una sección (<section>) en una Guía. Cada capítulo individual debe tener sus propios elementos para fecha y versión. La última fecha de todos los capítulos y documento maestro será desplegada cuando un usuario consult las distintas partes del libro. 4. Características avanzadas del manual A veces se repiten los mismos valores una y otra vez a través del manual. Una operación global de búsqueda y reemplazo podría pasar algo por alto o introducir cambios no deseados. Además, puede ser útil definir diferentes valores a ser usados en capítulos compartidos, dependiendo de cual manual incluya el capítulo. Los valores globales pueden ser definidos en el archivos maestro del manual y usados en todos los capítulos incluidos. Para definir valores globales, agregue el elemento <values> al archivo maestro del manual. Cada valor es definido con un elemento <key> cuyo atributo id identifica el valor, o sea, el nombre de la variable. El contenido de <key> corresponde a su valor. El siguiente ejemplo define tres valores en un archivo maestro de un manual:
Los valores definidos pueden entonces ser usados a través del manual con el elemento <keyval id="key_id"/>. Especifique el nombre de la clave (key) en su atributo id, por lo que <keyval id="min-cd-name"/> sería reemplazado por "install-x86-minimal-2007.0-r1.iso" en el ejemplo.
Para facilitarle la vida a nuestros traductores, use solo valores que no requieran traducción. Por ejemplo, definimos el valor de min-cd-size como 57 y no 57 MB. Los capítulos compartidos por varios manuales, tales como nuestro Manuales de Instalación frecuentemente tienen pequeñas diferencias, dependiendo de cuál manual los incluy. En vez de agregar contenido que sea irrelevante a algunos manuales, los autores pueden agregar una condición a los siguientes elementos: <section>, <subsection>, <body>, <note>, <impo>, <warn>, <pre>, <p>, <table>, <tr>, <ul>, <ol> y <li>. La condición debe ser una expresión Xpath que será evaluada al transformar el XML. Si evalúa a true, este elemento es procesado, si no, es ignorado. La condición es especificada en un atributo test. El siguiente ejemplo usa el valor arch, el cual es definido en cada archivo maestro de manual para condicionar el contenido:
Puesto que toda la documentación de Gentoo es esfuerzo conjunto y probablemente varias personas cambiarán la documentación existente, es necesario un estilo de codificación. Un estilo de codificación abarca dos secciones. La primera es relativa a la codificación interna - como se sitúan las etiquetas XML. La segunda trata sobre el contenido - como no confundir al lector. Ambas secciones se describen a continuación. Estilo de codificación interno Los fines de línea deben ponerse inmediatamente después de cada etiqueta GuideXML (tanto de apertura como de cierre) exceptuando: <version>, <date>, <title>, <th>, <ti>, <li>, <i>, <e>, <uri>, <path>, <b>, <c>, <comment>, <mail>. Deben situarse líneas en blanco inmediatamente después de cada <body> (solo de apertura) y antes de cada <chapter>, <p>, <table>, <author> (conjunto), <pre>, <ul>, <ol>, <warn>, <note> e <impo> (solamente de apertura). Los ajustes de líneas (word wrap) deben ser aplicados a los 80 caracteres, excepto dentro de <pre>. Solamente se puede desviar de esta regla cuando no hay otra opción (por ejemplo cuando una URL excede el máximo de caracteres). El editor debe entonces ajustar la línea en cuanto exista el primer espacio en blanco. Debe intentar mantenerse el contenido desplegado de los elementos <pre> dentro de 80 columnas para ayudar a los usuarios de consola. No debemos usar sangrías, excepto con las estructuras XML cuyas etiquetas padres sean <tr> (procedente de <table>), <ul>, <ol> <dl> y <author>. Si se usan sangrados, estos obligatoriamente debe ser de dos espacios por cada paso de sangrado. Esto significa que nada de tabs ni de más (de dos) espacios. Dicho sea de paso, que las tabulaciones no están permitidas en los documentos GuideXML. En caso de tener que ajustar las líneas con construcciones de tipo <ti>, <th>, <li> o <dd>, debe usarse el sangrado para el contenido. Un ejemplo de sangrado sería:
Los atributos no deben tener espacios entre sí, el signo "=" y el valor del atributo. Como en el ejemplo:
Estilo de codificación externa Dentro de las tablas (<table>) y los listados (<ul>, <ol>) y <dl>, no deben usarse puntos finales (".") a menos que se usen varias oraciones. En ese caso, cada oración debería acabar en un punto (u otras marcas de puntuación). Cada oración, incluyendo aquellas dentro de tablas y listados, debe empezar por una letra mayúscula.
Los listados de código deben tener siempre una leyenda Intente utilizar <uri> con el atributo link tanto como sea posible. En otras palabras, los Foros de Gentoo se prefiere en vez de http://forums.gentoo.org. Cuando comente algo dentro de una construcción <pre>, utilice <comment> y ponga entre paréntesis el comentario o la marca de comentario para el lenguaje que se utiliza (# si es para guiones bash y muchas otras cosas, // si es código C, etc.) Además sitúe el comentario antes del tema del comentario.
Esta guía ha sido diseñada especialmente para ser "clara y directa" para que los desarrolladores puedan pasar más tiempo escribiendo documentación y menos tiempo aprendiendo la sintaxis XML. Esperamos que esto permitirá a los desarrolladores que no son muy conocedores de la documentación, comenzar a escribir documentación Gentoo de gran calidad. Quizá esté interesado en nuestra página de Trucos y consejos sobre Documentación de Desarrollo. Si quiere ayudar (o tiene alguna duda sobre la guía), por favor mande un mensaje a la lista de correo gentoo-doc comentando lo que le gustaría saborear. ¡Diviértase! 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. |
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||