[Rfc-markdown] 1.6.1: v: 3

[Carsten Bormann <[e-mail]>]

For a long time, kramdown-rfc has been defaulting to RFCXMLv2.
xml2rfc already switched to default v3 with xml2rfc 3.0.0 in
2020-09-04.

It is time that kramdown-rfc does, too.

Changing a default creates a flag day.
As I hinted at before, the flag day is 2022-02-22 at 22:02:22 UTC.

At this time, all Makefiles/build scripts that still want to use the
v2 formatter (why?) and are not providing the -2/--v2 flag to the
kramdown-rfc tools will break.
Simultaneously, a few broken tools [1] will spontaneously start
working (once they have been updated to the current kramdown-rfc gem).

I'm using the opportunity to make a few other overdue changes, too.

(1)

The kramdown-rfc2629 gem now is accompanied by the kramdown-rfc gem.

kramdown-rfc is the official name of the tool, and for people who want
to use it under that name, there now is a gem with that name.
(This gem currently simply installs the kramdown-rfc2629 gem;
fully renaming gems is too much work with rubygems.
But you can forget the number 2629 now.)

(2)

Similarly (independent of which of the gems you have installed), the
kramdown-rfc2629 command is now accompanied by the kramdown-rfc
command.
This does the same, but already defaults to v3 today.

(3)

All kramdown-rfc processors (kdrfc, kramdown-rfc, kramdown-rfc2629)
now have -2 and -3 flags.  (The separate kdwatch gem is v3 only.)

These flags are about the output, not the input:
You only need to give -2 if you really need to make a document look
like it's 2016.

When you use kdrfc as the driver, -2 also switches the xml2rfc called
(which defaulted to --v3 since 2020-09-04) to --v2 (--legacy) mode
instead.

(4)

A new parameter is available for the YAML header:

    v: 3

can be used to override the command line default -2/-3.

That may not be particularly useful for the day left where the
default is still -2, but it also updates a few more defaults, which
therefore do not need to be given explicitly any more:

ipr: trust200902
stand_alone: yes
pi:
  toc: yes
  sortrefs: yes
  symrefs: yes

These are defaults, so they can be overridden in the YAML.
Note that, if you do give any of the "PI" values instead of accepting
the default set by "v: 3", you also need to switch on sortrefs which
inexplicably is not the default with xml2rfc (while toc and symrefs
*are* with v3). [Unless you are playing a practical joke on your
readers, you need to switch on sortrefs, or, if you just want to
dazzle them a little less, switch off symrefs.]

So this reduces the YAML boilerplate a little bit.

"v: 3" is also very useful as a mark on a markdown source file to
indicate that it has been looked at with v3 glasses.

(I expect to put a few more hooks on "v: 3", so if you need the utmost
of stability, maybe try switching that parameter on with 1.6.2 or 1.6.3.)

        .oOo.

Please do try out kramdown-rfc 1.6.1 and the "v: 3" feature.
As usual, you can do a "gem update", but maybe you also want to do a

   gem install kramdown-rfc

I promise I'll fix new bugs in 1.6.1 quickly for the next 80 hours or
so...

Happy Internet-Drafting -- two weeks and half a day left until the
deadline for 113 strikes at 2022-03-07T23:59:00Z.

Grüße, Carsten

[1]: https://github.com/ietf-tools/ietf-at/pull/78