db2rep
Anterior | Documentación de referencia de programas | Siguiente

## Nombre de referencia

db2rep — Extrae archivos para `repasa` de un documento DocBook con convenciones

## Sinopsis

`db2rep` [archivo...]

## DESCRIPCIÓN

El script db2rep convierte uno o más archivos escritos en DocBook con convenciones para `repasa` en tres archivos XML con definiciones (def(5)), clasificación (clasif(5)) y secuencia (sec(5)). Los archivos generados y las convenciones son apropiadas para procesar material de estudio organizado de acuerdo a la legislación colombiana vigente para colegios (Ley 115/1994).

Este script no recibe opciones por la línea de comando, pero puede adaptarse empleando las siguientes variables de ambiente:

DEF

  Nombre del archivo de definiciones por generar.

CLA

  Nombre del archivo de clasificaciones por generar.

SEC

  Nombre del archivo de secuencia por generar.

DESC

  Descripción por emplear en los archivos que se generan.

FECHA

  Fecha de actualización que debe emplearse.

BIBLIO

  Bibliografía por agregar en los archivos que se generan.

TIPO_DERECHOS

  Tipo de derechos de reproducción por emplear en archivos que se generan.

TIEMPO_DERECHOS

  Año(s) en los que comienzan a regir derechos de reproducción

DERECHOS

  Términos de reproducción completos.

AUTORES

  Nombres de los autores.

IDSIGNIFICADO

  Es la cadena con la que se completan identificadores de significados. Si no se especifica una se emplea `sig`.

Para extraer esta información hemos supuesto que el documento DocBook es material de referencia para estudiantes, que ha sido escrito por uno o más profesores, y que emplea un formato más o menos estándar:

- Cuenta con logros y sus indicadores de logros escritos, por ejemplo, al comienzo de una guía o sección o capítulo.

- Incluye definiciones importantes diferenciadas del resto del documento y valoradas de acuerdo a su relevancia. Estas definiciones deben relacionarse con los indicadores de logro que desarrollan. Las palabras podrían servir como elementos del índice del documento, o junto con las definiciones podrían emplearse en un glosario.

- Ejercicios relacionados con indicadores de logro y sus soluciones. Las soluciones podrían emplearse para generar un solucionario.

- Un orden para presentar los logros e indicadores de acuerdo al periodo en el que se presenten.

Esta información es extractada y dejada en archivos XML para `repasa`, que emplean el formato `docbook`. Queda separada así:

- Las definiciones y significados quedan en el archivo para definiciones

- Los logros e indicadores quedan en el archivo de clasificación con tipos `Logro` y `Indicador`. Dentro de la clasificación de un indicador quedan referenciados los significados que se relacionen con el indicador junto con el peso, y quedan incluidos los ejercicios que se relacionen con el indicador.

- La división en periodos queda en el archivo de secuencia con tipo `Periodo`. Dentro de cada secuencia quedan referenciados los indicadores del periodo correspondiente.

## Convenciones para documentos DocBook

Hemos buscado adaptar DocBook 4.1.2 sin infringir las expectativas de un procesador típico para este formato. Para esto hemos empleado especialmente los atributos `role`, `id` y `userlevel` que son comunes a todos los elementos de DocBook, así como extensiones a las hojas de estilo que permiten procesar las adaptaciones. A continuación se presenta en detalle cada una de las adaptaciones.

### Periodos

El orden en el que se especifiquen y procesen los archivos fuente debe corresponder al orden de presentación del material en periodos. Puede especificarse el inicio del material para un periodo en cualquier elemento que tenga el atributo `role="periodo"`. Se supone que el material de un periodo termina si no hay más archivos por procesar o al iniciarse material para un nuevo periodo. Se espera que como parte del material para un periodo se especifique al menos un indicador de logro. El mismo elemento con atributo `role="periodo"` (por ejemplo `chapter` o `sect1`) debe indicar el identificador del periodo en el atributo `userlevel`. Por ejemplo:

     <chapter role="periodo" userlevel="p1">

### Logros e indicadores-de-logro

Tanto un logro como un indicador de logro se esperan especificados en un elemento `<listitem>` con atributo `role="logro"` o `role="indicador"` respectivamente, y con identificador especificado en el atributo `id`, por ejemplo:

     <listitem role="logro" id="escucha"><para>Escucha música
     y sigue el ritmo</para></listitem>

o

     <listitem role="indicador" id="escucha.clave"><para>Identifica
     el instrumento que lleva la melodía</para></listitem>

Note que el identificador del logro además de ser un identificador XML (ver xmlintro(5)), no debe incluir el caracter punto '.', mientras que el identificador de un indicador debe tener este caracter, precedido del identificador para el logro que el indicador desarrolla y seguido de un identificador particular para el indicador que lo distinga de otros posibles indicadores del mismo logro.

