Documentador de codigos que genera agendas de posts de otros
programas desarrollados en lenguaje Tol y algunos otros lenguajes como
Javascript, Html, Sql y Xml. El programa explota la riqueza de otros
programas en comentarios, estructura y codigo para generar unos contenidos
que son el paso previo para ser llevados a paginas web y generar con ellos
documentacion en Pdf.
Este codigo se le puede clasificar como metaprogramación.
La metraprogramación consiste en escribir programas que escriben o
manipulan otros programas o a si mismo.
Usualmente no se ejecuta el fichero make.tol del documentador directamente,
sino que es desde otros programas donde se invoca a su funcion principal
DctMake().
Para invocar a DctMake() se le debe haber declarado previamente
a) Text DctPre que es la ruta del directorio contenedor del directorio del
programa a documentar y
b) Set DctTre que es el arbol de ficheros a documentar.
Para utilizar toda la potencia de este codigo de autodocumentación
Dct.Writer se han de tener en cuenta un conjunto de directrices, que
afectan fundamentalmente a Tol, pero tambien a otros lenguajes de
programacion sobre:
a) el estilo de programacion,
b) la forma de introducir los comentarios,
c) las descripciones de las funciones y de las variables en Tol, etc.
El nombre del programa es igual al de su directorio principal y
bajo este directorio principal hay un subdirectorio dct para documentacion:
a) donde se guardan las agendas de posts generadas,
b) con los fichero Html de presentacion realizados a mano y
c) las imagenes ilustrativas.
Todas las agendas generadas, una por fichero del programa:
a) se guardan en el directorio dct del programa y
b) con el nombre del fichero con extension cambiando los puntos por
subrayadores mas una nueva extension .age, por ejemplo,
de txt.tol es dct/txt_tol.age, todo en minusculas.
Las presentaciones generadas a mano:
a) se buscan en el directorio dct,
b) el nombre del fichero de presentacion es el del nombre que presenta,
incluida su extension, todo separado por subrayadores, con la extension
.htm, por ejemplo, la presentacion de make.tol es dct/make_tol.htm,
se conserva la antigua extension porque para agendas o presentaciones,
si no se incluyentan, pueden coincidir, por ejemplo, las de los ficheros
make.tol y make.bat que se diferencian al incluir su extension,
asi es dct/make_tol.htm y dct/make_bat.htm,
c) no es obligatorio incluir presentaciones ,htm manuales, solo se insertan
si existe dicho fichero de presentacion y
d) del fichero de presentacion se lee y se incluye todo el codigo html que
se encuentra entre las etiquetas de inicio <body><div class="Bdy"> y de
fin </div></body>, esto permite, si se emplea el Css adecuado,
reproducir el aspecto final de la pagina con sus imagenes y
e) dentro de este codigo de presentacion no se emplean headers h1, h2 y h3
que se reservan para las secciones oficiales, si se han de simular
titulos se ponen en un parrafo p con letra bold b o h4.
Las imagenes de las presentaciones manuales en html:
a) estan en el directorio dct.
b) se enlazan (src) como ../dct_writer/imagen.ext, siendo ext, por ejemplo, png.
La elaboracion de la documentacion se realiza a partir de:
a) la ruta previa al directorio del programa, por ejemplo, ../Web,
ruta que puede ser relativa o absoluta, preferiblemente lo primero, y
b) un arbol de entrada de descripcion de los ficheros a documentar.
El arbol de entrada:
a) contiene el nombre del programa y, por tanto, el nombre del directorio
principal, asi, por ejemplo, de Omr.Forms y ../Web se forma
../Web/Omr.Forms/dct,
b) todos los ficheros a documentar que pueden tener marcas que identifican
al modulo principal y a su raiz [*] y a los fichero de salida [>],
el resto de ficheros se asumen de entrada,
c) una breve descripcion que se utiliza para la generacion la estructura
de ficheros y como descripcion si no hay otra y
d) se documentan todos los ficheros, no se documentan los directorios,
salvo el directorio principal cuya documentacion es la del modulo
principal del programa, usualmente un make.tol
Este documentador distingue 4 tipos de ficheros:
a) los ficheros en lenguaje Tol en codigo realzado,
b) los ficheros en otros lenguajes de programacion en codigo realzado,
c) los ficheros en texto plano, que no van en codigo realzado y
d) los ficheros pdf que se dejan como estan en nombre y contenido.
La documentación de un fichero Tol tienen las siguientes secciones:
a) la Cabecera, cuyo contenido sale de la cabecera inicial del fichero Tol,
b) la Presentacion, opcional, cuyo contenido proviene de un fichero Html
generado de forma manual, que puede incluir imagenes,
c) el Indice de declaraciones, donde cada declaracion enlaza con las
variables y funciones que se definen a continuacion, esta seccion se
subdivide en Inclusiones, Variables de control, Constantes, Funciones,
etc. igual que los ficheros Tol,
d) la secuencia de secciones de Inclusiones, Estructuras de datos,
Variables de control, Constantes, Funciones de nombre corto, Funciones,
Proceso, Pruebas y Finalizacion, esta secuencia es la misma que la del
indice anterior y para cada fichero solo se ponen las que existen,
e) el Codigo fuente completo con el contenido en codigo realzado de todo
el fichero y
f) el Arbol de estructura de ficheros, que es una representacion en Html
del arbol que se recibe como entrada al documentador, en cada arbol se
destaca el propio fichero frente al resto, este arbol enlaza con links
a todos los ficheros del arbol del programa, esta seccion se pone al
final porque al ser similar para todos los ficheros si se pone al
principio a modo de menu de navegacion todas las paginas parecen
inicialmente similares.
Los ficheros en lenguajes diferentes a Tol, por ejemplo, los de SQL,
Javascript, Html, Xml, de mandatos, etc. tienen las siguientes secciones:
a) la Cabecera, cuyo contenido puede salir de sus comentarios de cabecera
y en otro caso sale de la descripcion del arbol,
b) la Presentacion, que es opcional,
c) el Codigo fuente completo con el contenido en codigo realzado de todo
el fichero y
b) el Arbol de estructura de ficheros.
Este documentador asume que existen 2 tipos de links a las secciones:
a) el link local, #, formado por el nombre del programa, el del fichero y
el nombre de la seccion, este link local podria ser mas simple, con la
seccion bastaria, pero se necesita todo porque cada seccion puede salir
a formar parte de otras paginas compartiendo espacio con otras secciones
con el mismo nombre de seccion o de fichero y
b) el link global formado por ../programa/fichero.html#link.local.
Sin embargo, habiendo realizado pruebas en FireFox, Chrome e IExplorer los
links globales funcionan como locales, sin recargar la pagina, cuando se
les invoca de forma local por lo que solo se plantea un tipo que es el
link global con la forma ../programa/fichero.html#seccion. Por lo que
ambos metodos, links globales y locales o solo globales, funcionan bien.
Este documentador genera 2 tipos de etiquetas para las secciones que
coinciden con el titulo de la seccion:
a) la etiqueta o titulo local que es solo el nombre de la seccion, en Tol,
en variables y funciones esto coincide con el nombre de la variable o
de la funcion mas () y
b) la etiqueta o titulo global formado por etiqueta.local de programa,
en este caso utilizar la etiqueta global como local resulta reiterado
ya que, por ejemplo, 12 funciones seguidas irian todas con el funX() de
Omr.Forms, funY() de Omr.Forms, etc.,
Es por ello que en este documentador se unifican las etiquetas de la
siguiente forma:
a) titulo ventana, enlaces y headers globales = seccion de programa, donde
seccion es un nombre castellano o un nombre de variable o funcion,
b) etiqueta a names, enlaces y headers locales que es solo la seccion
Esta diferencia entre etiquetas se podria crear en una fase posterior,
pero este documentador la genera porque dispone de toda la informacion para
crearlas evitandole esta tarea a procesos posteriores.
La informacion que este documentador obtiene de la cabecera de un fichero
de codigo es:
a) fichero, file,
b) autor, author,
c) clases, classes y
d) proposito, purpose.
Dct.Writer documenta programas Tol generado agendas para Html
//////////////////////////////////////////////////////////////////////////////
Set allInc = Include("tol/inc.tol");
//////////////////////////////////////////////////////////////////////////////
PutDescription("Inclusion de las funciones comunes.", allInc);
////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
Real makDct = Case(
! ObjectExist("Text","DctPre"),
{ Text WriteLn("Error: sin definir la ruta Text DctPre"); FALSE },
! ObjectExist("Set","DctTre"),
{ Text WriteLn("Error: sin definir el arbol Set DctTre"); FALSE },
TRUE, DctMake(DctPre, DctTre));
//////////////////////////////////////////////////////////////////////////////
PutDescription(
"Con DctPre, ruta del directorio contenedor del directorio del programa, y
DctTre, arbol de ficheros a documentar, crea la documentacion de un programa
Tol.",
makDct);
//////////////////////////////////////////////////////////////////////////////Text WriteLn("\nDct.Writer make: end");//////////////////////////////////////////////////////////////////////////////
// FILE : make.tol
// AUTHOR : http://www.asolver.com
// CLASS : Metaprogramación; Hipertexto
// VERSION : Tol 1.1.5; Tol 1.1.6; Tol 2.0.1
// PURPOSE : Documentador de codigos que genera agendas de posts de otros
// programas desarrollados en lenguaje Tol y algunos otros lenguajes como
// Javascript, Html, Sql y Xml. El programa explota la riqueza de otros
// programas en comentarios, estructura y codigo para generar unos contenidos
// que son el paso previo para ser llevados a paginas web y generar con ellos
// documentacion en Pdf.
//
// Este codigo se le puede clasificar como metaprogramación.
// La metraprogramación consiste en escribir programas que escriben o
// manipulan otros programas o a si mismo.
//
// Usualmente no se ejecuta el fichero make.tol del documentador directamente,
// sino que es desde otros programas donde se invoca a su funcion principal
// DctMake().
//
// Para invocar a DctMake() se le debe haber declarado previamente
// a) Text DctPre que es la ruta del directorio contenedor del directorio del
// programa a documentar y
// b) Set DctTre que es el arbol de ficheros a documentar.
// _
// Para utilizar toda la potencia de este codigo de autodocumentación
// Dct.Writer se han de tener en cuenta un conjunto de directrices, que
// afectan fundamentalmente a Tol, pero tambien a otros lenguajes de
// programacion sobre:
// a) el estilo de programacion,
// b) la forma de introducir los comentarios,
// c) las descripciones de las funciones y de las variables en Tol, etc.
//
// El nombre del programa es igual al de su directorio principal y
// bajo este directorio principal hay un subdirectorio dct para documentacion:
// a) donde se guardan las agendas de posts generadas,
// b) con los fichero Html de presentacion realizados a mano y
// c) las imagenes ilustrativas.
//
// Todas las agendas generadas, una por fichero del programa:
// a) se guardan en el directorio dct del programa y
// b) con el nombre del fichero con extension cambiando los puntos por
// subrayadores mas una nueva extension .age, por ejemplo,
// de txt.tol es dct/txt_tol.age, todo en minusculas.
// _
// Las presentaciones generadas a mano:
// a) se buscan en el directorio dct,
// b) el nombre del fichero de presentacion es el del nombre que presenta,
// incluida su extension, todo separado por subrayadores, con la extension
// .htm, por ejemplo, la presentacion de make.tol es dct/make_tol.htm,
// se conserva la antigua extension porque para agendas o presentaciones,
// si no se incluyentan, pueden coincidir, por ejemplo, las de los ficheros
// make.tol y make.bat que se diferencian al incluir su extension,
// asi es dct/make_tol.htm y dct/make_bat.htm,
// c) no es obligatorio incluir presentaciones ,htm manuales, solo se insertan
// si existe dicho fichero de presentacion y
// d) del fichero de presentacion se lee y se incluye todo el codigo html que
// se encuentra entre las etiquetas de inicio <body><div class="Bdy"> y de
// fin </div></body>, esto permite, si se emplea el Css adecuado,
// reproducir el aspecto final de la pagina con sus imagenes y
// e) dentro de este codigo de presentacion no se emplean headers h1, h2 y h3
// que se reservan para las secciones oficiales, si se han de simular
// titulos se ponen en un parrafo p con letra bold b o h4.
// _
// Las imagenes de las presentaciones manuales en html:
// a) estan en el directorio dct.
// b) se enlazan (src) como ../dct_writer/imagen.ext, siendo ext, por ejemplo, png.
//
// La elaboracion de la documentacion se realiza a partir de:
// a) la ruta previa al directorio del programa, por ejemplo, ../Web,
// ruta que puede ser relativa o absoluta, preferiblemente lo primero, y
// b) un arbol de entrada de descripcion de los ficheros a documentar.
//
// El arbol de entrada:
// a) contiene el nombre del programa y, por tanto, el nombre del directorio
// principal, asi, por ejemplo, de Omr.Forms y ../Web se forma
// ../Web/Omr.Forms/dct,
// b) todos los ficheros a documentar que pueden tener marcas que identifican
// al modulo principal y a su raiz [*] y a los fichero de salida [>],
// el resto de ficheros se asumen de entrada,
// c) una breve descripcion que se utiliza para la generacion la estructura
// de ficheros y como descripcion si no hay otra y
// d) se documentan todos los ficheros, no se documentan los directorios,
// salvo el directorio principal cuya documentacion es la del modulo
// principal del programa, usualmente un make.tol
// _
// Este documentador distingue 4 tipos de ficheros:
// a) los ficheros en lenguaje Tol en codigo realzado,
// b) los ficheros en otros lenguajes de programacion en codigo realzado,
// c) los ficheros en texto plano, que no van en codigo realzado y
// d) los ficheros pdf que se dejan como estan en nombre y contenido.
//
// La documentación de un fichero Tol tienen las siguientes secciones:
// a) la Cabecera, cuyo contenido sale de la cabecera inicial del fichero Tol,
// b) la Presentacion, opcional, cuyo contenido proviene de un fichero Html
// generado de forma manual, que puede incluir imagenes,
// c) el Indice de declaraciones, donde cada declaracion enlaza con las
// variables y funciones que se definen a continuacion, esta seccion se
// subdivide en Inclusiones, Variables de control, Constantes, Funciones,
// etc. igual que los ficheros Tol,
// d) la secuencia de secciones de Inclusiones, Estructuras de datos,
// Variables de control, Constantes, Funciones de nombre corto, Funciones,
// Proceso, Pruebas y Finalizacion, esta secuencia es la misma que la del
// indice anterior y para cada fichero solo se ponen las que existen,
// e) el Codigo fuente completo con el contenido en codigo realzado de todo
// el fichero y
// f) el Arbol de estructura de ficheros, que es una representacion en Html
// del arbol que se recibe como entrada al documentador, en cada arbol se
// destaca el propio fichero frente al resto, este arbol enlaza con links
// a todos los ficheros del arbol del programa, esta seccion se pone al
// final porque al ser similar para todos los ficheros si se pone al
// principio a modo de menu de navegacion todas las paginas parecen
// inicialmente similares.
// _
// Los ficheros en lenguajes diferentes a Tol, por ejemplo, los de SQL,
// Javascript, Html, Xml, de mandatos, etc. tienen las siguientes secciones:
// a) la Cabecera, cuyo contenido puede salir de sus comentarios de cabecera
// y en otro caso sale de la descripcion del arbol,
// b) la Presentacion, que es opcional,
// c) el Codigo fuente completo con el contenido en codigo realzado de todo
// el fichero y
// b) el Arbol de estructura de ficheros.
//
// Este documentador asume que existen 2 tipos de links a las secciones:
// a) el link local, #, formado por el nombre del programa, el del fichero y
// el nombre de la seccion, este link local podria ser mas simple, con la
// seccion bastaria, pero se necesita todo porque cada seccion puede salir
// a formar parte de otras paginas compartiendo espacio con otras secciones
// con el mismo nombre de seccion o de fichero y
// b) el link global formado por ../programa/fichero.html#link.local.
// Sin embargo, habiendo realizado pruebas en FireFox, Chrome e IExplorer los
// links globales funcionan como locales, sin recargar la pagina, cuando se
// les invoca de forma local por lo que solo se plantea un tipo que es el
// link global con la forma ../programa/fichero.html#seccion. Por lo que
// ambos metodos, links globales y locales o solo globales, funcionan bien.
// _
// Este documentador genera 2 tipos de etiquetas para las secciones que
// coinciden con el titulo de la seccion:
// a) la etiqueta o titulo local que es solo el nombre de la seccion, en Tol,
// en variables y funciones esto coincide con el nombre de la variable o
// de la funcion mas () y
// b) la etiqueta o titulo global formado por etiqueta.local de programa,
// en este caso utilizar la etiqueta global como local resulta reiterado
// ya que, por ejemplo, 12 funciones seguidas irian todas con el funX() de
// Omr.Forms, funY() de Omr.Forms, etc.,
// Es por ello que en este documentador se unifican las etiquetas de la
// siguiente forma:
// a) titulo ventana, enlaces y headers globales = seccion de programa, donde
// seccion es un nombre castellano o un nombre de variable o funcion,
// b) etiqueta a names, enlaces y headers locales que es solo la seccion
// Esta diferencia entre etiquetas se podria crear en una fase posterior,
// pero este documentador la genera porque dispone de toda la informacion para
// crearlas evitandole esta tarea a procesos posteriores.
//
// La informacion que este documentador obtiene de la cabecera de un fichero
// de codigo es:
// a) fichero, file,
// b) autor, author,
// c) clases, classes y
// d) proposito, purpose.
//////////////////////////////////////////////////////////////////////////////
//////////////////////////////////////////////////////////////////////////////
// INCLUDE
//////////////////////////////////////////////////////////////////////////////
Text WriteLn("\nDct.Writer make: begin\n");
//////////////////////////////////////////////////////////////////////////////
Set allInc = Include("tol/inc.tol");
//////////////////////////////////////////////////////////////////////////////
PutDescription("Inclusion de las funciones comunes.", allInc);
//////////////////////////////////////////////////////////////////////////////
//////////////////////////////////////////////////////////////////////////////
// MAKE
//////////////////////////////////////////////////////////////////////////////
Text WriteLn("\nDct.Writer make: process");
//////////////////////////////////////////////////////////////////////////////
Real makDct = Case(
! ObjectExist("Text","DctPre"),
{ Text WriteLn("Error: sin definir la ruta Text DctPre"); FALSE },
! ObjectExist("Set","DctTre"),
{ Text WriteLn("Error: sin definir el arbol Set DctTre"); FALSE },
TRUE, DctMake(DctPre, DctTre));
//////////////////////////////////////////////////////////////////////////////
PutDescription(
"Con DctPre, ruta del directorio contenedor del directorio del programa, y
DctTre, arbol de ficheros a documentar, crea la documentacion de un programa
Tol.",
makDct);
//////////////////////////////////////////////////////////////////////////////
//////////////////////////////////////////////////////////////////////////////
// END
//////////////////////////////////////////////////////////////////////////////
Text WriteLn("\nDct.Writer make: end");2015 asolver.com | Aviso legal | XHTML | Δ Θ Ξ | Creative Commons | Mapa y funciones del sitio
