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

[Kevin Hawkins]

Okay, bug created:

https://sourceforge.net/p/tei/bugs/630/

--Kevin

On 11/17/13 12:40 AM, Martin Holmes wrote:
> 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
>>