Subject: FIXED: Poll: RFCs with page numbers (pretty please) ? (was: Re: John/rsoc: Re: Page numbers in RFCs questions / preferences)

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

[Sorry, resenting with poll URL instead of result URL]

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/poll3188562x294441dA-98

Results here:

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

Cheers
    toerless

On Mon, Oct 26, 2020 at 01:35:43PM -0400, John R. Levine wrote:
> > 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 ?
> 
> 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: Phillip Hallam-Baker <[email-masked]>
Date: Tue, 27 Oct 2020 18:50:10 -0400

Whooaah there...

What is the status of this poll? I am all for moving from the subjective
consensus model in which certain parties get a veto because their opinions
are considered weightier than the rest of us. Objective measures of
consensus are good. But is this an official poll? What does it mean?

But of course, as John K. pointed out, this is not actually an IETF
process. Only of course it is in every meaningful sense except insofar as
IETF rules of the road apply.

Page numbers is not the hill I would choose to die on here. They don't work
in HTML and the whole point of this process is that the TXT documents
reflect very badly on the IETF as an organization. It spoke of an
organization that is stuck in the 1960s ranting on about how vinyl is
better than CD.

There are serious issues with the new format. Not least the fact that SVG
is not actually supported. The supported format is SVG/Tiny which is an
obsolete format originally proposed back in the WAP days as a means of
crippling the spec to fit the capabilities of the devices back before Steve
Jobs showed us an iPhone for the first time. There are no tools that
produce SVG/Tiny, not even GOAT - I had to modify the source code to comply.

I don't mind retooling to support an improved specification. Having to
retool to support an obsolete one is nonsense.

Anyway, how about as a compromise, authors can opt to suppress generation
of the TXT version so that the page number issue doesn't come up at all?

---

From: David Noveck <[email-masked]>
Date: Tue, 27 Oct 2020 19:36:24 -0400

The issue comes up with PDF files.  Currently, you get page numbers
together with a TOC that has no page numbers.  I'm OK with a no-TXT option
but I have a problem with a not-usefully-printable option for RFCs.

On Tue, Oct 27, 2020, 6:51 PM Phillip Hallam-Baker <[email-masked]>
wrote:

> Page numbers is not the hill I would choose to die on here. They don't
> work in HTML and the whole point of this process is that the TXT documents

---

From: "Jim Fenton" <[email-masked]>
Date: Tue, 27 Oct 2020 16:57:38 -0700

[Yikes, this discussion is getting crossposted everywhere, it seems. 
I’ll keep it brief]

> but I have a problem with a not-usefully-printable option for RFCs.

When RFC 8689 was about to be published about a year ago, I had a chat 
with the staff at the RFC Editor table in Singapore about this. It 
seemed a little strange to have a table of contents without page 
numbers, but if some people are reading HTML versions, PDF versions, and 
TXT versions, the pagination is different anyway (and nonexistent for 
HTML) so trying to reference something by page number is problematic. 
References should be to section numbers, and if sections are so big that 
it’s hard to find some text there, the author should really think 
about structuring the document with smaller subsections.

What does seem strange (and maybe it has changed in the past year) is 
that the plain text and PDF versions have tables of contents, and the 
html version does not. I would like for the html version to have a table 
of contents with links to anchors for each section.

-Jim

---

From: "Andrew G. Malis" <[email-masked]>
Date: Wed, 28 Oct 2020 00:49:28 -0400

Jim,

