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

[Paul Kyzivat <[e-mail]>]

On 10/27/20 3:27 PM, Toerless Eckert wrote:
> 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.

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

> 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.
>>
>> 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
>>
>> On 10/27/20 2:25 PM, 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.
>>>
>>> 	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
>>>       >>
>>>       >
>>>
>>>
>