[Rfc-markdown] Using kramdown-rfc with v3 (Re: [Tools-discuss] HTML vs HTMLized)

[Carsten Bormann <[e-mail]>]

Interesting discussion over at tools-discuss, some of which copied at the end.

One thing I didn’t say there is how to mix XML with markdown in kramdown:

Normally, you can just include XML wherever you need it:

Important German politicians usually have ASCII-compatible names, with very few exceptions, e.g., <u>Jürgen Möllemann</u>, and you know where that guy led us.

Now, sometimes you want to use some v3 feature that would envelope some normal text, e.g., the <aside> feature.  To use nested markdown inside manually entered XML markup, add:

<aside markdown="1">

Important German politicians usually have ASCII-compatible names, with very few exceptions, e.g., <u>Jürgen Möllemann</u>, and you know where that guy led us.

</aside>

The quotes around the 1 in markdown=“1” are needed.  (More on markdown=“1” and some variants in https://kramdown.gettalong.org/syntax.html .)

There are some limitations (trying to avoid the word “bugs” here) of the xml2rfc v2 to v3 conversion.  Most notably, it does not handle beyond-ASCII characters in some of the structured information.  Kramdown-rfc2629 has one workaround for that at the moment:

    name: Carsten Bormann
    org: Universität Bremen TZI
    orgascii: Universitaet Bremen TZI

I’m still considering ways to handle v3’s “ascii” convention in ways that are less intrusive, but for v2 to v3 version, really this limitation im xml2rfc needs to be fixed first.

Grüße, Carsten


> On Dec 5, 2019, at 20:54, Carsten Bormann <[e-mail]> wrote:
> 
> On Dec 5, 2019, at 18:27, Michael Richardson <[e-mail]> wrote:
>> 
>> kramdown-rfc2629 version 1.2.13 says:
>> 
>> dooku-[~](2.6.5) mcr 10052 %kramdown-rfc2629 -h
>> Usage: kramdown-rfc2629 [options] file.md|file.mkd > file.xml
>>   -v, --[no-]verbose               Run verbosely
>>   -3, --[no-]v3                    Use RFCXML v3 processing rules
>> 
>> which is new compared to 1.2.12.  But, maybe it doesn't do very much yet :-)
>> I'm hoping Carsten will educate us...
> 
> Indeed, the route towards v3 goes through v2 at this time.
> 
> As Henrik mentioned, xml2rfc has a compatibility mode and can process v2 and convert v2 to v3.
> For now, this is likely to be a more stable approach than direct v3 generation.
> 
> I admit this is a somewhat lazy way of handling this, but I also believe this is in the best interest of kramdown-rfc’s users: stability is the most important feature of kramdown-rfc.
> 
> If you actually need a new v3 feature (artsets anyone?), you are better off writing the XML on your own, in particular during a period where these features aren’t really stable.  When patterns of usage emerge here that actually can be expressed in markdown, I’ll sure go ahead and implement them.  And when we have an approved document for v3, directly generating v3 is likely to be stable enough. 
> 
> I’m going to stop going into details here.  Note that there is a (very low volume(*)) rfc-markdown list that should be hosting any specific discussions:
> 
> https://www.ietf.org/mailman/listinfo/rfc-markdown
> 
> Grüße, Carsten
> 
> (*) Well, that might change slightly as we embrace v3.
>