kramdown-rfc
kramdown-rfc copied to clipboard
cabo
boilerplate: Add bcp26 and bcp26-tagged by analogy with bcp14, bcp14-tagged
bcp 26 ("SPECIFICATION REQUIRED", "EXPERT REVIEW", etc) has some comparable boilerplate to bcp 14 ("MUST", "SHOULD", etc).
It'd be nice to offer the same boilerplate functionality in kramdown-rfc for bcp 26 as is offered for bcp 14.
One thing to note is that some documents might only have a limited set of the bcp 26 keywords (e.g. a draft that asks only for SPECIFICATION REQUIRED but never for EXPERT REVIEW). The fanciest thing to do would be to generate the boilerplate based on the content of the rest of the draft, only mentioning specific keywords in the generated boilerplate if they show up in the text.
Do you have an example for a document that carries that boilerplate? I usually do the 8126 explanations manually.
draft-ietf-openpgp-crypto-refresh says:
The key words "PRIVATE USE", "SPECIFICATION REQUIRED", and "RFC REQUIRED" that appear in this document when used to describe namespace allocation are to be interpreted as described in [RFC8126].
(this is the document where this came up for me -- i'm trying to help the editors streamline the kramdown source)
I haven't seen that usage yet. I can't find upper case "SPECIFICATION" in such a context in any recent RFC. Indeed, RFC 425x and RFC 4880 use something that looks like boilerplate, but that hasn't had any imitators in the last 15 years.
Hm, i hadn't realized it was such an idiosyncratic thing. If you think it's too unusual to be worth including in kramdown-rfc, feel free to close this issue. If you think it might be useful to encourage more people to tag their documents appropriately, let me know. my ruby is pretty rusty, but i can also try to take a crack at a PR if you're interested.
A PR is made easily (see boilerplate(key) in line 77 of lib/kramdown-rfc/command.rb). I'm more concerned about having an agreed modern (4880 used 2434!) variant of this. Also, there is no element like <bcp14 that could be used for tagging these keywords. My style meter also flags long uppercase phrases like FIRST COME FIRST SERVED or SPECIFICATION REQUIRED...
hm, so maybe the first thing would be to prod the xml2rfc folks to define a <bcp26> element?
They cannot really do this any more without action from the to-be-formed RSWG, and I'm afraid that has a ton of other things on its plate already. Unfortunately, there also is no way to evoke the bold small caps that are used to style <bcp14, so we can't even fake it on the authoring side.
ok, so it sounds like i'll need to put the labelling/tagging thing on hold (i've indicated interest on the xml2rfc list), and maybe this issue can focus on the boilerplate for now. I'll see about writing up some support for at least the boilerplate for bcp26.
I'm interested in the idea of only having the terms in the boilerplate that are actually being used. This may require a little amount of hacking, but I think it is worth that.
Per my note to the mailing list, how about thinking about XML to describe IANA registries and entries so we can automate 90% of the update process rather than 2%?
fwiw, i recently spoke to some of the IANA folks, and they suggested to me that as long as any relevant registries were clearly identified as tables in the document, their work would be greatly simplified.