Mallard PRCTICO

Maplerose, sxc.hu

Creacin de documentos con Mallard

AL TEMA
Una sintaxis sencilla y su estructura modular hacen de Mallard el punto de partida ideal para la creacin de documentacin temtica. POR MARIO BLTTERMANN
i desarrollamos software basado con una interfaz grfica de usuario, tiene sentido ayudar a nuestros fieles usuarios con un manual para cuando se atasquen. Escribir documentacin de ayuda pueden ser algo pesado. El tpico formato Docbook generalmente se considera y con razn complicado, y presenta una enorme curva de aprendizaje. Muchos desarrolladores y especialistas en documentacin se estn pasando a Mallard como alternativa para crear documentacin de ayuda al usuario. Mallard es similar a Docbook si nos fijamos en la estructura lgica, pero utiliza muchas menos etiquetas y simplifica considerablemente la sintaxis. Mallard [1] est especficamente diseado para crear documentos de ayuda. En otras palabras, es ideal para situaciones en las que la informacin est organizada en pequeos elementos orientados a tareas o temas. El diseo obliga al autor a trabajar de una manera basada en temas y no a simplemente encadenar un montn de informacin en un texto esttico. De acuerdo con el proyecto Mallard, una buena ayuda online tiene tres caractersticas importantes: Los usuarios pueden navegar hasta la informacin, siguiendo una ruta que se ajuste a su modelo mental.

Los usuarios encuentran la informacin que necesitan acerca de un tema sin tener que leer ms informacin introductoria de la necesaria. Los usuarios pueden aprender ms si optan por seguir los enlaces de informacin ms detallada. Mallard nos ayuda a crear documentos que incorporan estas caractersticas. Pone el nfasis en los temas pequeos, divididos en fragmentos e interconectados mediante enlaces. El formato basado en XML que usa Mallard hace muy fcil el ampliar documentos de ayuda al poder insertar nuevos temas sin modificar la estructura existente. El proyecto Mallard define un formato que puede verse por cualquier herramienta capaz de visualizar archivos Mallard; y recomienda el visor de ayuda Gnome Yelp como un ejemplo de visualizador preparado para Mallard.

Primeros Pasos
El Listado 1 muestra un archivo mnimo de Mallard. El ndice es la raz en la que se basa el resto de archivos. Los encabezados indican que es una gua guide desde el punto de vista de contenido, una tarea task estilsticamente, y un ndice index desde un punto de vista organizativo. Esto ltimo es importante para ase-

gurarse de que las otras pginas asuman los lugares correctos en la documentacin. Las restantes lneas dicen algo sobre el autor y la licencia. Despus de un corta introduccin, se llega a los textos que veremos ms adelante. La <section> crea una seccin, que puede estar vaca excepto que contiene el ttulo. Al aadir id=introduction a la etiqueta XML de apertura se asegura que el analizador cree un archivo de pgina con esta ID exactamente aqu y no en otra parte del documento principal. Consulte el Listado 2 para la estructura del archivo de pgina. La lnea tres del Listado 2 define la ID, la cual se confirm suministrando un enlace en la lnea 6. Podemos agregar ms temas y subtemas de la misma manera. Estos listados demuestran la sencilla sintaxis de Mallard. Si no estamos preocupados por dar a sus elementos de texto un aspecto sofisticado, al menos por el momento, no tendremos problemas para empezar. Ms tarde, todava podremos aadir informacin de estilo dentro de las etiquetas XML de apertura, que sern tratadas por otras herramientas. Mallard tambin hace la vida ms fcil para el usuario: en lugar de utilizar etiquetas diferentes para expresar los dife-

WWW.LINUX- MAGAZINE.ES

Nmero 80

27

PRCTICO Mallard

