missing `<listRef>`s?

[sydb]

A quick analysis demonstrates that many specifications do not have a <listRef>. Most of them probably should.

fn.1	# have <listRef>	# do not	% do	% not
model.*	72	56	56%	44%
teidata.*	1	35	03%	97%
att.*	58	27	68%	32%
macro.*	6	2	75%	25%
listRef	0	1		all 1
outputRendition	0	1		all 1
paramList	0	1		all 1

Those last 3 are individual elements. I did not list the other 580+ elements that do have a <listRef>. (There are no specification files that have > 1.)

Note-to-self
$ xsel -t -m "/*[count(//t:listRef)=0]" -f -n Source/Specs/*.xml | perl -pe 's,\..*,.,;' | rank
and the same with 1 instead of 0. Then created table of values by hand; then added percentages w/ Emacs macro & hand editing.

[sydb]

I assigned 4 people to this ticket because there are just over 123 cases to be checked. I thought the labor could be divided among us.

[trishaoconnor]

I have added <listRef>s to the Spec pages of the individual elements: <listRef>, <paramList>, and <outputRendition>. These were the most straightforward instances which clearly required a <listRef> and where there was a specific section in the Guidelines to which we could point.

I am also updating the label to Status:NeedsDiscussion as the rest of the specifications in the above table require discussion at Council.

[ebeshero]

@sydb @trishaoconnor I'm working on a little sideproject now that involves experimentally producing a knowledge graph built from the TEI P5 subset and Guidelines chapter files. So I'm writing XSLT today that is basically searching up all pointers and references (among other things) and making little statements in weird JSON lines that read something like:

"This chapterSection with id 'mshy' isConnectedTo that elementSpec with id 'HISTORY'."
and also
"This elementSpec with id 'HISTORY' isConnectedTo that chapterSection with id 'mshy'."

For reasons I'll disclose in some upcoming conference talks (or sooner if we get to talking about it), this listRef ticket could be pretty helpful to complete, but I'm also wondering if we should write a similar kind of XSLT to solve this ticket?

XSLT reading the collection of TEI Guidelines chapters could:

• search out the all pointers to elementSpec files
• check those elementSpec files to see which ones are missing pointers back to their chapters and, with an identity transformation, add the missing listRef and internal pointers.

I want to make sure I'm understanding what's needed on the ticket first, but since I'm writing a somewhat related XSLT anyway, I would be happy to try this out and check it in with a PR for review...Does this sound feasible, @sydb ?

[sydb]

Well, it does not sound crazy, but I am not convinced it is going to be particularly helpful, either. First and foremost, we are not interested in pointing from a tagdoc page to everywhere the construct is mentioned in the Guidelines, only to those places where it is discussed in some depth. E.g., the part of the Guidelines that says “For ducks, use the <quack> element, not the <waddle> element.” maybe should be pointed to by the quack tagdoc page, but almost certainly not from the waddle tagdoc page. So even if we wrote such XSLT, a human would have to go through the results thoroughly.

Second, we are talking not about tagdoc pages for elements, but rather for classes, datatypes, and macros. For datatypes and macros such an XSLT may actually prove kinda useful, as there are probably not too many places they are mentioned that are not a place they are discussed in depth. But for classes we need to make some decisions, first. If a class has 3 members, <a>, <b>, and <c>, does its tagdoc page refer to anyplace any one of those three are discussed in depth, or only where the class itself is discussed? Or, for attribute classes, anywhere one of the defined attributes is discussed in depth?