Authoring I-D/RFCs in AsciiDoc

classic Classic list List threaded Threaded
4 messages Options
Reply | Threaded
Open this post in threaded view
|

Authoring I-D/RFCs in AsciiDoc

Ronald Tse
Warm greetings to everyone on the rfc-interest list!

We’ve recently made a tool that allows writing Internet-Drafts using AsciiDoc called “asciidoctor-rfc” [1], as an alternative to Kramdown / MMark or manual RFC XML. AsciiDoc is a widely-adopted textual format. Similar to Markdown, it is simple to write and easy to understand, but its major benefit is for being a structured format that directly converts into DocBook XML.

The tool, “asciidoctor-rfc” supports generating both v3 and v2 RFC XML through the “AsciiRFC” syntax [2].

We have attempted to expose as many v3 (and v2) features as possible through native AsciiDoc syntax. I do know the v3 xml2rfc tool is under development (originally scheduled for Oct?), and we are excited to try it out using RFC XML files generated with asciidoctor-rfc.

Here are some examples created through this asciidoctor-rfc:
* A large number of v2/v3 examples, including the IETF templates, at [3]
* draft-oscca-cfrg-sm3-02 (source: [4], text: [5])
* draft-ribose-cfrg-sm4-03 (source: [6], text: [7])

We are very interested in your (and RFC Editors!) feedback. Please let us know how this could work better for you — we look forward hearing from all interested parties. Thank you in advance!

Links:

[1] https://github.com/riboseinc/asciidoctor-rfc
[2] https://tools.ietf.org/html/draft-ribose-asciirfc-01
[3] https://github.com/riboseinc/asciidoctor-rfc/tree/master/spec/examples
[4] https://github.com/riboseinc/rfc-crypto-sm3
[5] https://tools.ietf.org/html/draft-oscca-cfrg-sm3-02
[6] https://github.com/riboseinc/rfc-crypto-sm3
[7] https://tools.ietf.org/html/draft-ribose-cfrg-sm4-03

Kind regards,
Ronald

_____________________________________

Ronald Tse
Ribose Inc.


_______________________________________________
rfc-interest mailing list
[hidden email]
https://www.rfc-editor.org/mailman/listinfo/rfc-interest
Reply | Threaded
Open this post in threaded view
|

Re: Authoring I-D/RFCs in AsciiDoc

Julian Reschke
On 2017-11-25 17:26, Ronald Tse wrote:

> Warm greetings to everyone on the rfc-interest list!
>
> We’ve recently made a tool that allows writing Internet-Drafts using
> AsciiDoc called “asciidoctor-rfc” [1], as an alternative to Kramdown /
> MMark or manual RFC XML. AsciiDoc is a widely-adopted textual format.
> Similar to Markdown, it is simple to write and easy to understand, but
> its major benefit is for being a structured format that directly
> converts into DocBook XML.
>
> The tool, “asciidoctor-rfc” supports generating both v3 and v2 RFC XML
> through the “AsciiRFC” syntax [2].
>
> We have attempted to expose as many v3 (and v2) features as possible
> through native AsciiDoc syntax. I do know the v3 xml2rfc tool is under
> development (originally scheduled for Oct?), and we are excited to try
> it out using RFC XML files generated with asciidoctor-rfc.
> ...

You may want to try it with rfc2629.xslt, which already supports a broad
range of V3 features...:
<https://www.greenbytes.de/tech/webdav/rfc2629xslt/rfc2629xslt.html#v3>

Best regards, Julian
_______________________________________________
rfc-interest mailing list
[hidden email]
https://www.rfc-editor.org/mailman/listinfo/rfc-interest
Reply | Threaded
Open this post in threaded view
|

Re: Authoring I-D/RFCs in AsciiDoc

Ronald Tse
Thank you very much Julian, we will try to include this in our test suite to test for v2/v3 compatibility :-P

Kind regards,
Ron

