nitpicking as usual, less anal parsing, and hueg list of mandatory defaults

Originally committed to SVN as r1422.
This commit is contained in:
Karl Blomster 2007-07-13 20:54:33 +00:00
parent 02e15b0ac5
commit 3744cb505f

View file

@ -124,7 +124,7 @@ such ignored lines in the file after re-saving it. Note that the space after the
There are two sections which are required, \emph{[AS5]} and \emph{[Events]}, the former being There are two sections which are required, \emph{[AS5]} and \emph{[Events]}, the former being
the equivalent of \emph{[Script Info]} in previous formats. If either of those sections is the equivalent of \emph{[Script Info]} in previous formats. If either of those sections is
missing, the file is invalid and \must\ be refused by the parser. Any other section missing, the file is invalid and \must\ be rejected by the parser. Any other section
can be ommitted from the file, and need not be implemented by all parsers. can be ommitted from the file, and need not be implemented by all parsers.
Finally, there is a special type of undefined group, \emph{[Private:PROGNAME]}, which Finally, there is a special type of undefined group, \emph{[Private:PROGNAME]}, which
@ -140,15 +140,19 @@ when resaving. It is suggested that an editing program \should\ check whether co
actually valid AS5 lines, and if they are, display them to the user in some way as "disabled" lines. actually valid AS5 lines, and if they are, display them to the user in some way as "disabled" lines.
Note that commented out lines \mustnot\ influence subtitle rendering in any way. Note that commented out lines \mustnot\ influence subtitle rendering in any way.
Note that \emph{Format:} lines from the previous formats are not admitted in AS5. If the parser
finds any of them, or any other unrecognized lines not specified here (outside the \emph{[Private:]}
section, where any text data can be stored), including but not limited to unknown sections, it
\must\ halt parsing, rejecting the file as invalid, and it \should\ emit a warning specifying
where the problem lies.
The sections \may\ be written in any order, with the exception of the \emph{[AS5]} section which The sections \may\ be written in any order, with the exception of the \emph{[AS5]} section which
\must\ always be the first section. \must\ always be the first section.
In general, malformed lines in AS5 (such as unrecognized lines, lines with missing fields, fields
with invalid data for its type (for example, malformed timestamps) or unrecognized section headers)
are not considered fatal syntax errors. If nothing else is explicitly specified, the renderer \must\
ignore such lines completely, and the parser \should\ emit a warning describing the syntax error. The
spirit of this rule to be forgiving; something that doesn't make the entire file unuseable or dangerously
ambigous should not be a fatal syntax error. It is usually better to render the valid parts of the file
correctly and tell the user about the problematic lines by the way of warning messages. Under certain
circumstances it may be desirable to suppress warning messages; a well-behaved parser \should\ include
an option to do so, but in general it is probably more useful to let the user know about the problem
instead of just silently failing to render the line.
\subsubsection{[AS5]} \subsubsection{[AS5]}
This \must\ be the first section in every AS5 file. If the very first line of the file is not This \must\ be the first section in every AS5 file. If the very first line of the file is not
@ -169,11 +173,13 @@ It is possible, therefore, to determine the encoding of the file by checking its
This section is used to declare several script properties that affect its parsing and rendering. This section is used to declare several script properties that affect its parsing and rendering.
All properties are stored in the format \textit{Name: data}, with one property per line. All properties are stored in the format \textit{Name: data}, with one property per line.
This section \must\ always declare the following properties (a file that is missing one of them is not valid): This section \must\ always declare the following properties (a file that is missing one of them is not valid):
\begin{itemize} \begin{itemize}
\item ScriptType: Should always be set to \textit{AS5}, for this particular version of the specification. \item ScriptType: Should always be set to \textit{AS5}, for this particular version of the specification.
If this contains a value that the parser does not understand, it \must\ abort parsing. An unrecognized ScriptType value is considered a fatal syntax error, and \must\ cause the parser to
reject the entire file as invalid.
\item Resolution: Should contain the script resolution in \textit{WxH} format. For example, for a 640x480 \item Resolution: Should contain the script resolution in \textit{WxH} format. For example, for a 640x480
script, this should say \textit{``Resolution: 640x480''}. Note that this does not need to correspond to the script, this should say \textit{``Resolution: 640x480''}. Note that this does not need to correspond to the
video resolution, however, subtitles \must\ be rendered on such a coordinate space. That is, in a video resolution, however, subtitles \must\ be rendered on such a coordinate space. That is, in a
@ -181,6 +187,8 @@ video resolution, however, subtitles \must\ be rendered on such a coordinate spa
resolution of the video it's being drawn on. Also, in a 100x100 script, a radius 50 circle centered on resolution of the video it's being drawn on. Also, in a 100x100 script, a radius 50 circle centered on
the center will always take half of the height and half of the width of the video, even if that means the center will always take half of the height and half of the width of the video, even if that means
being distorted if drawn on a video with a non-1:1 aspect ratio (for example, a 640x480 video). being distorted if drawn on a video with a non-1:1 aspect ratio (for example, a 640x480 video).
An unrecognized or malformed Resolution value is considered a fatal syntax error, and \must\ cause the parser
to reject the entire file as invalid.
\end{itemize} \end{itemize}
The following items \may\ also be used; they are not required, but are recommended. They all have default values: The following items \may\ also be used; they are not required, but are recommended. They all have default values:
@ -190,10 +198,12 @@ The following items \may\ also be used; they are not required, but are recommend
Default value is empty. This should be ignored by the renderer, but might be useful for inter-editing-program Default value is empty. This should be ignored by the renderer, but might be useful for inter-editing-program
interaction. interaction.
\item Wrapping: The line wrapping style. This can be ``Manual'', in which case only \textbackslash{n} can \item Wrapping: The line wrapping style. This can be ``Manual'', in which case only \textbackslash{n} can
break lines or ``Automatic'', in which the renderer chooses how to break them. The default is ``Automatic''. break lines or ``Automatic'', in which the renderer chooses how to break them. If this is not set, or if the
value set is not recognized, the renderer \must\ default to ``Automatic''.
Even if it is set to Automatic, \textbackslash{n} will still insert a forced line break. Even if it is set to Automatic, \textbackslash{n} will still insert a forced line break.
On the other hand, if set to manual, the line can NEVER be broken at anywhere other than forced line breaks, On the other hand, if set to manual, the line can NEVER be broken at anywhere other than forced line breaks,
even if it means that the line will become unreadable because it goes outside the display area. even if it means that the line will become unreadable because it goes outside the display area.
This property is not case sensitive.
\item Extensions: A comma-separated list of all extensions being used in this file. At the moment, there are \item Extensions: A comma-separated list of all extensions being used in this file. At the moment, there are
no extensions available. Renderers should read this to enable any extensions that they might support. no extensions available. Renderers should read this to enable any extensions that they might support.
Editing programs \must\ keep this field intact, unless the user chooses otherwise. Scripts WILL break Editing programs \must\ keep this field intact, unless the user chooses otherwise. Scripts WILL break
@ -204,11 +214,11 @@ if the list of extensions is suddenly lost.
Subtitling programs \should\ be able to display this title to the user. Subtitling programs \should\ be able to display this title to the user.
\end{itemize} \end{itemize}
Unlike in the previous incarnations of the format, storing private properties here is not allowed, which means Unlike in the previous incarnations of the format, storing private properties here is strongly discouraged,
that this section \mustnot\ contain any properties not listed here. It \may\, just like any other section, contain which means that this section \shouldnot\ contain any properties not listed here. It \may\, just like any other
commented-out lines prefixed with a semicolon (;) which of course may contain anything, but it is strongly recommended section, contain commented-out lines prefixed with a semicolon (;) which of course may contain anything, but it
that any application-specific or otherwise private data \should\ be stored in the \textit{[Private:PROGNAME]} is strongly recommended that any application-specific or otherwise private data \should\ be stored in the
section instead, as mentioned above. \textit{[Private:PROGNAME]} section instead, as mentioned above, or if it is line-specific data, in the User field.
\subsubsection{[Events]} \subsubsection{[Events]}
@ -230,14 +240,14 @@ time is \emph{inclusive}.
\item End: The end time of the line. It follows the same format as the start time. The line is only \item End: The end time of the line. It follows the same format as the start time. The line is only
displayed if the timestamp of the current frame is \emph{lesser than} the end time. That is, end time is displayed if the timestamp of the current frame is \emph{lesser than} the end time. That is, end time is
\emph{exclusive}. In particular, it means that a line whose start time is equal to its end time will \emph{exclusive}. In particular, it means that a line whose start time is equal to its end time will
never be displayed. If the end time is earlier than the start time, the renderer \may\ issue a warning, never be displayed. If the end time is earlier than the start time, the renderer \should\ issue a warning,
but it \should\ render the remaining lines regardless of the issue. but this is not considered a fatal syntax error and it \should\ render the remaining lines regardless of the issue.
\item Style: The name of the default style used for this line. See the [Style] section below. If left blank, \item Style: The name of the default style used for this line. See the [Style] section below. If left blank,
the script's global default style \must\ be used. If an unknown style name is specified, the renderer \must\ the script's global default style \must\ be used. If there is no default style defined, or if an unknown
fallback to default, and \may\ issue a warning. style name is specified, the renderer \must\ fallback to its own defaults (see below), and \should\ issue a warning.
\item User: This field is used by the program to store program-specific data in each line. Renderers \item User: This field is used by the program to store program-specific data in each line. Renderers
\should\ ignore this (but \may\ use it for application-specific extension features). This field \should\ \should\ ignore this (but \may\ use it for application-specific extension features). This field \should\
be left blank if it's not used. Note that whatever data is stored here \mustnot\ contain any commas! be left empty if it's not used. Note that whatever data is stored here \mustnot\ contain any commas!
\item Content: The actual text of the line. This contains actual text and override tags. See the section \item Content: The actual text of the line. This contains actual text and override tags. See the section
on override tags for more information. on override tags for more information.
\end{itemize} \end{itemize}
@ -248,7 +258,7 @@ representing minutes, and a floating point number representing seconds. Leading
Localization is irrelevant: a period (``.'') is always used to separate the decimal point. This way, Localization is irrelevant: a period (``.'') is always used to separate the decimal point. This way,
0:21:42.5 and 0000:21:42.5000 are equivalent, and both represent 0 hours, 21 minutes, 42 seconds and 500 miliseconds. 0:21:42.5 and 0000:21:42.5000 are equivalent, and both represent 0 hours, 21 minutes, 42 seconds and 500 miliseconds.
Spaces between each field \must\ be ignored by all parsers. Any spaces at the beginning of the Spaces between each field \must\ be ignored by the parser. Any spaces at the beginning of the
content line \should\ be stripped by any editing program. A hard space (see the overrides section) or empty content line \should\ be stripped by any editing program. A hard space (see the overrides section) or empty
override block should be used if space at the start of a line is truly desirable. That is, the two override block should be used if space at the start of a line is truly desirable. That is, the two
following lines are syntactically identical: following lines are syntactically identical:
@ -330,10 +340,56 @@ this way of declaring styles is identical to the one above, but is more verbose.
\todo{This is bad, we need to fix it with specified defaults to get consistent rendering} \todo{This is bad, we need to fix it with specified defaults to get consistent rendering}
If no Default style is defined, the renderer \must\ choose its own defaults to render the text with. If no Default style is defined, the renderer \must\ choose its own defaults to render the text with.
The defaults \must\ also be used any for any properties not specified in a given style (in other words, The defaults \must\ also be used any for any properties not specified in a given style (in other words,
styles with no parent inherit from the renderer defaults). These defaults are entirely arbitrary and styles with no parent inherit from the renderer defaults). To ensure consistent rendering while still
can be set to anything, but the renderer \should\ allow the user change them. A simple Sans-Serif font avoiding having to explicitly define every single property, some of these defaults are mandatory and
with white text and black borders is recommended if the user does not specify anything else. specified below; some others have recommended values, also specified below, but a well-featured renderer
\may\ allow the user to change these defaults at will.
The following default overrides are mandatory and \must\ be set as following:
\begin{itemize}
\item \textbackslash i(0)
\item \textbackslash b(0)
\item \textbackslash u(0)
\item \textbackslash s(0)
\item \textbackslash fe(Unicode)
\item \textbackslash bordstyle(0)
\item \textbackslash fscx(100)
\item \textbackslash fscy(100)
\item \textbackslash fsp() - undefined (font default)
\item \textbackslash fsvp() - undefined (font default)
\item \textbackslash 1a(#00)
\item \textbackslash 2a(#00)
\item \textbackslash 3a(#00)
\item \textbackslash 4a(#80)
\item \textbackslash left(12)
\item \textbackslash right(12)
\item \textbackslash top(12)
\item \textbackslash bottom(12)
\item \textbackslash ax(50)
\item \textbackslash ay(100)
\item \textbackslash nx(50)
\item \textbackslash ny(100)
\item \textbackslash rel(0)
\item \textbackslash vertical(0)
\item \textbackslash q(1)
\item \textbackslash pos() - undefined (defined by alignment and margins)
\item \textbackslash org() - undefined (defined by alignment and margins)
\item \textbackslash bls(0)
\item \textbackslash frx(0)
\item \textbackslash fry(0)
\item \textbackslash frz(0)
\item \textbackslash fax(0)
\item \textbackslash fay(0)
\item \textbackslash fad(0,0)
\item \textbackslash distort() - undefined (none)
\item \textbackslash baseline() - undefined (none)
\item \textbackslash blpos(0)
\item \textbackslash vc() - undefined (none)
\item \textbackslash blend(normal)
\item \textbackslash clip() - undefined (none)
\item \textbackslash iclip() - undefined (none)
\item \textbackslash \$blur(0)
\end{itemize}
\subsubsection{[Resources]} \subsubsection{[Resources]}
@ -699,8 +755,8 @@ Script resolution relative to video area (0) or not (1)
\subsubsection{\textbackslash vertical} \subsubsection{\textbackslash vertical}
\textbf{Usage:} \textbf{Usage:}
\begin{verbatim} \begin{verbatim}
\vertical(1)
\vertical(0) \vertical(0)
\vertical(1)
\end{verbatim} \end{verbatim}
\textbf{Description:} \textbf{Description:}