Subject: Re: [Cellar] Matroska document titles

From: Steve Lhomme <[email-masked]>
Date: Sun, 8 Mar 2020 08:28:22 +0100

Hi Spencer,

The codec document will likely evolve more. I'd like to have one core
document describing how codecs are mapped and each type of codec and
small documents relating to this core document for each codec. (raw
codecs could be just one big document) So I don't think the name is
relevant yet.

The tags will likely remain as it is now. But I'm not sure what is
wrong with "Matroska Tags". Should it be longer ? Or in a different
grammatical form like "Tags used in Matroska" ?

The same question applies to the "Matroska Specifications". Is it too
broad ? This is the core documentation of the format.

Le mer. 19 févr. 2020 à 02:34, Spencer Dawkins at IETF
<[email-masked]> a écrit :
>
> Dear Cellar Folk,
>
> I'm wondering if the Matroska document titles could be more descriptive.
>
> I'm looking at the abstracts for these documents, and wondering if the titles accurately describe the contents of the first two documents. (The third document seems fine to me)
>
> Thoughts?
>
> Best,
>
> Spencer
>
> Matroska Codec - https://datatracker.ietf.org/doc/draft-ietf-cellar-codec/
>
> Abstract
>
>    This document defines the Matroska codec mappings, including the
>    codec ID, layout of data in a "Block Element" and in an optional
>    "CodecPrivate Element".
>
> Matroska Specifications - https://datatracker.ietf.org/doc/draft-ietf-cellar-matroska/
>
> Abstract
>
>    This document defines the Matroska audiovisual container, including
>    definitions of its structural elements, as well as its terminology,
>    vocabulary, and application.
>
> Matroska Tags - https://datatracker.ietf.org/doc/draft-ietf-cellar-tags/
>
> Abstract
>
>    This document defines the Matroska tags, namely the tag names and
>    their respective semantic meaning.
> _______________________________________________
> Cellar mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/cellar

-- 
Steve Lhomme
Matroska association Chairman

---

From: Spencer Dawkins at IETF <[email-masked]>
Date: Mon, 9 Mar 2020 20:01:46 -0500

Hi, Steve,

Thanks very much for following up on this.

For the purpose of this note, please consider that I'm not replying as one
of the co-chairs.

> codecs could be just one big document) So I don't think the name is

I didn't say clearly enough that I have no desire to ask you folks to make
structural changes to the Matroska document suite. I'm sorry if that
confused anyone. I'm only curious about the document titles.

And I really want to defer to the working group about the actual titles, so
please do the right thing.

So, here's what I've seen people do with multi-document specifications at
the IETF.

   - People use common title prefixes in Internet Drafts and RFCs to make
   it easier to find stuff that is part of the specification, and to not find
   things that aren't. If something like "Matroska Media Container" as a
   prefix would apply to any of the specifications you're working on now or
   thinking about in the future, that would be helpful to your readers. I
   assumed that form in the following suggestions, so if you can think of a
   better prefix, please use it to improve the following suggestions!
   - For "Matroska Tags", that's pretty close to what I'd hope for. If it
   was "Matroska Media Container Tags", would that work?
   - For "Matroska Codec" - the abstract says this is actually "Matroska
   Codec Mappings", so that seems like the title needs to change a bit more.
   If the document title was something like "Matroska Media Container Codec
   Mappings", would that work?
   - For "Matroska Specifications", that probably is too broad (because
   there are two other Matroska specifications in the working group now). You
   used the term "core" in your reply, and I know the working group has been
   considering whether to publish chapters in a separate document, so it seems
   possible that there will be at least one non-core specification at some
   point. Would it be accurate to use something like "Matroska Media Container
   Core Specification" for this one?

There are (many) other titles that would work for me, so please don't focus
on the details.

