Subject: [Cellar] An attempt at EBML specification in RFC form

From: Dave Rice <[email-masked]>
Date: Fri, 17 Jun 2016 00:36:14 -0400

Hi all,

I published a pull request [1] to the EBML specification which includes changes to support making an RFC document from the markdown-based specification using both mmark [2] and xml2rfc. Here’s some notes and questions about this work:

The use of hyphenated section names would not work with mmark, so I changed the phrase “Identically-Recurring Elements” to "Identically Recurring Elements” [3]. If there’s any objection I could feasibly add an id to the associated section header.

I added a new markdown file called rfc_frontmatter.markdown which contains metadata used to construct the RFC document. This currently contains:

% Title = "Extensible Binary Meta Language"
% abbrev = "EBML"
% category = "info"
% docName = ""
% ipr= "trust200902"
% area = ""
% workgroup = "cellar"
% keyword = [""]
%
% [[author]]
% initials="S."
% surname="Lhomme"
% fullname="Steve Lhomme”

This is partly based off changes from a document I found in the mmark repo with some customization for this project. However I am very unfamiliar with the IETF use of these values. What is our area, ipr, docName, etc? Also, I had used Steve as the author, but who I’m unclear on who are the authors of the EBML specification. Steve? Moritz?

I added a Makefile [4] to build the rfc output in text and html form via mmark and pandoc. I am not well experienced in coding Makefiles and welcome suggestions.

I also added a gitignore file to ignore the outputs of the makefile to make it easier for git users to not accidentally commit the built files.

The text output of the makefile is available for review at https://gist.github.com/dericed/fee1352b273be97a2e1879760ade96c3 [5]. The sections in lines 13 - 43 [6] appear to be IETF boilerplate output by xml2rfc. Should I make any changes to the use of xml2rfc for now?

Also now that we can see the EBML specification in RFC form there are some places where the formatting of the document should clearly be adjusted. Some of the markdown used prevents the RFC from properly line-wrapping and some tables don’t fit in the width of the RFC. I suggest these changes wait for another pull request, but would like comments on this approach for building RFC from our markdown.

Best Regards,
Dave Rice

[1] https://github.com/Matroska-Org/ebml-specification/pull/66
[2] https://github.com/miekg/mmark
[3] https://github.com/Matroska-Org/ebml-specification/pull/66/files/c5cec7b4ba212bd08cb466d9a5ea80fd9915a809?short_path=01f3b0f#diff-01f3b0f2fbf3e44327e6072f64ddc8a0
[4] https://github.com/Matroska-Org/ebml-specification/pull/66/commits/d8560f16c108b8a184e47cdefb43512a6a46dc9b
[5] https://gist.github.com/dericed/fee1352b273be97a2e1879760ade96c3
[6] https://gist.github.com/dericed/fee1352b273be97a2e1879760ade96c3#file-ebml_rfc-txt-L13-L43

---

From: "Timothy B. Terriberry" <[email-masked]>
Date: Thu, 16 Jun 2016 22:36:30 -0700

> % Title = "Extensible Binary Meta Language"

This should be "std" (for Standards Track, instead of Informational, as 
we agreed when adding the milestone).

> % docName = ""

This should be something like "draft-<first author's 
surname>-cellar-ebml-00". The use of an author's name indicates that 
this is an individual draft. If it is formally adopted as a working 
group draft, it will become "draft-ietf-cellar-ebml-00" instead. The 
trailing -00 is the version number, which you will increment each time 
you submit a new version to the datatracker.

> % ipr= "trust200902"

Unless you're updating an old RFC (which you're not), this is the 
correct thing to use.

> % area = ""

CELLAR is in the Applications and Real-Time Area, so "art" is the 
correct thing here. You can find this information on the charter page 
for CELLAR in the datatracker: 
https://datatracker.ietf.org/wg/cellar/charter/

> Also, I had used Steve as the author, but who I’m unclear on who are the authors of the EBML specification. Steve? Moritz?

 From a technical point of view, the authors/editors are the people who 
must sign off during the AUTH48 process (the last step before 
publication by the RFC Editor) and respond to inquiries such as errata. 
One author is required to approve posting an updated version of a draft 
to the datatracker. All authors are required to approve the document 
during AUTH48.

 From a policy point of view, exactly who should be an author or editor 
is somewhat subjective. You can find some guidance in various places:

https://tools.ietf.org/html/rfc7221#section-3
https://www.rfc-editor.org/old/policy.html#policy.authlist
https://tools.ietf.org/html/draft-carpenter-whats-an-author

(that last one is an individual draft, and thus only represents that 
individual's opinion, rather than the consensus of any working group or 
of the IETF as a whole)

Since we have not yet formally adopted your draft as a working-group 
draft, and it is still an individual draft, the choice of 
authors/editors is "whoever wants to be". It is the WG chairs' 
responsibility to appoint authors/editors when a draft is formally 
adopted, but unless there is some specific reason to do otherwise, this 
is usually just the same authors and editors who contributed the 
individual draft. Once adopted, the authors/editors are required to 
follow the guidelines in https://tools.ietf.org/html/rfc2418#section-6.3

