Htmlc : a text file generator

Version 3.5

Where is it ?

Htmlc's source files are here (access on this WEB server via the HTTP protocole) or there (access on the main INRIA FTP server ftp.inria.fr).

What is it ?

Htmlc is an HTML template files expander that produces regular HTML pages from source files that contain text fragments that require some computation to be written. Those fragments can be the output of an arbitrary Unix command, for instance the last modification date of a page, or parts of HTML pages to be included in the page, or pieces of the page that are common to the entire WEB site (a presentation header or a footer section for each page). Providing the automatic inclusion of those text fragments into your HTML source pages, Htmlc offers a server independent way of defining templates to factorize out the repetitive parts of HTML pages. Htmlc also provides a variable expansion facility (using definitions in the template file or in simple environment files using a syntax a la objective Caml). In short, Htmlc ensures the static verification and the static expansion of the Server Side Includes directives of the Web pages in the efficient and friendly way of a command-line compiler.

I How does it work ?

To generate HTML pages with htmlc, you simply write directives into your source pages; those directives are HTML comments that htmlc is able to find, interpret and execute to include the results of execution into the output file.

Directives for htmlc have the same syntax as directives for Apache servers (when corresponding directives exist for Apache). htmlc is thus a kind of compiler for HTML pages served by the HTTP server, since htmlc expands the server side macros written in the HTML source files. This way, the Apache server needs no more to parse files looking for directives: this has been done once and for all by htmlc. Furthermore, errors are detected during the expansion phase, not when pages are served (which is too late, since the erroneous page has already been served to the client anyway).

As an additional benefit, your source files are no more related to a specific HTTP server: htmlc directives need not to be rewritten when you change your HTTP server.

Not only your source files, but also the pages produced by htmlc are independent from any HTTP server. This is a desirable property that is mandatory if you want to browse your WEB site locally, even if no connection to the network is available. For instance, using htmlc, you obtain a WEB site that is directly usable on a CD-ROM: the pages expanded by htmlc are readable with any WEB browser, even if there is no HTTP server running on the user's computer.

II How can one use it ?

When writing HTML pages

Texts inclusion: where you want to include some text, write a directive to include the file containing that text. Such a directive is a single line with the name of the file to be included:
```

```
where ``name of the file to be included'' is the name of the file that contains the text.
Examples: systematic inclusion of the document type, or the page foot.
Search for files to be included: files are searched into a directory list, starting from the current directory. This list is modified using command line options for htmlc, -I directory_name that adds directory_name in front of the directory list.
Including text with no modification (programs for instance): HTML special characters are correctly escaped, such that the original ASCII text is readable into the HTML result (for instance < is expanded as <).
To include such a verbatim text, write
```

```
where ``name of the file to be included'' is the name of the file that contains the text.
Examples: including programs.
Search for verbatim files: those files are searched in the same directory list (search path) as other files to include.
Last modification date of the source file: write
```

```
and this comment is replaced by the date of the last modification of this source file.
Internationalization: htmlc tries to figure out the language of the source file, in order to include the dates in the corresponding language. The language is obtained from the name of the source file. The rules are the following:
- the name of the file is pattern matched against the pattern: filename-lang.extension (or filename.lang.extension), where
  - filename is a sequel of letters (the name of the file),
  - followed by the character - or .,
  - followed by a language marker lang, having 2 or 3 letters,
  - followed by a . character,
  - followed by a file extension (generally the 4 characters html).
  Then the language is the lang part of the file name, interpreted as Internet conventions for country names. If this interpretation fails, the language is supposed to be English.
- If the field lang is absent, and the extension is found, then filename is supposed to be the language indication.
- If the language cannot be found, it defaults to English.
- In this version of htmlc, supported languages are restricted to French and English. You're welcome to help me to add any additional language you want to.
- Examples: htmlc-eng.html has eng as language indication; this is interpreted as en, hence the document is supposed to be written in English. Similarly, htmlc.eng.html, eng.html, en.html, or en.ml are all supposed to be written in English.

During generation of final HTML pages

The HTML page generator is a command that treats files whose names are given on the command line. By default, result is written on the standard output; an output file can be specified using the option -t (or -to) followed by the file name of the output file. Input file can be specified using the option -f (or -from) followed by the input file name.

Usage: htmlc [-I] [include-dir] <source> <destination>
or htmlc <source>
or htmlc [-i|-f|-from] <source> [-o|-t|-to] <destination>

III How to use `htmlc` to handle a bundle of HTML files ?

First of all, we have to distinguish between sources of HTML files, and objects: sources are unexpanded files (those that we must edit), and objects are expanded files (those that we do not edit and that are automatically produced by htmlc).

