More auto4 docs work.

Originally committed to SVN as r249.

automation/v4-docs/misc.txt

@@ -0,0 +1,32 @@
+Miscellaneous functions in Automation 4
+
+This document describes various functions that couldn't be placed in any of
+the other Automation 4 documents.
+
+---
+
+Getting the rendered size of a string
+
+This function might later on be part of a full rendering-interface for
+creating actual bitmaps of text.
+
+This function does NOT attempt to handle line breaks, automatic line breaking,
+fomatting override tags, vector drawings or anything else to that effect.
+If you need such functionality, you need to implement it yourself. (For now,
+at least.)
+
+function aegisub.text_extents(style, text)
+
+@style (table)
+  A "style" class Subtitle Line table. This 
+
+@text (string)
+  The text to calculate the rendered size of.
+
+Returns: 4 values, all numbers.
+  1. Width of text in pixels.
+  2. Height of text in pixels.
+  3. Descent of text in pixels.
+  4. External leading of text in pixels.
+
+---

automation/v4-docs/overview.txt

@@ -1,8 +1,8 @@
 Aegisub Automation documentation
 Version 4
 Copyright 2005-2006 Niels Martin Hansen
-THIS IS A DRAFT. SUBJECT TO CHANGE.
-Last updated: 2006-02-01 04:17 UTC+1
+
+THIS IS OUT OF DATE COMPARED TO THE REST OF THE DOCS!
 
 ---
 
@@ -31,6 +31,11 @@ Automation allows you to:
     o Exporters write directly to a file stream, allowing you to generate
       those huge karaoke effects much faster!
 
+Automation runs in a true Unicode environment, meaning strings are internally
+represented as UTF-32, so you, as programmer, don't have to worry about text
+encodings, prefix encodings etc. to write scripts that can handle text in
+mostly any language of the world.
+
 ---
 
 Scripts, files functions
@@ -41,7 +46,8 @@ being the master script, and the others being include files.
 
 Every script runs in a separate Lua interpreter, so separate scripts cannot
 communicate directly with each other. Scripts can share code by having common
-include files.
+include files. Scripts can share data by storing data in the subtitle files,
+either in the dialogue lines or in the Script Info headers.
 
 Files containing Automation scripts must in UTF-8 encoding, with or without
 BOM (Byte Order Mark). Compiled Lua scripts should also work, as long as all
@@ -65,9 +71,9 @@ The following four features can be implemented by an Automation script:
 
    The macro can create and display dialog windows to the user.
 
-   For preformance-reasons, there is currently no provision for the script to
-   enable/disable its menu item based on eg. the selection in the Aegisub
-   subtitles grid.
+   A macro can provide a function, that determines whether the macro cen be
+   run, based on the current selection in the program, and the contents of
+   the subtitles.
 
  - Export filter
    An export filter is presented as a filter in the Export dialog accessed
@@ -76,16 +82,10 @@ The following four features can be implemented by an Automation script:
    Styles and Script Info lines) in the subtitle file, and can add/modify/
    remove lines in those.
 
-   The export filter can specify a static configuration dialog presented to
-   the user in the Export UI.
-
-   The export filter can specify a function that's run after the user selects
-   the Export item on the File menu, but before the Export dialog is actually
-   displayed. This function will be given access to the subtitles currently
-   loaded. This is to feature customising the configuration dialog based on
-   the contents of the subtitles.
-   It is strongly discouraged to change anything but a single, private Script
-   Info header line in the subtitles handed to this initialisation function.
+   The export filter can provide a function, that returns a configuration
+   dialog, which is presented to the user before the export is run. This
+   function can access the subtitle data in order to customise the
+   configuration dialog, before it's presented to the user.
 
  - File format reader
    It is not yet decided how the file format reader is accessed.
@@ -166,11 +166,11 @@ Version 2
 
 Version 3
   Using Lua as engine.
-  Aegisub 1.10 was the last version to use Automation 3.
+  Aegisub 1.09 was the last release-version to use Automation 3.
   (Tentative release date only!)
 
 Version 4
   Using Lua as engine
