.-----------------------------------------------------------------
.-  htmlpp.txt  htmlpp documentation source
.-
.-  Written:    96/03/27  Pieter Hintjens <ph@imatix.com>
.-  Revised:    96/06/08
.-
.-  Copyright:  (c) 1996 iMatix N.V.
.-
.-  This file is the original source for the htmlpp documentation.
.-  Whenever I need to change the documentation, I edit this file,
.-  then run htmlpp to re-create the set of web pages.
.-
.-  The BASE variable tells htmlpp what to call the output files.
.-  Here, the files will be index.htm, index1.htm, index2.htm...
.-
.define BASE      index
.-
.-  These variables get put into the header of each HTML file.
.-
.define author    Pieter Hintjens
.define written   24 Feb 1996
.define revised   09 Jun 1996
.define version   1.41
.-
.-  The prelude.def file centralises various definitions that I
.-  don't want to clutter-up this file with.  This is just one of
.-  my habits.
.-
.include prelude.def

.-----------------------------------------------------------------
.ignore header
.page Htmlpp - The HTML Preprocessor

<H1>$(TITLE)</H1>

.-  This file builds a table of contents for the current document,
.-  i.e. all the pages that result from this original text file.
.-
.include contents.def
<H2>Overview</H2>

<P><EM>What is htmlpp?</EM>
<UL>
<LI>Htmlpp is a pre-processor for HTML documents.</LI>
<LI>It's purpose is to simplify the work of writing and packaging
large numbers of HTML documents.</LI>
<LI>It acts a bit like a compiler: you provide an input <EM>source
text</EM> and htmlpp produces the HTML documents from that.  This
is easier and safer than trying to edit and manage each separate
HTML document.</LI>
<LI>To use htmlpp, you should be happy writing HTML directly
without help from a special HTML editor.  This is not as hard as
it sounds, since HTML is mostly a simple language.</LI>
<LI>Htmlpp is free software, copyright (c) 1996 Pieter Hintjens
and iMatix.  It is distributed with full sources according to the
$(*gnugpl=GNU General Public License).</LI>
</UL></P>

<P><EM>What does htmlpp do?</EM>
<UL>
<LI>It breaks one input source text file into several HTML
documents. Typically you will want to edit a larger file (it is
faster and easier), but provide the information in smaller pieces
on-line (people can access it easier).  Htmlpp makes this
possible.</LI>
<LI>It lets you define symbols like <TT>version</TT> in one place,
then use these in the text like this: <TT>$\(version)</TT> so that
you can make changes in a single place only, not throughout the
text.</LI>
<LI>It creates tables of contents, and links to chain pages
together in sequence.</LI>
<LI>It adds headers and footers to pages, so that you can keep a
consistent style in all HTML pages.</LI>
</UL></P>

<P><EM>How do I use htmlpp?</EM>
<UL>
<LI>Take a look at $(*htmlpp.txt), which is the documentation
source for htmlpp's own on-line documentation.  This is the main
example for htmlpp.</LI>
<LI>The files in <TT>template.zip</TT> provide the basic template
for a new project.  This zip file is provided as part of the
$(*htmlpp.zip=htmlpp package).</LI>
<LI>Edit the source text using any text editor, then run htmlpp on
the source.  It produces a number of HTML files (extension .htm)
which you can test using a browser.</LI>
<LI>In general, htmlpp generates HTML pages that use <EM>relative
addressing</EM>, so that pages refer to each other without
specifying a host or path.  This allows you to test and use the
HTML pages on a local hard disk.</LI>
</UL></P>

<P><EM>Where do I get htmlpp?</EM>
<UL>
<LI>Htmlpp is available from the $(*SERVER=iMatix website) as
a $(*htmlpp.zip=zip file).</LI>
<LI>You may also want to do a search using a site like
$(*altavista=Alta Vista).</LI>
</UL></P>

<P><EM>What else should I know?</EM>
<UL>
<LI>Htmlpp uses Perl 4, and should be portable to Perl 5.  It does
not use any system-specific features, so will run on any box (it
was developed on MS-DOS).</LI>
<LI>Perl is a programming language written by Larry Wall that is
freely available for many platforms.  If you never installed or
used Perl, this is an excellent time to start.</LI>
<LI>Under MS-DOS, you will need $(*bperl=Big Perl) to process
large documents.</LI>
</UL></P>