---

From: Dave Rice <[email-masked]>
Date: Fri, 17 Jun 2016 08:20:33 -0400

> On Jun 17, 2016, at 1:36 AM, Timothy B. Terriberry <[email-masked]> wrote:
> 
> Dave Rice wrote:
> This should be "std" (for Standards Track, instead of Informational, as we agreed when adding the milestone).
> 
>> % docName = ""
> 
> This should be something like "draft-<first author's surname>-cellar-ebml-00". The use of an author's name indicates that this is an individual draft. If it is formally adopted as a working group draft, it will become "draft-ietf-cellar-ebml-00" instead. The trailing -00 is the version number, which you will increment each time you submit a new version to the datatracker.
> 
>> % ipr= "trust200902"
> 
> Unless you're updating an old RFC (which you're not), this is the correct thing to use.
> 
>> % area = ""
> 
> CELLAR is in the Applications and Real-Time Area, so "art" is the correct thing here. You can find this information on the charter page for CELLAR in the datatracker: https://datatracker.ietf.org/wg/cellar/charter/

I updated the pull request based on all the above suggestions. The metadata for the EBML RFC is now:

% Title = "Extensible Binary Meta Language"
% abbrev = "EBML"
% category = "std"
% docName = "draft-lhomme-cellar-ebml-00"
% ipr= "trust200902"
% area = "art"
% workgroup = "cellar"
% keyword = [""]
%
% [[author]]
% initials="S."
% surname="Lhomme"
% fullname="Steve Lhomme"

