Subject: [Rfc-markdown] 1.3.34: map most codeblock classes to <sourcecode> instead of <artwork>

From: Carsten Bormann <[email-masked]>
Date: Thu, 18 Feb 2021 18:27:01 +0100

RFCXMLv3 introduces a second element for verbatim text beyond
<artwork>, the <sourcecode> element.
So kramdown-rfc needs to decide whether a codeblock turns into
<sourcecode> or into <artwork>.

1.3.34 now maps all code blocks with a language given to sourcecode,
except if the language is one of (ascii-art binary-art call-flow
hex-dump svg).
(This exception list was appropriated from RFC 7991; the current
xml2rfc documentation doesn't mention call-flow or hex-dump.)

So

~~~
/\
\/
~~~

still turns into <artwork>, while

~~~ c
int dezigzag(unsigned int i) {return (i>>1) ^ -(i&1)}
~~~

turns into <sourcecode> (with type="c").

Using the "gi" pseudo-attribute, this automatic choice can be
overridden (use gi="artwork" or gi="sourcecode" in an inline attribute
list).

Note that for both artwork and sourcecode, additional attributes need
to be notated as "artwork-foo" (or "sourcecode-foo") in an inline
attribute list, as the codeblock itself turns into a
<figure> around the artwork/sourcecode, so you can have title etc.

An example with an inline attribute list (IAL):

~~~ c
main() { return 1; }
~~~
{: #my-little-c-program artwork-name="myli.c" title="My little C program"}

or, to keep the actual source outside the markdown

~~~ c
{::include myli.c}
~~~
{: #my-little-c-program artwork-name="myli.c" title="My little C program"}

(kdrfc -c will generate a .v2v3.xml that includes the text, so it can
be directly submitted to the datatracker.)

Note that the conventional type strings listed in [0] are all
lower-case; I'm sorry if this violates your sense of aesthetics as
much as mine :-)

Over at the github issue [77], which this release resolves, we also
discussed using media-type-names (or content-types [1]) as types --
this strikes me as a great convention.

Grüße, Carsten

[0]: https://www.rfc-editor.org/materials/sourcecode-types.txt
[77]: https://github.com/cabo/kramdown-rfc2629/issues/77
[1]: https://www.ietf.org/archive/id/draft-bormann-core-media-content-type-format-02.html

---

From: Carsten Bormann <[email-masked]>
Date: Thu, 18 Feb 2021 21:48:47 +0100

Bizarrely, RFCXMLv3 does not allow an “align” attribute on <sourcecode>, while it does on <artwork>.  This, together with the automatic assignment of <sourcecode> to appropriately classed code blocks added in 1.3.34, creates a backwards compatibility problem.  

This is now worked around by reverting to <artwork> for any code blocks that do have “artwork-align”/“sourcecode-align” inline attributes, regardless of type.
So if you want your source code to turn up as <sourcecode>, do not center/right-adjust any more.

We apologize for the inconvenience.

Grüße, Carsten

---

From: Miek Gieben <[email-masked]>
Date: Fri, 19 Feb 2021 08:24:02 +0100

[ Quoting <[email-masked]> in "[Rfc-markdown] 1.3.34: map most cod..." ]
>turns into <sourcecode> (with type="c").

Note that mmark does exactly the same.

Regarding your other email on the alignment of artwork vs sourcecode, I think that must
be fixed in the schema, rather than working around it from our side.

---

From: Carsten Bormann <[email-masked]>
Date: Fri, 19 Feb 2021 08:33:21 +0100

> be fixed in the schema, rather than working around it from our side.

Yes.  The question really is on what timescales this can happen.
We have been waiting for some fixes for some time.
RFCEDP is still discussing on one end.
Somebody has to do the xml2rfc fixes on the other side.
Let’s see...

Grüße, Carsten

---

From: Julian Reschke <[email-masked]>
Date: Fri, 19 Feb 2021 09:06:24 +0100

Am 19.02.2021 um 08:24 schrieb Miek Gieben:
> ...

FWIW, I'm not sure what the use case for not left-aligning source code is?

Slightly related to this: it seems we need to come up with
recommendations about what is artwork and what is sourcecode. For
instance, in the HTTP specs, is a HTTP message example (or a header
field example) artwork or sourcecode?

Best regards, Julian

---

From: Carsten Bormann <[email-masked]>
Date: Fri, 19 Feb 2021 09:45:59 +0100

> FWIW, I'm not sure what the use case for not left-aligning source code is?

I had one just yesterday…

https://datatracker.ietf.org/doc/draft-bormann-core-media-content-type-format/

(In a normal publication I’d use color.)

> field example) artwork or sourcecode?

I’d say:
Q: Is it meant for machine consumption?
No?  Artwork.

Examples:

PEM, CBOR-diag, JSON data items that can be parsed: source code.
ABNF, CDDL, YANG: source code (but see example above)
Pseudocode, C, Python: source code

Math: artwork
Illustrative excerpts of code for human consumption: artwork
Call-flows (example in RFC 7991), HTTP interactions: artwork
UML stuff, MSCs, flow charts, GANTT charts: artwork

(Deliberately) Bad code (counterexamples): Hmm.

Grüße, Carsten

---

From: Carsten Bormann <[email-masked]>
Date: Fri, 19 Feb 2021 09:47:57 +0100

> https://datatracker.ietf.org/doc/draft-bormann-core-media-content-type-format/

Sorry, my intent here is probably better visible in the current editor’s version:

https://cabo.github.io/mtct/draft-bormann-core-media-content-type-format.html

Grüße, Carsten

---

From: Julian Reschke <[email-masked]>
Date: Fri, 19 Feb 2021 09:53:45 +0100

> field example) artwork or sourcecode?

