Subject: Resending: Page numbers in RFCs questions / preferences

From: Toerless Eckert <[email-masked]>
Date: Mon, 26 Oct 2020 03:04:33 +0100

Sent this question originally only to rfc-interest mailing list, but never
received a reply. Resending now also to wgchairs.

Thanks for any replies to my questions or suggestions what i could try to
do to get more page numbres back into the non-PDF output formats.

Cheers
    Toerless

On Thu, Sep 24, 2020 at 08:57:33AM +0200, Toerless Eckert wrote:
> Sorry for being asleep at the wheel, but i am just recognizing that newer
> RFCs on tools, datatracker and even in PDF formats do not have page numbers
> in their TOC, and that the original RFCs on rfc-editor do not even
> have any TOC. Nor is there any pagination in any of the text or html
> renderings and hence no notion of size/pages. One has to click to the
> pdf rendering, and scroll to the bottom to know the size of a document.
> 
> When did this change happen, where was it discussed ?
> 
> In my defense, even though i just had an rfc recently (rfc8815), this
> whole formatting change totally flew by me even when reviewing changes with
> RFC editor, because all the diffs from RFC editor we discussed still had
> the old and probably current formatting with pagination/TOC-with-page-numbers
> to the best of my memory, and somehow i didn't read recently any new RFCs
> since when this change seems to have happened (yes i know, shame on me).
> 
> Curious...
> 
> I actually would very much appreciate a rendering with pagination and
> page numbers in TOC. What would be the right place to ask for this ?
> (probably not rfc editor...)
> 
> Cheers
>     Toerless

---

From: David Noveck <[email-masked]>
Date: Mon, 26 Oct 2020 06:51:36 -0400

On Sun, Oct 25, 2020, 10:04 PM Toerless Eckert <[email-masked]> wrote:

> Sent this question originally only to rfc-interest mailing list,

I suppose that, officially speaking, that is the right mailing list.

but never
> received a reply.

I used to feel bad that I didn't pursue this on rfc-interest, but I now see
this would have been a waste.  Thanks for trying.

Resending now also to wgchairs.

You'll get at least one response.

> > Sorry for being asleep at the wheel,

I think it is OK relying on a self-driving process in this case, since
there was no possibility of death or physical injury.

but i am just recognizing that newer
> > When did this change happen, where was it discussed ?