> From a technical point of view, the authors/editors are the people who must sign off during the AUTH48 process (the last step before publication by the RFC Editor) and respond to inquiries such as errata. One author is required to approve posting an updated version of a draft to the datatracker. All authors are required to approve the document during AUTH48.
> 
> From a policy point of view, exactly who should be an author or editor is somewhat subjective. You can find some guidance in various places:
> 
> (that last one is an individual draft, and thus only represents that individual's opinion, rather than the consensus of any working group or of the IETF as a whole)
> 
> Since we have not yet formally adopted your draft as a working-group draft, and it is still an individual draft, the choice of authors/editors is "whoever wants to be". It is the WG chairs' responsibility to appoint authors/editors when a draft is formally adopted, but unless there is some specific reason to do otherwise, this is usually just the same authors and editors who contributed the individual draft. Once adopted, the authors/editors are required to follow the guidelines in https://tools.ietf.org/html/rfc2418#section-6.3

Steve, Moritz, other, specific suggestions for EBML authorship? Leave as Steve alone, add other working group members?

Here’s an update of the EBML draft. I’m not suggesting this is ‘done’ but it does meet the ‘words on a page’ test and happens to also look like an RFC draft.

Best Regards,
Dave Rice

---

From: "Timothy B. Terriberry" <[email-masked]>
Date: Fri, 17 Jun 2016 08:21:17 -0700

> Steve, Moritz, other, specific suggestions for EBML authorship? Leave as Steve alone, add other working group members?

Given the way you've been acting in capacity as editor thus far, I'd 
suggest you might want to consider adding yourself.

---

From: Dave Rice <[email-masked]>
Date: Mon, 20 Jun 2016 09:50:41 -0400

> On Jun 17, 2016, at 11:21 AM, Timothy B. Terriberry <[email-masked]> wrote:
> 
> Dave Rice wrote:
> Given the way you've been acting in capacity as editor thus far, I'd suggest you might want to consider adding yourself.

The PR is updated to add my name. https://github.com/Matroska-Org/ebml-specification/pull/66
Dave Rice

---

From: Dave Rice <[email-masked]>
Date: Wed, 29 Jun 2016 23:02:20 -0400

Hi all,

> On Jun 20, 2016, at 9:50 AM, Dave Rice <[email-masked]> wrote:
> 

I’ve submitted another pull request to change formatting to fix some of the issues with the RFC draft for EBML. The pr is reviewable here: https://github.com/Matroska-Org/ebml-specification/pull/70. It’s mostly adjustments to the presentation of tables and indentation as well as a few fixes to follow RFC2119 more accurately.

The new draft output of the makefile is here: https://gist.github.com/dericed/3ecc06cbc9abdeb3464f2c7d68d7b1ac

When I run the document through https://www.ietf.org/tools/idnits I get these error messages. Apparently some of the table of content numbering doesn’t follow recommended ip range recommendations.

idnits 2.14.01 

/tmp/draft-lhomme-cellar-ebml-00.txt:
/tmp/draft-lhomme-cellar-ebml-00.txt(859): Found possible IPv4 address '1.11.1.6' in position 38; this doesn't match the suggested documentation address ranges specified in RFC 6890 (or successor): blocks 192.0.2.0/24 (TEST-NET-1), 198.51.100.0/24 (TEST-NET-2), and 203.0.113.0/24 (TEST-NET-3); or the 233.252.0.0/24 (MCAST-TEST-NET) example multicast address range specified in RFC 5771.
/tmp/draft-lhomme-cellar-ebml-00.txt(904): Found possible IPv4 address '1.11.1.4' in position 38; this doesn't match the suggested documentation address ranges specified in RFC 6890 (or successor): blocks 192.0.2.0/24 (TEST-NET-1), 198.51.100.0/24 (TEST-NET-2), and 203.0.113.0/24 (TEST-NET-3); or the 233.252.0.0/24 (MCAST-TEST-NET) example multicast address range specified in RFC 5771.

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

     No issues found here.

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

     No issues found here.

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

  ** The document seems to lack an Abstract section.

  ** The document seems to lack an IANA Considerations section.  (See Section
     2.2 of http://www.ietf.org/id-info/checklist for how to handle the case
     when there are no actions for IANA.)

  ** The document seems to lack separate sections for Informative/Normative
     References.  All references will be assumed normative when checking for
     downward references.

  == There are 2 instances of lines with non-RFC6890-compliant IPv4 addresses
     in the document.  If these are example addresses, they should be changed.

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

  == Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 'SHOULD',
     or 'RECOMMENDED' is not an accepted usage according to RFC 2119.  Please
     use uppercase 'NOT' together with RFC 2119 keywords (if that is what you
     mean).
     
     Found 'MUST not' in this paragraph:
     
     As an XML Document, the EBML Schema MUST use "<EBMLSchema>" as the
     top level element.  The "<EBMLSchema>" element MAY contain "<element>"
     sub-elements.  Each "<element>" defines one EBML Element through the use
     of several attributes which are defined in the section on Section
     1.11.1.1.  EBML Schemas MAY contain additional attributes to extend the
     semantics but MUST not conflict is the definitions of the "<element>"
     attributes defined within this specification.

  == Couldn't figure out when the document was first submitted -- there may
     comments or warnings related to the use of a disclaimer for pre-RFC5378
     work that could not be issued because of this.  Please check the Legal
     Provisions document at http://trustee.ietf.org/license-info to determine
     if you need the pre-RFC5378 disclaimer.

  Checking references for intended status: Proposed Standard
  ----------------------------------------------------------------------------

     (See RFCs 3967 and 4897 for information about using normative references
     to lower-maturity documents in RFCs)

  -- Missing reference section? '1' on line 1116 looks like a reference
     '[1] https://tools.ietf.org/html/rfc2119...'

  -- Missing reference section? '2' on line 1118 looks like a reference
     '[2] http://www.faqs.org/rfcs/rfc2279.html...'

  -- Missing reference section? '3' on line 1120 looks like a reference
     '[3] http://www.w3.org/XML/Schema#dev...'

  -- Missing reference section? '4' on line 1122 looks like a reference
     '[4] http://www.w3.org/TR/xml/...'

  -- Missing reference section? '5' on line 1124 looks like a reference
     '[5] http://www.w3.org/TR/1999/REC-xml-names-19990114/#ns-decl...'

  -- Missing reference section? '6' on line 1126 looks like a reference
     '[6] https://www.w3.org/TR/xmlschema-0/#ref6...'

  -- Missing reference section? '7' on line 1128 looks like a reference
     '[7] https://www.w3.org/TR/xmlschema-0/#ref6...'

  -- Missing reference section? '8' on line 1130 looks like a reference
     '[8] http://www.open-std.org/jtc1/sc22/wg14/www/docs/n1570.pdf...'

  -- Missing reference section? '1A' on line 954 looks like a reference
     '| EBML ID     | [1A][45][DF][A3]...'

  -- Missing reference section? '45' on line 954 looks like a reference
     '| EBML ID     | [1A][45][DF][A3]...'

  -- Missing reference section? 'DF' on line 954 looks like a reference
     '| EBML ID     | [1A][45][DF][A3]...'

  -- Missing reference section? 'A3' on line 954 looks like a reference
     '| EBML ID     | [1A][45][DF][A3]...'

  -- Missing reference section? '42' on line 1059 looks like a reference
     '| EBML ID     | [42][85]...'

  -- Missing reference section? '86' on line 968 looks like a reference
     '| EBML ID     | [42][86]...'

  -- Missing reference section? 'F7' on line 981 looks like a reference
     '| EBML ID     | [42][F7]...'

  -- Missing reference section? 'F2' on line 995 looks like a reference
     '| EBML ID     | [42][F2]...'

  -- Missing reference section? 'F3' on line 1010 looks like a reference
     '| EBML ID     | [42][F3]...'

  -- Missing reference section? '82' on line 1032 looks like a reference
     '| EBML ID     | [42][82]...'

  -- Missing reference section? '87' on line 1045 looks like a reference
     '| EBML ID     | [42][87]...'

  -- Missing reference section? '85' on line 1059 looks like a reference
     '| EBML ID     | [42][85]...'

  -- Missing reference section? 'BF' on line 1075 looks like a reference
     '| EBML ID     | [BF]...'

  -- Missing reference section? 'EC' on line 1101 looks like a reference
     '| EBML ID     | [EC]...'

     Summary: 3 errors (**), 0 flaws (~~), 3 warnings (==), 22 comments (--).

Best Regards,
Dave Rice