From d45fb680587d2a86f5c04d44660b384820f7da6b Mon Sep 17 00:00:00 2001
From: Niels Martin Hansen <nielsm@aegisub.org>
Date: Wed, 22 Mar 2006 21:57:03 +0000
Subject: [PATCH] Originally committed to SVN as r239.

---
 .../v4-docs/basic-function-interface.txt      |   2 +-
 automation/v4-docs/subtitle-data.txt          | 237 ++++++++++++++++++
 2 files changed, 238 insertions(+), 1 deletion(-)
 create mode 100644 automation/v4-docs/subtitle-data.txt

diff --git a/automation/v4-docs/basic-function-interface.txt b/automation/v4-docs/basic-function-interface.txt
index 56bf9ad9b..6690e09c3 100644
--- a/automation/v4-docs/basic-function-interface.txt
+++ b/automation/v4-docs/basic-function-interface.txt
@@ -26,7 +26,7 @@ function aegisub.register_macro(
   on the status bar when hovering over the menu item.
 
 @menu (string)
-  The menu this macro will appear in. Can be one of:
+  The menu this macro will appear in. Must be one of:
    o "edit"
    o "video"
    o "audio"
diff --git a/automation/v4-docs/subtitle-data.txt b/automation/v4-docs/subtitle-data.txt
new file mode 100644
index 000000000..79b4266ff
--- /dev/null
+++ b/automation/v4-docs/subtitle-data.txt
@@ -0,0 +1,237 @@
+Automation 4 Subtitle Data format and functions API
+
+This file describes the API for retrieving and manipulating subtitle data in
+Automation 4, as well as the data structures generated and accepted by these
+APIs.
+
+---
+
+Subtitle Line table
+
+A Subtitle Line table contains various information about a line in the
+subtitle file being processed. There are several classes of subtitle lines,
+which all have a few fields in common, but otherwise have different fields.
+
+
+Common keys for all Subtitle Line classes:
+
+class (string)
+  The class of the Subtitle Line. Must be one of:
+    "clear", (empty line)
+    "comment", (semicolon-style comment line)
+    "head", (section heading)
+    "info", (key/value pair in Script Info section)
+    "format", (line format definition)
+    "style", (style definition line)
+    "stylex", (style extension line, tentative AS5 feature)
+    "dialogue", (dialogue line or dialogue-style comment line)
+    "unknown" (unknown kind of line)
+  Lines of the "unknown" class should never appear in well-formed subtitle
+  scripts. They will usually be a result of a line being outside the section
+  it belongs in.
+
+raw (string)
+  The raw text of the line.
+  You should not change this field directly, since the data in it will never
+  be used for generating lines in internal representation. It will, however,
+  be updated from the remaining data in the line whenever it is required for
+  one thing or another by an internal function.
+
+section (string)
+  The section this line is placed in. If it is placed before the first section
+  heading, this field is nil.
+
+
+Key defined only for the "comment" class:
+
+text (string)
+  The text of the comment line, ie. everything after the initial semicolon,
+  including any spaces.
+
+
+Key defined only for the "head" class:
+
+No special keys are defined for this class, but the "section" field will be
+the name of the new section started.
+
+
+Keys defined only for the "info" class:
+
+key (string)
+  The "key" part of the line, ie. everything before the first colon.
+
+value (string)
+  The "value" part of the line, ie. everything after the first colon,
+  discarding any leading whitespace.
+
+
+Keys defined only for the "format" class:
+
+fields (table)
+  An Array Table of strings, each being the name of a field on the line.
+
+
+Keys defined only for the "style" class:
+
+name (string)
+  Name of the style.
+
+fontname (string)
+  Name of the font used.
+
+fontsize (string)
+  Size of the font used, in pixels.
+
+color1 (string)
+color2 (string)
+color3 (string)
+color4 (string)
+  The four colors for the style. (Fill, pre-karaoke fill, border, shadow)
+  In VB hexadecimal, ie. "&HAABBGGRR&"
+
+bold (boolean/number)
+  The boldness/weight of the font. This will usually be a boolean, but it
+  can be a number, in which case it must be one of 0, 100, 200, ..., 900.
+
+italic (boolean)
+underline (boolean)
+strikeout (boolean)
+  Other properties of the font.
+
+scale_x (number)
+scale_y (number)
+  Scaling of the text, in percent.
+
+spacing (number)
+  Additional spacing between letters. Always integer.
+
+angle (number)
+  Rotation of the text on the Z axis in degrees.
+
+borderstyle (number)
+  1 = outline and drop shadow; 3 = opaque box.
+
+outline (number)
+  Width of the outline.
+
+shadow (number)
+  Distance between shadow and text.
+
+align (number)
+  Numpad alignment of the text.
+
+margin_l (number)
+margin_r (number)
+margin_t (number)
+margin_b (number)
+  Left/right/top/bottom margins of the text in pixels.
+  If using a format without support for separate top and bottom margins, the
+  margin_t value will be used for vertical margin when converting back to
+  textual representation.
+
+encoding (number)
+  Font encoding used for text. This follows the MS Windows font encoding
+  constants.
+
+relative_to (number)
+  ???
+
+vertical (boolean)
+  Whether vertical text semantics is used or not.
+
+
+Keys defined only for the "stylex" class:
+
+Remember that this class is only for the tentative AS5 format.
+
+name (string)
+  Name of the new style defined.
+
+basename (string)
+  Name of the style the new style is based on.
+
+overrides (string)
+  String of override tags defining the new style.
+
+
+Keys only defined for the "dialogue" class:
+
+comment (boolean)
+  True if the line is a comment line, otherwise false.
+
+layer (number)
+  The layer the line is rendered in.
+
+start_time (number)
+end_time (number)
+  Start/end time of the line in miliseconds.
+
+style (string)
+  Name of the style assigned to this line.
+
+actor (string)
+  Name of the actor performing this line.
+
+margin_l (number)
+margin_r (number)
+margin_t (number)
+margin_b (number)
+  Left/right/top/bottom margins of the text in pixels.
+  If any of these are zero, it's considered "not overriding".
+  Same comment as for style lines applies.
+
+effect (string)
+  Effect to apply to the line.
+
+userdata (string)
+  Authoring-application defined data. (Tentative AS5 field.)
+
+text (string)
+  The text for this line.
+
+---
+
+Subtitle File user data object
+
+The Subtitle File object is a user data object with some of the metatable
+methods overridden to provide table-like access to the subtitle lines, as
+well as some functions to modify the subtitles.
+
+The following operations are supported:
+
+n = subs[0]
+n = subs.length
+  Retrieve the number of lines in total.
+
+line = subs[i]
+  Retrieve line i, assuming 1 <= i <= n.
+
+subs[i] = line
+  Replace line i with new data.
+
+subs[i] = nil
+subs.delete(i[, i2, ...])
+  Delete line i, pushing all following lines up an index. (Ie. by repeatedly
+  deleting line 1 this way, the file will eventually end up empty.)
+  The function syntax for this function can also take multiple line indexes,
+  in which case it deletes each of those lines. All indexes are relative to
+  the line numbering before the function is called.
+
+subs.deleterange(a, b)
+  Deletes all lines from index a to index b, both inclusive. If b < a,
+  nothing is done.
+
+subs[0] = line
+subs.append(line)
+  Append a line to the file.
+
+subs[-i] = line
+subs.insert(i, line[, line2, ...])
+  Insert a line before index i.
+  The function syntax can also insert multiple lines.
+
+(Note that the function-syntax ways of doing these operations is slower than
+the array-syntax way of doing them.)
+
+---
+