Yet more function documentation

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

doc/function/built_in_image.txt

@@ -0,0 +1,18 @@
+Function: built_in_image
+
+--Usage--
+> built_in_image(image_name)
+
+Retrieve an image built into the program.
+
+--Parameters--
+! Parameter	Type			Description
+| @input@	[[type:string]]		Name of the image to retrieve
+
+--Possible values--
+! Image name	Image
+| @"bool_yes"@	<img src="bool_yes.png" alt="bool_yes" />
+| @"bool_no"@	<img src="bool_no.png" alt="bool_no"  />
+
+--Examples--
+> built_in_image("bool_yes")  ==  [[Image]]

doc/function/combine_blend.txt

@@ -0,0 +1,22 @@
+Function: linear_blend
+
+--Usage--
+> combine_blend(image1: image, image2: image, combine: combine_mode)
+
+Blend two images together using a [[type:combine|combine function]].
+
+The images must have the same size.
+
+--Parameters--
+! Parameter	Type			Description
+| @image1@	[[type:image]]		First image to blend
+| @image2@	[[type:image]]		Second image to blend
+| @combine@	[[type:combine]]	Combining function to use
+
+--Examples--
+> combine_blend(image1: "image1.png", image2: "image2.png", combine: "add")  ==  [[Image]]
+<pre style="padding-top:2px;padding-bottom:2px;"> combine_blend(image1: <img src="image1.png" alt='"image1.png"' style="border:1px solid black;vertical-align:middle;" />, image2: <img src="image2.png" alt='"image2.png"' style="border:1px solid black;vertical-align:middle;" />, combine: "add") == <img src="image_combine_blend.png" alt='"image_combine_blend.png"' style="border:1px solid black;vertical-align:middle;" /></pre>
+
+--See also--
+| [[fun:linear_blend]]		Blend two images together using a linear gradient.
+| [[fun:masked_blend]]		Blend two images together using a third mask image.

doc/function/contains.txt

@@ -16,3 +16,4 @@ Does one string contain another at any position?
 
 --See also--
 | [[fun:match|match / match_rule]]	Does a string match a regular expression?
+| [[fun:chosen]]			Is the given choice selected in a multiple choice value?

doc/function/english_number.txt

@@ -0,0 +1,24 @@
+Function: english_number
+
+--Usage--
+> english_number(number)
+> english_number_a(number)
+> english_number_multiple(number)
+> english_number_ordinal(number)
+
+Convert a number to English.
+These four functions all behave slightly differently:
+! Function			function(1)	function(2)	function(3)
+| @english_number@		@"one"@		@"two"@		@"three"@
+| @english_number_a@		@"a"@		@"two"@		@"three"@
+| @english_number_multiple@	@""@		@"two"@		@"three"@
+| @english_number_ordinal@	@"first"@	@"second"@	@"third"@
+
+If the input is a keyword parameter value, it leaves a hint tag for [[fun:process_english_hints]], to indicate whether the following word should be plural or singular.
+
+--Parameters--
+! Parameter	Type			Description
+| @input@	[[type:int]]		Number to convert
+
+--Examples--
+> english_number(1) == "one"

doc/function/filter_list.txt

@@ -8,6 +8,7 @@ Returns a new list that contain all elements in the list for which the filter pr
 If possible, when using a set, use the [[fun:position]] and [[fun:number_of_items]] functions instead.
 
 --Parameters--
+! Parameter	Type				Description
 | @input@	[[type:list]] or [[type:set]]	List to filter.
 | @filter@	[[type:function]]		Function indicating which values to keep,
 		  				Will be called with @input@ set to an item in the list.

doc/function/format.txt

