These are the design choices I've made for rendering RFC XML features in Asciidoc which I think are open for discussion with @paolobrasolin, as more comfortable with Asciidoc. I have to say, I'm more or less comfortable with where I have got to with these, but let's run through them.
The issue of whether normative and informative crossreferences are to be differentiated (as they are in MMark) is discussed in separate tickets. Ditto added markup on authors. (Myself, I am wary of adding machinery not built in to asciidoctor, in order to make the gem as reusable as possible, by minimising dependencies. I also don't see a strong reason why RFC Asciidoctor needs to look like MMark. But the customer is always right. :-)
-
Comments:
** Are being rendered as admonitions rather than comments, since (as far as I can tell!) the asciidoctor preprocessor actually ignores native asciidoc comments. There's no option in v2 to signal that comments should be removed from a published draft, as there is in v3.
-
Abstract
** Is being naively extracted as the first paragraphs after the document header and before the first section or admonitions (in the asciidoc preamble), since that is where the RFC XML schema constrains it to be. This happens whether or not there is an [abstract] style on the paragraph.
-
Boilerplate
** I have not rendered v3 boilerplate in Asciidoc at all.
-
Cross-reference formatting attribute
** Options of counter, title, or derived text (e.g. Table 1). I am currently ignoring these options, because xrefstyle did not seem to offer what RFC XML needed.
-
iref primary attribute
** This is not whether the index term is a primary term, but whether it should be emphasised in the index as a more important reference (as boldface or italics in some book indexes). Does not seem to be supported in Asciidoc.
-
author initials
** There is a clash between the Asciidoc :authorinitials attribute, which includes the initial of the surname, and the RFC XML :initials attribute, which leaves it out. For Homer J Simpson, asciidoc would assume the authorinitials are HJS, RFC XML as HJ. Currently I take only the initial letter of the first name as the initial. If the user can specify RFC XML initials for authors, they need to be given a name other than :authorinitials, to avoid confusion.
-
referencegroups
** I have delimited groupings of references in the ulist format of references by using nested lists, but that disrupts the rendering of anchors: the default asciidoc processor clearly expects any ulist under bibliography to be flat.
-
date
** Asciidoc expects an ISO date under :revdate. I currently process the date and extract out the year, month, date attributes expected by RFC XML.
-
arrays in header
** MMark puts array values of header attributes in brackets, e.g. obsoletes: ["7994", "8981"]. I just leave the value as a comma-delimited list, without quotes or brackets, though that raises the possibility of ambiguity for keyword that contain commas.
-
superscript, subscript
** Not natively supported at all in RFC XML v2, though they are in v3. I leave them as Latex-style ^ and _. These often end up in attribute values in v2 XML, so rendering them in markup will not always be feasible.
-
table column width
** This is more a bug, but v2 has an optional table column width attribute, which I'm reading from the colpcwidth attribute. Following the HTML5 converter, that attribute is not meant to be added if the table is autowidth, but it's being added anyway.
-
Table preamble and postamble
** Not supported; any prefatory or footer free text in a table is going to be indistinguishable from a separate paragraph in Asciidoc, unless the table is embedded in an example, say. The elements are desultorily supported in figure (example), but they are quite fragile, and the elements were justly deprecated in v3.
-
figure
** Rendered as example. Note that artwork, images, and sourcecode are all meant to be embedded within figures; the converter supplies the figure node if it is not in the Asciidoc markup.