[rfc-i] Have we standardized on Pandoc style Markdown?

Phillip Hallam-Baker phill at hallambaker.com
Mon Nov 30 14:06:20 PST 2015


OK, I have (mostly) got the PanDoc markup running. Numbered and bulleted
lists, Tables, defined items aren't working yet but the rest is.


This is how I currently handle the metadata issue:

I am basically using a pseudo XML. Tags close and scope automatically. So
there is no need to write </ietf>, it closes automatically.

I separate out the draft name and version because that makes other tools
work a lot nicer. And I stick to the XML convention that any text that the
user might see is presented as content, anything that the user won't see is
an attribute (but those don't seem to be needed very often).

Changing this round isn't too hard, it is just a question of specifying the
finite state machine transitions.

The one thing that does have me a bit flumoxed right now is how to deal
with the Pandoc style code blocks. This is not something an FSR can cope
with. So there has to be a hack to make one of the transitions happen.


// It is useful to allow comments
<ietf>draft-hallambaker-tlsfeature
<title>X.509v3 TLS Feature Extension
<abbrev>TLS Feature Extension
<version>07

<ipr>trust200902
<area>sec
<publisher>Internet Engineering Task Force (IETF)
<status>Standards Track

<author>Phillip Hallam-Baker
    <fullname>Phillip Hallam-Baker
    <initials>P. M.
    <organization>Comodo Group Inc.
    <surname>Phillip
    <email>philliph at comodo.com

<keyword>PKI
<keyword>X.509
<keyword>TLS
<keyword>OCSP

#Abstract

The purpose of the TLS Feature extension is to prevent downgrade attacks
that are not otherwise prevented by the TLS protocol. In particular, the ...

#Definitions

<include=Requirements.md />


Now I could change this fairly easily. But it is not clear to me what the
alternative is and there are advantages to being able to use attributes
when specifying metadata.



On Mon, Nov 30, 2015 at 3:54 PM, Carsten Bormann <cabo at tzi.org> wrote:

> On 30 November 2015 at 21:17:52, Phillip Hallam-Baker (
> phill at hallambaker.com) wrote:
>
> Do we have a consensus on using Pandoc style markdown?
>
> I have no idea who “we” is, but there are two elements to such a question:
>
> * What general sets of markdown features beyond Gruber markdown do RFC
> authors use?  (Tables, Definition lists, Attribute lists…)
>
> * How are the xml2rfc specific mechanisms addressed in markdown?
>
> Pandoc does not answer the second question.  RFC 7328 has one answer to
> that, but I think Miek has been moving on from that.
>
> kramdown-rfc2629 uses the common markdown extensions as used in the
> kramdown tool (and, where they differ, not the slightly less common ones in
> Pandoc). I have no idea how wikimedia’s markdown flavor enters this
> picture; I am not aware that that has much traction.
>
> kramdown-rfc2629 also has its own way of the representing xml2rfc specific
> mechanisms, much of it in a YAML header that is used for metadata and
> literature references.
>
> kramdown-rfc2629 has been around for half a decade now and hasn’t suffered
> incompatible changes yet; since documents often live a long time before
> becoming RFCs, I’m not particularly interested in wild experimentation here.
>
> Grüße, Carsten
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://www.rfc-editor.org/pipermail/rfc-interest/attachments/20151130/01e427ef/attachment.html>


More information about the rfc-interest mailing list