Notxor tiene un blog

Defenestrando la vida

Texinfo: el sistema de ayuda de Emacs

Notxor
2024-03-09

Los usuarios de Emacs están, o deberían estar, acostumbrados a utilizar el sistema de ayuda que trae incorporado. Cuando pulsamos C-h r accedemos al manual de Emacs en su versión info. Si lo cargáramos en PDF sería un manual de 768 páginas. Pero no es el único manual que viene con este editor, hay muchos más. Podemos acceder al manual de org-mode (323 págs.), a una introducción a la programación en emacs-lisp (286 págs.), también está el manual de referencia de emacs-lisp (1.522 págs.) y muchas otras herramientas que vienen con el propio Emacs, como calc, cuya documentación en PDF, son 505 páginas. Toda esta información viene anexada como documentación de en archivos .texi, es decir, en formato Texinfo. En este artículo te cuento un poco qué aspecto tiene y cómo funciona, por si lo quieres utilizar para documentar tu proyecto.

Historia y primer vistazo al sistema de documentación

Siempre lo he visto escrito con la «T» mayúscula y también sé, que como ocurre con TeX, la letra «x» no es una equis, sino una «χ» griega. Pero como los sonidos guturales «g» o «j» se les atraviesa a los guiris en la garganta, suelen preferir pronunciar el nombre tal que TeKinfo.

El sistema Texinfo, en la actualidad, es independiente de Emacs, aunque nació para hacer la documentación de nuestro editor favorito. Comenzó como el sistema de ayuda de hipertexto que incluyó Stallman en el año 1975–1976 para documentar Emacs y que sirviera de ayuda al usuario. Después, en los primeros años de la década de los 90 del siglo pasado, se tradujo al sistema a lenguaje C, en dos comandos: el makeinfo, que generaba la documentación y el info, que permitía navegar el contenido sin necesitar un buffer de Emacs.

En 2012, se sustituyó makeinfo por una versión en Perl llamada texi2any, que derivó de una implementación anterior llamada texi2html, que generaba la documentación en HTML para poder leerla en cualquier navegador y no depender de info ni de Emacs.

En la actualidad, los formatos que se pueden generar son los siguientes:

  • Info: el formato de hipertexto original.
  • Texto plano.
  • HTML: En dos formatos. El primero es una sola página con enlaces internos, pero también podemos generarlo con una página para cada nodo de documentación.
  • epub 3: Es un formato diseñado para documentos que deben leerse en dispositivos electrónicos.
  • DVI: Este formato es el de salida por defecto de TeX. Es un formato binario destinado a imprimir en papel, aunque también puede visualizarse en pantalla.
  • PostScript: es un lenguaje de descripción de página, muy popular hace unos años gracias a las impresoras postscript que realizaban la impresión mediante dicho lenguaje. También se puede visualizar en pantalla.
  • PDF: junto con dvi y postscript completa el trío de documentos para impresión. Este es un formato popularizado por Adobe® Systems.
  • LaTeX: es un lenguaje de descripción de documentos. Puede utilizarse como paso intermedio para modificar luego el aspecto de la documentación generada.
  • DocBook: se genera un archivo XML compatible con el sistema DocBook, que sirve para crear manuales en varios formatos.
  • XML: al contrario que en el formato anterior, se generan unos archivos .xml que no se pueden visualizar con navegadores o para generar otro tipo de formato de documento. Se utiliza un texinfo.dtd incluido en la distribución de Texinfo para utilizar otras herramientas de lectura de XML para acceder a ellos.

¿Cómo se escribe la documentación?

Si has utilizado con anterioridad TeX o LaTeX sabrás que cuando quieres introducir alguna instrucción o comando utilizas el carácter especial «\». En Texinfo el carácter que marca un comando es @.

Pongo un ejemplo simple para que se vea el formato y ahora lo comento todo un poco más despacio. El documento que he preparado para la prueba se llama ejemplo.texi (lo podéis descargar para trastearlo) y el archivo generado es ejemplo.info (también lo podéis descargar).

\input texinfo
@setfilename ejemplo.info
@documentencoding UTF-8
@documentlanguage es_ES

@set version 1.0
@set actualizado 9 de marzo de 2024

@settitle Mi fantabuloso manual @value{version}

@copying
Esto es un ejemplo cortito de un archivo Texinfo.

Copyright @copyright{} 2024 Free Software Foundation, Inc.
@end copying

@titlepage
@title El título de la documentación

@page
@vskip 0pt plus 1filll
@insertcopying
@end titlepage

@contents
@node Top
@top Ejemplo
Este es el manual que quiero escribir
(versión @value{version}, @value{actualizado}).

@menu
* Primer capítulo::           Primer capítulo del manual.
* Segundo capítulo::          Otro capítulo para rellenar.
@end menu

@node Primer capítulo
@chapter Primer capítulo

Ahora mismo no tengo muy claro qué debería escribir para hacer el ejemplo

Un bloque con una lista numerada:

@enumerate
@item
El primer ítem de la lista.

@item
El segundo ítem de la lista
@end enumerate

@node Primera sección
@section Primera sección

Primera sección del primer capitulo.

Enlaces a otro nodo:

@itemize
@item
@@ref@{Segunda sección@} @result{} @ref{Segunda sección}