I think it happened with the conversion to v3 xml.  At that time, the
72-character-ragged-right .txt format ceased to be considered canonical
(long overdue in my opinion).  As a result, in accord with some RFC that I
was pointed to, a decision was made (by whom it wasn't clear) to make all
TOCs the same, so that the pdf and text TOCs lost theirs since there was no
way to add them to html which doesn't have them.  The logic is impeccable
if you grant the premises and nobody ever considered rethinking the
premises when it resulted in nearly useless printed documents. Sigh!

> > In my defense,

Why would you need a defense? Do you feel under attack?

even though i just had an rfc recently (rfc8815), this
> > since when this change seems to have happened

I bet it happened, when, as the last stage of the RFC editing process, a
conversion was made to v3 xml and then there was no way back.

(yes i know, shame on me).

Since this was the first time, I think "Fool me once, shame on them"
applies, even if it is hard to identify "them".

> > Curious...

I think "insane" is a more appropriate adjective but it needs to be
understood that this is a statement of opinion and should not be understood
as a clinical judgment.

> > page numbers in TOC. What would be the right place to ask for this ?

I've asked the xml2rfc people who didn't really respond.

> (probably not rfc editor...)

The RFC editor was sympathetic and helpful but has no power to change
things.  Unfortunately, I'm not sure who does.

Currently, the only way to get a newer RFC with page numbers is to edit the
RFC xml to turn it into an I-D. That has problems but is the only way I
know to get a printed document with a useful TOC.

I would expect that the IETF plenary might be an appropriate venue to
discuss this.  If you do pursue this, let people know so they can be up at
4AM EST or 1AM PST and purchase a one-day pass.

---

From: Carsten Bormann <[email-masked]>
Date: Mon, 26 Oct 2020 13:55:40 +0100

On 2020-10-26, at 11:51, David Noveck <[email-masked]> wrote:
> 
> I think it happened with the conversion to v3 xml.  At that time, the 72-character-ragged-right .txt format ceased to be considered canonical (long overdue in my opinion).  As a result, in accord with some RFC that I was pointed to, a decision was made (by whom it wasn't clear) to make all TOCs the same, so that the pdf and text TOCs lost theirs since there was no way to add them to html which doesn't have them.  The logic is impeccable if you grant the premises and nobody ever considered rethinking the premises when it resulted in nearly useless printed documents. Sigh!

Obviously, with canonical XML, there is no good solution to this problem: Different renditions will have different concepts of pages, so the TOC’s won’t align.

(That is not a good argument for then finally choosing what is probably the worst possible solution to this problem.  I think what happened is that nobody thought about PDF where we continue to have pages, so there never really was a problem specific to retaining pages and thus page numbers in the TXT.)

Grüße, Carsten

---

From: Toerless Eckert <[email-masked]>
Date: Mon, 26 Oct 2020 16:02:41 +0100

Is there any reason why the tools team would not be able to produce
a rendered version that does incude page numbers ? PDF and txt ?
Call it RFC classic format ?

This is even just for simple examination like checking how long
a particular RFC is. Ridiculous if there is no indication of that.

If so, does a request like that first need to go into some RFC,
or just into the infinite wish list of the tools team where it might
only be prioritized by rallying up the community to provide some
+1 (in whatever fashion is appropriate - which i am unclear about...).

Cheers
    Toerless

On Mon, Oct 26, 2020 at 01:55:40PM +0100, Carsten Bormann wrote:
> Obviously, with canonical XML, there is no good solution to this problem: Different renditions will have different concepts of pages, so the TOC???s won???t align.
> 

-- 
---
[email-masked]

---

From: David Noveck <[email-masked]>
Date: Mon, 26 Oct 2020 11:04:49 -0400

On Mon, Oct 26, 2020 at 8:55 AM Carsten Bormann <[email-masked]> wrote:

> Obviously, with canonical XML, there is no good solution to this problem:

It's not clear what problem you are referring to.

> Different renditions will have different concepts of pages, so the TOC’s
> won’t align.
>

There's no reason for them to align with each other.   The paperback and
hardcover editions of books have different TOCs but there is no need for
them to be the same, as long as each matches the document it is a TOC for.

(That is not a good argument for then finally choosing what is probably the
> worst possible solution to this problem.

Actually it's a non-solution to a non-problem.

> I think what happened is that nobody thought about PDF where we continue
> to have pages,

 I think that's probably true.

so there never really was a problem specific to retaining pages and thus
> page numbers in the TXT.)
>
>  I guess this is because nobody thought about TXT files being printed
either.

Grüße, Carsten

---

From: Toerless Eckert <[email-masked]>
Date: Mon, 26 Oct 2020 16:14:03 +0100

>  I think that's probably true.

I always printed the .txt RFCs.

Pages are also a perfectly valid concept in the absence of sheets.
Its a measurement for the amount of text that is quite useful.

Cheers
    Toerless

---

From: Benjamin Kaduk <[email-masked]>
Date: Mon, 26 Oct 2020 09:28:14 -0700

> Call it RFC classic format ?

IIRC the xml2rfc tool already supports the pagination functionality with a
command-line argument, so you can make your own right now.
Unfortunately, I was unable to find the exact incatation in the mail
archives within the time I allotted for searching.

-Ben

---

From: Toerless Eckert <[email-masked]>
Date: Mon, 26 Oct 2020 17:40:36 +0100

Thanks, Ben. 

Then i guess it shouldn't be too hard for the tools team to
offer at least on tools.ietf.org beside the existing formats one
with e.g.: text with pagination...

I guess i'll have to ask Henrik how best to proceed.

Cheers
    Toerless

-- 
---
[email-masked]

---

From: Henrik Levkowetz <[email-masked]>
Date: Mon, 26 Oct 2020 18:11:12 +0100

Hi,

xml2rfc currently supports pagination of .txt output for drafts, but not
for RFCs.  This is a limitation originally requested by the RFC editor, in
the specification for the v3 text formatter work for RFCs.

A couple of months ago, prompted by multiple requests for the ability to
produce paginated .txt output for RFCs, I asked for permission to enable
pagination also for RFCs, but in the end the RSOC answered that they did
not want to make it possible to generate paginated .txt output for RFCs.

John Levine should be able to give further information.

I'd be perfectly happy to add the ability; given that it's available for
drafts it's trivial from a technical viewpoint.

Best regards,

	Henrik

---

From: Toerless Eckert <[email-masked]>
Date: Mon, 26 Oct 2020 18:19:32 +0100

Hi John/RSOC,

Could you please explain why RSOC does not want to permit the ability
to have paginated RFC output options ? Also, where and when was this
discussed with the community ?

Thank you!
    Toerless

P.S.: Thanks, Henrik

-- 
---
[email-masked]

---

From: "John R. Levine" <[email-masked]>
Date: 26 Oct 2020 13:35:43 -0400

> discussed with the community ?

It was discussed in the multi-year process leading to the IAB
publishing RFCs 7990, 7991, 7992, 7993, 7994, 7995, 7996, 7997, and
7998 in 2016. I'm sure you know how to find the discussions in the
archives.  Henrik knows all of this and I cannot imagine why he did not 
tell you the same thing.

I am aware there is one recent RFC author who did not participate in
the process at all and has been complaining that the text version of
his RFC doesn't have page numbers. I've explained this to him more
than once, and see no reason to waste more time on it.

R's,
John

---

From: Robert Sparks <[email-masked]>
Date: Mon, 26 Oct 2020 12:44:04 -0500

John - you've answered why RFCs are not published with page numbers and 
where/when the community discussion that took place for that decision.

You haven't answered whether/how the RSOC engaged the community on the 
question of whether the tools should let someone produce an RFC locally 
that has page numbers in it for themselves if they want to. The 
reasoning for not letting the tools produce such a thing is certainly 
not explicitly captured in the series of RFCs you point to.

Julian has alluded to the principle behind the pressure already, but I'm 
still at a small loss for why RSOC, or the RSE, should care about what 
people make for themselves?

RjS

On 10/26/20 12:35 PM, John R. Levine wrote:
> archives.  Henrik knows all of this and I cannot imagine why he did 
> not tell you the same thing.
>

---

From: Carsten Bormann <[email-masked]>
Date: Mon, 26 Oct 2020 18:45:31 +0100

> It's not clear what problem you are referring to.

The problem will become very evident once you get an RFP asking that your product implement the procedure on page 68 of RFC 9815.

You cannot really argue this based on whether people SHOULD be using section numbers etc.  This is a real downside in the real world.

Now whether that downside is overriding all the other upsides of having page numbers, can be a subject of discussion.

Grüße, Carsten

---

From: Toerless Eckert <[email-masked]>
Date: Mon, 26 Oct 2020 19:01:05 +0100

Since about RFC8650, newer RFC will not have any renderings with
page numbers on {datatracker,tools}.ietf.org. See explanation from
John Levine below.

Not having followed the details of the RFC/XMLv3 standardization process,
i was surprised by this because i think there is no reason to
have additional renderings, maybe even only on tools.ietf.org that
do include page numbers (and technically it does not seem to be a problem
either). 

If you care to express your position,
i have created a poll for this, please chime in there:

https://www.poll-maker.com/results3188562x294441dA-98

Cheers
    toerless

On Mon, Oct 26, 2020 at 01:35:43PM -0400, John R. Levine wrote:
> archives.  Henrik knows all of this and I cannot imagine why he did not tell
> you the same thing.
>

---

From: Toerless Eckert <[email-masked]>
Date: Mon, 26 Oct 2020 19:05:40 +0100

Carsten:

I would be fine if all the renderings with page numbers would be based on
the traditioanl txt format with i think 49 payload lines. If its
difficult to create native PDF with that constraint, then just
PDF'ize the classical text output.

-- 
---
[email-masked]

---

From: Robert Sparks <[email-masked]>
Date: Mon, 26 Oct 2020 13:11:36 -0500

Hi Toerless -

Just to be clear about my other thread on the subject - having xml2rfc 
produce things that look like RFCs that have page numbers in them for 
someone's local use is one thing. Publishing such things is entirely 
different. Confusion about different versions of published things is a 
real consideration. To get to that point, I think you really are talking 
about changing a community consensus set of documents - the output of 
such a poll will be input into some drafts, not just "stand up this 
separate service".

RjS

---

From: Warren Kumari <[email-masked]>
Date: Mon, 26 Oct 2020 14:25:21 -0400

> The problem will become very evident once you get an RFP asking that your product implement the procedure on page 68 of RFC 9815.

Yup -- I've already run into this sort of thing when talking with
authors and others -- I used to be able to say things like "Erm,
section 3, um... just above the bottom of the page..." and now it
involves much more quoting, etc.
I also liked to collect stats on documents that I review -- e.g:
(7,635 pages, ~31" / 79cm / 15 reams of single-sided paper).
Gamifying reviews makes them easier...

I really like the concept / history / continuity of RFCs being the
same over these many years; I didn't really participate in the v3
discussions, and am sad that the page numbers and similar have
changed...
W

-- 
I don't think the execution is relevant when it was obviously a bad
idea in the first place.
This is like putting rabid weasels in your pants, and later expressing
regret at having chosen those particular rabid weasels and that pair
of pants.
   ---maf

---

From: "Acee Lindem (acee)" <[email-masked]>
Date: Mon, 26 Oct 2020 18:36:19 +0000

On 10/26/20, 2:26 PM, "WGChairs on behalf of Warren Kumari" <[email-masked] on behalf of [email-masked]> wrote:

I wasn't involved in the RFC format discussion either but can't see how removing the pagination could have been seen as an advantage. Additionally, it is annoying that the htmlized version don't provide links to sections/sub-sections from TOC. 

Thanks,
Acee

    W

---

From: Brian E Carpenter <[email-masked]>
Date: Tue, 27 Oct 2020 07:56:36 +1300

As Julian Reschke observed on the rfc-interest list, since the
new RFC format was implemented:

>  page numbers should not be used to refer to parts of the
>  RFC, because page breaks vary with output formats

So I can only see confusion if people use page numbers for
any purpose whatever. So it doesn't matter if people want
page numbers; they're now useless. So I won't be answering
a poll, and I don't think the results are interesting.

Regards
   Brian 

Regards
   Brian Carpenter

On 27-Oct-20 07:01, Toerless Eckert wrote:
> .

---

From: Toerless Eckert <[email-masked]>
Date: Mon, 26 Oct 2020 20:10:42 +0100

Brian:

RFC editor can easily check that new RFC will not have references to
other RFCs with page numbers.

Its also perfectly easy to have only one rendering of page numbers, so
therre won't be inconsistencies of page numbers on official IETF pages.

Cheers
    Toerless

-- 
---
[email-masked]

---

From: John Scudder <[email-masked]>
Date: Mon, 26 Oct 2020 21:14:37 +0000

On Oct 26, 2020, at 2:56 PM, Brian E Carpenter <[email-masked]<mailto:[email-masked]>> wrote:

The argument that page numbers are harmful as a way of referring to a section of the RFC is reasonable.

The argument that page numbers are harmful for *any* *purpose* *whatever* is not reasonable. To offer one glaringly obvious counterexample, people (I, for one) sometimes print RFCs for the purpose of reading them. Sometimes we want to make use of some kind of facility for indexing from a list of headings to facilitate direct access to the right section of the pile of printout. A table of contents, in short. This is literally what tables of contents were invented for. They remain useful for this purpose… unless some bright spark chooses to remove the page numbers from them, because they forgot what tables of contents are FOR.

(Also, I think the use of the ToC for quickly estimating a document’s throw weight is a valid one. I previously suggested associating a BogoPages metric with each non paginated RFC for this purpose.)

—John

---

From: Brian E Carpenter <[email-masked]>
Date: Tue, 27 Oct 2020 10:16:01 +1300

> other RFCs with page numbers.

That is only one of the many ways in which ambiguous page numbers could be harmful.

> therre won't be inconsistencies of page numbers on official IETF pages.

I don't get it. Web sites don't have page numbers. We agreed during the whole process of designing the new RFC format that HTML is the most desirable presentation format. Page numbers make no sense and have no value in HTML.
So why bother with them in txt, which is now a legacy format and not very useful for new RFCs? (PDF is an oddity, since it's basically page images, so its page numbers will always be a source of confusion.)

You may have noticed that rfcdiff removes page breaks as its first step, and there's a reason for that: pages are irrelevant even when comparing plain text. As soon as you go to flowed rich text, they are even more irrelevant.

Maybe it's because I was brought up on paper tape rather than punch cards, but I can't see why anybody cares about pagination in 2020.

Regards
    Brian

---

From: Jeffrey Haas <[email-masked]>
Date: Mon, 26 Oct 2020 17:48:15 -0400

On Mon, Oct 26, 2020 at 06:36:19PM +0000, Acee Lindem (acee) wrote:
> I wasn't involved in the RFC format discussion either but can't see how
> removing the pagination could have been seen as an advantage.
> Additionally, it is annoying that the htmlized version don't provide links
> to sections/sub-sections from TOC. 

I understand why the page numbers were removed.  I think you're getting to
the more core issue: There is a need to provide a way to refer to portions
of documents easily.

For individual sections, the TOC absolutely should provide linkage to
sections, especially in formats like HTML.

The input XML already provides blocks.  It should be fairly reasonable for
the tool to provide you something like "this is section X.Y, ¶5".

How such a thing would eventually manifest in our old school email
discussions is likely to be the ugly discussion.

-- Jeff

---

From: Carsten Bormann <[email-masked]>
Date: Mon, 26 Oct 2020 22:33:10 +0100

On 2020-10-26, at 22:16, Brian E Carpenter <[email-masked]> wrote:
> 
> Maybe it's because I was brought up on paper tape rather than punch cards,

Ah!  I used both in the 1970s, but more punch cards, and even my paper tape was mostly Z-folded not rolled…  That explains it.

> but I can't see why anybody cares about pagination in 2020.

Proof by lack of imagination :-)

Apparently these people do exist, and they have been speaking up with their use cases.

Grüße, Carsten

---

From: Brian E Carpenter <[email-masked]>
Date: Tue, 27 Oct 2020 10:37:39 +1300

On 27-Oct-20 10:14, John Scudder wrote:
> On Oct 26, 2020, at 2:56 PM, Brian E Carpenter <[email-masked] <mailto:[email-masked]>> wrote:
>>

Well yes... but iirc the input to the new format discussion was that most people read RFCs and drafts on-screen and mostly with the htmlized versions. So the needs of the occasional eccentrics who print them for off-line reading were set aside. (I can say that because I am such an eccentric.)
 
> (Also, I think the use of the ToC for quickly estimating a document’s throw weight is a valid one. I previously suggested associating a BogoPages metric with each non paginated RFC for this purpose…

Well, the byte count serves fairly well for that too.

Regards
   Brian

---

From: Benjamin Kaduk <[email-masked]>
Date: Mon, 26 Oct 2020 14:51:17 -0700

> sections, especially in formats like HTML.

The native HTML format does.  I have no idea why the htmlization script
can't or does not do so for new-format RFCs.

> the tool to provide you something like "this is section X.Y, ¶5".

Like https://www.rfc-editor.org/rfc/rfc8815.html#section-3.1-5 ?

-Ben

---

From: Wes Hardaker <[email-masked]>
Date: Mon, 26 Oct 2020 14:53:46 -0700

> Gamifying reviews makes them easier...

I suggest a new metric instead to measure length: the "PoN".

1 PoN = the length of our largest RFC to date (where today becomes the
equivalent of Jan 1, 1970 is for seconds): RFC8881 (NFS version 4 minor
version 1 protocol) in txt format.  Thus, 1 PoN = 1593486 octets or
31832 lines.

Then we can measure the length of any other document based on this
length.  Thus, RFC3514 ("The Security Flag in the IPv4
Header."), which is 11211 octets or 339 lines becomes ".0070:.0106 PoN".
-- 
Wes Hardaker
USC/ISI

---

From: Flemming Andreasen <[email-masked]>
Date: Mon, 26 Oct 2020 18:00:14 -0400

On 10/26/20 5:14 PM, John Scudder wrote:
> On Oct 26, 2020, at 2:56 PM, Brian E Carpenter 
> <[email-masked] <mailto:[email-masked]>> wrote:
>>
> The argument that page numbers are harmful for *any* *purpose* 
> *whatever* is not reasonable. To offer one glaringly obvious 
> counterexample, people (I, for one) sometimes print RFCs for the 
> purpose of reading them. Sometimes we want to make use of some kind of 
> facility for indexing from a list of headings to facilitate direct 
> access to the right section of the pile of printout. A table of 
> contents, in short. This is literally what tables of contents were 
> invented for. They remain useful for this purpose… unless some bright 
> spark chooses to remove the page numbers from them, because they 
> forgot what tables of contents are FOR.
>
+1

Page numbers are also quite helpful to keep the pages in the right order 
after you have printed them, and in a ToC it helps giving you an idea of 
how much material is in each section.

I confess that while most of my reading is on-line, I still buy physical 
books, use highlighters and occasionally print out an RFC either in part 
or in full. It sounds like I'm not the only one, and I have a hard time 
understanding why I am not allowed to get page numbers to help in that 
process.

Thanks

-- Flemming

> (Also, I think the use of the ToC for quickly estimating a document’s 
> throw weight is a valid one. I previously suggested associating a 
> BogoPages metric with each non paginated RFC for this purpose.)
>
> —John

---

From: Henk Birkholz <[email-masked]>
Date: Mon, 26 Oct 2020 23:00:31 +0100

Hi all,

TL;DR
Gave up on looking up rfc-interest WGLC results from years ago; plenty 
use of the term surprise.

I admit, I was surprised by the notion that "there will be no more page 
numbers" over a year ago. I was not involved in any way in WGLCs that 
happened in rfc-interest in... 2015?

I can understand that people are now puzzled by these decisions back 
then, to be honest. Typically, I fault myself for not spending enough 
attention, so.. my bad. I spent some attention right now - and it 
yielded this:

> https://www.rfc-editor.org/pipermail/rfc-interest/

and I am certainly not going to do this right now:

> https://trac.tools.ietf.org/group/tools/trac/wiki/Imap#Overview

So yes, there probably was some discussion on something that resulted in 
consensus in some scope. I cannot easily check that right now (attention 
span and kids bedtime and such), but I can state that I am not surprised 
that this somehow violates the principle of least surprise, today.

Oh... and why was I trying to skim the archive? To find out why a TOC in 
HTML is harmful in a way that page numbers are harmful :o)

Viele Grüße,

Henk

---

From: "Andrew G. Malis" <[email-masked]>
Date: Mon, 26 Oct 2020 18:02:16 -0400

Flemming,

If you need a printable version with page numbers, that's provided by the
RFC Editor for every RFC, for example
https://www.rfc-editor.org/rfc/rfc8905.pdf (to cite a recent example). If
you quickly need the last page number, just click in your browser or PDF
reader on the last entry in the TOC.

Cheers,
Andy

On Mon, Oct 26, 2020 at 6:01 PM Flemming Andreasen <fandreas=
[email-masked]> wrote:

> On Oct 26, 2020, at 2:56 PM, Brian E Carpenter <
> [email-masked]> wrote:
>
>
> The argument that page numbers are harmful for *any* *purpose* *whatever*
> is not reasonable. To offer one glaringly obvious counterexample, people
> (I, for one) sometimes print RFCs for the purpose of reading them.
> Sometimes we want to make use of some kind of facility for indexing from a
> list of headings to facilitate direct access to the right section of the
> pile of printout. A table of contents, in short. This is literally what
> tables of contents were invented for. They remain useful for this purpose…
> unless some bright spark chooses to remove the page numbers from them,
> because they forgot what tables of contents are FOR.
>
> +1
>
> books, use highlighters and occasionally print out an RFC either in part or
> in full. It sounds like I'm not the only one, and I have a hard time
> throw weight is a valid one. I previously suggested associating a BogoPages
> metric with each non paginated RFC for this purpose.)
>
> —John
>
>
>

---

From: John C Klensin <[email-masked]>
Date: Mon, 26 Oct 2020 18:06:36 -0400

Brian,

I look at the same information and come to a different
conclusion (quite independent of the question of whether a poll
at this point is a useful exercise)...

>>  RFC, because page breaks vary with output formats

Cross references (and other references) to page numbers have
been discouraged since at least RFC 1543 (in 1993) and banned
soon after that, to the point that the RFC Editor from the last
half of the 1990s would simply remove such references, replace
them with references to section numbers, and complain when
sections got too long for convenient referencing.  Nothing about
restricting references to page numbers is new with the new
format.   

> a poll, and I don't think the results are interesting.

However, getting from "references to information by page numbers
have always been a bad idea, prohibited for a quarter-century,
and even more obviously a bad idea as we move to multiple
formats" to "any purpose whatsoever" is a big jump.  At least
some of us have tools and macros floating around that are
dependent on pagination and, as an exception to the
"referencing" rules, it is still not clear (at least to me) how
to build and format a document index using anything else (at
least without a lot of effort).  There are even simple and
obvious reasons: If one is going to print an RFC from the text
form (or render it into printable form), something is going to
do the pagination and being able to easily estimate the page
count may affect how printing is to be set up.

FWIW, the questions of "should documents be paginated" and
"should the pages be numbered" are also separate ones.

Moreover, the argument that pagination (and page numbers) are
obsolete and useless for RFCs would be much stronger if the PDF
form for new RFCs were not paginated (or at least not numbered)
... but it is both paginated and numbered.   And, if the issue
is having things lay out well on many different types of
devices, eliminating pagination (and headers and footers) to
facilitate that is bogus: it would be equally or more reasonable
to eliminate (or rethink) line breaks in running text, etc.   If
one really wants things optimally formatted for a variety of
different devices, then the right thing to do is to start from
the HTML form and a well-designed style sheet or to go back all
the way to the XML, not to try fussing with the ASCII text form. 

Conclusion: The main arguments that have been given for
eliminating pagination, headers and footers, and page numbering
--at least those based on different devices and references-- are
mostly bogus.

So, from my point of view as a fan of pagination in the ASCII
form of RFCs, one who has never willingly referenced part of an
RFC by page number, this seems to come down to something else
entirely: if there is a goal to eliminate (or strongly
discourage) the use of ASCII format RFCs in favor of the HTML or
PDF forms (or building directly on the XML), then "no page
numbers" and "no pagination" are among the first few cuts of a
death by 1000 of them.    If not, this has all of the hallmarks
of a gratuitous change to a format that has been useful to many
people for a very long time.

    john

p.s. Just in case I'm the anonymous person John Levine's note
referred to, I didn't just "not participate" in the discussion.
It was made extremely clear that my input was not welcome, so
clear that, after a discussion or two with Heather that I should
spend my time in other ways.  If there were a significant number
of others like me (and I have no way to tell, or even to guess)
then claims that the no-pagination form represents community
consensus lie somewhere on the scale between "dubious" and
"bogus".

---

From: Henk Birkholz <[email-masked]>
Date: Mon, 26 Oct 2020 23:07:22 +0100

I also think that the Header in the tools' HTML version provides tons of 
convenience functions. So many in fact that the current status quo 
actually conditioned me to look for a "tools" annotation in a button on 
the datatracker. Maybe that's just me, though.

---

From: Toerless Eckert <[email-masked]>
Date: Mon, 26 Oct 2020 23:14:26 +0100

Wes: Obviously, you can not use such a random point of
reference. This is like oh, Fahrenheit operated to find 0. And how
the heck could you go for something from a German anyhow
(and keep it for hundreds of years unchanged).

Obviouosly the point of reference needs to be a universal constants
of the IETF universe. Hence the size of documents needs to be measured
relative to rfc8200.

On Mon, Oct 26, 2020 at 02:53:46PM -0700, Wes Hardaker wrote:
> _______________________________________________
> rfc-interest mailing list
> [email-masked]
> https://www.rfc-editor.org/mailman/listinfo/rfc-interest

---

From: Toerless Eckert <[email-masked]>
Date: Mon, 26 Oct 2020 23:33:01 +0100

Btw: If folks are so worried about inappropriate use of page numbers
or inconsistencies in different renderings, we could define that instead of
a numerically increasing number, the page identifier is he byte count of
the text representation of the document up to the end of the page.

I am sure this approach would give us a more permanent high-score in
geekyness amongst SDOs than simply being the only one not using page numbers.

*sigh* 

Cheers
    Toerless

On Mon, Oct 26, 2020 at 11:07:22PM +0100, Henk Birkholz wrote:
> convenience functions. So many in fact that the current status quo actually
> conditioned me to look for a "tools" annotation in a button on the
> datatracker. Maybe that's just me, though.
> 

-- 
---
[email-masked]

---

From: Wes Hardaker <[email-masked]>
Date: Mon, 26 Oct 2020 15:49:48 -0700

> of the IETF universe. Hence the size of documents needs to be measured

Are you telling me that all operators had to do in order to switch
versions was multiple IPv4 by 1.0185 to upgrade to IPv6?  Nice.
-- 
Wes Hardaker
USC/ISI

---

From: Toerless Eckert <[email-masked]>
Date: Tue, 27 Oct 2020 00:31:38 +0100

Brian:

Given how it seemingly would be quite easy for tooling to ALSO
provide a paginated rendered version of the document, the basis
of the decision process to explicitly reject to support that
option looks unfortunately like a slim mayority not only getting
their way, but also wanting to force the minority NOT to get its
way too, quite unnecessarily. Not very inclusive.

Of course, i know: slippery slope argument:

"If everybody who had a 40 year beloved and successful document
format would step forward and request that a tiny bit of effort would
be spent to provide an easily done rendering for it, where would we
as the IETF end up then..."

Cheers
   Toerless

-- 
---
[email-masked]

---

From: David Noveck <[email-masked]>
Date: Mon, 26 Oct 2020 19:40:58 -0400

> consensus lie somewhere on the scale between "dubious" and

Disagree.  It is far past bogus.   How about "somewhere between 'false' and
'disingenuous'"?

---

From: Brian E Carpenter <[email-masked]>
Date: Tue, 27 Oct 2020 12:51:39 +1300

John,

Let me retract "useless". What really bothers me is that page numbers are actively misleading in the new format. I think that became true the moment a consensus appeared that the preferred presentation format was HTML with flowed text.

Regards
   Brian

---

From: John C Klensin <[email-masked]>
Date: Mon, 26 Oct 2020 19:56:30 -0400

--On Tuesday, October 27, 2020 10:37 +1300 Brian E Carpenter
<[email-masked]> wrote:

>> The argument that page numbers are harmful for *any*
>> *purpose* *whatever* is not reasonable. To offer one
>> glaringly obvious counterexample, people (I, for one)
>> sometimes print RFCs for the purpose of reading them.
>> Sometimes we want to make use of some kind of facility for
>> indexing from a list of headings to facilitate direct access
>> to the right section of the pile of printout. A table of
>> contents, in short. This is literally what tables of contents
>> were invented for. They remain useful for this purpose…
>> unless some bright spark chooses to remove the page numbers
>> from them, because they forgot what tables of contents are
>> FOR.

> Well yes... but iirc the input to the new format discussion
> was that most people read RFCs and drafts on-screen and mostly
> with the htmlized versions. So the needs of the occasional
> eccentrics who print them for off-line reading were set aside.
> (I can say that because I am such an eccentric.)  

But, first of all, if the only need is to print (eccentric or
not) for off-line reading were the only issue, then that is an
argument in favor of PDF and perhaps abolishing the text form,
not crippling it, unless one happens to like the fixed-pitch
font (definitely eccentric).   The people whose needs were set
aside were those of us who routinely use text editors (of the
emacs or vi species and their clones), and personal RFC-specific
macros in those editors, to work with RFCs, many of whom have
been working that way for a long time (a few since before there
was an IETF). 

As to "set aside", there were at least some IETF participants
with those needs (or, if you prefer, habits), along with those
who argued for keeping the xml2rfc v3 specification rather
closer to generic markup (reducing rather than increasing the
amount of format markup) and inclusion of markup that would make
it straightforward to specify references to book chapters and
journal articles in relatively standard form. It was made clear
to at least a subset of that group that they were (to paraphrase
somewhat) a bunch of old farts who, regardless of their prior
experience, just did not understand the modern Internet and
publishing and therefore would not be listened to no matter what
they had to say.  That message was rather clear and, since the
process was not an IETF one, appeals and the like felt rather
hopeless.  So, some people just moved on to other things and
others concluded that the IETF was on enough of a downhill slide
that issues like publication formats made little difference.

The good news is that there apparently weren't very many of us.

>> (Also, I think the use of the ToC for quickly estimating a
>> document's throw weight is a valid one. I previously
>> suggested associating a BogoPages metric with each non
>> paginated RFC for this purpose.)
> 

Sure.  So does a line count given a format.  But, while I'm
reconciled to do it, time I spend re-understanding and then
rebuilding macros that are a couple of decades old is time that
isn't spent on IETF substantive work.  The question is whether
whatever benefits are gained by eliminating pagination from RFCs
-- presumably gains to those who continue to use the text form
rather than HTML or PDF because the latter two groups are
irrelevant -- are sufficient to justify that.

   john

---

From: Toerless Eckert <[email-masked]>
Date: Tue, 27 Oct 2020 00:59:08 +0100

> Let me retract "useless". What really bothers me is that page numbers are actively misleading in the new format. I think that became true the moment a consensus appeared that the preferred presenta…

I do not understand: Who is mislead about what ?

Also: Given how there are so many possible presentation methods and consumption use-cases,
why do you think that prohibiting a particular format is helpful to the community ?

Cheers
    Toerless

-- 
---
[email-masked]

---

From: Ronald Tse <[email-masked]>
Date: Tue, 27 Oct 2020 00:32:10 +0000

My two cents: why don’t we just run a poll to see what the “consensus” is?

To me, standardizing page numbers is the wrong direction — one of the features of XML RFC is to allow rendering content into different formats. Having page numbers for the ASCII version is fine (it’s only being done by xml2rfc anyway), but requiring these numbers inside the XML is putting the cart before the horse.

Ron

_____________________________________

Ronald Tse
Ribose Inc.

On Oct 27, 2020, at 7:56 AM, John C Klensin <[email-masked]<mailto:[email-masked]>> wrote:

--On Tuesday, October 27, 2020 10:37 +1300 Brian E Carpenter
<[email-masked]<mailto:[email-masked]>> wrote:

  john

Regards
  Brian

_______________________________________________
rfc-interest mailing list
[email-masked]<mailto:[email-masked]>
https://www.rfc-editor.org/mailman/listinfo/rfc-interest

---

From: John C Klensin <[email-masked]>
Date: Mon, 26 Oct 2020 20:49:33 -0400

--On Tuesday, October 27, 2020 12:51 +1300 Brian E Carpenter
<[email-masked]> wrote:

> Let me retract "useless". What really bothers me is that page
> numbers are actively misleading in the new format. I think
> that became true the moment a consensus appeared that the
> preferred presentation format was HTML with flowed text.

Brian,

Assume, temporarily and for purposes of discussion, that we
agree about that "actively misleading" part.  Then either:

* We should remove the page numbers from the PDF file (if they
are "actively misleading" in the text, then they are at least as
actively misleading in the PDF and put the pagination plus
headers and footers back into the text form.   

or

* We should remove the page numbers and headers and footers from
the PDF and than paginate the text form.  

Otherwise, I find it very difficult to argue that there is any
sort of principle  here other than "punish those who insist on
being dependent on the text form" and maybe even "punish them
sufficiently that they repent of their sins and switch over to
HTML".

FWIW, I assume that everyone who prefers the paginated text form
has their own set of priorities.  For me, it would be
pagination; headers and footers with title, author, and date;
and only then page numbering (which I tend to use only for
document lengths and the occasional indexed document).   So, if
the goal was to suppress page numbers in the text form as
useless or worse, from my personal standpoint the baby went out
with the bathwater.

Apologies, but because of how those long-ago discussions were
handled -- and then claimed to represent community consensus --
I've got a really bad attitude on this issue.

best,
    john

---

From: Fred Baker <[email-masked]>
Date: Mon, 26 Oct 2020 17:50:50 -0700

> On Oct 25, 2020, at 7:04 PM, Toerless Eckert <[email-masked]> wrote:
> 

It seems to me like the first thing you have to have is the concept of a "page", and that "page" needs to have a predictable "size". With ASCII documents, we defined those terms, in terms of a "line" and a number of them. Personally, that's what I use paragraph numbers for.

---

From: Toerless Eckert <[email-masked]>
Date: Tue, 27 Oct 2020 02:00:55 +0100

On Tue, Oct 27, 2020 at 12:32:10AM +0000, Ronald Tse wrote:
> My two cents: why don???t we just run a poll to see what the ???consensus??? is?
> 
> To me, standardizing page numbers is the wrong direction ??? one of the features of XML RFC is to allow rendering content into different formats. Having page numbers for the ASCII version is fine (it???s only being done by xml2rfc anyway), but requiring these numbers inside the XML is putting the cart before the horse.

Btw: i very much like to have unpaginated document versions, even as primary
reference. I just think it would be easy and useful to have datatracker/tools
provide both. Of course the page numbers wouldn't go into the XML!

Its just another case of "there is no one single right answer" (at least IMHO).

Cheers
    Toerless

> were invented for. They remain useful for this purpose???

-- 
---
[email-masked]

---

From: John C Klensin <[email-masked]>
Date: Mon, 26 Oct 2020 21:15:13 -0400

--On Tuesday, October 27, 2020 00:32 +0000 Ronald Tse
<[email-masked]> wrote:

> My two cents: why don't we just run a poll to see what the
> "consensus" is?

There are some other issues with polls that people have
addressed so I won't repeat here, but...

> To me, standardizing page numbers is the wrong direction —
> one of the features of XML RFC is to allow rendering content
> into different formats. Having page numbers for the ASCII
> version is fine (it's only being done by xml2rfc anyway),
> but requiring these numbers inside the XML is putting the cart
> before the horse.

Unless I have missed something important as I have skimmed this
thread, no one has advocated anything that could be described as
"requiring ... numbers inside the XML".   We had paginated and
numbered RFCs all through the lives of xml2rfc v1 and v2 and
still have paginated and numbered I-Ds, none of them requiring
numbering within the XML source.  The issue here, at least as I
understand it, is that we have three output forms for RFCs: PDF
(inherently page-image and paginated), HTML (inherently
producing output that is line-flowed and unpaginated although it
can certainly produce other forms as rendered results), and
text.  The latter was originally supposed to be preserved in as
close to the historical ASCII text pages as possible but the
powers that be decided that the conversion from the XML should
retain the fixed-length lines but drop pagination and headers
and footers with line numbers.  AFAICT, it is only that last
decision that is under review / discussion here.  

And, again, if the PDF form did not have those headers and
footers with page numbers on the latter, I'd be much more
sympathetic to arguments that page numbers were harmful (or
confusing, etc.) and should hence be suppressed in RFCs.  And
even if one accepts page numbers as evil, that doesn't make a
case against paginating and retaining headers and footers in the
text format.  But I think I'm repeating myself so should stop.

   john

---

From: Ronald Tse <[email-masked]>
Date: Tue, 27 Oct 2020 01:30:47 +0000

Thanks John for the clarification. There is some confusion to me whether the intention is just about the TXT output having page numbers, or for the PDF to also have the same page numbers, and whether to use page numbers inside cross references. There was a also discussion about a ToC and page numbers, but perhaps that was a diversion.

If the discussion is only about the ASCII output having page numbers, I have no objection because it is (nearly) purely cosmetic (in publication and in usage of the text, being done by xml2rfc).

If having page numbers will require the PDF output to also have page numbers, this inevitably leads to some shared spec between the TXT and PDF outputs on the topic of pagination, which is less ideal, but since I assume that is the work of xml2rfc, it’s not a concern to us as tool maintainers.

Adding page numbers to cross references can make reading confusing — since the cross references between the paginated and flowed versions will render these references differently. It’s doable, but again this requirement ties the paginated versions (TXT and PDF) together for consistency.

Of course, if the PDF output is simply an enhanced PDF-ized TXT version, these aren’t really issues.

Ronald Tse
Ribose Inc.

On Oct 27, 2020, at 9:15 AM, John C Klensin <[email-masked]<mailto:[email-masked]>> wrote:

--On Tuesday, October 27, 2020 00:32 +0000 Ronald Tse
<[email-masked]<mailto:[email-masked]>> wrote:

  john

---

From: Ronald Tse <[email-masked]>
Date: Tue, 27 Oct 2020 01:41:29 +0000

I did mean to say that it is very useful to have page numbers, headers and footers on paginated output, eg. PDF. If the TXT version is also intended for printing (I only read them on a computer, but I digress), it should retain them.

Ronald Tse
Ribose Inc.

On Oct 27, 2020, at 9:31 AM, Ronald Tse <[email-masked]> wrote:

Ronald Tse
Ribose Inc.

  john

---

From: John C Klensin <[email-masked]>
Date: Mon, 26 Oct 2020 21:53:11 -0400

--On Tuesday, October 27, 2020 01:30 +0000 Ronald Tse
<[email-masked]> wrote:

> Thanks John for the clarification. There is some confusion to
> me whether the intention is just about the TXT output having
> page numbers, or for the PDF to also have the same page
> numbers, and whether to use page numbers inside cross
> references. There was a also discussion about a ToC and page
> numbers, but perhaps that was a diversion.
> 
> If the discussion is only about the ASCII output having page
> numbers, I have no objection because it is (nearly) purely
> cosmetic (in publication and in usage of the text, being done
> by xml2rfc).
> 
> If having page numbers will require the PDF output to also
> have page numbers, this inevitably leads to some shared spec
> between the TXT and PDF outputs on the topic of pagination,
> which is less ideal, but since I assume that is the work of
> xml2rfc, it's not a concern to us as tool maintainers.

Actually, I think you have it a bit backward.  The PDF has page
numbers today.  More to the point, PDF is (almost) inherently a
page image format so there is no way to escape pagination.  One
could decide to not number those pages in the footers, or one
could eliminate the headers and footers entirely, but the page
boundaries are going to be there regardless.

However, as long as a strict discipline is maintained that
references (within an RFC, between RFCs, and whatever we can
do/encourage about external references to RFCs use are to
section numbers and not pages (and there Brian and I agree)
_and_ as long as we don't allow sections to become so long that
people seek other mechanisms, then whether the page numbers in a
text format agree with those in the PDF format or not is largely
irrelevant.  That issue is centuries old: if I reference a
chapter by number in a book, that reference is typically stable
for different printings and formats (and often but not always
between editions).  But the page numbers often are not, so,
unless the people doing the layout are _really_ careful, using
the index from, e.g., a hardbound copy and trying to apply its
numbers to a paperback that uses different size type and page
layouts is, to use a technical term, just plain dumb.  And
external references that use page numbers need to be very
careful to specify exactly what form is being referred to.

> Adding page numbers to cross references can make reading
> confusing — since the cross references between the paginated
> and flowed versions will render these references differently.
> It's doable, but again this requirement ties the paginated
> versions (TXT and PDF) together for consistency.

And, again, this is why there has been a long-term prohibition
in the RFC Series against using page numbers in cross references.

> Of course, if the PDF output is simply an enhanced PDF-ized
> TXT version, these aren't really issues.

But two of several advantages of the contemporary (xml2rfc v3)
PDF version is that it can contain and render pictures easily
and that, if characters are used outside the ASCII repertoire,
they are rendered correctly as well.

best,
    john

---

From: Ronald Tse <[email-masked]>
Date: Tue, 27 Oct 2020 01:58:09 +0000

Thanks for the message. I do agree with most of your points, and may have had trouble expressing that.

In the last example you also described why the page numbers between PDF and TXT output will not sync:

It’s not easy synchronizing page numbers between two paginated outputs if rendered objects are allowed to have different dimensions (e.g. ASCII art in TXT vs SVG in PDF).

Ronald Tse
Ribose Inc.

---

From: Larry Masinter <[email-masked]>
Date: Mon, 26 Oct 2020 19:02:22 -0700

Ideally, from an RFC Future point of view, the Editor should aim for
support of work that would reduce the confusion surrounding the use of XML
+ SVG and a custom toolset that makes network engineers also become
document engineers.

I had hoped at one time that the WPACK working group (if it is one) might
solve the problem of opening up ebook by being reliable enough to compete
with PDF/A, and simple enough to author and render to displace XML and SVG
(and to extract text from well enough to make people with unmaintainable
downstream processing elements to not be upset.

It might be hard to fit all those requirements in, but it seems feasible
enough to hope for.
I say ebook because when i last looked, it was closer to the starting point
and in the right direction (I imagine because of 'book' requirements it has
a better choice of SVG allowed vocabulary). But do you agree with the end
point goal?

---

From: Brian E Carpenter <[email-masked]>
Date: Tue, 27 Oct 2020 19:20:17 +1300

> It’s not easy synchronizing page numbers between two paginated outputs if rendered objects are allowed to have different dimensions (e.g. ASCII art in TXT vs SVG in PDF).

Exactly. That's why any reference to page numbers is potentially misleading, because the page number depends on the presentation mechanism.

(For archaeologists, this issue came up in mid-2014 on the rfc-interest list and the relevant text in RFC7994 goes back to draft-flanagan-plaintext-03 in September 2014. Of course, we could relitigate this now that there is finally running code.)

    Brian

---

From: Brian E Carpenter <[email-masked]>
Date: Tue, 27 Oct 2020 19:35:54 +1300

Hi John,
On 27-Oct-20 13:49, John C Klensin wrote:
> and only then page numbering

And if you were to seek out my comments in June 2014, you'd see that
my view was that all I really wanted was pagination using Form Feed
characters.

Where it got tricky, IMHO, is when PDF was added in as a supported
presentation format, because PDF is intrinsically paginated (OK,
somebody may tell me that isn't strictly true, but it seems to be
true in practice). So whether the page numbers are printed or not,
they are *there* in PDF.

> (which I tend to use only for

If running code shows that there are problems with the current
format as defined in RFC7994, then we should certainly revisit
the claimed consensus. Unlike the canonical XML of an RFC, the
presentation format isn't frozen, afaik.

Regards
   Brian

---

From: Keith Drage <[email-masked]>
Date: Tue, 27 Oct 2020 11:33:50 +0000

I do agree that referencing by section numbering is the appropriate method.

However, as you say, it gets difficult with overly long sections, and 
this is something on which no guidance or checking is currently given. 
Perhaps it should be?

Further there are difficulties with section references if you allow text 
between x.y.z and x.y.z.1. Does a reference to x.y.z mean the entirety 
of the text including x.y.z.1, or merely the text before x.y.z. Other 
organisations restrict such usage in order to make section references 
unambiguous.

I also note people are referring to the XML version as the definitive 
version, but surely the section numbers do not appear until the 
presentation version is created?

Keith

---

From: Carsten Bormann <[email-masked]>
Date: Tue, 27 Oct 2020 14:15:17 +0100

> I do agree that referencing by section numbering is the appropriate method.

Yes.

> However, as you say, it gets difficult with overly long sections, and this is something on which no guidance or checking is currently given. Perhaps it should be?

“Overly long sections” are by definition of “overly” not a good idea.
The question when a section is “overly” long is the interesting one then — there certainly is no algorithm that is going to tell you the answer.

> Further there are difficulties with section references if you allow text between x.y.z and x.y.z.1. Does a reference to x.y.z mean the entirety of the text including x.y.z.1, or merely the text before x.y.z. Other organisations restrict such usage in order to make section references unambiguous.

»Please see the introduction of Section 2 in RFC 8610 for a definition of the terms “vector”, “record”, “table”, and “struct”.«

Works for me (except that I can’t put in the right quotes).

> I also note people are referring to the XML version as the definitive version, but surely the section numbers do not appear until the presentation version is created?

There is no “the XML version”.  There is the author-side XML (often created with a tool like kramdown-rfc).  This is edited, then run through a “prep-tool” which does all the formatting that is not rendition-specific, such as assigning section numbers (as well as reference anchors etc.), putting in boilerplate etc.  The result is the “canonical” XML, which is certainly no longer editable.  Then the rendition-specific formatters generate HTML, TXT, PDF from that.

Many of the problems we have with RFCXMLv3 stem from confusing the editable author-side XML form with the canonical, non-editable publishing form.  Both are expressed in XML, and they do use much of the same vocabulary, but they are *not* the same formats.

Grüße, Carsten

---

From: Paul Kyzivat <[email-masked]>
Date: Tue, 27 Oct 2020 11:22:46 -0400

+1

Sections that contain subsections are commonly long. And not only can 
x.y.z contain text prior to x.y.z.1, it can also contain text after 
subsections that is not part of a subsection.

Perhaps the solution is paragraph numbers. But I don't know how you 
would include them in the txt format.

	Thanks,
	Paul

---

From: Toerless Eckert <[email-masked]>
Date: Tue, 27 Oct 2020 17:03:01 +0100

Whot! Ae you saying IETF has no comprehensive and detailled written down
citation guidelines ? How could we have survived for so long without it ?
No proud academic publishing house can live without one!  ;-))

On Tue, Oct 27, 2020 at 11:22:46AM -0400, Paul Kyzivat wrote:
> Sections that contain subsections are commonly long. And not only can x.y.z
> contain text prior to x.y.z.1, it can also contain text after subsections
> that is not part of a subsection.
> 
> Perhaps the solution is paragraph numbers. But I don't know how you would
> include them in the txt format.
> 
> 	Thanks,
> 	Paul
> 
> > > > confusing ??? since the cross references between the paginated

-- 
---
[email-masked]

---

From: "HANSEN, TONY L" <[email-masked]>
Date: Tue, 27 Oct 2020 18:25:55 +0000

Typical placement for paragraph numbers is within the right margin.

RFC 7995 (RFC PDF format) has this recommendation:

   Recommendation:  When the XML "editing=yes" option has been chosen,
      show paragraph numbers in the right margin, typeset in a way so as
      to be unobtrusive.  (The right margin instead of the left margin
      prevents the paragraph numbers from being confused with the
      section numbers.)  If possible, the paragraph numbers should be
      coded in such a way that they do not interfere with screen
      readers.

RFC 7994 (RFC text format) has this to say about paragraph numbering:

   Where practical, the original guidance for the structure of a
   plain-text RFC has been kept (e.g., with line lengths, with lines
   per page [INS2AUTH]).  Other publication formats, such as HTML and
   PDF, will include additional features that will not be present in the
   plain text (e.g., paragraph numbering, typographical emphasis).

   The details described in this document are expected to change based
   on experience gained in implementing the new publication toolsets.

The HTML format generates paragraph numbering with pilcrows. However, you have to hover over the pilcrows to see those numbers.

Personally, I would support extending support for paragraph numbers to the text format as well, possibly even enabled using the same "editing=yes" option.

Note: I haven't tried this option to see if it actually works with the PDF format.

	Tony Hansen

On 10/27/20, 11:23 AM, "WGChairs on behalf of Paul Kyzivat" <[email-masked] on behalf of [email-masked]> wrote:

    +1

    	Thanks,
    	Paul

---

From: Henrik Levkowetz <[email-masked]>
Date: Tue, 27 Oct 2020 19:31:44 +0100

Hi Tony,

On 2020-10-27 19:25, HANSEN, TONY L wrote:
> The HTML format generates paragraph numbering with pilcrows. However,
> you have to hover over the pilcrows to see those numbers.
> 
> Personally, I would support extending support for paragraph numbers
> to the text format as well, possibly even enabled using the same
> "editing=yes" option.
> 

It doesn't.  I'm afraid the premise of the xml2rfc SoW, that the PDF version
should be generated from the HTML version, resulted in me loosing track of
that recommendation in 7995.

It might be possible to use a different CSS style for the PDF which turned the
pilcrows into right-hand paragraph numbers, but I suspect that a bit more would
be required than a CSS tweak.

Best regards,

	Henrik

---

From: "HANSEN, TONY L" <[email-masked]>
Date: Tue, 27 Oct 2020 18:53:48 +0000

I did some quick poking at the HTML&CSS in a recent HTML-formatted RFC. 

The paragraph pilcrows are represented as an anchor

	<a href="#section-1.2-1.2" class="pilcrow">¶</a>

This means that the text of the section number itself is not present within the output. You would need to have something this instead to get the data:

	<a href="#section-1.2-1.2" class="pilcrow"><span class="pilcrow-text">1.2-1.2</span>¶</a>

and then the CSS can be adjusted to display or not display that text as appropriate.

Just some thoughts.

	Tony

On 10/27/20, 2:32 PM, "Henrik Levkowetz" <[email-masked]> wrote:

    Hi Tony,

    Best regards,

    	Henrik

---

From: Paul Kyzivat <[email-masked]>
Date: Tue, 27 Oct 2020 14:54:11 -0400

If paragraph numbering were added to the txt format, and didn't break 
the diff tools) IMO it would solve the problem of making references into 
long sections.

Note that there is already sometimes a problem in going from the side by 
side diff format to the corresponding place in the full document, 
regardless of format. Paragraph numbers would help solve that too.

	Thanks,
	Paul

---

From: Jeffrey Haas <[email-masked]>
Date: Tue, 27 Oct 2020 15:38:08 -0400

Ben,

> Like https://www.rfc-editor.org/rfc/rfc8815.html#section-3.1-5 ?

You seem to have missed the paragraph 5 symbol I added.

I regularly use the html anchor notation above. :-)

If it wasn't for the fact that our XML is of highly variable quality
I'd simply note that XPath provides sufficient addressability.  But it's
less easy to interact with it in plain text emails and still awkward in
richer formats.

/section[@title='Security Considerations']/t[5]  as an example of the fifth
text block of the security considerations section.

-- Jeff

---

From: Henrik Levkowetz <[email-masked]>
Date: Tue, 27 Oct 2020 20:27:23 +0100

Hi Tony,

On 2020-10-27 19:53, HANSEN, TONY L wrote:
> This means that the text of the section number itself is not present
> within the output.

Yes, this was the reason I thought a bit more work would be needed :-)

> You would need to have something this instead to
> get the data:
> 

Right.

Best,
	Henrik

---

From: Toerless Eckert <[email-masked]>
Date: Tue, 27 Oct 2020 20:27:33 +0100

Somehow literature has survived hundreds of years with references to paraprahs
without having printed paragraph numbers. Always hard to extrapolate from what
one has known and used forever, but i would bet that paragraph numbrers would
only be seen as an improvement if they where made extremely unintrusive
(tiny font, positioned outside of normal text space).

In a lot of formal text where you know individual points will be
cited, one should try upfront to givem them explicit number. E.g.:
section 1.2.4, Q.4, whee you then have e.g.: a list of Q)uestions or
the like.

Cheers
    Toerless

On Tue, Oct 27, 2020 at 02:54:11PM -0400, Paul Kyzivat wrote:
> If paragraph numbering were added to the txt format, and didn't break the
> diff tools) IMO it would solve the problem of making references into long
> sections.
> 
> side diff format to the corresponding place in the full document, regardless
> of format. Paragraph numbers would help solve that too.
> 
> 	Thanks,
> 	Paul
> 
> > ???On 10/27/20, 11:23 AM, "WGChairs on behalf of Paul Kyzivat" <[email-masked] on behalf of [email-masked]> wrote:
> > 

-- 
---
[email-masked]

---

From: Benjamin Kaduk <[email-masked]>
Date: Tue, 27 Oct 2020 12:32:40 -0700

Hi Jeff,

> I regularly use the html anchor notation above. :-)

