Usage
*****

One convention is to name the TCL files with a .htcl extension and then
have a makefile rule to convert them into a file with a .tcl extension. 

From the command line, you would do: 

HTCLtoTCL.tcl file.htcl > file.tcl

Your Makefile rule might look like (GNU Make): 

%.tcl: %.htcl
        ./HTCLtoTCL.tcl $< > $@

Configuration
*************

 1. Copy the runtime libraries libHTCL.tcl and html.tcl into a
   library directory. 
 2. Edit HTCLtoTCL.tcl and edit this line to point to the library
   directory from the previous step. 

   set HTCLlibraries /home/k2/users/clarsen/htcl

Language Description
********************

HTCL is a preprocessor, and its directives are just TCL comments. The
directives must appear at the beginning of the line and must start with
"##". The directives are case-insensistive. 

##prologue 
   Inserts the initialization code at the particular point in your TCL
   code. The initialization code 
    o sets up the TCL auto_path variable to automatically load
      the required libraries. You must edit HTCLtoTCL.tcl to
      specify the location where the libraries (libHTCL.tcl and
      html.tcl) are installed. 
    o makes the current generated section "main". 
##html [section] 
   Start appending HTML to the particular section. 
    o If section is omitted, then it defaults to "main".
      Everything between ##html and ##endhtml is inserted
      into a quoted string in the generated TCL code. TCL
      variable expansion and function calls insert their results
      into the generated string at evaluation time. 
    o If section is specified, then HTML is appended to the
      specified section. The HTML will not appear in the final
      output unless it is specifically inserted into the "main"
      section using the ##section command. "section" is
      evaluate as a TCL expression at run-time, so you can use
      variable expansion, function calls, etc. 
##section sectionname 
   Inserts the contents of section "sectionname" into the HTML
   output at this point. The "sectionname" section does not need to
   contain any information at this point. The contents of the section
   is inserted when the HTML output is generated with ##outhtml.
   Sections can be nested, so "main" can include "foo" and "foo"
   can include bar. Sectionname is evaluated as a TCL expression at
   run-time, so you can use variable expansion and function calls,
   etc. 
##endhtml 
   Stop appending HTML to the section. 
##outhtml filedescriptor 
   Writes the HTML for the "main" section to the file descriptor.
   This is a TCL file descriptor such as stdout, stderr, or the result
   of an open call. filedescriptor is evaluated as a TCL expression at
   run-time as well. 

Example(s)
**********

An example TCL program coded as a CGI script marked up in HTCL is 
here, and the generated (not so nice looking) TCL source is here. The
output it generates is here. 

Description of CGI GET and old method GET script support functions
are here. 

                


A more involved example (excerpts from production code, not
executable) will be generated.