search

martinthomson / i-d-template

A template for IETF internet draft git repositories
Other
208 stars 182 forks source link

Generated index to use title (instead of abbrev) #333

Closed dwaite closed 2 years ago

dwaite commented 2 years ago

Use the more descriptive and appropriate full title for the specification in the generated index, rather than the abbreviation.

dwaite commented 2 years ago

The behavior was changed in September, 2021 . From the terse commit message, I can't tell if complete omission of the title was intended change.

https://github.com/martinthomson/i-d-template/commit/9d741431a2f9f2037cd0d8dee8ea1c2dc2117970

Perhaps the proper fix, if there are projects for which either a terse or more fully specified list is needed, is to move styling to a stylesheet which is copied in. Then, a repo stylesheet (if present) could override the default shipped stylesheet.

martinthomson commented 2 years ago

The change was deliberate. It was to support displays like https://httpwg.org/http-extensions/ where a longer name in the table is onerous. Are there examples where the abbreviated title doesn't work or ends up being misleading? I realize that we should perhaps put a title attribute with the full title on the link as well. Would that be helpful?

dwaite commented 2 years ago

Due to #332 I can't point to a working page that shows the issue. Instead, I'll propose a more hypothetical example:

A single repo for an in-progress RFC 2616, "Hypertext Transfer Protocol -- HTTP/1.1" with an abbreviated title of "HTTP/1.1" would not have enough context on the rendered page for someone to understand what tapping the hyperlink will do. They may be more likely to look at the 'plain text' version, perhaps interpreting the "HTTP/1.1" link to point to working group process information rather than a HTML build of the specification.

Since the issue is that the generated HTML does not have sufficient context, anything which provides more context will be more intuitive to the user.

Examples of more context would be a group that has more specifications (such as the decomposition of HTTP/1.1 as part of the "bis" work).

The odds of the user interpreting this correctly are also higher when abbrev is interpreted by the author as "shortening over overly long titles" rather than "abbreviated form of name").

dwaite commented 2 years ago

As generation of an index is more of a bike-shedding issue, I'm thinking of adding functionality to generate a JSON metadata file. That would allow another action in the pipeline to overwrite/generate whatever HTML index they desired.

martinthomson commented 2 years ago

If you work out what you want, I'm happy to help facilitate. Creating extra files on gh-pages isn't that much of a big deal.