Subject: [Cellar] Matroska schema Table of Contents numbering

From: Kieran O Leary <[email-masked]>
Date: Mon, 23 Jul 2018 11:25:12 +0100

Hi all,

I've been dipping in and out of the Matroska draft spec in the last
week, and I had one suggestion regarding the table of contents.

Currently, section 8.2 (Matroska Schema) has 243 child entries. I
think that it would make the document easier to parse through if the
numbering system for the ToC reflected the parent child relationships
of the elements.

For example:

8.2.112. BitsPerChannel Element has a path of

"0*1(\Segment\Tracks\TrackEntry\Video\Colour\BitsPerChannel)

So, perhaps this element could be numbered:

8.2.3.                   Segment
8.2.3.3.                Segment\Tracks
8.2.3.3.1.             Segment\Tracks\TrackEntry
8.2.3.3.1.9.          Segment\Tracks\TrackEntry\Video
8.2.3.3.1.9.10 .    Segment\Tracks\TrackEntry\Video\Color
8.2.3.3.1.9.10.2.  Segment\Tracks\TrackEntry\Video\Color\BitsPerChannel

While that ends up being a long index number, it would allow the table
of contents to represent the parent/child relationship between
elements. This might mess with automation or whatever, so I'm just
curious to know if anyone else would find it useful? If this had to be
done manually, I'd volunteer to do so.

It would allow these elements to look a bit more like the Menu example:

14. Menu Specifications . . . . . . . . . . . . . . . . . . . 142
     14.1.  Introduction . . . . . . . . . . . . . . . . . . . . . 142
     14.2.  Requirements . . . . . . . . . . . . . . . . . . . 143
       14.2.1.  Highlights/Hotspots  . . . . . . . . . . . .143
       14.2.2.  Playback features  . . . . . . . . . . . . . 144
       14.2.3.  Player requirements  . . . . . . . . . . . 144
     14.3.  Working Graph  . . . . . . . . . . . . . .  . . . 144
     14.4.  Ideas  . . . . . . . . . . . . . . . . . . . . . . . . . 145
     14.5.  Data Structure . . . . . . . . . . . . . . . .  . . 145

I found this approach useful when scanning the PREMIS data dictionary
( http://www.loc.gov/standards/premis/v3/premis-hierarchical-3-0.html)
, which looks a bit like this:

1.5    objectCharacteristics (M, R) [File, Bitstream]
        1.5.1    compositionLevel (O, NR) [File, Bitstream]
        1.5.2    fixity (O, R) [File, Bitstream]
                   1.5.2.1    messageDigestAlgorithm (M, NR) [File, Bitstream]
                   1.5.2.2    messageDigest (M, NR) [File, Bitstream]
                   1.5.2.3    messageDigestOriginator (O, NR) [File, Bitstream]
        1.5.3    size (O, NR) [File, Bitstream]
        1.5.4    format (M, R) [File, Bitstream]
                   1.5.4.1    formatDesignation (O, NR) [File, Bitstream]
                        1.5.4.1.1    formatName (M, NR) [File, Bitstream]
                        1.5.4.1.2    formatVersion (O, NR) [File, Bitstream]
                   1.5.4.2    formatRegistry (O, NR) [File, Bitstream]
                        1.5.4.2.1    formatRegistryName (M, NR) [File,
Bitstream]
                        1.5.4.2.2    formatRegistryKey (M, NR) [File, Bitstream]
                        1.5.4.2.3    formatRegistryRole (O, NR) [File,
Bitstream]
                   1.5.4.3    formatNote (O, R) [File, Bitstream]

Best,

Kieran O'Leary,
IFI Irish Film Archive.

---

From: Kieran O Leary <[email-masked]>
Date: Mon, 23 Jul 2018 13:23:16 +0100

Ok,so it looks like the XML transformation would prevent this from
occurring.

---

From: Dave Rice <[email-masked]>
Date: Mon, 23 Jul 2018 09:09:54 -0400

Hi,
When I was working on the xml transformation I did at one point have it nesting of the sections adjust according to the depth of the associated element. Basically I just had a counter add an extra ‘#’ character in the section header for every level of depth for that element. However the output rfc document then had a table of contents that only went down to a certain depth maybe 4 or 5. In Matroska some elements goes much deeper so have a nested element table of contents with our current document build system, resulting in some elements being hidden from the toc. I’m unclear if there is a depth limit for RFC TOC’s or if it’s a limitation of mmark or rfc2xml, but if it’s the latter and there’s interest in having the TOC as Kieran suggests then we could retry it.
Dave Rice

> On Jul 23, 2018, at 8:23 AM, Kieran O Leary <[email-masked]> wrote:
> 
> Ok,so it looks like the XML transformation would prevent this from occurring.
> _______________________________________________
> Cellar mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/cellar

---

From: Michael Richardson <[email-masked]>
Date: Mon, 23 Jul 2018 10:23:07 -0400

Dave Rice <[email-masked]> wrote:
    > When I was working on the xml transformation I did at one point have it
    > nesting of the sections adjust according to the depth of the associated
    > element. Basically I just had a counter add an extra ‘#’ character in
    > the section header for every level of depth for that element. However
    > the output rfc document then had a table of contents that only went
    > down to a certain depth maybe 4 or 5. In Matroska some elements goes
    > much deeper so have a nested element table of contents with our current
    > document build system, resulting in some elements being hidden from the
    > toc. I’m unclear if there is a depth limit for RFC TOC’s or if it’s a
    > limitation of mmark or rfc2xml, but if it’s the latter and there’s
    > interest in having the TOC as Kieran suggests then we could retry it.

I think that the xml2rfc tool has a setting for depth of ToC produced.

The RFC-Editor might mildly object, but it may be worth tweaking things in
this case, if the WG would prefer a deeper ToC.   If we want to go this way,
then I'll query the RFC-editor for their blessing.

--
Michael Richardson <[email-masked]>, Sandelman Software Works
 -= IPv6 IoT consulting =-

---

From: Dave Rice <[email-masked]>
Date: Mon, 23 Jul 2018 10:35:47 -0400

> On Jul 23, 2018, at 10:23 AM, Michael Richardson <[email-masked]> wrote:
> 
> 

Such to consider the sanity of it, we’d have a TOC that goes to a depth of 9 subsections if each element was to be referenced in the toc.
Dave

---

From: Steve Lhomme <[email-masked]>
Date: Mon, 23 Jul 2018 17:41:00 +0200

It seems adding something like <?rfc tocdepth='10'?> in the XML source
would be enough (number 10 picked randomly).

Source: https://xml2rfc.tools.ietf.org/authoring/README.html

We have to be careful with global elements that don't actually have a
parent. There's none in Matroska but some in EBML.

-- 
Steve Lhomme
Matroska association Chairman

---

From: Michael Richardson <[email-masked]>
Date: Mon, 23 Jul 2018 12:31:43 -0400

Dave Rice <[email-masked]> wrote:
    > Such to consider the sanity of it, we’d have a TOC that goes to a depth
    > of 9 subsections if each element was to be referenced in the toc.

Understood.
If it organizes things better then great.
If it makes sense to have a shallower ToC, omitting some detail in the ToC,
then do that.  I suggest trying it out.