Documentation of script functions and file types (work in progress)

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

doc/type/color.txt

@@ -0,0 +1,15 @@
+==Data type: color==
+
+--Syntax--
+In files and scritps a color can be represented as
+<pre>rgb(<i>red_component</i>, <i>green_component</i>, <i>blue_component</i>)</pre>
+where red_component, green_component and blue_component are numbers between 0 and 255 (inclusive).
+
+--Examples--
+For example:
+! Code			Represents	
+| @rgb(255,255,255)@	white, <span style="border:1px solid black; background:white;width:20px;"> </span>
+| @rgb(0,0,0)@		black, <span style="border:1px solid black; background:white;width:20px;"> </span>
+| @rgb(255,0,0)@	red,   <span style="border:1px solid black; background:red;width:20px;"> </span>
+| @rgb(0,255,0)@	green, <span style="border:1px solid black; background:green;width:20px;"> </span>
+| @rgb(0,0,255)@	blue,  <span style="border:1px solid black; background:blue;width:20px;"> </span>

doc/type/combine.txt

@@ -0,0 +1,7 @@
+==Data type: image combine type==
+
+This specifies how an image is to be combined with the background.
+This is similair to the feature found in more advanced drawing programs.
+
+--Possible values--
+| overlay

doc/type/index.txt

@@ -0,0 +1,48 @@
+Data types
+
+Magic Set Editor uses many data types in the files and in scripting.
+There are for instance [[type:card]]s in [[type:set]]s, [[type:stylesheet]]s describing the layout of [[type:field]]s, etc.
+
+--Styling trinity--
+
+--File types--
+These are the 'major' data types that are written directly to [[file:package]]s.
+| [[type:game]]		What information is on each card?
+| [[type:stylesheets]]	What do cards look like?
+| [[type:set]]		Sets of cards.
+| [[type:symbol_font]]	Fonts consisting of symbols, for instance mana symbols.
+| [[type:export_template]]	How to export sets to HTML files?
+| [[type:locale]]	Translations of MSE.
+| [[type:include]]	Files to include in other templates.
+| [[type:installer]]	Installers containing several packages.
+| [[type:symbol]]	Expansion symbols.
+| [[type:settings]]	MSE settings.
+
+--Compound types--
+These contain several properties, similair to the file types. But they are part of some other file type.
+| [[type:field]]	A field description for cards.
+| [[type:style]]	The styling and positioning of a field.
+| [[type:value]]	The value in a field, for a particular card.
+| [[type:card]]		A card containing values.
+| [[type:keyword]]	A keyword.
+| [[type:font]]		Description of a font.
+| [[type:script]]	A script to execute to update a field, or for initialization.
+| [[type:symbol_part]]	Part of a [[type:symbol]].
+
+--Collection types--
+| [[type:list]]		Lists of items
+			* item
+			* item
+			* item
+| [[type:indexmap|'index' map]]	Lists indexed by field name
+			<table><tr><td>name:</td><td>someone</td></tr>
+			<tr><td>type:</td><td>something</td></tr></table>
+| [[type:map]]		Lists indexed by other text
+
+--Primitive types--
+| [[type:string]]	Text, @"abc"@
+| [[type:int]]		Integer numbers, @1, 2, 100@
+| [[type:double]]	Real numbers, @1, 0.5, 21.3@
+| [[type:color]]	Colors
+| [[type:scriptable]]	A primitive type whose value can depend on a script.
+| [[type:function]]	Functions in scripts. These have no direct representation in a file.

doc/type/list.txt

@@ -0,0 +1,28 @@
+Data type: Lists
+
+--File syntax--
+In files a list is represented as multiple keys, one for each element.
+The keys are all in the singular for of the name of the list,
+if the list is named for instance @symbols@ each key will be named @symbol@.
+] symbol:
+]	# first symbol here
+] symbol:
+]	# second symbol here
+] # etc.
+
+--Script syntax--
+In a script lists can be declared using square brackets.
+> []    # An empty list
+> [1]   # A list with a single element, the value 1
+> [1,2] # A list with two elements
+
+Lists can be accessed using either the bracket operator, or the dot operator.
+The first element of a list is numbered 0, the next 1, etc.
+> list.0  # The first element of the list 'list'
+> list[0] # The same thing
+
+There are several functions for working with lists:
+| [[fun:position]]		Find the position of an element in a list
+| [[fun:number_of_items]]	Find the number of items in a list
+| [[fun:sort_list]]		Sort a list
+| [[fun:filter_list]]		Filter a list, keeping only elements that match a predicate

doc/type/set.txt

