htmlex - a powerful hypertext markup language preprocessor (HTML)
Copyright (C) 2001, 2002, 2003 by David A. Capello

LICENSE
=======

  htmlex is free software; you can redistribute it and/or modify it under the
  terms of the GNU General Public License as published by the Free Software
  Foundation; either version 2 of the License, or (at your option) any later
  version.

  This program is distributed in the hope that it will be useful, but WITHOUT
  ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
  FOR A PARTICULAR PURPOSE.  See the GNU General Public License for more
  details.

  You should have received a copy of the GNU General Public License along with
  this program; if not, write to the Free Software Foundation, Inc., 59 Temple
  Place, Suite 330, Boston, MA  02111-1307  USA

INTRODUCTION
============

  htmlex is a small but powerful HTML preprocesor, which has numerous
  advantages compared to conventional HTML files. On top of that, htmlex
  is fully compatible with the standard HTML syntax. This means that you
  can use any HTML file that you have previously made, rename it to .htex,
  and start using htmlex.

OPTIONS
=======

  htmlex interprets the following options from the command line:

    -c   compiles all subsequent files (gets an output file name
         from '-o' or generates a name with .html extension, see -E)
    -o   adds output files
    -a   adds arguments for the input files
    -I   adds search include paths (you can use old '-i' parameter)
    -E   changes the HTML extension generated by -c option (.html by default)
    -k   kills comments (old htmlex behavior)
    -d   calculates dependencies of the input files (output to STDOUT)
    -v   activates the verbose mode (to see what htmlex does)
    -V   activates very verbose mode (to debug .htex files)
    -h   displays help screen and exit
    --   breaks -coaI arguments

EXECUTION
=========

  References
  ----------

  STDIN      Standard input: from the keyboard or from file.

  STDOUT     Standard output: to the screen or to file.

  Common behavior
  ---------------

  ./htmlex
  Process STDIN and leave the results in STDOUT.

  ./htmlex file arguments...
  Process `file' and leave the results in STDOUT.

  ./htmlex -c files... -a arguments...
  Process `files' and leave the results in `files.html'.

  ./htmlex -c files... -o destinations...
  ./htmlex -o destinations... -c files...
  Process the `files' and leave the results in the `destinations'.

  Some equivalent examples
  ------------------------

  ./htmlex file.htex arg1 arg2 > file.html
  ./htmlex -c file.htex -a arg1 arg2
  ./htmlex -c file.htex -o file.html -a arg1 arg2
  ./htmlex -a arg1 arg2 < file.htex > file.html
  ./htmlex -a arg1 arg2 -o file.html < file.htex

  Common mistakes
  ---------------

  ./htmlex -I examples file.htex > file.html
  Here the program waits for input from STDIN, because file.htex
  counts as another path for "-I".
  Possible solutions:
    ./htmlex -I examples -- file.htex > file.html
    ./htmlex -I examples -c file.htex
    ./htmlex file.htex -I examples > file.html

  ./htmlex -c index.htex en English
  Here, htmlex will try to compile the files `index.htex', `en' and
  `English', instead of passing the arguments to `index.htex'.
  Possible solutions:
    ./htmlex -c index.htex -a en English
    ./htmlex index.htex en English > index.html

  Changes regarding previous versions
  -----------------------------------

  * Now you can use "-I" instead of "-i" (like gcc).
  * The argument order isn't necessary anymore, so you can do:
    ./htmlex -c src.htex -o dst.html -I dir

