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

["HANSEN, TONY L" <[e-mail]>]

Another quick test. I changed each pilcrow in the HTML format

like this:
<a href="#section-2-2" class="pilcrow">¶</a>
to this:
<a href="#section- 2-2" class="pilcrow"><span class="pilcrow-text">2-2</span>¶</a>

and added this CSS:

a.pilcrow > .pilcrow-text {
  visibility: visible;
  float: right;
  font-size: xx-small;
}

and a small, unintrusive section number (with paragraph) shows up on the bottom right of each paragraph. I also think it's very obvious that the numbers are not part of the text.

It's almost what I was thinking of when I helped write the text for RFC 7995. :) 

I'd rather have it in the right margin, but it was just a VERY quick test.

	Tony

On 10/27/20, 3:27 PM, "Toerless Eckert" <[e-mail]> 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.

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

    -- 
    ---
    [e-mail]