Debido a que es necesario crear un archivo de pgina para cada tema y generalmente cada subtema, en un primer momento esto podra confundir a los usuarios muy acostumbrados a Docbook, ya que estn habituados a un nico archivo de gran tamao que slo mantiene Figura 1: Gedit tiene soporte para Mallard desde hace algn tiempo. la declaracin de licencia en alguna rentes elementos de la interfaz grfica de parte externa. Sin embargo, separar las usuario (por ejemplo, <guilabel> , cosas tiene sus ventajas: si asignamos <guimenuitem> y <guibutton> en nombres intuitivos a los archivos indiviDocBook), simplemente usamos la duales, ser ms fcil que podamos sucinta <gui>. Si es necesario, podeencontrar las partes que queremos modimos agregar, por ejemplo, style =butficar, eliminar o complementar ms adeton en la etiqueta de apertura para defilante. nir que queremos un botn en la interfaz Al mismo tiempo, los enlaces facilitan grfica de usuario. la tarea de integrar archivos externos, Tambin tenemos la opcin de aadir incluso si son de terceros. Por ejemplo, si una etiqueta <span> para informacin los desarrolladores escriben un texto de que no se mostrar ms adelante, pero ayuda separado para los plugins disponique es muy til para diferentes herrables para un programa y referencian esto mientas de procesamiento. Adems, limpiamente como parte de la documenpodemos ampliar Mallard aadiendo eletacin principal, el tema externo se mosmentos de espacios de nombres externos, trar como una parte integral sin tener virtualmente sin limitacin. que cambiar un

solo carcter en el manual. Si el plugin no est instalado, la pgina de ayuda correspondiente no existe, y el lector manual no pierde el tiempo buscando funciones que no existen. Como autor, encontrar que el formato no plantea mayores problemas que otros lenguajes de marcado. A pesar de que la bsqueda de un editor WYSIWYG adaptado a la sintaxis ser en vano, el editor estndar de Gnome, Gedit (Figura 1), entiende el formato y sus caractersticas. Un plugin de fragmentos de texto para Gedit proporciona etiquetas predefinidas y ofrece cerrar cualquier etiqueta que hayamos abierto. El editor Emacs tambin identifica la sintaxis y la muestra correctamente. Si su editor favorito no entiende Mallard, puede activar el resaltado de sintaxis para XML genrico. Esto est generalmente bien para ayudarle a encontrar su camino en la selva de etiquetas.

Lnea de Montaje
El texto original por s solo no hace un manual: primero hay que procesarlo. Aqu es donde Mallard pierde algunos puntos en comparacin con su modelo a seguir secreto, Docbook. Aparte de usar el navegador de ayuda de Gnome Yelp y exportar a HTML, donde el primero se basa en este ltimo, prcticamente no

Listado 1 : Archivo Mnimo de Mallard

01 <page xmlns=http://projectmallard.org/1.0/ 02 type=guide style=task 03 id=index> 04 05 <info> 06 <title type=text>Documentacin de ejemplo</title> 07 <credit type=author> 08 <name>John Doe</name><email>max@online.de</email> 09 </credit> 10 <license> 11 <p>Creative Commons Share Alike 3.0</p> 12 </license> 13 </info> 14 15 <title>Aplicacin de ejemplo</title> 16 17 <section id=introduction> 18 <title>Introduccin</title> 19 </section> 20 </page>

Listado 2 : Estructura de Archivo de Pgina

01 <page xmlns=http://projectmallard.org/1.0/ 02 type=guide 03 id=introduction> 04 05 <info> 06 <link type=guide xref=index#introduction/> 07 <credit type=author> 08 <name>John Doe</name><email>max@online.de</email> 09 </credit> 10 <license> 11 <p>Creative Commons Share Alike 3.0</p> 12 </license> 13 </info> 14 15 <title>Qu es una <app>aplicacin de ejemplo</app>?</title> 16 <p> 17 <app>Aplicacin de ejemplo</app> en un programa 18 con muchas funciones interesantes. 19 </p> 20 </page>

28

Nmero 80

WWW.LINUX- MAGAZINE.ES

Mallard PRCTICO

hay programas de visualizacin que entiendan Mallard. Si alguna vez ha convertido un documento Docbook a un documento PDF con un diseo profesional, puede que Mallard le decepcione. Aunque se est desarrollando un conversor [2], los trabajos no estn progresando mucho. De momento, el diseo hace difcil crear copias impresas atractivas. Mallard dispone de la capacidad de traducir textos a travs de archivos Po. El popular xml2po no hace un buen trabajo con esto, pero existe un reemplazo a la vista: ahora, la herramienta ITS [4] de la herencia de Gnome permite automatizar el proceso de la adicin de comentarios para el traductor y la ocultacin de elementos que no estn diseados para la traduccin en los archivos Po. El predecesor no era tan exigente y pona todo en los archivos Po, sin importar si era cdigo del programa, comandos o contenido para la traduccin. El nuevo mtodo reduce el nmero de errores en las versiones de idiomas extranjeros, contribuyendo as a mejorar la no siempre impecable reputacin de los manuales.

Gnome Reconstruido
No hace tanto tiempo, Docbook fue la herramienta elegida para la creacin de los manuales en Gnome. Desde la introduccin de Mallard, esto ha cambiado radicalmente, y no slo ha sido la sintaxis simplificada lo que ha provocado este movimiento. La intencin era evitar que los documentos tuvieran el aspecto de

una tesis y para darles un diseo ms al estilo wiki que facilitase la bsqueda de informacin. Uno de los primeros en adoptarlo fue el programa Empathy, que ofreci un manual en formato Mallard tan pronto como Gnome 2.28 en el otoo de 2009 (vase la Figura 2). Detrs de la fachada haba tambin un par de cambios que parecan inocuos. La documentacin escrita recientemente fue publicada bajo una licencia Creative Commons y no bajo la licencia GFDL, como lo fue anteriormente. Este mtodo facilita la propagacin de los textos debido a que los equipos de documentacin de, por ejemplo, Fedora y Ubuntu, tambin optaban por este tipo de licencia. Esto significa que no hay nada que evite que los autores intercambien entre s e integren mutuamente los documentos. Cambiar de licencia tambin significa buscar el acuerdo de todos los autores anteriores, si el proyecto quiere seguir utilizando el contenido existente. En muchos casos, el esfuerzo que supone hacerlo sera un precio demasiado alto a pagar, pero, s da una opcin a los mantenedores para evitar que se publique contenido obsoleto. Al mismo tiempo, pueden imponer una estructura basada en temas. Ahora mismo, los servidores oficiales de Gnome ofrecen 42 manuales en el nuevo formato, y las cifras van en aumento. Proyectos externos, como Dj Dup [4] y Simple Scan [5] tambin han adoptado Mallard. A partir de Gnome 3.2, al integrar pginas externas de ayuda, no importa qu instalacin ni plugin tenga el programa principal. El navegador renderizar una pgina instalada en ~/.local tan fcilmente como una localizada en /usr. Esto significa que podemos instalar plugins en nuestro directorio personal, sin tener permisos de root, incluyendo pginas de ayuda correctamente integradas. En general se puede decir que Gnome es el motor que impulsa Mallard, aunque Mallard no es un proyecto exclusivo de Gnome, sino que tiene un derecho universal.

largo plazo simplemente lo complementar. Los desarrolladores responden rpidamente a las peticiones de nuevas funcionalidades, pero el mbito de aplicacin se limita a mostrar texto en pantalla. Lo que nadie puede adivinar es si algn da habr una funcin de exportacin utilizable a LaTeX/PDF. Si necesita escribir documentos tcnicos para impresin, no hay alternativa a Docbook, a menos que ya use LaTeX. Pero si tiene que escribir manuales basados en temas que proporcionen a sus lectores la conveniencia de un diseo familiar estilo Wiki, Mallard es la herramienta a elegir. El desarrollo an es muy activo. Tan pronto como terminan una nueva caracterstica, arrancan con la siguiente. Se est trabajando en glosarios [6], los cuales nos permiten resaltar trminos en el texto y enlazar automticamente con las explicaciones. Esta funcionalidad fue promovida por un usuario comercial, lo que claramente demuestra la amplia aceptacin que encuentra el formato actualmente. Es de esperar que Mallard abarque ms proyectos en el futuro. El proyecto de escritorio XFCE va por buen camino [7]. Actualmente slo la barra de Xfce y los programas de terminal tienen manuales Mallard, con archivos en HTML que se pueden leer mediante un navegador de ayuda, aunque esto no es algo que vaya en contra de la idea bsica de una ayuda basada en temas. I

RECURSOS
[1] Proyecto Mallard: http://projectmallard.org [2] Convertir a LaTeX: http://gitorious. org/+projectmallard/projectmallard/ mal2latex [3] Herramienta ITS: http://itstool.org [4] Dj Dup: http://launchpad.net/deja-dup/ [5] SimpleScan: http://launchpad.net/simple-scan [6] Shaun McCance acerca de los glosarios: http://blogs.gnome.org/ shaunm/2011/07/07/ mallard-glossaries/ [7] Mallard para XFCE: http://wiki.xfce.org/documentation [8] Documentacin del autor: http:// mariobl.fedorapeople.org/Mallard-en/

Futuro
Figura 2: Un manual formateado en Mallard ofrecido con Gnome 2.28.

Debido a las restricciones mencionadas, Mallard probablemente no ser capaz de derrocar a Docbook a

WWW.LINUX- MAGAZINE.ES

Nmero 80

29