Subject: [Tools-discuss] Hyperlinks to sections/subsections in current RFC HTML format

From: Spencer Dawkins at IETF <[email-masked]>
Date: Mon, 14 Jun 2021 09:26:12 -0500

I've read the discussion(s) about page numbers in current RFCs but I have a
semi-related question.

I've been spoiled by a decade or so of looking at the table of contents in
the HTML for I-Ds and RFCs, and clicking on a link that takes me to the
section of interest. For example, I can do this from the table of contents
in https://datatracker.ietf.org/doc/html/rfc7418.

I am now noticing that we're publishing HTML versions that don't have page
numbers in the table of contents (makes sense because there are no page
numbers in these documents, but also don't have clickable links to the
sections themselves. For example,
https://datatracker.ietf.org/doc/html/rfc8866.

Is this intentional? Was it previously discussed?

I would be less confused if I couldn't see HTML fragments in the HTML file,
so I can go directly to
https://datatracker.ietf.org/doc/html/rfc8866#section-3.4 if I can remember
how to construct that link as a URL, but I don't see how to click on
something in the document that will take me there.

I would be MUCH less confused if I couldn't see sections in the document
that are linking directly to other sections (see
https://datatracker.ietf.org/doc/html/rfc8866#section-5, which has a link
to https://datatracker.ietf.org/doc/html/rfc8866#section-6.10, although the
table of contents does not. .

I guess what I'm asking is, if the rest of the document can link directly
to a section, why can't the table of contents?

Best,

Spencer

---

From: Julian Reschke <[email-masked]>
Date: Mon, 14 Jun 2021 16:41:17 +0200

Am 14.06.2021 um 16:26 schrieb Spencer Dawkins at IETF:
> I've read the discussion(s) about page numbers in current RFCs but I
> have a semi-related question.
>
> I've been spoiled by a decade or so of looking at the table of contents
> in the HTML for I-Ds and RFCs, and clicking on a link that takes me to
> the section of interest. For example, I can do this from the table of
> contents in https://datatracker.ietf.org/doc/html/rfc7418
> <https://datatracker.ietf.org/doc/html/rfc7418>.
>
> I am now noticing that we're publishing HTML versions that don't have
> page numbers in the table of contents (makes sense because there are no
> page numbers in these documents, but also don't have clickable links to
> the sections themselves. For example,
> https://datatracker.ietf.org/doc/html/rfc8866
> <https://datatracker.ietf.org/doc/html/rfc8866>.
>

There is <https://www.rfc-editor.org/rfc/rfc8866.html> which is the
"official" HTML, and that has working links.

What you're looking at is the "htmlized" version, based on the plain
text version. That stopped to create links as the plain text version
doesn't have page numbers in the toc.

To fix this, the "htmlize" tool would need to be updated.

 > ...

Best regards, Julian

---

From: Spencer Dawkins at IETF <[email-masked]>
Date: Mon, 14 Jun 2021 12:09:40 -0500

JHi, Julian,

> To fix this, the "htmlize" tool would need to be updated.

Thank you for helping me understand, and thank you for the pointer to the
RFC Editor HTML version.

I wondered briefly about suggesting that the datatracker just link to the
RFC Editor HTML version for RFCs, because that does seem more helpful than
showing the htmlized versions (I'm not sure there's a reason to
think someone would think to check the RFC Editor HTML version), but now
I'm curious why a draft like
https://datatracker.ietf.org/doc/draft-ietf-quic-http/ has both an HTML
version and an HTMLized version, and both have links to sections ... and
maybe I should just stop being nosy. :-)

Best,

Spencer

---

From: Michael Richardson <[email-masked]>
Date: Mon, 14 Jun 2021 14:12:54 -0400

Spencer Dawkins at IETF <[email-masked]> wrote:
    > reason to think someone would think to check the RFC Editor HTML
    > version), but now I'm curious why a draft like
    > version and an HTMLized version, and both have links to sections
    > ... and maybe I should just stop being nosy. :-)

because
 a) some people objecting to removal of the htmlize version, so it remained.
 b) Internet Drafts continue to be rendered with pagination to txt, so the htmlizer
 knows how to put links into the ToC.

I continue to read txt files in emacs from my rsync'ed offline copy whenever
I need to copy and paste or I'm editing another document.
I now prefer HTML version for everything else though.

--
Michael Richardson <[email-masked]>, Sandelman Software Works
 -= IPv6 IoT consulting =-

---

From: Toerless Eckert <[email-masked]>
Date: Mon, 14 Jun 2021 22:33:07 +0200

Julian:

> To fix this, the "htmlize" tool would need to be updated.

I think this is not an update, but a fix for a regression bug.

If you look at older html'ized RFCs in comparison, e.g: rfc7866,
you will see that the table of content has not only hotlinks to
page numbers, but also for the section numbers hotlinks to those
section numbers.. And those section number hotlink targets still are
in the new rfc renderings (rfc8866), and they even are still
hotlinks on the section headings themselves. Just not on the
section numbers in th TOC. Sounds to me like it should be a very simple
fix.

Looks like collateral damage when removing page numbers, but
not justified by any "new rendering rules" i have seen.

Just don't know these days anymore where/how to submit a bugfix
request... whats the "tool" in question here ?

Cheers
    Toerless

On Mon, Jun 14, 2021 at 04:41:17PM +0200, Julian Reschke 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

-- 
---
[email-masked]

---

From: Toerless Eckert <[email-masked]>
Date: Mon, 14 Jun 2021 22:46:12 +0200

So, whats better about the HTMl rendering vs. the html'ized  txt rendering ?

-> I don't think the readability improves by exchanging fixed-width font
   with var-width font in the html. IMHO Quite the opposite.

-> Making the rendering adjust to the width of the window is also IMHO silly.

IMHO, if you care about readability of your rfc, you will take the
width of some reference renderng into account, for example with length
of paragraphs. And that standard rendering is of cours courier 72
character which is what pictures continue to use in whatever renderingg
one chooses. So you make the window more narrow, you cut the pictures.
You make it wider, then pictures are too narrow vs. the text. You choose
some randomn font vs. courier and pictures vs. text looks ugly.

Aka: this "new" html rendering is IMHO silly. The only (arguably) good
addition to the html'ized text version is the pulldown TOC.

Cheers
    Toerless

-- 
---
[email-masked]

---

From: "Martin Thomson" <[email-masked]>
Date: Tue, 15 Jun 2021 09:44:17 +1000

>    with var-width font in the html. IMHO Quite the opposite.

So fix it.  I did.  https://github.com/martinthomson/rfc-css makes the HTML more readable (to me).  Feel free to fork that and replace the fonts with fixed-width fonts if that makes you happier.  Complaining isn't likely to cause anyone to be convinced that regressing to plain text is worthwhile.

> -> Making the rendering adjust to the width of the window is also IMHO silly.

No, not adapting is what is silly.  Different people have different computers and different needs.  HTML lets people engage with the content on their own terms, not as dictated by long-dead constraints of terminals and line printers.

---

From: Toerless Eckert <[email-masked]>
Date: Tue, 15 Jun 2021 02:41:25 +0200

> So fix it.  I did.  https://github.com/martinthomson/rfc-css makes the HTML more readable (to me).  Feel free to fork that and replace the fonts with fixed-width fonts if that makes you happier.  C…

And everybody having to do their own fixups isn't going to have datatracker
provide the options preferred by some majority.

> No, not adapting is what is silly.  Different people have different computers and different needs.  HTML lets people engage with the content on their own terms, not as dictated by long-dead constra…

For generality let me claim that most people would not want to go through the trouble of editing css.

No browser allows you to easily say "please render only datatracker HTML RFCs with monospace" (so that i have font consistency across text and pictures. So much for font.

I do agree that increasing of font size for better readability is an extreme important benefit of the HTML rendering, but because of the fixed format pictures (and nowadays even more so various code segments), RFCs are just not arbitrary free-scale. You get trouble with all these non-free scaleable elements, and the more important formal languages become in RFCs, the more we will feel that.

Also: lines become harder to read the longer they are. The current HTML rendering already does have some maximum rendered line length. That limit seems to be based on someones preference.  Quite arbitrary. I have a different preference.

I would be all for having datatracker provide a per-datatracker-account style-sheet setting. In fact, i would have expected something like that so as to actually realize the benefit of html instead of letting every user figure it out by themselves and having to start becoming a CSS coder.

Cheers
     Toerless

-- 
---
[email-masked]

---

From: "Martin Thomson" <[email-masked]>
Date: Tue, 15 Jun 2021 10:57:56 +1000

> provide the options preferred by some majority.

What I am saying is that your preferences are unique enough that maybe you need to go look out for your own interests.

> Also: lines become harder to read the longer they are.

Here you are right.  Except that this is not subjective in the way you suggest.  All the best publishing advice I've seen supports this view.  The RFC Editor adopted a stylesheet that has lines that are too long.  

I tried to fix this using the processes at the time (I even proposed patches) and was unsuccessful.  FWIW, this is the main reason I override styles in my browser.

> I would be all for having datatracker provide a per-datatracker-account 
> style-sheet setting. 

Again, don't assume that your preferences are special enough to justify someone else doing a bunch of work.  If you care enough, volunteer the work necessary to fix it.

---

From: Toerless Eckert <[email-masked]>
Date: Tue, 15 Jun 2021 03:12:09 +0200

> Again, don't assume that your preferences are special enough to justify someone else doing a bunch of work.  If you care enough, volunteer the work necessary to fix it.

I would have just thought that all the html-heads would have wanted to show off the flexibility of html more than what is done now. The amount of work to come up with a separate css and then figure out how to apply it to just dras/RFC on datatracker is big enough that only few will do i. If instead you could choose on your datatracker account from e.g.: 3 different css and upload also your own, then that would have persuaded a lot more users.

But then again, afaik, css could by itself not take the current html and paginate it, so it too has its limits.

Cheers
    Toerless

---

From: Julian Reschke <[email-masked]>
Date: Tue, 15 Jun 2021 04:14:06 +0200

> But then again, afaik, css could by itself not take the current html and paginate it, so it too has its limits.

HTML does support pagination. You just need to use the proper CSS paged
media attributes (such as done by rfc2629.xslt=, and use a tools that
takes advantage of them (such as PrinceXml or WeasyPrint).

Best regards, Julian

---

From: Julian Reschke <[email-masked]>
Date: Tue, 15 Jun 2021 04:17:01 +0200

> I think this is not an update, but a fix for a regression bug.

The tool is not broken; i't doing what it has been doing all the time.
It's the *input* on what is runs that changed.

> request... whats the "tool" in question here ?

<https://tools.ietf.org/tools/rfcmarkup/> (unless datatracker runs
something else; Robert Sparks would know).

Best regards, Julian

---

From: "Salz, Rich" <[email-masked]>
Date: Tue, 15 Jun 2021 13:59:58 +0000

> -> Making the rendering adjust to the width of the window is also IMHO silly.

    No, not adapting is what is silly. 

Agreed.

It is more than silly.  It's called "adaptive formatting" and sometimes the requirement to do so is a legal one.

---

From: Toerless Eckert <[email-masked]>
Date: Tue, 15 Jun 2021 23:14:34 +0200

Julian,

> something else; Robert Sparks would know).

Thanks!

> It's the *input* on what is runs that changed.

Please explain, so that the bug report i would write is as correct
as possible. AFAIK, the input did have section numbers before and past
the new rfc changes. Likewise do the htmlized output have section
heading tags before and after. Just after those section heading tags
have no hotlinks to them in the toc anymore.

Cheers
    Toerless

-- 
---
[email-masked]

---

From: Julian Reschke <[email-masked]>
Date: Tue, 15 Jun 2021 23:56:09 +0200

> have no hotlinks to them in the toc anymore.

After the format switch, the plain text version ceased to have page numbers.

Looking at this some more, I really do not understand yet why linking
the section number string in the TOC entry does not work anymore. Might
be a tiny change in the formatting that causes the regexp used for that
not to work anymore.

Best regards, Julian