[tei-council] <listRef>s in specs for classes

[Martin Holmes]

This should be a ticket, I think. I agree that we need to explain how to 
use <listRef> in TCW20. Several times in the past I've come across 
pointers to the wrong chapter, or to a section that's only peripherally 
relevant to the element or class. I usually add a more useful reference 
first in the list; on one occasion, I think I removed a pointer to 
something completely irrelevant. I don't think a second <listRef> is 
required, though.

Cheers,
Martin

On 13-11-16 08:23 PM, Kevin Hawkins wrote:
> tcw20 does not explain how to use <listRef> when writing or editing a
> spec.  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, how do we feel about adding a second <listRef> to
> point to the chapter where the elements or attributes in the class are
> actually discussed?  Or actually removing the reference to #ST?
>
> Whatever we decide, we should record this in tcw20.
>
> Kevin
>