#define TITLE GTML - an HTML pre-processor
#include "header"

<label>toc2</label>
<p>
<ul>
  <li><url>#intro,Introduction</url>
  <li><url>#how,How does _gtml_ work ?</url>
  <li><url>#you,Is _gtml_ for you ?</url>
  <li><url>#features,_gtml_ features.</url>
  <li><url>#download,Downloading _gtml_</url>
  <li><url>#running,Running _gtml_</url>
  <li><url>#other,Other HTML pre-processors</url>
  <li><url>#license,Terms of license</url>
  <li><url>#history,A little bit of _gtml_ history</url>
</ul>

<p><hr>

<label>intro</label>
<p>HTML is a powerful markup language for individual Web pages, but it
has some serious limitations for maintaining entire Web <em>sites</em>
(i.e. a collection of Web pages which needs to be kept consistent).

<p>_gtml_ is an HTML pre-processor which adds some extra features
specially designed for maintaining multiple Web pages.


<label>how</label>
<h2>How does it work?</h2>

<p>You embed _gtml_ commands among the HTML in your source files.
_gtml_ reads and processes the _gtml_ commands, but leaves the
rest of the text unchanged (so it will work straight away on your
existing Web pages).

<p>HTML files generated by _gtml_ are just like any other HTML files.
Because _gtml_ doesn't attempt to interpret your HTML commands in
any way, it's fully compatible with <em>all</em> versions of HTML, and
doesn't require any specific browser or server.


<label>you</label>
<h2>Is _gtml_ for you?</h2>

<p>If you write the HTML in your Web pages by hand using a simple text
editor, then you'll find _gtml_ useful. If, on the other hand,
you use a sophisticated graphical tool to generate your HTML, you
probably won't be able to use _gtml_. There are three reasons for this:
<ul>
  <li>Your sophisticated tool won't understand the _gtml_
      commands, and might even complain violently about them.
  <li>_gtml_ operates in a command-line <em>batch</em> mode, and your
      sophisticated tool probably operates from a graphical environment.
  <li>The <em>source</em> for _gtml_ is in files ending in <ext>.gtm</ext>
      (or <ext>.gtml</ext>), and it generates the <ext>.html</ext>
      files. Your sophisticated tool probably generates the <ext>.html</ext>
      files itself. 
</ul>


<label>features</label>
<h2>Features</h2>

<p>Here are some of the things you can do with _gtml_:
<ul>
  <li>Create a <em>project file</em> with the names of all your Web pages, so
      you can update them all with one simple click or command. 
  <li>Process only files which sources have changed directly, or with the help
      of makefiles. 
  <li>Generate a <code>makefile</code> to control the process of your Web pages,
      based on their dependencies.
      _new_
  <li>Give a specific alias to a filename, useable as constants, so that it is
      easy to move files and have links preserved.
  <li>Specify a tree-like hierarchy of Web pages, so you can add Next,
      Previous and Up links automatically to your site.
  <li>Automatically generate a map of your site, with the possibility of
      customizing the way this table of contents will look like.
      _new_
  <li>Use named constants for HTML fragments to save typing, ensure
      consistency and make changes easily. 
  <li>Use environment variables as named constants.
  <li>Include header, footer and other common files into all your HTML
      files. <em>This doesn't require Server-Side Includes</em>. 
  <li>Include timestamps (in any format you like) to show the time of last
      process, or of last modification. 
  <li>Use conditional commands to create different versions of the output
      under different circumstances. 
  <li>Generate output to different directories to generate different versions
      of your site (for example, a Frames version and a non-Frames version). 
  <li>Change extensions of output files from <ext>.html</ext> to whatever
      you want, so that you may, for instance, use MultiViews options of
      Apache server, or create non-HTML files.
      _new_
  <li>Guard special characters `&lt;', `&gt;' and `&amp;' in normal text so
      that they don't get confused with HTML commands.
  <li>Define your own characters translations, so that you may easily input
      your non-ASCII characters into _gtml_ source.
      _new_
  <li>Embed <code>Perl</code> or <code>shell</code> code into your source, so
      that you may easily generate pages with computed information.
      _new_
  <li>Generate pages with all superfluous HTML code removed, so that readers
      retrieve them faster and may save bandwidth.
      _new_