@@ -5,9 +5,11 @@ Function: format
 > format_rule(format: format_specification)(some_number)
 
 Format a number or other string as a string, [[http://www.cplusplus.com/reference/clibrary/cstdio/printf.html|printf]] style.
+
 This function is available in [[script:rule form]].
 
 --Parameters--
+! Parameter	Type			Description
 | @input@	[[type:int]] or [[type:double]] or [[type:string]]
 		  			Item to format.
 | @format@	[[type:string]]		Format specification.

doc/function/index.txt

@@ -40,11 +40,11 @@ These functions are built into the program, other [[type:function]]s can be defi
 	
 ! English language			<<<
 | [[fun:english_number]]				Convert a number to text (@"one"@, @"two"@, ''etc.'')
-| [[fun:english_number_a]]		Convert a number to text (@"a"@, @"two"@, ''etc.'')
-| [[fun:english_number_multiple]]	Convert a number to text (@""@, @"two"@, ''etc.'')
-| [[fun:english_number_ordinal]]	Convert a number to text (@"first"@, @"second"@, ''etc.'')
+| [[fun:english_number|english_number_a]]		Convert a number to text (@"a"@, @"two"@, ''etc.'')
+| [[fun:english_number|english_number_multiple]]	Convert a number to text (@""@, @"two"@, ''etc.'')
+| [[fun:english_number|english_number_ordinal]]		Convert a number to text (@"first"@, @"second"@, ''etc.'')
 | [[fun:english_plural]]				Find the plural of a word, @"card" -> "cards"@.
-| [[fun:english_singular]]		Find the singular of a word, @"cards" -> "card"@.
+| [[fun:english_plural|english_singular]]		Find the singular of a word, @"cards" -> "card"@.
 | [[fun:process_english_hints]]				Process the hints left by english_ functions in a keyword's reminder text.
 	
 ! Fields and values			<<<

doc/function/linear_blend.txt

@@ -0,0 +1,28 @@
+Function: linear_blend
+
+--Usage--
+> linear_blend(
+>    image1: image, image2: image,
+>    x1: coordinate, y1: coordinate,
+>    x2: coordinate, y2: coordinate,
+> )
+
+Blend two images together using a linear gradient.
+
+The images must have the same size.
+
+--Parameters--
+! Parameter	Type			Description
+| @image1@	[[type:image]]		First image to blend
+| @image2@	[[type:image]]		Second image to blend
+| @x1@,@y1@	[[type:double]]		Coordinates where the gradient begins, and the first image is shown for 100%
+| @x2@,@y2@	[[type:double]]		Coordinates where the gradient ends, and the second image is shown for 100%
+
+--Examples--
+This gives a vertical gradient:
+> linear_blend(image1: "image1.png", image2: "image2.png", x1:0, y1:0, x2:1, y2:1)  ==  [[Image]]
+<pre style="padding-top:2px;padding-bottom:2px;"> linear_blend(image1: <img src="image1.png" alt='"image1.png"' style="border:1px solid black;vertical-align:middle;" />, image2: <img src="image2.png" alt='"image2.png"' style="border:1px solid black;vertical-align:middle;" />, x1:0, y1:0, x2:1, y2:1) == <img src="image_linear_blend.png" alt='"image_linear_blend.png"' style="border:1px solid black;vertical-align:middle;" /></pre>
+
+--See also--
+| [[fun:masked_blend]]		Blend two images together using a third mask image.
+| [[fun:combine_blend]]		Blend two images together using a given [[type:combine|combining mode]].

doc/function/masked_blend.txt

@@ -0,0 +1,24 @@
+Function: linear_blend
+
+--Usage--
+> linear_blend(light: image, dark: image, mask: image)
+
+Blend two images together using a third as a mask.
+On pixels the mask is white the 'light' image is used, where the mask is black the 'dark' image is used.
+For grey pixels the images are blended.
+
+The images must have the same size.
+
+--Parameters--
+! Parameter	Type			Description
+| @light@	[[type:image]]		Image for the light colores in the mask
+| @dark@	[[type:image]]		Image for the dark colores in the mask
+| @mask@	[[type:image]]		Mask image that selects between the two images
+
+--Examples--
+> masked_blend(light: "image1.png", dark: "image2.png", mask: "image3.png")  ==  [[Image]]
+<pre style="padding-top:2px;padding-bottom:2px;"> masked_blend(light: <img src="image1.png" alt='"image1.png"' style="border:1px solid black;vertical-align:middle;" />, dark: <img src="image2.png" alt='"image2.png"' style="border:1px solid black;vertical-align:middle;" />, mask: <img src="image3.png" alt='"image3.png"' style="border:1px solid black;vertical-align:middle;" />) == <img src="image_masked_blend.png" alt='"image_masked_blend.png"' style="border:1px solid black;vertical-align:middle;" /></pre>
+
+--See also--
+| [[fun:linear_blend]]		Blend two images together using a linear gradient.
+| [[fun:combine_blend]]		Blend two images together using a given [[type:combine|combining mode]].

doc/function/match.txt

@@ -2,7 +2,7 @@ Function: match
 
 --Usage--
 > match(some_string, match: regular expression)
-> match_rule(regular expression)()
+> match_rule(match:regular expression)(some_string)
 
 Does a string match the given [[type:regex|regular expression]]?
 
@@ -10,6 +10,7 @@ This function is available in [[script:rule form]].
 When the match is performed many times the rule form is more efficient, because the regular expression is only compiled once.
 
 --Parameters--
+! Parameter	Type			Description
 | @input@	[[type:string]]		String to match.
 | @match@	[[type:regex]]		Regular expression to match.
 

doc/function/number_of_items.txt

@@ -6,6 +6,7 @@ Function: number_of_items
 Returns the position of an item in a list or characters in a string.
 
 --Parameters--
+! Parameter	Type				Description
 | @in@		[[type:list]] or [[type:map]] or [[type:set]] or [[type:string]]
 		  				Object to determine the number of items of.
 		  				When it is a set, returns the number of cards.

doc/function/position.txt

@@ -8,6 +8,7 @@ The first position is @0@.
 If the item is not found in the list, returns @-1@.
 
 --Parameters--
+! Parameter	Type				Description
 | @of@		''anything''			Item to look for.
 | @in@		[[type:list]] or [[type:set]]	List to look in.
 		  				Can be a [[type:set]] when looking for a card.

doc/function/replace.txt

@@ -0,0 +1,36 @@
+Function: replace
+
+--Usage--
+> replace(some_string, match: regular expression, replace: replacement, in_context: regular expression)
+> replace_rule(match: ..., replace: ..., in_context: ...)(some_string)
+
+Replace all matches of a regular expression with a replacement value.
+The replacement can either be a string or a function.
+* The string can contain backreference @"\\0"@, @"\\1"@, etc. refering to the components captured by the parentheses in the regular expression.
+* When the replacement is a function, the variable @input@ contains the whole match and @_1@, @_2@, etc. contains the components.
+
+Optionally a context can be given. The replacement is only performed if the string where the match is represented as <tt>&lt;match></tt> also matches the context.
+
+This function is available in [[script:rule form]].
+When the replacement is performed many times the rule form is more efficient, because the regular expression is only compiled once.
+
+--Parameters--
+! Parameter	Type			Description
+| @input@	[[type:string]]		String to replace in.
+| @match@	[[type:regex]]		Regular expression to match.
+| @replace@	[[type:string]] or [[type:function]]
+		 			Replacement
+| @in_context@	[[type:regex]] (optional)	Context to match
+
+--Examples--
+> replace(match: "a", replace: "e", "banana")  ==  "benene"
+> replace(match: "a", replace: "e", in_context: "<match>n", "banana")  ==  "benena"
+> replace(match: "(a|b)x", replace: "[\\0,\\1]", "axabxc")  ==  "[ax,a]a[bx,b]c"
+> replace(match: "[ab]", replace: { to_upper(input) }, "banana")  ==  "BAnAnA"
+>
+> f := replace_rule(match: "xx+", replace: "A")
+> f("xyzxxyyzz") == "xyzAAyyzz"
+
+--See also--
+| [[fun:filter_text|filter_text / filter_rule]]
+				Keep only the text matching a regular expression.

doc/function/reverse.txt

@@ -6,6 +6,7 @@ Function: reverse
 Reverse a string.
 
 --Parameters--
+! Parameter	Type			Description
 | @input@	[[type:string]]		String to reverse.
 
 --Examples--

doc/function/sort_list.txt

@@ -7,6 +7,7 @@ Order the elements in a list in lexicographical order, from smallest to largest.
 Optionally order by some other property.
 
 --Parameters--
+! Parameter	Type			Description
 | @input@	[[type:list]] or [[type:set]]	List to sort.
 | @order_by@	[[type:function]] (optional)	Function to order by, for example when @order_by: {input.name}@ orders items by their name property.
 

doc/function/substring.txt

@@ -6,6 +6,7 @@ Function: substring
 Extract a subsection of a string.
 
 --Parameters--
+! Parameter	Type			Description
 | @input@	[[type:string]]		String to extract something from.
 | @begin@	[[type:int]] (optional)	Index of first character to keep (the first index is 0).
 		  			If ommitted, starts at the begining of the string.

doc/function/to_lower.txt

@@ -6,6 +6,7 @@ Function: to_lower
 Convert a string to lower case.
 
 --Parameters--
+! Parameter	Type			Description
 | @input@	[[type:string]]		String to convert.
 
 --Examples--

doc/function/to_title.txt

@@ -6,6 +6,7 @@ Function: to_title
 Convert a string to title case, where each words starts with an upper case leter.
 
 --Parameters--
+! Parameter	Type			Description
 | @input@	[[type:string]]		String to convert.
 
 --Examples--

doc/function/to_upper.txt

@@ -6,6 +6,7 @@ Function: to_upper
 Convert a string to upper case.
 
 --Parameters--
+! Parameter	Type			Description
 | @input@	[[type:string]]		String to convert.
 
 --Examples--

doc/function/trace.txt

@@ -6,6 +6,7 @@ Function: trace
 Output a message for debugging purposes, for example to investigate what is going on in some function.
 
 --Parameters--
+! Parameter	Type			Description
 | @input@	[[type:string]]		Message
 
 --Examples--