Skip to main content

Shepherd writeup
draft-ribose-asciirfc

Document reviewed at -04 by Heather Flanagan and Adrian Farrel (prior to taking
up ISE position). -05 and -06 address the reviews.

Both reviewers suggested asking the IESG whether they thought the document
belongs on the IETF stream, and the IESG is requested to comment on this in
parallel to 5742 review.

===Heather's Review===
My first question when reading this is "why"? The author mentions
several authoring formats, but seems to focus on directly competing with
Markdown. Is this just a situation of adding a 15th standard in an
attempt to consolidate the last 14 (https://xkcd.com/927/)?

A separate point of note: Having the comparisons to Markdown use the
terms AsciiDoc, Ascii RFC, and asciidoctor, each of which is defined
later, meant I had to go back and re-read that section to understand the
context.

With regards to the use of RFC 2119 keywords, I think it's an open
question as to whether those should be allowed in non-standards
documents. I lean towards "no" but there are definitely examples where
it's done. This is probably the ISE's call in this case.

I don't have an opinion on the syntax itself, but I would note that RFC
7991 will have a -bis that incorporates several changes based on what we
learn during implementation. Not sure if the author wants to continue to
rely on that, or wait until the update comes out.

And last comment - given Markdown was documented (somewhat) within the
IETF, should this go into the Apps Area WG for consideration? Or did
that happen already and it was rejected?
==========

===Adrian's Review===
This is a suitable subject for publication as an RFC. I would advise
the ISE to check with the IESG about having this published on the IETF
stream as it seems of direct interest to the IETF community.

---

I would encourage the authors to look at two links:
- https://www.rfc-editor.org/pubprocess/tools/
- https://tools.ietf.org/
Working with the owners of those pages to get included will widen the
up-take of your work. (This is independent of the publication of this
document.)

---

I found the distinction between Asciidoctor and AsciiDoc in this document
slightly unclear. As I understand it, AsciiDoc is a markup language
while Asciidoctor is a toolchain (written in Ruby) that processes
AsciiDoc source.

The text of this document says (for example)
>  This document describes the use of [Asciidoctor], a
>  Ruby-based enhancement of the original AsciiDoc markup language

---

I would have found it helpful if the document had given some clue about
the availability and license of Asciidoctor and asciidoctor-rfc.  Maybe
a few words saying "open source" and "MIT license"?

---

Tempus fugit :-( The BCP 14 text should now read...

   The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
   "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY",
and
   "OPTIONAL" in this document are to be interpreted as described in BCP
   14 [RFC2119] [RFC8174] when, and only when, they appear in all
   capitals, as shown here.

I'm not comfortable with the presence of bold demarkers ("*") in the
BCP14 boilerplate which (I think) should be perfectly conformant with
the BCP. That said, this document has no need of the boilerplate since
it does not use that language except in examples (which themselves use
the old boilerplate).

---

Heading of Section 3
s/AsciiDoctor/Asciidoctor/

---

Section 3

   o  A number of sections, set off by a section title (a line prefixed
      with two or more "=".

Missing close bracket

---

Section 3.2 has...

   Illustrations are in RFC XML v3, although the converter deals with
   both versions of RFC XML.

   A sample AsciiRFC document is provided in Figure 1, and its
   corresponding rendering in:

   o  RFC XML v3 (Figure 2)

   o  RFC XML v2 (Figure 3)

So it looks like the first para should read...

   Illustrations are in RFC XML v3 and RFC XML v2.

---

3.2 has
:email_4: mf@bcc.co.uk
You should probably use
:email_4: mf@example.com

Please search for bbc.co.uk and replace throughout the document.

---

The document quotes text from the Wikipedia page
https://en.wikipedia.org/wiki/Four_Yorkshiremen_sketch
(for example, the Abstract in Section 3.2).

That text is licensed as CC-BY-SA. That appears to be in conflict with
the standard IETF copyright license.

While a link and a "see also" note is supplied, this doesn't seem to
meet the attribution requirement in the license.

And all of this made me worry about the copyright of the actual sketch.

I wonder whether it wouldn't be easier (if drier) to use a completely
fabricated example, or some text from an existing RFC (perhaps an April
1st RFC) where we own copyright.

---

Placing cross-references (or citations) in the Abstract (in Fig 1) is
not good for an example because they are explicitly not allowed.

---

Fig 3 has errors that prevent parsing

Missing DOCTYPE statement generates a warning

OLD
    <title abbrev="4 Yorkshiremen">Four Yorkshiremen Sketch<title>
NEW
    <title abbrev="4 Yorkshiremen">Four Yorkshiremen Sketch</title>

OLD
          <spanx style="strong">lick<spanx>
NEW
          <spanx style="strong">lick</spanx>

---

Fig 8 has a real URI. While this is public domain for this person, you
should
OLD
:uri_2: https://twitter.com/johncleese
NEW
:uri_2: https://example.com/johncleese

---

4.4

   :inline-definition-lists: true
      overrides the RFC XML v2 "idnits" requirement that a blank line be
      inserted between a definition list term and its definition.

I'm not aware of such a requirement. You are possibly saying that there
is always a blank line between paragraphs? I use <list style="hanging">
for terms in a list.

---

Fig 13

OLD
       <t>The specification  <bcp14>MUST NOT</bcp14>
         use the word <em> doesn&#8217;t</em>.</t>
NEW
       <t>The specification <bcp14>MUST NOT</bcp14>
         use the word <em>doesn&#8217;t</em>.</t>

---

Section 6

   Section headers are given with a sequence of "=", the number of "="
   giving the header level.

You should make clear that the highest header level requires "=="

Can I skip a level going downwards (with numbered sections)? E.g.,

:sectnums:
== This Section
==== That Section

---

8.1

No numbered lists?

---

Section 13

   To prevent hyperlinking of a URL, prefix it with a backslash, as
   shown in Figure 46 with its rendered version in <<source-asciirfc-
   link-lit-v3>.

Probably your link to Figure 47 is broken.

---

17.2 an d 19.1 Headers needs a good spanxing :-)

---

Section 20.

I think you previously mentioned that URLs should be prefixed by a
backslash to prevent them from being hyperlinked. Is there a risk that a
malicious AsciiRFC source file contains an unprefixed URL that
hyperlinks to an unsafe site and causes an attack on the host?

---

Section 22
- Move to Appendix
- Same concerns about copyright
- Nice bunny :-)

---

Appendix A reads a little strangely?

Back