Subject: [Tools-discuss] pages numbers in ToC in PDF

From: Michael Richardson <[email-masked]>
Date: Thu, 27 May 2021 07:34:30 -0400

If the PDFs are paginated, why doesn't the Table of Contents in the PDF, have
page numbers?  Yes, they are linked.
But, that's useless if you actually dump it to tree-ware.

Consider, for instance, https://www.rfc-editor.org/rfc/rfc8995.pdf

--
Michael Richardson <[email-masked]>   . o O ( IPv6 IøT consulting )
           Sandelman Software Works Inc, Ottawa and Worldwide

---

From: Toerless Eckert <[email-masked]>
Date: Thu, 27 May 2021 20:50:57 +0200

We had this discussion recurringly last year, and it seems that the lovers
of page numbers need to get together and write an RFC adopted by the community,
or else nothing will change. Would be an update to the <can-never-remember-thenumber>
RFC about the new RC posting format whose text is interpreted by the tools
team to say "no-page-numbers", not even in TOC of PDF.

Thats my understanding. If there is an easier way to get page numbers into TOCs
of PDF, that would be great.

Cheers
    Toerless

---

From: Carsten Bormann <[email-masked]>
Date: Thu, 27 May 2021 20:51:37 +0200

> But, that's useless if you actually dump it to tree-ware.

It’s almost Friday, so here goes:

Maybe we need to add to the boilerplate:

> Please consider the environment before dumping RFCs on dead trees.
> Since we already did that for you, we made it deliberately hard for you to use tree-based copies of RFCs.

[SCNR, no such intention actually implied]

Grüße, Carsten

PS.: 
I stopped using paper around the turn of the century.
I still would like to have page numbers!

---

From: Bob Hinden <[email-masked]>
Date: Thu, 27 May 2021 12:03:39 -0700

I would also like the page numbers in the TOC.

Not for printing, but when I look at a new draft, it quickly tells me how
long it is.

I don't see any downside to adding page numbers to the TOC.

Bob

On Thu, May 27, 2021 at 11:51 AM Carsten Bormann <[email-masked]> wrote:

> ___________________________________________________________
> Tools-discuss mailing list - [email-masked]
> This list is for discussion, not for action requests or bug reports.
> * Report datatracker and mailarchive bugs to: [email-masked]
> * Report tools.ietf.org bugs to: [email-masked]
> * Report all other bugs or issues to: [email-masked]
> List info (including how to Unsubscribe):
> https://www.ietf.org/mailman/listinfo/tools-discuss
>

---

From: Toerless Eckert <[email-masked]>
Date: Thu, 27 May 2021 21:12:55 +0200

To actually go back to the root problem, and this is all just revival of
2020 discussions:

A) We wanted to make sure there can be multiple renderings of RFCs.
  They will not have consistent page numbers.

B) We have to avoid the collapse of the Internet, that would happen with A)
   and the fact that references such as "see RFCxxx page NN", would lead to
   implementers writing code for completely wrong pages of reference RFCs.

The problem with that logic is of course what i call "the terrorists always win":
someone does something malicious, or as in this case just less-well-educated,
and then new rules are made to let everyone suffer for it. Most of them not
even understanding why or for no good reason.

IMHO: For future RFCs to be, it is easy for RFC editor to prohibit references
to page numbers of RFC, but instead use correct RFC#/section/paragraph.

For third-party document i would be happy to have a new disclaimer added to
each RFC rendering that includes page numbers:

 "References into this document MUST NOT use page numbers. Any page numbers
  are rendering specific artefacts, not part of the document itself".

Cheers
    Toerless

On Thu, May 27, 2021 at 08:51:37PM +0200, Carsten Bormann wrote:
> It???s almost Friday, so here goes:
> 
> List info (including how to Unsubscribe): https://www.ietf.org/mailman/listinfo/tools-discuss

-- 
---
[email-masked]

---

From: Carsten Bormann <[email-masked]>
Date: Thu, 27 May 2021 21:18:29 +0200

> of PDF, that would be great.

A first step might be a patch for xml2rfc.
Note that xml2rfc can already put pagination in TXT, which is an option that needs to be explicitly specified.
https://xml2rfc.tools.ietf.org/xml2rfc-doc.html#section-b.7-1.11
This apparently was possible to do without changing RFCXXXX.

https://trac.ietf.org/trac/xml2rfc/ticket/558
seems to imply this cannot be done for PDF in the current architecture of xml2rfc.
Having used troff extensively for a quarter of a decade, I can authoritatively confirm that it sure can be done, at the cost of double (*) the processing time.
(One implementation of the concept is called a “side file”, and, no, that cannot be googled, but every TeX user knows it.)

Grüße, Carsten

(*) and, occasionally, triple that, but I don’t think that applies here.

---

From: Michael Richardson <[email-masked]>
Date: Thu, 27 May 2021 15:31:36 -0400

