Documentation of keyword functions, changes sort_text function

doc/function/drop_shadow.txt

@@ -5,6 +5,10 @@ Function: drop_shadow
 
 Add a drop shadow to an image.
 
+The shadow is based on the opacity of the image.
+
+To make sure the shadow doesn't fall outside the image, it can be a good idea to [[fun:enlarge]] the image first.
+
 --Parameters--
 ! Parameter	Type			Default	Description
 | @input@	[[type:image]]		 	Image to add drop shadow to
@@ -12,9 +16,9 @@ Add a drop shadow to an image.
 		 			 	Value is in the range 0 (no movement) to 1 (move by the width of the image)
 | @offset_y@	[[type:double]]		0	Relative position of the shadow, a positive number moves the shadow down.<br />
 		 			 	Value is in the range 0 (no movement) to 1 (move by the height of the image)
-| @blur_radius@	[[type:double]]		0	Amount to blur
+| @blur_radius@	[[type:double]]		0	Amount to blur the shadow.
 | @alpha@	[[type:double]]		0	Opacity of the shadow, in the range 0 (fully transparent) to 1 (fully opaque)
-| @color@	[[type:color]]		black	Color of the shadow
+| @color@	[[type:color]]		black	Color of the shadow.
 
 --Examples--
 > drop_shadow("image4.png", offset_x: 0.08, offset_y: 0.08, alpha: 0.5)  ==  [[Image]]

doc/function/expand_keywords.txt

+Function: expand_keywords
+
+--Usage--
+> expand_keywords(some_tagged_string, default_expand: {...}, combine: {...})
+> expand_keywords_rule(default_expand: {...}, combine: {...})(some_tagged_string)
+
+Find [[type:keyword]]s and generate their reminder text.
+
+The string is searched for keywords, when one is found its reminder text is generated.
+This is done by calling @keyword.reminder(param1:.., param2:..., ...)@.
+Where the @param@s are the matching keyword parameters.
+
+The it is determined whether the reminder text should be shown.
+This is either because the user explicitly selected it, or when @default_expand(mode: keyword.mode)@ returns true.
+Whether reminder text is shown is stored in a @<kw->@ tag around the keyword.
+! Tag		Reminder text		Changed by user
+| @"<kw-a>"@	hidden			no
+| @"<kw-A>"@	shown			no
+| @"<kw-0>"@	hidden			yes
+| @"<kw-1>"@	shown			yes
+
+If the reminder text is shown the function @combine@ is called which should combine the reminder text with (in the variable @reminder@) with the keyword and its parameters (in the variable @keyword@).
+
+For example, in the case of magic:
+> expand_keywords(
+>   default_expand: { set.automatic_reminder_text }
+>   combine:        { "{keyword}<atom-reminder-{mode}> ({reminder})</atom-reminder-{mode}>" }
+> )
+is used. This shows reminder text by default based on a [[type:set]] option, and it combined the keyword as @"keyword (reminder)"@.
+
+This function is available in [[script:rule form]].
+
+--Parameters--
+! Parameter		Type				Description
+| @input@		[[type:tagged string]]		String to expand keywords in.
+| @default_expand@	[[type:function]]		Should reminder text be shown by default?
+| @combine@		[[type:function]]		How to combine keywords with the reminder text?
+
+--Examples--
+Assuming a keyword @"mse"@ exists with reminder text @"Magic Set Editor"@ exists.
+> expand_keywords(default_expand: {true}, combine: { keyword + " = " + reminder },  "mse is cool")
+>    == "<kw-A>mse = Magic Set Editor is cool</kw-A>"
+>
+> f := expand_keywords_rule(default_expand: {true}, combine: { keyword+"="+reminder })
+> f("mse is cool") == "<kw-A>mse = Magic Set Editor is cool</kw-A>"

doc/function/keyword_usage.txt

+Function: keyword_usage
+
+--Usage--
+> keyword_usage(card: some_card)
+
+Returns a comma separated list of the keywords that appear on the card.
+
+For example if a card contains the keywords "Flying" and "Haste" the function will return @"Flying, Haste"@.
+
+If a keyword appears multiple times on the card it will also appear multiple times in the output, unless @unique@ is specified.
+
+--Parameters--
+! Parameter	Type				Description
+| @card@	[[type:card]]			Card to find keywords on.
+| @unique@	[[type:boolean]] (optional)	Return each keyword at most once.
+
+--Examples--
+> keyword_usage(card: some_card, unique: false) == "Flying, Flying, Haste"
+> keyword_usage(card: some_card, unique: true)  == "Flying, Haste"