I am not sure which of us is confused -- the link I provided is directly to
the fifth paragraph of the section (the "-5" suffix effectuates that
functionality).  So, if I assume that you knew that, I'm left with the
conclusion that the "paragraph" part of the reference/link needs to be more
prominent to someone that does not understand the URL fragment's structure.
Which is perhaps a valid position to hold, but I'm not entirely confident
if that is the position you are holding.

> If it wasn't for the fact that our XML is of highly variable quality

Indeed.  And there does not seem to be much appetite for fixing that -- I
had asked about even something as simple as consistent indentation for
nested XML elements and got a response along the lines of "if authors care,
they can put in the work to make the XML look pretty".  Which is
unsatisfying to me, but I apparently failed to make a persuasive case for
it.

-Ben

---

From: Jeffrey Haas <[email-masked]>
Date: Tue, 27 Oct 2020 15:42:52 -0400

Ben,

> On Oct 27, 2020, at 3:32 PM, Benjamin Kaduk <[email-masked]> wrote:
> 
> functionality).  

No, I missed the distinction of the -5 vs. .5.  If so, certainly my primary use cases for such citations are covered.

Is there a guide that has any other such things I may have missed?

> unsatisfying to me, but I apparently failed to make a persuasive case for

This is a battle I'd have no stomach for.  Much like code indentation, it's a fight that only generates sore losers.  And much like code indentation, if you care - run it through your favorite indenter.  