> PS.: I stopped using paper around the turn of the century.  I still
    > would like to have page numbers!

I also almost never print to paper.
I also seldom use PDF either, but I was surprised at that lack, given that
the document is paginated.

If we are going to paginate the PDF, the ToC should have page numbers.

---

From: "John Levine" <[email-masked]>
Date: 27 May 2021 16:03:39 -0400

It appears that Bob Hinden  <[email-masked]> said:
>-=-=-=-=-=-

Only if you promise to give $100 to the IETF Endowment any time you
mention a page number in a message to an IETF list.

Two points about page numbers in PDFs: I believe Carsten is correct, it'd take
two passes and double the time it takes to render the PDF.  I don't see this as
a terrible problem.

The key point is the one about page numbers being specific to a
rendering, and there's no canonical rendering. RFC 7995 suggested that
using paragraph numhers. It waffled about where they're visible, but
at least they stay the same among renderings. I suppose we could do
that, needing more like 1 1/2 passes to count and tag the paragraphs
if they aren't already tagged by the preptool.

xml2rfc uses a library called wasyprint to create the PDFs. It renders
HTML, using a tweaked version of the HTML output. That limits our
control over the output and is why the page breaks often look strange.
We knew about the limitations when we chose that approach, albeit
perhaps not just how bad the page breaks would be, because it is
vastly easier than the alternative of writing a PDF rendering engine.

R's,
John

---

From: Michael Richardson <[email-masked]>
Date: Thu, 27 May 2021 16:11:25 -0400

Toerless Eckert <[email-masked]> wrote:
    > For third-party document i would be happy to have a new disclaimer
    > added to each RFC rendering that includes page numbers:

    >  "References into this document MUST NOT use page numbers. Any page
    > numbers are rendering specific artefacts, not part of the document
    > itself".

Sure.

I'm okay if we show the ToC, in CoAP-option like way, so each line just has:

    Bananas ............... 0
    Green Peppers ......... +4
    Tomatoes .............. +3

{not a serious suggestion}

But, as long as the PDF has page numbers, then people can reference page XXX.
Whether or not the ToC has them doesn't matter.

---

From: Toerless Eckert <[email-masked]>
Date: Thu, 27 May 2021 22:23:15 +0200

Thanks, i was thinking this wuould be possible to do in .txt given
how its done for drafts.

Obviously what i meant was in the context of ietf tools/data-tracker offering such a
rendering. Having everyone doing it by themselves.

On Thu, May 27, 2021 at 09:18:29PM +0200, Carsten Bormann wrote:
> (One implementation of the concept is called a ???side file???, and, no, that cannot be googled, but every TeX user knows it.)
> 
> Grüße, Carsten
> 
> (*) and, occasionally, triple that, but I don???t think that applies here.

---

From: Toerless Eckert <[email-masked]>
Date: Thu, 27 May 2021 23:13:52 +0200

I would not put it past lazy research article writers to never read
a document but simply look at the TOC to find whatever section looks
like a good reference - and never read any of the doc. But i am saying
this after the last decade has seen various high ranking erman government
officials loose their jobs after their PhD thesis where shown to be
stlen or otherwise severely sub-par.

All i can do is upgrade my proposed disclaimer in paginated rendering to "yelling":

Eg. at beginning of TOC of paginated document:

PLEASE DO NOT USE REFERENCES TO PAGE NUMBERS. THEY ARE PART OF THIS RENDERING FORMAT
BUT THEY ARE NOT GUARANTEED TO BE THE SAME ACROSS DIFFERENT RENDERING FORMATS.

Cheers
    toerless

-- 
---
[email-masked]

---

From: Bob Hinden <[email-masked]>
Date: Thu, 27 May 2021 16:33:43 -0700

John,

> On May 27, 2021, at 1:03 PM, John Levine <[email-masked]> wrote:
> 

I promise to not mention page numbers on an IETF list.

> if they aren't already tagged by the preptool.

As others have noted, it seems to me that if the rendering has page numbers, then the TOC should too.

However, looking at RFC 8995, at https://www.rfc-editor.org/info/rfc8995, there are rendering for HTML, TEXT and PDF.   HTML and TEXT have no page numbers, PDF does.   Personally I find the Text version without page number (on pages and TOC) ugly and not very useful.

I would prefer we add page number back in all of the renderings.  Sigh...

Bob

---

From: Jay Daley <[email-masked]>
Date: Fri, 28 May 2021 11:41:31 +1200

> On 28/05/2021, at 9:13 AM, Toerless Eckert <[email-masked]> wrote:
> 

Perhaps a "Referencing this document" section needs to be part of the boilerplate of all RFCs and I-Ds.  The former can address this issue of multiple renderings, page numbering and referencing sections; the latter can address the issue of I-Ds not representing the IETF.

Jay

