Estudiantes o profesores
Emplea el script inirepdoc y la plantilla que este crea para iniciar rápidamente un proyecto DocBook que emplee las convenciones para repasa
Este script permite crear una plantilla para un documento DocBook que emplea las ayudas de repasa.
Emplea las convenciones de repasa para escribir un documento DocBook.
Emplea el Makefile para generar documentación, distribuciones, generar archivos de repasa y opcionalmente para publicar en un sitio de Internet.
repasa ofrece varios tipos de ayudas para DocBook 4.1.2 (ver [DocBook]):
Convenciones para escribir material de estudio de acuerdo a la legislación colombiana vigente para colegios (ver [L115-1994]).
Scripts y Makefiles que esperamos hagan más eficiente el desarrollo de documentos DocBook (especialmente los que sigan las convenciones).
Hojas de estilo y documentación para personalizar DocBook a las convenciones propuestas.
Aunque las convenciones son medianamente flexibles dentro del marco de la legislación educativa colombiana, resultan aún más apropiadas cuando se desarrolla material para una asignatura, la cual se estudia en diversos periodos. Sugerimos que en cada periodo se divida el tema por estudiar en una o más unidades, cada una de las cuales está dividida a su vez en guías. Cada unidad tiene además asociados unos logros y cada guía unos indicadores de logro. Además de indicadores de logro particulares, cada guía también puede incluir definiciones clave que desarrollan los indicadores y ejercicios que busquen valorarlos.
En cuanto a documento DocBook puede ser:
Un libro con índice y bibliografía, en el que cada capítulo corresponda a una unidad. Cada unidad puede tener como parte de la introducción los logros y sus secciones pueden corresponder a guias. Sugerimos que cada guía tenga los indicadores de logro como introducción, el desarrollo del contenido tal vez dividido en subsecciones, con las definiciones importantes especificadas, y tal vez concluida con lecturas recomendadas y ejercicios (cuyas soluciones se podrían incluir en un apéndice o en un solucionario separado). Como ejemplo puede basarse en [AA1.1]
Un libro con las mismas características del anterior pero con logros presentados al comienzo e indicadores de logros para cada capítulo, por ejemplo este documento.
Después de instalar repasa (ver Apéndice C) puede iniciar rápidamente un proyecto en DocBook. Vaya al directorio en el que creará el directorio de su proyecto (digamos cd ~), escoja un nombre (digamos democracia10) y ejecute el script inirepdoc así:
inirepdoc democracia10Esto creará un subdirectorio democracia10 con una plantilla para un proyecto DocBook que usa las ayudas de repasa. Entre las características de la plantilla están:
El documento de ejemplo consta de dos capítulos (cap1.xdbk y cap2.xdbk), índice generado automáticamente (indice.xdbk) y bibliografía (biblio.xdbk) incluidos en democracia10.xdbk. El documento emplea la estructura que sugerimos e incluye ejemplos de logros, indicadores, definiciones, citas bibliográficas, ejercicios y gráficas.
Cuenta con un script de configuración (conf.sh) que busca hacer portable las fuentes de los contenidos a diversos sistemas operativos tipo Unix y a diversos ambientes DocBook. Este script, que debe ejecutar antes de procesar por primera vez el documento, detecta las herramientas que haya disponibles en su sistema (e.g procesador de DocBook, ubicación de hojas de estilo, ruta de instalación) y prepara el resto de infraestructura (e.g Makefile, hojas de estilo personalizadas) de acuerdo a estas. Debe ejecutarse desde el directorio del proyecto, por ejemplo:
cd democracia10 ./conf.sh
Nombre del script de configuración de la plantilla creada con inirepdoc.
Incluye un Makefile que entre otras, busca facilitar la generación del documento en los formatos HTML, PostScript y PDF. Para generar documentación en estos formatos, después de la configuración emplee:
makeo si desea generar sólo HTML make html/index.html o para generar sólo PostScript make imp/democracia10.ps o para generar sólo PDF make imp/democracia10.pdf. También es posible validar la sintaxis del documento con make valida Puede revisar la ortografía con make ispell que generará un texto plano que es corregido usando el el diccionario democracia10.ispell. Teng en cuenta que los errores de ortografía debe corregirlos en las fuentes (las correcciones que haga desde la sesión con ispell sólo modificarán el texto plano generado).
Para generar los 3 tipos de documentos (HTML, PostScript y PDF) en un documento DocBook basado en la plantilla generada por inirepdoc basta usar ...
El Makefile incluye reglas que facilitan la distribución de fuentes y la publicación de nuevas versiones, actualizando un sitio en red (por ejemplo una página web). Para generar una distribución de fuentes:
make distque generará el empaquetado democracia10-1.0.tgz con las fuentes de su proyecto. Para liberar una nueva versión, actualizando un sitio en Internet o en una intranet (después de configurar para su caso como se explica más adelante):
make actque generará y comprimirá el PostScript (democracia10-1.0.ps.gz), preparará un empaquetado con el HTML (democracia10-1.0_html.tar.gz) y copiará a un directorio en otro computador las fuentes comprimidas, el PostScript, el PDF, el comprimido con HTML y las páginas HTML.
Con esta regla del Makefile de la plantilla para documentos DocBook se genera una distribución de fuentes.
Incluye un script (herram/db2rep) que extrae del documento DocBook información de los elementos que siguen las convenciones para periodos, definiciones, ejercicios, logros e indicadores y genera: archivo de definiciones (democracia10.def), archivo de clasificaciones (democracia10.cla) y archivo con secuencia (democracia10.sec). Puede ejecutarlo con:
make repasa
Con esta regla del Makefile de la plantilla para documentos DocBook se generan los archivos para repasa (ejecutando el script db2rep).
Incluye algo de documentación que usted puede modificar para que otras personas que reciban las fuentes de sus contenidos pueda emplearlos o continuar el desarrollo. Tal documentación también puede servirle para complementar la presentada en este capítulo:
Instrucciones básicas para quienes generarán la documentación y para quienes desean continuar el desarrollo: Leame.txt
Puede ver más sobre el script de configuración con ./conf.sh -M. También puede ver los comentarios del Makefile y demás archivos.