#define TITLE GTML Reference Page #include "header"

This is the reference page for the HTML pre-processor _gtml_. It describes all the _gtml_ features and commands in detail. For more information about getting _gtml_, see [[MAIN]], the main _gtml_ page.

_gtml_ features fall into four main areas, and we'll look at them in this order:

Commands

The original syntax of _gtml_ was stolen shamelessly from the C language pre-processor, and has been adapted to suit Web site management. It supports the following commands:

Command syntax

There are two ways of writing commands:

The first method is simpler, and is the recommended way of writing _gtml_ , if possible. However, if you're using an HTML authoring tool which complains about _gtml_ commands, you can use the second method to hide the _gtml_ commands from the tool.

#include

If you have some common text which you want inserted in more than one Web page, put it in a separate file - say, common.txt. Then, at the place where you want the text in each file, put the following line: 

#literal on
#include "common.txt"
#literal off

_gtml_ replaces this line with the entire contents of the file common.txt.

The name of the file can be defined in a named constant, as described next.

The directories in which the file may be looked for can be defined in a #searchpath,special named constant.

#define

This is a simple way to create shorthand definitions - what we call named constants, or macros - for your frequently-used text. For some text which you use often - say, an e-mail address - include a line like this: 

#literal on
#define MY_EMAIL gihan@pobox.com
#literal off

This defines a named constant MY_EMAIL and its value gihan@pobox.com. The value can be any text, including spaces and HTML markup (leading spaces and tabs are ignored), as long as it's all on one line or it's all on multiple consecutives lines with a trailing \ at the end of each lines, except the last.

To use this named constant, whenever you want your e-mail address, specify it like this: 

#entities ON
     <>
#entities OFF