@item
@@xref@{Segunda sección@} @result{} @xref{Segunda sección}

@item
@@pxref@{Segunda sección@} @result{} @pxref{Segunda sección}
@end itemize

@node Segunda sección
@section Segunda sección

La segunda sección del primer capítulo.

@node Segundo capítulo
@chapter Segundo capítulo

Esto es el segundo capítulo... es corto ¿no?

@bye

Visionando el archivo generado a través de la ayuda de Emacs, la apariencia sería así:

Captura_top-ejemplo.png
Captura_chap1-ejemplo.png

El formato

No creo que haga falta decir que un párrafo está separado de otro mediante una línea en blanco (o que sólo contenga espacios en blanco). Además vemos que hay algunos comandos que son entornos, como en el caso de las listas que tienen una instrucción de final, @end. Por ejemplo, una lista numerada tiene la siguiente estructura:

@enumerate

@item
...

@end enumerate

La mayoría de los comandos son familiares si has utilizado LaTeX. Nos puede llamar, quizá, la atención el comando @node, que en este caso no es un entorno. Un nodo en el documento es aquella información que se mostrará junta en la misma pantalla del info, buffer de Emacs, o en la misma página del HTML. En los formatos que no sean info o HTML, no tendrá ningún efecto.

Si miramos el código, que he puesto en el listado de arriba, el documento está contenido todo en el mismo listado1, pero se separa lógicamente mediante algunos comandos @node. Cada nodo comienza con dicho comando y finaliza donde comience otro nodo.

En el ejemplo, podemos encontrar otros comandos, más fáciles de digerir, como @chapter o @section, que considero que no es necesario explicar para qué se utilizan.

Los principales comandos de estructura del documento son:

  • @node
  • @part
  • @chapter, @unnumbered, @appendix
  • @section
  • @subsection
  • @subsubsection

Hay algunos más, y también hay otros muchos detalles. Como por ejemplo, el comando @section sabe si está en un capítulo numerado (@chapter), no numerado (@unnumbered) o en un apéndice (@appendix).

También se pueden establecer referencias cruzadas dentro del documento o manual; como vemos en el código anterior, que generan unos enlaces como se puede ver en la siguiente imagen:

Captura_ventana-info.png

Los comandos más habituales para formatear el texto, y que creo que tampoco necesitan mucha explicación son:

  • @strong{texto}
  • @emph{texto}
  • @code{texto}
  • @sub{texto}
  • @sup{texto}

O seleccionando la fuente:

  • @b{bold-negrita}
  • @i{italica}
  • @r{roman}
  • @sansserif{texto}
  • @sc{small-caps}
  • @slanted{oblicua}
  • @t{paso-fijo}

Con algún formateo más especializado:

  • @file{nombre-fichero}
  • @command{comando}
  • @email{dirección}
  • @abbr{abreviatura, [significado]}
  • @acronym{siglas, [significado]}
  • @kbd{secuencia-de-teclado}
  • @key{tecla-del-teclado}

También existen otros entornos, además de las listas, que pueden sernos útiles:

  • @cartouche2 dibuja un rectángulo de esquinas redondeadas alrededor del texto.
  • @quotation
  • @example
  • @verbatim

Conclusiones

No quiero enrollarme mucho: Es una herramienta interesante y merece la pena echarle un ojo si necesitas escribir documentación, porque se creó para eso: Texinfo es, realmente, un sistema potente de documentación. El compilador texi2any y el visualizador info son fáciles de instalar, si no los tienes ya instalados en tu máquina. Ocupan poco espacio y pueden ser verdaderamente útiles.

Por ejemplo, uno de los libros que suelo recomendar para aprender a programar en LISP es Structure and Interpretation of Computer Programs, cuyo repositorio (no oficial) podéis encontrar en https://media.githubusercontent.com/media/sarabander/sicp-pdf y veréis que utiliza una mezcla de Texinfo y LaTeX, que da como resultado un pdf bastante agradable a la vista. El sicp.texi necesita una limpieza antes de generar el info si lo quieres consultar desde Emacs (que poder, se puede).

Como propósito personal, voy a documentar el proyecto en el que ando programando a ratos con esta herramienta, en lugar de LaTeX, que suele ser mi elección más habitual. Si no me encuentro cómodo, no me costará nada generar el LaTeX con lo que haya escrito hasta entonces y continuar a partir de ahí.

Notas al pie de página:

1

Se puede dividir en varios archivos, que suele ser lo habitual en un manual grande, para luego incluir estos en el fichero maestro.

2

Hay que recordar que estos comandos deben ir emparejados con un comando de finalización, como en este caso @end cartouche.

Categoría: texinfo emacs

Comentarios

Debido a algunos ataques mailintencionados a través de la herramienta de comentarios, he decidido no proporcionar dicha opción en el Blog. Si alguien quiere comentar algo, me puede encontrar en esta cuenta de Mastodon, también en esta otra cuenta de Mastodon y en Diaspora con el nick de Notxor.

Si usas habitualmente XMPP (si no, te recomiendo que lo hagas), puedes encontrar también un pequeño grupo en el siguiente enlace: notxor-tiene-un-blog@salas.suchat.org

Disculpen las molestias.