#630 use of <listRef> in specs

AMBER
open
None
5(default)
2014-11-19
2013-12-28
No

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.

Discussion

  • Lou Burnard

    Lou Burnard - 2014-05-19

    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.

     
  • James Cummings

    James Cummings - 2014-05-19

    Assigning to Lou Burnard to triage and propose a recommendation to Council, implement, etc.

     
  • James Cummings

    James Cummings - 2014-05-19
    • assigned_to: Sebastian Rahtz
     
  • Kevin Hawkins

    Kevin Hawkins - 2014-05-19
    • assigned_to: Sebastian Rahtz --> Lou Burnard
     
  • Lou Burnard

    Lou Burnard - 2014-05-19

    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.

     
  • James Cummings

    James Cummings - 2014-11-19

    Raleigh F2F 2014-11-19; Prodding LB to progress the ticket.

     

Get latest updates about Open Source Projects, Conferences and News.

Sign up for the SourceForge newsletter:





No, thanks