.-----------------------------------------------------------------
.page Installing Htmlpp

<H2>$(TITLE)</H2>

<H3>Getting Htmlpp</H3>

<UL>
<LI>Htmlpp is available as a $(*htmlpp.zip=zip file) from the
$(*SERVER=iMatix website).</LI>
<LI>You need PKUNZIP for MS-DOS, $(*info-zip=Info-zip's unzip) for
most platforms, or some other compatible unzip tool.</LI>
<LI>You need (*perl=Perl 4.x or 5.x) for your platform, or
$(*bperl) for MS-DOS.</LI>
<LI>Htmlpp comes with a small example - its own documentation.
A larger example - the Libero documentation - is also on-line
as a $(*lrdoc.zip=zip file) from the iMatix website.</LI>
<LI>The free $(*weblint) tool is a useful way to check your web
pages for errors and style.</LI>
</UL>

<H3>Installation Under UNIX</H3>

<UL>
<LI>You must have Perl installed on your system.</LI>
<LI>Download and unzip $(*htmlpp.zip).</LI>
<LI>Install htmlpp and htmlpp.d in some convenient directory that
is accessible to everyone.  You should be familiar with the
mechanics of the Perl -I switch: you may need to play with this to
get Perl to find htmlpp.d correctly.</LI>
<LI>Make htmlpp executable and run it without arguments.  You
should get a message like this:<BR>
<PRE>Htmlpp - a HTML pre-processor Version $(version)
Written by Pieter Hintjens <ph@imatix.com>
Copyright (c) 1996 iMatix - http://www.imatix.com

syntax: htmlpp &lt;filename&gt;</PRE></LI>
</UL>

<H3>Installation Under MS-DOS</H3>

<UL>
<LI>You must have Perl installed on your system; I recommend that
you use $(*bperl=Big Perl). Bperl requires a 386 and a certain
amount of memory.  Check the documentation for details.</LI>
<LI>Download and unzip $(*htmlpp.zip).</LI>
<LI>Check htmlpp.bat - it assumes that the files are installed in
<TT>C:\SPECIAL</TT>, which is how my system is set-up.  Also, it
assumes that Big Perl is called <TT>bperl</TT>; it might be called
simply <TT>perl</TT>.</LI>
<LI>Install htmlpp, htmlpp.bat, and htmlpp.d in some convenient
directory that is on your path.</LI>
<LI>Change your <TT>autoexec.bat</TT> to define a variable
<TT>PERLLIB</TT>.  On my system, this is defined like this:
<TT>set perllib=c:\special;c:\gnutools</TT>.  Reboot or create a
new DOS window</TT>.
<LI>Run the <TT>htmlpp</TT> command it without arguments.  You
should get a message like this:<BR>
<PRE>DOS/4GW Professional Protected Mode Run-time  Version 1.96
Copyright (c) Rational Systems, Inc. 1990-1994
Htmlpp - a HTML pre-processor  Version $(version)
Written by Pieter Hintjens <ph@imatix.com>
Copyright (c) 1996 iMatix - http://www.imatix.com

syntax: htmlpp &lt;filename&gt;</PRE></LI>
</UL>

.-----------------------------------------------------------------
.page Getting Started

<H2>$(TITLE)</H2>

<P>The <TT>template.zip</TT> file that is supplied with htmlpp
contains the basis for a new project.  Unzip this file into a
working directory.  You'll find:
<UL>
<LI><TT>template.txt</TT> - template for new documentation text
files.</LI>
<LI><TT>prelude.def</TT> - standard definitions - e.g. page header
and footer.</LI>
<LI><TT>contents.def</TT> - build table of contents.</LI>
<LI><TT>filetype.def</TT> - definitions for various file
types.</LI>
</UL></P>

<P>As a start, run htmlpp on template.txt:</P>
<PRE>C:\SOMEDIR\&gt;htmlpp template.txt</PRE>
<P>This creates a set of HTML files.  You can open
<TT>index.htm</TT> with a browser, and the links should work.</P>

<P>Htmlpp creates a file called <TT>errors.lst</TT> which
contains any errors.  This file is useful if you are building
really large documentation kits, and messages scroll off the
screen.</P>

.-----------------------------------------------------------------
.page Htmlpp Reference

<H2>$(TITLE)</H2>

<H3>Description</H3>

<P>Htmlpp is a preprocessor for HTML files, and is intended to
simplify the task of maintaining large sets of HTML documents.
You provide htmlpp with a document that is a mix of HTML-tagged
text and htmlpp commands.  Htmlpp generates a set of HTML files
from that document.</P>

<P>During this process, htmlpp replaces symbols, reads include
files, builds tables of contents, and generally does a lot of
otherwise tedious and error-prone manual work.  To use htmlpp you
should be happy writing HTML with a simple text editor.</P>

<H3>Inserting Symbols</H3>

<P>Htmlpp replaces symbols in command lines and HTML text.  You
can specify a symbol in various ways:</P>

<DL>
<DT>$\(name)</DT>
<DD>Inserts the symbol <EM>name</EM>.  If the symbol is not
defined (see .define command below) you get an error message.</DD>
<DT>$\(*name)</DT>
<DD>Inserts an anchor for the symbol <EM>name</EM>.  This is
shorthand for:
<PRE>&lt;A HREF="$\(name)"&gt;name&lt/A&gt.</PRE>
If the symbol <EM>name</EM> has an empty value, the &lt;A...&gt;
and &lt;/A&gt; tags are left-out - i.e. the link is not
active.</DD>
<DT>$\(*name=label)</DT>
<DT>$\(*name="label")</DT>
<DD>Inserts an anchor for the symbol <EM>name</EM>, with label as
specified. This is shorthand for:
<PRE>&lt;A HREF="$\(name)"&gt;label&lt;/A&gt;.</PRE>
If the symbol <EM>name</EM> has an empty value, the &lt;A...&gt;
and &lt;/A&gt; tags are left-out. You can use double quotes if the
label itself contains ')'.</DD>
<DT>$\(*name=)</DT>
<DD>Inserts an anchor for the symbol <EM>name</EM>, with the full
reference as label.  This is shorthand for:
<PRE>&lt;A HREF="$\(name)"&gt;$\(name)&lt;/A&gt;.</PRE></DD>
<DT>\\(</DT>
<DD>Replaces this by (.  This is to 'escape' symbol definitions so
that they are not translated.</DD>
<DT>\.</DT>
<DD>Replaces "\." at the start of a line by ".".  Without this, dots
at the start of a line are interpreted as htmlpp commands.</DD>
</DL>

<P>You can define symbols in terms of symbols: $\($\(name)) is
quite okay, if you know what you are doing.  Htmlpp inserts
symbols in the above order, so it will translate all $\(name)'s
before looking at $\(*name)'s.</P>

<H3>Types of Symbol</H3>

<P>Symbols are of various types
<UL>
<LI>htmlpp provides various symbols when building certain blocks
like the table of contents;</LI>
<LI>htmlpp provides various symbols containg default values that
you can redefine if necessary;</LI>
<LI>you can define symbols using the .define command;</LI>
<LI>you can define symbols using the .build anchor command.</LI>
</UL></P>

<H3>Standard Symbols</H3>

<P>Htmlpp provides these standard symbols for use at any point in
the document:
<DL>
<DT>$\(DATE)</DT>
<DD>The current date, formatted as an 8-character string:
YY/MM/DD.</DD>
<DT>$\(TIME)</DT>
<DD>The current time, formatted as an 8-character string:
HH:MM:SS.</DD>
<DT>$\(INC)</DT>
<DD>A counter, which starts at zero and is bumped-up each time you
refer to it.  I use this to number filenames, in the .page
command.  The first time you use $\(INC), it is empty - i.e. "".
The second time it is "1", then "2", "3", "many", "manymany", and
"manymanymany".</DD>
<DT>$\(PAGE)</DT>
<DD>After a .page command, this holds the page filename, exactly
as specified in the .page command.</DD>
<DT>$\(TITLE)</DT>
<DD>After a .page command, this holds the page title.  It is nice
to use this in the header .block.</DD>
<DT>$\(PASS)</DT>
<DD>Contains either 0 or 1, depending on whether htmlpp is
scanning for titles (0) or building the output files (1).
You may also need to .define some of these symbols:</DD>
<DT>$\(BASE)</DT>
<DD>Defined as "doc".  This is used in .page commands for
automatic filename generation.</DD>
<DT>$\(EXT)</DT>
<DD>Defined as "htm", and commonly-used hot on the heels of a
$\(BASE).</DD>
<DT>$\(SILENT)</DT>
<DD>Defined as 0.  If you .define this as 1, htmlpp will try to be
a bit quieter.  When you are generating *lots* of pages, it is
easy to lose real warnings and errors amidst the information
messages.</DD>
</DL>
Unless you use .ignore pages, these symbols are available in
header and footer blocks (you can use them elsewhere, but you'll
get warnings):
<DL>
<DT>$\(FIRST_PAGE)</DT>
<DD>The filename for the first page of the document.</DD>
<DT>$\(LAST_PAGE)</DT>
<DD>The filename for the last page of the document.</DD>
<DT>$\(NEXT_PAGE)</DT>
<DD>The filename for the next page of the document.</DD>
<DT>$\(PREV_PAGE)</DT>
<DD>The filename for the previous first page of the document.</DD>
<DT>$\(FIRST_TITLE)</DT>
<DD>The title for the first page of the document.</DD>
<DT>$\(LAST_TITLE)</DT>
<DD>The title for the last page of the document.</DD>
<DT>$\(NEXT_TITLE)</DT>
<DD>The title for the next page of the document.</DD>
<DT>$\(PREV_TITLE)</DT>
<DD>The title for the previous first page of the document.</DD>
</DL></P>

<H3>Htmlpp commands</H3>

<P>A htmlpp command starts with a dot, in column 1.  These are the
commands that htmlpp understands:
<DL>
<DT>.define <EM>symbol</EM> [<EM>value</EM>]</DT>
<DD>Define a symbol with the specified value.  The symbol name can
consist of letters, digits, -, ., and _.  The value is everything
else up to the end of the line.  If you omit the value, the
variable is un-defined.  You can redefine a variable as often as
you like simply by repeating the .define command.  Use lowercase
for your own symbols.  Predefined htmlpp symbols are uppercase.
Case is significant.  You can assign values to the built-in htmlpp
variables like INC if you want to.  In some cases this is even
useful.</DD>
<DT>.define <EM>symbol</EM> = <EM>expression</EM></DT>
<DD>Evaluates the expression and stores the result in symbol.
Note that you must use '=' to evaluate an expression.  Otherwise
the expression is considered as a string and stored as-is in the
symbol.  Htmlpp passes the expression to Perl for evaluation, so
you can use any valid Perl syntax.  If you want your htmlpp files
to be portable to (future) non-Perl implementations of htmlpp,
restrict the expressions to simple arithmetic (+, -, *, /, and
parentheses).  If you decide to rely on Perl, you can use the
<B>.define =</B> command to execute shell commands, e.g.:
<PRE>
\.if $\(PASS)
\.define junk = system "rm *.htm";
\.endif
</PRE></DD>
<DT>.include <EM>filename</EM></DT>
<DD>Start reading from the specified file.  You can nest .include
files as much as you like.  Htmlpp checks for circular references.
If the same file was already included earlier, htmlpp ignores the
command, like the Perl 'require' operator.</DD>
<DT>.include <EM>filename</EM>!</DT>
<DD>Include the file in any case, like a C #include
directive.</DD>
<DT>.page <EM>filename</EM> = ["]<EM>title</EM>["]</DT>
<DD>Start writing a new HTML file.  The title is required.  At any
point after the .page, you can refer to $\(PAGE) and $\(TITLE) for
the current file name and title.  For instance, you'll often see
this:
<PRE>
<EM>H1</EM>$\(TITLE)<EM>/H1</EM>.
</PRE></DD>
<DT>.page ["]<EM>title</EM>["]</DT>
<DD>Equivalent to .page $\(BASE)$\(INC).$\(EXT) =
"<EM>title</EM>".  Just easier.</DD>
<DT>.ignore header</DT>
<DD>Ignore the next header line as far as the table of contents is
concerned.  This is good for headers like <EM>H2</EM>Table of
Contents<EM>/H2</EM>.</DD>
<DT>.ignore header <EM>level</EM></DT>
<DD>Ignores all headers with level greater or equal to level.
This is useful if a section has a lot of H3 and H4's that you
don't want in the table of contents.  Use .ignore header 99 to re
include all further headers.</DD>
<DT>.ignore pages</DT>
<DD>Ignore all .page commands except to pick-up the page titles.
Use this when you want to create a super-document.  When you use
\.ignore pages, htmlpp also ignores the .build toc and .build index
commands. So, if you want a table of contents, do the .build toc
before you say .ignore pages.  You can also use .if commands to
skip blocks of text under certain conditions.</DD>
<DT>.if <EM>expression</EM></DT>
<DT>[.else]</DT>
<DT>.endif</DT>
<DD>If the expression returns a false value, htmlpp skips until
the .else or .endif line.  You can nest .if blocks.  An .else is
always part of the closest preceding .if.  Htmlpp passes the
expression to Perl for evaluation, so you can use any valid Perl
syntax.  If you want your htmlpp files to be portable to (future)
non-Perl implementations of htmlpp, restrict your expressions to
simple arithmetic and logical tests (<EM>, </EM>, =, etc).
Otherwise, enjoy Perl's vast range of tests.  This is quite okay:
<PRE>.if -f myfile.htm</PRE>
An .if block must be entirely in one line.</DD>
<DT>.block <EM>blockname</EM></DT>
<DD>Define a piece of HTML text to be output as part of a .build
command.  You can end the .block with an .end or another .block.
Htmlpp knows about these block names:
<DL>
<DT>header</DT>
<DD>Output at the start of each new HTML page; i.e. whenever you
use a .page command.</DD>
<DT>footer</DT>
<DD>Output at the end of each HTML page.</DD>
<DT>toc_open</DT>
<DD>Output at the start of a .build toc block (see below), and
whenever htmlpp decides to indent a new level.</DD>
<DT>toc_entry</DT>
<DD>Output for each entry in the table of contents.  Use these
symbols: $\(TOC_HREF) - the local URL for the file and section;
$\(TOC_TITLE) - the title for the section, taken from the header
line.</DD>
<DT>toc_close</DT>
<DD>Output whenever htmlpp decides to outdent a level, and at the
end of the table of contents.</DD>
<DT>dir_open</DT>
<DD>Output at the start of a .build dir block (see below).</DD>
<DT>dir_entry</DT>
<DD>Output for each entry in a .build dir block.  Use these
symbols: $\(DIR_HREF) - URL for the file; $\(DIR_NAME) - the
filename, left-justified; $\(DIR_EXT) - the file extension, always
put into lowercase; $\(DIR_SIZE) - the file size, right-justified;
$\(DIR_DATE) - the file date; $\(DIR_TIME) - the file time.</DD>
<DT>dir_close</DT>
<DD>Output at the end of a .build dir block (see below).</DD>
<DT>index</DT>
<DD>Output for each entry in a .build index block.  Use these
symbols: $\(INDEX_PAGE) - the filename; $\(INDEX_TITLE) - the file
title.</DD>
<DT>anchor</DT>
<DD>Output whenever you use a .build anchor.  Use this symbol:
$\(ANCHOR) - name of anchor.</DD>
</DL>
<DT>.end</DT>
<DD>End the previous .block.  You can end a .block with an .end or
a further .block command.  Any other command within a .block is a
syntax error, which is something that I may change in the
future.</DD>
<DT>.build toc</DT>
<DD>Build table of contents for document.  Htmlpp scans the
document and all include files once to collect titles
(&lt;Hn&gt;...&lt;/Hn&gt;) and once to create the HTML pages.
Titles (&lt;Hn&gt;...&lt;/Hn&gt;) must be entirely on a single
line, or htmlpp will not find them.  You can manage the contents
of the table of contents through the .ignore header command. You
will normally use a .build toc at the start of a document.</DD>
<DT>.build dir <EM>directory</EM> [<EM>filespec</EM>...]</DT>
<DD>Build directory listing as specified.  The .build dir command
only works if you mirror the server directory on some local disk
that htmlpp can access.  This is a Good Idea in any case.  Before
you can use .build dir you must define LOCAL and SERVER.  I define
these like this:
<PRE>
\.define LOCAL   I:
\.define SERVER  http://www.imatix.com
</PRE>
The directory must be relative to either of these two.  It should
start with '/' but not end with '/'.  You can specify zero or more
filenames or wildcards (htmlpp accepts * and ?, according to UNIX
rules).  If you specify no filespecs, htmlpp assumes you mean '*'.
The filespecs can include PERL regular expressions: place the
filespec between double quotes, e.g. to match all files with 'doc'
or 'txt' somewhere in the name: .build dir /pub "doc|txt".  An
example might help:
<PRE>
\.define .txt   Text file
\.define .htm   HTML document
\.define .zip   ZIP archive
\.block dir_open
&lt;PRE&gt;
\.block dir_entry
$\(*DIR_HREF="$\(DIR_NAME)") $\(DIR_SIZE)  $\($\(DIR_EXT))
\.block dir_close
&lt;/PRE&gt;
\.end
</PRE>
Note the sneaky double-derefencing of $\(DIR_EXT) which translates
the file extension into a comment like 'Text file'.  I usually
stick all such .defines in a separate .include file,
filetype.def.</DD>
<DT>.build index</DT>
<DD>Build file index for document.  This is basically a list of
all pages in the document with their titles.  You may find a use
for this; I put it in for completeness.</DD>
<DT>.build anchor <EM>anchor-name</EM></DT>
<DD>Build an anchor definition.  This is real useful.  Basically
you do a .build anchor somename in a document, then do a
$\(*somename) or $\(*somename="label") anywhere in any other
document.  Htmlpp saves anchor symbols in the file anchor.def;
otherwise anchor symbols are treated much like normal .define'd
symbols.  One difference: anchor symbols and normal symbols do not
share the same namespace; if you .define a symbol with the same
name as the anchor symbol, the .define'd symbol takes precedence.
If you undefine the symbol, the anchor symbol reappears by magic.
This may or may not be useful, but it is the way it works.  If you
change the file structure of your document, run everything through
htmlpp *TWICE*, so that all anchor references can get really
solidly updated.</DD>
<DT>.echo [-] <EM>text</EM></DT>
<DD>Echoes the text to the console.  Strips-off any leading and
trailing spaces, but you can enclose the text in single or double
quotes if you want leading/trailing spaces.  Unless you place a
hyphen before the text, htmlpp adds a newline.</DD>
</DL>

.-----------------------------------------------------------------
.page Other Information

<H2>$(TITLE)</H2>

<P>The most recent version of htmlpp is located at $(*SERVER=).
You can download it from $(*htmlpp.zip=).</P>

<P>The Libero documentation is one example of htmlpp in action.
Download the archive $(*lrdoc.zip) to get hold of a set of text
and definition files for htmlpp.</P>

<P>If you want to change htmlpp, get a hold of the camel book
(Programming Perl), and the Libero documentation.</P>

<H3>Bugs and Limitations</H3>

<P>Htmlpp does not have any bugs that I know of.  The tool does
not scan over line breaks, so all commands and symbols must fit
onto a single line.</P>

<H3>Product History</H3>

<UL>
<LI>Version 1.0 written 3 April, 1996.</LI>
<LI>Version 1.1 released 6 April 1996.</LI>
<LI>Version 1.2 escaped around 13 April 1996.<BR>
V1.21 - sorted '.build dir' entries by name.<BR>
V1.22 - headers anchors changed to include whole line.</LI>
<LI>Version 1.3 published 13 May 1996.<BR>
V1.31 - improved documentation and packaging.</LI>
<LI>Version 1.4 published 9 Jun 1996.<BR>
V1.41 - log errors in separate listing file.</LI>
</UL>
