[NUT-devel] [RFC] some suggestions for the spec

[Diego Biurrun]

I had these notes in my local tree from the last time I looked at the
spec.  Hopefully this is useful to point out problems and clarify the
spec a bit.

Diego
-------------- next part --------------
Index: nut.txt
===================================================================
--- nut.txt	(revision 23236)
+++ nut.txt	(working copy)
@@ -584,6 +584,7 @@
     global headers as long as no incorrect values are stored and as long as
     the stripped result is not less valid per codec spec as before stripping.
 
+FIXME: The frame_code description is convoluted and incomprehensible.
 frame_code (f(8))
     frame_code is an 8-bit field which exists before every frame, it can
     store part of the size of the frame, the stream number, the timestamp
@@ -602,6 +603,7 @@
                            presentation. (EOR)
        3  FLAG_CODED_PTS   If set, coded_pts is in the frame header.
        4  FLAG_STREAM_ID   If set, stream_id is coded in the frame header.
+FIXME: What does "at the frame header" mean?
        5  FLAG_SIZE_MSB    If set, data_size_msb at the frame header,
                            otherwise data_size_msb is 0.
        6  FLAG_CHECKSUM    If set, the frame header contains a checksum.
@@ -612,7 +614,7 @@
     EOR frames MUST be zero-length and must be set keyframe.
     All streams SHOULD end with EOR, where the pts of the EOR indicates the
     end presentation time of the final frame.
-    An EOR set stream is unset by the first content frames.
+    An EOR set stream is unset by the first content frame.
     EOR can only be unset in streams with zero decode_delay .
     FLAG_CHECKSUM MUST be set if the frame's data_size is strictly greater than
     2*max_distance or the difference abs(pts-last_pts) is strictly greater than
@@ -795,7 +797,7 @@
     The ID of the chapter this packet applies to. If zero, the packet applies
     to the whole file. Positive chapter_id values represent real chapters and
     MUST NOT overlap.
-    A negative chapter_id indicates a sub region of the file and not a real
+    A negative chapter_id indicates a region of the file and not a real
     chapter. chapter_id MUST be unique to the region it represents.
     chapter_id n MUST NOT be used unless there are at least n chapters in the
     file.
@@ -830,6 +832,7 @@
     "Source"
         "DVD", "VCD", "CD", "MD", "FM radio", "VHS", "TV", "LD"
         Optional: Appended PAL, NTSC, SECAM, ... in parentheses.
+FIXME: Does this have to be lowercase?
     "SourceContainer"
         "nut", "mkv", "mov", "avi", "ogg", "rm", "mpeg-ps", "mpeg-ts", "raw"
     "SourceCodecTag"
@@ -849,6 +852,7 @@
         including "und" (Undetermined), "mul" (Multiple languages).
         See http://www.loc.gov/standards/iso639-2/
         and http://www.din.de/gremien/nas/nabd/iso3166ma/codlstp1/en_listp1.html
+FIXME: Does the following line have a meaning here?
         the language code
         A demuxer MUST ignore unknown language and country codes instead of
         treating them as an error.
@@ -884,6 +888,7 @@
 Headers may be repeated, but if they are, then they MUST all be repeated
 together and repeated headers MUST be identical.
 
+FIXME: This description is confusing, after 2^x *and* end of file???
 Each set of repeated headers not at the beginning or end of the file SHOULD
 be stored at the earliest possible position after 2^x where x is an integer
 and the end of the file. So the headers may be repeated at 4102 if that is
@@ -923,6 +928,7 @@
 demuxer (non-normative):
 ------------------------
 
+FIXME: Where is the syncpoint included?
 In the absence of a valid header at the beginning, players SHOULD search for
 backup headers starting at offset 2^x; for each x players SHOULD end their
 search at a particular offset when any startcode (including a syncpoint) is