List types and rendering

This is a set of proposals for changes to the Guidelines and Stylesheets relating to the typology and rendering of lists. The associated SourceForge ticket is Bug 460.

Background
The ticket was originally raised in 2010 due to inconsistencies in the way we were recommending that list/@type be used, and the way we are actually using it in the Guidelines source code and examples. After substantial discussion, Council is largely in agreement over these principal ideas:

 The previously-recommended values for list/@type are mostly not types of list at all:


 * "ordered" is not a type of list; it basically means "precede with a number", which is a rendering feature. Also, all lists are inherently ordered and cannot be otherwise, so despite the long historical usage of "ordered" arising out of early HTML, this term is largely meaningless.
 * "bulleted" is also not a type of list; it's a description of how the list is rendered.
 * "simple" is defined as "list items are not numbered or bulleted", which is of course also a rendering feature. Moreover, the TEI Stylesheets do not follow this instruction, and render simple lists with bullets; and the Guidelines depends on this behaviour.
 * "gloss" is more clearly a "type" of list, and the description of it ("each list item glosses some term or concept, which is given by a label element preceding the list item") supports this.



No values are currently suggested for list/@rend. It is now possible to override suggested valLists for attributes inherited from classes (as @rend is on list), so there's no reason why we should not deal with rendering features of lists using @rend.

@style/@rendition allow very sophisticated descriptions of list-rendering features through CSS, and we should provide some examples of the possibilities for people not familiar with CSS or used to using it in their encoding.



Council is still rather conflicted over whether we should continue to recommend the storage of transcribed text (in the form of item labels/bullets/numbers, chapter and page numbers, etc.) in the @n attribute, or whether this is something which should disappear in the aftermath of the War On Attributes.

Current usage in the Guidelines
This is how we currently (2013-12-20) use and exemplify the use of list/@type and list/@rend:

In Guidelines prose, we use:


 * list type="gloss": 59
 * list type="simple": 107
 * list type="ordered": 32
 * list rend="simple": 4
 * list rend="ordered": 4
 * list rend="specList": 1

In examples:


 * list type="ordered": 19
 * list type="gloss": 25
 * list type="speakers": 8
 * list type="simple": 8
 * list type="bullets": 3
 * list type="unordered": 2
 * list type="index": 2
 * list type="attendance": 2
 * list type="參與者": 1
 * list type="inline": 1
 * list type="indexentry": 1
 * list type="encoders": 3
 * list type="編碼員": 1
 * list rend="runon": 5

list/@rend
Most of the current suggested values for @type, or equivalents of them, would be moved to @rend:


 * @rend="inline" = lists items are rendered inline rather than as blocks, and have no marker of any kind. (CSS: display: inline; list-style-type: none;)
 * @rend="simple" = no markers, bullets or numbers of any type (CSS: list-style-type: none;).
 * @rend="bulleted" = regular bullets (&amp;#183;) (CSS: list-style-type: disc;).
 * @rend="numbered" = decimal numbers (1., 2., 3...) (CSS: list-style-type: decimal;)

list/@type
The only surviving value from the original set is now "gloss". It is odd to have a valList with only a single suggested value, but we cannot really eliminate this one; for one thing, we may add Schematron for it to enforce the presence of label elements. So, for the moment:


 * @type="gloss" = 'each list item glosses some term or concept, which is given by a label element preceding the list item' [unchanged]
 * [...more values needed...?]

For the future, we may want to consider something along the lines of a listGloss element, with specified structure (child glossItem with children term and def, or term and gloss). This would make a lot of sense, but it would provide yet another way of marking up dictionary-like structures (alongside entry and entryFree).

1. Stylesheets
Before we make changes to the Guidelines themselves, we should add the required processing changes into the Guidelines. Current handling should be retained for backward-compatibility, but the new values for @rend need to be incorporated. Doing this first means that the Guidelines themselves will continue to build correctly even as we change the Guidelines source, and the output from steps below will act as a check on the Stylesheet processing changes.

2. Specs
All required changes to be made in list.xml. No other spec files need to be changed. Examples for @type (="gloss"), @rend, and @style attributes need to be added. We should also add appropriate remarks explaining that previous versions of the Guidelines recommended the use of @type for features which are now handled with @rend.

3. Guidelines prose
Section 3.7 needs to be completely rewritten. Among the changes will be:


 * An explanation of the distinction between list types and rendering features.
 * Provision of page-images of source documents for examples, for clarity.
 * An explanation of the suggested usage of @rend, and how these relate to the more sophisticated possibilities available through CSS.
 * Changes in examples:
 * The pair of examples is odd in many ways. They both exemplify a numbered list which is inline, and the numbers themselves are included as labels or as @n attributes. This advice precedes the example: "Each distinct item in the list should be encoded as a distinct item element. If the numbering or other identification for the items in a list is unremarkable and may be reconstructed by any processing program, no enumerator need be specified. If however an enumerator is retained in the encoded text, it may be supplied either by using the n attribute on the item element, or by using a label element." The suggestion that @n should be used for text which appears in the actual transcription should never have survived from P4. The two examples are contradictory in that the labels in the first example includes parentheses around the numbers, while the @n attribute in the second does not include the parentheses; they could only be reconstructed for rendering through special knowledge or specific documentation.
 * At least one example should be added showing the use of the label element where very idiosyncratic item-labels preclude the use of conventional @rend values or CSS.

The lengthy explanation and examples of the encoding of glossary lists seems uncontroversial and can be left alone for the moment, although a future ticket may propose creating a listGloss element to replace this usage.

4. Other Guidelines examples
Outside of the exemplification of the list element itself, other Guidelines examples make use of list and item, so these need to be brought in line with the new recommendations.

5. Guidelines usage
All current usage in the Guidelines needs to be brought in line with the new recommendations. That means looking at all instances of the use of the list element.

6. Raise a ticket for the creation of listGloss
If this is felt to be a good idea, a ticket should be raised for the creation of a listGloss element, so that we can dispense with the last of the suggested values for list/@type.