Automation scripts updated, mainly heavy commenting on the demo scripts. Updated readme files for script directories.

Removed some old code from the colorpicker.

Originally committed to SVN as r484.

automation/demos/1-minimal.lua

@@ -2,15 +2,32 @@
 -- Original written by Niels Martin Hansen
 -- Given into the public domain
 
+-- Comment lines (like this line) start with two hyphens, these are ignored when the script is interpreted.
+-- This script does not do anything useful, it merely displays a message. Think of it as a kind of "hello world" script.
+
+-- The following lines define some values identifying the script
+-- This script is written for Automation version 3
 version = 3
+-- And it's a "basic ass" processing script. There are no other kinds of scripts though... but this is still required.
 kind = "basic_ass"
+-- This is the name of the script that shows up in Aegisub
 name = "Minimal demonstration"
+-- This is a longer description of the script
 description = "A very minimal demonstration of the strucrure of an Automation script."
+-- This defines any configuration that can be done of the script. This is demonstrated in demo 5.
+-- The empty braces denote an empty table (associative array)
 configuration = {}
 
+-- This is the main function of the script.
+-- This function is run whenever the script is run
 function process_lines(meta, styles, lines, config)
+	-- The function aegisub-report_progress changes the position of the progress bar shown while the script is running
+	-- The value given is in percent.
 	aegisub.report_progress(50)
+	-- The aegisub,.output_debug function shows some text
 	aegisub.output_debug("Test script 1 running")
 	aegisub.report_progress(100)
+	-- It is very important that the process_lines function returns an array of lines, otherwise an error will occur
+	-- If an empty array is returned, the entire file is cleared!
 	return lines
 end

automation/demos/10-furigana.ass

@@ -1,22 +1,18 @@
 [Script Info]
-; Script generated by Aegisub
+; Demonstration script for Aegisub Automation 3 demo script '10-furigana.lua'
 ; http://www.aegisub.net
-Title: Default Aegisub file
+Title: Furigana demonstration
 ScriptType: v4.00+
-PlayResX: 704
+PlayResX: 640
 PlayResY: 480
-Last Style Storage: Default
-Video Aspect Ratio: 0
-Video Zoom: 6
-Video Position: 0
-Automation Scripts: 10-furigana.lua|E:\Anime Projekter\Binchou-tan\op\binchou-fx.lua
+Automation Scripts: 10-furigana.lua
 Export Encoding: UTF-8
-Export filters: Automation: Binchou-tan OP
+Export filters: Automation: Furigana demo
 WrapStyle: 0
 
 [V4+ Styles]
 Format: Name, Fontname, Fontsize, PrimaryColour, SecondaryColour, OutlineColour, BackColour, Bold, Italic, Underline, StrikeOut, ScaleX, ScaleY, Spacing, Angle, BorderStyle, Outline, Shadow, Alignment, MarginL, MarginR, MarginV, Encoding
-Style: Default,MS Gothic,36,&H00FFFFFF,&H0000FFFF,&H00000000,&H00000000,0,0,0,0,100,100,0.00,0.00,1,2.00,2.00,2,10,10,30,0
+Style: Default,MS Gothic,36,&H00FFFFFF,&H0000FFFF,&H00000000,&H00000000,0,0,0,0,100,100,0,0,1,2,2,2,10,10,30,0
 
 [Events]
 Format: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text

automation/demos/10-furigana.lua

@@ -2,8 +2,11 @@
 -- Original written by Niels Martin Hansen
 -- Given into the public domain
 
+-- Furigana is handled by the advanced karaskel
 include("karaskel-adv.lua")
+-- But it requires some additional functionality to be enabled as well. Do that here
 karaskel.engage_furigana = true
+-- Enabling trace isn't really required, but it's nice for debugging
 karaskel.engage_trace = true
 
 version = 3
@@ -12,32 +15,44 @@ name = "Furigana demo"
 description = "Demonstrates how to use the Furigana feature in karaskel-adv"
 
 function do_syllable(meta, styles, config, line, syl)