We use the following conventions:

a source file has suffix .html,
an object file has suffix .htm.

A very good idea to manage the complexity of dealing with a lot of HTML files to expand is to carefully separate source and object files: object files belong to a directory that is accessible to the HTTP server (sometimes also called the WEB server), and we name it the WEB directory, since the files it contains are those sent to the net by the WEB server; on the other hand, source files belong to a directory that is only used by the WEB site editors, let's name it the SRC directory.

To handle all those files, the method we propose is to set up two Makefiles:

the file SRC/Makefile manage the expansion of source files to corresponding objects files.
the file WEB/Makefile handle the copy of the expanded object files from the SRC directory to the WEB directory.

Note that the WEB directory only contains the minimum set of files necessary to consult the WEB site. By contrast, the SRC directory has both source and objects files. Also, the SRC directory has a sub-directory for the files to include; we suppose that this sub-directory is named Includes; hence the expansion command will systematically have an additional option -I Includes.

Here is an example for the Makefile in the SRC directory
```
FILES=htmlc-fra.html htmlc-eng.html
HTMLC=htmlc -I Includes

OBJS=$(FILES:.html=.htm)

all: $(OBJS)

clean:
        rm -f $(OBJS)

.SUFFIXES:
.SUFFIXES: .htm .html

.html.htm:
        $(HTMLC) -f $< -t $@
```
To use this Makefile, you just have to fill in the FILES variable to specify the list of source files you need (the list written here corresponds to the htmlc documentation). If necessary, you can also specify the include directory by modifying the -I Includes option of the HTMLC variable.
Here is an example for the Makefile in the WEB directory (this file is also available here):
```
SRC=../doc_src
FILES=htmlc-fra.htm htmlc-eng.htm

AUTO=.Makefile.auto

all: $(AUTO) expand $(FILES)

expand:
        cd $(SRC); make

clean: $(AUTO)
        cd $(SRC); make clean
        rm -f $(FILES)

$(AUTO) : Makefile

$(AUTO):
        rm -f $(AUTO)
        for i in $(FILES); do         j=`basename $$i .htm`;         echo $$i: $(SRC)/$$j.htm >> $(AUTO);         echo >> $(AUTO);         echo $(SRC)/$$j.htm: >> $(AUTO);         echo -n "        chmod +w $$j.htm; " >> $(AUTO);         echo "cp -p $(SRC)/$$j.htm $$j.htm" >> $(AUTO);         done

include $(AUTO)
```
To use it, you just have to fill in the SRC and FILES variables to respectively specify the source directory and the list of source files you use. The method to build the site is to copy the object files from the $(SRC) directory. To achieve this goal the Makefile builds the set of copy rules corresponding to the set of files to create. Those rules are then automatically included into the Makefile by the last line (include $(AUTO)). So you need to initiate this process when installing the Makefile somewhere: you have first to create an empty set of rules, in order to be able to then run make to create the relevant rules; at first usage of the Makefile, type in:
```
touch .Makefile.auto
make
```
that creates the empty set of rule .Makefile.auto, and then allows the computation of the relevant set of rules before compiling the files.

Discussion

This organization into two separate directories has many advantages: the WEB site is clean, having a minimum set of files, and all the necessary auxiliary files are kept in the SRC directory; moreover changes to the source files are not immediately effective and visible from outside: source pages can be modified then expanded and verified before commitment to the online WEB site. And this commitment is easy: a simple make command in the WEB directory publishes all the modifications at once in a coherent way.

This setting has proved to be extremely efficient to write and develop the set of HTML pages that is the Caml language FAQ.

IV Examples

Including a header

To include the document type, you may just write as first line of your file:

  <!--#include virtual="doctype" -->

This directive includes the text of the file named doctype. If the file doctype contains:

  <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"
   "http://www.w3.org/TR/REC-html40/loose.dtd">

then the file

  <!--#include virtual="doctype" -->

  <HTML>

  <HEAD>
  <TITLE>Frequently asked questions about Caml</TITLE>
  </HEAD>

becomes

  <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"
   "http://www.w3.org/TR/REC-html40/loose.dtd">

  <HTML>

  <HEAD>
  <TITLE>Frequently asked questions about Caml</TITLE>
  </HEAD>

Including a footer

If we suppose the footer to be written in the file endofpage-eng.html, then just write:

  <!--#include virtual="endofpage-eng.html"-->

to include the footer in your HTML page. Then, if the file endofpage-eng.html contains:

   <P>
   <HR>
   <EM>Last modified: </EM>
   <!--#echo var="LAST_MODIFIED" -->
   <BR>
   <A HREF="copyright-eng.htm">Copyright</A>
   © 1997 - 2005 INRIA, all rights reserved.

