Re: [Tools-discuss] Please provide feedback on a proposed reworking of the datatracker /doc/html/... pages

[John C Klensin <[e-mail]>]

Robert, Lars, and others,

Impressive piece of work but it feels closer to "almost finished
but in need of more iteration" than "just about done".  A few
observations, some left over from a few weeks ago:

(1) Like others, I find the "Contents" tab almost never works.
I've tried it with selected older RFCs, older I-Ds, contemporary
v3 I-Ds, and relatively recent RFCs.  I may just have had bad
luck, but only the latter seem to actually display the TOC.
Suggestion: if this is going to work on some documents and not
others, it would be helpful if, for the ones where it does not
appear but there is a TOC in the document, either 
 (i) the tab did not appear,
 (ii) an anchor were generated for the string "Table of
	Contents" and the "Contents" tab contained a link to it.
 (iii) some bit of text appeared under the tab indicating
	that the omission was deliberate and not a fault in the
	user's environment.
Clicking the Contents tab and finding nothing is unnerving.

(2) As I think was mentioned on the tools-discuss list, it would
be good to have email addresses, not just a link to a profile
page, for the authors.  The "Email authors" button is a nice
addition but, especially when there are a large number of
authors, one might reasonably want to contact only one or two of
them.

(3) I'm a bit confused by the "Email authors" button.  My
understanding is that, historically,
[e-mail] reached the authors while
[e-mail] might reach a somewhat larger list.  Has
that been changed such that the latter is effectively just an
alias for the former?

(4) Although I don't have an example handy, especially for a
document in the v3 period, it is not unheard of for authors to
change over the many versions of an I-D.  If, for example, the
I-D is at version 10 and authorship changed at version 3, if the
user clicks on "01", pulls up that version, and then clicks on
"Email authors", they will presumably still get a mailto: link
for [e-mail] which will presumably point to the
latest collection of authors, not the authors for -01.  That
also raises the question of whether the "Authors" list in the
right column will reflect the current (most recent) version or a
version that is pulled up by clicking one of the Version numbers.

(5) Many thanks for the correction to where links generated by
"[RFCnnnn]" or other citation anchors point.

(6) I haven't been able to make a good guess at the algorithm,
but sometimes, when "... RFC nnnn..." appears in running text, a
link is generated.  Sometimes it isn't.  Whatever the algorithm
is, having a line break between "RFC" and "nnnn" or a
construction like "... RFCs nnnn and mmmm" seems to suppress it.
I don't see this as a big deal as long as all of the citation
anchors are correctly picked up (in every document I looked at,
they are), but it might be worth a look.

(7) Possible bug mentioned previously: If one looks at
https://sandbox-htmlize.ietf.org/doc/html/draft-ietf-emailcore-rfc5321bis-13
(a long, messy, complex, document but current and in v3) some of
the sections that have entries in the TOC get anchors and links
and some don't, with no pattern at which I can guess.    That
document illustrates several of the other issues above.  It also
has nothing under the Contents tab -- if something were
generated there, it might be a particularly interesting test
case because the TOC of that document is most of seven pages
long.

(8) Also using rfc5321bis as an example, it has an index and
index entries such as 
    ALPHA  Section 4.1.2, Paragraph 2, Item 1
A link is generated for "Section 4.1.2", which is great, but the
paragraph and item information are apparently ignored.  The
ideal, at least, IMO, would be to generate a single link to the
item, not to link to the paragraph and send the reader hunting.
Sadly, the longer and more complex a document gets, the more
likely a TOC that always works is important, the more likely the
author is to include an index, and the more important it is that
index entries actually point to the item being indexed.

Of course, several of the comments above may just be arguments
for generating HTML from the XML source rather than htmlizing
plain text, but that is a different problem.

thanks,
   john


--On Thursday, September 22, 2022 14:53 -0500 Robert Sparks
<[e-mail]> wrote:

> We've set up https://sandbox-htmlize.ietf.org/ to help
> continue to get feedback on the htmlization changes a group
> led by Lars has been working towards.
> 
> These changes will replace/enhance how pages at /doc/html/...
> are built.
> 
> First - Many thanks to the tools-discuss participants who
> helped verify this temporary site's configuration, and have
> started providing feedback already on this thread:
> https://mailarchive.ietf.org/arch/browse/tools-discuss/?q=help
> %20check%20config