Subject: Re: [rfc-i] [Rsoc] RFCs with page numbers (pretty please) ?

From: "John R. Levine" <[email-masked]>
Date: 1 Nov 2020 09:59:50 -0500

>> What formats do you believe don't have section numbers?  They're in all
>> three rendered formats and in the XML as tags like "section-3.1".
>
> They aren't in raw XML and they aren't in kramdown, so they aren't where
> an author needs them when processing comments on an I-D. (So, strictly,
> that isn't an RFC format issue, but it is an issue created by our format
> choices and it's quite an annoyance.)

Sounds like yet another thing that could be improved with better tooling. 
Adding and updating comments with section numbers isn't exactly rocket 
science.

Regards,
John Levine, [email-masked], Primary Perpetrator of "The Internet for Dummies",
Please consider the environment before reading this e-mail. https://jl.ly
_______________________________________________
rfc-interest mailing list
[email-masked]
https://www.rfc-editor.org/mailman/listinfo/rfc-interest

---

From: tom petch <[email-masked]>
Date: Mon, 2 Nov 2020 10:12:14 +0000

On 01/11/2020 14:59, John R. Levine wrote:
> Sounds like yet another thing that could be improved with better
> tooling. Adding and updating comments with section numbers isn't exactly
> rocket science.

YANG modules do not have section numbers and can be 50 (five zero) pages 
long and the same identifier (e.g. 'status') can appear multiple times 
in different branches of the schema tree and the tree can be over 10 
levels deep so providing the absolute form of the identifier of the leaf 
that you are commenting on can take more than one line.  Reference by 
page number is so simple (even ADs use it:-).

Tom Petch

> .

---

From: Julian Reschke <[email-masked]>
Date: Mon, 2 Nov 2020 11:34:14 +0100

> page number is so simple (even ADs use it:-).

And is it absolutely mandatory that the YANG module appears in a single
chunk?

Best regards, Julian

---

From: tom petch <[email-masked]>
Date: Mon, 2 Nov 2020 12:17:46 +0000

> And is it absolutely mandatory that the YANG module appears in a single

It is like writing anything in code, modular is better than spaghetti, 
but there is a limit to how far that can go without creating a spiders 
web of interconnections between modules.  The i2nsf I-D I just looked at 
is 55 pages split into three modules and I would not subdivide it any 
further.  YANG modules must be self-contained and comprehensible, 
independent of the RFC they come from so in a well written one, a large 
part with be text description; and the whole idea of YANG was that it be 
text-based, unlike the binary encoding of SNMP, so you have text 
identifiers, type, references to RFC, IANA etc.  It all mounts up.  Five 
pages would be very small.

Tom Petch

Tom Petch

---

From: "Joel M. Halpern" <[email-masked]>
Date: Mon, 2 Nov 2020 07:19:28 -0500

And this Tom is exactly why many of us flinch at the generally 
reasonable request that people be able to get page numbers of printed 
documents and the on line form from which it was printed.

If you refer to page numbers in a comment, then folks looking in some 
other form factor will have no way of using that reference.  For YANG 
modules, my experience is that one is much better to use other reference 
indicators (e.g the grouping name, ...).

Yours,
Joel

---

From: Julian Reschke <[email-masked]>
Date: Mon, 2 Nov 2020 13:37:36 +0100

Am 02.11.2020 um 13:17 schrieb tom petch:
> ...
> ...

I'll assume the example is
<https://www.ietf.org/archive/id/draft-ietf-i2nsf-nsf-facing-interface-dm-10.txt>?

What you could do now: split the module into top-level artefacts and
place them into separate <sourcecode> elements. These can have anchors
the split tool could generate. Thus each of the pieces would have an
anchor you can link to.

What might be desirable as xml2rfc feature: the ability to add line
numbers to <sourcecode>.

I do understand that both would interfere with extraction code that has
been written for plain text, but that should not be needed/used anymore
in the v3 xml world anyway.

Best regards, Julian

---

From: Robert Sparks <[email-masked]>
Date: Mon, 2 Nov 2020 10:17:17 -0600

It's worth noting that this has been a fundamental point of disagreement 
between people involved in the v3 effort (and is often so in any world 
where you are adding big new things).

For the v3 transition, I'm still more on the fence that it's too soon to 
break people's toolchains just because we can. At some point, when 
there's not such a mix of historic text files that have to be processed 
along with the new things (which may or may not be in v3 format while 
they are internet drafts), then sure - we can say "Get with the times". 
But I don't think those times are here yet.

RjS

---

From: "John R. Levine" <[email-masked]>
Date: 2 Nov 2020 11:50:01 -0500

> YANG modules do not have section numbers and can be 50 (five zero) pages long 
> and the same identifier (e.g. 'status') can appear multiple times in 
> different branches of the schema tree and the tree can be over 10 levels deep 
> so providing the absolute form of the identifier of the leaf that you are 
> commenting on can take more than one line.  Reference by page number is so 
> simple (even ADs use it:-).

Too bad the page numbers are different in every rendering.

I don't deny this is an issue but "use page numbers" is not much of an 
answer.

Regards,

---

From: Carsten Bormann <[email-masked]>
Date: Mon, 2 Nov 2020 17:56:47 +0100

On 2020-11-02, at 17:50, John R. Levine <[email-masked]> wrote:
> 
>> YANG modules do not have section numbers and can be 50 (five zero) pages long and the same identifier (e.g. 'status') can appear multiple times in different branches of the schema tree and the tree can be over 10 levels deep so providing the absolute form of the identifier of the leaf that you are commenting on can take more than one line.  Reference by page number is so simple (even ADs use it:-).
> 
> I don't deny this is an issue but "use page numbers" is not much of an answer.

Obviously, YANG needs a fragment identifier syntax (like RFC 6901 JSON pointers).

Grüße, Carsten

---

From: Julian Reschke <[email-masked]>
Date: Mon, 2 Nov 2020 18:49:52 +0100

> where you are adding big new things).

