modified leveleditor documentation

[chaz/carfire] / CarFire / leveleditor / doc / leveleditor.txt

diff --git a/CarFire/leveleditor/doc/leveleditor.txt b/CarFire/leveleditor/doc/leveleditor.txt
index 46cfb6392ab89f364ace8046390aedb5fffd590e..377cbf95125457319b27a501c7a3b5d17780649e 100644 (file)
--- a/CarFire/leveleditor/doc/leveleditor.txt
+++ b/CarFire/leveleditor/doc/leveleditor.txt
@@ -33,10 +33,15 @@ vim directory; usually:
     $HOME/.vim/doc or\r
     $HOME/vimfiles/doc\r
 \r
     $HOME/.vim/doc or\r
     $HOME/vimfiles/doc\r
 \r

-You're done!  To use the level editor without installing the plugin, just\r
-|source| the plugin in vim:\r
+Alternatively, you can use the level editor without installing the plugin,\r
+just |source| the plugin in vim:\r

 \r
 \r

-    :source path/to/leveleditor.vim\r
+    :so /path/to/leveleditor.vim\r
+\r
+Or setup Vim to do it automagically with |:autocmd|; put this in your user\r
+Vim config file:\r
+\r
+    au BufNewFile,BufRead *.cfmap so /path/to/leveleditor.vim\r

 \r
 ===========================================================================\r
 3. Features                                          *leveleditor-features*\r
 \r
 ===========================================================================\r
 3. Features                                          *leveleditor-features*\r


@@ -68,6 +73,9 @@ A. Map File Format                                 *leveleditor-fileformat*
 \r
 The format of the CarFire map file follows the de facto standard INI file\r
 format, with at least one notable exception which we'll get to shortly.\r
 \r
 The format of the CarFire map file follows the de facto standard INI file\r
 format, with at least one notable exception which we'll get to shortly.\r

+Because of that exception, a specialized loader is necessary, so map files\r
+should carry the extension `cfmap' so as not to have them be mistook as\r
+your everyday household variety INI file.\r

 \r
                                                      *leveleditor-metadata*\r
 The metadata section of the file contains just that: metadata.  Some of the\r
 \r
                                                      *leveleditor-metadata*\r
 The metadata section of the file contains just that: metadata.  Some of the\r


@@ -114,27 +122,34 @@ B. Basic Syntax                                        *leveleditor-syntax*
 \r
 To make parsing simple, the format of the values that make up a key-value\r
 pair follows a consistent pattern based on the type of thing being\r
 \r
 To make parsing simple, the format of the values that make up a key-value\r
 pair follows a consistent pattern based on the type of thing being\r

-described.  Here are the things that can appear on the right side of a\r
-key-value pair assignment:\r
+described.  Except in the case of strings, white space is ignored.  Here\r
+are the things that can appear in a map file.\r
+\r
+                                                         *leveleditor-keys*\r
+Keys are special strings that appear on the left side of a key-value pair,\r
+which combined is a key and value separated by an equals sign.  Keys are\r
+simply a sequence of alphabet characters.  No white space, digits, or\r
+punctuation is allowed in a key.\r

 \r
                                                       *leveleditor-strings*\r
 Strings are simply a sequence of characters.  If the key expects to be set\r
 to a string, then the right side of the assignment up to the line-end will\r
 be parsed as a string, including any white space.  If a string value is not\r
 \r
                                                       *leveleditor-strings*\r
 Strings are simply a sequence of characters.  If the key expects to be set\r
 to a string, then the right side of the assignment up to the line-end will\r
 be parsed as a string, including any white space.  If a string value is not\r

-necessarily expected, you can explicitly surround the string with quotes;\r
-otherwise, the value could be interpreted as a list if it contains any\r
-white space.\r
+necessarily expected, you can explicitly surround the string with double\r
+quotes; otherwise, the value could be interpreted as a list if it contains\r
+any white space.  The characters given as a string are interpreted as-is.\r
+No escape characters are ever parsed (i.e. \t or \n).\r

 \r
 \r

-The characters that make up the string are included in the string according\r
-to their literal characters; no escape characters are ever parsed (i.e. \t\r
-or \n).  Any value which does not follow any of the following formats will\r
-be read as a string.\r
-\r
-                                                      *leveleditor-numbers*\r
+                                                     *leveleditor-integers*\r

 Base-ten numbers are parsed as they appear.  The parser is allowed to read\r
 numbers with special characters such as -10e5.  Numbers cannot be specified\r
 in any other base than ten.\r
 \r
 Base-ten numbers are parsed as they appear.  The parser is allowed to read\r
 numbers with special characters such as -10e5.  Numbers cannot be specified\r
 in any other base than ten.\r
 \r

+                                                     *leveleditor-booleans*\r
+Boolean values are one of two keywords: `true' and `false.'  Case is\r
+ignored when parsing booleans, but abbreviations are not allowed.  For\r
+example, `TrUe' is okay, but `T' is not.\r
+\r

                                                   *leveleditor-coordinates*\r
 To specify a coordinate or location on the map, surround two\r
 comma-separated integers with square brackets.  For example,\r
                                                   *leveleditor-coordinates*\r
 To specify a coordinate or location on the map, surround two\r
 comma-separated integers with square brackets.  For example,\r


@@ -150,7 +165,7 @@ you go down.
 A range of integer values is parsed as two comma-separated integers with\r
 angular brackets.  For example,\r
 \r
 A range of integer values is parsed as two comma-separated integers with\r
 angular brackets.  For example,\r
 \r

-    <1-4>       Matches any integer between 1 and 4, inclusive.\r
+    <1,4>       Matches any integer between 1 and 4, inclusive.\r

 \r
 In this way, you could set a range as the value for the key `numplayers' in\r
 the |leveleditor-metadata| section, representing the minimum and maximum\r
 \r
 In this way, you could set a range as the value for the key `numplayers' in\r
 the |leveleditor-metadata| section, representing the minimum and maximum\r


@@ -159,16 +174,12 @@ number of players the map supports.
                                                     *leveleditor-functions*\r
 The syntax of a function call is familiar.  First comes the name of the\r
 function to be called, then an open parenthesis, followed by a\r
                                                     *leveleditor-functions*\r
 The syntax of a function call is familiar.  First comes the name of the\r
 function to be called, then an open parenthesis, followed by a\r

-comma-separated list of arguments before a closing parenthesis.  For\r
-example,\r
+whitespace-separated (no commas!) list of arguments before a closing\r
+parenthesis.  For example,\r

 \r
     wait(3)             Delay for 3 seconds.\r
     has(F)              Check if a player has an entity F in inventory.\r
 \r
     wait(3)             Delay for 3 seconds.\r
     has(F)              Check if a player has an entity F in inventory.\r

-    create(B,[2,3])     Create an entity B on the map at [2,3].\r
-\r
-Note, the file loader parses each group of characters between white space\r
-separately; therefore, do not include spaces between the arguments of the\r
-function call, only a single comma.\r
+    create(B [2,3])     Create an entity B on the map at [2,3].\r

 \r
                                                         *leveleditor-lists*\r
 Some keys can be assigned a list of things, such as functions to be called\r
 \r
                                                         *leveleditor-lists*\r
 Some keys can be assigned a list of things, such as functions to be called\r