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

Copy the runtime libraries libHTCL.tcl and html.tcl into a library directory.
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

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.
makes the current generated section "main".

##html [section]

Start appending HTML to the particular section.

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.
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.