htmake(1)
htmake - create a web site from a source document tree
As shipped in IRIX 6.5.30. Unchanged since IRIX 6.5.
NAME htmake - create a web site from a source document tree SYNOPSIS htmake [-c] [-l] [-v] [-x] [-a auxdir] [-b button] [-f font] [-h home] [-n name] [-p permissions] [-s subdir] [source] destination DESCRIPTION htmake 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. 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). 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. 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'. 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. 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 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. 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 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.