ZedAI Reference Elements

From zedwiki

This page contains an overview of a proposal to deal with various kinds of reference sections in ZedAI.

Contents 1 Definition Lists (and Glossary) 2 Indices 3 Bibliographies 4 Timelines

Definition Lists (and Glossary)

A definition list should contain only the existing term and definition elements for each item, allowing authors to define the usage of terms across an entire document or for a specialized purpose. Authors would be advised to use the element only for glossaries and similar situations where specific terms are being defined, to avoid the problematic use of the element for formatting headings.

Basic Structure:

<glossary>
   <entry>
	<term xml:id="t1"></term>
	<definition ref="t1"></definition>
   </entry>
</glossary>

and/or

<list role="definitions"> 
 <item>
	<term xml:id="t1"></term>
	<definition ref="t1"></definition>
 </item>
</list>

Questions/Requirements:

• Implicit or explicit association of terms and defs in this context?

Indices

Indexes are not lists in the traditional sense (they are not prefixed with bullets or numbers). They are grouped, alphabetical listings of entries, which is why they are often confused and formatted as lists and list items.

For DAISY talking book production, each section of an index is normally included with a heading, regardless of whether the print original contained any headings or any entries for that section of the alphabet.

Basic Structure:

<index> <!-- either entry* or section*<entry> -->
 <h>Index Heading</h>
 <p>prefatory paragraph</p>
 <section role="part"> <!-- or part -->
    <h>A</h>
    <entry> Will use a lot of <reference /> elements of different kinds</entry>
 	<entry>
	  <entry /> <!-- note: nested -->
	</entry>
 </section>
</index>

Questions/Requirements:

• To be faithful to print, headings should not be inserted as content in the files when they are not part of the print original. One method for handling this problem would be to include an attribute (@custom-hd, for example) that could be used when transforming/reading the file in the absence of a header when one is needed. The proper heading cannot always be determined by the first character of the first entry, making automated approaches somewhat problematic.
• What to do about sections of the alphabet that are not in the print, but that are necessary for talking books? (Why they are required for talking books is another question.) Empty content models will have to be allowed. CNIB uses an attribute in these cases to distinguish the dummy sections that we've added that were not part of the original content (@custom-content). The empty sections translate into the heading and "No entries" text that is included in DAISY 2.02 output or are removed for braille (and can only occur in indices and bibliographies).

Bibliographies

Bibliographies share a lot of the same conventions with indices, but with a little more fluid structure internally:

• both contain entries that are incorrectly structured as lists;
• both contain groupings of entries under alphanumeric headings;
• both allow empty sections for talking book production; and
• both have headings inserted when none present for talking book production.

Bibliographies are formatted differently from indices when output, however: hanging indents after the first line represent a continuation of the entry (for print, braille, etc.). Bibliographies never(?) appear to contain subentries, unlike indices.

Basic Structure:

<bibliography> <!-- either entry* or section*<entry> -->
 <h>Bibliography Heading</h>
 <p>prefatory paragraph</p>
 <section role="part"> <!-- or part -->    
    <entry></entry>
 	<entry></entry> <!-- no nested entries -->
 </section>
</bibliography>

Questions/Requirements:

• See Indices above for overlap issue with groupings and headings.
• Some bibliographic sections are prose and not narrative, so a restrictive content model that allows basic elements within a bibliography section may be necessary.

Timelines

Timelines associate dates with events. The ZedAI schema already includes a date element which could be used to re-structure a generic list into a timeline.

Basic Structure:

<list> 
 <item>
	<date>1980</date>
	<p>...</p>
 </item>
</list>

<list role="timeline"> 
 <item>
	<bridgehead><date>1980</date> to <date>1990</date></bridgehead>
	<p>...</p>
 </item>
</list>

Questions/Requirements:

• Is a more specialized content model necessary? The date element fails when textual periods are used, requiring an alternation between date, bridgehead with dates and bridgeheads to signify the context of the events.