Continuing documenting functions

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

doc/function/combine_blend.txt

@@ -15,7 +15,7 @@ The images must have the same size.
 
 --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>
+>>> combine_blend(image1: <img src="image1.png" alt='"image1.png"' style="border:1px solid black;vertical-align:middle;margin:1px;" />, image2: <img src="image2.png" alt='"image2.png"' style="border:1px solid black;vertical-align:middle;margin:1px;" />, combine: "add") == <img src="image_combine_blend.png" alt='"image_combine_blend.png"' style="border:1px solid black;vertical-align:middle;margin:1px;" />
 
 --See also--
 | [[fun:linear_blend]]		Blend two images together using a linear gradient.

doc/function/curly_quotes.txt

@@ -0,0 +1,17 @@
+Function: curly_quotes
+
+--Usage--
+> curly_quotes(some_tagged_string)
+
+Make quotes 'curly'.
+Single and double quotation marks are changed to opening or closing versions depending on where they appear in the text.
+
+--Parameters--
+! Parameter	Type			Description
+| @input@	[[type:tagged string]]	String to make quotes curly in.
+
+--Examples--
+>>> curly_quotes("He said: 'This is cool!', she said: \"No way!\" ")
+>>>   ==  "He said: ‘This is cool!’, she said: “No way!” "
+>>> curly_quotes("Also: ’Wrong quotes‘ ")
+>>>   ==  "Also: ‘Wrong quotes’ "

doc/function/enlarge.txt

@@ -0,0 +1,16 @@
+Function: enlarge
+
+--Usage--
+> enlarge(input: image, border_size: amount_to_enlarge)
+
+Enlarge an image by putting a transparent border around it.
+The border size is given in percentages of the image size, so @border_size: 1@ makes the image three times as large by putting a border of 100% the size on all sides.
+
+--Parameters--
+! Parameter	Type			Description
+| @input@	[[type:image]]		Image to enlarge
+| @border_size@	[[type:double]]		Amount of border to add
+
+--Examples--
+> enlarge(input: "image1.png", border_size: 0.1)  ==  [[Image]]
+>>> enlarge(light: <img src="image1.png" alt='"image1.png"' style="border:1px solid black;vertical-align:middle;margin:1px;" />, border_size: 0.1) == <img src="image_enlarge.png" alt='"image_enlarge.png"' style="border:1px solid black;vertical-align:middle;margin:1px;" />

doc/function/linear_blend.txt

@@ -9,6 +9,9 @@ Function: linear_blend
 
 Blend two images together using a linear gradient.
 
+Coordinates range from 0 to 1, where 0 is the top and the left, and 1 is the right and the bottom.
+So for example a blend from @x1:0, y1:0@ to @x2:0, y2:1@ is from top to bottom.
+
 The images must have the same size.
 
 --Parameters--
@@ -20,8 +23,8 @@ The images must have the same size.
 
 --Examples--
 This gives a vertical gradient:
-> linear_blend(image1: "image1.png", image2: "image2.png", x1:0, y1:0, x2:1, y2:1)  ==  [[Image]]
+> linear_blend(image1: "image1.png", image2: "image2.png", x1:0, y1:0, x2:0, 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>
+>>> linear_blend(image1: <img src="image1.png" alt='"image1.png"' style="border:1px solid black;vertical-align:middle;margin:1px;" />, image2: <img src="image2.png" alt='"image2.png"' style="border:1px solid black;vertical-align:middle;margin:1px;" />, 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;margin:1px;" />
 
 --See also--
 | [[fun:masked_blend]]		Blend two images together using a third mask image.

doc/function/masked_blend.txt

@@ -17,7 +17,7 @@ The images must have the same size.
 
 --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>
+>>> masked_blend(light: <img src="image1.png" alt='"image1.png"' style="border:1px solid black;vertical-align:middle;margin:1px;" />, dark: <img src="image2.png" alt='"image2.png"' style="border:1px solid black;vertical-align:middle;margin:1px;" />, mask: <img src="image3.png" alt='"image3.png"' style="border:1px solid black;vertical-align:middle;margin:1px;" />) == <img src="image_masked_blend.png" alt='"image_masked_blend.png"' style="border:1px solid black;vertical-align:middle;margin:1px;" />
 
 --See also--
 | [[fun:linear_blend]]		Blend two images together using a linear gradient.

doc/function/remove_tag.txt

@@ -0,0 +1,28 @@
+Function: remove_tag
+
+--Usage--
+> remove_tag(tag: some_tag, some_string)
+> tag_remove_rule(tag: some_tag)(some_string)
+
+Remove a tag and its matching close tag from a [[type:tagged string]], but keep the contents.
+
+The tag can be a whole tag, @"<tag>"@, or a prefix @"<i"@. In the latter case all tags starting with @"<i"@ are removed.
+
+This function is available in [[script:rule form]].
+
+--Parameters--
+! Parameter	Type			Description
+| @tag@		[[type:string]]		Tag to remove
+| @input@	[[type:tagged string]]	String to remove tags from
+
+--Examples--
+> remove_tag(tag: "<b>", "<b>bold <i>text</i></b>")  ==  "bold <i>text</i>"
+> remove_tag(tag: "<b", "<b-auto>bold</b-auto> text")  ==  "bold text"
+>
+> f := tag_remove_rule(tag: "<i-auto>")
+> f("text, <i-auto>reminder</i-auto> <i>italic</i>") == "text, reminder <i>italic</i>"
+
+--See also--
+| [[fun:tag_contents|tag_contents / tag_contents_rule]]
+				Change the contents of a specific tag.
+| [[fun:to_text]]		Remove all tags from tagged text.

doc/function/set_alpha.txt

@@ -0,0 +1,21 @@
+Function: set_alpha
+
+--Usage--
+> set_alpha(image: image, alpha: transparency value)
+
+Make an image more transparent.
+
+The transprarency is multiplied by @alpha@.
+If @alpha@ is 1 the image stays the same, if @alpha@ is 0 the image becomes completely transprent.
+
+--Parameters--
+! Parameter	Type			Description
+| @image@	[[type:image]]		Image to make transparent.
+| @alpha@	[[type:double]]		Transparency factor.
+
+--Examples--
+> set_alpha(image: "image1.png", alpha: 0.5)  ==  [[Image]]
+>>> set_mask(image: <img src="image1.png" alt='"image1.png"' style="border:1px solid black;vertical-align:middle;margin:1px;" />, alpha: 0.5) == <img src="image_set_alpha.png" alt='"image_set_alpha.png"' style="border:1px solid black;vertical-align:middle;margin:1px;" />
+
+--See also--
+| [[fun:set_mask]]		Set the transparancy mask of an image.

doc/function/set_combine.txt

@@ -0,0 +1,17 @@
+Function: set_combine
+
+--Usage--
+> set_combine(input: image, combine: combine_mode)
+
+Set how the resulting image should be combined with the background.
+
+--Parameters--
+! Parameter	Type			Description
+| @input@	[[type:image]]		Image to change combining mode of
+| @combine@	[[type:combine]]	Combining function to use
+
+--Examples--
+> set_combine(input: "image1.png", combine: "shadow")  ==  [[Image]]
+
+--See also--
+| [[fun:combine_blend]]		Blend two images together using a given [[type:combine|combining mode]].

doc/function/set_mask.txt

@@ -0,0 +1,21 @@
+Function: set_mask
+
+--Usage--
+> set_mask(image: image, mask: mask_image)
+
+Make parts of an image (more) transparent using a mask.
+Black areas in the mask make the image transparent, white areas stay opaque.
+
+The images must have the same size.
+
+--Parameters--
+! Parameter	Type			Description
+| @image@	[[type:image]]		Image to apply the mask to
+| @mask@	[[type:image]]		Mask image.
+
+--Examples--
+> set_mask(image: "image1.png", mask: "image3.png")  ==  [[Image]]
+>>> set_mask(image: <img src="image1.png" alt='"image1.png"' style="border:1px solid black;vertical-align:middle;margin:1px;" />, mask: <img src="image3.png" alt='"image3.png"' style="border:1px solid black;vertical-align:middle;margin:1px;" />) == <img src="image_set_mask.png" alt='"image_set_mask.png"' style="border:1px solid black;vertical-align:middle;margin:1px;" />
+
+--See also--
+| [[fun:set_alpha]]		Change the transparency of an image.

doc/function/sort_text.txt

@@ -0,0 +1,37 @@
+Function: sort_text
+
+--Usage--
+> sort_text(order: order specification, some_text)
+> sort_rule(order: order specification)(some_text)
+
+Sort a string or filter it by keeping specific characters.
+
+When the @order@ parameter is not given, the input is sorted in alphabetical order.
+
+Otherwise the @order@ parameter determines what characters to show in the output.
+The @order@ is a string consisting of multiple ''parts'', each part selects a specific thing from the input.
+! Part		<tt>sort("zzyyxx")</tt>	Description
+| @"x"@		@"xx"@			A normal character, selects all matching characters from the input
+| @"<wxy>"@	@"xy"@			Selects the characters from the input, but only once.
+		 			@"<xy>"@ is the same as @"<x><y>"@.
+| @"[wxy]"@	@"yyxx"@		Selects the given characters, but keep them in the same order as in the input.
+| @"(xwz)"@	@"zzxx"@		Selects the given characters, and put them in the order that minimizes the distance.
+		 			around a 'circle'. Imagine w x and y in a circle, then "zx" is shorter then "x.z" because the latter passes the "w" space.
+		 			This sorting option is used to sort colored mana symbols in Magic.
+
+This function is available in [[script:rule form]].
+
+--Parameters--
+! Parameter	Type				Description
+| @input@	[[type:string]]			Text to sort
+| @order@	[[type:string]] (optional)	Order specification
+
+--Examples--
+> sort_text("banana")                 ==  "aaabnn"
+> sort_text(order: "na",   "banana")  ==  "nnaaa"
+> sort_text(order: "<na>", "banana")  ==  "na"
+> sort_text(order: "[na]", "banana")  ==  "anana"
+> sort_text(order: "[1234567890](wubrg)", "21wg")  ==  "21gw"
+>
+> f := sort_rule(order: "[1234567890](wubrg)")
+> f("21wg")  ==  "21gw"

doc/function/tag_contents.txt

@@ -0,0 +1,31 @@
+Function: tag_contents
+
+--Usage--
+> tag_contents(tag: some_tag, contents: some_function, some_string)
+> tag_contents_rule(tag: some_tag, contents: some_function)(some_string)
+
+Apply a function to the contents of a particular tag.
+The function is called with @input@ set to the old value inside the tag.
+
+The tag can be a whole tag, @"<tag>"@, or a prefix @"<i"@. In the latter case all tags starting with @"<i"@ are removed.
+
+This function is available in [[script:rule form]].
+
+--Parameters--
+! Parameter	Type			Description
+| @tag@		[[type:string]]		Tag to match
+| @contents@	[[type:function]]	Function to apply to the contents
+| @input@	[[type:tagged string]]	String to change
+
+--Examples--
+> tag_contents(tag: "<up>", contents: to_upper, "this <up>is text</up>")
+>     ==  "this <up>IS TEXT</up>"
+> tag_contents(tag: "<atom-name", contents: { card.name }, "<atom-name-auto></atom-name-auto> loses 1 life")
+>   ==  "<atom-name-auto>Pink Elephant</atom-name-auto> loses 1 life"
+>
+> f := tag_contents_rule(tag: "<i>", contents: {""})
+> f("text, <i-auto>reminder</i-auto> <i>italic</i>") == "text, <i-auto>reminder</i-auto> <i></i>"
+
+--See also--
+| [[fun:remove_tag|remove_tag / tag_remove_rule]]
+				Remove a tag, keep the contents.