Minimalist Online Docmentation

Using the mod2html command

The mod2html command is used to convert the source tree of mod files to the indexed html tree. It regenerates every file in the html tree each time it is run. It can be run as many times as you want.

Command line arguments

Usage: mod2html [-c file] [-d dest] [-i static|dynamic] [-a] [-s] [-Y|N] [-q|v] source_dir
       mod2html -h|u

source_dir

This is the required command-line argument that specifies the root of the MOD source tree that should be converted to html. mod2html will expect to find a directory ".mod/" here, which contains the config file ".mod/config", and the default template ".mod/default.tmpl".

-c file

Specify a different config file for source_dir. The default is ".mod/config". Using this option, you can easily maintain multiple presentations of the same source tree (for example regular and printer-friendly versions); create separate config files that each specify a different default template and destination, and use this option to update each site.

-d dest

This option overrides the destination specified in the config file. Since the value will be overriding the default in the config file, status information is not kept, and all destination files will be recreated. The destination usually specifies a directory name under which the resulting html tree should be built. Other destination types are supported, though:

Tar archives:

If the destination ends in ".tar" or ".tar.gz", mod2html will store all output in the requested tar file or gzipped tar file.

FTP locations:

If the destination starts with "ftp://", mod2html will attempt to upload the resulting files to the given anonymous ftp server and directory. If priveleged FTP is desired, a username and optionally a password can be specified before the hostname in the same format as supported by most browsers:

ftp://[username[:password]@]hostname/[path/]

If the password is not supplied, you will be prompted for it when the FTP connection is made. This is the recommended usage to prevent your password from appearing in the shell history file.

-i static|dynamic

This tells mod2html which style of index to create. The static version just uses plain old HTML, which loads very quickly in browsers and it supported everywhere. The dynamic version uses javascript and cookies to create an expandable/collapsable Windows-Explorer-like interface, which can be useful if your index is growing too large. This corresponds to the index_style config file option.

-a

This option tells mod2html to rebuild all destination files. Normally, mod2html will use the files in .mod/status/ to determine which files have been modified since the last update, and will only update the pages that depend on the newly modified files.

-s

This option tells mod2html not to update its status information (kept in the .mod/status/ directory at the base of the source tree) after updating the destination. In effect, this will cause mod2html to forget that it has updated the tree with the current round of modifications. Probably not used very frequently, but useful in certain cases.

-Y

-N

These mutually exclusive options specify whether to pre-answer "yes to all" or "no to all" to any questions on whether to remove stale destination files, which can occur when a source file has been removed or renamed. The default is to ask for each file to be removed.

-q

Quiet. mod2html won't tell you what it's doing. It will only report warnings and errors. The default is somewhere between "-q" and "-v".

-v

Verbose. Use this option to get more debug and progress output from mod2html. This can be helpful if you're trying to determine when in the script a problem is occuring, or if mod2html takes a while on your tree and you just want to monitor the progress.

-h

Help. Don't do any processing, just print out a summary of what the command does and what its options mean.

-u

Usage. Don't do any processing. Just print out the valid options and command format.

Permissions

For a site maintained by one person, everything is simple; the source tree and destination tree are both owned by one user. That person runs mod2html as themself and creates the tree.

Our site, which is probably more typical, has several people maintaining it. We all own portions of the source tree, and none of us has unilateral write permissions to the destination tree.

The mod2html script itself doesn't really offer any solution to this problem, following the unix philosophy (do only one thing, do it well). I don't really have a great solution to this problem, but here's what we have set up so far:

The source tree is owned by a number of people. Each person owns the section that they are responsible for.

The destination tree is owned by a userid dedicated to the purpose, whose username starts with "www". The user has a locked password entry and an invalid shell.

Note that when mod2html is run, there are two locations that will need to have write access: the destination directory of course, and also the status directory, which is ususally ".mod/status/" in the source directory (its location can be overridden in the config file). For this setup, I had to make sure that both the destination and status dir were created with write permissions for our "www" user.

At the root of the source tree, there is an executable shell script called "update" that wraps the mod2html script. It calls mod2html using sudo to run the script as the "www" user to install the files. In this way, the sudoers file controls who is allowed to update the site. Here is the wrapper:

#!/bin/sh

# wrapper around mod2html so that we can easily run it as user www_ecf.
# Command line options to this script are inserted into the mod2html
# command so that mod2html flags can be set.

umask 002
PATH=/usr/bin:/bin:/usr/local/bin
export PATH

sudo -u www_ecf mod2html $* /mare/s0/doc/ecf/