HTMAKE(1)HTMAKE(1)NAMEhtmake - create a web site from a source document tree
SYNOPSIShtmake [-c] [-l] [-v] [-x] [-a auxdir] [-b button] [-f font] [-h home]
[-n name] [-p permissions] [-s subdir] [source] destination
DESCRIPTIONhtmake is a "site compiler." It creates a World Wide Web site (composed
of several hypertext documents and related objects (e.g., graphics) from
a source tree (expressed as a directory hierarchy).
Pre-requisites to using htmake are: 1. a server supporting NCSA-compliant
Server-Side Includes ("includes"); and 2. a Netscape-style frames- and
JavaScript-capable browser/client/user-agent (such as Netscape 2.1).
Includes (including `execs') must be enabled in the site's target
directory. You can do this by placing the following line into the target
directory's access control file: (ACF)
The path to the source tree is either specified on the command line
[source] or, by default, is the current working directory (CWD). The
generated site is written to the specified destination directory
(destination).
Generating the Site When invoked, htmake reads (recursively) through the
source document tree and outputs the objects comprising the corresponding
web site. The generated site is comprised of each of the objects found
within the source tree along with a set of HTML files. htmake renames
source tree objects as is necessary to avoid name-space collisions (two
or more objects having the same name). Appropriate permissions (allowing
reading or execution by other than owner, as is appropriate) are applied
to objects when they are written or copied to the destination directory.
Site Home Page Unless inhibited by use of the -l switch, htmake
automatically generates a home page (entry page) for the site. By
default this is named "index.shtml" (the home page's name can be changed
using the -h switch). This means that, as default configured, the NCSA,
APACHE and most other webservers will automatically serve "index.html" if
a user specifies the destination directory as a URL.
The home page consists of a title ("splash") graphic followed by a blank
line and a "Start" link. All are centered along the page's vertical
axis.
The splash graphic must be placed in the source document's root directory
under the name "title.gif" (which therefore requires it to be a GIF
image). In lieu of a title graphic, the title page will show the
document's name (the last portion of the source directory path). A GIF
image may be used in place of the text "Start" links (on the link) by
placing a file named "start.gif" in the document's root directory.
Page 1
HTMAKE(1)HTMAKE(1)
The remainder of the site is functionally organized into two levels.
Each level is expressed as one or more directories and subdirectories.
The title page's start link links to the top level and the top level
links to the lower level. Clicking on the home page's start link will
display the site's "upper" level.
UPPER LEVEL STRUCTURE
The upper level consist of a single page. The page is a simple index and
is called the _selection page_. 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.
htmake creates one row for each directory within the source directory.
All row components are part of a single, giant hotlink (one per row),
which points to one of several frame and page sets, each set representing
one of the subdirectories within each upper level directory. These
represent the "lower level" of the source document.
For both the gif and label files, the file name is the same as the
directory's name. For the gif file, the extension must be `.gif' while
the label file's extension is `.lbl'.
Thus, the label and gif files for <source>/Applications would be:
`Applications.lbl' and `Applications.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).
Page 2
HTMAKE(1)HTMAKE(1)
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. htmake will detect the presence of the background
file and automatically modify the page's <BODY> tag to account for the
background attribute.
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>).
htmake 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 htmake 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.
Page 3
HTMAKE(1)HTMAKE(1)
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).
You can have htmake 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 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: htmake will automatically copy files with `.xeq' to the destination
directory, changing their extensions to `.cgi'.
Page 4
HTMAKE(1)HTMAKE(1)LOWER LEVEL STRUCTURE
Clicking one of the upper level index's links (icon, label or
description), will cause the browser's document area to be divided into
three frames: (actually four but one is not visible)
+-------------------+
| BUTTONS |
+-------+-----------+
| | |
| | |
| | |
| | |
| INDEX | FORM |
| | |
| | |
| | |
| | |
+-------+-----------+
Buttons In the button frame, htmake places a "button bar" (a row of
clickable buttons). Each button represents a subdirectory within an
upper level directory (that is, a directory for which there is a link on
the selection page).
Buttons can be textual or iconic. When creating a button, htmake first
searches the associated directory for a file with the same name as the
directory but having a '.gif' (Graphic Interchange Format) extension. If
a matching GIF file is found, it is copied to the destination directory.
The GIF will then be used for the button bar (it will be clickable). If
htmake does not find a GIF file for the directory, it then searches for
a file with a '.lbl' ("label") extension. If one is found, the first
line of the file is used verbatim (the terminating newline is ignored)
for the button's value and is displayed in brackets [<button>].
If neither an icon nor a label file is found then the name of the
directory is used. When using the directory name, htmake will
automatically capitalize the first and lowercase the remaining letters of
the directory.
Buttons within the bar are ordered alphabetically by their labels (the
directory's capitalized name is used if no label is found). The ordering
is case sensitive.
The buttons can be animated by creating an "activated" image for each
button, naming them
<directory>.active.gif
and placing them within the appropriate directory. The button's active
image will be displayed whenever the button is selected (clicked on). In
this sense, the button bar will appear to function like a set of old-
style car radio buttons, where one is pressed in to show its selection.
Page 5
HTMAKE(1)HTMAKE(1)htmake supports the placement of a tiled background into the button bar.
If one exists within the directory represented by the button bar, then it
will be used. Otherwise, htmake will use the background specified in the
document's root directory (the source directory), if present--this is the
same image that htmake uses on the selection page.
htmake can place a "banner" graphic at the top of the button bar (above
the button row). Banner graphics must be named 'banner.gif'. htmake
will first search the directory represented by the button bar for a
banner, then the document's root directory.
In the button bar's upper left, above the button row and just before the
banner graphic, htmake places a "Home" link. Clicking this jumps back to
the site's home page. A GIF can be substituted for the button text by
placing a 'home.gif' graphic in the document's root directory. (To
ensure that the banner graphic and home button are properly centered,
htmake checks for a 'nohome.gif' image. If present, it will be placed to
the right of the banner, offsetting the effects of the 'home.gif' image.
This GIF should be transparent and the same dimensions as your
'home.gif.')
Indicies Within the index frame, htmake places a list of forms (detailed
below). Each entry within an index reflects one form ('.frm') file
within the subdirectory associated with the selected button bar button.
Clicking on an index entry causes the associated form to be executed
(and, hence, displayed in the lower right frame).
You can have one or more arguments passed to any form by creating a
'.arg' file having the same name as the form ('.frm' file) to which you
want to pass the arguments (it must be in the same directory as the
form).
The first line of the file will be passed to the form as part of the URL
invoking the form (using the <location>?<argument> CGI URL protocol).
The arguments are then available to your script using the CGI 'get'
method. They are encoded using standard CGI URL encoding rules ("opaque
string"). Note that if your script uses self-referencing (URLs), it will
be necessary for you to pass these arguments back to your script as part
of a URL or [hidden] form parameter.
Like with buttons, you may specify either an icon (graphic) or label to
be displayed for an index entry: (form) create a '.gif' or '.lbl' file
having the same name (but different extension) as a particular form.
If htmake does not find a GIF file for the form, it then searches for
afile with a '.lbl' ("label") extension. If one is found, the first line
of the file is used verbatim (the terminating newline is ignored) for the
button's value and is displayed in brackets [<button>].
If neither an icon nor a label file is found then the name of the form is
used. When using a form's name, htmake will automatically capitalize the
first and lowercase the remaining letters of the name and drop the
Page 6
HTMAKE(1)HTMAKE(1)
extension ('.frm').
Within the index, items are ordered alphabetically by their labels
(theform's capitalized name is used if no label file is found). The
ordering is case sensitive.
In order to highlight the currently selected index entry, if it is a
label, htmake displays it <STRONG>. htmake also allows you to specify
'selected.gif' and 'unselected.gif' graphics which will be placed before
the currently selected and unselected index items, accordingly. htmake
first looks for these graphics in the (sub)directory represented by the
selected button (for which the index is being built). If either graphic
is missing, it next searches for an appropriately named graphic in the
parent directory (for which the containing button bar, index and frameset
are being built), and finally, if still not found, in the source
directory.
If the directory for which the index is being built (the subdirectory of
sub- directory of the source directory) contains a _description.frm_,
then htmake will place that entry at the top of the index, regardless of
the names of any other forms. This allows an obvious, consistent means
of self-documenting the site.
Further, if a `describe.gif' and/or `undescribe.gif' graphic can be
found, then these will supplant `selected.gif' and `unselected.gif',
respectively. Otherwise the standard `selected.gif' and `unselected.gif'
will be used, if present. This allows further highlighting of the
_description.frm_ index entry. htmake uses the same search strategy in
looking for `describe.gif' and/or `undescribe.gif' as when looking for
`selected.gif' or `unselected.gif'.
Forms Forms are stand-alone executable scripts (e.g., C shell, shell or
PERL) which generate HTML pages (ostensibly forms). They are identified
by having a '.frm' extension. (They'll be renamed to '<form>.cgi' by
htmake.)
ACCESSING THE GENERATED SITE
Assuming that you're already viewing the site's home page (which, if you
accepted the defaults and your webserver is traditionally configured, you
can do by specifying the destination directory as a URL to your browser),
clicking on the "Start" link will cause the _selection_ page to be
displayed.
In turn, clicking on one of the selection page's links (a row, comprised
of icon, label and description), will cause a frame and button bar/index
set to be displayed.
Selecting a button will change indicies while clicking on a particular
index item will cause a different form to be displayed. Clicking on the
"Home" icon within the button bar will return you to the site's home page
and the bar's "Back" icon will jump you back to the selection page.
Page 7
HTMAKE(1)HTMAKE(1)GENERATED SITE STRUCTURE
While the source tree is hierarchical, the output is basically flat--
normally all generated or copied documents reside in the destination
directory. The one exception is if the -s flag is given to htmake. In
this case, the site's home page document (index.html) is placed in the
target directory and the remaining objects (i.e., HTML, CGI and GIF
files) are placed in a designated subdirectory (subdest) within the
target directory. If subdest does not exist then it is created. (The
destination directory must always exist prior to beginning site
creation.) All hypertext links between the home page document and other
site documents are maintained.
Placing all but the index document within a subdirectory allows all but
the site's home page to be placed within a controlled access directory;
all users can view the home page without restriction but, by placing or
modifying an ACF (access control file) within the subdirectory, users can
be selectively restricted from accessing the remainder of the site (and
the home page can then note any access restrictions).
OPTIONS-c Clears the destination directory before compilation begins. (If the
-s option is used, the subdirectory is cleared, too, if it exists).
ALL files except for those with a '.' prefix (normally not displayed
by ls) are deleted from the destination directory. This is useful
if your source tree includes documents which have changed names
since the last time the site was generated.
Note that if the -s switch is used, only the specified sub-directory
is cleared. The [parent] destination directory is not altered.
[The reason for having clearing being an option is to allow your
forms to take advantage of images or other documents residing in the
destination directory prior to site generation.)
-x suppress use of labels if graphics are not present.
-v Enables verbose mode: htmake will report each step of its processing
with a series of messages to STDOUT. Given that site compilation
typically takes only a few seconds, this option is only for the most
neurotic.
-l Prevents construction of the site's home page (whether expressly
identified using the -h switch). All appropriate links will still
point to the home page. This allows the use of a separately
constructed home page with the site. (Use the -s switch to place
the generated site in a subdirectory within your site's principal
directory-- wherein your home page will reside).
-a auxdir
You can have htmake generate selection pages for additional
directories (other than the source directory) by specifying one or
more of them using this option (you must use a separate -a switch
Page 8
HTMAKE(1)HTMAKE(1)
for each directory you want to add). No button bar/index page sets
will be built for these directories and no forms are
required/processed.
The site's home page will (if generated) will include links to these
additional pages.
-h homepage
This option lets you specify a name for the site's home page (entry
point) other than the default "index.html."
Note: most HTTP servers automatically seek an "index.html" document
when passed a URL without a file name. This allows a URL to consist
only of a site path....
http://anywhere.com/
This will cause the server to qualify the URL as
http://anywhere.com/index.html
-p permissions {`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.
-s subdirectory
Places all objects (pages, forms, etc.), except for the site's home
page, in the specified directory. The home page is placed in the
destination directory. All links between the home page and the
other site objects are properly resolved.
The value of using this switch is when the site must be access-
controlled. See _generated document structure_, above.
The directory must be within the site's destination directory; if it
doesn't exist, it is created.
CAVEATS
Beware of using large icons, or long labels or directory names for
buttons. These can crowd button bars and cause the browser to wrap them
[to the next line]. Similar problems arise in indices for the same
causes.
Page 9
