File	Date	Author	Commit
data	2010-07-18	Eugene A. Shatokhin	[6d9522] Prepared README for the repository; added "mist...
mist_engine	2010-07-18	Eugene A. Shatokhin	[6d9522] Prepared README for the repository; added "mist...
src	2010-07-18	Eugene A. Shatokhin	[6d9522] Prepared README for the repository; added "mist...
templates	2010-07-18	Eugene A. Shatokhin	[6d9522] Prepared README for the repository; added "mist...
README	2010-07-18	Eugene A. Shatokhin	[6d9522] Prepared README for the repository; added "mist...
makefile.linux	2010-07-18	Eugene A. Shatokhin	[6d9522] Prepared README for the repository; added "mist...
makefile.win32	2010-07-18	Eugene A. Shatokhin	[6d9522] Prepared README for the repository; added "mist...

Read Me

The "mist_gen" example uses MiST Engine to generate different types of 
documents from the same data but different templates.
========================================================================

The example should be build with GCC 4.x. On Windows, it is recommended to
use MinGW for GCC C++ compiler and for GNU Make tool.

[NB] The sources of MiST Engine 1.0.0 are included in this example for 
convenience, see src/mist_engine directory. Note that they are only used 
to build the example on Linux (you do not need to build them manually anyway
as the makefile handles this). During the build, MiST Engine library will be
built and installed locally to 'mist_engine' subdirectory in the example's 
main directory.

On Windows, the easiest way is to use the pre-built MiST Engine package 
available from http://template2code.sourceforge.net. Just unpack the archive
to 'mist_engine' subdirectory in the example's main directory. After that, 
the subdirectory should contain at least 'include' and 'lib' subdirectories
with the appropriate header files and libraries.

[Build]
To build the example, execute

        make -f makefile.linux 

on Linux or

        mingw32-make -f makefile.win32

on Microsoft Windows.

[Run]
To run the example, execute 

        ./mist_gen templates/source_file data/data.txt > result.c

on Linux or

        mist_gen.exe templates\source_file data\data.txt > result.c

on Microsoft Windows.

[Try it out]
When you use "source_file" set of templates, a C source file will be 
generated from the data in data.txt file.
You can try to use a different set of templates, to generate a document in 
a different format from the same data.

Two more sets of templates are distributed with the example:
- "html_table" (templates/html_table) allows to create a html page with a 
    table filled with the data;
- "text_report" (templates/some_report) allows to create a plain text 
    "report" including the data.

[How it works]
The resulting document is always organized as follows. It may have head
and/or tail parts and it has a sequence of blocks inbetween, probably with 
some separators. 

A grammar could look like this:

Document :=
        DocumentHead ?
        (Block (Separator Block)*) ?
        DocumentTail ?

Each block is generated from "block" template group (see templates/*/block).
Please refer to MiST Engine manual at http://template2code.sourceforge.net 
for details on the template-based document generation.

[NB] In this example, both "block" and "document" template groups do not use
.cfg files because it is not necessary to generate the path to the created 
document. In addition, the begin and end markers recognized in the templates
are hard-coded as "<$" and "$>" (without quotes), respectively.

Each block is generated using the parameters specified in the appropriate 
"[group]" section of the data file (see data/data.txt).

The value of each block is set as the value of <$block$> parameter for the 
"document" template group. After each block has been generated by MiST 
Engine, MiST Engine is used once more, to create the resulting document 
this time.

The format of the data file is almost the same as that of "values" files 
used by MiST Engine. Similarly, the values can occupy multiple lines, the 
parameters can be multi-valued, etc. The only difference if that the 
values can be organized in groups. 

Each group begins with "[group]" marker and continues until the next such 
marker or the end of file, whatever comes first. From the parameter 
definitions contained in a group, a single block is created. The order of  
blocks is the same as the order of groups in the data file.

Parameter definitions before the first group do not affect the generation 
of blocks, they are used to generate the whole document only.

Note that the parameter definitions contained in the groups are applied not 
only when the blocks are being generated but also during the generation of 
the document. For instance, consider the following data file:

#----------------------
aaa = 1
ccc = 10

[group]
        aaa = 2
        bbb = 5
[group]
        aaa = 2
        aaa = 4
#----------------------

There are two groups of parameter definitions in the file, hence the 
resulting document will have two blocks. 

The first block will be created using the following parameters:
        aaa = 2
        bbb = 5

The second block will be created using the following parameters:
        aaa = 2
        aaa = 4

Note that 'ccc' parameter does not affect the blocks.

The resulting document will contain the two generated blocks and probably 
parts that depend on the following parameters:
	aaa = 1, 2, 2, 4
	bbb = 5
	ccc = 10
That is, the lists of values defined for a parameter before the groups and 
in each group are combined when generating the document.

This allows to create other list-like structures in the document like the 
list of function names in this example.