|
The Guava Toolshss2html
|
Home Computer Software Guava Main Page Guava Manual Pages
NAME
hss2html - Converts an hss source file into HTML.
SYNOPSIS
hss2html [options] input-file
DESCRIPTION
hss2html is a Perl program that converts a source file
into HTML. It calls the C preprocessor cpp(1) to do some
of the work, so you get to #define your own macros,
#include other files, and use /*comments*/ just like you
can in C. It also allows you to cross reference other
files, and pre-defines a few handy macros of its own.
hss2html is also called from other programs in the Guava
tools, for example the htt2html template processing pro-
gram, so that all the features of hss2html can be used in
your htt2html source files.
OPTIONS
-v Be verbose.
-version
Print version information and exit.
-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 source file is always searched.
-o file
The name of the output file. If the supplied name
does not have a filename extension the output file-
name extension (as specified by -outext) will be
appended.
-localroot dir
The directory to use as the local-root when pro-
cessing the FULLREF builtin.
-remoteroot dir
The directory to use as the remote-root when pro-
cessing the FULLREF builtin.
-x name
The full name of the cross reference file. The
default is "index.xref".
-rfile name
The name of the data file containing local and
remote directory pairs for the FULLREF macro. The
file format is described in the description of the
FULLREF macro. The default name is "fullref.dat".
-M Causes hss2html 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 behaviour of hss2html differs slightly from
that of the C preprocessor when creating dependency
information in that conditionals such as #if are
not considered, and any #include or <IMPORT> state-
ment in the input files will cause a dependency to
be created, regardless of whether that file will be
used in the final output.
Use the -M option to the htt2html program to gener-
ate dependency information from multi-page source
files.
-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.
-d Compare the generated output file with any existing
file of the same name and replace only if there are
changes. This can help to avoid updating files
unnecessarily, for example, when a large number of
files are generated from a single source file by
htt2html(1).
The diff(1) program is used to compare the files.
This can be modified using the -diffprog option.
INFREQUENTLY USED OPTIONS
-k Keep intermediate files.
-b Don't delete blank lines in the output. The C pre-
processor often generates a lot of unnecessary
blank lines, so you probably don't want to use this
option.
-pwd dir
The directory to use as the pwd when processing the
FULLREF builtin. If -pwd is not specified the
directory name will be obtained by calling the
pwd(1) program.
-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 hss2html writes out
the command line definitions supplied with the -D
option during the preprocessing stage.
The define string must contain both of the inser-
tion point markers, although the markers themselves
can be redefined using the -defnmarkand -defdmark
options.
-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.
-diffprog string
The string used to invoke the comparison program
when the -d option is used. The default is "diff
-b -q %OLD% %NEW% >/dev/null". If you do not have
GNU diff or if you want to change its behaviour,
then you may need to change this setting. hss2html
expects your replacement program to return zero if
there are no differences between the files, and a
non-zero value otherwise.
The -b option to GNU diff tells it to ignore dif-
ferences in the amount of white space. The -q
option reduces the amount of output that diff gen-
erates.
The words %OLD% and %NEW are insertion point mark-
ers that will be replaced with the names of the old
and new output files when the command is invoked.
The diffprog string must contain both of the inser-
tion point markers, although the markers themselves
can be redefined using the -diffomarkand -diffnmark
options.
-diffomark marker
Sets the insertion point marker for names in the
-diffprog command string. The default is "%OLD%".
In the unlikely event that the default marker con-
flicts with something in your -diffprog string, you
will have to use this option to specify an alterna-
tive.
-diffnmark marker
Sets the insertion point marker for names in the
-diffprog command string. The default is "%NEW%".
In the unlikely event that the default marker con-
flicts with something in your -diffprog string, you
will have to use this option to specify an alterna-
tive.
-cpp command
Sets the command line used to execute the C prepro-
cessor. Not all gcc(1) installations have a stand-
alone cpp(1) program, so the default command string
uses gcc with the -E command line option to do the
same thing.
The default setting is therefore:
gcc -x c -traditional -E %OPTS% -o %OUTFILE%
%INFILE%
The -P option will also be added if line control is
not being used. (Line control is used automatically
unless the -p option is given to hss2html).
The three words %OPTS%, %OUTFILE%, and %INFILE% are
insertion point markers. Before the command is
executed they will be replaced with the -cppopts
string, the name of the output file, and the name
of the input file, respectively.
The command string must contain all three of the
insertion point markers, although the markers them-
selves can be redefined using the -cppoptsmark,
-cppoutmark, and -cppinmark options.
-cppdm command
Sets the command line used to execute the C prepro-
cessor in order to determine the names of macros
that are predefined by the preprocessor. These
macros are then automatically #undefined by
hss2html to reduce the chance of unexpected
effects.
The default setting is:
gcc -x c -traditional -E -dM %OPTS% %INFILE%
The words %OPTS%, and %INFILE% are the same inser-
tion point markers that are used with the -cpp
option string. Before the command is executed they
will be replaced with the -cppopts string and the
name of an empty file.
The command string must contain both of the inser-
tion point markers, although the markers themselves
can be redefined using the -cppoptsmark, and
-cppinmark options.
Setting the command line to an empty string dis-
ables the automatic #undefining of predefined
macros.
See the section PREDEFINED MACROS for more informa-
tion about this option.
-cppopts opts
Options to pass to the C preprocessor. Options
will be inserted into the CPP command line at the
insertion point defined by the -cppoptsmark option.
-cppoptsmark marker
Sets the insertion point marker for C preprocessor
options in the -cpp command string. The default is
"%OPTS%". In the unlikely event that the default
marker conflicts with something in your -cpp com-
mand string, you will have to use this option to
specify an alternative.
-cppinmark marker
Sets the insertion point marker for the input file
name in the -cpp command string. The default is
"%INFILE%". In the unlikely event that the default
marker conflicts with something in your -cpp com-
mand string, you will have to use this option to
specify an alternative.
-cppoutmark marker
Sets the insertion point marker for the output file
name in the -cpp command string. The default is
"%OUTFILE%". In the unlikely event that the
default marker conflicts with something in your
-cpp command string, you will have to use this
option to specify an alternative.
-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.
-intext ext
The filename extension for intermediate files.
Default is ".hxx".
-diffext ext
The filename extension for intermediate output
files when the -d option is used. Default is
".dout".
-outext ext
The filename extension for output files. Default
is ".html".
-stamp Write the date to the output file in an HTML
<!--comment-->. This is not enabled by default as
it will interfere with the operation of the -d
option.
OPERATION
hss2html reads an input file, and processes it in three
stages. There is a pre-processing stage, after which the
file is processed using the C preprocessor (cpp), and
finally a post-processing stage.
Pre-processing
The pre-processing stage reads the input file and expands
#include files. Any macro definitions made with the com-
mand line -D option are prepended to the output as #define
lines. Cross references are expanded here too.
The C pre-processor
The output from the pre-processing stage is sent to the C
pre-processor cpp(1) which does all the usual C pre-pro-
cessor things. C-style /*comments*/ are removed, macros
are expanded, etc. The only unusual thing is that
#include files will already have been expanded by the
hss2html pre-processing stage, so will not be visible to
cpp.
Post-processing
The post-processing stage takes the output of the C pre-
processor and processes a few more built-in macros, which
are described below. Imported files are inserted into the
output at this stage.
CROSS REFERENCES
Cross references are particularly useful (and pretty much
automatic) when hss2html is driven by the htt2html pro-
gram, such as when processing a multi-page document. Nev-
ertheless, they can also be used when hss2html is called
directly, by specifying a file containing cross reference
information using the -x command line option. Cross ref-
erences are inserted in a document using the REF macro.
The Cross Reference File Format
The cross reference file contains one or more sections,
each corresponding to another page or section of a larger
document. Each section begins with a <PAGE> marker, fol-
lowed by a number of key/value pairs.
For example:
<PAGE>
LABEL The first page
NUMBER 1
<PAGE>
LABEL The second page
NUMBER 2
The <REF> builtin macro.
The <REF> macro will output the value of the key named
output, for the first page that has a key/value pair
matching key and value in the cross reference file:
<REF:output,key=value>
Using the example cross reference file given in the sec-
tion above, the string:
<REF:LABEL,NUMBER=1>
will be replaced with:
The first page
BUILTIN MACROS
There are a number of built in macros which are expanded
in the post-processing stage of hss2html.
<DATE[="format"]>
The <DATE> macro expands to the current date and time, as
specified by the format string. The format string is
almost identical to the format string passed to the POSIX
strftime(3) function, in C and Perl. For example, the
macro:
<DATE="%A, %B %d<TH>, %Y">
will be replaced with something like:
Thursday, September 30th, 1999
The format string can be omitted, in which case the output
will be in the format produced by the ctime(3) function
call. For example:
<DATE>
will be replaced with something like:
Thu Sep 30 20:33:01 1999
A small difference between this format string and the
POSIX format string is the availability of the <TH> mini-
macro, which is demonstrated in the example above.
<TH> can only be used in the format string of the <DATE>
macro, and expands to one of "st", "nd", "rd", or "th",
according to the current day of the month.
<IMPORT="filespec">
The IMPORT macro imports the contents of a file and
inserts it into the output. The file specified will be
searched for using the include path (as set by the -I com-
mand line option), in exactly the same way that the
#include directive is processed. The difference between
#include and <IMPORT> is that imported files are copied
verbatim into the output, with no further processing tak-
ing place on the contents.
<FULLREF="filespec">
The FULLREF macro operates in one of two modes, depending
upon whether the macro LOCAL has been defined, e.g. using
-DLOCAL on the command line.
In LOCAL mode, the FULLREF macro simply expands to its
filespec argument.
In non-LOCAL mode, the FULLREF macro first converts any
relative components of the filespec argument into an abso-
lute path, using the current working directory, or the
value specified by the -pwd option.
The next stage of the operation uses the data in the FULL-
REF data file, which must be provided by the user. The
name of this file is specified by the -rfile command line
option, or defaults to "fullref.dat" if the rfile option
is not used.
The FULLREF data file should contain pairs of path names,
one pair on each line, with the remote path name followed
by the local path name.
If the file name provided as the argument to FULLREF, once
expanded to an absolute path name, matches any of the
local path names in the FULLREF data file, that path will
be replaced with the corresponding remote path name in the
output.
Example:
You have a web site at
http://www.test.site/
and your source code is being built in the directory
/home/sdm/guava/test/
You should set up a FULLREF data file containing the line,
http://www.test.site/ /home/sdm/guava/test/
Then, when building source code in /home/sdm/guava/test/ ,
the macro:
<FULLREF="index.html">
will be replaced with the string:
http:/www.test.site/index.html
The FULLREF data file can contain more than one pair of
remote and local path names. This can be useful if your
web project is distributed over a number of physical
sites.
Example:
The web site at http://www.test.site/ uses a library of
images which are stored on another server at
http://www.pics.site/
The source code for the main site is being built in the
directory
/home/sdm/guava/test/
and the local copies of the images are stored in
/home/chasca/images/
You should set up a FULLREF data file containing the
lines,
http://www.test.site/ /home/sdm/guava/test/
http://www.pics.site/ /home/chasca/images/
Then, when building source code in
/home/sdm/guava/test/subdir/ the macro:
<FULLREF="../index.html">
will be replaced with the string:
http:/www.test.site/index.html
and the macro:
<FULLREF="/home/chasca/images/jump.jpg">
will be replaced with the string:
http:/www.pics.site/jump.jpg
Versions of the Guava tools prior to version 1.0.4 used an
alternative method of setting local and remote path names,
which did not support multiple directories. The -local-
root, -remoteroot, -DLOCALROOT and -DREMOTEROOT methods of
setting the path names are no longer supported. Use a
FULLREF data file and the -rfile option instead.
<APOS> and <QUOTE>
Sometimes the C preprocessor gets confused by apostrophes
(') and quotes ("), because it assumes that they mark the
beginning of a character constant. This can cause the C
preprocessor to abort, with a diagnostic like "untermi-
nated character constant". By default, hss2html passes
the -traditional option to GNU cpp(1) which avoids the
abort, but still appears not to guarantee the desired
behaviour for text like:
#define MACRO work
This test doesn't MACRO as well as it should.
which will fail to expand the macro due to the presence of
the apostrophe in "doesn't".
To work around these problems use the <APOS> and <QUOTE>
builtin macros, which are expanded to the appropriate
characters in the post processing stage, after the C pre-
processor has been run.
The behaviour of GNU cpp and the -traditional option is
explained in detail in the info(1) pages for cpp.
<NOSP>
The <NOSP> builtin macro absorbs spaces, so that the
string:
There are no <NOSP> spaces here.
becomes:
There are nospaces here.
This can be useful if the C preprocessor inserts spaces
into its output where you do not want them, for example,
when it expands macros.
Another use of <NOSP> is to protect strings that would
otherwise be expanded as macros. So:
#define MACRO string
MACR<NOSP>O
will be output as:
MACRO
<SP>
The <SP> builtin macro inserts a single space into the
output. It is occasionally useful in conjunction with
<NOSP>, for example, to ensure that there is only a single
space at certain point:
#define MACRO1 one
#define MACRO2 two
MACRO1 <NOSP><SP> MACRO2
will give:
one two
You can also use <SP> to protect a blank line inside
HTML's <PRE> tags, since <SP> is expanded after blank
lines are removed from the output. Note that <NOSP> will
not work for this purpose, since it absorbs all whites-
pace, including newlines.
<REF:output,key=value>
The <REF> macro is described in the Cross References sec-
tion.
Adding new macros to hss2html.
Perl programmers could easily add new macros to hss2html
by adding them to sub Postprocess in the Perl script.
Patches to the Guava tools are welcomed.
FILES
The input file for hss2html must be specified on the com-
mand line. If the input filename has an extension (a dot
followed by characters at the end of the filename), the
names of intermediate and output files will be created by
replacing the extension. If the filename has no exten-
sion, the intermediate and output file names will be cre-
ated by appending the appropriate extensions to the input
filename.
Two intermediate files will always be created. The first
is the output from the preprocessing stage, and will have
an extension something like .1.hxx where the hxx part is
the default extension which can be modified using the
-intext option. The second file is the output of the C
preprocessor, and will have an extension like .2.hxx.
The final output file is the output of the postprocessing
stage, and uses the filename extension specified by the
-outext option, which defaults to ".html".
If the -d option is used, the output will be written to a
third intermediate file before being compared to any
existing file with the output file name. The existing
file is replaced only if the contents of the two files
differ, or if there is no existing file with the output
file name. The intermediate file name uses the file
extension specified by the -diffext option, which defaults
to ".dout".
All intermediate files will be deleted automatically
unless the -k option is given.
PREDEFINED MACROS
The C preprocessor normally defines a number of macros
automatically. For example, if you're running Linux on an
Intel system, the gcc preprocessor will define macros such
as "__linux__", "linux", "unix", and "__i386__". If any
of these strings appear in your input files they will be
replaced with the value of the macro, usually "1", which
is unlikely to give the desired effect. Fortunately
hss2html is able to automatically correct this problem.
A set of #define directives corresponding to the prede-
fined macros can be obtained by using the -dM option with
gcc. Full details are given in the gcc manual. This
method is used by hss2html, and the program automatically
#undefines each of the predefined macros before running
the C preprocessor on your input file.
If you need to change the command used to determine the
predefined macros then the -cppdm option may be used.
Markers should be given, as discussed in the description
of the option above, to indicate the positions where addi-
tional options, and a file name, will be inserted into the
command. The filename is used to provide the name of an
empty input file (see the gcc manual for details).
hss2html will choose an appropriate name for this file,
and delete it afterwards. You just need to provide the
marker to indicate where its name should be inserted into
the command.
If you would rather leave these macros defined for any
reason, simply set the command to an empty string using
-cppdm "".
BUGS
hss2html 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
description of the <NOSP>, <SP>, and <IMPORT> builtin
macros suggests 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) gcc(1) cpp(1)
diff(1) make(1) perl(1)
Email: