metanorma / rfc-asciidoc-rfc Goto Github PK

AsciiRFC: Preparing Internet-Drafts And RFCs In AsciiDoc

Ruby 0.57% HTML 99.43%

rfc-asciidoc-rfc's Introduction

AsciiRFC: Preparing Internet-Drafts And RFCs In AsciiDoc

This Internet-Draft is written in pure AsciiDoc using the excellent asciidoctor-rfc gem. The latest draft of this Internet-Draft is available at https://tools.ietf.org/html/draft-ribose-asciirfc-02 .

Fetching the document

git clone https://github.com/metanorma/rfc-asciidoc-rfc

To fetch the sub-documents for /examples:

cd rfc-asciidoc-rfc
git submodule init
make pull

Installing Build Tools

You will need Ruby, xml2rfc and idnits (for submission preflight).

On macOS

brew install idnits
brew install python
easy_install pip
pip install -r requirements.txt
gem install bundler
bundle install

Building The Document

make all
# or
export ID_NAME=ribose-asciirfc
make draft-${ID_NAME}.txt

Checking Against idnits

idnits is the RFC checking tool prior to submissions.

The make target finds exactly the document name from the :name: document attribute and puts the file in the right place before calling idnits to prevent it complaining about the location.

export ID_NAME=ribose-asciirfc
make draft-${ID_NAME}.nits

Checking for invalid / unicode characters

export ID_NAME=ribose-asciirfc
pcregrep --color='auto' -n "[\x80-\xFF]" draft-${ID_NAME}.xml

Iterating the document

export ID_NAME=ribose-asciirfc
make clean all; open draft-${ID_NAME}.txt

rfc-asciidoc-rfc's People

Contributors

Stargazers

Watchers

rfc-asciidoc-rfc's Issues

Automatic citations of RFC and I-Ds

We should implement the functionality so that RFCs and I-Ds are automatically fetched. Managing them manually is quite a pain.

Use better example RFCs

As mentioned by Adrian Farrell we should use better examples.

Now we have three examples in the /examples directory that are git submodules (each of them has its own repo).

@opoudjis (after the holidays) could you help:

