[e] (0) More information for cue syntax.

Fixing http://www.w3.org/Bugs/Public/show_bug.cgi?id=12813 git-svn-id: http://svn.whatwg.org/webapps@6366 340c8d12-0b0e-0410-8428-c7bf67bfef74
whatwg · Aug 4, 2011 · f3989bd · f3989bd
1 parent d9a844d
commit f3989bd
Show file tree

Hide file tree

Showing 3 changed files with 166 additions and 16 deletions.
diff --git a/complete.html b/complete.html
@@ -32038,7 +32038,12 @@ <h6 id=syntax-0><span class=secno>4.8.10.13.2 </span>Syntax</h6>
    <li>Optionally, one or more U+0020 SPACE characters or U+0009 CHARACTER TABULATION (tab) characters followed by <a href=#webvtt-cue-settings>WebVTT cue settings</a>.</li>
    <li>A <a href=#webvtt-line-terminator>WebVTT line terminator</a>.</li>
    <li>The <dfn id=cue-payload>cue payload</dfn>: either <a href=#webvtt-cue-text>WebVTT cue text</a> or <a href=#webvtt-metadata-text>WebVTT metadata text</a>.</li>
-  </ol><p><a href=#webvtt-cue-text>WebVTT cue text</a> is syntactically a subset of
+  </ol><p class=note>A <a href=#webvtt-cue>WebVTT cue</a> corresponds to one piece
+  of time-aligned text or data in the <a href=#webvtt-file>WebVTT file</a>, for
+  example one subtitle. The <a href=#cue-payload>cue payload</a> is the text or
+  data associated with the cue.</p>
+
+  <p><a href=#webvtt-cue-text>WebVTT cue text</a> is syntactically a subset of
   <a href=#webvtt-metadata-text>WebVTT metadata text</a>. Conformance checkers, when
   validating <a href=#webvtt>WebVTT</a> files, may offer to restrict all cues
   to only having <a href=#webvtt-cue-text>WebVTT cue text</a> as their <a href=#cue-payload>cue
@@ -32062,6 +32067,9 @@ <h6 id=syntax-0><span class=secno>4.8.10.13.2 </span>Syntax</h6>
   SIGN), nor containing any U+000A LINE FEED (LF) characters or U+000D
   CARRIAGE RETURN (CR) characters.</p>
 
+  <p class=note>A <a href=#webvtt-cue-identifier>WebVTT cue identifier</a> can be used to
+  reference a specific cue, for example from script or CSS.</p>
+
   <p>The <dfn id=webvtt-cue-timings>WebVTT cue timings</dfn> part of a <a href=#webvtt-cue>WebVTT
   cue</a> consists of the following components, in the given
   order:</p>
@@ -32085,7 +32093,11 @@ <h6 id=syntax-0><span class=secno>4.8.10.13.2 </span>Syntax</h6>
    timestamp</a> must be greater than the start time offset of the
    cue.</li>
 
-  </ol><p>A <dfn id=webvtt-timestamp>WebVTT timestamp</dfn> representing a time in seconds and
+  </ol><p class=note>The <a href=#webvtt-cue-timings>WebVTT cue timings</a> give the start
+  and end offsets of the <a href=#webvtt-cue>WebVTT cue</a>. Different cues can
+  overlap. Cues are always listed ordered by their start time.</p>
+
+  <p>A <dfn id=webvtt-timestamp>WebVTT timestamp</dfn> representing a time in seconds and
   fractions of a second is a <a href=#webvtt-timestamp>WebVTT timestamp</a>
   representing hours <var title="">hours</var>, minutes <var title="">minutes</var>, seconds
   <var title="">seconds</var>, and thousandths of a second <var title="">seconds-frac</var>, calculated as follows:</p>