+	-- First prepare a table to add the resulting lines of this syllable to
 	local result = {n=0}
+	-- Actually, make a function that does some stuff for us
+	-- Calling result.add will create another copy of the current line, add it to the result table, and return a reference to the new line
+	-- The result from this function can just be modified, and the line in the result table changes along (since it's just a reference)
 	function result.add()
 		local l = copy_line(line)
 		table.insert(result, l)
 		return l
 	end
 	-- Place the main text
+	-- So far no magic, just a regular line placed
 	local l = result.add()
 	l.text = string.format("{\\an8\\pos(%d,%d)\\k%d\\kf%d}%s", line.centerleft+syl.center, line.height*1.5, syl.start_time/10, syl.duration, syl.text_stripped)
 	l.layer = 5
-	-- Perform the highlights
+	-- Now for some "magic" stuff, loop over the highlights array to add possibly multiple highlights to each syllable
+	-- For example, kanji spanning multiple syllables can "flash" multiple times this way
 	for i = 0, syl.highlights.n-1 do
 		local hl = syl.highlights[i]
 		l = result.add()
 		l.start_time = l.start_time + hl.start_time/10
 		l.end_time = l.start_time + 25
 		l.text = string.format("{\\an8\\k10000\\k0\\move(%d,%d,%d,%d)\\t(\\1a&HFF&\\2a&HFF&\\3a&HFF&\\4a&HFF&)}%s", line.centerleft+syl.center, line.height*1.5, line.centerleft+syl.center, line.height*3, syl.text_stripped)
+		-- Put each highlight in a layer for itself, because they might overlap. This creates a possibly slightly nicer effect
 		l.layer = 10+i
 	end
-	-- Place the furigana
+	-- Now for the real magic, ,loop over the furigana array
+	-- This contains a lot of pre-calculated info about how each furigana syllable should be placed relatively to the beginning of the line
+	-- With this info, it's really not much different from making a "main" effect. You just have to be aware that you're working with much smaller font sizes
 	for i = 0, syl.furigana.n-1 do
 		local furi = syl.furigana[i]
 		l = result.add()
+		-- Be sure to include the \fscx%f\fs%f tags here! Otherwise the text will be incorrectly scaled.
+		-- The \fscx is also important, because long stretches of furigana might be squished together so it all fits over the main text
 		l.text = string.format("{\\an2\\k%d\\k%d\\bord2\\fscx%.1f\\fs%.1f\\t(%d,%d,\\bord0)\\pos(%d,%d)}%s", furi.start_time/10, furi.duration, syl.furigana.scale, syl.furigana.fontsize, furi.start_time, furi.end_time, line.centerleft+furi.center, line.height*1.5, furi.text)
 		l.layer = 3
 	end
+	-- The additional 'add' function in the result is ignored when it's read back by the caller
 	return result
 end
 

automation/demos/2-dump.lua

@@ -2,6 +2,7 @@
 -- Original written by Niels Martin Hansen
 -- Given into the public domain
 
+-- For an explanation of these, see the documentation, or demo 1
 version = 3
 kind = "basic_ass"
 name = "Reading data demonstration"
@@ -9,35 +10,49 @@ description = "This is a demonstration of how to access the various data passed
 configuration = {}
 
 function process_lines(meta, styles, lines, config)
-	out = aegisub.output_debug
+	-- This makes an alias for the aegisub.output_debug function. Remember that functions are first-class values in Lua.
+	-- The 'local' keyword makes the 'out' variable local to this function
+	local out = aegisub.output_debug
 	
+	-- Use the string.format function to form a string showing some metadata about the subtitles and output it
 	out(string.format("Metadata: res_x=%d res_s=%d", meta.res_x, meta.res_y))
 	
-	numstyles = styles[-1]
+	-- The number of styles is stored in index -1, because there might be a style named "n"
+	local numstyles = styles[-1]
 	out("Number of styles: " .. numstyles)
+	-- Loop over the styles with a for loop, printing some info about each style
 	for i = 0, numstyles-1 do
 		out(string.format("Style %d: name='%s' fontname='%s'", i, styles[i].name, styles[i].fontname))
 	end
 	
+	-- Do the same, but for the actual subtitle lines
 	out("Number of subtitle lines: " .. lines.n)
 	for i = 0, lines.n-1 do
+		-- Use the report_progress function to show the progress of the loop
 		aegisub.report_progress(i/lines.n*100)
+		-- Check if the line is a dialogue line, otherwise it won't have much interesting data
+		-- Also, the script will crash if you try to access a field that doesn't exist
 		if lines[i].kind == "dialogue" then
+			-- Again, output some info about the line
 			out(string.format("Line %d: dialogue start=%d end=%d style=%s", i, lines[i].start_time, lines[i].end_time, lines[i].style))
 			out("   Text: " .. lines[i].text)
 			out("   Stripped text: " .. lines[i].text_stripped)
 			out("   Number of karaoke syllables: " .. lines[i].karaoke.n)
+			-- Also loop over the karaoke syllables, if any, in the line.
+			-- Note that there will actually always be at least one syllable, number zero, which is everything before the first \k tag
 			for j = 0, lines[i].karaoke.n-1 do
 				syl = lines[i].karaoke[j]
+				-- Use the aegisub.text_extents function to calculate the rendered size of the syllable text
+				-- Note that the styles[lines[i].style] construct can be dangerous, in case the line refers to a non-existant style
 				extx, exty, extd, extl = aegisub.text_extents(styles[lines[i].style], syl.text_stripped)
 				out(string.format("        Syllable %d: dur=%d kind=%s text='%s' text_stripped='%s' extx=%d exty=%d extd=%d extl=%d", j, syl.duration, syl.kind, syl.text, syl.text_stripped, extx, exty, extd, extl))
-				--out(string.format("        Syllable %d: kind=%s", j, syl.kind))
 			end
 		else
+			-- For non-dialogue lines, output a lot less info
 			out(string.format("Line %d: %s", i, lines[i].kind))
 		end
 	end
 	
-	-- but really just do nothing
+	-- In the end, no modifications were done, so just return the original subtitle data
 	return lines
 end

automation/demos/3-include.lua

@@ -2,15 +2,24 @@
 -- Original written by Niels Martin Hansen
 -- Given into the public domain
 
+-- This script demonstrated using include scripts in Automation.
+-- You include a file simply by calling the include function with a filename.
+-- Depending on whether the filename contains a path or not, it is interpreted in slightly different ways,
+-- see the documentation for more information.
 include("utils.lua")
 
+-- The usual info
 name = "Include demo"
 description = "Simple demonstration of the include function."
-
+-- Here several values are set in one line
 version, kind, configuration = 3, 'basic_ass', {}
 
 function process_lines(meta, styles, lines, config)
+	-- Copy the first line (line 0) and store it as as a new last line
+	-- The last line has index lines.n-1, so lines.n is one past the last line
 	lines[lines.n] = copy_line(lines[0])
+	-- Make sure to increment 'n', so the correct number of lines are read out
 	lines.n = lines.n + 1
+	-- Then return the modified lines table
 	return lines
 end

automation/demos/4-text_extents.lua

@@ -6,7 +6,6 @@ include("utils.lua")
 
 name = "Text placement demo"
 description = "Demonstration of the text_extents function, to do per-syllable placement of text."
-
 version, kind, configuration = 3, 'basic_ass', {}
 
 function process_lines(meta, styles, lines, config)

automation/demos/5-configuration.lua

@@ -4,45 +4,65 @@
 
 name = "Configuration demo"
 description = "This script allows the user to input some data in the Aegisub Export window. Some of these data are used during the processing, to change the subtitles. (The strings is prepended every dialogue line.)"
+version, kind = 3, 'basic_ass'
+-- The configuration table defines a number of controls to show in the config window
+-- The controls must be numbered from 1 and up with no "holes", the number of controls is automatically detected
 configuration = {
     [1] = {
+		-- There are some mandatory fields for evry control defined
+		-- 'name' is the internal name of the control, it's used to refer to the value the user entered later on
         name = "thelabel";
+		-- 'kind' is the class of control, this is a label which only displays text and can't be edited
         kind = "label";
+		-- 'label' is  a short description of the control, displayed ot the left of it.
+		-- In the case of a label control, it's the entire text displayed
         label = "This is a label control. Just for shows.";
+		-- 'hint' is a tooltip for the control. It doesn't actually work for label controls though
         hint = "Tooltip for label?!?";
         };
     [2] = {
         name = "thestring";
+		-- the "text" class is a regular text input field
         kind = "text";
         label = "String:";
         hint = "The string to insert at the beginning of each line";
+		-- The 'default' is required for everything but 'label' controls, it simply specifies the default value
         default = "foobar "
         };
     [3] = {
         name = "theint";
+		-- 'int' is a text control that only allows inputting whole numbers (integers)
         kind = "int";
         label = "Integer:";
         hint = "An integer number to display in debug output";
         default = 50;
+		-- If the 'min' and 'max' fields are specified, the control will get a "spin control" attached,
+		-- which can be used to change the value with the mouse
         min = 0;
         max = 100;
         };
     [4] = {
         name = "thefloat";
+		-- 'float' is like int, except you can also put decimal numbers in  it
         kind = "float";
         label = "Float number:";
         hint = "Just a random float number";
         default = 3.1415927;
+		-- There are no working spin controls for floats, unfortunately
         };
     [5] = {
         name = "thebool";
+		-- 'bool' makes a checkbox, which can either be checked or unchecked
         kind = "bool";
         label = "I accept";
         hint = "Check if you accept the terms of the license agreement";
+		-- false means unchecked, true means checked
         default = false;
         };
     [6] = {
         name = "thecolour";
+		-- 'colour' is currently just a text edit box which allows you to input an ASS format color
+		-- The idea was to have some kind of graphical control, but that probably won't happen in auto3
         kind = "colour";
         label = "Favourite color:";
         hint = "What color do you want your pantsu?";
@@ -50,20 +70,24 @@ configuration = {
         };
     [7] = {
         name = "thestyle";
+		-- 'style' produces a drop down list, where the user can select one of the styles in the file, or no style at all
         kind = "style";
         label = "Style:";
         hint = "Pick a style the effects will apply to, or none to apply to everything";
+		-- An empty string means that nothing is selected
+		-- Be careful about assuming any style names that might be available in the subtitle file
         default = "";
         }
 }
 
-version, kind = 3, 'basic_ass'
-
 function process_lines(meta, styles, lines, config)
+	-- All the values selected by the user are stored in the 'config' variable
+	-- For example, control 2 in this example has name "thestring", so you can access the value input by config.thestring
     aegisub.output_debug("The string entered is: " .. config.thestring)
     for i = 0, lines.n-1 do
 		aegisub.report_progress(i/lines.n*100)
         if lines[i].kind == "dialogue" then
+			-- So loop over all dialogue lines and append thestring to them all
             lines[i].text = config.thestring .. lines[i].text
         end
     end

automation/demos/7-advanced-effect.lua

@@ -4,6 +4,13 @@
 -- But still, please don't use the effect generated by this script
 -- (unchanged) for your own works.
 
+-- Note that many of the techniques used in this script are heavily deprecated, much of the processing done
+-- is also done by the karaskel scripts.
+-- In fact, this can almost be viewed as an example of how *not* to do things...
+
+-- Since this script assumes some rather specific things about the ASS input, it might not be very useful at first.
+-- The original ASS file this was written for is available upon request.
+
 include("utils.lua")
 
 name = "Advanced karaoke effect"

automation/demos/8-skeleton.lua

@@ -4,15 +4,23 @@
 
 name = "Karaoke skeleton demo"
 description = "This script demonstrates the use of the karaskel.lua include file, to avoid writing almost identical code for every karaoke effect script."
-
 version, kind, configuration = 3, 'basic_ass', {}
 
+-- Include the "magic" karaskel.lua file. It also includes utils.lua for you.
+-- karaskel.lua defines the process_lines function, so you'll usually not have to write that yourself
 include("karaskel.lua")
 
+-- Instead, a do_syllable function is written. This is called by karaskel for every syllable, to get the text replacement for that syllable.
 function do_syllable(meta, styles, config, line, syl)
+	-- First check if it's the first syllable on the line; if it is don't bother doing anything special
 	if syl.i == 0 then
+		-- Remember you have to return the text of the syllable as well as any formatting tags you want
 		return syl.text
 	else
+		-- For other syllables, apply a little effect
 		return string.format("{\\r\\k%d\\t(%d,%d,\\1c&H%s&)}%s", syl.duration, syl.start_time, syl.end_time, line.styleref.color2, syl.text)
 	end
 end
+
+-- Exercise for the reader: Rewrite this script in "classic style", ie. the same way as demo 6.
+-- See how few lines you can get it down to, while still producing the same effect.

automation/factorybrew/readme.txt

@@ -1,5 +1,5 @@
 This directory contains flexible, configurable Automation scripts to do common jobs,
-without having to do programming.
+without having to do (much) programming.
 
 You can load these scripts into an ASS file in Aegisub, and apply an effect without
 doing more than writing ASS override tags.

automation/include/readme.txt

@@ -5,6 +5,14 @@ means the files here are always available for use with the include() function.
 See the Aegisub help and the individual files in this directory for more
 information on their purpose and contents.
 
-You may add your own files to this directory, they will not be touched upon
-uninstalling/upgrading Aegisub. The standard files here will, however, be
-removed/replaced on uninstall/upgrade, so you are advised not to edit those!
+
+DO NOT MODIFY THE CONTENTS OF THIS DIRECTORY OR ADD YOUR OWN FILES,
+
+any files added or modified might be deleted or reverted upon upgrade or
+uninstall of Aegisub.
+
+A better solution is to create your own include directory and put it in the
+"Automation Include Path" in the Aegisub config.dat file. The path
+specifications are separated by pipe characters ("|"). Using this method, you
+can also override the default includes with your own, modified versions, by
+placing the path to your own versions earlier in the path list.

core/dialog_colorpicker.cpp

@@ -548,13 +548,6 @@ DialogColorPicker::DialogColorPicker(wxWindow *parent, wxColour initial_color)
 	button_sizer->AddButton(cancel_button);
 	button_sizer->Realize();
 
-	/*wxGridBagSizer *input_sizer = new wxGridBagSizer(5, 5);
-	input_sizer->Add(rgb_box, wxGBPosition(0, 0), wxGBSpan(1, 4), wxALIGN_CENTER|wxEXPAND);
-	input_sizer->Add(hsl_box, wxGBPosition(1, 0), wxGBSpan(1, 2), wxALIGN_CENTER);
-	input_sizer->Add(hsv_box, wxGBPosition(1, 2), wxGBSpan(1, 2), wxALIGN_CENTER);
-	input_sizer->Add(screen_dropper, wxGBPosition(2, 0), wxGBSpan(1, 1), wxALIGN_CENTER);
-	input_sizer->Add(recent_box, wxGBPosition(2, 1), wxGBSpan(1, 3), wxALIGN_CENTER);
-	input_sizer->Add(button_sizer, wxGBPosition(3, 0), wxGBSpan(1, 4), wxALIGN_RIGHT|wxALIGN_BOTTOM);*/
 	wxSizer *input_sizer = new wxBoxSizer(wxVERTICAL);
 	input_sizer->Add(rgb_box, 0, wxALIGN_CENTER|wxEXPAND);
 	input_sizer->AddSpacer(5);