If it's helpful to know why I sent my first note ...

   - These documents are important enough that people who you don't know,
   are looking at them now, while they're still being developed.
   - I've been having conversations with people outside the working group,
   and outside my employer's community, about planning for Matroska. I expect
   I'm not the only person doing that. It seems helpful for planners to be
   able to find what they need to be looking at.
   - Michael and I have been asked to provide a write-up about what's
   happening in CELLAR to the IEEE standards journal, and the Matroska
   documents would be featured prominently in that, and IEEE journals go all
   over the planet, but I don't want to confuse people all over the planet.
   - It's lightweight to change draft document titles, so even if you
   change a title more than once, it can accurately reflect the contents at
   any particular point in time.

And thanks, again, for the opportunity to be clearer on what I was thinking.

Best,

Spencer

> > I'm looking at the abstracts for these documents, and wondering if the
> titles accurately describe the contents of the first two documents. (The
> third document seems fine to me)
> >
> > Thoughts?
> >
> > Best,
> >
> > Spencer
> >
> > Matroska Codec -
> https://datatracker.ietf.org/doc/draft-ietf-cellar-codec/
> >
> > Abstract
> >
> > Matroska Specifications -
> https://datatracker.ietf.org/doc/draft-ietf-cellar-matroska/
> >
> > Abstract
> >

---

From: Dave Rice <[email-masked]>
Date: Mon, 16 Mar 2020 19:00:47 -0400

> On Mar 9, 2020, at 9:01 PM, Spencer Dawkins at IETF <[email-masked]> wrote:
> 
> Hi, Steve, 
> 
> For the purpose of this note, please consider that I'm not replying as one of the co-chairs. 
> 
> On Sun, Mar 8, 2020 at 1:28 AM Steve Lhomme <[email-masked] <mailto:[email-masked]>> wrote:
> Hi Spencer,
> 
> I didn't say clearly enough that I have no desire to ask you folks to make structural changes to the Matroska document suite. I'm sorry if that confused anyone. I'm only curious about the document titles. 
> 
> And I really want to defer to the working group about the actual titles, so please do the right thing. 
> 
> So, here's what I've seen people do with multi-document specifications at the IETF.
> People use common title prefixes in Internet Drafts and RFCs to make it easier to find stuff that is part of the specification, and to not find things that aren't. If something like "Matroska Media Container" as a prefix would apply to any of the specifications you're working on now or thinking about in the future, that would be helpful to your readers. I assumed that form in the following suggestions, so if you can think of a better prefix, please use it to improve the following suggestions!
> For "Matroska Tags", that's pretty close to what I'd hope for. If it was "Matroska Media Container Tags", would that work?
> For "Matroska Codec" - the abstract says this is actually "Matroska Codec Mappings", so that seems like the title needs to change a bit more. If the document title was something like "Matroska Media Container Codec Mappings", would that work?
> For "Matroska Specifications", that probably is too broad (because there are two other Matroska specifications in the working group now). You used the term "core" in your reply, and I know the working group has been considering whether to publish chapters in a separate document, so it seems possible that there will be at least one non-core specification at some point. Would it be accurate to use something like "Matroska Media Container Core Specification" for this one?
I’m not sure about the word ‘Media’, how about:
Matroska File Format Specification
Matroska File Format Codec Mappings
Matroska File Format Metadata Tags

I think the term “File Format” is a bit more accessible than “Container”. Also I see that MXF uses similar wording at http://web.archive.org/web/20051210203751/http://www.smpte.org/smpte_store/standards/pdf/s377m.pdf <http://web.archive.org/web/20051210203751/http://www.smpte.org/smpte_store/standards/pdf/s377m.pdf>.

