Tras mucho tiempo de buscar, leer, preguntar... he conseguido descifrar cómo funciona la documentación automática en LaTeX.
LaTeX permite escribir comentarios a la vez que escribimos el código de un paquete o clase. Estos comentarios pueden seguir una estructura de documento y se pueden compilar para obtener un manual perfecto. Podemos definir el paquete, sus macros, entornos, etc.
Los paquetes se escriben en formato
.dtx. No cambia nada, excepto que los comentarios seguiran una estrutura de documento. Todo el texto comentado es el que aparecerá en el manual.
Posteriormente pasamos el archivo
dtx, a través del programa docstrip. Para llamar a
docstrip debemos escribir:
latex docstrip.tex (en línea de comandos)
No hay que preocuparse de buscar el archivo
docstrip.tex, porque suele ir incluido en las distribuciones latex más populares. Y el propio LaTeX sabrá dónde está. A continuación se nos preguntarán varias cosas:
- extensión de archivo de entrada: dtx
- extensión de archivo de salida: sty (vamos a generar el paquete)
- parámetros: package (para generar el paquete - hay más pero de momento no los conozco)
- listado de ficheros a generar sin extensión: paquete (supangamos que nuestro fichero es "paquete.dtx")
- ya está!
Una vez hecho esto, tendremos el archivo
paquete.sty que contendrá todo el paquete sin comentarios. Y ya podremos utilizarlo con:
\usepackage{paquete}
Para terminar, podemos compilar el archivo
paquete.dtx utilizando LaTeX:
latex paquete.dtx
y obtendremos el manual estructurado del paquete.
Para definir nuevas macros podemos escribir lo siguiente en el dtx:
% Permite al usuario añadir notas
% \begin{macrocode}
%<*package>
\newenvironment{Notas}{...}{...}
% \end{macrocode}
%
Con las etiquetas
<*package> encerramos todo lo que queremos que se incluya en el documento sty resultante de la ejecución de docstrip.
Trasteando de nuevo con Perl, he encontrado un par de módulos que me pueden ser de gran utilidad. Además me han gustado mucho! Por cierto! Los he encontrado, como no, en CPAN.