Which point exactly?

Best regards, Julian

---

From: Robert Sparks <[email-masked]>
Date: Mon, 2 Nov 2020 12:02:20 -0600

zooming in to the particular specific you are asking for:

> that should not be needed/used anymore
and again returning context:

> For the v3 transition, I'm still more on the fence that it's too soon 
> to break people's toolchains just because we can. At some point, when 
> there's not such a mix of historic text files that have to be 
> processed along with the new things (which may or may not be in v3 
> format while they are internet drafts), then sure - we can say "Get 
> with the times". But I don't think those times are here yet. 
I'm puzzled that you didn't find the exact point of disagreement in 
that, but I'll try to restate it:

Some people have repeatedly held the position it's ok to disrupt 
existing toolchains because what we're creating is so much better and 
breakage will make people use the new thing. Others think that a longer 
period of transition allowing older toolchains to continue working is 
important.

---

From: Julian Reschke <[email-masked]>
Date: Mon, 2 Nov 2020 19:29:26 +0100

> Re-adding the context you dropped:

I didn't realize that this was actually the point you were making.

> ... >> For the v3 transition, I'm still more on the fence that it's too soon

My recollection is that we preserved support for plain text exactly
*because* we did not want to disrupt existing tool chains. And we did
not, right?

What was news to me is that there are documents which have
artwork/sourcecode that spans 50 pages, and thus people would like to
use page numbers. I don't recall that use case being mentioned in
context of the format transition.

IMHO, publishing large blobs of source code as-is is weird. We publish
specs for *readers*, not for automatic processing. Is this specific to
the YANG community, or does it apply to other areas as well?

Best regards, Julian

---

From: Robert Sparks <[email-masked]>
Date: Mon, 2 Nov 2020 12:42:53 -0600

> the YANG community, or does it apply to other areas as well?

ABNF can get pretty large (certainly more than one traditional page).

So can the ASN.1 module representations used in security drafts.

I don't think 50 pages is common for those cases, but more than one 
probably is.

---

From: Carsten Bormann <[email-masked]>
Date: Mon, 2 Nov 2020 20:19:04 +0100

> ABNF can get pretty large (certainly more than one traditional page).

As can CDDL.

Generally, introducing parts of a CDDL spec in a piecemeal fashion, like it is done in RFC 8152, can work well, if there is a defined way to get the spec out from the XML.  There is for RFC 8152:

   //artwork[@type='CDDL']/text()

(which would need to be adapted to RFCXMLv3 now).

CDDL and ABNF have in common that you can point to places in the spec by rule name, as these are unique (they are not ordered, but that’s what search functions are for).

> So can the ASN.1 module representations used in security drafts.

I’m out :-)

> I don't think 50 pages is common for those cases, but more than one probably is.

Grüße, Carsten

---

From: Carsten Bormann <[email-masked]>
Date: Mon, 2 Nov 2020 20:23:13 +0100

> the YANG community, or does it apply to other areas as well?

Much weirder, but not benefitting from page numbers:
RFC 6716 appendix A.3

(As was already mentioned in a different branch, YANG now also has RFC 8792, which missed an opportunity to put in bookmarks.)

Grüße, Carsten

---

From: Robert Sparks <[email-masked]>
Date: Mon, 2 Nov 2020 13:31:16 -0600

> Much weirder, but not benefitting from page numbers:

Ugh. To make sure we don't conflate "need to convey a bit exact and long 
message" with whether what 6716 did with that appendix was a good idea...

There are docs that have test vectors, doing a uuencoded tarball (or 
some other armoring that survives text transmission) has been useful for 
those.

A different example, would be appendix A. in RFC4475 for example.

---

From: Julian Reschke <[email-masked]>
Date: Tue, 3 Nov 2020 08:23:20 +0100

> ABNF can get pretty large (certainly more than one traditional page).

Many specs have the ABNF defined in context (HTTP, URI...). That makes
it much easier to refer to specific rules.

(In HTTP as of 2014, we have additionally included a "collected" ABNF as
appendix).

Best regards, Julian

---

From: tom petch <[email-masked]>
Date: Tue, 3 Nov 2020 11:35:51 +0000

<inline a query on v3>

> in the v3 xml world anyway.