> There are (many) other titles that would work for me, so please don't focus on the details. 
> 
> These documents are important enough that people who you don't know, are looking at them now, while they're still being developed.
> I've been having conversations with people outside the working group, and outside my employer's community, about planning for Matroska. I expect I'm not the only person doing that. It seems helpful for planners to be able to find what they need to be looking at. 
> Michael and I have been asked to provide a write-up about what's happening in CELLAR to the IEEE standards journal, and the Matroska documents would be featured prominently in that, and IEEE journals go all over the planet, but I don't want to confuse people all over the planet.  
> It's lightweight to change draft document titles, so even if you change a title more than once, it can accurately reflect the contents at any particular point in time.   
> <[email-masked] <mailto:[email-masked]>> a écrit :
> >
> > Dear Cellar Folk,
> >
> > Matroska Codec - https://datatracker.ietf.org/doc/draft-ietf-cellar-codec/ <https://datatracker.ietf.org/doc/draft-ietf-cellar-codec/>
> >
> > Abstract
> >
> > Matroska Specifications - https://datatracker.ietf.org/doc/draft-ietf-cellar-matroska/ <https://datatracker.ietf.org/doc/draft-ietf-cellar-matroska/>
> >
> > Abstract
> >
> > Matroska Tags - https://datatracker.ietf.org/doc/draft-ietf-cellar-tags/ <https://datatracker.ietf.org/doc/draft-ietf-cellar-tags/>
> >
> > Abstract
> >
> > [email-masked] <mailto:[email-masked]>
> > https://www.ietf.org/mailman/listinfo/cellar <https://www.ietf.org/mailman/listinfo/cellar>
> 
> 
> 
> -- 
> Steve Lhomme

---

From: Spencer Dawkins at IETF <[email-masked]>
Date: Mon, 16 Mar 2020 19:18:43 -0500

Hi, Dave,

On Mon, Mar 16, 2020 at 6:00 PM Dave Rice <[email-masked]> wrote:

> [deleted down to]

> I think the term “File Format” is a bit more accessible than “Container”.
> Also I see that MXF uses similar wording at
> http://web.archive.org/web/20051210203751/http://www.smpte.org/smpte_store/standards/pdf/s377m.pdf
> .
>
> I still want to defer to the working group on the exact titles, but your
proposals capture the ideas I was trying to convey in my proposals (looks
like a document set, clearer what the relationship between the documents
is, and titles seem clear to me).

And thanks for the pointer to the MXF document. It may be useful to match
their terminology, given an opportunity to do so.

Do The Right Thing, of course :-)

Best,

Spencer

---

From: Jerome Martinez <[email-masked]>
Date: Tue, 17 Mar 2020 09:35:20 +0100

On 17/03/2020 00:00, Dave Rice wrote:

> I’m not sure about the word ‘Media’,

It may make titles too long without a big added value.

> how about:

Matroska File Format Core Specification?

> [...]

Matroska can be used without a storage device, e.g. streaming.
Checking a definition of "file" [1], it may limit the scope of Matroska 
in the mind of people.
"Container" is more and more known [2] and more generic IMO.
In contrast another well known container format [3], also having some 
streaming capabilities, has "file" in its name, so maybe better to match 
the terminology seen in other similar formats.

[1] https://en.wikipedia.org/wiki/Computer_file
[2] https://en.wikipedia.org/wiki/Digital_container_format
[3] https://en.wikipedia.org/wiki/ISO/IEC_base_media_file_format

---

From: Steve Lhomme <[email-masked]>
Date: Sun, 29 Mar 2020 13:51:44 +0200

I agree with Jérôme on both. Container is the proper word, although nowadays it's more popular for other things. We should use the proper word ASAP so we don't create confusion like we had with our own concept of timecodes.

The "core" may be tricky. It sounds like it's the bare minimum to Matroska when in fact a lot of things are not essential (Cues or Chapters for example).

How about 
Matroska Media Container Format Specifications
Matroska Media Container Codec Specifications
Matroska Media Container Tags Specifications 

> On 17 Mar 2020, at 09:35, Jerome Martinez <[email-masked]> wrote:
> 
> Checking a definition of "file" [1], it may limit the scope of Matroska in the mind of people.
> In contrast another well known container format [3], also having some streaming capabilities, has "file" in its name, so maybe better to match the terminology seen in other similar formats.
>