Documentation of keyword functions, changes sort_text function

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

doc/function/expand_keywords.txt

@@ -0,0 +1,45 @@
+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>"