Examples in P5 are unnumbered

[pdurusau]

The examples in P5 are unnumbered. I mention this because I have a comment to make on some but not all of the examples in 16.1.2 Using Pointers and Links, but the only sure reference is to quote each relevant example separately.

Numbering the examples would enable section/sub-section / Example # references. Useful both for teaching as well as reporting errors.

[hcayless]

This is a good point. If you're willing to do a little extra legwork, each example should have an ID, meaning you can construct a URL pointing directly to the right example, e.g. https://www.tei-c.org/release/doc/tei-p5-doc/en/html/SA.html#index-egXML-d53e121026

One simple solution might be for us to generate a link for each that can be copied.

[pdurusau]

Thanks for pointing out the example IDs. Not easy to find in HTML source view.

Not controlling for TEI but the ISO Guidelines, 7th edition, 25 Examples, requires multiple examples in a section/subsection to be numbered, but a single example isn't numbered. Makes reference in a paper or lecture as Section N, Example N easy, as opposed to: https://www.tei-c.org/release/doc/tei-p5-doc/en/html/SA.html#index-egXML-d53e121026.

[tuurma]

Just a note that since GL are constantly updated, we cannot guarantee that a reference scheme like Section/Example number is going to be stable.

[pdurusau]

I suspect stability is a function of the starting point for example numbering.

If Examples are numbered from the start of the GL, sure, likely to change.

If Examples are numbered within sections or say second level divisions, suspect less likely to change.

That is: Section 16, Example 3 is likely to be stable enough for citation in discussions, even papers.

I don't have a sense for what level of the GL are changing or how often but I suspect someone with better Git skills than mine could determine that from the revision history.

[tuurma]

It's not often but it does happen that chapters are substantially extended or rewritten. This is why for pointing rather than using section number, e.g. 16.1.2 for Using Pointers and Links we use its id, namely 'SAPTEG', thus full link reads https://www.tei-c.org/release/doc/tei-p5-doc/en/html/SA.html#SAPTEG. It does look long but basically we also use chapter (SA, for Segmentation and Alignment) and section id (SAPTEG).

In short, while numbering of examples can be added without much problem, it's likely not good enough as a reference scheme.

[jamescummings]

In my occasional thinking about examples the problem that @pdurusau raises has occurred to me a number of times and I had the same worry as @tuurma that anything which numbers them, even based on their position in the section is not going to be stable over multiple releases. It may be that this is fine, "TEI P5 Version 3.5.0 Section 16.1.2, Example 4" is then a perfectly fine canonical example. It just doesn't preserve itself in version 3.6.0 or some later version that adds and extra example. (Let's assume we're adding more, not taking them away...)

@hcayless is right that the best way to refer to them is by their xml:id, but @pdurusau rightly points out this is difficult.