doc/function/sort_text.txt

@@ -10,14 +10,36 @@ When the @order@ parameter is not given, the input is sorted in alphabetical ord
 
 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
+Parts
+! Part			<tt>sort("zzyyxxy")</tt>	Description
 | @"x"@			@"xx"@			A normal character, selects all matching characters from the input
+| @" "@			@""@			Whitespace is ignored.
+| @"\\<"@		@""@			Characters can be escaped with a backslash, normally the character @"<"@ has special behaviour.
+			 			Note that you also need to escape the backslash for the [[type:string]].
 | @"<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.
+| @"[wxy]"@		@"yyyxx"@		Selects the given characters, but keep them in the same order as in the input.
+| @"ordered(wxy)"@	@"xxyyy"@		The same as just @"wxy"@.
+| @"once(wxy)"@		@"xy"@			The same as @"<wxy>"@.
+| @"mixed(wxy)"@		@"yyyxx"@		The same as @"[wxy]"@.
+| @"compound(yx)"@	@"yx"@			Selects the literal substring @"xy"@ only where it matches exactly. Selects it as many times as it appears
+| @"any()"@		@"zzyyxxy"@		Selects the remaining part of the input.
+| @"cycle(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.
+| @"reverse_order(x y)"@	@"yyyxx"@	Inside the parentheses can be multiple parts (that can again include part-functions).
+			 			@"reverse_order(x y)"@ is ''not'' the same as just @"y x"@, because in the first case x is evaluated first.
+			 			For example @"x compound(xy)"@ doesn't work, because the xs are all matched by the time the compound part is evaluated.
+			 			So instead you can use @"reverse_order(compound(xy) x)"@.
+| @"pattern(.z. xyz)"@	@"yzz"@			Selects all things that match the pattern, where @"."@ is a wildcard.
+			 			The things matching the wildcards are then sorted using the given pattern (separated by a space), and subsituted back in.
+			 			So in <tt>"zzyyxxy"</tt> the pattern matches <tt>"<b>zzy</b>xxy"</tt> with wildcards <tt>"zy"</tt> these sort as <tt>"yz"</tt> and in the pattern this becomes <tt>"yzz"</tt>.
+
+The parts are read from left to right, each part that matches something removes it from the input, so for example
+> sort_text(order: "xx")
+behaves the same as
+> sort_text(order: "x")
+because the first @"x"@ already selects all xs from the input.
 
 This function is available in [[script:rule form]].
 
@@ -29,9 +51,17 @@ This function is available in [[script:rule form]].
 --Examples--
 > sort_text("banana")                                      ==  "aaabnn"
 > sort_text(order: "na",                        "banana")  ==  "nnaaa"
+> sort_text(order: "n a",                       "banana")  ==  "nnaaa"
 > sort_text(order: "<na>",                      "banana")  ==  "na"
+> sort_text(order: "once(na)",                  "banana")  ==  "na"
 > sort_text(order: "[na]",                      "banana")  ==  "anana"
-> sort_text(order: "[1234567890](wubrg)", "21wg")  ==  "21gw"
+> sort_text(order: "mixed(na)",                 "banana")  ==  "anana"
+> sort_text(order: "compound(na)",              "banana")  ==  "nana"
+> sort_text(order: "reverse_order(na)",         "banana")  ==  "aaann"
+> sort_text(order: "a n <a>",                   "banana")  ==  "aaann"
+> sort_text(order: "reverse_order(<a> n a)",    "banana")  ==  "aanna"
+> sort_text(order: "pattern(./. cycle(wubrg))", "wgw/g")   ==  "g/w"
+> sort_text(order: "[1234567890]cycle(wubrg)",  "21wg")    ==  "21gw"
 >
-> f := sort_rule(order: "[1234567890](wubrg)")
+> f := sort_rule(order: "[1234567890]cycle(wubrg)")
 > f("21wg")  ==  "21gw"