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

[Henrik Levkowetz <[e-mail]>]

Hi Tony,

On 2020-10-27 19:25, HANSEN, TONY L wrote:
> 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.

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

> 	Tony Hansen
> 
> On 10/27/20, 11:23 AM, "WGChairs on behalf of Paul Kyzivat" <[e-mail] on behalf of [e-mail]> wrote:
> 
>     On 10/27/20 7:33 AM, Keith Drage wrote:
>     > 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.
> 
>     +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
> 
>     > 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
>     > 
>     > On 27/10/2020 01:53, John C Klensin wrote:
>     >>
>     >> --On Tuesday, October 27, 2020 01:30 +0000 Ronald Tse
>     >> <[e-mail]> 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
>     >>
>     > 
> 
>