Documentation update

This is update of documentation draft before code implementation.

9 files changed, 180 insertions, 0 deletions

diff --git a/docs/builtin_commands.md b/docs/builtin_commands.md
new file mode 100644
index 0000000..79222ad
--- /dev/null
+++ b/docs/builtin_commands.md
@@ -0,0 +1,107 @@
+Built-in commands
+=================
+Here is full list of all build in commands including its description and sometime
+usage examples. For more information see syntax documentation.
+
+All build in commands are defined in lover case as they are presented here, but
+also in upper case. Also you can change initial character, we use here default one
+(`$`).
+
+###	$include(PATH)
+Includes file content to its place. `PATH` is system path relative to current file
+folder or absolute path.
+
+With this command you can nest any other file content and this content. Note that
+because of evaluation principles, content can be evaluated multiple times. If it
+is not what you want, common idiom would be use:
+```
+$limit(0)$include(file)$endlimit
+```
+
+### $load(...)
+This loads additional modules. sgp searches with precedence for modules in file
+directory and in paths defined by environment variable `SGPMODULES`. `NAME` is in
+such case relative path to module, but also absolute path can be used.
+
+Be aware that modules stays loaded even after current file preprocessing is
+finished. They are not unloaded automatically after return from include.
+
+For more information see module documentation.
+
+### $unload(...)
+Serves as opposite to `load` command. It is as it says unloading modules. But it
+is not paired with load.
+
+Without any argument `unload` will unload all loaded modules.
+
+### $limit(NUM)
+This command limits number of evaluation cycles for some text (see evaluation
+documentation).  After this command all text will be evaluated only `NUM` times.
+So `NUM` should be number. Passing empty string results in disabled evaluation
+until end of limit command. Default value if not limit command is used is `inf`,
+that means no limit.  Limit can be ended using `endlimit` command.
+
+Because of how limit works. Most likely you will use limit without any argument or
+with `inf`, or with `1`. Lets see once again what every one does. No argument is
+same as `0` so no evaluation is done until `endlimit` command. `inf` removes any
+limit and allows any number of nested evaluations. `1` specifies that evaluation
+should be done only once.
+
+You can nest limits together. This results to situation when content is evaluated
+limited times but some part of it that is wrapped in another limit block will be
+evaluated few times more without sucking up its root limit.
+
+### $endlimit
+This ends previous evaluation limit. Text after this command is not limited by
+that.
+
+### $"
+### $'
+This is almost same command as `$"`. It has same behavior as if you would write:
+```
+$"$limit $Text $endlimit$"
+```
+Where result would be:
+```
+ $Text 
+```
+So its also limits evaluation.
+
+### $set(VAR,VALUE)
+### $define(VAR,...)
+### $enddefine
+### $undefine(VAR)
+### $math(EQ)
+### $if(COND)
+### $ifdef(VAR)
+### $ifndef(VAR)
+### $elif(COND)
+### $else
+### $endif
+### $for(VAR,COND,EQ)
+### $endfor
+### $while(COND)
+### $endwhile
+### $switch(VAR)
+### $case(VAL)
+### $default
+### $break
+### $continue
+### $exec(EXEC,...)
+Calls executable `EXEC` with rest of arguments as arguments for executed program.
+Standard output from this program is than included to same place as `exec`.
+
+### $shell(CMD)
+This is same as exec, except that instead of defining executable and command line
+arguments separately they are defined together in `CMD` argument. In fact you can
+specify any shell command in `CMD`.
+
+### $error(TEXT)
+`TEXT` is printed to error output and spg is terminated.
+
+### $warning(TEXT)
+`TEXT` is printed to error output, but sgp continuous preprocessing text.
+
+### $info(TEXT)
+Simply prints `TEXT` to standard output. If standard output is used as output of
+result, info is printed to error output.
diff --git a/docs/evaluation.md b/docs/evaluation.md
new file mode 100644
index 0000000..04d8854
--- /dev/null
+++ b/docs/evaluation.md
@@ -0,0 +1,2 @@
+Evaluation process
+==================
diff --git a/docs/index.md b/docs/index.md
new file mode 120000
index 0000000..32d46ee
--- /dev/null
+++ b/docs/index.md
@@ -0,0 +1 @@
+../README.md
\ No newline at end of file
diff --git a/docs/module_creation.md b/docs/module_creation.md
new file mode 100644
index 0000000..e69de29
--- /dev/null
+++ b/docs/module_creation.md
diff --git a/docs/modules/array.md b/docs/modules/array.md
new file mode 120000
index 0000000..1c9ed09
--- /dev/null
+++ b/docs/modules/array.md
@@ -0,0 +1 @@
+../../modules/array/README.md
\ No newline at end of file
diff --git a/docs/modules/file.md b/docs/modules/file.md
new file mode 120000
index 0000000..82313a3
--- /dev/null
+++ b/docs/modules/file.md
@@ -0,0 +1 @@
+../../modules/file/README.md
\ No newline at end of file
diff --git a/docs/modules/protect.md b/docs/modules/protect.md
new file mode 120000
index 0000000..5a63a23
--- /dev/null
+++ b/docs/modules/protect.md
@@ -0,0 +1 @@
+../../modules/protect/README.md
\ No newline at end of file
diff --git a/docs/modules/python.md b/docs/modules/python.md
new file mode 120000
index 0000000..cdce586
--- /dev/null
+++ b/docs/modules/python.md
@@ -0,0 +1 @@
+../../modules/python/README.md
\ No newline at end of file
diff --git a/docs/syntax.md b/docs/syntax.md
new file mode 100644
index 0000000..fa00287
--- /dev/null
+++ b/docs/syntax.md
@@ -0,0 +1,66 @@
+Syntax
+======
+Syntax consist from expandable macros and commands. They are both used in code
+with initial character. In default `$`, but other can be used if specified as
+argument to program. After this character is name of macro. Names are case
+sensitive, without spaces and special character, except underscore.
+
+For example this text:
+```
+$set(VAR, Hello)$VAR World!
+```
+Is expanded to:
+```
+Hello World!
+```
+
+If you want use initial character without preprocessing, you should write it two
+times. So if our initial character is `$`, you should use `$$`.  Also you can use
+`--permissive` argument to disable error when initial character is not followed by
+known name. In such case is preprocessor treating it as it is part of text and let
+it be without change. Be aware that collisions with names can occur and no typing
+errors will be reported. Also you can limit preprocessing with `limit` command. If
+you set limit, only given number of macros and commands is expanded.
+
+Macros and commands can have arguments. Arguments are used to pass text to them.
+Every argument can be specified on multiple lines and separated from others using
+coma. All empty characters (spaces, tabulators and new lines) are removed from
+beginning and end of argument. You can enclosure argument using `$'` or `$"`, which
+will ensure that empty characters will stay in argument. But be aware that even
+when `$'` or `$"` is used macros and functions inside argument is evaluated. Another
+usage for enclosing argument to `$'` or `$"` is to ignore `)` and `,`.
+
+End of macro or command is identified by other character that is not known. Or
+bracket that is used to bound arguments to commands and macros. Or you can use `-`
+as special meaning. `-` is removed during processing which allows you to paste
+anything anywhere. For example `Without$SPACE-spaces`.
+
+Difference between macros and commands is that macros are defined in text and
+allows only simple expansion. Additional commands are defined using modules.
+At the end, commands are more versatile than macros, but requires more work to
+create.
+
+Some commands can be paired with some other commands. Common example is "if" with
+its paired commands "else", "elif" and "endif". Paired commands are defined as
+that first of them defines behavior and second one ends it or changes it for next
+text. It should newer be that second one somehow defines behavior for previous
+processed text. Also to ensure that code is contained inside file, all first
+commands allowing pairs has default ending command. If file is read to end and no
+pair is found, default end is artificially inserted. Also no paired command opened
+before including can be ended in included file.
+
+Special macros
+--------------
+These macros has special meaning. They can't be redefined, but can be overloaded
+using modules. And they are not defined in processed text.
+### SGP_VERSION
+Expands to version of sgp tool.
+### FILE
+Expands to name of file that is processed. This macro is not changing during whole
+preprocessing. Note that you can use it in included files to identify name of
+original preprocessed file.
+### LINE
+This macro is expanded always to line number on which it is specified in source
+text.
+### MODULES
+This macro specifies coma separated list of active modules.