[bcn-pm] Sistema de documentación
Carlos Escribano
cesatablinum.org
Div Oct 14 04:16:34 PDT 2005
El Viernes 14 Octubre 2005 12:14, Xavier Noria escribió:
> Si es eso lo que planteas ya entiendo mejor por donde vas, seria un
> sistema de litprog algo apartado del paradigma como tal creo yo, pero
> no mucho.
Bueno, no he sido yo quien ha cambiado el paradigma; es como hace en XML,
donde no se suele ver todo como una sucesión de fragmentos de documentación y
código. Ten en cuenta que en XML cualquier elemento puede tener un id y otros
atributos, y por tanto es enlazable, y se puede indexar; desde un punto de
vista lógico puedes crear cuantos fragmentos de XML quieras sin forzar el
modelo ni separar espacios de nombres.
Siempre se podría levantar un elemento equivalente a tu chunk en el mismo
espacio de nombres, de cara al indexado o referencias, algo así como:
<section id="impresion">
<para>Esto imprime el texto Hola Mundo:</para>
<lp:fragment id="Impresión de hola mundo">print "Hola Mundo";</lp:fragment>
</section>
Y hacer que la hoja de estilos ignore este elemento section a efectos de
formeateado, utilizando solo un modo de indexado que sí se implementara. Pero
no se suele hacer. Los enlaces e índices se suelen referir exclusivamente al
código.
He aquí algunos ejemplos de programación literaria en XML:
- xweb [1]: El más sencillo de todos, lo más parecido a un libro de
programación, donde se eumeran código y datos, limitado a un archivo (está
hecho para documentar archivos XSLT).
- XML-Lit [2]: Igual de sencillo que el anterior, pero con posibilidad de
generar varios archivos.
- xmltangle [3]: En salida es similar al anterior, aunque difiere en su
implementación (instrucciones de procesamiento).
-xmlP [4]: Una salida más elaborada, con elementos orientados al control de
calidad del código, inspirado en funnelweb.
> Es que litprog es un paradigma de documentacion! No hay tal
> documentacion externa al estilo POD tradicional
Ese es el problema que tengo. La documentación de programación literaria es
documentación interna, dice qué hace el programa. Un usuario normal no tiene
interés en ello, sólo quiere la documención externa: Sinopsis, descripción de
métodos y los parámetros que admiten ...
En Perl hay un sistema de documentación externa que funciona muy bien (los
PODS, a menudo integrados en el propio código) y no quiero perderlo.
La solución para mí hasta ahora ha sido tratarlo como si fuera un trozo de
código más, por ejemplo en un capítulo final.
Pero el otro día Francesc nos enseñó unos ejemplos con Test::More en que
fragmentaba el POD en trozos, delante de cada función; cada una iba con su
documentación externa. Esta parte me gusta, pero no veo cómo compatibilizar
la estructrura de la documentación que él presentaba (funciones o métodos)
con la de la programación literaria.
Es decir, cómo compatibilizar algo como lo de arriba con ésto:
==head1 Imprimir
El método devuelve la cadena "hola mundo"
my $string= holamundo();
= cut
sub holamundo {
return "hola mundo";
}
-------------
[1] http://nwalsh.com/docs/articles/xml2002/lp/paper.html
[2] http://xml-lit.sourceforge.net/
[3] http://www.eskimo.com/~johnnyb/computers/xmltangle/
[4] http://xmlp.sourceforge.net/2002/extreme/index.html
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: signature
Url : http://mail.pm.org/pipermail/barcelona-pm/attachments/20051014/87770c44/attachment.bin
Més informació de la llista de correu Barcelona-pm