-> <https://github.com/rfc-format/draft-iab-xml2rfc-v3-bis/issues/195>

Best regards, Julian

---

From: Julian Reschke <[email-masked]>
Date: Fri, 19 Feb 2021 10:03:08 +0100

> https://cabo.github.io/mtct/draft-bormann-core-media-content-type-format.html

So I see
<https://cabo.github.io/mtct/draft-bormann-core-media-content-type-format.html#name-discussion>:

>  7. Discussion
>
> The ABNF given here is provisional and may need some more cleanup: We need to unify the various forms of reg-name, token, etc.
> (ABNF just shown for illustration is centered, in an aside, and tagged with <artwork type="abnf;old"...> in the XML, while the normative ABNF of this memo is left-aligned and tagged with <sourcecode type="abnf"...>.)We need to discuss case-insensitivity, which is usually rather insensitive.

FWIW, if you cite a specific piece of ABNF from other specs for
illustration, why not use <blockquote> for that? That should make the
distinction very visible.

Best regards, Julian

---

From: Jay Daley <[email-masked]>
Date: Mon, 22 Feb 2021 08:56:54 +1300

> On 19/02/2021, at 9:47 PM, Carsten Bormann <[email-masked]> wrote:
> 

I’m not sure I understand - do you mean that you want it indented to show that you are quoting the ABNF or do mean that you want a different alignment.  I ask because I can’t see a different alignment.

Jay

> 
> Grüße, Carsten
> 
> _______________________________________________
> Rfc-markdown mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/rfc-markdown

-- 
Jay Daley
IETF Executive Director
[email-masked]

---

From: Carsten Bormann <[email-masked]>
Date: Mon, 22 Feb 2021 01:38:19 +0100

>> https://cabo.github.io/mtct/draft-bormann-core-media-content-type-format.html <https://cabo.github.io/mtct/draft-bormann-core-media-content-type-format.html>
> 

I was essentially trying to separate the ABNF quoted for reference from the ABNF that is part of this specification.
As you can see, this doesn’t work very well in the HTML (better for figure 1, where it is obvious this is centred, than for figure 4).
The distinction is much easier to see in the plaintext, where aside/blockquote get much stronger visual support.

So this may not be the perfect example, but it was a case where I was trying to center source code.

My criticism of the current grammar is that there are lots of arbitrary differences between different contexts in which things can be used, and these arbitrary differences seem to be driven by the combination of (1) a desire to enforce a weird perception of “good style” with (2) a lack of imagination.  Much less of this would probably have happened if the grammar had been properly factorized.  The grammar style to repeat everything everywhere seems to suggest one should endlessly tweak any single one of the clones so they are all subtly different, leading to the current jungle.

CCing rfc-interest, because this is a problem not with, but for writing IETF documents in markdown.

Grüße, Carsten