Htmlc : a text file generator

Version 2.6

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

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.

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:
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="2.6"-->
Now, the variable HtmlcVersion is known by the compiler. Hence
Voilà la version:
<!--#echo var="$HtmlcVersion"-->.
gives
Voilà la version:
2.6.

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: 2.6.
Indeed, Htmlc is a cool tool to generate Web pages!


Contact the author Pierre.Weis@inria.fr

Creation date: February 20, 2000
Last modification date: Monday, March 21st, 2011 (on host double-glazed , by user cfranchi).
Copyright © 1997 - 2014 INRIA, all rights reserved.