_____________________________________

Ronald Tse
Ribose Inc.

On Nov 27, 2017, at 7:24 PM, Julian Reschke <[hidden email]> wrote:

On 2017-11-25 17:26, Ronald Tse wrote:
Warm greetings to everyone on the rfc-interest list!
We’ve recently made a tool that allows writing Internet-Drafts using AsciiDoc called “asciidoctor-rfc” [1], as an alternative to Kramdown / MMark or manual RFC XML. AsciiDoc is a widely-adopted textual format. Similar to Markdown, it is simple to write and easy to understand, but its major benefit is for being a structured format that directly converts into DocBook XML.
The tool, “asciidoctor-rfc” supports generating both v3 and v2 RFC XML through the “AsciiRFC” syntax [2].
We have attempted to expose as many v3 (and v2) features as possible through native AsciiDoc syntax. I do know the v3 xml2rfc tool is under development (originally scheduled for Oct?), and we are excited to try it out using RFC XML files generated with asciidoctor-rfc.
...

You may want to try it with rfc2629.xslt, which already supports a broad range of V3 features...: <https://www.greenbytes.de/tech/webdav/rfc2629xslt/rfc2629xslt.html#v3>

Best regards, Julian


_______________________________________________
rfc-interest mailing list
[hidden email]
https://www.rfc-editor.org/mailman/listinfo/rfc-interest
Reply | Threaded
Open this post in threaded view
|

Re: Authoring I-D/RFCs in AsciiDoc

Ronald Tse
For anyone interested in using the AsciiDoc format for authoring I-Ds/RFCs, you can find a large number of examples we use to spec against and their AsciiDoc-equivalent.


These examples include:

* the official IETF templates including RFC XML v1 (https://tools.ietf.org/tools/templates)
* existing I-Ds/RFCs from (https://github.com/rfc-format)
* examples used by MMark
* examples used by Kramdown-rfc2629
* and a number of existing RFC documents like RFC 6350.

If you encounter any issue with our tool, please feel free to file an issue here and we will get it fixed (or answered):


Thanks!

Kind regards,
Ron

_____________________________________

Ronald Tse
Ribose Inc.

On Nov 27, 2017, at 10:40 PM, Ronald Tse <[hidden email]> wrote:

Thank you very much Julian, we will try to include this in our test suite to test for v2/v3 compatibility :-P

Kind regards,
Ron

_____________________________________

Ronald Tse
Ribose Inc.

On Nov 27, 2017, at 7:24 PM, Julian Reschke <[hidden email]> wrote:

On 2017-11-25 17:26, Ronald Tse wrote:
Warm greetings to everyone on the rfc-interest list!
We’ve recently made a tool that allows writing Internet-Drafts using AsciiDoc called “asciidoctor-rfc” [1], as an alternative to Kramdown / MMark or manual RFC XML. AsciiDoc is a widely-adopted textual format. Similar to Markdown, it is simple to write and easy to understand, but its major benefit is for being a structured format that directly converts into DocBook XML.
The tool, “asciidoctor-rfc” supports generating both v3 and v2 RFC XML through the “AsciiRFC” syntax [2].
We have attempted to expose as many v3 (and v2) features as possible through native AsciiDoc syntax. I do know the v3 xml2rfc tool is under development (originally scheduled for Oct?), and we are excited to try it out using RFC XML files generated with asciidoctor-rfc.
...

You may want to try it with rfc2629.xslt, which already supports a broad range of V3 features...: <https://www.greenbytes.de/tech/webdav/rfc2629xslt/rfc2629xslt.html#v3>

Best regards, Julian

_______________________________________________
rfc-interest mailing list
[hidden email]
https://www.rfc-editor.org/mailman/listinfo/rfc-interest


_______________________________________________
rfc-interest mailing list
[hidden email]
https://www.rfc-editor.org/mailman/listinfo/rfc-interest