Added a bunch of clarifications for AS5 and some moro todo items. RFC.

Originally committed to SVN as r1437.

specs/as5/as5.tex

@@ -242,12 +242,20 @@ displayed if the timestamp of the current frame is \emph{lesser than} the end ti
 \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 \should\ issue a warning,
 but this is not considered a fatal syntax error and it \should\ render the remaining lines regardless of the issue.
+If the end time is earlier than the start time, it should for rendering purposes be considered to be equal to
+the start time, and editing programs \may\ automatically reset the end time to be equal to the start time.
 \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 there is no default style defined, or if an unknown
 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
 \should\ ignore this (but \may\ use it for application-specific extension features). This field \should\
 be left empty if it's not used. Note that whatever data is stored here \mustnot\ contain any commas!
+
+It is suggested that text in the User field is encoded with the following scheme: The characters
+0x00 to 0x1F (control codes), 0x23 (number sign), 0x2C (comma), 0x3A (colon) and 0x7C (pipe)
+are replaced with a number sign (0x23) followed by the hexadecimal code for the character, for example
+a comma is replaced with ``\#2C''. This scheme allows the field to contain several sub-fields separated
+with pipe characters, optionally using a ``Name:Value'' format.
 \item Content: The actual text of the line. This contains actual text and override tags. See the section
 on override tags for more information.
 \end{itemize}
@@ -319,7 +327,7 @@ Style: UglinessItself,Default,\fn(Comic Sans MS)
 In the above fragment, the first style defines the Default style that will be used on all lines that
 don't set any style and the second style defines a base speech style that will be used for all actors
 (note that it doesn't inherit from Default, even though Default overrode the renderer's default, that
-one is still used for style definitions).
+one is still used for style definitions.)
 
 The third and fourth styles are based on the second, and simply assign different colours to it. They
 will both have all properties of Speech, and only differ in primary colour. Finally, the last example
@@ -372,8 +380,8 @@ The following default overrides are mandatory and \must\ be set as following:
 \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 pos() - undefined (defined by alignment, margins and script resolution)
+\item \textbackslash org() - undefined (defined by alignment, margins and script resolution)
 \item \textbackslash bls(0)
 \item \textbackslash frx(0)
 \item \textbackslash fry(0)
@@ -520,7 +528,9 @@ Line 1\nLine 2
 \end{verbatim}
 
 \textbf{Description:}
-Inserts a line break
+Inserts a forced line break.
+
+\todo{Should the presence of a forced line break in a line disable automatic line breaking for that line?}
 
 \subsubsection{\textbackslash h}
 \textbf{Usage:}
@@ -529,7 +539,9 @@ Word1\hWord2
 \end{verbatim}
 
 \textbf{Description:}
-Inserts a "hard" space
+Inserts a ``hard'' space. This is equivalent to Unicode character U+00A0 No-Break Space, but script authors
+are recommended to use \textbackslash h over U+00A0 since U+00A0 can visually easily be mistaken for a regular
+space character.
 
 \subsubsection{\textbackslash \{, \textbackslash \}}
 \textbf{Usage:}
@@ -538,7 +550,7 @@ Text \textbackslash \{inside curly braces\textbackslash \}
 \end{verbatim}
 
 \textbf{Description:}
-\{ and \} respectively
+Insert respectively literal \{ and \} into the rendered output.
 
 \subsubsection{\textbackslash \textbackslash}
 \textbf{Usage:}
@@ -547,7 +559,7 @@ A \textbackslash \textbackslash\ (backslash)
 \end{verbatim}
 
 \textbf{Description:}
-\textbackslash of course
+Insert a literal \textbackslash\ into the rendered output.
 
 
 \subsection{Basic Typography Tags}
@@ -560,7 +572,10 @@ A \textbackslash \textbackslash\ (backslash)
 \end{verbatim}
 
 \textbf{Description:}
-Italics
+Enable (parameter 1) or disable (parameter 0) italics font style. If the selected font face does not
+have a native italics variation, a simulated italics style \must\ be used. If the selected font face
+does not have a non-italics variation, the italics vatiation \must\ be used even when \textbackslash i(0)
+is specified.
 
 \subsubsection{\textbackslash b}
 \textbf{Usage:}
@@ -570,7 +585,15 @@ Italics
 \end{verbatim}
 
 \textbf{Description:}
-Bold
+Enable (parameter 1) or disable (parameter 0) boldface font style. If the selected font face does not
+have a native boldface variation, a simulated boldface \must\ be used. If the selected font face
+does not have a non-boldface variation, the boldface variation \must\ be used even when \textbackslash b(1)
+is specified.
+
+AS5 does not support specifying a specific font weight with \textbackslash b and any other parameter
+than 0 or 1 (zero or one) is an error. To specify a specific weight version of a font that has more
+than two weight variations, the textual name of the weight variation must be specified with the
+\textbackslash fn override.
 
 \subsubsection{\textbackslash u}
 \textbf{Usage:}
@@ -580,7 +603,8 @@ Bold
 \end{verbatim}
 
 \textbf{Description:}