@@ -32144,13 +32156,23 @@ <h6 id=syntax-0><span class=secno>4.8.10.13.2 </span>Syntax</h6>
    <li>A <a href=#webvtt-text-position-cue-setting>WebVTT text position cue setting</a>.</li> <!-- T:100% -->
    <li>A <a href=#webvtt-size-cue-setting>WebVTT size cue setting</a>.</li>          <!-- S:100% -->
    <li>A <a href=#webvtt-alignment-cue-setting>WebVTT alignment cue setting</a>.</li>     <!-- A:start/middle/end -->
-  </ul><p>A <dfn id=webvtt-vertical-text-cue-setting>WebVTT vertical text cue setting</dfn> consists of the
+  </ul><p class=note><a href=#webvtt-cue-settings>WebVTT cue settings</a> give configuration
+  options regarding the position and alignment of the cue. For
+  example, it allows a cue to be aligned to the left or positioned at
+  the top right.</p>
+
+  <p>A <dfn id=webvtt-vertical-text-cue-setting>WebVTT vertical text cue setting</dfn> consists of the
   following components, in the order given:</p>
 
   <ol><li>A U+0044 LATIN CAPITAL LETTER D character.</li>
    <li>A U+003A COLON character (:).</li>
    <li>One of the following strings: "<code title="">vertical</code>", "<code title="">vertical-lr</code>".</li>
-  </ol><p>A <dfn id=webvtt-line-position-cue-setting>WebVTT line position cue setting</dfn> consists of the
+  </ol><p class=note>A <a href=#webvtt-vertical-text-cue-setting>WebVTT vertical text cue setting</a>
+  configures the cue to use vertical text layout rather than
+  horizontal text layout. Vertical text layout is sometimes used in
+  Japanese, for example. The default is horiontal layout.</p>
+
+  <p>A <dfn id=webvtt-line-position-cue-setting>WebVTT line position cue setting</dfn> consists of the
   following components, in the order given:</p>
 
   <ol><li><p>A U+004C LATIN CAPITAL LETTER L character.</li>
@@ -32167,27 +32189,55 @@ <h6 id=syntax-0><span class=secno>4.8.10.13.2 </span>Syntax</h6>
        <li>One or more characters in the range U+0030 DIGIT ZERO (0) to U+0039 DIGIT NINE (9).</li>
       </ol></dd>
     </dl></li>
-  </ol><p>A <dfn id=webvtt-text-position-cue-setting>WebVTT text position cue setting</dfn> consists of the
+  </ol><p class=note>A <a href=#webvtt-line-position-cue-setting>WebVTT line position cue setting</a>
+  configures the position of the cue. For horizontal cues, this is the
+  vertical position. The position can be given either as a percentage,
+  which gives the distance from the top of the frame, or as a line
+  number. Line numbers are based on the size of the first line of the
+  cue. Positive line numbers count from the top of the frame (the top
+  line is numbered 0), negative line numbers from the bottom of the
+  frame (the bottom line is numbered &minus;1).</p>
+
+  <p>A <dfn id=webvtt-text-position-cue-setting>WebVTT text position cue setting</dfn> consists of the
   following components, in the order given:</p>
 
   <ol><li>A U+0054 LATIN CAPITAL LETTER T character.</li>
    <li>A U+003A COLON character (:).</li>
    <li>One or more characters in the range U+0030 DIGIT ZERO (0) to U+0039 DIGIT NINE (9).</li>
    <li>A U+0025 PERCENT SIGN character (%).</li>
