[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