> [email-masked] <mailto:[email-masked]>
> 

-- 
Jay Daley
IETF Executive Director
[email-masked]

---

From: Toerless Eckert <[email-masked]>
Date: Fri, 28 May 2021 01:47:53 +0200

> I would prefer we add page number back in all of the renderings.  Sigh...

For HTML, TEXT its not only page numbers, its also to add back pagination.
PDF is the odd man of, because it has pagination but yet no page numbers (in TOC).

As i said, unless someone from the tools teams offers something better, its
got to be an RFC to be written to ask for it. However, that will fail if
it does not make it clear that paginated TXT/HTML will only be ADDITIONAL
renderings to be requested for on on datatracker or rfc-editor (whatever tools team
prefers). Otherwise we would have an unwinnable battle.

Cheers
    toerless

-- 
---
[email-masked]

---

From: Michael Richardson <[email-masked]>
Date: Thu, 27 May 2021 19:53:48 -0400

John Levine <[email-masked]> wrote:
    >> Not for printing, but when I look at a new draft, it quickly tells me
    >> how long it is.
    >>

    > mention a page number in a message to an IETF

*I* didn't put the page numbers there :-)

1) another other option is not to number the pages in the PDF :-)

2) a third option is to number the pages is an unusual base using a
   non-arabic number system.

I'm just asking for consistency.

--
]               Never tell me the odds!                 | ipv6 mesh networks [
]   Michael Richardson, Sandelman Software Works        |    IoT architect   [
]     [email-masked]  http://www.sandelman.ca/        |   ruby on rails    [

---

From: Toerless Eckert <[email-masked]>
Date: Fri, 28 May 2021 02:01:16 +0200

Indeed. Thats what i said at one of those "pontification about future of RFC series structure"
meeetings we had (before your time ?):  Just start with disclaimers.

To cut a good compromise between "can not be overread" and "does not clutter up the doc",
probably always have only a short paragraph followed by a URL for more info if needed
(htttps://www.ietf.org/rfc-faq/42)...

Chers
    Toerless

-- 
---
[email-masked]

---

From: Toerless Eckert <[email-masked]>
Date: Fri, 28 May 2021 02:12:54 +0200

I tried hard to only provide factual, useful information in
this thread, but now you have teased me enough...

> 1) another other option is not to number the pages in the PDF :-)

For consistency we need to remove pagination from the PDF rendering and make 
the document one single page. PDF spec i think has no problem with it,
and a global News headline of "IETF crashes computers worldwide" 
would be well worth it.

>    non-arabic number system.

Braille.

Not sure how useful 1,000 engineers are that randomnly start learning
braille numbers from desparation, but it sure scores inclusiveness points.

---

From: Michael Richardson <[email-masked]>
Date: Thu, 27 May 2021 20:20:09 -0400

Bob Hinden <[email-masked]> wrote:
    > However, looking at RFC 8995, at
    > https://www.rfc-editor.org/info/rfc8995, there are rendering for HTML,
    > TEXT and PDF.  HTML and TEXT have no page numbers, PDF does.
    > Personally I find the Text version without page number (on pages and
    > TOC) ugly and not very useful.

I found reading YANG diagrams, CDDL and other figures without page breaks was
refreshing.
But, the HTML version is generally much more pleasant.

---

From: "John R Levine" <[email-masked]>
Date: 27 May 2021 21:54:52 -0400

> and a global News headline of "IETF crashes computers worldwide"

That certainly is tempting.

Regards,
John Levine, [email-masked], Taughannock Networks, Trumansburg NY
Please consider the environment before reading this e-mail. https://jl.ly

---

From: Carsten Bormann <[email-masked]>
Date: Fri, 28 May 2021 05:29:30 +0200

Works great for me:

http://tzi.de/~cabo/rfc9000.pdf

Grüße, Carsten

> On 2021-05-28, at 03:54, John R Levine <[email-masked]> wrote:
>

---

From: Toerless Eckert <[email-masked]>
Date: Fri, 28 May 2021 05:56:50 +0200

> http://tzi.de/~cabo/rfc9000.pdf

Haha, thanks for the test.

Chrome always has memory holes for me with some eternally long web pages,
hence my prediction. But yes, this renders fine without crashing.

This PDF is also a pretty good protection against killing trees.
Cannot print more than just the first paper page with standard
PDF software.

So, how is this not better in all respects than HTML ?
Guaranteed more consistent rendering ;-))

Cheers
    Toerless

-- 
---
[email-masked]

---

From: "Salz, Rich" <[email-masked]>
Date: Fri, 28 May 2021 13:06:08 +0000

*   Perhaps a "Referencing this document" section needs to be part of the boilerplate of all RFCs and I-Ds.  The former can address this issue of multiple renderings, page numbering and referencing sections; the latter can address the issue of I-Ds not representing the IETF.

This is an excellent idea!