-Underline
+Add an underline decoration to the text (parameter 1) or not (parameter 0.) The underline is a straight
+line parallel to the text baseline, placed slightly below the baseline.
 
 \subsubsection{\textbackslash s}
 \textbf{Usage:}
@@ -590,7 +614,8 @@ Underline
 \end{verbatim}
 
 \textbf{Description:}
-Strikeout
+Add a strikeout decoration to the text (parameter 1) or not (parameter 0.) The strikeout is a straight
+line parallel to the text baseline, which strikes through the letters.
 
 \subsubsection{\textbackslash fn}
 \textbf{Usage:}
@@ -601,6 +626,8 @@ Strikeout
 \textbf{Description:}
 List of preferred fonts in descending order of preference
 
+\todo{What about fonts that have commas or parentheses in their names?}
+
 \subsubsection{\textbackslash fe}
 \textbf{Usage:}
 \begin{verbatim}
@@ -610,6 +637,9 @@ List of preferred fonts in descending order of preference
 \textbf{Description:}
 Set font encoding in some ISO code
 
+\todo{What does this affect? Apart from possibly selecting national variations of some characters
+and possibly fixing things in Windows.}
+
 \subsubsection{\textbackslash fs}
 \textbf{Usage:}
 \begin{verbatim}
@@ -617,7 +647,16 @@ Set font encoding in some ISO code
 \end{verbatim}
 
 \textbf{Description:}
-Set font size in points
+Set font height in pixels. The font nominal character width is also set by \textbackslash fs to the default
+of the font face.
+
+The parameter can also be interpreted as a typographic point value, when
+the script resolution is assumed to be 72 dpi and the size of a typographic point is defined as
+$1/72$ inch.
+
+\todo{Can this be defined more clearly?}
+
+A negative font size must be considered an error and \must\ be ignored.
 
 \subsubsection{\textbackslash bord}
 \textbf{Usage:}
@@ -626,7 +665,21 @@ Set font size in points
 \end{verbatim}
 
 \textbf{Description:}
-Set border size in script resolution pixels
+Set the width of the text outline. The outline width \mustnot\ be negative.
+
+The text outline can be defined by a morphological dilation operation using the rasterised text
+and a circular element with the radius specified by the \textbackslash bord tag. The outline is the
+original rasterised text subtracted from the result of the dilation operation. Ie.:
+\[O = (T \oplus E_{bord}) - T\]
+Where $O$ is the image of the outline, $T$ is the image of the text,$E_{bord}$ is the image of the
+circular element with radius $bord$ and $\oplus$ is the morphological dilation operation.
+
+The border can also be calculated from the vector outlines of the text.
+
+\todo{Define border by vector operations?}
+
+\todo{Is the outline calculated before or after applying other transformations? Ie. does X/Y axis
+rotations affect it?}
 
 \subsubsection{\textbackslash shad}
 \textbf{Usage:}
@@ -635,7 +688,19 @@ Set border size in script resolution pixels
 \end{verbatim}
 
 \textbf{Description:}
-Set shadow depth in script resolution pixels
+Set shadow depth in script resolution pixels. The shadow depth \mustnot\ be negative.
+
+\todo{Or define what a negative shadow depth should mean instead?}
+
+The shadow can be defined as a shadow image offset from the text and outline images. The shadow image
+\must\ be rendered visually ``further away'' than the text and outline images, ie. ``behind'' them.
+
+The shadow image is the sum of the text and outline images, rendered entirely in the fourth color.
+
+The shadow image offset from the text and outline images is $shadowsize$ script resolution pixels in
+both X and Y direction.
+
+After offsetting the shadow image, the text and outline images are subtracted from it at its new position.
 
 \subsubsection{\textbackslash bordstyle}
 \textbf{Usage:}
@@ -645,7 +710,12 @@ Set shadow depth in script resolution pixels
 \end{verbatim}
 
 \textbf{Description:}
-Set border style; 0 means normal, 1 means solid bounding box
+Set border style; 0 means normal, 1 means solid bounding box.
+
+When border style is 1 the outline image defined by the \textbackslash bord override \mustnot\ be used
+and instead an opaque box of the border color must be drawn behind the text.
+
+\todo{Define that box further}
 
 \subsection{Font Scaling Tags}
 
@@ -658,7 +728,9 @@ Set border style; 0 means normal, 1 means solid bounding box
 \end{verbatim}
 
 \textbf{Description:}
-Set font X/Y scaling in percent
+Set font X/Y scaling in percent.
+
+\todo{Implementation for this should probably go in a section that deals with transformation pipeline.}
 
 \subsubsection{\textbackslash fsp}
 \textbf{Usage:}
@@ -667,7 +739,13 @@ Set font X/Y scaling in percent
 \end{verbatim}
 
 \textbf{Description:}
-Set font spacing between characters in pixels
+Set additional spacing between characters in pixels. When the spacing is non-zero, an additional
+number of script pixels equal to the parameter given to \textbackslash fsp are skipped after rendering
+each glyph in the text. When the spacing is non-zero, any ligatures defined by the font face
+\mustnot\ be used.
+
+\todo{Does non-zero spacing have further implications? How about complex scripts?}
+\todo{What about negative spacing?}
 
 \subsubsection{\textbackslash fsvp}
 \textbf{Usage:}