That said, a tool that can generate such citations might still be of use if we continue further down this hole.  But I think if we have the ability to generate paragraph and section citations, we're probably covering the majority of the common use cases.

-- Jeff

---

From: Benjamin Kaduk <[email-masked]>
Date: Tue, 27 Oct 2020 12:49:39 -0700

> No, I missed the distinction of the -5 vs. .5.  If so, certainly my primary use cases for such citations are covered.

Ah, happy to help.

> Is there a guide that has any other such things I may have missed?

I don't remember a specific guide; I think I have just picked up on some
things by exploring and clicking on random stuff.  (Well, and perhaps
spending way too much time on the datatracker.)  But it's possible that one
of Heather's plenary talks had a summary of new and exciting features and
I've just forgotten about it.

> That said, a tool that can generate such citations might still be of use if we continue further down this hole.  But I think if we have the ability to generate paragraph and section citations, we'r…

I suspect you are correct.

Thanks,

Ben

---

From: "HANSEN, TONY L" <[email-masked]>
Date: Tue, 27 Oct 2020 19:57:45 +0000

Another quick test. I changed each pilcrow in the HTML format

like this:
<a href="#section-2-2" class="pilcrow">¶</a>
to this:
<a href="#section- 2-2" class="pilcrow"><span class="pilcrow-text">2-2</span>¶</a>

