Yet more function documentation

git-svn-id: svn://svn.code.sf.net/p/magicseteditor/code/trunk@573 0fc631ac-6414-0410-93d0-97cfa31319b6

doc/function/combine_blend.txt

@@ -1,4 +1,4 @@
-Function: linear_blend
+Function: combine_blend
 
 --Usage--
 > combine_blend(image1: image, image2: image, combine: combine_mode)

doc/function/copy_file.txt

@@ -0,0 +1,22 @@
+Function: copy_file
+
+--Usage--
+> copy_file(filename)
+
+Copy a file from the export template package to the output directory.
+If a file with the given name already exists it is overwritten.
+
+Returns the name of the file written.
+
+This function can only be used in an [[type:export template]], when <tt>create directory</tt> is true.
+
+--Parameters--
+! Parameter	Type			Description
+| @input@	[[type:filename]]	File to copy
+
+--Examples--
+> copy_file("logo.png") == "logo.png" # this file is now in the output directory
+
+--See also--
+| [[fun:write_text_file]]	Write a text file to the output directory.
+| [[fun:write_image_file]]	Write an image file to the output directory.

doc/function/english_plural.txt

@@ -0,0 +1,16 @@
+Function: english_plural
+
+--Usage--
+> english_plural(some_word)
+> english_singular(some_word)
+
+Convert a word to the plural or singular form.
+
+--Parameters--
+! Parameter	Type			Description
+| @input@	[[type:string]]		String to convert
+
+--Examples--
+> english_plural("apple") == "apples"
+> english_plural("berry") == "berries"
+> english_singular("Red Horses") == "Red Horse"

doc/function/filter_text.txt

@@ -0,0 +1,27 @@
+Function: filter_text
+
+--Usage--
+> filter_text(some_string, match: regular expression, in_context: regular expression)
+> filter_rule(match: ..., in_context: ...)(some_string)
+
+Filter text by only keeping the parts of the input that match the regular expression.
+
+If @in_context@ is given, the context must also match the string where the match is represented as <tt>&lt;match></tt>.
+
+--Parameters--
+! Parameter	Type			Description
+| @input@	[[type:string]]		String to replace in.
+| @match@	[[type:regex]]		Regular expression to match.
+| @in_context@	[[type:regex]] (optional)	Context to match
+
+--Examples--
+> filter_text(match: "a", "banana")  ==  "aaa"
+> filter_text(match: ".", in_context:"a<match>", "banana")  ==  "nn"
+> filter_text(match: "[xy]", "xyz")  ==  "xy"
+>
+> f := filter_rule(match: "xx+")
+> f("xyzxxyyzz") == "xx"
+
+--See also--
+| [[fun:replace|replace / replace_rule]]
+				Replace text matching a regular expression.

doc/function/masked_blend.txt

@@ -1,4 +1,4 @@
-Function: linear_blend
+Function: masked_blend
 
 --Usage--
 > linear_blend(light: image, dark: image, mask: image)

doc/function/symbols_to_html.txt

@@ -0,0 +1,22 @@
+Function: symbols_to_html
+
+--Usage--
+> symbols_to_html(some_tagged_text)
+
+Convert a [[type:tagged string]] to HTML code for use in web pages, entirely using a symbol font.
+This is intended for fields with @always symbol:true@.
+
+This function can only be used in an [[type:export template]], when <tt>create directory</tt> is true, as the images
+of the font are written to the output directory.
+
+--Parameters--
+! Parameter		Type				Description
+| @input@		[[type:tagged string]]		String to convert to html
+| @symbol_font@		[[type:string]]			Name of a symbol font to use.
+| @symbol_font_size@	[[type:double]] (optional)	Size in points to use for the symbol font, default 12
+
+--Examples--
+> symbols_to_html("WU")    == "<img src='data-dir/w.png' alt='W'><img src='data-dir/u.png' alt='U'>"
+
+--See also--
+| [[fun:to_html]]		Convert [[type:tagged text]] to html.

doc/function/to_html.txt

@@ -0,0 +1,30 @@
+Function: to_html
+
+--Usage--
+> to_html(some_tagged_text)
+
+Convert a [[type:tagged string]] to HTML code for use in web pages.
+Characters are correctly escaped for HTML code.
+
+The following tags are converted to html:
+! Tag			Description
+| <tt>&lt;b></tt>	Bold
+| <tt>&lt;i></tt>	Italic
+| <tt>&lt;sym></tt>	Symbols, if the @symbol_font@ parameter is set.
+
+Symbol fonts can only be used in an [[type:export template]], when <tt>create directory</tt> is true, as the images
+of the font are written to the output directory.
+
+--Parameters--
+! Parameter		Type				Description
+| @input@		[[type:tagged string]]		String to convert to html
+| @symbol_font@		[[type:string]] (optional)	Name of a symbol font to use for images.
+| @symbol_font_size@	[[type:double]] (optional)	Size in points to use for the symbol font, default 12
+
+--Examples--
+> to_html("<b>bold text</b>") == "<b>bold text</b>"
+> to_html("<sym>WU</sym>")    == "<img src='data-dir/w.png' alt='W'><img src='data-dir/u.png' alt='U'>"
+
+--See also--
+| [[fun:symbols_to_html]]	Convert text to html using a [[type:symbol font]].
+| [[fun:to_text]]		Remove all tags from tagged text.

doc/function/to_text.txt

@@ -0,0 +1,17 @@
+Function: to_text
+
+--Usage--
+> to_text(some_tagged_text)
+
+Convert a [[type:tagged string]] to a normal string by removing all tags and restoring escaped < characters.
+
+
+--Parameters--
+! Parameter	Type				Description
+| @input@	[[type:tagged string]]		String to convert to text
+
+--Examples--
+> to_text("<b>bold text</b>") == "bold text"
+
+--See also--
+| [[fun:to_html]]		Convert [[type:tagged text]] to html.

doc/function/write_image_file.txt

@@ -0,0 +1,24 @@
+Function: write_image_file
+
+--Usage--
+> write_image_file(some_image, file: filename)
+
+Write an image to a file in the output directory.
+If a file with the given name already exists it is overwritten.
+
+Returns the name of the file written.
+
+This function can only be used in an [[type:export template]], when <tt>create directory</tt> is true.
+
+--Parameters--
+! Parameter	Type			Description
+| @input@	[[type:image]]		Image to write to the file.
+| @file@	[[type:string]]		Name of the file to write to
+| @width@	[[type:int]]		Width in pixels to use for the image, by default the size of the image is used if available.
+| @height@	[[type:int]]		Height in pixels to use for the image, by default the size of the image is used if available.
+
+--Examples--
+> write_image("image_out.png", linear_blend(...)) == "image_out.png" # image_out.png now contains the given image
+
+--See also--
+| [[fun:write_text_file]]	Write a text file to the output directory.

doc/function/write_text_file.txt

@@ -0,0 +1,22 @@
+Function: write_text_file
+
+--Usage--
+> write_text_file(some_string, file: filename)
+
+Write a string to a file in the output directory.
+If a file with the given name already exists it is overwritten.
+
+Returns the name of the file written.
+
+This function can only be used in an [[type:export template]], when <tt>create directory</tt> is true.
+
+--Parameters--
+! Parameter	Type			Description
+| @input@	[[type:string]]		Text to write to the file.
+| @file@	[[type:string]]		Name of the file to write to
+
+--Examples--
+> write_file("index.html", lots_of_html_code) == "index.html" # index.html now contains the given text
+
+--See also--
+| [[fun:write_image_file]]	Write an image file to the output directory.