search

ietf-tools / xml2rfc

Generate RFCs and IETF drafts from document source in XML according to the IETF xml2rfc v2 and v3 vocabularies
https://ietf-tools.github.io/xml2rfc/
BSD 3-Clause "New" or "Revised" License
68 stars 38 forks source link

All HTML and PDF links must be hightlighted #1058

Closed ajeanmahoney closed 10 months ago

ajeanmahoney commented 10 months ago

Describe the issue

The effect of PR #963 on xml2rfc HTML output was discussed with the RFC Series Advisory Board (RSAB), which has determined the following:

The RSAB confirms that RFC7993 specifies a policy that requires highlighting of links “for example, through the use of color and/or text decoration”. ... Different handling for links that are used to link terms to a section or definition would require an update to RFC7993. Therefore all links in an RFC must be highlighted.

The details of the assessment can be found here: https://mailarchive.ietf.org/arch/msg/rsab/F9QOvdVX2amsX1bgR4DGVTzQat8/

Please roll back #963.

Code of Conduct

kesara commented 10 months ago

Revert PR #1060 only reverts changes from PR #963. But the figure captions still have the same issue with unhighlighted links (this has been the case for some time). For example: https://www.rfc-editor.org/rfc/rfc9001.html#figure-1

ajeanmahoney commented 10 months ago

Just adding some notes here regarding the figure and table captions: Since the first v3 RFC (RFC 8650), both the figure label (e.g., "Figure 1") and figure caption (e.g., "TLS Layers") link to the top of the figure, but these links are only noticeable when the reader hovers a mouse cursor over them. There is some documentation in Implementation notes for RFC7991 regarding the figure caption. Table labels and captions work the same way.

The accessibility spot check report mentions these double links (label and caption), and says the following:

If it is important to allow users to share the diagram using the fragment URL then use only one link to encompass the caption text and ensure that the link targets the <figure> container.

Note that users may achieve a similar outcome by using the permalink for the section heading. If this feature is sufficient, the link mark-up can be removed from both text elements in the caption.

Maybe the visibility of label and caption links should be a separate issue.