[rfc-i] draft-iab-xml2rfc-03, "B.2.1 Overlapping Values"

[julian.reschke at gmx.de (Julian Reschke)]

On 2016-03-14 22:46, Julian Reschke wrote:
> <http://greenbytes.de/tech/webdav/draft-iab-xml2rfc-03.html#rfc.section.B.2.1>:
>
>
>> The following rules prevent this overlap:
>>
>> - "pn" for regular sections always has the format "s-nnn", where "nnn"
>> is the section or appendix number. For example, this would be
>> "s-2.1.3" for Section 2.1.3 and "s-a" for Appendix A. For the
>> <abstract> element, it is always "s-abstract". For the <note> element,
>> it is always "s-note-nnn", where "nnn" is a sequential value. For the
>> <boilerplate> element, it is always "s-boilerplate-nnn", where "nnn"
>> is a sequential value.
>
> a) What is "pn" for a section that is unnumbered? I assume numbers are
> still assigned, just not displayed?
>
> b) Don't we need "pn" on <references> (as they get numbered as regular
> sections)?

In the meantime I realized it's mentioned later.

> c) Why is "pn" for <boilerplate> numbered when it can only occur once?

I spent some more time with implementation, and here's my consolidated 
feedback:

1) The spec says that <references> are handled like things that appear 
inside <section>s; I believe that's counter-intuitive as <references> 
are treated like <section>s otherwise (in that they're getting section 
numbers).

2) It would be good to clarify that a <section> with numbered=false 
(<http://greenbytes.de/tech/webdav/draft-iab-xml2rfc-03.html#element.section.attribute.numbered>) 
still gets a regular pn=s-..., even though the section number won't be 
visible.

3) Why is "pn" for <boilerplate> numbered when it can only occur once?

4) The preptool spec and the vocabulary spec are inconsistent with 
respect to which elements get numbered (the vocabulary spec defines the 
"pn" attribute on many elements not mentioned in the preptool spec).

5) It's not clear at all to me why we need to have pn attributes on all 
the elements it's mentioned for; their use case seems to provide stable 
targets for pilcrow links, but not all of them can get a pilcrow. For 
instance, why have it on <dd> and <dt>?

Aside from these technical issues, I'm also unhappy with the usability 
of this.

Numbering all child elements of a section without considering nesting is 
technically simple, but will generate part numbers that are very 
unintuitive. For instance, in an imaginary Section 1.1 that has exactly 
five paragraphs with no other markup, we'll get the part numbers

   p-1.1-1 through p-1.1-5

Good. However, inserting a single <xref> into the first <t> will change 
the part numbers for paragraph 2...5 to p-1.1-3...p-1.1-6. Not good, 
IMHO, because:

1) p-1.1-2 is now assigned to something that doesn't need a part number 
at all,

2) part numbers have lost their obvious relation to paragraph numbers,

3) anchors in documents under development will be broken more often that 
needed (think Internet-Drafts).

This could be fixed as follows:

a) Do not count elements that do not have the semantics of creating a 
standalone block of text (as opposed to a part of a block), and

b) Count elements on the same level of nesting separately, and structure 
the pn accordingly.

With that, a list appearing after the first parapgraph of a section 
would get the part number "p-n-2", and the individual list entries would 
be "p-n-2.1" etc.

Finally, I continue to find it odd that we use both the "s-" prefix and 
the "p-" prefix. The latter isn't needed, and the part numbers that we 
generate lose the nice property of having a somewhat logical sort order.

Best regards, Julian