asciidoctor doctype should be "rfc"

[ronaldtse]

asciidoctor supports multiple doctypes, including:

• article
• book
• inline
• manpage

And for our gem, the doctype should definitely be rfc.

Agree?

[ronaldtse]

There are actually two types of documents we should handle:

• Internet-Draft ("I-D") is the normal one that people create (like this: https://github.com/riboseinc/rfc-openpgp-oscca-adoc). These are documents not yet approved by the IETF. These documents have a "rev" number beginning from "00", "01", etc.
• RFC is an official document published by the IETF, with an official numbering, after being approved from an Internet-Draft.

Maybe we should have separate :doctype:s for them ("internet-draft", "rfc"). Both have pretty much an identical structure, but different boilerplate.

RFCs are only created by IETF "RFC Editors", not by mere mortals. The only purpose of the "rfc" doctype in this gem is to re-create XMLRFCs of existing RFCs in asciidoctor format.

The purpose of the "internet-draft" doctype is to create XMLRFCs that can be submitted to the Internet Drafts Repository.

[opoudjis]

@paolobrasolin: Note that the RFC XML doesn't look essentially different, but there are different, in some instances mutually exclusive document header values. I haven't actually done anything with front/boilerplate in v3, because I had no idea how to populate it!

I have assumed the documents processed by this code to be articles, with an initial top-level title; so presumably rfc doctype would be a subclass of article.

[ronaldtse]

I think the boilerplate is inserted by the RFC tools (e.g., xml2rfc) as long as you have a <boilerplate> element in front: https://tools.ietf.org/html/rfc7991#section-2.11

And yes I agree that the rfc and internet-draft doctypes can subclass article.

[ronaldtse]

I feel that this should be implemented early on. Any time for this @opoudjis ? 😉

[opoudjis]

rolls eyes :-)

Obviously I need a sample of what this boilerplate is supposed to look like, and I assume the boilerplate is not determined by the ASCIIdoctor at all, but fixed for all Internet Drafts? The xml2rfc tool https://xml2rfc.tools.ietf.org says only that you should provide rfc@ipr attributes, not how you should populate the <boilerplate> element. I'll put an empty element for now, and see what xml2rfc does with it.

[ronaldtse]

From MMark only these elements are generated (from the rfc-openpgp-oscca draft):

<rfc ipr="trust200902" category="std" docName="draft-openpgp-oscca-02" updates="4880, 6637">
<?rfc toc="yes"?>
<?rfc symrefs="yes"?>
<?rfc sortrefs="yes"?>
<?rfc compact="yes"?>
<?rfc subcompact="no"?>
<?rfc private=""?>
<?rfc topblock="yes"?>
<?rfc comments="no"?>
...
</rfc>

Seems that the <boilerplate> element is only used by "real" RFC Editor tools, and is not present in MMark generated RFC XML. In any case, the textual boilerplate, like licenses etc., are indeed generated by xml2rfc.

[opoudjis]

Doctype is implemented, and is inheriting :article behaviour by default (since other doctype values are by exception).

Boilerplate element is not present in MMark output either, and is not required by XML2RFC. So closing this ticket.

[ronaldtse]

Perfect -- thank you @opoudjis !