Guava

The Guava Tools

hss2html


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: