ARTÍCULO EN DESARROLLO

Si quieres colaborar con nosotros completando este apartado o cualquier otra parte del Curso, puedes informarte en el enlace siguiente.

>[Documentación para desarrolladores]

CONTENIDO
Los contenidos y tareas pendientes se indican a continuación:

/2203 Utilidades de documentación de GNOME (gnome-doc-utils) 

Completar este apartado con los siguientes aspectos:
 - Describir con un breve ejemplo cómo implementar la función que llame a Yelp y le pase como parámetro el fichero xml
 - Definir dónde colocar los archivos en el directorio del proyecto
 - Definir el contenido de los ficheros Makefile.am/configure.in para soporte de documentación
 - Describir el uso de gnome-doc-utils
 - Describir cómo generar páginas man y/o info para aplicaciones que incluyan comandos sin GUI 

Escribir documentación para aplicaciones GNOME

En todo proyecto la documentación es un elemento muy importante y que lamentablemente no siempre se le da la atención que requiere. Tanto desde el punto de vista de quien recibe la documentación como de quien la genera, es vital contar con herramientas que hagan mucho mas fácil esta labor.

Así se tiene el visor de ayuda de GNOME yelp para poder leer la documentación. Para generar documentación existe docbook el cual tiene la particularidad de poder generar documentos (a partir de un archivo fuente escrito en texto claro) en varios formatos. El visor de ayuda yelp es capaz de cargar un documento escrito con docbook y mostrar su contenido.

Visor de ayuda Yelp

El navegador de ayuda de GNOME incluye documentación detallada de la mayoría de las aplicaciones, utilidades u otros componentes como el panel o el administrador de archivos Nautilus.

Yelp puede mostrar algunos archivos HTML y XML al ser pasados como parámetro en la línea de comandos. Este programa acepta todos las opciones estándares de GNOME y GTK+ que siga la sintáxis habitual de la línea de comandos GNU. Para obtener mas información sobre estas opciones utilize Yelp con el argumento --help.

Para visualizar un documento escrito con docbook desde una terminal ejecute el siguiente comando:

:~$ yelp ghelp:/ruta/completa/al/documento/articulo.xml

DockBook

Con docbook se pueden generar documentos en diferentes formatos: html, latex, txt, pdf, postscript. Permite la creación de documentos tales como libros, articulos, manuales, etc. Se ha convertido junto a Open eBook en un estandar internacional para el procesamiento de este tipo de documentos.

Donde escribir los documentos

Cualquier editor sirve para escribir nuestro documento, Vim con la opción syntax on activada para el resalte de etiquetas con colores es una buena idea. También puede usar Emacs con el módulo SGML mode, el que permite escribir con mas facilidad estos documentos. Conglomerate es una herramienta gráfica para la creación de documentos para docbook, por supuesto que Gedit también es una buena opción.

Programas necesarios

Para un equipo con Debian GNU/Linux (lenny/sid) instale los siguientes paquetes:

Para el uso de docbook:

Para utilizar Vim, instale los paquetes:

Si quiere activar el soporte para syntax highlighting (resaltar la sintaxis), debe editar el archivo /etc/vim/vimrc y habilitar la línea syntax on.

Adicionalmente puede instalar el script dbhelper el cual permite tras el uso de abreviaturas insertar etuiquetas de docbook. Los pasos para instalar son:

La lista conpleta de abreviaturas está en el archivo .vimscripts/dbhelper.vim.

Para utilizar conglomerate instale los paquetes:

Para utilizar Gedit, instale los paquetes:

Tipos de documentos

Docbook permite dos tipos de documentos; book (libro) y article (articulo). Los Articulos son mas sencillos de que los libros, estos no tienen ­índice de contenidos y ocupan menos hojas. Los libros permiten el uso de capí­tulos e índice de contenidos. Los libros además tienen la ventaja de que pueden contener más de un archivo, es decir, se pueden incluir otros archivos en un documento.

Artículo

Como ya indicamos, este tipo de documento es mucho mas sencillo que un libro. En el ejemplo vemos uno de estos documentos.