-  Present in Aegisub 1.11 and later (tentative!)
+  Present in Aegisub 1.10 and later (tentative!)
   Heavily expanded feature set, allowing a much wider range of modifications,
   and more direct integration into the Aegisub user interface.

automation/v4-docs/progress-reporting.txt

@@ -0,0 +1,102 @@
+Automation 4 Progress Reporting and Debugging interface
+
+This document describes the functions used for reporting progress and
+outputting debug information during the running of a script.
+
+---
+
+Showing/hiding the progress dialog
+
+This function is used to show or hide the progress dialog.
+
+function aegisub.progress.show(do_show, can_cancel)
+
+@do_show (boolean)
+  True if the dialog should be shown, false if it should be hidden.
+
+@can_cancel (boolean)
+  Determines whether the Cancel button is shown. If you set this to true,
+  you should remember to periodically test whether the script has been
+  cancelled.
+
+Returns: nothing.
+
+---
+
+Setting the progress bar position
+
+function aegisub.progress.set(precent)
+
+@percent (number)
+  The percentage completed.
+
+Returns: nothing.
+
+---
+
+Showing the current task
+
+Used to set a message describing the current task being done.
+
+function aegisub.progress.task(msg, ...)
+
+@msg (string)
+  A format string used for the message.
+
+@...
+  Parameters to the format string.
+
+Returns: nothing.
+
+---
+
+Setting the progress dialog title
+
+function aegisub.progress.title(title, ...)
+
+@title (string)
+  A format string used for the title.
+
+@...
+  Parameters to the format string.
+
+Returns: nothing.
+
+---
+
+Getting the "cancelled" status
+
+Call this function to determine whether the Cancel button in the progress
+dialog has been clicked.
+
+function aegisub.progress.is_cancelled()
+
+Returns: Boolean. True is the user has clicked the Cancel button, false if it
+  has not been clicked, nil if there is no Cancel button.
+
+---
+
+Outputting text to the debug log
+
+function aegisub.debug.out(level, msg, ...)
+
+@level (number)
+  Integer describing the verbosity of this message. Here are some suggested
+  values you can use:
+    0: Fatal, this is really an error that can't be ignored.
+    1: Error, this kind of error can be recovered from, but might result in a
+       fatal error later on.
+    2: Warning, something might be going wrong.
+    3: Hint, something isn't entirely sane, but nothing wrong.
+    4: Debug, some additional data only needed for development.
+    5: Trace, extremely verbose data showing every tiny step during execution.
+
+@msg (string)
+  A format string used for the message.
+
+@...
+  Parameters for the format string.
+
+Returns: nothing.
+
+---

automation/v4-docs/subtitle-data.txt

@@ -134,7 +134,7 @@ encoding (number)
   constants.
 
 relative_to (number)
-  ???
+  From STS.h: "0: window, 1: video, 2: undefined (~window)"
 
 vertical (boolean)
   Whether vertical text semantics is used or not.
@@ -164,7 +164,7 @@ layer (number)
 
 start_time (number)
 end_time (number)
-  Start/end time of the line in miliseconds.
+  Start/end time of the line in milliseconds.
 
 style (string)
   Name of the style assigned to this line.
@@ -197,11 +197,12 @@ 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:
+The following operations are supported.
 
-n = subs[0]
-n = subs.length
+n = #subs
+n = subs.n
   Retrieve the number of lines in total.
+  The first syntax is preferred.
 
 line = subs[i]
   Retrieve line i, assuming 1 <= i <= n.
@@ -222,16 +223,176 @@ subs.deleterange(a, b)
   nothing is done.
 
 subs[0] = line
-subs.append(line)
-  Append a line to the file.
+subs.append(line[, line2, ...])
+  Append one or more lines to a file.
 
 subs[-i] = line
 subs.insert(i, line[, line2, ...])
-  Insert a line before index i.
-  The function syntax can also insert multiple lines.
+  Insert one or more lines before index i.
 
-(Note that the function-syntax ways of doing these operations is slower than
-the array-syntax way of doing them.)
+Note that the array-style accessors are most likely faster for any case only
+involving one line at a time, while the function syntax versions are probably
+faster if operating on multiple lines at a time.
 
 ---
 
