#581 `<attRef>` needs better documentation


As pointed out during the thread starting here on TEI-L:


the <attRef> element is never mentioned in chapter 22. There are also only two examples for it, which are identical. The use-case discussed in the thread might provide possible examples.


  • Louis-Dominique Dubeau

    The example given in the P5 documentation is as follows:

    <attRef name="att.global.attribute.xml:id"/>

    but I was not able to get it to work. However, this worked:

    <attRef name="att.global.attribute.xmlid"/>
  • Martin Holmes

    Martin Holmes - 2013-11-13

    Louis-Dominique's issue has been corrected -- you have to drop the colons, and the examples now shows correctly, but that fact also has to be documented.

  • Martin Holmes

    Martin Holmes - 2013-11-13
    • status: open --> open-accepted
    • assigned_to: Martin Holmes
    • Group: AMBER --> GREEN
  • Martin Holmes

    Martin Holmes - 2013-11-13

    This is potentially a solution to the unease with which we contemplate the idea of claiming membership of a class, then deleting some of its attributes; with this, you can have an element that does not claim membership of the class, and instead pulls in only the attributes it wants from that class.

  • Martin Holmes

    Martin Holmes - 2013-11-13
    • Group: GREEN --> AMBER
  • Syd Bauman

    Syd Bauman - 2013-11-13

    We really need to revamp the syntax, here, though. Instead of name= having a RELAX NG pattern, we really should refer to the class and particular attribute. E.g. <attRef class="att.global" name="xml:id"/>.

    Last edit: Martin Holmes 2013-11-13
  • Martin Holmes

    Martin Holmes - 2013-11-13

    Action on MH to watch as SR and SB implement this, and then document it properly when it's done.

  • Martin Holmes

    Martin Holmes - 2013-11-13

    LB suggests we can use classRef instead, using include or exclude of attributes. Therefore we might be able to get rid of this element.

  • Martin Holmes

    Martin Holmes - 2014-06-06

    Posted to the Council list asking for any answers to these questions:

    1. Are there (currently) any good use-cases for end-users which depend
      on the use of <attRef> and which will work with current ODD processing?

    2. If there are such use-cases, can the same results be achieved using
      other existing elements and attributes?

    3. Will future plans for ODD make <attRef> obsolete anyway?

  • Martin Holmes

    Martin Holmes - 2014-06-29

    No responses to the questions as of today. I guess this will need to be discussed in the FtF.

  • Lou Burnard

    Lou Burnard - 2014-06-30

    Feature request to extract attribute from locally defined element, either because it's special or because it over rides class definition, would be useful. Maybe add @element as an alternative to @class

  • Martin Holmes

    Martin Holmes - 2014-09-09
    • status: open-accepted --> open
  • James Cummings

    James Cummings - 2014-11-19

    F2F Raleigh: Prods MH to progress ticket.

  • Martin Holmes

    Martin Holmes - 2015-05-25

    A summary of what I know for the Council FtF in Ann Arbor:

    The P5 Source makes absolutely no use of <attRef>; the explanation of it in the USE chapter suggests that ODD pre-processing does make use of it, and in fact if I capture the odd.processedodd file created during ODD processing, preventing it from being deleted at the end, I do find instances of it; and it's mentioned a lot in the ODD processing modules of the Stylesheets.

    When I make use of it in an ODD file to (for example) add @source from att.sourced to the <p> element, it works perfectly (which is what you'd expect; ODD processing wouldn't work otherwise).

    So it seems to me that we have these options:

    1. Leave well alone because nothing is broken.
    2. Improve the documentation to explain that this element is mainly used in intermediate steps when processing ODD files to produce schemas.
    3. Add more detailed documentation with some examples of how you might use this in a user-created ODD file.
    4. Extend it to add Lou's requested @element attribute, which would enable one element to pull a copy of an attribute defined locally on another element. There would probably have to be some namespace-related functionality to go along with this, and it would require more work in the Stylesheets code.

    Personally, I favour #1 or #2. I haven't seen any convincing use-cases for #3 or #4 which cannot be accomplished in other ways. The use-case for #3 might be (for instance) adding @xml:id to a new element you're creating, but that could be achieved by adding it to add.global and then deleting the other global attributes you don't want (admittedly long-winded but familiar); in the case of #4, I think that once you're sharing an attribute between two elements you might as well create a class they can both belong to which defines the attribute, rather than define it on one and refer to it from the other.

    Last edit: Martin Holmes 2015-05-25
  • Martin Holmes

    Martin Holmes - 2015-05-30

    MH to go forward with option 2+3 (explain that we use it internally, but it could be used in an ODD directly), with examples. An example that makes some sense: you add a new element in your own namespace, and you want to pull @xml:id from att.global, but don't want the others. You could add it to att.global, then delete all the other consequences, but it might be simpler to use attRef.

  • Martin Holmes

    Martin Holmes - 2015-05-30
    • Group: AMBER --> GREEN