</ul>

<p>All the _gtml_ features and commands are described on the
<url>[[REF]],_gtml_ Reference page</url>. 


<label>download</label>
<h2>Downloading _gtml_</h2>

<p>_gtml_ is written in Perl. If you don't have Perl, it's easy to
<url>http://www.perl.com/pace/pub/perldocs/latest.html,obtain it</url> on
<url>http://www.perl.com,perl.com</url>. 

<p>There are two methods to download _gtml_:
<ul>
  <li><url>gtml,Download _gtml_</url> Perl script, and save it to a file called
      <file>gtml.pl</file>. <em>If you're running this under UNIX, edit
      the first line to point to the location of your version of
      Perl</em>, and give the execute right to the file. 
  <li>Download _gtml_ archives containing Perl script as well as
      documentations. Archives are available in
      <url>_ftp_gtml.zip,zip format</url>
      or <url>_ftp_gtml.tar.gz,gzipped tar format</url>.
</ul>

<p>The home page of _gtml_ is at <file><surl>_www_</surl></file>,
and archives may be found at <file><surl>_ftp_</surl></file>.


<label>running</label>
<h2>Running _gtml_</h2>

<p>_gtml_ source files end in <ext>.gtm</ext> (or <ext>.gtml</ext>), not
<ext>.html</ext>. If you're using _gtml_ on existing HTML files, simply
rename them with the ending <ext>.gtm</ext> (or <ext>.gtml</ext>).

<p>_gtml_ is run from the command line, like this:
<pre>
     perl gtml.pl fred.gtm harry.gtm bill.gtm
</pre>

<p>(The UNIX version won't need the <code>Perl</code> at the front, so long as
the script is executable.)

<p>The output of this command will be in <file>fred.html</file>,
<file>harry.html</file> and <file>bill.html</file>. 

<p>If you have a <url>[[REF]]#project,_gtml_ project file</url>,
you include this on the command line. In this case, it's not necessary to list
any of the files in the project as well. 

<p>Remember that you <url>[[REF]]#optiond,can use <cmd>-D</cmd></url> on the
command line to create named constants. You can have as many <cmd>-D</cmd>
options as you like. Make sure they appear <em>before</em> the file names to
which they apply. For example, if you say:
<pre>
     perl gtml.pl -DNAME=Fred fred.gtm harry.gtm -DTYPE=car bill.gtm
</pre>
then <code>NAME</code> is defined for all three files and <code>TYPE</code>
is defined for <file>bill.gtm</file> only.

<p>By default, _gtml_ will try to process some
<url>[[REF]]#project,project file</url>. It will look at these <em>configuration</em>
files in this order:
<ul>
  <li><file>$HOME/.gtmlrc</file>
  <li><file>$HOME/gtml.conf</file>
  <li><file>.gtmlrc</file>
  <li><file>gtml.conf</file>
</ul>

<p>Thoses files, if they exist, are parsed before command line is processed.

<p>You may have a look at the source of the documentation pages of _gtml_ in
the <url>src,source directory</url>. The project file is called
<url>src/gtml.gtp,<file>gtml.gtp</file></url>.


<label>other</label>
<h2>Other HTML pre-processors</h2>

<p>Here is a list of other HTML pre-processors that I know of, in
case _gtml_ will not satisfy your needs:
<ul>
  <li><url>http://chakotay.ist.org,Chpp</url>
  <li><url>http://frontier.userland.com,Frontier</url>
  <li><url>http://www.metahtml.com,Meta-HTML</url>
  <li><url>http://www.php.net,PHP</url>
  <li><url>http://www.qml.org/,QML</url>
  <li><url>http://artho.com/webtools,Webtools</url>
  <li><url>http://www.engelschall.com/sw/wml/,WML</url>
  <li><url>http://www.geocities.com/Tokyo/1474/wpp,Wpp</url>
