Re: [rpat] Links in draft-ietf-ohai-ohttp

[Sandy Ginoza <[e-mail]>]

Thanks for your replies.  We agree that readers benefit from consistent handling.  We have recommended that the authors limit the links and index entries to those that will assist the reader.  If you’re interested, our message is available at <https://mailarchive.ietf.org/arch/msg/auth48archive/t5YmeMiZq7Vm71KmVXOVWyP-dBg/>. 

Sandy 

> On Oct 10, 2023, at 9:52 AM, Alexis Rossi <[e-mail]> wrote:
> 
> Hi,
> 
> I agree that the RPC should require documents to use a consistent style for the benefit of RFC readers. 
> 
> Frankly, I also think the PRC should probably require a more restrained use of anchor links, unless there’s a very clear reason why this draft needs to have this many.
> 
> Alexis
> 
> 
> 
>> On Oct 10, 2023, at 4:31 AM, Jay Daley <[e-mail]> wrote:
>> 
>> Hi Sandy
>> 
>> In general, I think the RFC series is better off with a consistent style and in particular it is vital that we have a consistent approach to the user experience of the information architecture of RFCs because these are inherently complex documents.
>> 
>> On that basis, my starting position is to advise you to not allow this styling as it is a significant deviation from the common style.  However, if the authors were able to identify a unique problem that this action is intended to solve, and if you were to agree that this is best way to solve it, then you should adopt it, but only if it is clearly documented, well explained and then used in future cases where the same problem exists.
>> 
>> Finally, a note about 'deprecated'.  My read of RFC 7991 section 1.2 is that we should consider that that certain parts of the vocabulary were  deprecated and not removed, solely to allow a v2 document to work under v3, not for those to be used in new documents.  Therefore deprecated elements/attributes should not be allowed in RFCs.
>> 
>> Jay
>> 
>>> On 9 Oct 2023, at 22:46, Sandy Ginoza <[e-mail]> wrote:
>>> 
>>> Hi again,
>>> 
>>> It turns out that our initial assessment was wrong.  Thanks to Paul Hoffman for pointing out that it is the use of format=“none” that results in “lighter styling on internal irefs” and that format=“none” is deprecated by RFC 7991 [1] (more on this below).  For example, format=“none” causes links to Oblivious Gateway Resource to appear in black.
>>> 
>>>   <li>a method for forwarding these encapsulated messages between
>>>   clients and an <iref item="Oblivious Gateway Resource"/><xref
>>>   target="dfn-gateway" format="none">Oblivious Gateway Resource</xref>
>>>   through a trusted <iref item="Oblivious Relay Resource"/><xref
>>>   target="dfn-relay" format="none">Oblivious Relay Resource</xref> using
>>>   HTTP, and</li>
>>> 
>>> draft-ietf-ohai-ohttp has been moved to AUTH48 as RFC-to-be 9458.  You can view the effects in the HTML; see item 2 of the introduction [2].
>>> 
>>> While format=“none” is deprecated by RFC 7991, Henrik provides rationale for keeping it; see
>>> Henrik’s implementation notes [3].  It also appears in version 3 of the XML vocabulary as implemented [4] (see related discussion in issue 17 [5]).
>>> 
>>> Our question remains the same, do you think it's acceptable for this styling to appear in RFCs, even though links are expected to be differentiated from surrounding text so the reader is aware of their presence?
>>> 
>>> Thanks,
>>> Sandy 
>>> 
>>> 
>>> [1] https://www.rfc-editor.org/rfc/rfc7991.html#section-2.66.1
>>> [2] https://www.rfc-editor.org/authors/rfc9458.html#section-1
>>> [3] https://www.ietf.org/archive/id/draft-levkowetz-xml2rfc-v3-implementation-notes-13.html#section-4.4.17
>>> [4] https://www.ietf.org/archive/id/draft-rswg-xml2rfcv3-implemented-02.html#name-format-attribute-2
>>> [5] https://github.com/rfc-format/draft-iab-xml2rfc-v3-bis/issues/17
>>> 
>>> 
>>>> On Oct 6, 2023, at 12:52 PM, Sandy Ginoza <[e-mail]> wrote:
>>>> 
>>>> Greetings all,
>>>> 
>>>> draft-ietf-ohai-ohttp contains a number of links that are invisible to the user because they are not differentiated from the surrounding text (i.e., they appear in black, see #5071 regarding "lighter styling on internal irefs”).  Note that the display is tied to a combined use of <xref> and <iref>, so links that typically appear in blue are now displayed in black (for example, in Section 2, compare how the link to "Section 8.2" appears as opposed to the the links for "Oblivious Gateway Resource”).
>>>> 
>>>> Our understanding is that links should be easily differentiable from surrounding text so the reader is aware of their presence.  Do you think it's acceptable for this styling to appear in RFCs?
>>>> 
>>>> Note that the links in earlier versions of draft-ietf-ohai-ohttp were distracting.  There was some discussion about this within the IESG, but excessive linking was not considered a blocking issue (see https://datatracker.ietf.org/doc/draft-ietf-ohai-ohttp/ballot/).  
>>>> 
>>>> If the lighter styling is not acceptable, it seems the authors should be encouraged to use <xref> to definitions and <irefs> more judiciously. 
>>>> 
>>>> Thanks,
>>>> Sandy 
>>>> 
>>>> -- 
>>>> RPAT mailing list
>>>> [e-mail]
>>>> https://mailman.rfc-editor.org/mailman/listinfo/rpat
>>> 
>>> -- 
>>> RPAT mailing list
>>> [e-mail]
>>> https://mailman.rfc-editor.org/mailman/listinfo/rpat
>> 
>> -- 
>> Jay Daley
>> IETF Executive Director
>> [e-mail]
>> 
>> -- 
>> RPAT mailing list
>> [e-mail]
>> https://mailman.rfc-editor.org/mailman/listinfo/rpat
>