Proposal:
At the start of each section in the HTML view of the TEI Guidelines we have a small greyed out pilcrow which becomes blue when hovered on it and provides a link to this section. As one of the people who argued for this (and this character in specific... https://lists.tei-c.org/pipermail/tei-council/2007/008589.html) I think it is invaluable. People now use them on TEI-L and issues here to point to the section they are referring to. Success. What is my proposal then? Do the same thing for all figures and examples. For examples a discreet little pilcrow in the upper-left or bottom right of the box, for figures, just float them left near it. Greyed-out in the same manner as the section links (which we miss-called 'permalinks' when introducing them...ignore that.) That way people have the URL that Hugh suggests should be used at hand in an easy manner. ;-)

[pdurusau]

James, That would make the URL easy to access but would it be stable across versions? That is will all examples and figures be assigned permanent xml:ids that persist across versions? That's my assumption if your proposal is accepted but thought it best to voice the concern ahead of time. Thanks! Patrick

On 10/12/19 4:43 PM, James Cummings wrote: In my occasional thinking about examples the problem that @pdurusau <https://github.com/pdurusau> raises has occurred to me a number of times and I had the same worry as @tuurma <https://github.com/tuurma> that anything which numbers them, even based on their position in the section is not going to be stable over multiple releases. It may be that this is fine, "TEI P5 Version 3.5.0 Section 16.1.2, Example 4" is then a perfectly fine canonical example. It just doesn't preserve itself in version 3.6.0 or some later version that adds and extra example. (Let's assume we're adding more, not taking them away...) @hcayless <https://github.com/hcayless> is right that the best way to refer to them is by their xml:id, but @pdurusau <https://github.com/pdurusau> rightly points out this is difficult. Proposal: At the start of each section in the HTML view of the TEI Guidelines we have a small greyed out pilcrow which becomes blue when hovered on it and provides a link to this section. As one of the people who argued for this (and this character in specific... https://lists.tei-c.org/pipermail/tei-council/2007/008589.html) I think it is invaluable. People now use them on TEI-L and issues here to point to the section they are referring to. Success. What is my proposal then? Do the same thing for all figures and examples. For examples a discreet little pilcrow in the upper-left or bottom right of the box, for figures, just float them left near it. Greyed-out in the same manner as the section links (which we miss-called 'permalinks' when introducing them...ignore that.) That way people have the URL that Hugh suggests should be used at hand in an easy manner. ;-) — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#1931?email_source=notifications&email_token=AACOWYBE73XJ5BKAWYM6YNLQOIZITA5CNFSM4I4N2VM2YY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGOEBCH67A#issuecomment-541359996>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AACOWYGVVJUATHGP5NNGF4LQOIZITANCNFSM4I4N2VMQ>.

-- Patrick Durusau patrick@durusau.net Technical Advisory Board, OASIS (TAB) Editor, OpenDocument Format TC (OASIS), Project Editor ISO/IEC 26300 Co-Editor, ISO/IEC 13250-1, 13250-5 (Topic Maps) Another Word For It (blog): http://tm.durusau.net Homepage: http://www.durusau.net Twitter: patrickDurusau

[martindholmes]

I can imagine all sorts of problems which follow from the idea that example identifiers should be consistent across versions. Imagine these scenarios:

• Between one release of the Guidelines and the next, the list of suggested values for an attribute changes very slightly; an example which uses the altered value is updated to reflect the new value. Should its identifier change?

• Between one release and the next, the definition of an element changes, and the explanation surrounding an example is rewritten, but it turns out that the example itself does not need to be changed. Should it retain the same identifier as before, even though it's now exemplifying something slightly different?

• Between one release and the next, an example used in Chapter X is moved to Chapter Y, since the explanatory text it supports has been moved as part of a module reorganization, but the example itself remains unchanged. Should it retain the same identifier?

For reasons like this, I don't think the idea of stable identifiers for examples across versions makes sense. Instead, I would simply go for a system where each example is identified by something constructed from the Guidelines version, the chapter id, and the number of the example in the chapter sequence.

[pdurusau]

Martin, That makes my original suggestion, just numbering figures and examples, which enables "TEI Guidelines P5, version 3.6.0, Section #, Example #" sound quite doable. So the number of the example may change with different versions. The burden is on me as a person citing the example to use the full citation form. Minimal burden on the generation of the Guidelines. Permanent reference for my readers. What's there not to like? Yes? Thanks! Patrick

On 10/13/19 11:55 AM, Martin Holmes wrote: I can imagine all sorts of problems which follow from the idea that example identifiers should be consistent across versions. Imagine these scenarios: * Between one release of the Guidelines and the next, the list of suggested values for an attribute changes very slightly; an example which uses the altered value is updated to reflect the new value. Should its identifier change? * Between one release and the next, the definition of an element changes, and the explanation surrounding an example is rewritten, but it turns out that the example itself does not need to be changed. Should it retain the same identifier as before, even though it's now exemplifying something slightly different? * Between one release and the next, an example used in Chapter X is moved to Chapter Y, since the explanatory text it supports has been moved as part of a module reorganization, but the example itself remains unchanged. Should it retain the same identifier? For reasons like this, I don't think the idea of stable identifiers for examples across versions makes sense. Instead, I would simply go for a system where each example is identified by something constructed from the Guidelines version, the chapter id, and the number of the example in the chapter sequence. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#1931?email_source=notifications&email_token=AACOWYDOTQKSL77GGBNVK6TQONAH7A5CNFSM4I4N2VM2YY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGOEBCZHRY#issuecomment-541430727>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AACOWYET4CMCNYJQR4WGDZDQONAH7ANCNFSM4I4N2VMQ>.

-- Patrick Durusau patrick@durusau.net Technical Advisory Board, OASIS (TAB) Editor, OpenDocument Format TC (OASIS), Project Editor ISO/IEC 26300 Co-Editor, ISO/IEC 13250-1, 13250-5 (Topic Maps) Another Word For It (blog): http://tm.durusau.net Homepage: http://www.durusau.net Twitter: patrickDurusau

[jamescummings]

Hrmmm. In almost all those cases @martindholmes suggests I think the xml:id of the example stays the same. If it moves to a different module the URL would be different anyway. The identifier is an identifier for the example .... it could change if so different the person editing it thinks it is a new example but I think that is just a matter of policy. The URL would be best to be pointing to the version that is in the Vault in any case, so it is always release specific. (I think we should do that with the existing section pilcrows also.)

[jamescummings]

(Oh and this doesn't stop us also doing @pdurusau's approach to referencing as well)

[pdurusau]

I corrected examples in 16.1.2 Using Pointers and Links this morning and encountered an internal use for numbered examples. The first example in 16.1.2 omits the anchoring text of the encoded note altogether. That is the text reads: Verse 283-84 -- With equal grace ... But, the encoding omits Verse 283-84 in its entirety. The same is true for the second example. But, examples 4, 5, and 6, all capture the anchor without comment, but at least it is present. A careful reader will notice this silent omission, which is unexplained in the text. It is certainly an opportunity to note that not every encoding captures every feature present in the original. But that would be aided in this case by calling out the examples by number and their treatment of the feature in question. Hope everyone is having a great day! Patrick

On 10/13/19 1:09 PM, James Cummings wrote: (Oh and this doesn't stop us also doing @pdurusau <https://github.com/pdurusau>'s approach to referencing as well) — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#1931?email_source=notifications&email_token=AACOWYB6C4JNJ3HTKOPLIZTQONI2ZA5CNFSM4I4N2VM2YY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGOEBC2V3Q#issuecomment-541436654>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AACOWYFXJIPKSODFQVRL2BLQONI2ZANCNFSM4I4N2VMQ>.

-- Patrick Durusau patrick@durusau.net Technical Advisory Board, OASIS (TAB) Editor, OpenDocument Format TC (OASIS), Project Editor ISO/IEC 26300 Co-Editor, ISO/IEC 13250-1, 13250-5 (Topic Maps) Another Word For It (blog): http://tm.durusau.net Homepage: http://www.durusau.net Twitter: patrickDurusau

[tuurma]

VF2F Council meeting agrees that it's helpful to have a copiable, direct link to the example that users can easily copy with an informative title. While such links to allow for meaningful citation must point to a specific Guidelines version, twinning them with an alert if a user is viewing an older version of the Guidelines would be helpful.

[martinascholger]

VF2F Council meeting agrees that this is a good idea. We will close the issue here and open a Stylesheets issue to 1) create a permalink and b) alert the user when looking at old versions.