Hierarchical numbered lists, references to list items

[toerless]

a) In https://www.ietf.org/archive/id/draft-ietf-bier-te-arch-13.html, section 2.3 has a two-tier numbered list. It would be a lot better if there was a rendering that would show the full hierarchical numbering, e.g. in that example points 1.1 ... 4.2. Instead of only indenting the second numbering level. Without showing as structured numbers, even textual references to these numbered points are not "nice".

b) (hotlink) references through xml tagging to such numbered items in a list is kinda impossible. See section 3.2.1.1 and how it tries to achieve this quite ugly.

Note: that draft is right now in AUTH48. Not quite sure what the best is RFC editor will whip up in the final RFC, but from my last AUTH48 discussion, it wasn't ideal IMHO, aka: the above two type of enhancements would hopefully be very helpful to better write structured text with easily referenced / hierarchical points.

[jrlevine]

This is not a draft about rendering bugs.

[toerless]

Its not clear to me whether the solution to the issues i list is just in rendering or in vocabulary. I for once would think that a hierarchically numbered list could a vocabulary option as well as explicit section targets in the vocabulary that could then be used in references (other languages like latex have that for example).

[reschke]

The list format you're asking for already exists. See example in https://github.com/ietf-tools/xml2rfc/blob/45dd38935217e94ca4699ab035e7afa3f03d0823/tests/input/elements.xml#L339

[ajeanmahoney]

Regarding a), nested ordered lists are documented on the authors.ietf.org site. Please see the description of the type attribute (type='%p%d') on the Attributes tab of https://authors.ietf.org/en/rfcxml-vocabulary#ol

For b), https://www.ietf.org/archive/id/draft-ietf-bier-te-arch-13.html has the description "Section 3.2, Paragraph 3, Item 2.2.1" for the item being cross-referenced, but 'Item 2.2.1' isn't correct. It should say "Section 3.2, Paragraph ..." Actually, I'm not sure what it should say because the xref is pointing to the first item of an ordered list that is nested within a definition list. Perhaps "Section 3.2, Definition 1, Item 1".

[toerless]

[let me add RSWG for broader community review] Thanks a lot, Jean, inline

On Tue, Sep 27, 2022 at 08:32:25AM -0700, Jean Mahoney wrote: Regarding a), nested ordered lists are documented on the authors.ietf.org site. Please see the description of the type attribute (type='%p%d') on the Attributes tab of https://authors.ietf.org/en/rfcxml-vocabulary#ol

Hah! yes, i had not found the % notation for the type attribute, and maybe i didn't well enough communicate the desire with RFC editor: <ol spacing="normal" type="%p%c"> ... 1. BIER-TE inherits ... 1.a The fundamental purpose o ... ^^^ The 1.a is what i wanted. The only thing that i could see being improved here is that it should not need to be indented, e.g.: 1. BIER-TE inherits ... 1.a The fundamental purpose o ... But i don't see how that would be possible today. [ Just because lines become ugly short with so much indentation. And indentation is originally to differentiate the two tiers of the list, which is not necessarily anymore with the "1.a" formatting... ]

For b), https://www.ietf.org/archive/id/draft-ietf-bier-te-arch-13.html has the description "Section 3.2, Paragraph 3, Item 2.2.1" for the item being cross-referenced, but 'Item 2.2.1' isn't correct. It should say "Section 3.2, Paragraph ..." Actually, I'm not sure what it should say because the xref is pointing to the first item of an ordered list that is nested within a definition list. Perhaps "Section 3.2, Definition 1, Item 1".

Let me rephrase the root problem: There is no equivalent to the type="%..." notion for the <xref > element. Instead, there is what i would call a lot of built-in magic to create the non-configurable derivedContent attribute. In result, it is impossible to create an IMHO good reference text such as "See Section 3.2 Bullet 1.2 on page 20" And of course, whether or not that rather long reference text is appropriate or not IMHO highly depends on what you are rendering for: If you are rendering with hotlinks it is likely not ideal (but still fine), but if you are rendering for paper printout, then IMHO you really want to have this much information to quickly locate the referenced location in a stack of printed paper. And i quite rankly always like rendering that work for any output (aka: above example reference text that also is a hotlink). So, maybe if we are talking about language extensions, then maybe this could be considered to be rendering hints or the like. Cheers toerless