@@ -0,0 +1,85 @@
+==Object type: Set==
+
+--Package--
+A set is described in a package with the <tt>.mse-set</tt> file extension,
+such a package contains a data file called <tt>set</tt>.
+
+--Properties--
+| game		Name of a [[type:game]]			The game this set is made for.
+| stylesheet	Name of a [[type:stylesheet]]		The default style for drawing cards in this set.
+| set info	[[type:indexmap]] of [[type:value]]s	The data for the [[prop:game:set fields]] defined in the game.
+| styling	[[type:indexmap]] of [[type:value]]s	
+| cards		[[type:list] of [[type:card]]s		The cards in the set.
+
+--Example--
+
+|-
+| <tt>set info:</tt>
+| Contains custom information about the set, corresponding to the <tt>set field</tt>s in the game.
+|-
+| <tt>extra set info:</tt>
+| Contains information about the set for a specific style, corresponding to the <tt>extra field</tt>s in the style. <br>
+  Stored with an index for the game, see the example below.
+|-
+| <tt>card:<br>card:<br><i>...</i></tt>
+| Contains information about each card, corresponding to the <tt>card field</tt>s in the game.
+|-
+| <tt>keyword:<br>keyword:<br><i>...</i></tt>
+| Extra keywords specific to this set, in addition to those defined in the game. 
+  For more information see the <a href="/extending/game">game file</a>
+|}
+
+The <tt>set info</tt> and <tt>card</tt>s contain a list of keys that correspond to the names fields in the game,
+For example if the game looks like:
+ name: my game
+ set field:
+ 	name: copyright
+ 	type: text
+ card field:
+ 	name: card name
+ 	type: text
+ card field:
+ 	name: power
+ 	type: text
+
+The the set file looks like:
+ game: my game
+ name: my set
+ set info:
+ 	copyright: something
+ extra set info:
+ 	name-of-style:
+ 		name-of-field: something
+ card:
+ 	card name: first card
+ 	power: 100
+ card:
+ 	card name: second card
+ 	power: 50
+
+
+The value that is stored depends on the type of field of course, in the above example the fields have <tt>type: text</tt>, so the value is just the text.
+For other types of fields the value is encoded as follows:
+{|
+! Attribute !! Description
+|-
+| <tt>text</tt>
+| The text that is stored in the field. This text can contain <a href="/extending/tags">tags</a>.
+|-
+| <tt>choice</tt>
+| One of the choices specified in the game.
+|-
+| <tt>boolean</tt>
+| One of <tt>yes</tt> or <tt>no</tt>.
+|-
+| <tt>color</tt>
+| The color is encoded as <tt>rgb(red,green,blue)</tt> where red, green and blue are numbers between 0 and 255 that indicate the color components.
+|-
+| <tt>image</tt>
+| The filename containing the image, this file must also be in the set package. It can be empty to indicate that no image is selected.
+|-
+| <tt>symbol</tt>
+| The filename containing the <a href="/extending/symbol">symbol specification</a>, this file must also be in the set package.
+  It can be empty to indicate that no symbol is selected.
+|}
+If a field has the default value (calculated by the default script), then the field name and value are ommited from the set file.

doc/type/string.txt

@@ -0,0 +1,5 @@
+==Data type: character string==
+
+--File syntax--
+
+--Script syntax--

doc/type/stylesheet.txt

@@ -0,0 +1,12 @@
+Object type: Stylesheet
+
+--Properties--
+| @game@		Name of a [[type:game]]			Game this stylesheet is made for
+| @init script@		[[type:script]]				
+| @card width@		[[type:double]]				Width of cards in pixels
+| @card height@		[[type:double]]				Height of cards in pixels
+| @card dpi@		[[type:double]]				Resoltion of cards in dots-per-inch
+| @card background@	[[type:color]]				Background color of cards
+| @card style@		[[type:indexmap] of [[type:style]]s	Styles for the [[property:game:card fields]] defined in the game
+| 
+

doc/type/tagged_string.txt

@@ -0,0 +1,37 @@
+==Data type: string with tags==
+
+--Syntax--
+&1;
+
+--Basic markup--
+! Tag		Description
+| <b>		The text inside the tag is bold.
+| <i>		The text inside the tag is italic.
+| <sym>		The text inside the tag is rendered as symbols, if a [[prop:style:symbol font]] is set for the text box.
+| <line>	Line breaks inside this tag use the [[prop:style:line height line]], and they show a horizontal line.
+| <soft-line>	Line breaks inside this tag use the [[prop:style:soft line height]].
+| <atom>	An atomic piece of text. The cursor can never be inside it; it is selected as a whole.
+		The program automatically inserts <atom-soft>
+| <code>	The text inside the text is rendered in a monospace font. This is used for syntax highlighting script code.
+| <code-kw>	The text inside the text is highlighted as a keyword in source code.
+| <code-str>	The text inside the text is highlighted as a string in source code.
+
+
+--Other tags--
+! Tag		Description
+| <kw-?>	Indicates that the text inside it is a keyword. This tag is automatically inserted by
+		The [[fun:expand_keywords] function. There are four versions, indicating whether or not reminder text is shown
+		| <kw-0>	Reminder text hidden, by default
+		| <kw-1>	Reminder text shown, by default
+		| <kw-a>	Remder hidden manually
+		| <kw-A>	Remder shown manually
+| <sep>		A separator between fields. This tag is automatically inserted by the [[fun:combined_editor]] function.
+		Inserting this tag manually will confuse that function!
+		This tag can never be selected, and its contents can not be edited.
+| <sep-soft>	Like &lt;sep>, only hidden. This is inserted by [[fun:combined_editor]]
+		...
+| any other tag	Other tags are ignored.
+
+--Related functions--
+The following script functions deal with tags:
+| [[fun:remove_tag]]

doc/type/value.txt

@@ -0,0 +1 @@
+== Object type: Field value ==