@(#) $Id: README,v 1.1 2000/01/28 07:02:57 mayoff Exp $

Author: Rob Mayoff <mayoff@dqd.com>

This module provides directory indexing support for AOLserver 3.0.  That
means that when the user tries to access a directory that does not have
an index.html, this module will dynamically generate a directory
listing.  (Substitute the contents of your DirectoryFile config
directive for "index.html".)

The module actually replaces AOLserver's built-in file handler,
"fastpath".  It duplicates the function of fastpath (by dint of
originally being a copy of it), but adds a hook for special handling
of directories that lack index files.

/*--------------------------------------------------------------------*/
Installation and Configuration

Unpack the dqd_dirindex archive in the contrib directory of your
AOLserver source tree.  Note: you MUST have the AOLserver source code to
compile this module.  You don't have to compile AOLserver yourself,
though; you just need to have the source code.  Then:

    $ cd dqd_dirindex
    $ make
    $ make install

To configure the module, you need to add these lines to your nsd.tcl:

    ns_section ns/servers/server1/modules
    ns_param dirindex dqd_dirindex.so

    ns_section ns/mimeicons
    ns_param unknown /icons/unknown.gif
    ns_param dir /icons/dir.gif
    ns_param text/* /icons/doc.gif
    ns_param image/* /icons/image.gif
    ns_param audio/* /icons/sound.gif

/*--------------------------------------------------------------------*/
Customization

The module provides two APIs for customizing the directory listing: a C
API and a Tcl API.

You can register a C routine to be called for directories.  The
registration routine is:

    void Dqd_SetDirHandlerProc(Ns_OpProc *procPtr, void *context);

The definition of Ns_OpProc is:

    typedef int (Ns_OpProc) (void *arg, Ns_Conn *conn);

When the module encounters a directory with no index file, it calls your
function thusly:

    retval = (*procPtr)(context, conn);

Your function should return NS_OK if it was successful, and NS_ERROR
otherwise.

The default provided by the module, if you don't register your own C
handler, is a function that runs a Tcl script.  The default Tcl script
is "dirindex", which is a Tcl proc defined in dirindex.tcl.  You can
specify a different Tcl script in your nsd.tcl:

    ns_section ns/servers/server1/module/dirindex
    ns_param tclCommand my_dirindex

The best way to customize the directory indexing is to make a copy
dirindex.tcl, say my-dirindex.tcl, and rename the dirindex proc in it to
something like my_dirindex.  Then use the tclCommand parameter to
specify this proc as your Tcl script.

