ZedAI Lists Proposal

From zedwiki

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

Contents 1 Background 2 Requirements 3 Candidate Solution 3.1 Generic Lists 3.2 sketch area generic lists 3.2.1 Enum alternatives 3.2.1.1 Alt 1 3.2.1.2 Alt 2: CSS2 3.2.1.3 Alt 2: CSS3 3.2.1.4 Alt 4: best of from CSS2 + CSS3 3.2.2 On inherit 3.2.3 Standard undeordered list 3.2.4 Standard ordered list using decimal 3.2.5 Standard ordered list using alpha 3.2.6 Special prefix list 3.2.7 Freaky ordered list with gap (1,2,3,8) 3.3 Important prose points and questions 3.4 Implementation 3.5 Definition Lists (and Glossary) 3.6 Indices 3.7 Bibliographies 3.8 Timelines 3.9 List Items with Headings 4 Reference 4.1 Issues on the ZedAI Tracker

Background

With the demise of the XHTML2 Working Group's activity, the ZedAI Working Group has been faced with the question of what to inherit from that standard. The first consideration facing the group is whether the legacy xhtml list constructs (ol, ul, and dl) should be ported forwarded with this specification.

Re-employing these elements would actually be taking a step back from the z3986.5 standard, which already had removed the ol and ul elements in favour of a single list element. This approach to lists is more in keeping with the function of lists, which does not change depending on whether each item is prefixed with a bullet, letter, number or any other type of character.

The only solid argument in favour of XHTML list element inheritance is that it is in keeping with the principle of re-use of elements, especially from well-known grammar sets.

The arguments against inheritance of these lists, however, is more compelling:

• having two high-level elements merely to distinguish that there is sequential ordering in one and not the other is a weak argument when this information can be conveyed in other, more generic, ways;
• there is widespread misunderstanding and misuse of the definition list element dl -- it is often used in other contexts than for proper definition of terms (note also that ZedAI includes term and definition elements already);
• these elements do not fit well with specialized content models, such as for bibliographies, indices and timelines.

For these reasons, an investigation of alternate models seem prudent, and the following sections will outline some possible alternate approaches.

Requirements

A list module must be capable of covering all of the following structures:

• ordered lists -- where items are prefixed by sequentially ordered alphanumeric characters;
• unordered lists -- where items are prefixed by bullets or other glyphs;
• definition lists -- where each item defines a single term (e.g. glossaries);
• timelines -- where each item associates a date or time period with one or more events;
• bibliographies -- where each entry is a reference to another work; and
• indices -- where each item is an entry pointing back to a location in the book or to another location in the index.

The list element(s) developed must also be capable of handling the following specialized requirements:

• list items that start with or contain headings;
• sequentially ordered lists where the first list item's prefix begins mid-sequence (e.g. a numeric list where the first item is number "4.").

Candidate Solution

Generic Lists

A single, standard list element could be used to cover cases where the only distinction that has to be made is in the prefix for the list item. This element would cover all simple alphanumeric and bullet list constructs.

Basic Structure:

<list> 
 <item></item>
 <item></item>
</list>

Questions/Requirements:

• Is there any use for the @type attribute defined in DTBook? It's primary purpose is to define if the list is ordered, unordered or preformatted, but this information should be implied by @enum. @type may be redundant and could take on the purpose of @enum in defining the kind of list.
• Is a way of including the literal expression of item prefix a requirement? (as an attribute) For print recreation, a simple enumeration list may not be sophisticated enough for storing whether letters/numbers were followed by period, parens, nothing, etc.
• A more comprehensive enumeration of list prefix types may be necessary. How to account for all the possible variation people will need? (ties back into prefix)
• Is there any need for the lic grouping component? Will the revision made here obsolete that generic container element.
• A start attribute is probably still required for lists that begin mid-sequence (a co-occurence constraint on the list type could be used to prevent the attribute from being added for unordered lists)
• Do we need to account for list headings, or should bridgehead be used when lists are preceded by a heading?

Dtbook lists enum types: http://www.daisy.org/z3986/structure/SG-DAISY3/part2-block.html#lists

sketch area generic lists

Enum alternatives

Alt 1

[1|A|a|I|i|anyOtherChar], people will hate that for bullet lists. If anyOtherChar, it is repeated for each item (the other have incremental behavior) -->

Alt 2: CSS2

enum would be