and added this CSS:

a.pilcrow > .pilcrow-text {
  visibility: visible;
  float: right;
  font-size: xx-small;
}

and a small, unintrusive section number (with paragraph) shows up on the bottom right of each paragraph. I also think it's very obvious that the numbers are not part of the text.

It's almost what I was thinking of when I helped write the text for RFC 7995. :) 

I'd rather have it in the right margin, but it was just a VERY quick test.

	Tony

On 10/27/20, 3:27 PM, "Toerless Eckert" <[email-masked]> wrote:

    Cheers
        Toerless

    -- 
    ---
    [email-masked]

---

From: Andrew Campling <[email-masked]>
Date: Tue, 27 Oct 2020 22:09:30 +0000

As general comment on the topic, I have to say that I'd never thought of either page numbers nor indeed pagination to be remotely controversial topics.  Clearly this debate is proving otherwise!  

For those of us that might prefer to read printed documents, especially documents of more than a few pages in length, page numbers are particularly help to ensure that the order of the documents does not become jumbled.  Those that appear to be taking a position that pagination is obsolete might want to reflect on the importance of making IETF materials readily accessible to a wider audience, many of whom may be accustomed to printable documents with tables of contents inclusive of page numbers, pages with footers incorporating page numbers etc.  

Andrew

-----Original Message-----
From: Carsten Bormann <[email-masked]> 
Sent: 26 October 2020 21:33
To: Brian E Carpenter <[email-masked]>
Cc: Toerless Eckert <[email-masked]>; [email-masked]; [email-masked]; [email-masked]; [email-masked]; [email-masked]
Subject: Re: Poll: RFCs with page numbers (pretty please) ?

