Subject: [Cellar] presenting Matroska Elements in document sections

From: Dave Rice <[email-masked]>
Date: Thu, 6 Oct 2016 00:19:51 -0400

Hi all,

The presentation of the Matroska elements in the initial submitted draft was in odd tables <https://tools.ietf.org/html/draft-lhomme-cellar-matroska-00#section-8>. This pull request <https://github.com/Matroska-Org/matroska-specification/pull/52> adjusts the conversion of Matroska elements from the ebml_matroska.xml file into a series of sections that each contain the vocabulary of the EBML Schema with some additional extrapolated content (listing Child Elements). Here is a preview of the new output in RFC HTML form <http://htmlpreview.github.io/?https://gist.githubusercontent.com/dericed/f6f271ca86e79d2f624a74bc65bd861e/raw/35aa838db68fe57ecd4f0dc92c55907ff4535818/elements.html#rfc.section.7.3.1> and in markdown form <https://gist.github.com/dericed/e6ed55a897462faf4b41cda892eec3b6>. Keep in mind that the past presentation of Matroska Elements was in a shaded HTML table <https://matroska.org/technical/specs/index.html#Segment>.

The total list of Elements (in the proposed format of sections) accounts for 7,124 of 11,649 lines (over 60% of a 208 page RFC).

Suggestions for adjustments to make the Elements more clearly or precisely presented?

Should an RFC for Matroska include both the EBML Schema of Matroska (a 713 lines XML document) and the Elements presented in such sections? Should one of those forms (XML vs Elements sections) be identified as authoritative over the other? The benefits of using a section per Element is that is enables better referencing to Element sections within an RFC. For similar reasons the EBML draft has already had conversion <https://github.com/Matroska-Org/ebml-specification/issues/89> of many of its tables to sections.

Kind Regards,
Dave Rice

---

From: Steve Lhomme <[email-masked]>
Date: Sun, 16 Oct 2016 14:38:26 +0200

2016-10-06 6:19 GMT+02:00 Dave Rice <[email-masked]>:
> Hi all,
>
> The presentation of the Matroska elements in the initial submitted draft was
> in odd tables. This pull request adjusts the conversion of Matroska elements
> from the ebml_matroska.xml file into a series of sections that each contain
> the vocabulary of the EBML Schema with some additional extrapolated content
> (listing Child Elements). Here is a preview of the new output in RFC HTML
> form and in markdown form. Keep in mind that the past presentation of
> Matroska Elements was in a shaded HTML table.
>
> The total list of Elements (in the proposed format of sections) accounts for
> 7,124 of 11,649 lines (over 60% of a 208 page RFC).
>

I would replace Context with the Path. A neat feature in the HTML
version would be able to click on a parent element directly from the
path.

I would not list the children. This is adding extra text that's
already found elsewhere. It also becomes invalid if elements are
defined in a separate specification. The way to describe a parent in
the path can only have one form so it's easy to search the document
for elements that have that path in them. On the other hand there are
a lot of false positive with children of direct children.

When minOccurs or maxOccurs has the default value they may be omitted.

> Should an RFC for Matroska include both the EBML Schema of Matroska (a 713
> lines XML document) and the Elements presented in such sections? Should one
> of those forms (XML vs Elements sections) be identified as authoritative
> over the other? The benefits of using a section per Element is that is
> enables better referencing to Element sections within an RFC. For similar
> reasons the EBML draft has already had conversion of many of its tables to
> sections.

I'd say we should have noth. The textual/section is the authorative
part. Especially because it can (and will) have finer details on each
element. The XML file should be in an Annex as a machine friendly
version.

> Kind Regards,
> Dave Rice
>
> _______________________________________________
> Cellar mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/cellar
>

-- 
Steve Lhomme
Matroska association Chairman

---

From: Steve Lhomme <[email-masked]>
Date: Sun, 16 Oct 2016 14:42:28 +0200

> a lot of false positive with children of direct children.

Also parent should be removed if we add the path. In HTML the
navigation remains easy to do. In a text RFC format that's trickier.
But then there's no hyperlink anyway.