[rfc-i] Pagination requirements

Martin Rex mrex at sap.com
Tue May 15 09:40:51 PDT 2012


Iljitsch van Beijnum wrote:
> 
> Martin Rex wrote:
>> 
>>> Why are page references so much better than section references
>>> that we need to have pages in the canonical format?
>> 
>> Because there are numerous sections that span multiple pages, and
>> it is really helpful when you can specify locations in a specification
>> with reasonable proximity -- and that page-based location information
>> remains valid across all display devices.

page-based location information only makes sense if is pre-paginated
and canonical.

> 
> So what you're saying is that it's a good tradeoff for readers
> of ALL RFCs on ALL devices where the page length and the display
> length are not identical to be annoyed dozens of times when reading
> an RFC because they have to navigate across superfluous page boundaries
> in order to make it easier to accommodate the very occasional situation
> where someone wants to refer to the middle of a long section that
> the author couldn't be bothered to break up in subsections?

The discussion seems to circle around braindead software on small devices.
There is no requirement for the software that visualizes RFCs on small
devices to waste most of their fingernail screen real estate with a
representation of the pre-pagination page breaks.  It would be trivial
to not display them at all.

Do those fancy devices have a requirement for pocket-book printers, or
are they capable of driving regular printers with DIN A4 or Letter paper
size?

Rendering pre-formatted and pre-paginated ASCII (such as existing RFCs)
smarter on small devices can probably done by a single person in less
than a week and is close to a no-brainer (but one that is meeting strong
resistance).  Writing the software to render HTML on a device that
does not have that software is a lifetime project.

rfcmarkup, the script that produces the HTML display on
http://tools.ietf.org/html/rfc5280
knows quite well where page breaks, header&footers are.

If HTML is as versatile as folks claim it to be, why does it take regular
long discussions, rather than adding the 10 lines of code to rfcmarkup
that enable small devices to not display the page breaks for folks that
dislike them?


> 
> I would argue that if the desire arises to refer to text that doesn't
> start very soon after a section header, the author has done a bad job.

You're calling for a 20-page size limit for specifications.


> 
> I would also think that referring to text is only necessary when
> it's too long to quote,

Nope, I prefer to limit quotes to what I believe matters -- but for
fairness I would like to include an URL that puts the quoted information
directly on-screen when clicked and enables others to check the vincinity
of the quoted text to see whether that quotation is "out of context".


Usually, when implementing an RFC, I do just the same: quote the lines
relevant to a block of code from the RFC into a comment of the code
and include an direct URL to that part of the RFC.

RFCs specify data and functions in abstract fashion, program source code
specify a particular implementation.  If the RFC can not get along with
plain ASCII, then it is probably not a technical specification that
others want to implement, but rather demo/marketing/sales material.

Do we need a third demo/marketing/sales track for IETF documents?


>
> And although deep study or review of an RFC or draft may happen using
> a hardcopy,

That is what I usually do when implementing a larger spec for the
first time.  I print it out, read through the document 2-3 times,
paging back and forth and marking all parts relevant for the initial
implementation, and then start implementing and copy&pasting snippets
of the online RFC into comment lines in front of code blocks or
functions/modules.

Doing this for current RFCs is easy and fast.
Doing the same for ISO-specification (e.g. X.509) is a royal PITA,
because of the PDF format with 100+ chars line lengths and ripple
left margin.

Discussing paragraphs from ISO-specs is also a royal PITA because of
the difficulty of quoting the stuff in plain text EMail and because
I can not include functioning URLs that will position mail recipients
at the exact location of the spec with a single mouse-click.
PDF is nice for printing and archival, but significantly lacks
in comparison to the rfcmarkup that is available on tools.ietf.org.

Being able to convert an RFC into some format that I might personally prefer
with fairly simple scripts is a temendous advantage, as demonstrated by
the rfcmarkup and 2-column document diff display on tools.ietf.org.

A complex document format like XML or HTML is a dead end road, to get
from there to other places, it always requires significant familarity with
the underlying data format, multi-megabytes software and moderately sized
software projects rather than an all-nighter with no prior knowledge
about the document format.


> I think most referrals will be followed in electronic form,
> preferably through a hyperlink. In that case, page numbers aren't the
> most obvious mechanism.

Only if the page-numbers are based on canonical pre-pagination.

Table of contents are normally part of the document, and they would
be pretty useless without canonical pre-pagination.


> 
> Perhaps an example of where the omission of page numbers would
> be problematic would help.

There is no requirement that the software you use for reading RFCs
visualizes the original pre-pagination, headers&footers.  Maybe you're
simply using the wrong software?


-Martin


More information about the rfc-interest mailing list