Subject: [Cellar] Refining language in Matroska specification

From: Ashley Blewer <[email-masked]>
Date: Sun, 30 Jul 2017 12:54:48 -0400

Hi CELLAR!

I have been reading through the Matroska specification and thinking about
the clarity of the language, especially in the light of RFC 2119
<https://www.ietf.org/rfc/rfc2119.txt>. I'm considering Tim's initial
review of the ebml-specification
<https://mailarchive.ietf.org/arch/msg/cellar/Mfj44tK1gyfqjU3Uu1tI5fMovtk>
as a guide to the kind of language clean-up that can be done towards making
this an IETF-approved spec.

I skipped the Intro section and went straight for the Diagram section. (It
seemed more polite to start there, as a non-original-author.) I have opened
up a PR here:
https://github.com/Matroska-Org/matroska-specification/pull/156

I would like to continue this work, but would appreciate some feedback
before I consider the other sections.

Off-list, to Dave Rice, I brought up the question of how to speak of and
quote (or backtick, in Markdown) related elements, and he recommended I
follow the patterns in ebml-specification, so I did my best to do that. My
question was around if elements should be defined and described as `Example
Element`, `Example` Element, or `Example`. (The recommendation is for the
first of that group of three). If that turns out to not be the case, I can
remediate.

Thanks all,

Ashley

---

From: Ashley Blewer <[email-masked]>
Date: Sun, 30 Jul 2017 18:51:05 -0400

Hello! To follow up on this and much great feedback from Moritz, I moved on
to Ordered Guidelines part of the Matroska specification.

I opened a PR with some small changes
<https://github.com/Matroska-Org/matroska-specification/pull/157>, but have
a larger question (also repeated in the PR dialogue box):

Overall, I am wondering if the content in ordered_guidelines should be
checked for duplication in the rest of the specification and then left out
of the RFC Makefile. It seems to me that most of this section is either
repeated elsewhere (diagram.md -- with conflicting information, as I
commented in the above PR #156 ) or it contains recommendations not
required to be in the official specification. Thoughts?

My best,

Ashley 🐳

On Sun, Jul 30, 2017 at 12:54 PM, Ashley Blewer <[email-masked]>
wrote:

> up a PR here: https://github.com/Matroska-Org/matroska-
> specification/pull/156
>

---

From: Tessa Fallon <[email-masked]>
Date: Mon, 31 Jul 2017 02:54:11 -0400

Ashley,

It seems like you're doing great work with this.

Thanks,
Tessa

On Sun, Jul 30, 2017 at 6:51 PM, Ashley Blewer <[email-masked]>
wrote:

> Hello! To follow up on this and much great feedback from Moritz, I moved
> on to Ordered Guidelines part of the Matroska specification.
>
> <https://github.com/Matroska-Org/matroska-specification/pull/157>, but
> have a larger question (also repeated in the PR dialogue box):
>
>> I skipped the Intro section and went straight for the Diagram section.
>> (It seemed more polite to start there, as a non-original-author.) I have
>> opened up a PR here: https://github.com/Matro
>> ska-Org/matroska-specification/pull/156
>>
> _______________________________________________
> Cellar mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/cellar
>
>

---

From: Tessa Fallon <[email-masked]>
Date: Mon, 31 Jul 2017 02:55:07 -0400

Sorry, not meant to be posted on the list. My bad.

On Mon, Jul 31, 2017 at 2:54 AM, Tessa Fallon <[email-masked]>
wrote:

>>> I have been reading through the Matroska specification and thinking
>>> about the clarity of the language, especially in the light of RFC 2119