-  </ol><p>A <dfn id=webvtt-size-cue-setting>WebVTT size cue setting</dfn> consists of the
+  </ol><p class=note>A <a href=#webvtt-text-position-cue-setting>WebVTT text position cue setting</a>
+  configures the position of the text in the direction orthogonal to
+  the <a href=#webvtt-line-position-cue-setting>WebVTT line position cue setting</a>. For horizontal
+  cues, this is the horizontal position. The <a href=#webvtt-text-position-cue-setting>WebVTT text
+  position cue setting</a> is given as a percentage, calculated
+  from the edge of the frame that the text begins (so for
+  left-to-right English text, the left edge).</p>
+
+  <p>A <dfn id=webvtt-size-cue-setting>WebVTT size cue setting</dfn> consists of the
   following components, in the order given:</p>
 
   <ol><li>A U+0053 LATIN CAPITAL LETTER S character.</li>
    <li>A U+003A COLON character (:).</li>
    <li>One or more characters in the range U+0030 DIGIT ZERO (0) to U+0039 DIGIT NINE (9).</li>
    <li>A U+0025 PERCENT SIGN character (%).</li>
-  </ol><p>A <dfn id=webvtt-alignment-cue-setting>WebVTT alignment cue setting</dfn> consists of the
+  </ol><p class=note>A <a href=#webvtt-size-cue-setting>WebVTT size cue setting</a> configures
+  the size of the cue in the same direction as the <a href=#webvtt-text-position-cue-setting>WebVTT text
+  position cue setting</a>. For horizontal cues, this is the width
+  of the cue. It is given as a percentage of the width of the
+  frame.</p>
+
+  <p>A <dfn id=webvtt-alignment-cue-setting>WebVTT alignment cue setting</dfn> consists of the
   following components, in the order given:</p>
 
   <ol><li>A U+0041 LATIN CAPITAL LETTER A character.</li>
    <li>A U+003A COLON character (:).</li>
    <li>One of the following strings: "<code title="">start</code>", "<code title="">middle</code>", "<code title="">end</code>"</li>
-  </ol><p><dfn id=webvtt-metadata-text>WebVTT metadata text</dfn> consists of any sequence of one
+  </ol><p class=note>A <a href=#webvtt-alignment-cue-setting>WebVTT alignment cue setting</a>
+  configures the alignment of the text within the cue. The keywords
+  are relative to the text direction; for left-to-right English text,
+  "<code title="">start</code>" means left-aligned.</p>
+
+  <p><dfn id=webvtt-metadata-text>WebVTT metadata text</dfn> consists of any sequence of one
   or more characters other than U+000A LINE FEED (LF) characters and
   U+000D CARRIAGE RETURN (CR) characters, each optionally separated
   from the next by a <a href=#webvtt-line-terminator>WebVTT line terminator</a>. (In other

