HTSMALL(1)HTSMALL(1)NAMEhtsmall - create an index for a web site from a data definition
SYNOPSIS
/usr/WebFace/bin/htsmall [-x] [-p permissions] [-m match] [source]
destinition
DESCRIPTIONhtsmall is a simple "web site compiler." It provides a subset of the
functionality found in the htmake site compiler (see htmake(1)). htsmall
reads a source directory (the current working directory if not specified
on the command line) and generates a single page in the destination
directory. htsmall also copies all necessary files within the source
directory to the destination directory.
The generated page is a simple index, useful for the top level of a web
site. The index is structured as a table, with one index entry per row.
_Row Structure_ Each row contains a combination of the following (from
left to right)
{<Graphic> or <Label>} <Description>
Graphic:
a "gif" image, usually an icon. This is placed at the leftmost edge
of the row.
Label:
the label is a short description of what the link does. In lieu of
a graphic, the label is displayed.
Description:
a [detailed] description. This can be of any length, lines are
wrapped to the right of the graphic and label.
All row components are part of a single, large hotlink (one per
row), which points a category file (described below).
_Row Specification_ When htsmall is invoked, it searches the source
directory for files with ".cgi", ".html" and ".shtml" extensions
having names prefixed (having as their first few characters) with a
usr-specifiable `match' value (e.g., "Tasks.").
By default, this match value is equivalent to the name of the source
directory although you can specify a different value by using the -m
switch (see options).
Example: if htsmall was invoked like
htsmall-m Applications /usr/people/bob/mysource /var/www/htdocs
then the following files would fit htsmall's search criteria:
Page 1
HTSMALL(1)HTSMALL(1)
Applications.test.html
Applications.artwork.cgi
Applications.brian.demo.shtml
Note: it is illegal to have two or more files with the same name but
different extensions and htsmall will report this as an error:
Applications.brian.demo.shtml
Applications.brian.demo.cgi
The foregoing is illegal.
Each matching file, which will hereafter be referred to as "category"
files, becomes a separate row in htsmall's generated index page. Each
row is a single hotlink (graphic, label and description). The link
points to the category file ([S]HTML page or CGI script) for which the
row was created.
For each category file, htsmall looks for two files, one a "gif" file
containing the graphic (icon) icon to be used for the row (see above),
and a separate "label" file.
For both the gif and label files, the file name is the same as the
category file's name without the match value (such as "Applications" in
our above example. For the gif file, the extension must be `.gif' while
the label file's extension is `.lbl'.
Thus, the label and gif files for "Applications.artwork.cgi" (assuming
the match value was "Applications") would be:
`artwork.lbl' and `artwork.gif'
respectively.
The label file is used for two purposes: the first line of the file can
contain a string to be used as a label if no graphic is found for the
matching category file (the label will also be displayed if the user
turns off image loading, via the <IMG> tag's ALT="" attribute).
The remaining lines of the file contain the text of the description (see
_Row Structure_, above). There can be as many lines as you like and they
can contain any HTML tags (including server side includes) you like.
Note that the entire description text will be hot (linked) and that
carriage returns ending lines will be parsed by the browser as whitespace
(according to HTML parsing rules which reduce any number of consecutive
whitespace characters to single spaces).
_Background_ You can add a tiled background (for display by Netscape-
compatible browsers) to the page by placing a `background.gif' image in
the source directory. htsmall will detect the presence of the background
file and automatically modify the page's <BODY> tag to account for the
background attribute.
Page 2
HTSMALL(1)HTSMALL(1)
_Banner Image_ A banner image may be placed at the very top of the page
by including a `banner.gif' image within the source directory. No other
name is allowed.
If you are using Netscape Navigator 2.0 or later, or another browser
which supports Netscape-style client-side image maps, you may have an
image map built into the page by creating a `banner.map' file within the
source directory.
The map file should contain only <AREA> tags (no <MAP> ... </MAP>).
htsmall will detect the presence of the map file and automatically
generate the appropriate enclosing tags (<MAP> and <NOMAP>) and
incorporate the map file's contents into the page.
_Includes and Execs_ You can have htsmall include text before and after
the banner image (if present), after each index row, and at the bottom of
the page. To do this, create one or more of the following files: (as
befits your needs)
upper.inc
Text to be placed before banner graphic. Text will span entire
page.
middle.inc
Text to be placed after banner graphic but before index rows. Text
will span entire page.
between.inc
Text to be placed immediately after banner graphic (will not be hot
[linked]). Text will wrap underneath descriptions (to the right of
the graphic or label).
lower.inc
Text to be placed after all index rows. Text will span entire page.
You can also include text specific to each row by creating a `.inc' file
having the same name as the category file without the match value
("Applications" in the above examples). Thus, the include for
"Applications.artwork.cgi" (assuming the match value was "Applications")
would be:
`artwork.inc'
Each `.inc'lude file can contain any number of lines. Text will be
parsed according to HTML rules (as with descriptions, described above).
If your web server supports and has enabled "server side includes" (which
are beyond the scope of this document), you can have htsmall invoke a cgi
script before and after the banner image (if present), after each index
row, and at the bottom of the page. The results (output text) of these
scripts will be written into the page as it is sent to the browser. Note
Page 3
HTSMALL(1)HTSMALL(1)
that because these scripts will be outputting text into the middle of an
existing HTML page, they should not generate any the following tags:
<HTML> <HEAD> <TITLE> </TITLE>
</HEAD> <BODY> </BODY> </HTML>
Specifying which script to run is similar to that for specifying include
files, the principal difference is the extension:
upper.xeq
Script will be executed before banner graphic. Output text will
span entire page.
middle.xeq
Script will be executed after banner graphic but before index rows.
Output text will span entire page.
between.xeq
Script will be executed immediate after row's description. Output
text will wrap underneath descriptions (to the right of the graphic
or label).
lower.xeq
Script will be executed after all rows have been displayed. Output
text will span the entire page.
You can also have executed a script specific to each row by creating a
`.inc' file having the same name as the category file without the match
value ("Applications"in the above examples). Thus, the include for
"Applications.artwork.cgi" (assuming the match value was "Applications")
would be:
`artwork.xeq'
Note: htsmall will automatically copy files with `.xeq' to the
destination directory, changing their extensions to `.cgi'.
OPTIONS-x suppress use of labels if graphics are not present.
-m match_value Specifies the string (other than the name of the source
directory) against which to match category files. The generated
page contains one index row for each category file.
-p permissions mail {`u', `o', `g'} Any combination of `u', `o' and `g'
can be used (but no letter more than once). The letters can be
either upper or lowercase. Specify base access permissions for the
generated page and any related (copied) files. Only the user is
ever given write permission on the page. Group and Other users are
given read or execute access as is appropriate.
Page 4
HTSMALL(1)HTSMALL(1)CAVEATS
Beware of using large icons, long labels or descriptions. These can
crowd rows, resulting in illegibility, or result in very long pages.
BUGS
There are a couple of unsupported switches that are remnants of htsmall's
parentage (being derived from htmake). It is expected that they'll be
removed in a future release.
SEE ALSOhtmake(1)
Page 5