</ul>


<label>license</label>
<h2>Licensing</h2>

<p>_gtml_ is distributed under the <url>COPYING,GNU General Public License</url>
(GPL). 

<p>Copyright <c> 1996-1999
<url>http://www.pobox.com/~gihan,Gihan Perera</url>
 (<mail>gihan@pobox.com</mail>)

<p>Copyright <c> 1999
<url>http://www.lifl.fr/~beaufils,Bruno Beaufils</url>
 (<mail>beaufils@lifl.fr</mail>)

<p>This program is free software; you can redistribute it and/or modify it
under the terms of the GNU General Public License as published by the Free
Software Foundation; either version 2 of the License, or (at your option) any
later version.

<p>This program is distributed in the hope that it will be useful, but WITHOUT
ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
FOR A PARTICULAR PURPOSE.  See the
<url>http://www.gnu.org/copyleft/gpl.html,GNU General Public License</url>
for more details.


<label>history</label>
<h2>Some history</h2>

<p>For a long time I was looking for a way of maintaining some of the sites 
that I set up for the research team which I am member of. I wanted to get a 
tool which would enable me to easily change the look and feel of all pages of 
a site, and easily move pages of a site from one location to another.

<p>I then used all my favourite search engines on the web, and found some
pages, describing such tools. I tried some. They all missed something, from ease
of use, to important features. When I tried _gtml_, from Gihan, I found
it was pretty cool, but lacking some important features that I needed.

<p>I wrote to Gihan asking him to add those features which I needed, since I 
had no Perl programming skill. He told me that he doesn't have time to do that
 in the near future. So I decided to read his code, and to learn Perl with his
script.

<p>The script was pretty well written and I learnt Perl, or at least understand
how _gtml_ worked very fast. It was then easy to add the features that I needed in it. I then asked Gihan if he would mind if I distribute _gtml_ under the
GNU General Public License, since his license policy was not as open as GPL,
and he accepted.

<p>Then I just updated some of the docs, prepared an archive, in the
<url>http://www.gnu.org,GNU</url> spirit, and that was it.

<p>My biggest question was to understand where the name of the tool come from,
and after some reflexions I got two possible answers:
<ul>
  <li><car>G</car> is the letter just before H, and _gtml_ source production
      comes just before HTML file one.
  <li><car>G</car> is the first letter of Gihan's first name.
</ul>

<p>Well this is not a question anymore, Gihan told me the truth. Guess
what? I found it: the first of my two previous hypotheses is the right  
one. (Well I hope that as time goes by it will be interpreted as GNU
<code>:-)</code>  

<p>After I distributed it on my web pages, and after announcing it only on
<url>http://www.freshmeat.net,Freshmeat</url>,
I got some feedback from users coming from all around the world. I added some
features which were asked of me, but realized that the source of the script
needed some reorganization, and that there were some bugs in _gtml_.

<blockquote>
I have done this source reorganization, and so have been able to fix bugs,
and add a lot of fancy features. So now I'm waiting for users' feedback, in 
order to verify that I did not add bugs <code>:-)</code>, and that _gtml_ is now
sufficiently stable.
</blockquote>

<p>In one month or so I hope to be able to say that it does. So I
<em>really</em> need your help for that, please <em>give me some feedback!</em>.

<p>I will not add any features, before the next <em>stable</em> release.

<p>I hope my version of _gtml_ will help you as it helps me.

<p>--Bruno, <em>31 August 1999</em>

#include "footer"

<!-- Local Variables: -->
<!-- mode: html-helper-mode -->
<!-- End: -->
