#630 use of <listRef> in specs
Our use of <listRef> in specs is inconsistent. We should decide our preferred approach, document it in tcw20, and then fix any existing specs that don't match this practice.
For definitions of elements, we generally refer to one or more chapters in which the element is discussed. For definitions of element or attribute classes, though, we seem to refer to the chapter documenting the module that defines this element or attribute.
This, however, leads to some strange situations. For example, the spec for att.transcriptional has a <listRef> pointing to #ST, which discusses the TEI infrastructure and happens to define att.transcriptional, rather than to #PH, where these attributes are actually discussed. I think this problem is unique to #ST, which contains all sorts of things not actually explained in that chapter. But in the user interface it sends the user to a chapter irrelevant to the class.
In cases like this, perhaps we should add a second <listRef> to point to the chapter where the elements or attributes in the class are actually discussed. Or perhaps we should just remove the reference to #ST.
The original intent was to have the listRef point to where the element (etc) is first defined, since that is also where it's mostly discussed. This remains true of most elements but not, unfortunately, of attribute classes, some of which are first defined in ST as dummies, but not actually discussed until much later. The links to ST for attribute classes need to be reviewed, as Kevin suggests, and an additional reference to the places where they are properly discussed added.
Assigning to Lou Burnard to triage and propose a recommendation to Council, implement, etc.
The xpath //classSpec[@type='atts']//listRef/ptr/@target finds 61 cross references, of which 4 are to #ST (att.ascribed, att.editLike, att.sortable, att.transcriptional), and 4 to #STECAT (att.damaged, att.typed, att.spanning, att.citing). It shouldn't be too hard to find (or add) specific discussions of these 8 classes elsewhere. All the others already point to different parts of the Guidelines.
Raleigh F2F 2014-11-19; Prodding LB to progress the ticket.