|
The Guava Toolshtt2html
|
Home Computer Software Guava Main Page Guava Manual Pages
NAME
htt2html - Converts an htt template file into HTML.
SYNOPSIS
htt2html [options] input-file
DESCRIPTION
htt2html is a Perl program that produces single or multi-
page HTML documents using a template file.
htt2html produces hss files and a cross-reference file and
then uses hss2html to produce HTML files.
OPTIONS
-v Be verbose.
-nocont
Turn off contents file generation. The default
behaviour is to generate a contents file. If the
pages being created are not part of a single docu-
ment but share the same template, you may not want
a contents file.
-o name
The name of the contents file. The default is
"index". If the supplied name does not have a
filename extension the output filename extension
(as specified by -outext) will be appended.
-op name
The name of the page files. The default is "out".
Page names will have two digit numbers added,
beginning with "01". The output filename extension
(as specified by -outext) will also be appended.
-Dmacro[=defn]
Predefine macro, with definition defn. If defn is
not specified, the value "1" will be used.
-Idir Add dir to the list of directories to be searched
when processing #include. The directory containing
the input file is always searched.
-M Causes htt2html to generate dependency information
in a form suitable for use with make(1). The
dependency information is written to stdout and the
program terminates without creating any normal out-
put.
The target file name will be the name of the con-
tents page, or the name of the first page if no
contents page is produced.
-MG Treat missing included or imported files as gener-
ated files, rather than stopping with an error mes-
sage. It is assumed that these files will be cre-
ated in the current directory. If you specify -MG
you must also specify -M.
-MX Consider extra files (the cross reference and full-
ref data files) for inclusion in the dependency
list generated by -M. The appropriate files will
only be added to the list when the <REF> and <FULL-
REF> tags are found in the input. If you specify
-MX you must also specify -M.
-Mp This option produces a line of dependency output
for each page produced, rather than a single line
for only the first page which is the default when
-M is used alone. The dependency information gen-
erated by -Mp will be the same for each page. If
you specify -Mp you must also specify -M.
-d Compare the generated output files with any exist-
ing files of the same name and replace only if
there are changes. This option is passed through
to the hss2html program. See the manual page for
hss2html(1) for more information.
-version
Print version information and exit.
INFREQUENTLY USED OPTIONS
-hm tag
Sets the field marker for the header section of the
data file. The default is "<HDR%PAGE%>".
The word %PAGE% marks the point at which the
optional page name override will be expected to
occur.
-hpm marker
Sets the marker for the position of the page name
override in the header marker tag. The default is
"%PAGE%", as seen in the default value for the -hm
option. In the unlikely event that the default
marker conflicts with something in your -hm string,
you will have to use this option to specify an
alternative.
-dm tag
Sets the field marker for the data section of the
data file. The default is "<DATA>".
-cm tag
Sets the insertion point marker for the contents
entries on the contents page. The default is
"<CONTENTS>".
-tm tag
Sets the insertion point marker for the page data
in the page template. The default is "<PAGE>".
-def string
The define string (default is "#define %NAME%
%DEF%"). You'll only need to change this if you
use something other than the C preprocessor.
The words %NAME% and %DEF% are insertion point
markers that will be replaced with the name of the
macro and the definition when htt2html writes out
the automatic definition.
The define string must contain both of the inser-
tion point markers, although the markers themselves
can be redefined using the -defnmarkand -defdmark
options.
-undef string
The undefine string (default is "#undef %NAME%").
You'll only need to change this if you use some-
thing other than the C preprocessor.
The %NAME% insertion point marker works as
described for the -def option.
-defnmark marker
Sets the insertion point marker for names in the
-def command string. The default is "%NAME%". In
the unlikely event that the default marker con-
flicts with something in your -def string, you will
have to use this option to specify an alternative.
-defdmark marker
Sets the insertion point marker for names in the
-def command string. The default is "%DEF%". In
the unlikely event that the default marker con-
flicts with something in your -def string, you will
have to use this option to specify an alternative.
-cpre string
Set the prefix used for contents macro names. The
default is "_C_".
-x name
The full name of the cross-ref file. The default
is "index.xref".
-rfile name
The name of the data file containing local and
remote directory pairs for the FULLREF macro in the
hss2html program. The default is "fullref.dat".
-intext ext
The filename extension for intermediate files.
Default is ".hss".
-outext ext
The filename extension for output files. Default
is ".html".
-hssprog name
The program to be used to convert .hss files to
.html. The default is "hss2html".
-hssopts opts
Additional options to pass to the hss2html program.
-p Do not use cpp(1) line control.
Line control allows error messages to correspond to
the line in the source file where they actually
occur. This is useful, so line control is turned
on by default.
ANSI cpp(1) compatible line control codes are used.
If your preprocessor does not understand these, you
may need to use this option to turn off line con-
trol.
-pname name
Add a page name to the list that will be used
instead of the default page names or names speci-
fied in the header marker tags. This option may be
used multiple times to add more than one name to
the list. Pages created using names from this list
will have the output filename extension (as speci-
fied by outext) appended. If more pages are cre-
ated than there are names in the list, the naming
will revert to the default, using page names speci-
fied by the -op option, or in the header marker
tags.
It is recommended that the mechanism of page name
overrides in the header marker tag be used instead
of the -pname option. If using -pname in conjuc-
tion with page name overrides, names specified
using -pname have the highest priority.
THE INPUT FILE
htt2html reads a single input file. The first part of the
file is the template, which will be used for all the gen-
erated pages. The template part of the file is followed
by the data for each of the pages, including the contents
page.
The input file structure is as follows:
--- Start of htt2html input file. ---
Template text before the page data.
<PAGE>
Template text after the page data.
<HDR>
Header data for the contents page
<DATA>
Text before the contents list.
<CONTENTS>
Text after the contents list.
<HDR>
Header data for the first page.
<DATA>
Text for the first page.
<HDR>
Header data for the second page.
<DATA>
Text for the second page.
etc...
--- End of htt2html input file. ---
The template is the part of the file up to the first
"<HDR>" marker. The "<PAGE>" tag is the page data inser-
tion point, where the text for each page will be inserted
into the template.
The data for each page consists of a pair of "<HDR>" and
"<DATA>" tags, with lines of data following each. Data
following the "<HDR>" tag will be inserted at the begin-
ning of the template, and data following the "<DATA>" tag
will be inserted at the position marked by the "<PAGE>"
tag in the template.
The "<CONTENTS>" tag marks the position on the first page
where the table of contents will be inserted.
The "<HDR>", "<DATA>", "<PAGE>", and "<CONTENTS>" tags
must be the only text on a line.
In addition to the header data, a number of system gener-
ated definitions will be written into the output files.
These lines will appear between the header data and the
beginning of the template.
The input file given above will therefore create output
pages as follows. Note that the system generated defini-
tions and contents table entries are not shown in detail.
--- Start of contents page. ---
Header data for the contents page.
<System generated definitions.>
Template text before the page data.
Text before the contents list.
<Contents Table.>
Text after the contents list.
Template text after the page data.
--- End of contents page. ---
--- Start of page one ---
Header data for the first page.
<System generated definitions.>
Template text before the page data.
Text for the first page.
Template text after the page data.
--- End of page one ---
--- Start of page two ---
Header data for the second page.
<System generated definitions.>
Template text before the page data.
Text for the second page.
Template text after the page data.
--- End of page two ---
etc.
SYSTEM GENERATED DEFINITIONS
The system generated definitions are written to each page,
after the pages own header data, and before the beginning
of the data from the template. Up to five lines of defi-
nitions will be written. The following shows typical out-
put for the sixth page in a multi page document.
#define PAGE 6
#define _THIS_ out06.html
#define _CONT_ index.html
#define _PREV_ out05.html
#define _NEXT_ out07.html
The PAGE macro is always output, and gives the number of
the page. The contents page is page zero, and output
pages are numbered beginning with one. If there is no
contents page, there will be no page zero.
The _THIS_ macro is always output, and gives the name of
the current page.
The _CONT_ macro gives the name of the contents page. If
no contents page is produced this macro will not be
defined.
The _PREV_ macro gives the name of the previous page in
the document. If a contents page is produced, this will
be considered to be the previous page for page one of the
output. If there is no previous page, for example, for a
contents page, or for page one when the contents page is
not produced, the macro will not be defined.
The _NEXT_ macro gives the name of the next page in the
document. I there is no next page, as for the last page
in the document, the macro will not be defined.
THE CONTENTS PAGE
The prefix "_C_" is used to identify special macro defini-
tions that will be used to create the contents list. This
prefix can be redefined using the -cpre command line
option.
As each page is processed, its header ("<HDR>") data will
be scanned for macro definitions that begin with the "_C_"
prefix. These definitions will be copied onto the con-
tents page, beginning at the insertion point marked by the
"<CONTENTS>" tag in the contents page "<DATA>" section.
Each definition output will be preceded by a line that
undefines the macro, since the contents list will neces-
sarily have the same macros defined and redefined a number
of times.
In addition to appropriately prefixed macros defined from
the page header, two more macros will automatically be
output to the contents page. These are _C_LINK, and
_C_NUM. These macros have values identical to the _THIS_
and PAGE macros of the page being referred to, the differ-
ence being that these are inserted in the contents page
rather than the page itself.
Finally, the string "_CONTENTS_" will be output. It is up
to you to ensure that there is a macro named _CONTENTS_
that expands to a contents table entry, and makes appro-
priate use of the "_C_" macros previously written to the
file.
A very simple contents list, including HTML markup, for a
two page document might look something like this. System
defines and some comments are not shown, for clarity:
--- The input file ---
/* The contents list entry -- a very simple example. */
#define _CONTENTS_ <LI><A HREF="_C_LINK">_C_TITLE</A></LI>
/* The template is empty, apart from the PAGE tag. */
<PAGE>
<HDR>
/* Content page header */
<DATA>
Contents:
<UL>
<CONTENTS>
</UL>
<HDR>
#define _C_TITLE Page One
<DATA>
Page One Text.
<HDR>
#define _C_TITLE Page Two
<DATA>
Page Two Text.
--- End of input file ---
--- Contents page .hss output ---
#define _CONTENTS_ <LI><A HREF="_C_LINK">_C_TITLE</A>
Contents:
<UL>
#undef _C_TITLE
#define _C_TITLE Page One
#undef _C_LINK
#define _C_LINK out01.html
#undef _C_NUM
#define _C_NUM 1
_CONTENTS_
#undef _C_TITLE
#define _C_TITLE Page Two
#undef _C_LINK
#define _C_LINK out02.html
#undef _C_NUM
#define _C_NUM 2
_CONTENTS_
</UL>
--- End of contents page .hss output ---
--- Contents page. HTML output. ---
Contents:
<UL>
<LI><A HREF="out01.html">Page One</A>
<LI><A HREF="out02.html">Page Two</A>
</UL>
--- End of contents page. HTML output. ---
THE CROSS REFERENCE FILE
htt2html automatically produces a cross reference file
containing a <PAGE> entry for each of the output pages,
including the contents page. The cross reference file is
passed to hss2html where it is used to resolve cross ref-
erences made with the <REF> macro.
The macros that the system puts into the cross reference
file are the same ones that are used in the creation of
the contents list. (See the section THE CONTENTS PAGE).
Those are the macros from the header ("<HDR>") data of
each page that begin with the "_C_" prefix, and the spe-
cial macros _C_LINK and _C_NUM which contain the page's
file name and number respectively. If you want to define
a macro that will be used in a cross reference you must
ensure that its name begins with the "_C_" prefix.
The _C_NUM macro has the value "0" for the contents page,
and begins at "1" for the actual pages of the document.
The document page numbers begin at one regardless of
whether a contents page is produced.
INCLUDE FILES
Source files for htt2html can use #include to include
other files. #include is expanded by htt2html rather than
by the C pre-processor, allowing #include to be used to
structure the input files in a flexible manner.
For example, a number of documents might need to use the
same template, but it would seem that each document needs
a copy of that template in the first few lines of its
"htt" source file. The solution, of course, is to use
#include to import the template from a common file:
--- Start of template file - template.inc ---
Template text before the page data.
<PAGE>
Template text after the page data.
--- End of template file - template.inc ---
--- Start of htt2html input file - file1.htt ---
#include "template.inc"
<HDR>
etc...
--- End of htt2html input file - file1.htt ---
--- Start of htt2html input file - file2.htt ---
#include "template.inc"
<HDR>
etc...
--- End of htt2html input file - file2.htt ---
It may also be helpful, particularly with long documents,
to use #include to import each page of the document from a
separate file.
Naturally, #include can be nested, so that included files
can include other files.
FILES
The input file for htt2html must be specified on the com-
mand line.
All output files will have the extension "html", although
this can be changed using the -outext command line option.
An intermediate file with the extension "hss" will first
be created, and this will be converted to HTML using the
hss2html program. The extension for intermediate file
names can also be changed using the intext option.
htt2html creates two types of output file. A single con-
tents page will be generated for each invocation of the
program (as long as the -nocont option is not used).
Additional "page" files will be created for each page in
the document.
The name of the contents page will default to "index", to
which the "html" extension will be added, using a dot.
The -o option can be used to change the name of the con-
tents page.
Page names are generated automatically, by appending two
digit numbers and the output extension to a base name.
The default base name is "out", so that pages will be
named "out01.html", "out02.html", etc. The base name for
page files can be modified using the -op command line
option. The automatically generated filenames can be
overriden, as discussed below.
The intermediate ("hss") files will be deleted automati-
cally unless the -k option is used.
A cross reference file will also be generated, as
described above. This file will also be deleted automati-
cally, unless the -k option is used. The name of this
file will default to "index.xref", or this can be changed
using the -x option.
PAGE NAME OVERRIDES
If the automatically generated page names are not appro-
priate, then file names can be specified on a page by page
basis, by writing the file name in the "<HDR>" marker for
the page.
The new name is specified after an equals sign ("=") and
without an extension. For example:
<HDR=infopage>
will produce a page called "infopage.html".
The page name should be inserted into the header tag in
the position specified by the "%PAGE%" marker. See the
discussion of the -hm and -hpm options for information on
changing both the header tag and the page marker strings.
Page name overrides are the recommended method for speci-
fying for names for output pages. The older -pname mecha-
nism is provided for compatibility with older versions of
the Guava tools.
Names added to a list by repeated use of -pname on the
command line will be used to override all filenames,
whether generated automatically or specified as page name
overrides in the header tags. The output extension is
added automatically. When no more names remain in the
list, naming reverts to automatically generated names, or
to the names specified in the header tags.
BUGS
The hss2html program, which is called by htt2html does not
parse HTML, so it might not always do the right thing.
For example it will expand macros and remove blank lines
from verbatim sections of HTML. The descriptions of the
<NOSP>, <SP> and <IMPORT> builtin macros in the hss2html
manual suggest workarounds for some of these problems.
There are too many options that you'll probably never use.
AUTHOR
Steve Morphet <email-address-hidden>
http:/www.morphet.org.uk/
LICENCE
hss2html and the Guava tools are Copyright (C) 1999-2001
Steve Morphet <email-address-hidden>
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.
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 GNU General Public License for more
details.
SEE ALSO
htt2html(1) websrccopy(1) webbuilder(1) cpp(1) gcc(1)
perl(1)
Email: