Minor bugfixing in karaskel.

Added preliminary Automation 4 design docs.

Originally committed to SVN as r218.

automation/include/karaskel-base.lua

@@ -80,7 +80,7 @@ function karaskel.precalc_syllable_data(meta, styles, lines)
 		meta.res_y = 288
 	elseif meta.res_x == 0 then
 		-- This is braindead, but it's how TextSub does things...
-		if meta.res_x == 1024 then
+		if meta.res_y == 1024 then
 			meta.res_x = 1280
 		else
 			meta.res_x = meta.res_y / 3 * 4
@@ -154,21 +154,27 @@ function karaskel.precalc_syllable_data(meta, styles, lines)
 				syl.inline_fx = inline_fx
 				-- Do positioning calculations, if applicable
 				sumtext = sumtext .. syl.text_stripped
+				karaskel.trace("new sumtext = " .. sumtext)
 				if karaskel.engage_positioning then
 					-- Summed text dimensions
 					local sumwidth = aegisub.text_extents(style, sumtext)
+					karaskel.trace("sumwidth = " .. sumwidth)
 					-- Strip some spaces
-					local tmp1, tmp2, prespc, syltxt, postspc = string.find(syl.text_stripped, "^(%s*)(.-)(%s*)$")
+					local tmp1, tmp2, prespc, syltxt, postspc = string.find(syl.text_stripped, "^([ \t]*)(.-)([ \t]*)$")
 					-- Pre/post space dimensions
 					local prespc_width = aegisub.text_extents(style, prespc)
 					local postspc_width = aegisub.text_extents(style, postspc)
+					karaskel.trace("space capture lengths = " .. string.len(prespc) .. ", " .. string.len(syltxt) .. ", " .. string.len(postspc))
+					karaskel.trace("space widths = " .. prespc_width .. ", " .. postspc_width)
 					-- Syllable dimensions
 					syl.width, syl.height, syl.ascent, syl.extlead = aegisub.text_extents(style, syltxt)
+					karaskel.trace("syllable text, width = " .. syltxt .. ", " .. syl.width)
 					karaskel.trace("precalc_syllable_data:8::")
 					-- Syllable positioning
 					syl.right = sumwidth - postspc_width
 					syl.left = sumwidth - syl.width + prespc_width
 					syl.center = math.floor(syl.left + (syl.right - syl.left) / 2)
+					karaskel.trace("syllable left, center, right = " .. syl.left .. ", " .. syl.center .. ", " .. syl.right)
 					if syl.furigana then
 						karaskel.calc_furigana_sizes(line, syl)
 					end

automation/v4-docs/data-structures.txt

@@ -0,0 +1,141 @@
+Automation 4 Basic Interface
+
+This document described the basic functions needed to define an Automation 4
+script. This covers Feature registration and the prototypes of functions used
+to implement the various features.
+
+---
+
+Macro Registation Function
+
+This is a function called from top-level of an Automation script to register
+a new Macro Feature.
+
+function aegisub.register_macro(
+    name,
+    description,
+    menu,
+    processing_function,
+    validation_function)
+
+@name (string)
+  The displayed name of the menu item this macro will generate.
+
+@description (string)
+  A longer description of the function of this macro. This will appear
+  on the status bar when hovering over the menu item.
+
+@menu (string)
+  The menu this macro will appear in. Can be one of:
+   o "edit"
+   o "video"
+   o "audio"
+   o "tools"
+   o "right" (the subtitles grid right-click menu)
+  The menu chosen should be relevant to the function of the macro.
+
+@processing_function (function)
+  The actual function called for the macro execution.
+  This function must be an instance of the Macro Processing Function
+  described below.
+
+@validation_function (functioon)
+  Optional. A function called when it is to be determined whether the
+  macro can act on the current subtitles.
+  This function, if provided, must execute very quickly to avoid lag
+  in the GUI.
+  This function must be an instance of the Macro Validation Function
+  described below.
+
+---
+
+Filter Registration Function
+
+This is a function called from top level of an Automation script to register
+a new Export Filter Feature.
+
+function aegisub.register_filter(
+    name,
+    description,
+    priority,
+    processing_function,
+    options_window_provider)
+
+@name (string)
+  The name of the filter, as presented to the user.
+
+@description (string)
+  A longer description of the filter presented to the user.
+
+@priority (nhumber)
+  A number determining the default order the enabled filters will be
+  processed. The order can be overridden by the user.
+  Priorities of some built-in filters:
+   o Clean Script Info = 0
+   o Fix Styles = -5000
+   o Transform Framerate = 1000
+  Filters with higher priority will be executed earlier by default.
+
+@processing_function (function)
+  The function called to do the actual filter processing.
+  This function must be an instance of the Filter Processing Function
+  described below.
+
+@options_window_provider (function)
+  Optional. A function providing a dialog template for setting options
+  prior to filter processing.
+  This function must be an instance of the Filter Options Window Provider
+  function described below.
+
+---
+
+Format Reader Registration
+
+This is a function called from top level in an Automation script to register
+a new File Format Reader Feature.
+
+function aegisub.register_reader(
+    name,
+    extension,
+    processing_function)
+
+@name (string)
+  The name of the file format.
+
+@extension (string)
+  The file extension usually given to this file format. This must not
+  include any wildcards. (Ie. extension could be "srt", "sub", "ssa" and
+  so on.)
+
+@processing_function (function)
+  The function called to do the actual file import.
+  This function must be an instance of the Format Reader Function described
+  below.
+
+---
+
+Format Writer Registration
+
+This is a function called from top level in an Automation script to register
+a new File Format Writer Feature.
+
+function aegisub.register_writer(
+    name,
+    extension,
+    processing_function)
+
+@name (string)
+  Name of the file format, as presented to the user.
+
+@extension (string)
+  The usual file extension given to this file format. This is automatically
+  be attached to the file name on export, unless the user chooses to
+  override it.
+
+@processing_function (function)
+  The function doing the actual file export.
+  This function must be an instance of the Format Writer Function described
+  below.
+
+---
+

automation/v4-docs/overview.txt

@@ -0,0 +1,176 @@
+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 document describes version 4 of the automation system used in Aegisub.
+The automation system uses the Lua language for scripting engine.
+See <http://www.lua.org/> for more information.
+
+---
+
+Overview
+
+Aegisub Automation is a scripting environment that allows you to automate
+almost any task working with subtitles in Aegisub, ie. a macro environment.
+
+Automation allows you to:
+ - Create macros (adding extra menu items to the main menu)
+    o Those macros can optionally also display dialog boxes to the user
+    o Allows adding new features to Aegisub without recompiling the entire
+      program!
+ - Write export filters
+    o This is what Automation 3 did, but with more options
+    o Useful for adding complicated special effects to a script
+ - Write file-format importers and exporters
+    o Load every strange subtitle format you come by
+    o Save in those formats as well
+    o Exporters write directly to a file stream, allowing you to generate
+      those huge karaoke effects much faster!
+
+---
+
+Scripts, files functions
+
+An automation script is a Lua script following certain conventions described
+in this document. A script consists of one or more files, with one of them
+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.
+
+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
+strings are UTF-8 encoded, but this is untested and unsupported.
+
+Automation scripts implement one or more of four possible features. A feature
+is implemented by filling a specially named global table with certain values.
+See below for a discussion about the various features and how they differ.
+
+---
+
+Scriptable features
+
+The following four features can be implemented by an Automation script:
+
+ - Macro
+   A macro is presented as a new menu item in the Automation menu on the menu
+   bar in Aegisub. When the user select the menu item, a function in the
+   Automation script is called to do processing. Features are present to allow
+   direct interaction with the subtitle data.
+
+   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.
+
+ - Export filter
+   An export filter is presented as a filter in the Export dialog accessed
+   from the File menu. The export filter is called when the user uses the
+   Export feature. The export filter is given access every line (including
+   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.
+
+ - File format reader
+   It is not yet decided how the file format reader is accessed.
+
+   Current ideas:
+    o It provides two functions, one to test whether it can handle a given
+      file and one to actually convert that file to ASS. Which import filter
+      to use is decided by Aegisub, based on the result of the first function.
+    o The user selects an import filter and a file. The import filter is
+      applied to the selected file.
+
+   The file format reader can present dialog windows to the user.
+
+   The file format reader is given access to the raw file stream.
+
+ - File format writer
+   The file format writer is selected in the Export dialog access from the
+   File menu. The file format writer is handed all the lines of the subtitles
+   file and a file stream to write to.
+
+   The file format writer can report itself as writing a binary format or a
+   text format. In the case of a text format, all output is passed through the
+   character set conversion routines in Aegisub.
+
+   The file format writer can present dialog windows to the user.
+
+Every feature is given access to the following in addition to what's described
+above:
+
+ - Displaying/hiding/updating a progress bar.
+ - Outputting messages to the user.
+ - Accessing framerate data
+ - (Not fully decided yet) Raw video frame data (RGB and/or YUV)
+ - (Not fully decided yet) Raw and FFT transformed wave data
+ - (Not fully decided yet) Utilising FexTracker functions
+ - Calculating the rendered size of a text string, given a style definition
+
+---
+
+Script registration
+
+Scripts can be loaded in two ways, through autoload or by assigning them to
+a subtitle file.
+
+Autoloading of scripts happens by placing the master script file into the
+"automation/autoload" directory under the Aegisub installation directory.
+
+Assining scripts to a subtitle file is done through the Automation Manager
+GUI. Scripts assigned to a subtitle file are stored in the ASS Script Info
+line "Automation Scripts", using a pipe character as separator between the
+master script filenames.
+
+The automatic loading/storing of configuration options from Automation 3 has
+been removed, but can still be implemented in an Export Filter feature using
+the initialisation function.
+
+---
+
+Actual documentation for functions, data structures and other interfaces is
+yet to be written.
+
+---
+
+
+Versions of the scripting interface
+
+Here's a quick history of the scripting interface:
+
+Version 1
+  Using Lua as engine.
+  The scripts used in the Karaoke Effector application, avaible at:
+  <http://www.jiifurusu.dk/files/programming/effector/> (currently down)
+
+Version 2
+  Using Python as engine.
+  The first draft for an Aegisub automation engine.
+  Never implemented.
+
+Version 3
+  Using Lua as engine.
+  Aegisub 1.10 was the last version to use Automation 3.
+  (Tentative release date only!)
+
+Version 4
+  Using Lua as engine
+  Present in Aegisub 1.11 and later (tentative!)
+  Heavily expanded feature set, allowing a much wider range of modifications,
+  and more direct integration into the Aegisub user interface.