Write spec in IETF RFC style

[zkat]

Regardless of when we decide to submit KDL for consideration as an Internet standard, it might make sense to rewrite the format of the KDL spec such that it meets the requirements for an IETF RFC.

This MUST NOT change any of the semantics of the spec, as it’s intended to just be a formatting change.

This is related to #460, since it’s one potential avenue for achieving it, but also I think it would be nice to have such a well-known, -understood, and formal structure to the KDL spec

This is very much open to community members to participate in and I expect it to be a somewhat laborious process with multiple people involved. If you’re someone in our community and you’re familiar with the RFC format and process, and you’d like to get involved, please do chime in! Any level of involvement and help is welcome. I’ve definitely never done this before.

[jyasskin]

I've done a preliminary conversion in main...jyasskin:kdl:main, whose result you can see at https://jyasskin.github.io/kdl/draft-marchan-kdl2.html.

I haven't proofread it in detail, but there are definitely some stylistic things still to clean up ([whitespace](#whitespace) turns into "Section 3.17" instead of "whitespace", and the horizontal rules in https://github.com/kdl-org/kdl/blob/main/SPEC.md#example-5 don't have a translation into the RFC markup language).

Before I do that stylistic pass and send a PR:

1. Now that you can see roughly what it'll look like, is this worth doing? If it's too ugly, we can still push IANA to list a provisional MIME registration without using this format.
2. Do you want this to replace SPEC.md in a single PR or live in parallel for a while?
3. What draft name do you want? https://authors.ietf.org/naming-your-internet-draft has the guidelines. Convention is to use the primary author's last name, but it won't hurt anyone if you prefer zkat or something else.

Any other comments are also welcome.

[zkat]

@jyasskin I really like this! Thanks for taking the time.

I was thinking recently that maybe we should have both the RFC-style and the “classic” spec, but I think your example makes clear that RFC style wouldn’t really take away from the readability, and might even add some clarity in key places.

One thing I’m wondering: are we required to use ABNF for official RFCs? While most of the grammar is probably translatable to it (though with maybe less readability), we do things like requiring non-greedy parsing that I don’t think ABNF accommodates. I clearly haven’t read enough RFCs :)

All in all I like this and it makes things feel much more cleaned-up and… “professional”?

Also, using my last name is fine. I’d prefer to use my full name for this if possible (Katerina Zoé Marchán Salvá), but my first last name without the accent (marchan) is fine for the file name.

[jyasskin]

ABNF is not required for describing syntax in RFCs. It's common, but for example, TLS has its own language, and HTTP Structured Headers include ABNF but say that the algorithmic parsing is normative. If this were going through a WG, you could get away with anything the community decided was worth it, and an Independent submission is supposed to be even more accepting. (The IESG might decide this is worth chartering a small WG for, since it might be a "foundational formats upon which standards are expected to be built", but you can deal with that when you get to it.)

I've fixed your name and guessed at the initials you want in the top of the document (https://github.com/cabo/kramdown-rfc/wiki/Syntax2#authors-contributors). I've sent #466, so you can let me know what should change there.

[nleanba]

Could you maybe rename the file back to SPEC.md or update the respective links?

Currently the kdl.dev homepage has multiple dead links as a consequence of this

[zkat]

@jyasskin is it ok for us to do this? Does the source markdown file require that specific name?

[jyasskin]

The tooling assumes this name format for the source. The source also doesn't look as nice as the rendered form now (e.g. it has the {{section-name}} links), so it's probably better to fix the links. It'd also be good to add a new SPEC.md that points at the new location, to catch external links that you can't update.

Finally, you had a link to the 2.0.0 version that pointed to a specific branch. I forget if I updated that, but you could submit this spec to the IETF datatracker (https://github.com/martinthomson/i-d-template/blob/main/doc/SUBMITTING.md) and have any versioned links point there.

[zkat]

The reason I haven't updated the website yet is because I think I need to make that gh-pages branch before the Action that builds the spec works again. I also think I'd like to start copying over the generated spec to the site so it can be hosted at https://kdl.dev/spec