…

-- Reply to this email directly or view it on GitHub: #1 (comment) You are receiving this because you authored the thread. Message ID: ***@***.***>

-- --- ***@***.***

[toerless]

--On Tuesday, September 27, 2022 20:45 +0200 Toerless Eckert ***@***.***> wrote:

... Let me rephrase the root problem: There is no equivalent to the type="%..." notion for the <xref > element. Instead, there is what i would call a lot of built-in magic to create the non-configurable derivedContent attribute. In result, it is impossible to create an IMHO good reference text such as "See Section 3.2 Bullet 1.2 on page 20"

Toerless, Jean, and others, %include SoundOfCanOfWormsOpening; And I think this is a separate issue that deserves an entry on John's list. Questions/issues similar to that have been noted on and off for many years. Sandy might recall my raising a related one shortly after she came on board, and it was not new then. So, two observations: (1) As I am sure the RPC knows, different book publisher style guides take different positions on whether a citation like that should be expressed (translating as best I can into our format) as: See [RFC9999 Section 3.2 Bullet 1.2 on page 20] or the equivalent See [Section 3.2 Bullet 1.2 on page 20 of RFC9999] or syntactic tweaks to that, with the actual reference containing only information about RFC nnnn (or some other publication citation, e.g., Eckert2002). Or whether the correct form is closer to See [Carroll1871a] where the actual reference would read more like [[Carroll1871] Carroll, L., _Through the Looking-Glass_, Chapter 6 "Humpty Dumpty", ... and might be followed in the references by [[Carroll1871b] Carroll, L., _Through the Looking-Glass_, Chapter 4 "Tweedledum and Tweedledee", ... (2) One thing that every style guide from a serious publisher I have looked at (except those who consider the answer so obvious as to be beneath notice) agrees on, however, is that, despite its frequent use in RFCs, the form "As discussed in [RFC9999]" is unacceptable, if only because a citation anchor cannot be the object of a sentence and because it would be even more confusing if the anchor is expressed as, e.g., [3] in plain text and in pretty-printing as a superscript "3". Variations on both of the above preference appear in the RFC Series, partially because some of us have insisted that "As discussed in RFC 9999 [RFC9999]" is the correct rendering of the above and have sometimes found the first form, when the citation qualifies something in the references, a little tedious and obnoxious. And, at least so far, the RPC (and its predecessors) have yielded to author discretion on the matter as long as there is consistent usage within a document. But there is more...

And of course, whether or not that rather long reference text is appropriate or not IMHO highly depends on what you are rendering for: If you are rendering with hotlinks it is likely not ideal (but still fine), but if you are rendering for paper printout, then IMHO you really want to have this much information to quickly locate the referenced location in a stack of printed paper. And i quite rankly always like rendering that work for any output (aka: above example reference text that also is a hotlink). So, maybe if we are talking about language extensions, then maybe this could be considered to be rendering hints or the like.

See above, but... This is not something the reader should be figuring out, probably even by a choice of style sheets. It is even less something the author should be specifying. No matter what is rendered, the authoritative XML should be consistent across the choices. So what is really wanted for an external reference is markup like <xref target="RFC9999" location="Section 3.2 Bullet 1.2 on page 20"> with any of the above forms --including rendering the anchor for RFC 9999 as [5] -- a style and output decision, not an author one. For an internal one, the value for the location attribute might be an anchor or equivalent somewhere. The difference between now and 20-odd years ago is that we could probably not have gotten our heads around an element and attribute set like that back then. Today, we are arguably doing things that are more complex already. Or, perhaps, "RFC references, what are they but a dream?" best, john