Make the content here "original" (https://github.com/riboseinc/rfc-camelot-holy-grenade) so that we can use it in the document?
Think of a good, short example that can serve as the most "basic" example, and can be submoduled under the /examples directory.

Stripping of leading spaces in ASCII Art

Need to fix this prior to -08 submission.

Figure 22: AsciiRFC With ASCII Art Without Figure Wrapping

______
\\/ \/
__\\ /__
|| //\ |
||__\\/ __|
|| | ,---,
|| |====`\ |
|| | '---'
,--'*`--,
_||#|***|#|
_,/.-'#|* *|#`-._
,,-'#####| |#####`-.
,,'########| |########`,
//##########| o |##########\
||###########| |###########|
||############| o |############|
||------------' '------------|
||o o o o o o o o o o|
|-----------------------------|
||###########################|
\\#########################/
`..#####################,'
``..###############_,'
``--.._____..--'
`''-----''`

Folding script problem: latest '07' version contains many "lines too long"

This seems like a folding script problem.

In examples/rfc-asciirfc-minimal/xml2/draft-asciirfc-minimal.xml (the "folded" version), it contains these lines which are not correctly folded:

<section anchor="conventions" title="Terms and Definitions"><t>The key words "<spanx style="strong">MUST</spanx>", "<spanx style="strong">MUST NOT</spanx>", "<spanx style="strong">REQUIRED</spanx>", "<spanx style="strong">SHALL</spanx>",

  <section anchor="_example_1" title="Example 1"><t>Here&#8217;s an example of a properly wrapped code snippet in
accordance with rules specified in <xref target="code-snippets"/>.</t>

In fact, the lines are hardly folded.

Small bug in the examples (title not deep enough)

The last example is not properly indented

--- a/rfc-asciidoc-rfc-orig/sections/97-examples.adoc
+++ b/rfc-asciidoc-rfc/sections/97-examples.adoc
@@ -95,7 +95,7 @@ include::../examples/rfc-divination-cfapi/draft-divination-cfapi.adoc[]
 --------
 
 [[example-3-xml3]]
-=== Rendered as RFC XML v3
+==== Rendered as RFC XML v3
 
 [source,xml]
 ----

Add captions to all source code example blocks

I’ve added captions to example code blocks in sections 3 to 7.

This issue is to add captions for the remaining source code blocks.

Convert to Metanorma

@metanorma/editors can you help convert this document to Metanorma? Thanks!

Emphasize the benefit of using AsciiDoc over Markdown

From @opoudjis

emphasise the Unique selling point of asciidoc more, not much more work in data entry, but formal validation for free

Distinguish AsciiDoc syntax vs asciidoctor syntax

The original AsciiDoc syntax was defined here: http://www.methods.co.nz/asciidoc/

asciidoctor supports a superset of AsciiDoc - and lacks support in some parts. So they are slightly different.

We should distinguish them in the document. Specifically, we are using a superset of asciidoctor syntax.

Replace hard-coded code snippets with AsciiDoc "include::" directives with lines

Currently we have a lot of (syntactically incomplete) snippets like:

[[source-asciirfc-header]]
.AsciiRFC Document Header
====
[source,asciidoc]
----
= Four Yorkshiremen Sketch
Tim Brooke-Taylor <[email protected]>
:doctype: internet-draft
:abbrev: 4 Yorkshiremen
:obsoletes: 10, 120
:updates: 2010, 2120
:status: informational
:name: draft-four-yorkshiremen-00
:ipr: trust200902
:area: Internet
:keyword: yorkshire, memory
:revdate: 1990-04-01T00:00:00Z
----
====

[[source-asciirfc-header-v3]]
.AsciiRFC Document Header Rendered As RFC XML v3
====
[source,xml]
----
<rfc ipr="trust200902" obsoletes="10, 120" updates="2010, 2120"
    submissionType="IETF" prepTime="2017-11-25T10:13:46Z" version="3">
  <front>
    <title abbrev="4 Yorkshiremen">Four Yorkshiremen Sketch</title>
    <seriesInfo name="Internet-Draft" status="informational"
        stream="IETF" value="draft-four-yorkshiremen-00" />
    <author fullname="Tim Brooke-Taylor" surname="Brooke-Taylor">
      <address>
        <email>[email protected]</email>
      </address>
    </author>
    <date day="1" month="April" year="1990" />
    <area>Internet</area>
    <workgroup>Network Working Group</workgroup>
    <keyword>yorkshire</keyword>
    <keyword>memory</keyword>
----
====

We should keep all the examples as real "AsciiRFC" files in other repos, and include the snippets using the include::path[leveloffset=offset,lines=ranges,tag(s)=name(s),indent=depth] directive (especially the lines one).

Final review before submission

@opoudjis could you help do a final review, then we will submit the document? Thanks!

Bibliography and AsciiBib

The asciidoctor-rfc syntax isn't "perfect" when bibliography is still done via XML.

I believe we should come up with a better "AsciiBib" format for this purpose?

Add 2 complete examples to section 97

We should provide two (completely fictitious) examples in the draft:

Minimal example
Very complex example

Convert RFC/I-D references into the auto-fetch format

As title.

Replace Travis (and remove) with GHA

Use completely fictitious RFC samples

Right now we have some references to the Avian Carrier one, but it would be better if we just make up our own (or use Monty Python etc.).

Update this document to use Metanorma instead of the old asciidoctor-rfc

The old asciidoctor rfc is documented as v2 metanorma-ietf on metanorma.com

Last edit

From Lynne:
Sigh.... Just want to make sure that we should update Figure 15, after spotting the following in Figure 14:

:no-rfc-bold-bcp14: false

Does this text in Section 4.4 indicate that Figure 15 is actually OK as is? Apologies for also missing this before!

:no-rfc-bold-bcp14: false
overrides the wrapping by default of boldface uppercase BCP14
[RFC2119] words (e.g. "MUST NOT") with the "bcp14" element.

Thank you again!

RELAXNG validation error: <eref> inside <spanx>

The document is not building due to this error. (we do have Travis CI 😉)

V2 RELAXNG Validation: 315:0: ERROR: Did not expect element eref there
V2 RELAXNG Validation: 315:0: ERROR: Element spanx has extra content: eref
V2 RELAXNG Validation: 720:0: ERROR: Did not expect element eref there
V2 RELAXNG Validation: 720:0: ERROR: Element spanx has extra content: eref

The exact lines are:

03-asciidoc.adoc

<spanx style="verb">:link: <eref target="https://en.wikipedia.org/wiki/Four_Yorkshiremen_sketch"/> describedby</spanx>,

04-header.adoc

<spanx style="verb">Tim Brooke-Taylor &lt;<eref target="mailto:[email protected]">[email protected]</eref>&gt;; John Cleese &lt;<eref target="mailto:[email protected]">[email protected]</eref>&gt;</spanx>

Move README content into draft

@opoudjis now that the document is buildable 👍

Could you help move some syntax from the README to this document?

Thanks!

idnits complaints

(Updated)

idnits 2.15.00 

draft-ribose-asciirfc-01.txt:
draft-ribose-asciirfc-01.txt(374): Line is too long: the offending characters are 'y'
draft-ribose-asciirfc-01.txt(387): Line is too long: the offending characters are 'ic'
draft-ribose-asciirfc-01.txt(402): Line is too long: the offending characters are 'orning,'
draft-ribose-asciirfc-01.txt(403): Line is too long: the offending characters are 'y day'
draft-ribose-asciirfc-01.txt(404): Line is too long: the offending characters are 'nd'
draft-ribose-asciirfc-01.txt(409): Line is too long: the offending characters are 'had'
draft-ribose-asciirfc-01.txt(410): Line is too long: the offending characters are 't the'
draft-ribose-asciirfc-01.txt(420): Line is too long: the offending characters are 'n to come'
draft-ribose-asciirfc-01.txt(421): Line is too long: the offending characters are ' our'
draft-ribose-asciirfc-01.txt(454): Line is too long: the offending characters are 've ya'.'
draft-ribose-asciirfc-01.txt(551): Line is too long: the offending characters are 'ire who'
draft-ribose-asciirfc-01.txt(552): Line is too long: the offending characters are 'hey try'
draft-ribose-asciirfc-01.txt(553): Line is too long: the offending characters are 'come'
draft-ribose-asciirfc-01.txt(572): Line is too long: the offending characters are 'in a'
draft-ribose-asciirfc-01.txt(573): Line is too long: the offending characters are 'ning,'
draft-ribose-asciirfc-01.txt(574): Line is too long: the offending characters are 'for'
draft-ribose-asciirfc-01.txt(575): Line is too long: the offending characters are ' would'
draft-ribose-asciirfc-01.txt(579): Line is too long: the offending characters are 'ck in'
draft-ribose-asciirfc-01.txt(580): Line is too long: the offending characters are 'o work'
draft-ribose-asciirfc-01.txt(581): Line is too long: the offending characters are ' would'
draft-ribose-asciirfc-01.txt(582): Line is too long: the offending characters are 'ere'
draft-ribose-asciirfc-01.txt(587): Line is too long: the offending characters are 'oebox at'
draft-ribose-asciirfc-01.txt(589): Line is too long: the offending characters are 'zing'
draft-ribose-asciirfc-01.txt(590): Line is too long: the offending characters are 'urpence'
draft-ribose-asciirfc-01.txt(591): Line is too long: the offending characters are 'in two'
draft-ribose-asciirfc-01.txt(597): Line is too long: the offending characters are 'an hour'
draft-ribose-asciirfc-01.txt(598): Line is too long: the offending characters are 'p of'
draft-ribose-asciirfc-01.txt(599): Line is too long: the offending characters are 'ill'
draft-ribose-asciirfc-01.txt(600): Line is too long: the offending characters are 'r Dad'
draft-ribose-asciirfc-01.txt(601): Line is too long: the offending characters are 'ah."</t>'
draft-ribose-asciirfc-01.txt(608): Line is too long: the offending characters are 'c7253">'
draft-ribose-asciirfc-01.txt(695): Line is too long: the offending characters are 'shire'
draft-ribose-asciirfc-01.txt(696): Line is too long: the offending characters are 'sses'
draft-ribose-asciirfc-01.txt(698): Line is too long: the offending characters are 'n" />'
draft-ribose-asciirfc-01.txt(707): Line is too long: the offending characters are 'in a'
draft-ribose-asciirfc-01.txt(708): Line is too long: the offending characters are 'ning,'
draft-ribose-asciirfc-01.txt(709): Line is too long: the offending characters are 'for'
draft-ribose-asciirfc-01.txt(710): Line is too long: the offending characters are ' would'
draft-ribose-asciirfc-01.txt(714): Line is too long: the offending characters are 'ck in'
draft-ribose-asciirfc-01.txt(715): Line is too long: the offending characters are 'o work'
draft-ribose-asciirfc-01.txt(716): Line is too long: the offending characters are ' would'
draft-ribose-asciirfc-01.txt(717): Line is too long: the offending characters are 'ere'
draft-ribose-asciirfc-01.txt(720): Line is too long: the offending characters are 'illiam">'
draft-ribose-asciirfc-01.txt(721): Line is too long: the offending characters are 'oebox at'
draft-ribose-asciirfc-01.txt(722): Line is too long: the offending characters are '> the'
draft-ribose-asciirfc-01.txt(723): Line is too long: the offending characters are ' cold'
draft-ribose-asciirfc-01.txt(724): Line is too long: the offending characters are 'ce every'
draft-ribose-asciirfc-01.txt(733): Line is too long: the offending characters are ' with a'
draft-ribose-asciirfc-01.txt(738): Line is too long: the offending characters are 'an hour'
draft-ribose-asciirfc-01.txt(740): Line is too long: the offending characters are ' hours a'
draft-ribose-asciirfc-01.txt(741): Line is too long: the offending characters are 'rk, and'
draft-ribose-asciirfc-01.txt(742): Line is too long: the offending characters are 'r graves'
draft-ribose-asciirfc-01.txt(749): Line is too long: the offending characters are 'c7253">'
draft-ribose-asciirfc-01.txt(751): Line is too long: the offending characters are 'n'
draft-ribose-asciirfc-01.txt(987): Found possible FQDN 'bbc.co.uk' in position 10; this doesn't match RFC 2606's suggested ".example" or ".example.(com|org|net)".
draft-ribose-asciirfc-01.txt(1191): Line is too long: the offending characters are 's,'
draft-ribose-asciirfc-01.txt(1206): Line is too long: the offending characters are 'e'
draft-ribose-asciirfc-01.txt(1250): Line is too long: the offending characters are ' and'
draft-ribose-asciirfc-01.txt(1251): Line is too long: the offending characters are 'w</em>'
draft-ribose-asciirfc-01.txt(1252): Line is too long: the offending characters are 'Python'
draft-ribose-asciirfc-01.txt(1253): Line is too long: the offending characters are 'ive'
draft-ribose-asciirfc-01.txt(1254): Line is too long: the offending characters are '>.</t>'
draft-ribose-asciirfc-01.txt(1256): Line is too long: the offending characters are 'shire'
draft-ribose-asciirfc-01.txt(1257): Line is too long: the offending characters are 'sses'
draft-ribose-asciirfc-01.txt(1258): Line is too long: the offending characters are 'ildhoods'
draft-ribose-asciirfc-01.txt(1262): Line is too long: the offending characters are 'may'
draft-ribose-asciirfc-01.txt(1267): Line is too long: the offending characters are 's one of'
draft-ribose-asciirfc-01.txt(1268): Line is too long: the offending characters are 'he'
draft-ribose-asciirfc-01.txt(1369): Found possible FQDN 'node.parent.context' in position 8; this doesn't match RFC 2606's suggested ".example" or ".example.(com|org|net)".
draft-ribose-asciirfc-01.txt(1421): Found possible FQDN 'node.parent.context' in position 12; this doesn't match RFC 2606's suggested ".example" or ".example.(com|org|net)".


  Checking boilerplate required by RFC 5378 and the IETF Trust (see
  https://trustee.ietf.org/license-info):
  ----------------------------------------------------------------------------

     No issues found here.

  Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt:
  ----------------------------------------------------------------------------

     No issues found here.

  Checking nits according to https://www.ietf.org/id-info/checklist :
  ----------------------------------------------------------------------------

  ** There are 67 instances of too long lines in the document, the longest one
     being 9 characters in excess of 72.

  == There are 3 instances of lines with non-RFC2606-compliant FQDNs in the
     document.


  Miscellaneous warnings:
  ----------------------------------------------------------------------------

  -- The document date (November 20, 2017) is 5 days in the past.  Is this
     intentional?


  Checking references for intended status: Informational
  ----------------------------------------------------------------------------

  -- Looks like a reference, but probably isn't: '1' on line 1919
     '[1] https://github.com/miekg/mmark...'

  -- Looks like a reference, but probably isn't: '2' on line 1921
     '[2] https://github.com/cabo/kramdown-rfc2629...'

  -- Looks like a reference, but probably isn't: '3' on line 1923
     '[3] https://daringfireball.net/projects/markdown/...'

  -- Looks like a reference, but probably isn't: '4' on line 1925
     '[4] http://www.methods.co.nz/asciidoc/...'

  -- Looks like a reference, but probably isn't: '5' on line 1927
     '[5] http://asciidoctor.org...'

  -- Looks like a reference, but probably isn't: '6' on line 1929
     '[6] http://asciidoctor.org/docs/user-manual/#compared-to-markdown...'

  -- Looks like a reference, but probably isn't: '7' on line 1931
     '[7] http://asciidoctor.org/docs/user-manual/#compared-to-markdown...'

  -- Looks like a reference, but probably isn't: '8' on line 1933
     '[8] http://docs.mathjax.org/en/latest/asciimath.html...'

  -- Looks like a reference, but probably isn't: '9' on line 1935
     '[9] http://docs.mathjax.org/en/latest/tex.html...'

  -- Looks like a reference, but probably isn't: '10' on line 1937
     '[10] https://www.mathjax.org...'

  == Missing Reference: 'NOTE' is mentioned on line 968, but not
     defined
'[NOTE]...'

  -- Looks like a reference, but probably isn't: '11' on line 1939
     '[11] http://asciidoctor.org/docs/user-manual/#complex-list-conten...'

  -- Looks like a reference, but probably isn't: '12' on line 1941
     '[12] http://asciidoctor.org/docs/user-manual/#include-directive...'

  -- Looks like a reference, but probably isn't: '13' on line 1943
     '[13] https://github.com/riboseinc/asciidoctor-bibliography...'

  -- Looks like a reference, but probably isn't: '14' on line 1945
     '[14] http://asciidoctor.org/docs/user-manual...'

  -- Looks like a reference, but probably isn't: '15' on line 1947
     '[15] https://github.com/riboseinc/asciidoctor-...'

  -- Looks like a reference, but probably isn't: '16' on line 1950
     '[16] https://github.com/riboseinc/asciidoctor-rfc/tree/master/spe...'

  == Unused Reference: 'RFC5385' is defined on line 1891, but no explicit
     reference was found in the text
     '[RFC5385]  Touch, J., "Version 2.0 Microsoft Word Template for Creat...'

  == Unused Reference: 'RFC7328' is defined on line 1896, but no explicit
     reference was found in the text
     '[RFC7328]  Gieben, R., "Writing I-Ds and RFCs Using Pandoc and a Bit...'

  -- Obsolete informational reference (is this intentional?): RFC 7749

     Summary: 1 error (**), 0 flaws (~~), 4 warnings (==), 18 comments (--).

Spanx elements should not be inserted into section titles (v2)

This line:

=== Preprocessing Using `asciidoctor-bibliography`

Produces:

17.2.  Preprocessing Using <spanx style="verb">asciidoctor-
       bibliography</spanx>

Through xml2rfc.

Therefore section titles should not accept <spanx> elements. RFC 7749 doesn't quite specify what should be in the <section> title attribute, but presumably not XML elements. https://tools.ietf.org/html/rfc7749#section-2.34

In v3 RFC 7991, it does specify that then <section>'s <name> element can contain XML. https://tools.ietf.org/html/rfc7991#section-2.32

Bug Cannot continue processing No such file: /home/runner/work/rfc-asciidoc-rfc/rfc-asciidoc-rfc/site/documents/draft-ribose-asciirfc.rfc.xml

https://github.com/metanorma/rfc-asciidoc-rfc/runs/2948292251?check_suite_focus=true#step:8:224

...
RFC XML: xref target asciidoctor-rfc does not exist in the document
RFC XML: xref target RFC7749 does not exist in the document
RFC XML: xref target RFC7991 does not exist in the document
RFC XML: xref target NroffEdit does not exist in the document
RFC XML: xref target RFC5385 does not exist in the document
RFC XML: xref target lyx2rfc does not exist in the document
RFC XML: xref target RFC7328 does not exist in the document
RFC XML: xref target pandoc2rfc does not exist in the document
RFC XML: xref target draftr does not exist in the document
RFC XML: xref target kramdown-rfc2629 does not exist in the document
RFC XML: xref target mmark does not exist in the document
RFC XML: xref target RFC7763 does not exist in the document
RFC XML: xref target RFC7990 does not exist in the document
RFC XML: xref target RFC7991 does not exist in the document
RFC XML: xref target RFC7749 does not exist in the document
RFC XML: xref target RFC7991 does not exist in the document
RFC XML: xref target AsciiDoc does not exist in the document
RFC XML: xref target Asciidoctor does not exist in the document
RFC XML: xref target AsciiDoc does not exist in the document
RFC XML: xref target Asciidoctor does not exist in the document
RFC XML: xref target RFC7764 does not exist in the document
RFC XML: xref target asciidoctor_bibliography does not exist in the document
RFC XML: xref target AsciiDoc does not exist in the document
RFC XML: xref target Asciidoctor does not exist in the document
RFC XML: xref target I-D.wu-netmod-yang-xml-doc-conventions does not exist in the document
RFC XML: xref target asciidoctor_bibliography does not exist in the document
RFC XML: xref target Asciidoctor-Manual does not exist in the document
RFC XML: xref target RFC7996 does not exist in the document
RFC XML: xref target AsciiMathML does not exist in the document
RFC XML: xref target TeX-LaTeX does not exist in the document
RFC XML: xref target MathJax does not exist in the document
RFC XML: xref target asciidoctor-rfc does not exist in the document
RFC XML: xref target RFC2119 does not exist in the document
RFC XML: xref target Asciidoctor-Manual does not exist in the document
RFC XML: xref target RFC2119 does not exist in the document
RFC XML: xref target RFC8174 does not exist in the document
RFC XML: xref target Asciidoctor-Manual does not exist in the document
RFC XML: xref target git-asciirfc-minimal does not exist in the document
RFC XML: xref target I-D.asciirfc-minimal does not exist in the document
RFC XML: xref target datatracker-asciirfc-minimal does not exist in the document
RFC XML: xref target git-camelot-holy-grenade does not exist in the document
RFC XML: xref target I-D.camelot-holy-grenade does not exist in the document
RFC XML: xref target datatracker-camelot-holy-grenade does not exist in the document
RFC XML: xref target git-divination-cfapi does not exist in the document
RFC XML: xref target I-D.divination-cfapi does not exist in the document
RFC XML: xref target datatracker-divination-cfapi does not exist in the document
Cannot continue processing
No such file: /__w/rfc-asciidoc-rfc/rfc-asciidoc-rfc/site/documents/draft-ribose-asciirfc.rfc.xml

metanorma / rfc-asciidoc-rfc Goto Github PK

rfc-asciidoc-rfc's Introduction

AsciiRFC: Preparing Internet-Drafts And RFCs In AsciiDoc

Fetching the document

Installing Build Tools

On macOS

Building The Document

Checking Against idnits

Checking for invalid / unicode characters

Iterating the document

rfc-asciidoc-rfc's People

Contributors

Stargazers

Watchers

rfc-asciidoc-rfc's Issues

Recommend Projects

Recommend Topics

Recommend Org