+Parsing tag data
+
+This function uses the Aegisub SSA parser to split a string into override
+blocks and text, and give separate access to each tag in override blocks.
+
+function aegisub.parse_tag_data(text)
+
+@text (string)
+  The SSA format string to parse.
+
+Returns: A Parsed Tag Data table.
+
+---
+
+Recreating a line from tag data
+
+This function takes a Parsed Tag Data table and creates an SSA string from it.
+
+function aegisub.unparse_tag_data(tagdata)
+
+@tagdata (table)
+  The Parsed Tag Data table to "unparse".
+
+Returns: A string, being the "unparsed" data.
+
+---
+
+Parsing karaoke data
+
+Tihs function uses the Aegisub SSA parser to split a string into karaoke
+syllables with additional calculated information added.
+
+function aegisub.parse_karaoke_data(text)
+
+@text (string)
+  The SSA format string to parse.
+
+Returns: A Parsed Karaoke Data table.
+
+---
+
+Parsed Tag Data table
+
+The Parsed Tag Data table is an Array Table containing a number of Parsed Line
+Block tables.
+
+
+Parsed Line Block table
+
+A Parsed Line Block describes part of a line. (See ass_dialogue.cpp:70 for a
+more complete description of this.
+There are several classes of Parsed Line Block tables, which have slightly
+varying fields.
+
+
+Base Parsed Line Block table class
+
+class (string)
+  One of:
+    "plain",
+    "override",
+    "drawing"
+
+
+"plain" and "drawing" Parsed Line Block table classes
+
+text (string)
+  The text contained in this block.
+
+
+"override" Parsed Line Block table class
+
+This class doesn't have any new, specifically named fields. It does, however,
+have multiple integer indexed fields, ie. acts as an Array Table.
+Each of these indexes refer to a table of type Parsed Override Tag.
+
+
+Parsed Override Tag table
+
+This table describes a single override-tag in an SSA line.
+
+valid (boolean)
+  Whether this tag was parsed as a valid tag, or is just used for representing
+  junk in the middle of the line.
+
+name (string)
+  Name of the tag, including leading backslash character. (In the case of
+  invalid tags, the leading backslash might not be present.)
+
+paran (boolean)
+  Whether this tag has parantheses in its textual representation.
+
+params (table)
+  This is an Array Table containing the parameters for this tag. It will
+  always have the maximum number of entries that can be supported by the tag,
+  but in case of omitted parameters, the parameters omitted will have 'false'
+  for value in this table.
+
+---
+
+Parsed Karaoke Data table
+
+The Parsed Karaoke Data table is simply an Array Table of Karaoke Syllable
+Data tables. However, the Parsed Karaoke Data table will always have one more
+item than its count shows, which is numbered 0 (zero). This item contains
+everything before the first syllable.
+
+
+Karaoke Syllable Data table
+
+This table contains information about a single karaoke syllable.
+
+duration (number)
+  Duration of the syllable in milliseconds.
+  (In case of syllable zero, this is always zero.)
+
+start_time (number)
+end_time (number)
+  Start and end times of the syllable, relative to the start of the line,
+  given in milliseconds.
+  (While these can technically easily be calculated from the duration data,
+  they are too convenient to leave out from the standard interface.)
+
+tag (string)
+  The tag used for marking up this syllable. Usually one of:
+    "k", "K", "kf", "ko"
+  (In case of syllable zero, this is always the empty string.)
+
+text (string)
+  The text of the syllable, including all additional override tags.
+
+text_stripped (string)
+  The text of the syllable, stripped of any override tags.
+
+---
+
+Setting undo points
+
+This function can only be used in macro features, it will have no effect when
+used in any other feature.
+It sets an undo point.
+
+You should always call this function after every operation that must be
+undoable as a separate step. It is considered very bad practice to modify
+the subtitles in a macro without setting at least one undo-point, which must
+be at the end.
+
+Furthermore, this function also marks the subtitles as "modified". No other
+function does this.
+
+function aegisub.set_undo_point(description)
+
+@description (string)
+  A short description of the operation that will be undone, if this undo-point
+  is used. Note that this is currently unused in Aegisub, and this parameter
+  is simply ignored.
+
+Returns: nothing.
+
+---