Subject: [Tools-discuss] placing < and > in artwork renders broken html

From: Paul Wouters <[email-masked]>
Date: Wed, 5 May 2021 22:31:10 -0400 (EDT)

I have an issue with artwork that renders badly in html on the site:

<artwork>    struct {
         uint16 ExtSupportLifetime;
         opaque AuthenticationChain&lt;1..2^16-1&gt;;
     } DnssecChainExtension;
</artwork>

I am expecting to see:

        struct {
            uint16 ExtSupportLifetime;
            opaque AuthenticationChain<1..2^16-1>
        } DnssecChainExtension;

but the rendered html (from www.ietf.org/staging/) displays:

     struct {
         uint16 ExtSupportLifetime;
         opaque AuthenticationChain&lt;1..2^16-1&gt;
     } DnssecChainExtension;

If use literal < or >, then xml2rfc complains and won't render my .txt output.

Worse but unrelated, the rfc markdown stuff generates &amp;lt; _and_
changes all quotes to &quot; and yes these two bugs amplify each other.

I hope someone in the future can fix all the badly rendered html format in RFCs/drafts.

Paul

---

From: Carsten Bormann <[email-masked]>
Date: Thu, 6 May 2021 06:58:45 +0200

Hi Paul,

>        opaque AuthenticationChain&lt;1..2^16-1&gt;;

That is what <[CDATA[ sections are good for:

<artwork><![CDATA[
  struct {
]]></artwork>

(This example generated by “the rfc markdown stuff”.)

>        opaque AuthenticationChain&lt;1..2^16-1&gt;

Care linking to the specific file?

The specific example above generates this html for me:

<div class="artwork art-text alignLeft" id="section-1-10">
<pre>
  struct {
      uint16 ExtSupportLifetime;
      opaque AuthenticationChain&lt;1..2^16-1&gt;
  } DnssecChainExtension;
</pre><a href="#section-1-10" class="pilcrow">¶</a>
</div>

Which renders as attached below (not sure that will make it through this ML).

> If use literal < or >, then xml2rfc complains and won't render my .txt output.

As it should.

> changes all quotes to &quot; and yes these two bugs amplify each other.

I don’t know which rfc markdown stuff you are referring to (there is a choice!), but see above for what is generated by rfc-kramdown.

We wouldn’t have got to RFC 9000 if what you are experiencing were a common problem, so we do need to know some details.

Grüße, Carsten

---

From: Julian Reschke <[email-masked]>
Date: Thu, 6 May 2021 15:32:26 +0200

Am 06.05.2021 um 04:31 schrieb Paul Wouters:
> ...

It would be best if you attached sample XML; at this point I'm not sure
whether what you have got through properly.

*If* your intent is to have the "16" in 2^16 in superscript, you can use:

>         opaque AuthenticationChain&lt;1..2&#xb9;&#x2076;-1&gt;;
>     } DnssecChainExtension;
> </artwork>

(I've used numeric character references here to avoid transmission
problems).

I've tested this with current xml2rfc in v3 mode, and it appears to
generate the desired HTML.

Best regards, Julian

---

From: Paul Wouters <[email-masked]>
Date: Thu, 6 May 2021 10:48:47 -0400 (EDT)

>      opaque AuthenticationChain<1..2^16-1>

Ahhh, I have used (copied it from others) before. I didn't realise I
needed it here! But the markdown didn't generate that ofr me.

> Care linking to the specific file?

https://tools.ietf.org/html/draft-dukhovni-tls-dnssec-chain-05

That is me tweaking the xml and txt artisanally though. The original .md
file (and the Makefile with my sanitizing hacks) is at:

https://github.com/vdukhovni/dnssec-chain-extension

> I don’t know which rfc markdown stuff you are referring to (there is a choice!), but see above for what is generated by rfc-kramdown.

Yes rfc-kramdown :)

> We wouldn’t have got to RFC 9000 if what you are experiencing were a common problem, so we do need to know some details.

I'm sure it's me, and you've already helped me a step in the right
direction. Thanks!

Paul

---

From: Carsten Bormann <[email-masked]>
Date: Thu, 6 May 2021 16:56:12 +0200

> needed it here! But the markdown didn't generate that ofr me.

To clarify, you are talking about the tool called mmark.

>> I don’t know which rfc markdown stuff you are referring to (there is a choice!), but see above for what is generated by rfc-kramdown.

I was trying to say kramdown-rfc, but misstated.
(Kramdown-rfc and mmark are the two markdown-to-rfc tools available right now.)

> direction. 

Great!

Grüße, Carsten

---

From: Julian Reschke <[email-masked]>
Date: Thu, 6 May 2021 17:38:21 +0200

> needed it here! But the markdown didn't generate that ofr me.

You don't need it.

Either you use a CDATA section, *or* you ampersand-escape the critical
characters.

> https://github.com/vdukhovni/dnssec-chain-extension

That file appears to contaion "&gt;" instead of ">"
(<https://github.com/vdukhovni/dnssec-chain-extension/blame/master/draft-dukhovni-tls-dnssec-chain.md#L257>).
Maybe that's the only issue here?

Best regards, Julian

---

From: Carsten Bormann <[email-masked]>
Date: Thu, 6 May 2021 18:04:30 +0200

> Maybe that's the only issue here?

Probably, but then somebody put those there, possibly after a previous malfunction of some tool, which we should try to dig out if true.
(Maybe the markdown conversion was just done manually and incompletely, though.)

Grüße, Carsten

---

From: Julian Reschke <[email-masked]>
Date: Thu, 6 May 2021 18:24:41 +0200

> Either you use a CDATA section, *or* you ampersand-escape the critical

FWIW, because this is such FAQ, the spec has an entire section about
that topic:
<https://greenbytes.de/tech/webdav/rfc7991.html#cdata.and.escaping>.

Best regards, Julian

---

From: Carsten Bormann <[email-masked]>
Date: Thu, 6 May 2021 18:33:26 +0200

> <https://greenbytes.de/tech/webdav/rfc7991.html#cdata.and.escaping>.

Yeah, and that perpetuates the myth of needing to escape “>”…

(Yes, I learned about that rare species “]]>” in XML 101, which you only ever need when making examples about CDATA.)

Sorry, pet peeve.  (You can now go ahead and escape all “/” in JSON as well :-)

Grüße, Carsten

---

From: Julian Reschke <[email-masked]>
Date: Thu, 6 May 2021 19:02:20 +0200

> Yeah, and that perpetuates the myth of needing to escape “>”…

It does in the prose:

"A common problem authors have with <artwork> and <sourcecode> elements
is that the XML processor returns errors if the text in the artwork
contains either the "&" or "<" character, or the string "]]>". To avoid
these problems, the "&" and "<" characters may be escaped using the
strings "&amp;" and "&lt;", respectively; the "]]>" string can be
represented as "]]&gt;". Alternatively, they may be surrounded in a
CDATA structure: "<![CDATA[]]>". (...)"

...but the example below is indeed misleading.

-> <https://www.rfc-editor.org/errata/eid6574>

I should have cited RFC 7749, which indeed says:

> ">" does not require escaping, unless it appears in the sequence "]]>" (which indicates the end of a CDATA section; see below).

Best regards, Julian