Ej: articulo.xml

<?xml version="1.0"?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
<article>
  <articleinfo>
  <title>Ejemplo de un Artículo</title>
  <author role="maintainer">
    <firstname>Comunidad</firstname>
    <surname>GNOME Hispano</surname>
  </author>
  <address><email>gnome-hispano-list@gnome.org</email></address>
  <revhistory>
    <revision>
      <revnumber>v0.1</revnumber>
      <date>2007</date>
    </revision>
  </revhistory>
  <abstract role="description">
    <para>Este artículo es un ejemplo de como escribir este tipo de documentos.</para>
  </abstract>
</articleinfo>

<sect1 id="sect1">
  <title>Primera sección</title>
  <para>Contenido primera sección...</para>
</sect1>
</article>

Libro simple

Docbook tiene otros elementos que se utilizan en este tipo de documentos y que permiten organizarlos de manera mas conveniente. En el ejemplo vemos como se crea un documento de este tipo.

Ej: libro.xml

<?xml version="1.0"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
<book>
<bookinfo>
  <title>Ejemplo de un Libro</title>
  <author role="maintainer">
    <firstname>Comunidad</firstname>
    <surname>GNOME Hispano</surname>
  </author>
  <revhistory>
    <revision>
      <revnumber>v0.1</revnumber>
      <date>2007</date>
    </revision>
  </revhistory>
  <abstract role="description">
    <para>Este libro es un ejemplo de como escribir este tipo de documentos.</para>
  </abstract>
</bookinfo>
<chapter id="chapter1">
  <title>Entornos de escritorio</title>
    <para>Texto...</para>
    <sect1 id="sect1">
      <title>GNOME</title>
      <para>contenido de la sección 1</para>
    </sect1>
</chapter>
</book>

Libro con varios archivos

Para hacer la documentación mas ordenada y permitir la división de capítulos de manera de distribuir las tareas, se puede crear un libro el cual contempla otros trozos de documentos. El siguiente ejemplo muestra como dividir el libro en varios capítulos.

Ej: libro2.xml

<?xml version="1.0"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
<!ENTITY capitulo2.xml SYSTEM "capitulo2.xml">
]>
<book>
<bookinfo>
  <title>Ejemplo de un Libro con varios archivos</title>
  <author role="maintainer">
    <firstname>Comunidad</firstname>
    <surname>GNOME Hispano</surname>
  </author>
  <revhistory>
    <revision>
      <revnumber>v0.1</revnumber>
      <date>2007</date>
    </revision>
  </revhistory>
  <abstract role="description">
    <para>Este libro es un ejemplo de como escribir este tipo de documentos con varios archivos.</para>
  </abstract>
</bookinfo>
<chapter id="chapter1">
  <title>Ambientes de escritorio</title>
  <para>Texto...</para>
  <sect1 id="sect1">
    <title>GNOME</title>
    <para>contenido de la sección 1</para>
  </sect1>
</chapter>
  &capitulo2.xml;
</book>

Ej: capitulo2.xml

<chapter id="chapter2">
  <title>Sistemas Operativos</title>
  <sect1 id="Linux">
  <title>GNU/Linux</title>
  <para>Linux....</para>
  </sect1>
</chapter>

Generación de formatos

Para pasar el documento fuente a otros formatos tenemos los siguientes comandos:

Algunos ejemplos son:

~$ db2pdf articulo.xml
~$ db2html articulo.xml

Elementos

Los siguientes son algunos elementos de uso común en cualquier documento.

<itemizedlist>
  <listitem><para>Item 1</para></listitem>
  <listitem><para>Item 2</para></listitem>
</itemizedlist>

<orderedlist numeration="arabic">
  <listitem><para>Item 1</para></listitem>
  <listitem><para>Item 2</para></listitem>
</orderedlist>

<table id="tabla-ejemplo">
  <title>Tabla de ejemplo</title>
  <tgroup cols="1">
    <thead>
      <row>
      <entry>Titulo columna</entry>
      </row>
    </thead>
    <tbody>
      <row>
        <entry>fila 1</entry>
      </row>
      <row>
        <entry>fila 2</entry>
      </row>
    </tbody>
  </tgroup>