the source file

  <!--#include virtual="endofpage-eng.html"-->

  </BODY>
  </HTML>

is then compiled by htmlc into:

   <P>
   <HR>
   <EM>Last modified: </EM>
   <!--#echo var="LAST_MODIFIED" -->
   Tuesday February 15 2005
   <BR>
   <A HREF="copyright-eng.htm">Copyright</A>
   © 1997 - 2005 INRIA, all rights reserved.

  </BODY>
  </HTML>

Including a program

To include the program text contained into the file exemple_caml.ml, just write:

  <!--#include verbatim="exemple_caml.ml"-->

Then, if exemple_caml.ml contains:

   let succ x = x + 1;;
   succ : int -> int = <fun>

the directive is replaced by:

   let succ x = x + 1;;
   succ : int -&gt; int = &lt;fun&gt;

HTML page templates

To facilitate the edition of the HTML pages of a WEB site, you can define a set of templates with include directives.
For instance, the following template defines the standard document type, footer and header:

  <!--#include virtual="beforetitle-eng.html"-->

  <!--#include virtual="aftertitle-eng.html"-->


  <!--#include virtual="endofpage-eng.html"-->

The page writer just writes the page title to obtain the following correct HTML file:

  <!--#include virtual="beforetitle-eng.html"-->
  The <CODE>htmlc</CODE> expander
  <!--#include virtual="aftertitle-eng.html"-->

  <H2 ALIGN=LEFT>What is it ?</H2>

  <P>One uses ...

  <!--#include virtual="endofpage-eng.html"-->

Since, if we suppose that:

the file beforetitle-eng.html contains:

    <!--#include virtual="doctype" -->
    <!-- File beforetitle-eng.html included before the page's title -->

    <HTML>

    <HEAD>
    <TITLE>

the file aftertitle-eng.html contains:

    <!-- File aftertitle-eng.html included after the page's title -->
    </TITLE>
    </HEAD>

    <BODY BGCOLOR="#FFFFFF">

    <!--#include virtual="hautdepage-eng.html"-->

the file endofpage-eng.html contains:

   <!-- File endofpage-eng.html included at the last line of the page -->
   <P>
   <HR>
   <EM>Last modification: </EM>
   <!--#echo var="LAST_MODIFIED" -->
   </BODY>
   </HTML>

the file hautdepage-eng.html contains:

   <ADDRESS>Contact the author <A HREF="mailto:Pierre.Weis@inria.fr">Pierre.Weis@inria.fr</A></ADDRESS>

and files doctype and endofpage-eng.html are as described above

Then from the file:

  <!--#include virtual="beforetitle-eng.html"-->
  The <CODE>htmlc</CODE> expander
  <!--#include virtual="aftertitle-eng.html"-->

  <H2 ALIGN=LEFT>What is it ?</H2>

  <P>One uses ...

  <!--#include virtual="endofpage-eng.html"-->

we get:

  <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"
   "http://www.w3.org/TR/REC-html40/loose.dtd">
  <!-- File beforetitle-eng.html included before the page's title -->

  <HTML>

  <HEAD>
  <TITLE>
  The <CODE>htmlc</CODE> expander
  <!-- File aftertitle-eng.html included after the page's title -->
  </TITLE>
  </HEAD>

  <BODY BGCOLOR="#FFFFFF">

  <ADDRESS>Contact the author <A HREF="mailto:Pierre.Weis@inria.fr">Pierre.Weis@inria.fr</A></ADDRESS>

  <H2 ALIGN=LEFT>What is it ?</H2>

  <P>One uses ...

  <!-- File endofpage-eng.html included at the last line of the page -->
  <P>
  <HR>
  <EM>Last modification: </EM>
  <!--#echo var="LAST_MODIFIED" -->
  mardi 15 février 2005
  <BR>
  <A HREF="copyright-eng.htm">Copyright</A>
  © 1997 - 2005 INRIA, all rights reserved.

  </BODY>
  </HTML>

We define a variable for the expansion of this very file:

 <!--#define $HtmlcVersion="3.5"-->

Now, the variable HtmlcVersion is known by the compiler. Hence

Voilà la version:
<!--#echo var="$HtmlcVersion"-->.

gives

Voilà la version:
3.5.

Well, this is a bit complex: no need to use a directive to expanse the value of a variable! It suffices to cite the variable in the text: after a proper preceding definition, Htmlc can simply replace the variable by its value. Just write:

Voilà la version: $HtmlcVersion

to obtain:

Voilà la version: 3.5.

Indeed, Htmlc is a cool tool to generate Web pages!

Contact the author Pierre.Weis@inria.fr