Convert to Markdown

[cabo]

I haven't fixed typos or outdated references. I did fix the outdated BCP14 boilerplate. I did not fix the placement of the acknowledgements section (see Section 4.10 of RFC 7322: should be in the back material). Many of the lists use a weird format; you should be using bullet points. References use an unusual convention, I have therefore not fixed Section references. Sourcecode-tagging is somewhat random, some claimed JSON isn't (you may want to use RFC 8972 folding), some JSON is not marked as such. I didn't use removeInRFC for the Changelog sections, as I probably should have. The inconsistent manual indentation of examples (relative-json-pointer) should be using align= attributes instead.

[gregsdennis]

Thanks for this @cabo.

For everyone else, I requested that the tool we used on the spec document for JSON Path (here) be used to convert our documents to kramdown to see what that would look like. I'd like as many people as possible to review this.

I know that @awwright requested that we finish with existing PRs first, but

• I feel the document format has been a hindrance long enough.
• Most open PRs haven't seen any movement in a long time and could be reworked easily enough.
• There are additional changes that I'd like to make (that we have issues for), and I don't want to wait for this to make them.

[jdesrosiers]

I'm definitely in the make-the-change-asap camp. However, what's the benefit of this solution over https://github.com/json-schema-org/json-schema-spec/pull/1357?

[gregsdennis]

However, what's the benefit of this solution over #1357?

I'm not sure there's an explicit benefit over that one. I think this is just another option, and one that's been used elsewhere. I wanted to bring this up again.

[cabo]

I'm definitely in the make-the-change-asap camp. However, what's the benefit of this solution over #1357?

I apologize for not explaining this; I didn't know this hasn't been discussed between the collaborators of this repo.

The existing files in this repo are in a format that we call RFCXML.
Since this format is not easy to author in, many authors of IETF-related documents generate the RFCXML from an authoring format. The specific markdown format that this PR is in, kramdown-rfc, is widely used as an authoring format for RFCXML. The tool kramdown-rfc (https://rfc.space) generates RFCXML right from the markdown.

Given that the existing files were in RFCXML, I assumed that submitting (some of) this work to the IETF at some point was possibly still in the cards. This ultimately would require generating RFCXML. Of course, you can write your own tool to generate RFCXML from a new markdown-based format that you develop, but that is somewhat redundant work and also may make it harder to collaborate with people at the IETF who are used to kramdown-rfc for authoring.

[gregsdennis]

Thank you for the additional info, @cabo. We're moving toward self-publishing, so maintaining some sort of IETF compliance isn't really a concern. We just want something that's easier to author.

To that end, migrating what we have into something more palletable, even if it's still an IETF format, is a good first step, which is why I asked about this tooling on the JSON Path mailing list.

Thanks for this contribution. I've had a scan of the document and aside from a few line wrapping artifacts (most likely due to us not managing line lengths), this looks really good.

[jdesrosiers]

Given that the existing files were in RFCXML, I assumed that submitting (some of) this work to the IETF at some point was possibly still in the cards. This ultimately would require generating RFCXML.

It was originally in RFCXML for that reason, but we've decided IETF is not the right path for this project an we're trying to move away from any perceived association with IETF. I knew there was a tool to convert RFCXML to kramdown-rfc and I expected that conversion would be a good first step to make it easier to convert to a non-IETF markdown format. But, since someone created a tool to convert directly from XMLRFC to github-flavored-markdown, it doesn't seem like we need this intermediate step.

Unless, @gregsdennis, you're proposing that we stick with kramdown-rfc? My concern with this approach has always been that the generated documents have "IETF" and "draft" and an expiration date and other things we don't want in our spec. @awwright demoed one time that a lot of those things could be hidden. I would be willing to consider using kramdown-rfc and the IETF toolchain as the endgame rather than just a stepping stone if it's possible to sufficiently mold it to our needs, but I don't think we know for sure that that's the case.

[gregsdennis]

Unless you're proposing that we stick with kramdown-rfc?

I am not making any proposals. I'm just trying to provide options.

[cabo]

My concern with this approach has always been that the generated documents have "IETF" and "draft" and an expiration date and other things we don't want in our spec.

RFCXML has a few flags you can use to get less of that boilerplate (kramdown-rfc mirrors these as the "topblock" and "private" flags in pi:; https://rfc.space has a brief example). I'm occasionally using this to generate reports that are not an RFC/trying to become an RFC.

Clearly, support for this is a secondary citizen in xml2rfc land.
But I do think some fixes could be made if that turns out to be necessary.

[jdesrosiers]

I built these files to see if I could configure it to meet our needs. The following config changes gets us most of the way there.

+ ipr: none
- submissionType: IETF
- wg: Internet Engineering Task Force

Additionally, I'd like to be able to remove the header altogether, which at this point is pretty awkward because it only includes "authors". Personally, I don't think we need to list authors at all. Listing authors at the end of the document is more than enough.

The other issue I found is the term "Informational" included in the footer for paged builds such as txt and pdf. I believe this is associated with the cat: info config. This is an IETF concept that doesn't apply to us, but the config is required and doesn't allow an empty string.

[cabo]

If you are still pursuing this, I could relay any formatting fixes you need to the xml2rfc maintainers, who might be able to get to them more quickly before the preparations for the next (IETF 118) meeting in November start again.

[jdesrosiers]

No, we decided to go a different direction. Sorry, we should have closed this when we made that decision. Thanks for your time and effort to put this together for us. Even though we didn't end up using it, it was very helpful to be able to have something to review to help us make our decision.