Diferencias entre las revisiones 28 y 29
Versión 28 con fecha 2007-12-10 20:39:21
Tamaño: 8452
Comentario:
Versión 29 con fecha 2007-12-10 20:57:10
Tamaño: 8728
Comentario:
Los textos eliminados se marcan así. Los textos añadidos se marcan así.
Línea 18: Línea 18:
Para Debian lenny/sid instale los siguientes paquetes para el uso de docbook:
Para un equipo con Debian GNU/Linux (lenny/sid) instale los siguientes paquetes:

P
ara el uso de docbook:
Línea 25: Línea 26:
Línea 26: Línea 28:
Línea 29: Línea 30:
Línea 30: Línea 32:

Para utilizar conglomerate instale los paquetes:
 * conglomerate: Editor XML.
 * conglomerate-common: Datos comunes.

Para utilizar Gedit, instale los paquetes:
 * gedit: Editor de texto oficial de GNOME.
 * gedit-common: Datos comunes.

Escribir documentación para aplicaciones GNOME

TableOfContents()

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í existe el visor de ayuda [http://live.gnome.org/Yelp yelp] para poder leer la documentación y para generar documentación existe [http://www.docbook.org/ docbook], que permite a través de un documento fuente generar documentos en diferentes formatos.

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.

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.

Programas necesarios

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

Para el uso de docbook:

  • sgml-base: Infraestructura SGML.
  • sgml-data: Datos comunes para SGML y XML.
  • docbook: Sistema estandar SGML para la representación de documentos ténicos
  • docbook-utils: Convertidor de archivos docbook a otros formatos.
  • docbook-xsl: Estilos para el procesamiento de archivos docbook XML.

Para utilizar Vim, instale los paquetes:

  • vim-common: Datos comunes.
  • vim: Editor VI mejorado.

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.

Para utilizar conglomerate instale los paquetes:

  • conglomerate: Editor XML.
  • conglomerate-common: Datos comunes.

Para utilizar Gedit, instale los paquetes:

  • gedit: Editor de texto oficial de GNOME.
  • gedit-common: Datos comunes.

Donde escribir los documentos

Cualquier editor sirve para escribir nuestro documento, [http://www.vim.org/ Vim] con la opción syntax on activada para el resalte de etiquetas con colores es una buena idea. También puede usar [http://www.gnu.org/software/emacs/ Emacs] con el módulo SGML mode, el que permite escribir con mas facilidad estos documentos. [http://www.conglomerate.org/ Conglomerate] es una herramienta gráfica para la creación de documentos para docbook, por supuesto que [http://www.gnome.org/projects/gedit/ Gedit] también es una buena opción.

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 siguiente ejemplo vemos uno de estos documentos.

<?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 lang="es">
<articleinfo>
  <author>
    <firstname>Comunidad</firstname>
    <surname>GNOME Hispano</surname>
  </author>
  <title>Ejemplo de un articulo</title>
</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 siguiente ejemplo vemos como se crea un documento de este tipo.

<?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 lang="es">
<bookinfo>
  <date>Diciembre 2007</date>
  <title>Ejemplo de un Libro</title>
  <author>
    <firstname>Comunidad</firstname>
    <surname>GNOME Hispano</surname>
  </author>
</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.

<?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 lang="es">
  <bookinfo>
  <date>Diciembre 2007</date>
  <title>Ejemplo de un Libro con varios archivos</title>
  <author>
    <firstname>Comunidad</firstname>
    <surname>GNOME Hispano</surname>
  </author>
</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>

<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:

  • db2dvi: genera un documento en formato dvi.
  • db2html: genera un directorio con el nombre del archivo y el su interior archivos html.
  • db2pdf: genera un documento en formato pdf.
  • db2ps: genera un documento en formato postscript.
  • db2rtf: genera un documento en formato rtf.

Algunos ejemplos son:

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

Elementos

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

  • Lista con ítems

<itemizedlist>
  <listitem><para>Item 1</para></listitem>
  <listitem><para>Item 2</para></listitem>
</itemizedlist>
  • Listas ordenadas

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

<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>
  • Imágenes

<figure id="figura-ejemplo">
  <title>logo</title>
  <graphic fileref="xd2.png" format="PNG">
</figure>
  • Referencias dentro de un documento

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

<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>
  • Notas al pie

<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>
  • Ejemplos de código

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

<para>
  Para generar la salida en html usar el comando: <command>db2html archivo.xml</command>
</para>
  • Nombres de archivos y directorios

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

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