Re: [bcn-pm] Sistema de documentación

Xavier Noria fxnahashref.com
Div Oct 14 03:14:25 PDT 2005


On Oct 14, 2005, at 11:49, Carlos Escribano wrote:

> El Viernes 14 Octubre 2005 11:14, Xavier Noria escribió:
>
>> De manera que si escoges XML como formato del sistema de litprog
>> entonces se dara la coincidencia de que el formato de documentacion
>> tambien es XML, pero no le veo mucha ventaja a eso de por si, ese XML
>> estara como CDATA, tan ajeno al XML de alrededor como lo estaria otro
>> formato no XML como Markdown.
>>
>
> Bueno, es la ventaja de utilizar XML. El código va en un espacio de  
> nombres
> propio (lp en este ejemplo), y la documentación en el espacio de  
> nombres
> principal (docbook en este caso). El documento sigue siendo un  
> documento
> válido XML, y las herramientas de DOM y XPAth siguen estando  
> asequibles para
> ambos espacios de nombres. Algo así:
>
> <para>Esto imprime el texto Hola Mundo:</para>
> <lp:fragment id="Impresión de hola mundo">print "Hola Mundo";</ 
> lp:fragment>

Es que eso no es suficiente, porque _ambas_ cosas deben tener un id  
comun para que cada chunk se distinga en la documentacion (y por  
ejemplo puedas enlazar los chunks, enlazar a los chunks donde algo  
(como una variable) se define, hacer un indice de los mismos, etc.):

     <lp:chunk id="impresion de hola mundo">
       <lp:doc>
          Ahora vamos a escribir Hola Mundo.
       </lp:doc>
       <lp:code>
         my $str = %% cadena hola mundo %%;
         print "$str\n";
       </lp:code>

     <!-- a 300 lineas de distancia -->

     <lp:chunk id="Literales">
       <lp:doc>
         \section{Literales}
         En esta sección tenemos todos los literales,
         no tiene mucho sentido pero sirve para dar un
         ejemplo con referencias cruzadas breve.
       </lp:doc>
     </lp:chunk>

     <lp:chunk id="cadena hola mundo">
       <lp:doc>
          Esta es la cadena Hola Mundo.
       </lp:doc>
       <lp:code>
         "Hola Mundo!"
       </lp:code>
     </lp:chunk>

De otro modo lo unico que tienes es documentacion normal, donde hay  
texto y fragmentos de codigo mezclados como en un libro de  
informatica normal, solo que con la funcionalidad adicional de  
extraer codigo y poder usar ids para hacerlo recursivamente al estilo  
arbol de litprog.

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.

> Mis dudas no están en la implementación, sino en cómo enlazo la  
> documentación
> externa (POD); pero veo por el otro mesaje que has enviado que esto  
> no lo
> llegaste a plantear en Halk.

Es que litprog es un paradigma de documentacion! No hay tal  
documentacion externa al estilo POD tradicional, o Javadoc  
tradicional, has cambiado el paradigma y tu documentacion va a tener  
otra pinta.

-- fxn




Més informació de la llista de correu Barcelona-pm