Grüße, Carsten

---

From: Mark Andrews <[email-masked]>
Date: Wed, 28 Oct 2020 10:13:49 +1100

There are several over lapping issues here.  There is PFD for different
media involved here.  Screen really is different to print.  The current
PDF is laid out for screen, the same as the HTML version is laid out for
screen.  There are internal linkages in the TOC to get to the right section
in the TOC without page numbers.  That is fine for screen.

PDF for print the TOC needs page numbers to optimally navigate to the
correct page.  Navigating by section on page headers, footers is
sub-optimal.

There really is no reason more forms can’t be produced.  Disk space is
cheap as is creating links to multiple forms [PDF screen] [PDF A4] [PDF
Letter].

For referencing we actually should consider adding paragraph numbers as
that should eliminate the perceived need for page numbers by providing
finer grained referencing.

e.g. Section [Number] Title [Paragraph <number>]

If people say page X, just push back with “section (number and title) and
paragraph please”.  People do learn.

Mark
-- 
Mark Andrews, ISC
1 Seymour St., Dundas Valley, NSW 2117, Australia
PHONE: +61 2 9871 4742              INTERNET: [email-masked]

---

From: Paul Kyzivat <[email-masked]>
Date: Wed, 28 Oct 2020 10:50:06 -0400

> section 1.2.4, Q.4, whee you then have e.g.: a list of Q)uestions or

Unfortunately, in the real world, it is often necessary to reference 
parts of the document that the author didn't anticipate might need to be 
referenced. (E.g., when a reviewer is pointing out a spot that needs a fix.)

	Thanks,
	Paul