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

[Henrik Levkowetz <[e-mail]>]

Hi Tony,

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

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:
> 
> <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.

Right.

Best,
	Henrik

> 
> Just some thoughts.
> 
> 	Tony
> 
> On 10/27/20, 2:32 PM, "Henrik Levkowetz" <[e-mail]> wrote:
> 
>     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
>     >     >>
>     >     > 
>     > 
>     > 
> 
>