@@ -676,7 +754,10 @@ Set font spacing between characters in pixels
 \end{verbatim}
 
 \textbf{Description:}
-Set font spacing between vertical baselines in pixels
+Set font spacing between vertical baselines in pixels. This is an additional number of script pixels
+to skip after each rendered line of text.
+
+\todo{Any further implications on text rendering? What about negative values?}
 
 \subsection{Colouring Tags}
 
@@ -687,7 +768,7 @@ Set font spacing between vertical baselines in pixels
 \end{verbatim}
 
 \textbf{Description:}
-Set font colouring in hexadecimal RGB
+Set font colouring in hexadecimal RGB.
 
 \subsubsection{\textbackslash \$a}
 \textbf{Usage:}
@@ -696,7 +777,7 @@ Set font colouring in hexadecimal RGB
 \end{verbatim}
 
 \textbf{Description:}
-Set font alpha channel (transparency) in hexadecimal RGB
+Set font alpha channel (transparency) in hexadecimal RGB.
 
 \subsection{Positioning and Rotation Tags}
 
@@ -742,6 +823,9 @@ See the alignment tags for more information regarding screen alignment.
 \textbf{Description:}
 Set alignment in various ways
 
+\todo{How about an alignment mode where the position set controls the text baseline position instead
+of an edge of the text bounding box?}
+
 \subsubsection{\textbackslash rel}
 \textbf{Usage:}
 \begin{verbatim}
@@ -752,6 +836,8 @@ Set alignment in various ways
 \textbf{Description:}
 Script resolution relative to video area (0) or not (1)
 
+\todo{Is this really a good tag name?}
+
 \subsubsection{\textbackslash vertical}
 \textbf{Usage:}
 \begin{verbatim}
@@ -760,7 +846,10 @@ Script resolution relative to video area (0) or not (1)
 \end{verbatim}
 
 \textbf{Description:}
-Makes text vertical
+Makes text vertical. This in particular affects the use of some glyph variations in CJK scripts.
+
+\todo{Does vertical imply that the baseline is vertical, ie.
+\verb/{\vertical1\fscx0}this is vertical text/ is indeed shown top-down?}
 
 \subsubsection{\textbackslash q}
 \textbf{Usage:}
@@ -779,7 +868,9 @@ Set wrap style to manual (0) or automatic (1)
 \end{verbatim}
 
 \textbf{Description:}
-Set line position to x,y in script coordinates
+Set line position to x,y in script coordinates.
+
+Can be animated with \textbackslash t.
 
 \subsubsection{\textbackslash org}
 \textbf{Usage:}
@@ -788,7 +879,9 @@ Set line position to x,y in script coordinates
 \end{verbatim}
 
 \textbf{Description:}
-Set origin to x,y in script coordinates
+Set origin to x,y in script coordinates.
+
+Can be animated with \textbackslash t.
 
 \subsubsection{\textbackslash bls}
 \textbf{Usage:}
@@ -813,7 +906,9 @@ its parameter.
 \end{verbatim}
 
 \textbf{Description:}
-Set font rotation around x/y/z axis in degrees
+Set font rotation around x/y/z axis in degrees.
+
+\todo{Define the axes}
 
 \subsubsection{\textbackslash fax, \textbackslash fay}
 \textbf{Usage:}
@@ -823,7 +918,8 @@ Set font rotation around x/y/z axis in degrees
 \end{verbatim}
 
 \textbf{Description:}
-Set shearing in x and y axis, 0..1 (I think?)
+Set shearing in x and y axis. 0 means no shearing takes place. Negative values allowed.
+The parameters are multipliers in a shearing matrix.
 
 \subsection{Animation Tags}
 
@@ -965,7 +1061,9 @@ colour, blurring, etc.
 \end{verbatim}
 
 \textbf{Description:}
-Sets the primary colour to blend with each of the four vertices of draw polygon. The primary use for this is to make smooth gradients easily, which are often required for proper blending with the background. Note that you can also set alpha using this tag.
+Sets the primary colour to blend with each of the four vertices of draw polygon.
+The primary use for this is to make smooth gradients easily, which are often required
+for proper blending with the background. Note that you can also set alpha using this tag.
 
 \subsubsection{\textbackslash \$blend}
 \textbf{Usage:}
@@ -1002,11 +1100,13 @@ by x1,y1,x2,y2 will be drawn.
 \end{verbatim}
 
 \textbf{Description:}
-Blurs stuff
+Blurs stuff. Animatable.
+
+\todo{Gaussian kernel or a number of applications of box blur?}
 
 \subsection{Advanced Typography Tags}
 These are more advanced tags, which might prove to be fairly complex to implement. They include
-things such as ruby text support (also known as furigana, when used with Japanese Kanji).
+things such as ruby text support (also known as furigana, when used with Japanese Kanji.)
 
 \todo{Write me}