Htmlincl v5.35

Htmlincl is a preprocessor that generates html files out of “macro” files. The macrofiles contain special instructions for Htmlincl. There are instructions to include other files, if/then conditional html, and macro handling.

 

Download and install

 *  Download htmlincl-5.35.zip for Windows 95/98/NT (76kb)
 *  Download htmlincl-5.35.tar.gz for Unix (34kb)
The distribution for Windows 95/98/NT contains the htmlincl.exe program. Installing it is very simple: just copy the program to a directory in your path, for example: “c:windows” or “c:winnt”. The distribution for Unix contains all the sources and a Makefile. Run “make” and copy the binary to somewhere in your path. 

How does it work

  1. Create a simple text file called “example.m” containing the following text:<include header.inc TITLE=”Test”>
    This page was created on: <macro MODIFIED>
    <include footer.inc>
  2. Run the htmlincl program. It will generate a file called “example.html”:htmlincl example.m

The first line of the example will include a file called “header.inc”. In this example you have not created such a file yet, so it will generate an error message. Normally you would stuff the header file with html code such as <html>, <title>, and <body> tags. These have no meaning to the htmlincl program, so it will copy them into the output “example.html” file without change.The first line of the example also defines a macro called “title”, containing the string “Test”. It is passed to the included file, where it can be used to customise the title of the page. You can define any macro you like, you are not limited to just the “title”.

The second line of the example begins with the text “This page was created on:”. This text has no meaning to htmlincl, so it will copy it without change to the output. Then a pre-defined macro is used, which will insert the date of the macro file into the html. The whole string “<macro MODIFIED>” will be replaced with something like “19 january 2002 17:00:43”.

The third line is a bit like the first. It will include a file called “footer.inc”, which could contain html code such as <address>, </body>, and </html>.

 

Macro files

The input for Htmlincl is a “macro” file, which always has extension “.m”. Macro files live in the same directory as their “.html” files. Htmlincl will read the macro file, process all the commands in it, and write the result to the “.html” file. Htmlincl recognises the following tags:

Include Include the contents of another file. For example:
<include header.inc Title=”This is the title.”>
Macro Store a string in memory, or retrieve a string from memory. For example:
<macro Page=”This is the title.”>
<macro Page>
Undef Remove a macro from memory. For example:
<undef Page>
If Conditionally skip html. For example: <if Page=12> … </if>
<if Page=12> … <else> … </if>
<if Page=12> … <elif Page=13> … <else> … </if>
The following conditionals are recognised:

  • Equal: “=”, “==”, “EQ”
  • Not equal: “!=”, “NE”
  • Greater than: “>”, “GT”
  • Less than: “<“, “LT”
  • Greater or equal: “>=”, “GE”
  • Less or equal: “<=”, “LE”
Literal Do not process this html. For example:
<literal “<macro macros>”>
Macros Dump the contents of all the macros for debugging purposes. For example:
<macros>

 

General remarks:

  • See the generated html for error messages.
  • Tags may be anywhere on a line, even inside comments and strings.
  • The program is case-insensitive. You may use uppercase and lowercase characters anywhere, they will be treated the same.
  • Tags may be nested.
  • Tags may span more than one line.
  • Tags may also be ASP-style. This allows macro-files to be edited by ASP-aware editors such as DreamWeaver. For example:
    <macro Page>
    <%macro Page%>
  • The tags are not part of the HTML standard. I have defined them myself. Browsers will treat the tags as a comment.

Expressions

Htmlincl contains a simple expression evaluator. You can use expressions anywhere, but you will use them most frequently in “if” tags. The expressions can handle simple integer arithmetic and strings. Here are the commands that are recognised:

+ If both operands are numbers then they are added. If both operands are strings then the second operand is appended to the first. For example:
5 + 9 = 14
“a” + “b” = “ab”
Subtract (numbers only). For example:
9 – 5 = 4
* Multiply (numbers only). For example:
9 * 5 = 45
/ Divide (numbers only). For example:
19 / 5 = 3
% Remainder (numbers only). For example:
19 % 5 = 4
( … ) Process this first. For example:
5 * (3 + 2) = 25
AND True if both left and right operand are true. For example:
(page != 3) AND (page != 4)
OR True if left or right operand are true. For example:
(page = 3) OR (page = 4)
var(…) Interpret the expression inside the parenthesis as the name of a macro. For example:
var(“arr” + index)

Precedence:

  • Multiplication and division take precedence over addition and subtraction. For example: “x + y * z” is equivalent to “x + (y * z)”.
  • AND takes precedence over OR. For example: “x OR y AND z” is equivalent to “x OR (y AND z)”.
  • Use parenthesis ‘(…)’ to change precedence to what you want it to be.

Strings:

  • Use single- or double quotes to enclose strings containing whitespace. For example:
    <macro title=”This is page 1″>
    <macro title=’This is page 1′>

Escaping:

  • Sometimes it is necessary to include a character in a string that would normally have special meaning. You can escape these characters by preceding them with the ” (backslash) or the ‘~’ (tilde) character. For example:
    <if (Age > 21) AND (Age < 65)> … </if>
    <if (Age ~> 21) AND (Age ~< 65)> … </if>

Examples:

  • <macro PageNumber + 7>
  • <macro PlusVAT = Amount * 1175 / 1000>
  • <if (Age > 21) AND (Age < 65)> … </if>
  • Array’s:
    Setup index: <macro index = 3>
    Store array entry: <macro var(“date” + index) = 17>
    Fetch array entry: <macro var(“date” + index)>
    Equivalent with: <macro date3>

Pre-defined macros

Filename The name of the macro file, without extension or directory. For example: “index”
Extension The extension of the macro file. Generally this will be “m”. For example: “m”
Path The full path to the macro file, without filename or extension. For example: “D:www.kessels.comhtmlDownloadshtmlincl”
Dir The topmost directory where the macro file lives. For example: “htmlincl”
Modified The time the macro file was last modified. For example: “19 january 2002 17:00:43”

 

 

Running htmlincl

htmlincl [-d N] [-h] [-r] [-v] [filenames/dirnames]
-d N Set debug level to N. Default is zero, highest is 3.
-h Show a quick help.
-r Recursively process all subdirectories.
-v Show the version of the program.
filenames/dirnames The files and/or directories to process. Default is “*”, all the files and subdirectories in the current directory. If you specify a directory, then all files in the directory tree starting at that point will be processed. Only files with extension .m will be processed.

 

 

Tips and tricks

  1. Macros are faster than included files. Try to use a macro for short items instead of include’s.
  2. Create a header file that is used in all macro files. Here is an example: header.txt
  3. Stuff the htmlincl program into a hotkey of your editor.
  4. Using macro’s inside macro’s (recursive macro expansion):
      <macro fonts='Helvetica, Arial, sans-serif'>
      <macro font='<font face="<macro fonts>">'>
      ...
      <macro font>
    
  5. How to test if a variable exists:
      <if VarName> ... </if>
    
  6. Dynamic macros, or how to make a macro that uses parameters:
      <macro Bold="<B><I><macro Text></I></B>">
      ...
      <macro Bold Text="This text will be set in italic bold">
    
  7. Dynamic include-files, or how to make an include-file that uses parameters:
      <include header.inc TITLE="The greatest show on earth">
    
      Inside the "header.inc" file:
      <macro TITLE>
    
  8. On-the-fly include-file names, or how to use a variable to select an include-file:
      <macro HeaderNum = 3>
      ...
      <include var("header" + HeaderNum + ".inc") >