Open any recent HTML RFC (such as
https://www.rfc-editor.org/rfc/rfc8905.html) and take a look at the frame
to the right of the text (on a phone browser, the TOC is a button at the
top of the screen).

Cheers,
Andy

---

From: "Jim Fenton" <[email-masked]>
Date: Tue, 27 Oct 2020 22:47:38 -0700

> to the right of the text (on a phone browser, the TOC is a button at 

Thanks, John and Andy, for pointing that out. That’s what I get for 
(1) using a narrow browser window and (2) looking for the TOC in exactly 
the same place, so I didn’t see the Table of Contents thing in the 
upper right corner.

-Jim

>>>> There are serious issues with the new format. Not least the fact 
>>>> that
>>>> SVG
>>>> is not actually supported. The supported format is SVG/Tiny which 
>>>> is
>>>> an
>>>> crippling the spec to fit the capabilities of the devices back 
>>>> before
>>>> Steve
>>>> produce SVG/Tiny, not even GOAT - I had to modify the source code 
>>>> to
>>>> comply.
>>>>

---

From: David Noveck <[email-masked]>
Date: Wed, 28 Oct 2020 08:03:45 -0400

> HTML) so trying to reference something by page number is problematic.

True but the function of page number in a TOC is not to allow references
using page numbers.  That is a bad practice and has always been.

The function is of page numbers in a TOC is to enable the use *of printed *
*documents*.   In any printed document (e.g. books), one has to go from
section number to the text in question, and the TOC, with page numbers,
allows you to do this.  If the TOC doesn't have page numbers, you are
stuck doing an annoying binary search.   This is the reason that all books
are published with TOCs containing page numbers.

> about structuring the document with smaller subsections.

True.

> of contents with links to anchors for each section.

Seems reasonable.

---

From: Robert Sparks <[email-masked]>
Date: Wed, 28 Oct 2020 10:27:35 -0500

> [Yikes, this discussion is getting crossposted everywhere, it seems. 
Any chance we can cut down the crossposting and move this conversation 
to one place? There are already several examples of messages that only 
occur on one of the lists, so unless everyone reads all of the lists 
from all of the crossposts, there'll be missed comments.

I'd suggest rfc-i?

RjS

---

From: Carsten Bormann <[email-masked]>
Date: Wed, 28 Oct 2020 16:31:48 +0100

One little problem with executing on this is that the IETF mailing list software seems to swallow Reply-To.  So there is no way to move comments to a message to a specific mailing list.

Attempts to do such a move without the aid of reply-to usually don’t work (they just add more fragmentation to the discussion).

Grüße, Carsten

---

From: Robert Sparks <[email-masked]>
Date: Wed, 28 Oct 2020 10:49:47 -0500

I haven't run into that. I'm going to try to redirect this particular 
subthread to tools-discuss, with a Reply-To, and I'll go looking for 
where such stripping might take place.

RjS

---

From: "Derek Atkins" <[email-masked]>
Date: Wed, 28 Oct 2020 12:00:37 -0400

My received version has this header:

 Reply-To: "[email-masked]" <[email-masked]>

I did "Reply-All"

-derek

On Wed, October 28, 2020 11:49 am, Robert Sparks wrote:
>> One little problem with executing on this is that the IETF mailing list
>> software seems to swallow Reply-To.  So there is no way to move comments
>> to a message to a specific mailing list.
>>
>> Attempts to do such a move without the aid of reply-to usually don’t
>> work (they just add more fragmentation to the discussion).
>>
>> Grüße, Carsten
>>
>
>

-- 
       Derek Atkins                 617-623-3745
       [email-masked]             www.ihtfp.com
       Computer and Internet Security Consultant

---

From: Toerless Eckert <[email-masked]>
Date: Wed, 28 Oct 2020 17:40:53 +0100

On Tue, Oct 27, 2020 at 04:57:38PM -0700, Jim Fenton wrote:
> but if some
> people are reading HTML versions, PDF versions, and TXT versions, the
> pagination is different anyway (and nonexistent for HTML) so trying to
> reference something by page number is problematic.

The thread is getting long so it is hard to not miss things said earlier, so
let me repeat: My proposal was to add on IETF pages renderings with page
numbers (not to remove any of the non-paginated renderings), AND make sure
the pagination is consistent across them.

References to pages number where and are always problematic, we already
have rules in IETF/RFC-editor forther not to alow them in our own work
product, but we can not prohibit others to do them, but most scientific
yournal formatting guidelines AFAIK also prohibit them. Besides, if someone
really wants to use it, they can do so today, pointing to the IETF provided
PDF rendering, which has page numbers, but (IMHO silly) no pages in the
TOC.

> References should be to
> section numbers, and if sections are so big that it???s hard to find some
> text there, the author should really think about structuring the document
> with smaller subsections.

Nobody disagrees, we just got a dogmatic division whether those arguments
can be reasonably used as an argument for IETF not to provide renderings
with pagination (also in TOC).

> What does seem strange (and maybe it has changed in the past year) is that
> the plain text and PDF versions have tables of contents, and the html
> version does not. I would like for the html version to have a table of
> contents with links to anchors for each section.

The native HTML version, e.g.: https://www.rfc-editor.org/rfc/rfc8815.html
seems to have the TOC as a HTML object that is now rendered independenlty
by browsers from the text. On my browser there is a menu button on the
top right that you can click on whereever you are in the text.

cheers
    Toerless
> > > that SVG
> > > before Steve
> _______________________________________________
> rfc-interest mailing list
> [email-masked]
> https://www.rfc-editor.org/mailman/listinfo/rfc-interest

-- 
---
[email-masked]

---

From: John C Klensin <[email-masked]>
Date: Wed, 28 Oct 2020 15:19:43 -0400

--On Wednesday, October 28, 2020 17:40 +0100 Toerless Eckert
<[email-masked]> wrote:

>> people are reading HTML versions, PDF versions, and TXT
>> versions, the pagination is different anyway (and nonexistent
>> for HTML) so trying to reference something by page number is
>> problematic.
> 
> The thread is getting long so it is hard to not miss things
> said earlier, so let me repeat: My proposal was to add on IETF
> pages renderings with page numbers (not to remove any of the
> non-paginated renderings), AND make sure the pagination is
> consistent across them.

And, also to repeat, the expectation of consistent numbering (or
consistent pagination) across different renderings is
impractical and unwise.   As a specific and concrete example,
consider the relationship between a PDF document that contains
representations of several graphic images and the associated
text version.  The only way I can think of to make the
pagination (and numbering) consistent between them would be to
leave large areas of white space in the text.   That could be
done, but would make the text file longer and less useful.

AFAICT, the arguments against page numbers in the text files are:

(1) They are not allowed to be used in crossreferences within
the document, therefore they are utterly useless.
   Response: See many comments that contradict "utterly useless"
in this set of threads.  And we've had that rule for decades and
the RFC Editor and then the RFC Production Center enforce it.

(2) They are not allowed to be used in references within the RFC
Series to parts of other RFCs.
   Response: We've had that rule for decades and the RFC Editor
and then the RFC Production Center enforce it.

(3) We don't want them used by third parties or their documents
to references parts of RFCs.
   Response: As you point out, many other publications already
prohibit page number references to identify particular material
and do so for much the same reason we have.  But, as long as we
paginate documents, nothing we do is going to prevent someone
who insists on page numbers from counting and using them.  And,
as long as we have at least one paginated form (numbered or not)
that will be possible.  However, page numbers that are
inconsistent among renderings actually reinforces the "don't use
page numbers in references" rule because it is then clear that
they are too unstable to make good references, so maybe we
should be promoting their inclusion.

(4) Page numbers in plain text documents are so inherently evil
and/or the risk to horrible damage being done by anyone using
them so high that we need to suppress them and headers and
footers (and perhaps even pagination) as well.  That evilness
and risk of damage is acceptable in the PDF form, just not in
the plain-text one.
    Response: In fairness, no one whose comments I have read has
actually said/ claimed that, but it seems to me that it is were
several arguments against page identification (numbered or not)
seem to be heading.  YMMD.

By contrast, there are, it seems to me only two reasons for
retaining the page numbers (and pagination, headers, and
footers) in the plain text rendering:

 (a) They are traditional in the RFC Series and
	preserving that rendering in a format consistent with a
	significant fraction of the first 7000 or so of RFCs
	would seem to have some advantages.  Of course, no one
	is forced to use them, any more than anyone has been
	forced to use the standard text form since HTML and PDF
	forms became generally available years ago.
	
 (b) Of the fraction of the community that still prefers
	to use the plain text form (at least sometimes) and for
	one purpose or another, some fraction of them prefer to
	have the headers and footers and many of those prefer,
	or are not disturbed by, the page numbers.  Because many
	of the arguments against page numbers seem to be coming
	from people who do not find the plain text form useful,
	probably we should pay attention to that preference ...
	or start making the case for getting rid of the plain
	text form entirely, perhaps because those who prefer it
	(for any purpose) need to be persuaded to join the
	modern era and get with the programs.

Probably I'm missing something important but, if the above
analysis is even nearly correct, I don't understand why we are
still having this conversation.

    john

---

From: Benjamin Kaduk <[email-masked]>
Date: Wed, 28 Oct 2020 17:55:19 -0700

Hi Mark,

I think we are solidly into "your way is not my way but your way is okay"
territory here.  Just because you like the clickable-link ToC and it works
great for you does not meen that everyone else has to prefer it, too.
If John is happy with "dumb" text, what difference does it make to you?

-Ben

On Thu, Oct 29, 2020 at 11:30:53AM +1100, Mark Andrews wrote:
> John, with electronic versions the ToC *works* for PDF and HTML.
> 
> For dead trees versions the ToC does not work efficiently regardless
> of the original form.  Binary searches through a stack of pages is
> not efficient.  The plain text version also has this issue in the
> electronic version.
> 
> The point of a ToC is to have list of the sections *and* to be able
> to get to the relevant section easily.  When you can’t click on a link
> you need page numbers especially as we have unnumbered sections.
> 
> One shouldn’t have to memorise the section names *and* order in the ToC
> to find something in a dead tree version.

---

From: Mark Andrews <[email-masked]>
Date: Thu, 29 Oct 2020 12:41:50 +1100

I’m actually arguing *for* numbers in the ToC of the PDF version
because I know it gets turned into dead trees.  If that helps those
that want/need to used page number to navigate electronic versions
that is fine.

Page numbers in the HTML version don’t make sense as there is only
one page.  We don’t currently produce a multi-page HTML version and
there is no discussion of what a multi-page version would look like.
Navigation in HTML is intrinsically by following links.

The TXT version needs to go back to the old format for page numbers
to be useful.

At the I-D stage page numbers are useful because people send diffs
and you need to context to get to the right place in the .xml.

Mark

> On 29 Oct 2020, at 11:55, Benjamin Kaduk <[email-masked]> wrote:
> 
> Hi Mark,
> 

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

---

From: Julian Reschke <[email-masked]>
Date: Thu, 29 Oct 2020 11:04:16 +0100

> one page.  We don’t currently produce a multi-page HTML version and

Hmm, no. That is true when you read it in the browser, but is not the
case once you print it.

> Navigation in HTML is intrinsically by following links.

Unless it's on paper.

> The TXT version needs to go back to the old format for page numbers

Why? The only reason appears to be printing, for which the PDF seems to
be superior.

> and you need to context to get to the right place in the .xml.

How do page numbers help with the XML? Aren't section and paragraph
numbers much better for that?

Best regards, Julian

---

From: Keith Moore <[email-masked]>
Date: Thu, 29 Oct 2020 10:48:17 -0400

> numbers much better for that?

Given that none of section, paragraph, or page numbers appear in the 
XML, I don't see how any of them helps with that problem. But it is a 
real problem.

(IMO, XML is a horrible format for document authoring/editing. It 
optimizes for all of the wrong things and imposes a considerable burden 
on writing and maintaining drafts, especially for newcomers.)

Keith

---

From: Julian Reschke <[email-masked]>
Date: Thu, 29 Oct 2020 16:00:03 +0100

Am 29.10.2020 um 15:48 schrieb Keith Moore:
> ...

I never perceived that as a big problem.

Of course it's possible to run "xml2rfc --preptool" to generate an XML
document with section numbers inlined (see
<https://greenbytes.de/tech/webdav/rfc7998.html#part-numbering>), but of
course you wouldn't want to *edit* that.

At the end of the day, it's a choice of automatic and consistent section
numbering (what we have now), or having the authors do the numbering. I
prefer the former.

Best regards, Julian

---

From: Warren Kumari <[email-masked]>
Date: Wed, 28 Oct 2020 16:01:21 -0400

On Wed, Oct 28, 2020 at 3:20 PM John C Klensin <[email-masked]> wrote:
[ Massive SNIP ]

>         modern era and get with the programs.

I realize you aren't actually pushing this point, but this seemed like
the clearest expression of one of my concerns with this entire thread,
and so I'm choosing to hook onto it...

Full disclosure:
I'm one of the people who both believes that there is value in the
"traditional" aspect of the series, and the fact that RFC17 looks the
same as RFC42, which looks the same as RFC4217, which looks the same
as RFC8217 is a good thing.
I also like and use the text formats - I sometimes print out RFCS, I
have tooling which greps through documents for things, I generate
statistics, etc. It's a personal preference.

I've gotten 2 distinctly negative impressions from this thread:
1: "You need to join the modern era and get with the program" sums it
up well. HTML / flowed output is the new world, liking the text format
is bad and you should feel bad[0].

2: There were extensive discussions around the new format, and the
lack of page numbers was mentioned. You were not paying attention when
this happened. Not only do you lose any right to discuss this, but you
were lazy and should feel bad.

I'll happily admit that I didn't follow the new format discussions
closely, and that I do read a lot of things (including books) in
formats which don't have clear "pages", but the thing that is worrying
me is the underlying "and you should feel bad" tone in much of this
discussion.

Perhaps I'm being overly sensitive (or that I just miss seeing IETFers
in person), but it feels to me like the "and you should feel bad"
subtext seems to be cropping up more and more. We used to generally
assume that someone who had a bad or silly idea just had a bad or
silly *idea* - but it now we often seem to be implying that the person
is bad or silly.

Other than being able to meet in person again, I'm not sure how we get
back to where our base assumptions are that other IETFers are friends,
and are also trying to do the right thing...

W
[0]: Meme reminder: https://www.youtube.com/watch?v=jG2KMkQLZmI

-- 
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: Brian E Carpenter <[email-masked]>
Date: Thu, 29 Oct 2020 10:56:17 +1300

One more comment with all these CCs and then I will try to shut up.
On 29-Oct-20 09:01, Warren Kumari wrote:
...
> me is the underlying "and you should feel bad" tone in much of this

Agreed. Yes, there was active discussion of this issue 6 years ago,
but in a vacuum (no running code). Now we have running code, revisiting
the issue in the light of experience is the right thing to do. Nothing
to feel bad about. I hope none of my messages made anyone feel bad.

However, we don't currently have the organizational framework needed
for this discussion. There is active discussion of the organizational
issue right now, on [email-masked]. Please join.

   Brian

---

From: Mark Andrews <[email-masked]>
Date: Thu, 29 Oct 2020 11:30:53 +1100

Mark

> On 29 Oct 2020, at 06:19, John C Klensin <[email-masked]> wrote:
> 
> 
>

---

From: Larry Masinter <[email-masked]>
Date: Thu, 29 Oct 2020 10:02:16 -0700

If you're concerned about people seeing different pagination depending on
format, you could change the page numbers at the bottom of .txt pages to be

 Author                                  Shortname
                           docname.txt[Page 2]

and the numbers at the bottom of pages in PDF similarly to have
    docname.pdf[Page 2]

where docname is either rfcNNNN or draft-ietf-wgname-NN

it's better if the page identifier at the bottom of the page identifies the
context anyway.
Put it outside the [Page NN] brackets for backward compatibility :)

-- 
--
https://LarryMasinter.net <http://larry.masinter.net>

---

From: Keith Moore <[email-masked]>
Date: Thu, 29 Oct 2020 13:05:32 -0400

> course you wouldn't want to *edit* that.

But then you actually have to install xml2rfc and keep it up to date.   
I tried that once but gave up because it was such a hassle.

Keith

---

From: Julian Reschke <[email-masked]>
Date: Thu, 29 Oct 2020 18:14:18 +0100

Am 29.10.2020 um 18:05 schrieb Keith Moore:
> But then you actually have to install xml2rfc and keep it up to date. I
> tried that once but gave up because it was such a hassle.

"pip install --upgrade ..." (update?) has worked for me for years.

Or are you referring to the old TCL script days?

Best regards, Julian

---

From: Keith Moore <[email-masked]>
Date: Thu, 29 Oct 2020 13:22:55 -0400

On 10/29/20 1:14 PM, Julian Reschke wrote:

>> tried that once but gave up because it was such a hassle. ls
>

Is this documented anywhere prominently?   I see no mention of this on:

  * https://ietf.org/standards/ids/
  * https://xml2rfc.tools.ietf.org/
  * https://xml2rfc.tools.ietf.org/xml2rfcFAQ.html

How many places should someone have to look to find this?  It's not as 
if "pip" is the obvious place to look, especially to someone who doesn't 
use python regularly.   And even if one finds some version of this tool 
somewhere, how is one to know which is the current version?

---

From: Julian Reschke <[email-masked]>
Date: Thu, 29 Oct 2020 18:36:11 +0100

> somewhere, how is one to know which is the current version?

Third google hit is ... <https://pypi.org/project/xml2rfc/>.

I *do* agree that this should be linked from one of the pages you mentioned.

Best regards, Julian

---

From: Donald Eastlake <[email-masked]>
Date: Thu, 29 Oct 2020 15:10:16 -0400

I endorse Warren's comments. I use the text versions heavily and I believe
that one of the formats available should preserve the traditional RFC
format.

-- All formats should have a Tables of Content. (Well, I guess I would
agree that if an RFC had less than two sections, it wouldn't need a ToC,
but I don't see how that is possible with the current requirements.)

-- If a format is paginated, it should have page numbers. (A warning could
be added something like "Warning: The page numbers in this document depend
on its presentation format and will differ in other renditions.")

-- If a format has a ToC and pages numbers, those page numbers should
appear in the ToC and just before the ToC would be a good place for the
warning suggested above.

Thanks,
Donald
===============================
 Donald E. Eastlake 3rd   +1-508-333-2270 (cell)
 2386 Panoramic Circle, Apopka, FL 32703 USA
 [email-masked]

---

From: Christian Huitema <[email-masked]>
Date: Thu, 29 Oct 2020 12:32:39 -0700

I think I agree with Warren and Donald. The primary purpose of our
specifications is to provide guidance to people implementing and
deploying protocols. This requires that specifications are easy to read,
whether as text, or HTML, or PDF. And "ease of reading" requires a table
of content, with page numbers if the presentation format uses pages.

I understand the argument that people might them misuse these page
numbers, as in "page 16 said that you MUST do this." That could be bad,
especially if that argument happens during some kind of legal dispute.
But let's not lose sight of the main goal of the series, which is NOT
"solving legal dispute". If it were, the RFC ought to be formatted much
like legal documents, numbering not just every section but every
paragraph as well. We won't do that, because that would harm our primary
objective, easy to access and read by implementers and users. Instead of
solving the "legal reference" problem by making documents harder to
read, we need to find another way. Maybe point to a reference rendering
of the official XML text, or something like that.

-- Christian Huitema

On 10/29/2020 12:10 PM, Donald Eastlake wrote:
> I endorse Warren's comments. I use the text versions heavily and I
> believe that one of the formats available should preserve the
> traditional RFC format.
>
> agree that if an RFC had less than two sections, it wouldn't need a
> ToC, but I don't see how that is possible with the current requirements.)
>
> -- If a format is paginated, it should have page numbers. (A warning
> could be added something like "Warning: The page numbers in this
> document depend on its presentation format and will differ in other
> renditions.")
>
> appear in the ToC and just before the ToC would be a good place for
> the warning suggested above.
>
> Thanks,
> Donald
>  [email-masked] <mailto:[email-masked]>
>
>
> On Wed, Oct 28, 2020 at 4:02 PM Warren Kumari <[email-masked]
> <mailto:[email-masked]>> wrote:
>
>     On Wed, Oct 28, 2020 at 3:20 PM John C Klensin <[email-masked]
>     <mailto:[email-masked]>> wrote:
>     >
>     [ Massive SNIP ]
>
>     >

---

From: Mark Andrews <[email-masked]>
Date: Fri, 30 Oct 2020 09:40:02 +1100

> On 30 Oct 2020, at 01:48, Keith Moore <[email-masked]> wrote:
> 
> Given that none of section, paragraph, or page numbers appear in the XML, I don't see how any of them helps with that problem.   But it is a real problem.
> (IMO, XML is a horrible format for document authoring/editing.   It optimizes for all of the wrong things and imposes a considerable burden on writing and maintaining drafts, especially for newcomers.)
> 
> Keith

They can provide more context.  Going from text form back to xml can be
difficult.  But all this is an aside to the RFC form.
-- 
Mark Andrews, ISC
1 Seymour St., Dundas Valley, NSW 2117, Australia
PHONE: +61 2 9871 4742              INTERNET: [email-masked]

---

From: John C Klensin <[email-masked]>
Date: Fri, 30 Oct 2020 01:28:06 -0400

--On Thursday, October 29, 2020 10:48 -0400 Keith Moore
<[email-masked]> wrote:

>>> At the I-D stage page numbers are useful because people send
>>> diffs and you need to context to get to the right place in
>>> the .xml.
>> 
>> How do page numbers help with the XML? Aren't section and
>> paragraph numbers much better for that?
> 
> Given that none of section, paragraph, or page numbers appear
> in the XML, I don't see how any of them helps with that
> problem. But it is a real problem.

Actually, Keith, some of us manage to put comments in the XML
that make relevant material easy to find.  Sometimes those
comments might actually be section or other numbers, others
might be convenient terms for searching, a function that short
names for sections (the same names that might be used for
anchors) may also serve.  

See below.

> (IMO, XML is a horrible format for document authoring/editing.
> It optimizes for all of the wrong things and imposes a
> considerable burden on writing and maintaining drafts,
> especially for newcomers.)

Well, first of all, while I acquired it long ago (IIR, before
there was an IETF), I still believe that generic markup is an
acquired taste.  For my particular taste, relatively purely
generic forms are better than hybrids, but that is also a matter
of taste-- and a different discussion.  So, of course, are
format markup, various flavors of assisted or unassisted WYSIWYG
editors (with or without subsequent machine translation to XML),
and writing I-Ds in advanced plain text editors of the vi or
emacs persuasions.

Of those options, the format markup is the only one that is
probably unsuitable if we are trying to support availability of
multiple output formats as long as the RFC Editor is willing to
accept plain text input (and even that might be ok if the plain
text output is produced first).  IMO at least, we should be
pleased that we have multiple input arrangements and sets of
tools available so that, if you (or I or someone else) doesn't
like one option, they can chose another and get on with the
IETF's substantive technical work.  That seems to me to be, to
partially paraphrase Warren, far more productive than
conversations about how one method is better and more virtuous
than another and hence that people who prefer something else
should Feel Bad about it.   

What Warren didn't say but someone probably should is that
--using the two of us and this particular case as an example--
if you felt that my life would be immeasurably improved if I
switched away from XML, I'd be quite interested in understanding
why.  But let's do that off-list because that discussion would
necessarily draw on our long friendship and knowledge of each
other's backgrounds and history.  The same discussion would
likely be irrelevant to others.

As others have pointed out, this is not really related to the
current thread, but there is one way in which it is.  IMO, the
fundamental issue about choices of input formats and tools is
nearly the same as the fundamental issue about choices of output
formats.  A discussion among people who prefer to work with
plain text (sometimes or always) about what the details of that
format should be is useful.  A discussion between then and
people who believe the format is obsolete or backward or
destructive and that people should feel bad using it is much
less likely to be useful in sorting details of the plain text
form.   

And when people can't even discuss such a format without use of
metaphors whose intent seems to be to be demeaning of the format
and to make those who use it feel bad ("dead trees versions"
comes to mind regardless of the merits of the associated
comments) then not only does it not help with constructive
suggestions or moving toward consensus, but leads to wondering,
given our supposed policies, where the SAA team is.  At the same
time, their intervention is unlikely to move the conversation in
constructive directions.

Jay, I copied you explicitly on this because, while I'll try to
find time in the next few days to go through your survey, I want
to make an observation after looking at the first page, one that
relates critically to the comments above: at least IMO, the best
interests of the Internet and the IETF are going to be best
served by being as inclusive as possible, including inclusive of
people with different backgrounds, habits, and consequent
preferences about tools and ways of working.  If we say that we
ran a survey and the vast majority prefer method A or B and
hence we are going to concentrate our energy and resources
there, we need to understand that people who prefer method C or
D (or who have attitudes toward A and B more negative than those
Keith expresses above about XML) are as likely to drop out and
go elsewhere than to learn, and become enthused about, A or B.
And that situation could be even worse if there is only an A and
no B.   Were this or other things to leave an IETF that was a
wonderful place for people with one type of history, work
styles, and preferences to do their work but with everyone else
shut out, its opinions and consensus would not be worth much
consideration by the wider world and it would basically not be
worth the resources to keep it going.  No one issue or decision
is likely to produce that outcome, but, again IMO, it is more
important to concentrate on preserving diversity along those
dimensions (not just demographic ones) rather than asking
questions about the preferences of those who happen to be active
now and assuming the answers tell us where we should be going.
Certainly there are resource and common-sense limits on how far
we can or should go but caution about doing a survey and then
going with majority opinions or practices would seem to be in
order if only because, almost by definition, you aren't going to
hear from those who have walked away.

best,
   john

---

From: Leonard Giuliano <[email-masked]>
Date: Thu, 29 Oct 2020 12:18:36 -0700

+1 
One of the big things I appreciate about IETF specs is the simplicity and 
ease of consumption from the txt versions.  

On Thu, 29 Oct 2020, Donald Eastlake wrote:

| 
| 
| I endorse Warren's comments. I use the text versions heavily and I believe that one of the formats available should preserve the traditional RFC format.
| -- All formats should have a Tables of Content. (Well, I guess I would agree that if an RFC had less than two sections, it wouldn't need a ToC, but I don't see how that is possible with the current requirements.)
| 
| -- If a format is paginated, it should have page numbers. (A warning could be added something like "Warning: The page numbers in this document depend on its presentation format and will differ in other renditions.")
| 
| -- If a format has a ToC and pages numbers, those page numbers should appear in the ToC and just before the ToC would be a good place for the warning suggested above.
| 
| Thanks,
| Donald
| ===============================
|  Donald E. Eastlake 3rd   +1-508-333-2270 (cell)
|  2386 Panoramic Circle, Apopka, FL 32703 USA
|  [email-masked]
| 
| 
| On Wed, Oct 28, 2020 at 4:02 PM Warren Kumari <[email-masked]> wrote:
|       On Wed, Oct 28, 2020 at 3:20 PM John C Klensin <[email-masked]> wrote:
|       >
|       [ Massive SNIP ]
| 
|       >
|       >  (a) They are traditional in the RFC Series and
|       >         preserving that rendering in a format consistent with a
|       >         significant fraction of the first 7000 or so of RFCs
|       >         would seem to have some advantages.  Of course, no one
|       >         is forced to use them, any more than anyone has been
|       >         forced to use the standard text form since HTML and PDF
|       >         forms became generally available years ago.
|       >
|       >  (b) Of the fraction of the community that still prefers
|       >         to use the plain text form (at least sometimes) and for
|       >         one purpose or another, some fraction of them prefer to
|       >         have the headers and footers and many of those prefer,
|       >         or are not disturbed by, the page numbers.  Because many
|       >         of the arguments against page numbers seem to be coming
|       >         from people who do not find the plain text form useful,
|       >         probably we should pay attention to that preference ...
|       >         or start making the case for getting rid of the plain
|       >         text form entirely, perhaps because those who prefer it
|       >         (for any purpose) need to be persuaded to join the
|       >         modern era and get with the programs.
|       >
| 
|       I realize you aren't actually pushing this point, but this seemed like
|       the clearest expression of one of my concerns with this entire thread,
|       and so I'm choosing to hook onto it...
| 
|       Full disclosure:
|       I'm one of the people who both believes that there is value in the
|       "traditional" aspect of the series, and the fact that RFC17 looks the
|       same as RFC42, which looks the same as RFC4217, which looks the same
|       as RFC8217 is a good thing.
|       I also like and use the text formats - I sometimes print out RFCS, I
|       have tooling which greps through documents for things, I generate
|       statistics, etc. It's a personal preference.
| 
|       I've gotten 2 distinctly negative impressions from this thread:
|       1: "You need to join the modern era and get with the program" sums it
|       up well. HTML / flowed output is the new world, liking the text format
|       is bad and you should feel bad[0].
| 
|       2: There were extensive discussions around the new format, and the
|       lack of page numbers was mentioned. You were not paying attention when
|       this happened. Not only do you lose any right to discuss this, but you
|       were lazy and should feel bad.
| 
|       I'll happily admit that I didn't follow the new format discussions
|       closely, and that I do read a lot of things (including books) in
|       formats which don't have clear "pages", but the thing that is worrying
|       me is the underlying "and you should feel bad" tone in much of this
|       discussion.
| 
|       Perhaps I'm being overly sensitive (or that I just miss seeing IETFers
|       in person), but it feels to me like the "and you should feel bad"
|       subtext seems to be cropping up more and more. We used to generally
|       assume that someone who had a bad or silly idea just had a bad or
|       silly *idea* - but it now we often seem to be implying that the person
|       is bad or silly.
| 
|       Other than being able to meet in person again, I'm not sure how we get
|       back to where our base assumptions are that other IETFers are friends,
|       and are also trying to do the right thing...
| 
|       W
|       [0]: Meme reminder: https://www.youtube.com/watch?v=jG2KMkQLZmI
| 
| 
|       > Probably I'm missing something important but, if the above
|       > analysis is even nearly correct, I don't understand why we are
|       > still having this conversation.
|       >
|       >     john
|       >
| 
| 
|       --
|       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: Toerless Eckert <[email-masked]>
Date: Thu, 29 Oct 2020 20:57:37 +0100

[Cc'in Jay explicitly]

Btw: i had created initiall a poll to start this thread:

[ after i was previously already told to not revive this topic. And of course
  the poll was met with procedural resistance as well, such as claiming polls is not what
  (IETF) we do, or that its subject to attacks. I did get from those comments
  mostly a feeling of personal hostility against me, but of course i was also
  told in other threads that it is inappropriate to question or even discuss peer
  reasonings.  So i will leave it at that, even though i think outside of
  personal hostilities there are a lot more important aspects why discussing
  motivations would be really helpfull to the IETF communications culture 
  (hint: commercial reasonings that are not discussed). ]

Be that as it may: 

I very much like Jay Daley's in-development questionaire for draft/rfc authors
to understand the creation side of dealing with running xmlv3 code.

I asked Jay, if there where similar plans for the consumption side, and he said no.

So i think it would probably be good if folks who think the consumption side options
for our work product are not perfect could chime in and show interest for a
similar questionare to be made for such consumption aspects - such as
available, IETF provided formats including their details such as page
numbers. I am sure there is a lot more consumption side aspects to query.

Cheers
    Toerless

-- 
---
[email-masked]

---

From: "Black, David" <[email-masked]>
Date: Thu, 29 Oct 2020 19:59:09 +0000

+1, Thanks, --David

From: WGChairs <[email-masked]> On Behalf Of Christian Huitema
Sent: Thursday, October 29, 2020 3:33 PM
To: Donald Eastlake; Warren Kumari
Cc: Working Group Chairs; Phillip Hallam-Baker; John Levine; IETF Discussion Mailing List; RFC Interest; [email-masked]; John C Klensin
Subject: Re: Jim: Re: [rfc-i] FIXED: Poll: RFCs with page numbers (pretty please) ? (was: Re: John/rsoc: Re: Page numbers in RFCs questions / preferences)

[EXTERNAL EMAIL]

I think I agree with Warren and Donald. The primary purpose of our specifications is to provide guidance to people implementing and deploying protocols. This requires that specifications are easy to read, whether as text, or HTML, or PDF. And "ease of reading" requires a table of content, with page numbers if the presentation format uses pages.

I understand the argument that people might them misuse these page numbers, as in "page 16 said that you MUST do this." That could be bad, especially if that argument happens during some kind of legal dispute. But let's not lose sight of the main goal of the series, which is NOT "solving legal dispute". If it were, the RFC ought to be formatted much like legal documents, numbering not just every section but every paragraph as well. We won't do that, because that would harm our primary objective, easy to access and read by implementers and users. Instead of solving the "legal reference" problem by making documents harder to read, we need to find another way. Maybe point to a reference rendering of the official XML text, or something like that.

-- Christian Huitema
On 10/29/2020 12:10 PM, Donald Eastlake wrote:
I endorse Warren's comments. I use the text versions heavily and I believe that one of the formats available should preserve the traditional RFC format.

-- All formats should have a Tables of Content. (Well, I guess I would agree that if an RFC had less than two sections, it wouldn't need a ToC, but I don't see how that is possible with the current requirements.)

-- If a format is paginated, it should have page numbers. (A warning could be added something like "Warning: The page numbers in this document depend on its presentation format and will differ in other renditions.")

-- If a format has a ToC and pages numbers, those page numbers should appear in the ToC and just before the ToC would be a good place for the warning suggested above.

Thanks,
Donald
===============================
 Donald E. Eastlake 3rd   +1-508-333-2270 (cell)
 2386 Panoramic Circle, Apopka, FL 32703 USA
 [email-masked]<mailto:[email-masked]>

On Wed, Oct 28, 2020 at 4:02 PM Warren Kumari <[email-masked]<mailto:[email-masked]>> wrote:
On Wed, Oct 28, 2020 at 3:20 PM John C Klensin <[email-masked]<mailto:[email-masked]>> wrote:
[ Massive SNIP ]

Full disclosure:

W

---

From: Jane Coffin <[email-masked]>
Date: Thu, 29 Oct 2020 20:31:09 +0000

I have stayed out of the debate to learn from all of you.
I did want to just say +1 to the framing, below.
This makes sense to me.

From: irsg <[email-masked]> on behalf of Donald Eastlake <[email-masked]>
Date: Thursday, October 29, 2020 at 3:11 PM
To: Warren Kumari <[email-masked]>
Cc: Working Group Chairs <[email-masked]>, Phillip Hallam-Baker <[email-masked]>, John Levine <[email-masked]>, IETF Discussion Mailing List <[email-masked]>, Toerless Eckert <[email-masked]>, RFC Interest <[email-masked]>, "[email-masked]" <[email-masked]>, John C Klensin <[email-masked]>
Subject: Re: [irsg] Jim: Re: [rfc-i] FIXED: Poll: RFCs with page numbers (pretty please) ? (was: Re: John/rsoc: Re: Page numbers in RFCs questions / preferences)

Thanks,
Donald

On Wed, Oct 28, 2020 at 4:02 PM Warren Kumari <[email-masked]<mailto:[email-masked]>> wrote:
On Wed, Oct 28, 2020 at 3:20 PM John C Klensin <[email-masked]<mailto:[email-masked]>> wrote:
[ Massive SNIP ]

Full disclosure:

W

---

From: Keith Moore <[email-masked]>
Date: Sat, 31 Oct 2020 07:18:41 -0400

First, I am sorry if I gave the impression that I thought any of "you 
should feel bad" about any preferences you might have for either 
input/authoring/revision or output formats for RFCs.  I'm pretty sure 
that was not my intention.

(I do appreciate Warren's mention of that, though.   I was raised and 
schooled in a world full of "you should feel bad", and it's a poor habit 
of both speaking and thinking.   And I struggle to think of occasions in 
which "you should feel bad" have actually helped people be wiser or 
better informed.)

I have used all of the RFC output formats and continue to find all of 
them useful.   If paginated plain text were added to the existing 
formats, I'm not sure that I would use that format very often, but its 
existence wouldn't bother me either.   Even though I dislike the XML as 
an input/authoring/revision format, I see its value as a common format 
from which multiple output formats can be derived.  (And I do not 
believe that "you should feel bad" if you either happen to like the XML 
or prefer paginated text as an output format.)

The frustration which I was trying to express is something more like 
this:  Every time I submit a new I-D, I dread the process of fighting 
with the format and the tools, generally under deadline pressure of some 
kind.    Making the tools happy has often required more work than 
writing the text itself.   And occasionally I've been unable to get the 
tools to produce the output in a form that I thought would be most 
readable.

The problems I've seen aren't entirely with the XML2RFC language and the 
document processing tools, but also with the many requirements (for 
boilerplate etc) that we're expected to fulfill just in order to submit 
what used to be an informal proposal.   Or at least it appears that way 
when I use the I-D submission tool. I remember when I could write an 
acceptable I-D using nothing more than emacs, and about the only 
requirement was knowing what email address to send it to.

I got into the habit of using the xml2rfc language long ago when it 
seemed like the best way to make sure that the I-D would pass all of the 
various requirements for submitting one.   (That was right after I had 
an I-D rejected, and missed a submission deadline, because I fixed a 
grammatical error in some of the prescribed boilerplate text.)

But I just realized from filling out Jay's survey that there are now a 
lot of I-D authoring tools that I wasn't aware of, and that I didn't 
find the last time I looked for such tools sometime within the past 
year.  (thanks Jay!)   So I'm glad to see that more such tools exist, 
and I hope to find time to evaluate some of them before once again 
facing another deadline to write a new I-D.

Keith

---

From: "Andrew G. Malis" <[email-masked]>
Date: Sat, 31 Oct 2020 10:02:30 -0400

Keith (any anyone else looking for shiny new draft authoring tools),

I recommend that you give Carsten Bormann's Kramdown a try. It's really
easy to pick up and use. You can install a converter locally, or just use
the one at https://xml2rfc.tools.ietf.org/experimental.html . From Kramdown
source, you can directly generate any output format, or generate XML (look
for the "kramdown" button in the first dialog box, and also the third
dialog box at https://xml2rfc.tools.ietf.org/experimental.html). There's
documentation at https://github.com/cabo/kramdown-rfc2629, and a syntax
guide at https://kramdown.gettalong.org/syntax.html . I find that it really
lets me concentrate more on the content and less on the formatting.

Cheers,
Andy

---

From: John C Klensin <[email-masked]>
Date: Sat, 31 Oct 2020 11:53:47 -0400

Larry,

Clever idea but --

 (1) We already have rules against people making such
	references.  The RFC Editor Function has been enforcing
	those rules for references within and between RFCs for
	decades. After this discussion, if paying more attention
	to that is even possible, I'm confident they will do it.
 (2) If people are determined to break that rule, it is
	not clear to me that some additional words will either
	prevent their doing it or convince them to include the
	format / rendering information in their references.
 (3) It is also not clear to me that assorted markup
	templates (not only our xml2rfc one but those of
	external journals and publishers have a good place to
	put that information, especially if we do not invent,
	and publicize, a standard way to reference RFCs that
	includes that information (which would be odd, given
	that we are trying to stamp it out (see(1) above and one
	or two of my earlier notes). 
 (4) At least for shorter documents, if people are really
	determined to use page numbers but we leave them off of
	paginated documents, they will simply count and then use
	them (perhaps as "fifth page", rather than "page 5")
	just as many of us have been counting paragraphs within
	sections and referring to, e.g., "the third paragraph of
	Section 5" for years.
 (5) If we are going to do anything other than putting
	the page numbers into the plain text form (and leaving
	them in the PDF form) or trying to punish anyone who is
	ignorant or backward enough to want to use the plain
	text form for any purpose (presumably included
	tree-hatred), then, IMO, we should just put them in
	(along with the headers and footers) and move on.
	
    john

--On Thursday, October 29, 2020 10:02 -0700 Larry Masinter
<[email-masked]> wrote:

> If you're concerned about people seeing different pagination
> depending on format, you could change the page numbers at the
> bottom of .txt pages to be
> 
>  Author                                  Shortname
>                            docname.txt[Page 2]
> 
> it's better if the page identifier at the bottom of the page
> identifies the context anyway.

---

From: Larry Masinter <[email-masked]>
Date: Sat, 31 Oct 2020 13:37:01 -0700

in lieu of some (useless) warning text about paginations, make MIME-type
relative URIs more useful.

Consider what it would take to make a hyperlink of the
https://tools.ietf.org/html/rfc6924 form
         urn:ietf:rfc:2324#Section_2.3.2
work better than
        https://tools.ietf.org/pdf/rfc2324.pdf#page=5

to use the same fragID for text, HTML, pdf, XML ?

RFC 5147 is an obstacle, but suppose it only applies to text/plain so
they could be served as text/rfc

I don't know how widely https://tools.ietf.org/html/rfc8118#section-3 is
implemented.