Subject: [rfc-i] semantics of <aside/>

From: Peter Saint-Andre <[email-masked]>
Date: Mon, 26 Apr 2021 10:49:02 -0600

Discussion in the XML change management team has identified a potential
issue with use of the <aside/> element in RFCs.

The HTML specification [1] says that aside content that "is tangentially
related to the content of the parenting sectioning content" and "could
be considered separate from that content".

Other, unofficial documents [2] state that content in an <aside/>
element can be deleted without affecting the main content. But it seems
that we really don't want to delete content from RFCs, even if they are
in an <aside/> element.

Do folks here with deeper knowledge of HTML semantics have more
definitive opinions?

Peter

[1] https://html.spec.whatwg.org/#the-aside-element

[2] https://www.w3docs.com/learn-html/html-aside-tag.html
_______________________________________________
rfc-interest mailing list
[email-masked]
https://www.rfc-editor.org/mailman/listinfo/rfc-interest

---

From: "HANSEN, TONY L" <[email-masked]>
Date: Mon, 26 Apr 2021 21:20:55 +0000

On 4/26/2021, 12:49 PM, "rfc-interest on behalf of Peter Saint-Andre" <[email-masked] on behalf of [email-masked]> wrote:

    Peter

    [1] https://html.spec.whatwg.org/*the-aside-element 

IMO, you should consider the <aside/> text as equivalent to non-normative, explanatory text. That is, the mainline text is accurate as it stands, but the aside gives more information "of potential interest to the audience." For example, might be an historic note.

That follows the normal definition of an aside one would find in a dictionary. For example, m-w.com says that an aside 

1 : an utterance not meant to be heard by someone especially : an actor's speech heard by the audience but supposedly not by other characters
2 : a comment or discussion that does not relate directly to the main subject being discussed : digression

I consider the <aside/> element as following that intent. 

No, it should not be deleted from an RFC. But you should be able to skip over the asides while reading the text and not lose anything truly relevant.

	Tony

---

From: "Martin Thomson" <[email-masked]>
Date: Tue, 27 Apr 2021 09:41:19 +1000

On Tue, Apr 27, 2021, at 07:20, HANSEN, TONY L wrote:
> No, it should not be deleted from an RFC. But you should be able to 
> skip over the asides while reading the text and not lose anything truly 
> relevant.

My sense matches that of Tony.  I start most of my <aside>s with "Note: ", and it seems like others do also.

I think that the xml2rfc styling of <aside> makes it hard to ignore, which is somewhat counter to this interpretation. Most "Note: " paragraphs in pre-existing RFCs are styled without a vertical bar.  The vertical bar is more appropriate for <blockquote>.

---

From: Julian Reschke <[email-masked]>
Date: Tue, 27 Apr 2021 06:07:48 +0200

> [2] https://www.w3docs.com/learn-html/html-aside-tag.html

The definition in RFC 7991 appears to be consistent with what the HTML
specs says.

Why do we care about "w3docs.com"?

Best regards, Julian

---

From: Julian Reschke <[email-masked]>
Date: Tue, 27 Apr 2021 06:11:13 +0200

> I think that the xml2rfc styling of <aside> makes it hard to ignore, which is somewhat counter to this interpretation. Most "Note: " paragraphs in pre-existing RFCs are styled without a vertical ba…

Agreed. See <https://trac.tools.ietf.org/tools/xml2rfc/trac/ticket/438>.

Best regards, Julian

---

From: Carsten Bormann <[email-masked]>
Date: Tue, 27 Apr 2021 08:22:46 +0200

On 27. Apr 2021, at 06:11, Julian Reschke <[email-masked]> wrote:
> 
> See <https://trac.tools.ietf.org/tools/xml2rfc/trac/ticket/438>.

I’d love to, but the server for that page times out.

Grüße, Carsten

---

From: Carsten Bormann <[email-masked]>
Date: Tue, 27 Apr 2021 11:48:51 +0200

I read this for the third time and I’m still not sure what the background behind your question is (I do understand the question itself and cannot answer it).

Do you have a problem with the way that <aside/> is defined in RFCXML?

* Stability: I believe this is mostly stable over the various documents.
* Usefulness: There are 172 instances of <aside/> in published RFCs, which I sample as mostly used for notes that help with questions (*) that are likely to come up but that are not fundamental to the understanding of the document.
* Misuse: There are some <aside/> elements that do contain what might be crucial text (**).
* Misunderstanding: The reader of future documentation of the RFCXMLv3 format (or the non-reader) might assume <aside/> has the same semantics in RFCXML that it has in HTML.

Or maybe you have a problem with the mapping that xml2rfc chooses for RFCXML <aside/> to HTML <aside/>?  Do you have a problem with the style semantics chosen for <aside/>  in the CSS?

We will rarely need actual “sidebars” in RFCXML, which is really what HTML5 <aside> was about IIRC (but then there is a terminology issue there as well: [1]).  So there is a bit of appropriation going on here, but I’m not sure that is a problem.

(In this pile of issues there is also the indistinguishability in rendering between <aside> and <blockquote>, and the related question of <blockquote> vs. <ul empty=“true”>, where the latter is closer in rendering to what we got out of the RFCXMLv2 idiom for block quotes.)

Grüße, Carsten

(*) How do you pronounce SCHC?
(**) Note: The ACK bitmap is 1 bit long and is always 1.
[1]: https://www.aastudio.fr/Sidebar-and-Aside-are-different.html

> On 2021-04-26, at 18:49, Peter Saint-Andre <[email-masked]> wrote:
>

---

From: Peter Saint-Andre <[email-masked]>
Date: Tue, 27 Apr 2021 10:38:40 -0600

Hi Carsten,

> We will rarely need actual “sidebars” in RFCXML, which is really what HTML5 <aside> was about IIRC (but then there is a terminology issue there as well: [1]).  So there is a bit of appropriation go…

I'm not sure there is an active problem, either!

The worry is that some (seemingly non-canonical) interpretations of HTML
<aside/> indicate that its content can be hidden from the user without
harm, but that is very much not the case for RFCs (and we wouldn't want
the developer of an RFC-related tool to do so). I posted to this list in
hopes that someone (like Mark or Julian) who is closer to the HTML spec
could disabuse me of the worry.

Personally I'm not worried about usefulness or misuse, although of
course it's always good to use the right semantic tool for the job.

Peter

---

From: Kent Watsen <[email-masked]>
Date: Mon, 26 Apr 2021 17:40:54 +0000

No, but I’m using <aside> and got the following WGLC comments:

1) the plain-text rendering was non-obvious [this isn’t an issue for PDF/HTML as a shaded box is rendered] - maybe a different character than ‘|’ (e.g., ‘#’), or an ASCII-box, would be help?  Footnotes/endnotes serve the same purpose and are less distracting to the content-flow, thoughts about using instead?

2) all text is relevant and should be draft-level text (i.e., no need for asides).  However, in my use, the text could’ve been deleted without negative affect, so my response was along the lines of leaving it to the copyeditor to resolve.

K.

> On Apr 26, 2021, at 12:49 PM, Peter Saint-Andre <[email-masked]> wrote:
>

---

From: "Martin Thomson" <[email-masked]>
Date: Wed, 28 Apr 2021 15:45:59 +1000

On Tue, Apr 27, 2021, at 03:40, Kent Watsen wrote:
> 1) the plain-text rendering was non-obvious [this isn’t an issue for 
> PDF/HTML as a shaded box is rendered] - maybe a different character 
> than ‘|’ (e.g., ‘#’), or an ASCII-box, would be help?  
> Footnotes/endnotes serve the same purpose and are less distracting to 
> the content-flow, thoughts about using instead?

As Julian implied in his response to the issue he cited, there is no reason to insist on visual distinction at all.

Rendering with an indent might make it indistinguishable from other semantic elements in plain text, but there a lots of semantic details that the plain text rendering erases (like <xref format=none>) and that is perfectly OK.
 
> 2) all text is relevant and should be draft-level text (i.e., no need 
> for asides).  However, in my use, the text could’ve been deleted 
> without negative affect, so my response was along the lines of leaving 
> it to the copyeditor to resolve.

I don't think we should ever just leave it to the copyeditors.  Authors and editors should decide whether text is useful.  Useful text is included; everything else is dropped.  After that, the use of appropriate elements ensures that semantics are preserved.  If the text really is tangential to the main thread of the text, then <aside> is entirely appropriate for use.