#457 make explicit difference between tagUsage and ODD documentation


Per Lou's comment on TEI-L:


it seems that tagUsage is only useful when describing use of an element, but if you want to describe more complex usage, you need to use an ODD. However, I am having trouble finding this stated explicitly in the Guidelines.

The introduction to section 2.3.4 (#HD57) implies that more detailed information might be elsewhere in the header, and section (#HD57-2) does not mention any other location where you might put such information.

I might also expect to find a mention of this use of an ODD in section 1.2 (#STIN) and section 23.3 (#MD). I confess to not having time right now to re-read these sections closely, so I might have missed a reference. But I would also expect this use to be stated somewhere obvious, near the beginning of these sections.


  • Martin Holmes

    Martin Holmes - 2013-05-24

    This should be linked with this ticket:


    which I'm all-too-slowly working on. The ODD documentation needs to be more detailed and user-friendly when we refer people to it.

  • James Cummings

    James Cummings - 2013-11-09

    Should this ticket be closed and the concern rolled into the ticket Martin mentions above?

  • Kevin Hawkins

    Kevin Hawkins - 2013-11-10
    • Description has changed:


    --- old
    +++ new
    @@ -1,6 +1,6 @@
     Per Lou's comment on TEI-L:
     it seems that tagUsage is only useful when describing use of an element, but if you want to describe more complex usage, you need to use an ODD.  However, I am having trouble finding this stated explicitly in the Guidelines.
    • Priority: 5 --> 1(low)
  • Kevin Hawkins

    Kevin Hawkins - 2013-11-10

    This is about revising part of the Guidelines, and the other ticket is about revising some of the text on www.tei-c.org outside of the Guidelines. I've just linked back from the other ticket to this one, suggesting they be dealt with at the same time. But I suggest keeping them as separate tickets.

  • Piotr Banski

    Piotr Banski - 2013-11-10

    It feels like déjà-vu, because I recall talking about it, but maybe it was during one of Council meetings, rather than in tickets: in 2010? in Zadar, I argued that tagUsage is a good place for keeping DCR references, in environments with a single general ODD that nevertheless display lots of internal variation and dynamics. My example was the Freedict project, with numerous pairs of bilingual dictionaries.

    A relatively simple implementation can be seen in e.g. [1] -- I've chosen this one because it's not a download bomb, but there are better examples, I think, in some others.

    (In Freedict, I made the reference structure indirect, because of some i18n issues that I was looking at at the same time, and the relevant central linking resource is in [2])

    [1]: https://sourceforge.net/p/freedict/code/HEAD/tree/trunk/eng-pol/eng-pol.tei
    [2]: https://sourceforge.net/p/freedict/code/HEAD/tree/trunk/shared/FreeDict_ontology.xml

    • Kevin Hawkins

      Kevin Hawkins - 2013-12-26

      Piotr, what are "DCR references"?

  • Kevin Hawkins

    Kevin Hawkins - 2013-12-26

    At the November 2013 Technical Council meeting in Oxford, it was agreed that KH, LB, and JC will review the minutes of the discussion of ways that tagUsage might be used and make a recommendation to Council before the next face-to-face.

  • Kevin Hawkins

    Kevin Hawkins - 2013-12-27

    KH just emailed LB and JC to start the discussion.

    • Kevin Hawkins

      Kevin Hawkins - 2014-01-05

      My email is below, for easy reference:


      In Oxford, we were assigned the task of making a recommendation to Council regarding use of tagUsage versus project-specific ODDs (see https://sourceforge.net/p/tei/feature-requests/457/ ) before the next face-to-face meeting. It seems to me there are a few separate questions:

      1. Whether tagUsage should be used to describe only uses of elements, not uses of element-attribute combinations (as was said on TEI-L).

      2. Whether you have to include a tagUsage for every element in your document (as Syd understands from section 2.3.4) or whether you can use it for only those elements that you care to discuss (as Sebastian seemed to think was the case).

      3. Whether to redefine tagUsage so that it is used only for formal description, without any prose description.

      4. Whether to make more explicit that tagUsage is supposed to be used for usages specific to a particular document, not practice across a set of documents (which would go only in the ODD).

      I suggest that we think not about how to interpret the Guidelines as currently written but about what we think would be a good way going forward and then consider whether we can get there without breaking backwards compatibility.

      I have no particular opinions on any of these questions, so I'm open to your suggestions.


  • Lou Burnard

    Lou Burnard - 2014-01-05

    The English Polish freedict example above doesn't seem to me to establish a particularly good precedent. If you were doing this project again, surely you'd use DCR ("data category registry", Kevin) pointers instead?


    <tagUsage gi="pos">
    <list n="values" type="bulleted">
    <item xml:id="tag_N" ana="FreeDict_ontology.xml#f_pos_noun">N</item>
    <item ana="FreeDict_ontology.xml#f_pos_noun">N Comp</item>
    <item xml:id="tag_V" ana="FreeDict_ontology.xml#f_pos_verb">V</item>
    <item ana="FreeDict_ontology.xml#f_pos_verb">V Mod</item>
    <item ana="FreeDict_ontology.xml#f_pos_verb">V Phras</item>


    Why do some entries have xml:id values but not others?

    Why is the list of type "bulleted" rather than (say) "valueList" ?

    The Guidelines suggest instead storing your POS values as <category> elements within a <taxonomy>. (maybe we should add <category> to att.datcat)

    In any case, I can see the logic of defining these things here. So now we have three possibilities: document them with a <valList> inside your ODD; document them with a <taxonomy> in your corpus header; document them inside <tagUsage> inside your header. Oh, and then there's the possibility of that new other special element for <standoff> too...

    Last edit: Kevin Hawkins 2014-01-05
  • Kevin Hawkins

    Kevin Hawkins - 2014-05-10

    So while Piotr may think that <tagUsage> is a good place for DCR references, right now the Guidelines don't suggest this. In fact, according to Lou the Guidelines say to store values for the <pos> element in a <category> in <taxonomy>.

    In that case, I'd prefer to keep this discussion about <tagUsage>—and any examples we provide in the Guidelines—restricted to those elements for which the Guidelines do not provide another mechanism for recording information about usage, such as <category> elements in <taxonomy>.

    If everyone agrees, then I think we're back to my four questions at https://sourceforge.net/p/tei/feature-requests/457/#a526/d4d0 .

  • James Cummings

    James Cummings - 2014-05-19

    Assigning to Lou Burnard to triage ticket and make recommendation to council.

  • James Cummings

    James Cummings - 2014-05-19
    • assigned_to: Lou Burnard
  • Lou Burnard

    Lou Burnard - 2014-06-06

    Council needs to discuss Kevin's four questions and see if there is any consensus on their answers.

  • Syd Bauman

    Syd Bauman - 2014-11-23

    2014-11-18 Council discussed the issues, focusing on Kevin's four questions of 2014-01-05. We agreed that:
    1) <tagUsge> is used for elements, not attributes (although you can discuss an attribute in the prose inside <tagUsage>)
    2) See feature request on tagUsage usage
    3) No, we are not going to change <tagUsage> to formal only
    4) Yes, the Guidelines need to be more explicit about when you would record information about an element's usage in the ODD vs in the <tagUsage>



    Feature Requests: #516