El logro que desarrolla uno o más indicadores debe especificarse antes (digamos los logros al comienzo de un capítulo mientras que los indicadores al comienzo de una sección), y los indicadores deben especificarse cómo parte de algún periodo.

### Definiciones

Una definición debe constar de una palabra,un significado, un peso y un indicador de logro asociado (en realidad pueden ser varias palabras separadas por espacio o números o caracteres arbitrarios) Con respecto al documento la palabra puede ser también una entrada del índice.

Para especificar una palabra que también aparezca en el índice se emplea el elemento `indexterm` con el atributo `role="pal"`, a continuación de este elemento o al menos antes de otro que especifique una definición debe incluirse la definición en un párrafo `para` con atributo `role="sig"`. Otro atributo del párrafo debe ser `id` cuyo valor será el identificador de un indicador seguido del caracter punto ('.') y una cadena que diferencie la palabra de otras del mismo indicador (se sugiere la palabra misma o una variación). El párrafo con la definición también debe emplear el atributo `userlevel` para indicar el peso de la palabra con respecto a otras (se sugiere un número de 1 a 5, siendo 5 las más importantes) y si se desea, separada con el caracter dos puntos (':'), la heurística que una herramienta de repaso (ver repasa(1) o repasatk(1)) debería emplear al valorar respuestas de quien estudie la definición ---repasa y repasatk soportan `dist` e `indist` para tener en cuenta o no diferencia entre mayúsculas y minúsculas en respuestas abiertas. Por ejemplo:

     <indexterm role="pal">
       <primary>Denario</primary>
     </indexterm>
     <para role="sig" userlevel="3:indist" id="contexto.historia.denario">Moneda empleada por los romanos del tiempo de Jesús, equivalía al jornal de un día de trabajo agrícola.</para>

Tenga en cuenta que las hojas de estilo distribuidas con `repasa` no presentan los párrafos con definiciones.

Una definición cuya palabra no se desea incluir en el índice se especifica en un párrafo con atributo `role="nipal:`palabra`"`, siendo `palabra` la palabra (o palabras) que se define. El texto del párrafo debe corresponder al significado y los atributos `id` y `userlevel` se emplean como en el caso de definiciones cuya palabra se incluye en el índice. Por ejemplo:

     <para role="nipal:1/128" id="contexto.historia.val-lepton" userlevel="1">El
     leptón era una moneda de cobre y zinc, cuyo valor correspondía a 1/2
     cuadrante y a ... de denario</para>

De emplear la misma palabra con diversos significados agregue a la identificación una cadena que distinga unas de otras separadas con el caracter '.' Por ejemplo una segunda definición para "denario" podría tener como identificación `contexto.historia.denario.2`

### Ejercicios

Se espera que los ejercicios se incluyan en secciones `qanda` de preguntas y reespuestas. El ejercicio en un elemento `question` (o en un párrafo dentro de este elemento) con atributo `role="ejer"`, y la respuesta en el elemento `answer` que debe ir después de `question`. Se espera que el elemento que incluya `role="ejer"` también incluya el atributo `id` cuyo valor debe ser el identificador del ejercicio que se compone del identifcador del indicador de logro que desarrolla, seguido del caracter punto ('.') y una cadena que distinga al ejercicio de otros del mismo indicador --- Tanto en el enunciado del ejercicio como en la respuesta, evite emplear las cadenas %-% y %;%.

     <question role="ejer" id="dh.busca.carta">
     <para>Un camino directo que puede seguir para buscar determinar
     si cierta información de derechos humanos es cierta o falsa es
     preguntar por confirmación directamente a quienes la información
     afecte. ¿Dónde puede consultar casos actuales de derechos humanos
     en Colombia y direcciones donde pueda escribir solicitando confirmación?
     </para>
     </question>
     <answer><para>
     Entre las organizaciones que mantienen información
     reciente sobre casos en Colombia están:
     <itemizedlist>
     <listitem><para>Amnistía Internacional.
     <ulink url="http://www.amnesty.org"/>.   Además de mantener información
     publicada (reportes, cartas, acciones urgentes), cuenta con una lista de
     distribución abierta de acciones urgentes.  Estas acciones incluyen
     direcciones a las cuales escribir.</para></listitem>
     <listitem><para>Human Right Watch. <ulink url="http://www.hrw.org"/>.
     Publica reportes con regularidad.  Cuenta con lista de noticias.</para></listitem>
     <listitem><para>Banco de violencia política de Justicia y Paz &
     CINEP.  <ulink url="http://www.nocheyniebla.org"/>. Registra
     todos los casos de violación a derechos humanos de los que se tiene
     noticia, así como reportes periódicos. Cuenta con lista de noticias.</para></listitem>
     </itemizedlist>
     </para></answer>

Anterior | Subir | Siguiente
edsec | Inicio | latex2rep