diff --git a/index b/index
@@ -31910,7 +31910,12 @@ interface <dfn id=texttrackcue>TextTrackCue</dfn> {
    <li>Optionally, one or more U+0020 SPACE characters or U+0009 CHARACTER TABULATION (tab) characters followed by <a href=#webvtt-cue-settings>WebVTT cue settings</a>.</li>
    <li>A <a href=#webvtt-line-terminator>WebVTT line terminator</a>.</li>
    <li>The <dfn id=cue-payload>cue payload</dfn>: either <a href=#webvtt-cue-text>WebVTT cue text</a> or <a href=#webvtt-metadata-text>WebVTT metadata text</a>.</li>
-  </ol><p><a href=#webvtt-cue-text>WebVTT cue text</a> is syntactically a subset of
+  </ol><p class=note>A <a href=#webvtt-cue>WebVTT cue</a> corresponds to one piece
+  of time-aligned text or data in the <a href=#webvtt-file>WebVTT file</a>, for
+  example one subtitle. The <a href=#cue-payload>cue payload</a> is the text or
+  data associated with the cue.</p>
+
+  <p><a href=#webvtt-cue-text>WebVTT cue text</a> is syntactically a subset of
   <a href=#webvtt-metadata-text>WebVTT metadata text</a>. Conformance checkers, when
   validating <a href=#webvtt>WebVTT</a> files, may offer to restrict all cues
   to only having <a href=#webvtt-cue-text>WebVTT cue text</a> as their <a href=#cue-payload>cue
@@ -31934,6 +31939,9 @@ interface <dfn id=texttrackcue>TextTrackCue</dfn> {
   SIGN), nor containing any U+000A LINE FEED (LF) characters or U+000D
   CARRIAGE RETURN (CR) characters.</p>
 
+  <p class=note>A <a href=#webvtt-cue-identifier>WebVTT cue identifier</a> can be used to
+  reference a specific cue, for example from script or CSS.</p>
+
   <p>The <dfn id=webvtt-cue-timings>WebVTT cue timings</dfn> part of a <a href=#webvtt-cue>WebVTT
   cue</a> consists of the following components, in the given
   order:</p>
@@ -31957,7 +31965,11 @@ interface <dfn id=texttrackcue>TextTrackCue</dfn> {
    timestamp</a> must be greater than the start time offset of the
    cue.</li>
 
-  </ol><p>A <dfn id=webvtt-timestamp>WebVTT timestamp</dfn> representing a time in seconds and
+  </ol><p class=note>The <a href=#webvtt-cue-timings>WebVTT cue timings</a> give the start
+  and end offsets of the <a href=#webvtt-cue>WebVTT cue</a>. Different cues can
+  overlap. Cues are always listed ordered by their start time.</p>
+
+  <p>A <dfn id=webvtt-timestamp>WebVTT timestamp</dfn> representing a time in seconds and
   fractions of a second is a <a href=#webvtt-timestamp>WebVTT timestamp</a>
   representing hours <var title="">hours</var>, minutes <var title="">minutes</var>, seconds
   <var title="">seconds</var>, and thousandths of a second <var title="">seconds-frac</var>, calculated as follows:</p>
@@ -32016,13 +32028,23 @@ interface <dfn id=texttrackcue>TextTrackCue</dfn> {
    <li>A <a href=#webvtt-text-position-cue-setting>WebVTT text position cue setting</a>.</li> <!-- T:100% -->
    <li>A <a href=#webvtt-size-cue-setting>WebVTT size cue setting</a>.</li>          <!-- S:100% -->
    <li>A <a href=#webvtt-alignment-cue-setting>WebVTT alignment cue setting</a>.</li>     <!-- A:start/middle/end -->
-  </ul><p>A <dfn id=webvtt-vertical-text-cue-setting>WebVTT vertical text cue setting</dfn> consists of the
+  </ul><p class=note><a href=#webvtt-cue-settings>WebVTT cue settings</a> give configuration
+  options regarding the position and alignment of the cue. For
+  example, it allows a cue to be aligned to the left or positioned at
+  the top right.</p>
+
+  <p>A <dfn id=webvtt-vertical-text-cue-setting>WebVTT vertical text cue setting</dfn> consists of the
   following components, in the order given:</p>
 
   <ol><li>A U+0044 LATIN CAPITAL LETTER D character.</li>
    <li>A U+003A COLON character (:).</li>
    <li>One of the following strings: "<code title="">vertical</code>", "<code title="">vertical-lr</code>".</li>
-  </ol><p>A <dfn id=webvtt-line-position-cue-setting>WebVTT line position cue setting</dfn> consists of the
+  </ol><p class=note>A <a href=#webvtt-vertical-text-cue-setting>WebVTT vertical text cue setting</a>
+  configures the cue to use vertical text layout rather than
+  horizontal text layout. Vertical text layout is sometimes used in
+  Japanese, for example. The default is horiontal layout.</p>
+
+  <p>A <dfn id=webvtt-line-position-cue-setting>WebVTT line position cue setting</dfn> consists of the
   following components, in the order given:</p>
 
   <ol><li><p>A U+004C LATIN CAPITAL LETTER L character.</li>
@@ -32039,27 +32061,55 @@ interface <dfn id=texttrackcue>TextTrackCue</dfn> {
        <li>One or more characters in the range U+0030 DIGIT ZERO (0) to U+0039 DIGIT NINE (9).</li>
       </ol></dd>
     </dl></li>
-  </ol><p>A <dfn id=webvtt-text-position-cue-setting>WebVTT text position cue setting</dfn> consists of the
+  </ol><p class=note>A <a href=#webvtt-line-position-cue-setting>WebVTT line position cue setting</a>
+  configures the position of the cue. For horizontal cues, this is the
+  vertical position. The position can be given either as a percentage,
+  which gives the distance from the top of the frame, or as a line
+  number. Line numbers are based on the size of the first line of the
+  cue. Positive line numbers count from the top of the frame (the top
+  line is numbered 0), negative line numbers from the bottom of the
+  frame (the bottom line is numbered &minus;1).</p>
+
+  <p>A <dfn id=webvtt-text-position-cue-setting>WebVTT text position cue setting</dfn> consists of the
   following components, in the order given:</p>
 
   <ol><li>A U+0054 LATIN CAPITAL LETTER T character.</li>
    <li>A U+003A COLON character (:).</li>
    <li>One or more characters in the range U+0030 DIGIT ZERO (0) to U+0039 DIGIT NINE (9).</li>
    <li>A U+0025 PERCENT SIGN character (%).</li>
-  </ol><p>A <dfn id=webvtt-size-cue-setting>WebVTT size cue setting</dfn> consists of the
+  </ol><p class=note>A <a href=#webvtt-text-position-cue-setting>WebVTT text position cue setting</a>
+  configures the position of the text in the direction orthogonal to
+  the <a href=#webvtt-line-position-cue-setting>WebVTT line position cue setting</a>. For horizontal
+  cues, this is the horizontal position. The <a href=#webvtt-text-position-cue-setting>WebVTT text
+  position cue setting</a> is given as a percentage, calculated
+  from the edge of the frame that the text begins (so for
+  left-to-right English text, the left edge).</p>
+
+  <p>A <dfn id=webvtt-size-cue-setting>WebVTT size cue setting</dfn> consists of the
   following components, in the order given:</p>
 
   <ol><li>A U+0053 LATIN CAPITAL LETTER S character.</li>
    <li>A U+003A COLON character (:).</li>
    <li>One or more characters in the range U+0030 DIGIT ZERO (0) to U+0039 DIGIT NINE (9).</li>
    <li>A U+0025 PERCENT SIGN character (%).</li>
-  </ol><p>A <dfn id=webvtt-alignment-cue-setting>WebVTT alignment cue setting</dfn> consists of the
+  </ol><p class=note>A <a href=#webvtt-size-cue-setting>WebVTT size cue setting</a> configures
+  the size of the cue in the same direction as the <a href=#webvtt-text-position-cue-setting>WebVTT text
+  position cue setting</a>. For horizontal cues, this is the width
+  of the cue. It is given as a percentage of the width of the
+  frame.</p>
+
+  <p>A <dfn id=webvtt-alignment-cue-setting>WebVTT alignment cue setting</dfn> consists of the
   following components, in the order given:</p>
 
   <ol><li>A U+0041 LATIN CAPITAL LETTER A character.</li>
    <li>A U+003A COLON character (:).</li>
    <li>One of the following strings: "<code title="">start</code>", "<code title="">middle</code>", "<code title="">end</code>"</li>
-  </ol><p><dfn id=webvtt-metadata-text>WebVTT metadata text</dfn> consists of any sequence of one
+  </ol><p class=note>A <a href=#webvtt-alignment-cue-setting>WebVTT alignment cue setting</a>
+  configures the alignment of the text within the cue. The keywords
+  are relative to the text direction; for left-to-right English text,
+  "<code title="">start</code>" means left-aligned.</p>
+
+  <p><dfn id=webvtt-metadata-text>WebVTT metadata text</dfn> consists of any sequence of one
   or more characters other than U+000A LINE FEED (LF) characters and
   U+000D CARRIAGE RETURN (CR) characters, each optionally separated
   from the next by a <a href=#webvtt-line-terminator>WebVTT line terminator</a>. (In other