</table>

<figure id="figura-ejemplo">
  <title>logo</title>
  <graphic fileref="xd2.png" format="PNG">
</figure>

<para>
  en la <xref linkend="tabla-ejemplo"> se muestra una tabla.
</para>

<para>Una dirección web:
  <ulink url="http://www.gnome.org/"> GNOME </ulink>
</para>
<para>Una dirección de correo:
  <ulink url="mailto:usuario@dominio.cl"> usuario@dominio.cl </ulink>
</para>

<para>
El siguiente ejemplo es una nota al pie de página
<footnote>
  <para>Para mas información visite: <ulink url="http://www.gnome.org/"> GNOME</ulink></para>
</footnote>
</para>

<programlisting>
static void
gyrus_main_app_on_file_exit (GtkWidget *widget G_GNUC_UNUSED,
                             gpointer user_data G_GNUC_UNUSED)
{
      gtk_main_quit ();
}
</programlisting>

<para>
  Para generar la salida en html usar el comando: <command>db2html archivo.xml</command>
</para>

<para>
Cuando instale Docbook varios archivos son agregados a <filename class="directory">/usr/bin</filename>, incluyendo <filename>db2html</filename> y <filename>db2pdf</filename>.
</para>

Utilidades de documentación de GNOME (gnome-doc-utils)

Muchas aplicaciones usan un viejo método para incluir documentación. Con estas herramientas se pretende entregar un método uniforme para generar e instalar documentación. El documento debe estar escrito utilizando docbook.

Requerimientos

Asegurece de estar usando una versión reciente de gnome-common (del 2005-07-19 o posterior) si esta usando gnome-autogen.sh o si llama a gnome-doc-prepare en su autogen.sh.

Configurando help/Makefile.am

La ubicación estandar para la documentación es en un subdirectorio llamado help/ dentro de la estructura del proyecto. Este nombre no es obligatorio aunque si es muy recomendado. También debe contener un subdirectorio help/C el cual contendrá el documento documento-nombre.xml

En el directorio help crear un archivo llamado Makefile.am y defina en él las siguientes variables:

include $(top_srcdir)/gnome-doc-utils.make
dist-hook: doc-dist-hook

DOC_MODULE = documento-nombre
DOC_ENTITIES = legal.xml
DOC_INCLUDES = 
DOC_FIGURES = figures/figure.png   

DOC_LINGUAS = es

* DOC_MODULE: es el nombre del documento a generar. El nombre debe aparecer sin la extensión .xml. Debe tener help/C/$DOC_MODULE.xml

* DOC_ENTITIES: lista de cualquier archivo incluido en el documento usando el sistema de entidades, por ejemplo:

<!ENTITY SYSTEM "legal.xml.xml">

* DOC_INCLUDES: lista de cualquier archivo incluido con la especificación Xinclude.

* DOC_FIGURES: lista de todas las figuras que son referenciadas en el documento.

* DOC_LINGUAS: lista de los códigos de lenguages para los cuales el documento está traducido.

Configurando help/documento-nombre.omf.in

Las utilidades de generación de documentos para GNOME requiere de un archivo instalado en help/documento-nombre.omf.in. Este archivo es una versión reducida de un archivo Scrollkeeper OMF.

<?xml version="1.0" standalone="no"?>
<omf>
  <resource>
    <subject category="<categories>"/>
    <type>guía de usuario</type>
    <relation seriesid="<use el programa uuidgen para generar un único identificador"/>
    <rights type="<License type>" license.version="<version, if desired>" holder="<Nombre del escritor>"/>
  </resource>        
</omf>

El documento docbook

Asegúrece que el documento docbook tenga los siguientes campos relevantes:

Pasos finales

En la raiz del proyecto:

Documentacion/Desarrollo/EscribirDocumentacionParaAplicacionesGNOME (última edición 2009-09-08 22:27:53 efectuada por DomingoGonzalez)