The double angle-brackets tell _gtml_ to substitute this with its definition (You can #delimiters,specify your own choice of delimiters instead of the double-angle brackets).

There are a few other things you should know about #define:

#newdefine

This is identical to #define,#define, except that the definition applies only if the named constant has not been defined already. If it has been defined, the old definition is unchanged. #newdefine! is identical to #define! with the same exception.

#undef

Use this to remove the definition of a named constant: 

#undef MY_EMAIL

If the named constant didn't exist previously, this does nothing.

#if, #ifdef, #ifndef, #elsif, #elsifdef, #elsifndef, #else, #endif

These commands are used together for conditional output:

Conditional blocks can be nested.

#timestamp

The special named constant TIMESTAMP evaluates to the current date and time. But to use it, you must tell _gtml_ what format to use to print the date/time.

The format string is specified in the #timestamp statement like this: 

#literal on
#timestamp   $dd/$MM/$yy at $hh:$mm:$ss
#literal off

The value of <<TIMESTAMP>> will then be: 8/06/96 at 11:45:03.

As you can see, certain strings (like $dd) are replaced with values. The full set of substitution strings is as follows (everything else is left unchanged in the format string):

$hh Hour (00 to 23)
$mm Minute (00 to 59)
$ss Seconds (00 to 59)
$Day Full weekday name (Sunday to Saturday)
$Ddd Short weekday name (Sun to Sat)
$dd Day of the month (1 to 31)
$ddth Day of the month with ordinal extension (1st to 31th)
$MM Month number (1 to 12)
$Month Full month name (January to December)
$Mmm Short month name (Jan to Dec)
$yyyy Year (e.g. 1996)
$yy Short year (e.g. 96)

Monthnames are output in English by default; but they can be output in other languages, according to the #language,LANGUAGE special definition.

#mtimestamp

This is identical to #timestamp,timestamp, except that the time used is not the current one, but the time the file was last modified.

#literal

The command #literal ON tells _gtml_ to stop interpreting lines beginning with # as _gtml_ commands, until the next #literal OFF line. Defined constants are still substituted, and #entities,entities are translated if desired.

For example, this is useful for bracketing blocks of C code, which might have lines beginning with #.

#entities

The command #entities ON tells _gtml_ to convert the characters <, > and & into HTML entities so they aren't treated as part of HTML commands. Use #entities OFF to turn off this conversion.

This is useful for bracketing blocks of program code, which often contain these characters.

#definechar

Basic HTML authorized characters may only be ASCII characters. Accentuated characters are coded in HTML in a certain way. For instance the é character is coded &eacute;. You may want to input é in your source file, and have the right code used in your HTML file. This character's translation may be defined with the #definechar command, like in this example: 

#literal on
#definechar é &eacute;
#literal off

Sometimes you might want to input special characters that are not available on your keyboard, but do not want to input its HTML code (Think of the German ß on an English keyboard). For instance if you want all occurrances of ss in your source file to be translated into ß, you can use the #definechar command: 

#literal on
#definechar ss &szlig;
#literal off

#compress

The command #compress ON tells _gtml_ to begin producing compressed HTML code, i.e. stripping multiple spaces, removing newlines, HTML comments, and all other stuff useless for an HTML browser to render a page. This compression is done on the output file until the next #compress OFF.

#sitemap, #toc

When you specify a #hierarchy, hierarchy of pages in your #project,project file you may insert a table of contents, or site map, of those pages, using the command #sitemap, or #toc.

See #hierarchy,Document hierarchy specifications for more information on how the list is created.

_gtml_ project files

Because _gtml_ is most useful for managing multiple files, it's quite common to change something in a #include'd file, and then run _gtml_ on all the .gtm files which use it.

To make this procedure easier, _gtml_ supports a concept of a project file. This is a simple text file with the extension .gtp. It can contain:

When you run _gtml_ with the project file as a command-line argument, it will process all the source files in the project file. They will all inherit the define, definechar and timestamp values, if any, in the project file. The mtimestamp value will change according to the modification date of the appropriate source file.

You may use a project file, but process only selected source files (declared in the project) with the #optionf, -F command line argument.

Note that #define, #newdefine and #undef commands inside a file are local to that file - they don't carry over to the next file in the project. However, named constants defined in the project file are inherited by all files in the project.

Document hierarchy

_gtml_ allows you to create a hierarchy of Web pages, with links between them. Each Web page can have a link to the previous page, the next page, or one level up in the hierarchy. Obviously, some of these links don't apply to some pages - _gtml_ generates only those that apply to each page.

Describing the hierarchy

You describe the document hierarchy to _gtml_ by listing the file names in the project file in a certain order, with a document level and title for each. Level 1 is for top-level documents, and 2, 3, 4, and so on are lower levels. File names without a level have no hierarchical information attached to them.

When _gtml_ processes a file, it defines special named constants which can be used in exactly the same way as #define,other named constants.

For each file, _gtml_ generates the named constants, LINK_PREV, LINK_NEXT and LINK_UP. These correspond to the file names of the previous file, next file and one level up in the hierarchy. In addition, it also generates the corresponding named constants TITLE_PREV, TITLE_NEXT, TITLE_UP and TITLE_CURRENT to be the titles of these files (As stated above, the title follows the level number in the project file).

Some of these named constants may not be applicable to some files, in which case the named constant is not defined for that file.

Example

Here's an extract from a hypothetical _gtml_ project file: 

    contents.gtm 1 Table of Contents
    chapter1.gtm 2 Introduction
    sec11.gtm    3 What's the Problem
    sec12.gtm    3 Old Approaches
    sec13.gtm    3 New Idea
    chapter2.gtm 2 Historical Evidence
    sec21.gtm    3 Early 1900's
    sec22.gtm    3 Recent Findings
    chapter3.gtm 2 Our Bright Idea

To take a simple case, the file sec21.gtm will have LINK_NEXT set to sec22.html (and TITLE_NEXT set to Recent Findings) and LINK_UP set to chapter2.html (and TITLE_UP set to Historical Evidence). LINK_PREV and TITLE_PREV will be undefined.

Using the links

The links can be used to create navigation links between the documents. In other words, each document can have links up the hierarchy and to the next and previous documents.

Typically, you would place the navigation information in a common file and #include it into each _gtml_ source file. The _gtml_ #ifdef command can be used to exclude links which don't apply to a particular file.

Here's a simple example: 

#entities on
#literal ON
#ifdef LINK_NEXT
   
Next document: <>
#endif
#ifdef LINK_PREV
   
Previous document: <>;
#endif
#ifdef LINK_UP
   
Up one level: <>;
#endif
#literal OFF
#entities off

Creation of table of contents

When you have described a document hierarchy, and you use a #sitemap, #toc or #sitemap command into your source file, _gtml_ includes a sitemap generated as a list with the help of the __TOC_#__(x), and __TOC_#_ITEM__(x,y) special named constants (# being a file level).

With the previous example it gives: 

#entities on
<<__TOC_1__('
  <<__TOC_1_ITEM__('contents.html','Table of Contents')>>
  <<__TOC_2__('
    <<__TOC_2_ITEM__('chapter1.html','Introduction')>>
    <<__TOC_3__('
      <<__TOC_3_ITEM__('sec11.html','What's the Problem')>>
      <<__TOC_3_ITEM__('sec12.html','Old Approaches')>>
      <<__TOC_3_ITEM__('sec13.html','New Idea')>>
    ')>>
    <<__TOC_2_ITEM__('chapter2.html','Historical Evidence')>>
    <<__TOC_3__('
      <<__TOC_3_ITEM__('sec21.html','Early 1900's')>>
      <<__TOC_3_ITEM__('sec22.html','Recent Findings')>>
    ')>>
  ')>>
')>>
#entities off

__TOC_#__(x), and __TOC_#_ITEM__(x,y) have the following default values: 

#entities on
#literal on
#define __TOC_#__(x)        
#define __TOC_#_ITEM__(x,y) 
  • y
#literal off
#entities off

    • You may redefine this constant to whatever you want as long as you respect the number of variables.

    Special definitions

    Environment

    All environment variables are defined as named constants by _gtml_.

    Current file names

    The special named constants ROOT_PATH, BASENAME, FILENAME and PATHNAME are set to the current path to root of the project (where the project file resides), output file name without any extension and excluding any directory path information, output file name excluding any directory path information, and directory path information relative to the path to the root of the project.

    Search path for include files

    _gtml_ always searches for include files in the directory of the processed source file first, then the current directory (where the _gtml_ command is executed).

    In addition, if you define the named constant INCLUDE_PATH, _gtml_ will interpret it as a list of directories (separated by colons), to search for include files. Those directories may be absolute, or relative to the root path of the project.

    Output directory

    By default, _gtml_ writes its output files to the same directory as the corresponding source file. You can override this by defining the named constant OUTPUT_DIR as the name of the output directory.

    If you are doing this with a project file, specify OUTPUT_DIR as the top-level output directory. _gtml_ will create the same directory hierarchy for the output files as for the input files (It creates sub-directories as required).

    Output suffix

    By default all created files are created by changing the .gtm, or .gtml extension of the source file to the .html one.

    You may change this behavior by defining the special constant EXTENSION to whatever extension you want.

    The definition of this constant does not have sense in a source file, since the output file is already created the moment GTML starts to parse the source file. It makes sense however to define it in the #project,project file or on the #cmdline,command line.

    If the suffix is preceded by two dots as in gtml.css..gtm, then the source suffix is not replaced, but just removed, as in gtml.css.

    Fast generation

    _gtml_ only processes files which are younger than the output files which they might produce. This is very useful, as it increases the generation speed of web sites with a big number of pages, when only one of them has been changed. Same kind of the way make works.

    To enable this feature you just have to define the special constant FAST_GENERATION. The use of this constant will work only in #project,_gtml_ project files or on the #cmdline,command line.

    This feature does not take into account included files, but only the main gtml source, and the wanted output. To deal with more complex file dependencies you may use the make tool in conjunction with the #optionf,-F and #optionm,-M command line arguments.

    Language localisation

    By default all timestamps produce monthnames and daynames which are output in English. You can output them in other languages by defining the constant LANGUAGE to a value corresponding to an available language.

    As of today seven languages are available. The default one is English. Following is the list of those language with the corresponding value for LANGUAGE constant:

    If you can send me month and day names in other languages, just do it, I will integrate it in following versions of _gtml_.

    Substitution delimiters

    The default delimiters for substituting named constants are << and >>. You can change these to any other strings by defining the named constants OPEN_DELIMITER and CLOSE_DELIMITER respectively.

    For example, if you had the following lines: 

    #literal ON
#define OPEN_DELIMITER {{
#define CLOSE_DELIMTER }}

#define MY_EMAIL  gihan@pobox.com
#literal OFF

    then GTML substitutes MY_EMAIL when it finds the text {{MY_EMAIL}} instead of the default <<MY_EMAIL>>.

    Document hierarchy links

    As described above, _gtml_ #hierarchy,defines several named constants for links between documents.

    Embedded Perl code

    You may embed Perl code into your _gtml_ source file, and have the result of the last evaluated expression inserted in your output file, with the help of the one argument macro __PERL__.

    Here is an example inserting the size of the source file: 

    #entities on
<<__PERL__(return (stat(<><>.".gtm"))[7];)>>
#entities off

    Embedded system command code

    You may embed system command output into your _gtml_ source file, with the help of the one argument macro __SYSTEM__.

    Here is an example inserting the list of files in the current directory: 

    #entities on
<<__SYSTEM__(dir)>>
#entities off

    Command-line arguments

    -D

    When you run _gtml_ from the command line, you can define named constants like this:

    -DMY_EMAIL=fred

    This is the same as #define MY_EMAIL fred in the file.

    These definitions can occur anywhere within the command-line options, but only affect the files after them. For example, if your command line is: 

    perl gtml.pl fred.gtm -DMY_EMAIL=fred bill.gtm harry.gtm

    then the MY_EMAIL definition doesn't apply to fred.gtm.

    -F

    When you run _gtml_ from the command line on a project file you may want to process only some of the files used in it. This may be very useful in conjunction with make for page regeneration based on complex files dependencies (induced by #include commands).

    To process only one file of a project you can use the -F argument followed by the name of the file to process. File to be processed must appear, on the command line, before the project file it appears in.

    Let us suppose we have this project file, called foo.gtp: 

    // Beginning of foo.gtp
define MAIL beaufils@lifl.fr

foo.gtm
bar.gtm
// End of foo.gtp

    If you just want to regenerate the bar.html file your command line will be: 

    perl gtml -Fbar.gtm foo.gtp

    List of files to processed is cleared after each project file treatment.

    -M

    When you run _gtml_ with the -M command line argument, _gtml_ process project and source files, but do not produce ouput files. _gtml_ generates a makefile ready to create output files.

    If you do not specify a filename, the generated makefile is created under the GNUmakefile name.

    To specify a filename, just add it after the -M argument, with a colon between the option and the file name.

    -h, --help

    To get a small command line usage description you can use the -h, or --help command line argument.

    --silent

    If you specify the --silent command line argument, _gtml_ will produce no processing information during its work.

    --version

    To get the version number of the _gtml_ you are currently using you can use the --version command line argument. #include "footer"