Capítulo 5. Ayudas para DocBook
Anterior |  | Siguiente

## Capítulo 5. Ayudas para DocBook

## Público e indicadores de logro

Estudiantes o profesores

Indicadores de logro

- Emplea el script inirepdoc y la plantilla que este crea para iniciar rápidamente un proyecto DocBook que emplee las convenciones para `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.

## 1. Plantilla para nuevos contenidos

Después de instalar `repasa` (ver Apéndice C, Instalación) 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 democracia10

Esto 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

- 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:

      make

  o 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`. Tenga 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).

- 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 dist

  que generará el empaquetado `democracia10-1.0.tar.gz` 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 act

  que 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.

- 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

- 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.

  Tenga en cuenta que entre la documentación incluida en la plantilla no hay instrucciones para emplear DocBook, ni las convenciones de `repasa`. Puede consultar ayuda sobre DocBook en [Tutdocbk] o en [TDG] y las convenciones en db2rep(1)

Anterior |  | Siguiente
3. Autoevaluación en un colegio con red local | Inicio | 2. Cambios iniciales