db2rep — Extrae archivos para repasa de un documento DocBook con convenciones
db2rep [archivo...]
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:
Nombre del archivo de definiciones por generar.
Nombre del archivo de clasificaciones por generar.
Nombre del archivo de secuencia por generar.
Descripción por emplear en los archivos que se generan.
Fecha de actualización que debe emplearse.
Bibliografía por agregar en los archivos que se generan.
Tipo de derechos de reproducción por emplear en archivos que se generan.
Año(s) en los que comienzan a regir derechos de reproducción
Términos de reproducción completos.
Nombres de los autores.
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.
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.
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">
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.
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:, siendo
palabra"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
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>