[none|disc|circle|square|armenian|decimal|decimal-leading-zero|georgian|lower-alpha|lower-greek|lower-latin|lower-roman|upper-alpha|upper-latin|upper-roman|

Alt 2: CSS3

http://www.w3.org/TR/css3-lists/

<glyph>

   box | check | circle | diamond | disc | hyphen | square 

<algorithmic>

   armenian | cjk-ideographic | ethiopic-numeric | georgian | hebrew | japanese-formal 

| japanese-informal | lower-armenian | lower-roman | simp-chinese-formal | simp-chinese-informal | syriac | tamil | trad-chinese-formal | trad-chinese-informal | upper-armenian | upper-roman

<numeric>

   arabic-indic | binary | bengali | cambodian | decimal | decimal-leading-zero 

| devanagari | gujarati | gurmukhi | kannada | khmer | lao | lower-hexadecimal | malayalam | mongolian | myanmar | octal | oriya | persian | telugu | tibetan | thai | upper-hexadecimal | urdu

<alphabetic>

   afar | amharic | amharic-abegede | cjk-earthly-branch | cjk-heavenly-stem 

| ethiopic | ethiopic-abegede | ethiopic-abegede-am-et | ethiopic-abegede-gez | ethiopic-abegede-ti-er | ethiopic-abegede-ti-et | ethiopic-halehame-aa-er | ethiopic-halehame-aa-et | ethiopic-halehame-am-et | ethiopic-halehame-gez | ethiopic-halehame-om-et | ethiopic-halehame-sid-et | ethiopic-halehame-so-et | ethiopic-halehame-ti-er | ethiopic-halehame-ti-et | ethiopic-halehame-tig | hangul | hangul-consonant | hiragana | hiragana-iroha | katakana | katakana-iroha | lower-alpha | lower-greek | lower-norwegian | lower-latin | oromo | sidama | somali | tigre | tigrinya-er | tigrinya-er-abegede | tigrinya-et | tigrinya-et-abegede | upper-alpha | upper-greek | upper-norwegian | upper-latin

<symbolic>

   asterisks | footnotes 

<non-repeating> circled-decimal | circled-lower-latin | circled-upper-latin | dotted-decimal | double-circled-decimal | filled-circled-decimal | parenthesised-decimal | parenthesised-lower-latin

Alt 4: best of from CSS2 + CSS3

• none (or absence of attribute)

Non-incremental:

• box
• check
• circle
• diamond
• disc
• hyphen
• square

Incremental:

• decimal
• decimal-leading-zero
• lower-alpha
• lower-greek
• lower-latin
• lower-roman
• upper-alpha
• upper-greek
• upper-latin
• upper-roman

On inherit

Inheritance is on by default. This means that a nested list inherits both the style type, and any counter value in the case of an ordered list. If we are lucky, CSS specifies this somewhere, so we can reference it.

Inheritance can be overriden on sublists simply by specifying the prefix and start attributes. This means the enum attribute needs to be optional.

Standard undeordered list

<list prefix="disc"> 
 <item></item>
 <item></item>
</list>

Standard ordered list using decimal

<list prefix="decimal" start="3"> <!-- @start only relevant when... or check with SCH -->
 <item></item>
 <item></item>
</list>

Standard ordered list using alpha

<list prefix="upper-alpha" start="C"> <!-- @start only relevant when... or check with SCH -->
 <item></item>
 <item></item>
</list>

Special prefix list

<!-- this mode is activated by the absence of @prefix, then <item><prefix> becomes allowed (but not required, see definition lists, glossary) -->
<!-- prefix can either have a src attribute or child nodes, compare separator -->
<!-- @prefix and prefix as element are not allowed -->
<!-- the prefix element kills all inheritance -->
<list> 
 <item><prefix src="img" /></item>
 <item><prefix><svg:svg>...</svg:svg></prefix></item>
</list>
<!-- prefix is prolly not the right name? -->

Freaky ordered list with gap (1,2,3,8)

<list prefix="decimal" start="1"> <!-- @start only relevant when... or check with SCH -->
 <item></item>
 <item></item>
 <item></item>
 <item><prefix>8</prefix></item>
</list>

Important prose points and questions

• inheritance, thats its on by default
• inheritance, that the prefix element kills all inheritance, for following siblings and sub lists
• which of the prefix values are ordered, and which are unordered

Implementation

• Note: dont make list allowed as child of list
• Maybe we should have two attributes: optional type="ordered|unordered", and optional @prefix[]

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 (see the section on headings in lists below).

Basic Structure:

<list role="glossary"> or
<list role="definitions"> 
 <item>
	<term xml:id="t1"></term>
	<definition for="t1"></definition>
 </item>
</list>

Questions/Requirements:

• Should be possible to allow more than one term to be associated with a single definition and a single term to be associated with one or more definitions.

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.

List Items with Headings

One of the primary reasons for abusing definition lists is list items with headings. The generic lists should allow for headings to start each bullet so that there is no requirement to misappropriate other tags.

Basic Structure:

<list> 
 <item>
	<bridgehead>the header</bridgehead>
	<p>...</p>
 </item>
</list>

Reference

• DTBook Lists
• XHTML2 List Module
• TEI List Element
• Docbook Lists
• HTML5 ul
• HTML5 ol

Issues on the ZedAI Tracker

• Issue 24
• Issue 75
• Issue 76
• Issue 77 ?