Guava

The Guava Tools

htt2html


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: