[%!\
  Tema User Manual.
%]\\

<%silent include:document.tema%>\\

<%document:
  title    <%:Tema -- template macro processor%>
  author   <%:Mikhail Kryshen%>
  content

<%section:Introduction%>

<%par:Tema is a macro processor and template engine. It reads the input file 
recursively expanding any macro found in the text.%>

<%par:Distinctive features:%>
<%itemize:
  <%:Extensible: implement new functions as Java classes.%>
  <%:Database access.%>
  <%:Processes and outputs data as early as possible (function could start 
     to output data before all it's arguments are read and parsed).%>
  <%:Apache Ant integration.%>
%>

<%par:Tema macro has the following syntax:%>

<%par:[%code\<%function_list{:|#|\|`}[escape]text%>[escape]%]%>

<%par:<%code:function_list%> is the list of text-processing functions.
Functions will be applied to text in reverse order.%>

<%par:<%code:text%> could contain space-separated list of arguments 
followed by arbitrary data. Number of arguments is determined by the last
function in the <%code:function_list%>.%>

<%par:<%code\[arg1 arg2...] [data]%>%>

<%par:The text is separated from the list of functions by one of the 
following characters:%>

<%itemize:
  <%\':' -- process text recursively.%>
  <%\'#' -- parse text but do not replace any embedded macro.%>
  <%\'\', '`' -- do not parse text (ignore any '<%' sequences).%>
%>

<%par:<%code:escape%> is either '\' or '\\':%>

<%itemize:
  <%:<%:\%> -- the following newline symbol will be removed;%>
  <%:<%:\\%> -- the following sequence of the whitespace characters will be removed.%>
%>

<%par:You could use <%\'[%' and '%]'%> character sequences to denote macro
as an alternative to [%\'<%' and '%>'%].%>

<%par:Every function returns integer value. The general convention is to 
return non-zero for successful operation. The value of the macro substitution 
is the return value of the first function in the function list. The value of
any Tema text is the sum of the absolute values of all macro in the text,
except the value of the text without any macro equals -1.%>

<%par:Internally, Tema function could be represented by any Java object.
Instances of kryshen.tema.Function and kryshen.tema.Context are handled
specially. For any other type of object, function output would be the value 
returned by the method <%code:toString()%>.%>

<%section:Built-in functions%>

<%par emph:Notice: some functions are not yet described in this manual.
For the complete list of built-in functions refer to the API documentation
and source code.%>

<%function:tema
  output  <%:Tema version%>
%>

<%function:echo  
  output  <%:function data%>
%>

<%function:!
  output      nothing
  description <%:Ignores the input text (':' separator works as '#').
    Use for commenting (e.g. <%code\[%!\ comment %]%>).%>
%>

<%function:silent  
  output  nothing
%>

<%function:set
  arguments   <%:definition name%>
  input_data  <%:variable value%>
  output      <%:function data%>
  description <%:Defines new function as a static variable.%>
%>

<%function:define
  arguments   <%:name%>
  input_data  <%:code%>
  description <%:\\
    Defines new function. 
    Use <%code:next_arg%>, <%code:data%>, and <%code:has_more_data%> 
    functions to access function arguments.%>
  output      <%:name%> 
%>

<%function:next_arg
   description <%:\\
     Works in context of <%code:define%> function.
     Parses the next argument from the calling function input.%>
   output <%:next argument text%>
%>

<%function:data
   description <%:\\
     Works in context of <%code:define%> function.
     Outputs remaining text passed to the calling function.%>
   output <%:next argument text%>
%>

<%function:has_more_data
   description <%:\\
     Works in context of <%code:define%> function. Returns non-zero value if
     the calling function has more input data available.
   %>
%>

<%function:export
  arguments   <%:definition name%>
  input_data  <%:static variable value (optional)%>
  output      <%:function data%>
  description <%:Exports the definition to the global (outermost) context.%>
%>

<%function:unset
  arguments   <%:def1, def2, ...%>
  output      <%:nothing%>
  description <%:Unsets the definitions.%>
%>

<%function:invoke
  arguments   <%:function, arg1, arg2, ..., data%>
  output      <%:function output%>
  description <%:Invokes function.%>
%>

<%function:load
  arguments   <%:name, class, url1, url2, ...%>
  output      <%:name%>
  description <%:Instantiate specified class as a Tema function definition.
    URL arguments are optional.%>
%>

<%function:super
  input_data  <%:code%>
  output      <%:output generated by the code%>
  description <%:Evaluates the specified template code in the super-context
    (i.e. context of the calling function or context executing 
    the database query).%>
%>

<%function:replace
  arguments   <%:s1, s2, data%>
  description <%:\\
    Replaces all occurrences of <%code:s1%> with <%code:s2%> in data.%>
%>

<%function:xml_escape
  input_data  <%:text%>
  output      <%:text with escaped XML special characters%>
%>

<%function:xml_cdata
  input_data  <%:text%>
  output      <%:XML CDATA section containing the text%>
%>

[%!\ TODO: all functions defined in Strings.java %]\\

<%subsection:Input / output%>

<%function:copy
  arguments   <%:src, dest%>
  description <%:Copies file <%code:src%> to <%code:dest%>.%>
  output      <%:dest%> 
%>

<%function:write
  arguments   <%:name%>
  input_data  <%:text%>
  description <%:Writes text to file.%> 
  output      <%:name%>
%>

<%function:read
  arguments   <%:name%>
  description <%:Reads file.%> 
  output      <%:File contents.%>
%>

<%function:include
  arguments   <%:name%>
  description <%:Includes template.%> 
  output      <%:Result of processing the template.%>
%>

<%function:file
  arguments   <%:base, name%>
  output      <%:Path constructed from the base directory and file name.%> 
%>

<%subsection:Conditionals%>

<%function:optional
  input_data  <%:text%>
  output      <%:Function data if it's value is non-zero or empty text.%>
%>

<%function:while
  input_data  <%:code%>
  description <%:Repeatedly outputs it's evaluated data while parses with non-zero value.%>
%>

<%function:if
  arguments   <%:condition%>
  input_data  <%:text%>
  description <%:Outputs the input text if the condition parses with non-zero value.%>
%>

[%!\ TODO: all functions defined in Control.java %]\\

<%subsection:Database%>

<%function:db_connect
  arguments   <%:connection name%>
  input_data  <%:resource%>
  description <%:Establishes connection with the database.
    Load the appropriate database driver using the <%code:load%> function
    before using <%code:db_connect%> 
    (e.g. [%code\<%load:driver sun.jdbc.odbc.JdbcOdbcDriver%>%]).%>
%>

<%function:db_prepare
  arguments   <%:query name, connection name%>
  input_data  <%:SQL statement%>
%>

<%function:db_query
  arguments   <%:query, template, arg1, arg2, ...%>
  description <%:Executes query, evaluating the template for each result row.%>
%>

<%function:db
  input_data  <%:column name%>
  output      <%:value from the query result.%>
  description <%:Available in the template for the <%code:db_query%> function.%>  
%>

<%function:db_row
  output      <%:current row number in the result set.%>
  description <%:Available in the template for the <%code:db_query%> function.%>  
%>

[%!\ TODO: all functions defined in ImageConverter.java %]\\

<%section:Running Tema%>

<%par:Change to the dist subdirectory in the distribution package and
issue the following command:%>

<%par:<%code:java -jar tema.jar [options] [files]%>%>

<%par:The following options are recognized:%>
<%itemize:
  <%:<%code:--demo%> --- run demo console with a code example;%>
  <%:<%code:-h, --help%> --- print help message;%>
  <%:<%code:--input-encoding <arg>%> --- set the input encoding;%>
  <%:<%code:--log <arg>%> --- log all error messages to the specified file;%>
  <%:<%code:-o, --output <arg>%> --- set the output file;%>
  <%:<%code:--output-encoding <arg>%> --- set the output encoding;%>
  <%:<%code:-v, --version%> --- print the version information and exit.%>
%>

<%if:<%not embedded:%>
<%section:Homepage%>

<%par link:http://kryshen.net/tema/%>
%>