FEATURES
========

  Reference
  ---------

  This notation will be used along of the definitions:
    expression            The _expression_ is mandatory.
    [ expression ]        The _expression_ is optional.
    { expression }        The _expression_ is optional and repeatable.
    source -> result      Indicates that _results_ will be obtained
                          when the program will process the _source_ text.

  Tags
  ----

  Lists of tags which you can use in the .htex files (by alphabetical
  sorting):

  <!args>
    Returns the number of arguments which was passed to the input file.
    Example:
      You input <!args> argument(s).

  <!arg1> ... <!argN>
    Returns the argument's value. The arguments are passed to the files
    via the command line's -a option, or from the <!include file
    arg1 ... argN> tag.
    Example:
       2nd argument = <!arg2>.

  <!basename file>
    Returns the base name of the _file_. In other words, removes its
    extension.
    Examples:
      <!basename src/foo.c>    -> src/foo
      <!basename src-1.0/bar>  -> src-1.0/bar
      <!basename hacks>        -> hacks

  <!chop word>
    Removes the last character of _word_.
    Examples:
      <!chop hello>       -> hell
      <!chop directorio/> -> directorio

  <!clean word>
    Cleans _word_ removing blank space (tabulators and line breaks)
    around it.
    Example:
      *<!clean " hola ">* -> *hola*

  <!dep file>
    Adds 'file' as a dependency. This tag takes effect only in the dependency
    generation process.
    Example:
      <!exec ./script.sh>
      <!dep script.sh>

  <!dir file>
    Returns the directory part of _file_. In other words, deletes the file name.
    Examples:
      <!dir src/foo.c> -> src/
      <!dir a/b/foo.h> -> a/b/
      <!dir hacks>     -> ./

  <!elif expression>
    See <!if>.

  <!else>
    See <!if>.

  <!end>
    See <!function>.

  <!exec command { arguments }>
    Executes the indicated _command_ passing the _arguments_ to it. Whatever
    the command prints to the standard output (STDOUT) will be inserted at
    this position in the file.
    Examples:
      <!exec date>
      <!exec gcc --version>

  <!exec-proc file { arguments }>
    Equal to <!exec ...> except that it will process the results as other
    htmlex file.
    Examples:
      <!exec-proc cat header.htex>
      <!exec-proc cat "a footer.htex">
      <!exec-proc cat <!find macros.htex>>

  <!fi>
    See <!if>.

  <!file-size file>
    Returns the size of _file_ in a format that's more human-readable
    (bytes, KB, MB or GB).
    Example:
      image <!file-size image.jpg>

  <!find file>
    Tries to find _file_ in the search path (the active directory and
    all directories added with the -i option), and will return the name
    of the _file_ with the matching path. In the case that the file isn't
    found, nothing is returned.
    Examples:
      <!if <!find index.en.html>>
        english
      <!fi>

  <!function name { submacros }>
    Creates a new functional macro like in C/C++. When the program see
    this tag, it follows reading the file in "raw" mode until finds
    <!end> tag. Then, the macro could be called like any other tag:
    <!name {args}>
    Example:
      <!function my_macro a b c>a is b c<!end>
      <!my_macro This my macro>.
    Results:
      This is my macro.

  <!if expression>
    One of the more powerful features of htmlex relative to
    conventional HTML is the conditional-blocks.

    Through four tags you can do some of the conditional operations
    of "normal" programming languages. Although nowadays, htmlex has a
    poor handling of operations, improvements to this construct will
    made.

    The general syntax is the following:

      <!if [ expression ]> block
      { <!elif [ expression ]> block }
      [ <!else> block ]
      <!fi>

    The _block_ can be any text (or just nothing), can have other tags,
    and consequentialy, can have more nested <!if> tags.

    The _expression_ to be evaluated can have any of the formats below:

      FORMAT               TRUE IF...
      -------              ----------
      number               _number_ is not zero
      ! number             _number_ is zero
      word                 _word_ has one character as minimum
      ! word               _word_ is empty
      number1 < number2    _number1_ is less than _number2_
      number1 > number2    _number1_ is greater than _number2_
      number1 <= number2   _number1_ is less or equal than _number2_
      number1 >= number2   _number1_ is greater or equal than _number2_
      number1 == number2   _number1_ is equal than _number2_
      number1 != number2   _number1_ is different than _number2_
      word1 == word2       _word1_ is identical than _word2_
      word1 != word2       _word1_ differs in just one character than _word2_
      
    If the expression format cannot be resolved to the table above, then false
    is returned.

    _numbers_ are distinguished from _words_ when they have some of these
    formats:

      [1-9][0-9]*      decimals
      0x[0-9a-fA-F]*   hexadecimals
      0[0-7]           octals

    Examples:
      <!if <!arg1> == --help>
        Do you need help?
      <!else>
        Try with --help.
      <!fi>
      <!if <!tolower HELLO> == <!tolower Hello>>
        works
      <!fi>
      <!if>For here it won't never pass<!fi>

  <!include file { arguments }>
    Includes the _file_ to be processed like an normal .htex file. This file
    will also be used for calculating dependencies. This is equivalent to
    C's #include.
    Examples:
      <!include header.htex>
      <!include footer.htex en UK>

  <!macro name [ value ]>
    Creates or modifies a macro with the specified _name_ and _value_.
    If _value_ is not specified, the macro will be eliminated from
    memory. The main use of macros is to replace a certain keyword
    (its _name_) for some predetermined text (its _value_).
    Example:
      <!macro hi bye>
      hi -> bye   <!-- "hi" replaced by "bye" -->
      <!macro hi>
      hi -> hi    <!-- "hi" macro is deleted -->

  <!macro-reset>
    Removes any macro which was created before this tag.
    Example:
      <!macro a b>a<!macro-reset>a -> ba

  <!notdir file>
    Returns the name of the _file_ without the directory.
    Examples:
      <!notdir src/foo.c> -> foo.c
      <!notdir a/b/foo.h> -> foo.h
      <!notdir hacks>     -> hacks

  <!shift word>
    Removes the first character of _word_.
    Examples:
      <!shift your> -> our
      <!shift .txt> -> txt

  <!suffix file>
    Returns the extension of _file_.
    Examples:
      <!suffix "src/foo.c">   -> .c
      <!suffix "src-1.0/bar"> ->
      <!suffix "hacks">       ->

  <!tolower word [ beginning [ final ] ]>
    See <!toupper>.

  <!toupper word [ beginning [ final ] ]>
    Converts partially or completelly _word_ to lower or upper case
    depending on if you specify or not the _beginning_ and/or the _final_
    character index. Indecies start at 0.
    If only _beginning_ is specified, then the range starting from
    _beginning_ to the last character is converted.
    If you also indicate _final_, you are specifying an upper bound
    to the conversion range.
    Note: negative values for _final_ indicates that values are to be taken
    from the end of the _word_.
    Examples:
      <!tolower HELLO>      -> hello
      <!tolower HELLO 0>    -> hELLO
      <!toupper hello 1 2>  -> hELlo
      <!toupper hello 0 -2> -> HELLo

  <!version>
    Shows the program version which is processing the file.
    Example:
      This page was created with htmlex <!version>.

IMPORTANT NOTES
===============

  <!macro X> deletes the X macro, so if you use <!if X>
  that expression will give you true (because the string "X"
  will be used, and not the value of X).

  <!macro X ""> assigns a null value to the X macro, this is
  necessary for a false result in <!if X> (because in this case,
  the X is replaced by its value).

BUGS
====

  Report bugs to <dacap@users.sourceforge.net>.

UPDATES
=======

  To obtain the latest information about htmlex, go to:

    http://htmlex.sourceforge.net

AUTHOR
======

  David A. Capello <dacap@users.sourceforge.net>

  Any suggestion, thank-you letters, or (preferably) donations ;-),
  will be most welcomed.
  You can visit http://www.davidcapello.com.ar for more information.