That I do not understand.  What is different with the v3 xml world that 
the extraction code is not needed?  And is this also true for the checks 
that are performed on YANG modules that they 'compile' ok which I think 
are done automativally when a I-D with a YANG module in it is submitted 
(it is a while since I submitted an I-D with a YANG module it it)?

Tom Petch

---

From: Julian Reschke <[email-masked]>
Date: Tue, 3 Nov 2020 13:19:08 +0100

> (it is a while since I submitted an I-D with a YANG module it it)?

In the v3 world, you have by definition an XML document from which you
can trivially extract artwork/sourcecode sections, no matter how the
published plain text looks like.

Best regards, Julian

---

From: Michael Richardson <[email-masked]>
Date: Tue, 03 Nov 2020 11:31:27 -0500

It seems to me that for more line oriented "artwork"
(i.e., source code: ABNF, YANG, ASN.1, etc.)
that even in HTML and PDF renderings, that we are using page number
references as a crux because we don't have line numbers.

It seems to me that adding line numbers with CSS is a thing, and we should do
that for HTML in that way.

For unpaginated TXT, our rendering should add line numbers.
I'd even go as far as embedding a URL for that content-piece
into the text file, since some people will come across the RFC
in a source repo as txt.

(That's one of my use cases for having rfcXXXX.txt vs HTML)

--
Michael Richardson <[email-masked]>   . o O ( IPv6 IøT consulting )
           Sandelman Software Works Inc, Ottawa and Worldwide

---

From: Tony Finch <[email-masked]>
Date: Thu, 5 Nov 2020 22:59:29 +0000

John R. Levine <[email-masked]> wrote:
>
> My point was that if you want a mechanical reference to a section
> in an RFC, the RFCs we publish now have them.

I think that when you have neither page numbers nor paragraph numbers then
document authors ought to be much more keen to have lots of numbered
subheadings to make it easier for people to refer to a particular point.
(Actually I think more subheadings are good regardless of numbering!)

Numbered paragraphs would make references even easier. The C standard has
paragraph numbers but they are not written in a way that suggests exactly
how a reader should refer to them
<http://www.open-std.org/jtc1/sc22/wg14/www/docs/n1570.pdf>. There have
been a few RFCs with paragraph numbers, e.g. RFC 2671, RFC 2845 (I don't
know if this is a Vixie-ism or if other authors did it too) and they
helpfully include the full dotted section number so they make it clear how
to refer to them, and they give you more context if you are lost in a wall
of text.

I had a look for recent RFCs with problematic lack of numbering and the
first I found was RFC 8923. There's a figure in section 6.1 without a
number. There's a huge list of protocol features in appendix A which a
reader can only refer to by name (if they don't want to depend on a
particular web site), and which can only be located by searching (awkward
if you are reading on paper). These problems can be avoided within the
current technical style but it needs a change in editorial style to ensure
the table of contents has a high enough density.

Tony.
-- 
f.anthony.n.finch  <[email-masked]>  http://dotat.at/
Sole: East 5 or 6. Rough. Fair. Good.
_______________________________________________
rfc-interest mailing list
[email-masked]
https://www.rfc-editor.org/mailman/listinfo/rfc-interest

---

From: Tony Finch <[email-masked]>
Date: Sun, 8 Nov 2020 15:54:40 +0000

Phillip Hallam-Baker <[email-masked]> wrote:

> The paragraphs are already numbered. All it would take is a small change to
> the HTML-izer.

A reader needs to know how to refer to specific text regardless of the
format of the RFC: if paragraph numbers are going to be helpful they need
to appear in every format with a consistent syntax that's convenient to
use in things like document reviews.

Tony.
Malin: Southeast 4 to 6. Rough becoming moderate. Occasional rain. Moderate or
good, occasionally poor.

---

From: "John R. Levine" <[email-masked]>
Date: 8 Nov 2020 12:18:25 -0500

> use in things like document reviews.

I see where you're coming from, but I have to push back.  Different 
formats serve different purposes.  It would be technically easy to put 
paragraph numbers in the rendered text or PDF, but it would also be ugly 
and cluttered.  We do put thenm in the HTML because they're hidden until 
you hover over the mark at the end of the paragraph.

This comes back around to the question of variant not-quite-the-same 
renderings.  We currently have text without para or page numbers.  Add 
optioons for both and now we have four variant renderings.  I'm not 
unalterably opposed to that, and at least paragraph numbers unlike page 
nunbers should be stable if they appear at all, but I'd really like to 
have a strategy rather than looking at one wart at a time.

Regards,

---

From: Tony Finch <[email-masked]>
Date: Sun, 8 Nov 2020 22:00:41 +0000

John R. Levine <[email-masked]> wrote:
>
> It would be technically easy to put paragraph numbers in the rendered
> text or PDF, but it would also be ugly and cluttered.

Yes :-) The alternative is to insist on a high enough density of
subheadings so that readers can find their way around a document at least
as well as they could when page numbers imposed an upper limit on the size
of a wall of text, e.g. keep the number of paragraohs in a subsection
within the range of subitizing https://en.wikipedia.org/wiki/Subitizing

Tony.
a world in which all people share the same basic rights