Apache HTTP Server Version 1.3

Module mod_quickdocs

Status: Add-on
Source File: mod_quickdocs.c
Module Identifier: quickdocs_module

Table Of Contents

• Summary
• Requirements and Design
• Differences with mod_autoindex
• How it Works
• Quickdocs Directives
• Autoindex Directives

Summary

The quickdocs module provides directory formatting which extends the capabilites of the autoindex module. It can be thought of as a compromise between the spartan but automatic formatting of file system links (files and directories) provided by autoindex and the fully manual presentation of links provided by an index.html file, in which every link must be mentioned explicitly.

Although clearly, an index page can contain dynamic elements, these involve some nontrivial web programming. That represents an effort which is well beyond what the casual user is willing to invest. Quickdocs is provided as an Apache module in the hope that it will become a ubiquitous element in deployed servers, helping LAN inhabitants to organize and document their directories with a minimum of effort.

Quickdocs provides very basic formatting to help organize and annotate the files contained in a file system directory. The most important formatting element is annotation, which can be added to individual files or groups of files. Although the document previews provided by the Windows Explorer go some way toward making directories more usable, annotations allow the quickdocs user to tersely express the intent of a file. Moreover, there are many types of files for which a preview makes no sense (DLLs for example).

The second most important formatting element is the ability to order the files in the directory arbitrarily. This allows the quickdocs user to bring the most important files up to the top of the page, while allowing full access to the remaining files in the directory.

The third formatting element is the ability to group files by sections and to supply header text for each section. Quickdocs also supplies the ability to specify a title and a background for the document.

The remaining formatting elements are also present in the original autoindex module. These include the ability to add header and footer text and the ability to hide files matching a certain pattern. One additional difference is that an effort has been made to allow all of the quickdocs formatting commands to appear within a single auxiliary file. Therefore, quickdocs allows the user to supply header and footer text inline, rather than having to refer to another file for each.

The quickdocs module is almost backward compatible with autoindex. With the exception of some slight formatting changes, the default behavior of quickdocs is very close to that of autoindex.

The big advantage of using quickdocs is that -- through the addition of an auxilary .htaccess file to each directory -- an entire file directory tree can be documented internally. Quickdocs is intentionally limited in its capabilities, so that it encourages you to document your directories, but discourages you from fussing over the format once the basic documentation is in place. The auxiliary file need not be modified as files are added and deleted, which further encourages minimalistic use: Document the important files, and let the rest take care of themselves.

Requirements and Design

What constitutes the minimum usable set of formatting commands? That is a topic that is ripe for debate. So what appears in the balance of this document is my opinion. And the accompanying software is an even stronger restatement of my opinion. You are welcome to your own opinion, and you can even use my module as a starting point, but if your opinion differs significantly from mine, then please name your opinion something other than quickdocs.

The documentation of a directory requires (in order of decreasing importance):

1. Overall documentation for the directory.
2. Per-file annotations.
3. Arbitrary grouping and ordering of the files.
4. Ignoring of uninteresting files.

5. Setting the window title.
6. Adding sections and section headers.

My one concession to purely frivolous formatting is the capability of setting the background image. Being able to set the background may improve legibility in some cases, and may also help quickdocs pages "fit" better within a larger set of web pages.

Since one of the design criteria is simplicity, I have striven to make all of these capabilities available within one auxiliary file. Therefore, in addition to the abilities provided by autoindex for reading header and footer text from a file, I provide commands which accept header and footer text as a literal argument (in the form of an HTML snippet). The command for adding a section header uses a similar syntax.

Files which are not moved to any section are listed below all sections in a normal directory listing "catchbin". In essence, the commands belonging to the original autoindex module are applied first, then the commands supported by quickdocs modify the result. Thus, in addition to determining the order of files within the catchbin, the autoindex-style sorting commands will determine the fine sorting of multiple files which are moved to a specific section using filename wildcards.

The mod_autoindex documentation is quoted below, since mod_quickdocs also provides that functionality.

Differences with mod_autoindex

There are a few changes in the basic behavior of quickdocs which I made due to expediency, efficiency considerations or personal preference. These are listed below.

In any case, I can be persuaded. If you really love the old behavior and can provide compelling arguments for restoring it, I will bow to the consensus.

• Directory names used to have a forward slash appended. But they are most often distinguished by a different icon, so there is no need for this visual clutter. It requires recopying the filename, so is wasteful of both time and memory. I took it out.
• The parent directory used to be sorted first no matter what. I pushed this behavior down into sorting by name, to simplify the comparison routines used for other sort criteria.
  Currently, directory sizes are reported as -1, so they bubble up to the top anyway. In the new implementation, the parent directory may not be on top if the modification date or description is used as the sort criterion.

How it Works

The mod_quickdocs module is based on the mod_autoindex module. The first thing it does is read the directory configuration information. It obtains this from the global configuration file (httpd.conf) on startup, and from configuration files which may appear in the directory being formatted (user selectable via the AccessFileName directive, but .htaccess by default).

The module then reads the entries in the current directory. From this, it generates a list of files, including for each its name, size and date of last modification. If the filename matches a pattern in an active IndexIgnore directive, then the file is not added to the list. If the filename matches the pattern in an active AddAlt or AddIcon directive, then alternative icon text or an icon is added to the entry, as appropriate. If the filename matches the pattern in an active AddDesc directive, then a description is added to the file entry. If the filename matches the pattern in one ore more active AddNote directives, then the annotation text from each is added to the file entry, in the order in which the AddNote directives appear.

Next, the list of files is sorted according to the current sorting criterion. This can be ascending or descending by name, size, modification date or description. Then, files are distributed among the defined sections according to the OrderFiles directives.

The final step is to assemble the web page. A page is constructed with the given title and background. The contents of any header file named in a HeaderName directive is emitted next, followed by any text provided by a SetHeader directive.

The sections are emitted next, in the order in which they were defined. The section header text is emitted first, if present, then column headers and then any files contained in that section. If some files remain unassigned to any section after the ordering phase, they will appear in a catchall section at the bottom of the page. Finally, any footer text supplied in a SetFooter directive is emitted, followed by the contents of all files named in active ReadmeName directives.

Quickdocs Directives

I give a brief list of the commands implemented only by quickdocs below, roughly in the order in which you might use them. In the following section, I provide a full listing of the commands, including their syntax, default values and full documentation. The Command Reference also restates the commands providing backward compatibility with the autoindex module.

• BackgroundName
  Specify the URI of an image to be used as the background for the page.
• SetTitle
  Text to be used as the page title (also appears in the window's title bar.
• SetHeader
  An HTML snippet to be used as the page header.
• SetFooter
  An HTML snippet to be used as the page footer.
• AddSection
  A section ID followed by an optional HTML snippet to be used as section header text.
• AddNote
  Takes a regular expression and an HTML snippet, which appears as an annotation for each matching file.
• OrderFiles
  Takes a regular expression and a section ID. Appends all files matching the regular expression to the indicated section.

BackgroundName directive

The filename argument is a relative URI which supplies the background image to be used in displaying the resulting directory listing. If multiple BackgroundName directives are supplied, only the last one is respected. Similarly, an BackgroundName directive in a Directory section or .htaccess file will override the background specified in the config file or in a parent directory.

Example:

    BackgroundName ../images/background.gif
    

SetTitle directive

This sets the page title to the given string, in place of "Directory for ...". The title string also appears in the title bar of the containing window.

SetTitle works only within an .htaccess file. It is not inherited.

Example:

    SetTitle "Documentation for C^"
    

SetHeader directive

This directive arranges for the text in string to be printed as header text in the directory listing. In contrast to the HeaderName directive, the text to be printed is given inline in the configuration file rather than being read from a file.
Note that because directives are line-delimited, end-of-line escapes must be used if the header text spans more than one line (which is altogether likely).

The descriptive text can contain HTML formatting. It is simply copied into the directory listing output in a context in which a pragraph tag would be appropriate (but not necessary).

If multiple SetHeader directives appear in an .htaccess file, only the last one is respected. The text from SetHeader directives is not inherited.

Example:

    SetHeader "<p>This directory contains files\
which document the C-caret language.<br>\
C^ was developed by language designers\
with a fondness for rabbits.</p>"
    

SetFooter directive

This directive arranges for the text in string to be printed as footer text in the directory listing. In contrast to the ReadmeName directive, the text to be printed is given inline in the configuration file rather than being read from a file.
Note that because directives are line-delimited, end-of-line escapes must be used if the header text spans more than one line (which is altogether likely).

The descriptive text can contain HTML formatting. It is simply copied into the directory listing output in a context in which a pragraph tag would be appropriate (but not necessary).

If multiple SetFooter directives appear in an .htaccess file, only the last one is respected. The text from SetFooter directives is not inherited.

Example:

    SetFooter "C^ is a trademark of\
Totally Bored Software Toolsmiths<br>\
Copyright &Copyr; 2002  TBST, Inc."
    

AddSection directive

This directive creates a new section in the directory, associated with the given sectionID, and uses the given string as descriptive text. The section ID is a (hopefully) mnemonic string which the user supplies. The section ID in an OrderFiles directive must match this mnemonic string exactly to send files to this section.

The descriptive string is quote-delimited, and can contain HTML formatting tags. It is copied into the directory listing output in a context in which a paragraph tag would be appropriate. In accordance with the general syntax for directives, the end-of-line must be escaped if the string spans multiple lines.

When formatted for output, a horizontal rule is emitted, followed by the section ID and the descriptive string. If any files have been sent to that section by one or more OrderFiles directives, then column headers and files appear next, sorted and formatted in accordance with the active sort criteria and IndexOptions.

A section initially contains nothing but its descriptive text. The OrderFiles directive is used to send files to a particular section in a particular order. Section descriptors are not inherited.

Example:

      AddSection Clutter "<H2>Directory Clutter</H2><br /> \
      This section contains files which you can ignore in most cases."
      OrderFiles Clutter *~ *.o #*#
    

AddNote directive

This directive appends the given string to the descriptive text associated with all files in the directory which match the given filename (which may contain wildcard characters). The string may contain HTML formatting tags, and is copied into the output in a context in which a paragraph tag would be appropriate.

The filename is a unix-style filename, which may include wildcard characters. All files which match the given regular expression have the descriptive text appended, in the order in which the AddNote directives appear.

Example:

      AddNote mod_quickdocs.c "Source for the quickdocs module. \
A very quick way to document the important files in a directory."
    

OrderFiles directive

The OrderFiles directive sends files matching the given regular expression to the section with the given section ID. If no section has a matching ID then matching entries are sent to the catchall bin. Because of the way in which the lists are constructed, files matching an OrderFiles directive containing a bogus section ID follow the files which do not match any OrderFiles directive.

OrderFiles directives take effect after any sorting which is done by the normal mod_autoindex directives. Files are sent to sections in the order in which the OrderFiles directives appear. If multiple files are selected by a single OrderFiles directive, then their relative order (established by the mod_autoindex sorting) is preserved.

OrderFiles directives apply only in the directory in which they are defined. They are not inherited. Like AddSection directives, they can only be defined in an .htaccess auxiliary file, not in the main configuration file.

Example:

      # Move all source files up.
      Section Code "These are the source files."
      OrderFiles Code *.c *.cc *.cpp *.cxx *.C *.CC *.h
    

Autoindex Directives

Directives having the same name as those in the autoindex module also have the same syntax and semantics in the quickdocs module. These backward-compatible directives are listed below.

• AddAlt
• AddAltByEncoding
• AddAltByType
• AddDescription
• AddIcon
• AddIconByEncoding
• AddIconByType
• DefaultIcon
• FancyIndexing
• HeaderName
• IndexIgnore
• IndexOptions
• IndexOrderDefault
• ReadmeName

See also: Options, the DirectoryIndex.

Autoindex Request Query Arguments

The column sorting headers themselves are self-referencing hyperlinks that add the sort query options to reorder the directory listing. The query options are of the form X=Y, where X is one of N (file Name), M (file last Modified date), S (file Size, or D (file Description), and Y is one of A (Ascending) or D (Descending).

When options other than the file name are used as the sorting key, the secondary key is always the file name. (When the file name is used to sort by, there is no need of a secondary sort key, since file names are guaranteed to be unique, and so the sort order is unambiguous.)

If sections are used, the column sorting headers will appear at the beginning of each section.

Example:

If the URL http://your.server.name/foo/ produces a directory index, then the following URLs will produce different sort orders:

• http://your.server.name/foo/?M=D sorts the directory by last modified date, descending.
• http://your.server.name/foo/?D=A sorts the directory by file description, ascending.
• http://your.server.name/foo/?S=A sorts the directory by file size, ascending.

See IndexOrderDefault to set the default directory ordering.

Note also that when the directory listing is ordered in one direction (ascending or descending) by a particular column, the link at the top of that column then reverses to allow sorting in the opposite direction by that same column.

AddAlt directive

This sets the alternate text to display for a file, instead of an icon, for FancyIndexing. File is a file extension, partial filename, wild-card expression or full filename for files to describe. String is enclosed in double quotes ("). This alternate text is displayed if the client is image-incapable or has image loading disabled.

Examples:

    AddAlt "PDF" *.pdf
    AddAlt "Compressed" *.gz *.zip *.Z
    

AddAltByEncoding directive

This sets the alternate text to display for a file, instead of an icon, for FancyIndexing. MIME-encoding is a valid content-encoding, such as x-compress. String is enclosed in double quotes ("). This alternate text is displayed if the client is image-incapable or has image loading disabled.

Example:

    AddAltByEncoding "gzip" x-gzip
    

AddAltByType directive

This sets the alternate text to display for a file, instead of an icon, for FancyIndexing. MIME-type is a valid content-type, such as text/html. String is enclosed in double quotes ("). This alternate text is displayed if the client is image-incapable or has image loading disabled.

Example:

    AddAltByType "TXT" text/plain
    

AddDescription directive

This sets the description to display for a file, for FancyIndexing. File is a file extension, partial filename, wild-card expression or full filename for files to describe. String is enclosed in double quotes ("). Example:

AddDescription "The planet Mars" /web/pics/mars.gif

The description field is 23 bytes wide. 7 more bytes may be added if the directory is covered by an IndexOptions SuppressSize, and 19 bytes may be added if IndexOptions SuppressLastModified is in effect. The widest this column can be is therefore 49 bytes.

As of Apache 1.3.10, the DescriptionWidth IndexOptions keyword allows you to adjust this width to any arbitrary size.

AddIcon directive

This sets the icon to display next to a file ending in name for FancyIndexing. Icon is either a (%-escaped) relative URL to the icon, or of the format (alttext,url) where alttext is the text tag given for an icon for non-graphical browsers.

Name is either ^^DIRECTORY^^ for directories, ^^BLANKICON^^ for blank lines (to format the list correctly), a file extension, a wildcard expression, a partial filename or a complete filename. Examples:

AddIcon (IMG,/icons/image2.gif) .gif .jpg .png
AddIcon /icons/dir.gif ^^DIRECTORY^^
AddIcon /icons/backup.gif *~

AddIconByEncoding directive

This sets the icon to display next to files with MIME-encoding for FancyIndexing. Icon is either a (%-escaped) relative URL to the icon, or of the format (alttext,url) where alttext is the text tag given for an icon for non-graphical browsers.

Mime-encoding is a wildcard expression matching required the content-encoding. Examples:

AddIconByEncoding /icons/compressed.gif x-compress

AddIconByType directive

This sets the icon to display next to files of type MIME-type for FancyIndexing. Icon is either a (%-escaped) relative URL to the icon, or of the format (alttext,url) where alttext is the text tag given for an icon for non-graphical browsers.

Mime-type is a wildcard expression matching required the mime types. Examples:

AddIconByType (IMG,/icons/image3.gif) image/*

DefaultIcon directive

The DefaultIcon directive sets the icon to display for files when no specific icon is known, for FancyIndexing. Url is a (%-escaped) relative URL to the icon. Examples:

DefaultIcon /icon/unknown.xbm

FancyIndexing directive

The FancyIndexing directive sets the FancyIndexing option for a directory. The IndexOptions directive should be used in preference.

Note that in versions of Apache prior to 1.3.2, the FancyIndexing and IndexOptions directives will override each other. You should use IndexOptions FancyIndexing in preference to the standalone FancyIndexing directive. As of Apache 1.3.2, a standalone FancyIndexing directive is combined with any IndexOptions directive already specified for the current scope.

HeaderName directive

The HeaderName directive sets the name of the file that will be inserted at the top of the index listing. Filename is the name of the file to include.

Apache 1.3.6 and earlier: The module first attempts to include filename.html as an HTML document, otherwise it will try to include filename as plain text. Filename is treated as a filesystem path relative to the directory being indexed. In no case is SSI processing done. Example:

HeaderName HEADER

when indexing the directory /web, the server will first look for the HTML file /web/HEADER.html and include it if found, otherwise it will include the plain text file /web/HEADER, if it exists.

Apache versions after 1.3.6: Filename is treated as a URI path relative to the one used to access the directory being indexed, and must resolve to a document with a major content type of "text" (e.g., text/html, text/plain, etc.). This means that filename may refer to a CGI script if the script's actual file type (as opposed to its output) is marked as text/html such as with a directive like:

    AddType text/html .cgi

Content negotiation will be performed if the MultiViews option is enabled. If filename resolves to a static text/html document (not a CGI script) and the Includes option is enabled, the file will be processed for server-side includes (see the mod_include documentation).

If the file specified by HeaderName contains the beginnings of an HTML document (<HTML>, <HEAD>, etc) then you will probably want to set IndexOptions +SuppressHTMLPreamble, so that these tags are not repeated.

See also ReadmeName.

IndexIgnore directive

The IndexIgnore directive adds to the list of files to hide when listing a directory. File is a file extension, partial filename, wildcard expression or full filename for files to ignore. Multiple IndexIgnore directives add to the list, rather than replacing the list of ignored files. By default, the list contains `.'. Example:

IndexIgnore README .htaccess *~

IndexOptions directive

The IndexOptions directive specifies the behavior of the directory indexing. Option can be one of

DescriptionWidth=[n | *] (Apache 1.3.10 and later)

The DescriptionWidth keyword allows you to specify the width of the description column in characters. If the keyword value is '*', then the column is automatically sized to the length of the longest filename in the display. See the section on AddDescription for dangers inherent in truncating descriptions.

FancyIndexing

This turns on fancy indexing of directories.

Note that in versions of Apache prior to 1.3.2, the FancyIndexing and IndexOptions directives will override each other. You should use IndexOptions FancyIndexing in preference to the standalone FancyIndexing directive. As of Apache 1.3.2, a standalone FancyIndexing directive is combined with any IndexOptions directive already specified for the current scope.

FoldersFirst (Apache 1.3.10 and later)

If this option is enabled, subdirectories in a FancyIndexed listing will always appear first, followed by normal files in the directory. The listing is basically broken into two components, the files and the subdirectories, and each is sorted separately and then displayed subdirectories-first. For instance, if the sort order is descending by name, and FoldersFirst is enabled, subdirectory Zed will be listed before subdirectory Beta, which will be listed before normal files Gamma and Alpha. This option only has an effect if FancyIndexing is also enabled.

IconHeight[=pixels] (Apache 1.3 and later)

Presence of this option, when used with IconWidth, will cause the server to include HEIGHT and WIDTH attributes in the IMG tag for the file icon. This allows browser to precalculate the page layout without having to wait until all the images have been loaded. If no value is given for the option, it defaults to the standard height of the icons supplied with the Apache software.

IconsAreLinks

This makes the icons part of the anchor for the filename, for fancy indexing.

IconWidth[=pixels] (Apache 1.3 and later)

Presence of this option, when used with IconHeight, will cause the server to include HEIGHT and WIDTH attributes in the IMG tag for the file icon. This allows browser to precalculate the page layout without having to wait until all the images have been loaded. If no value is given for the option, it defaults to the standard width of the icons supplied with the Apache software.

IgnoreCase

If this option is enabled, names are sorted in case-insensitive manner. For instance, if the sort order is ascending by name, and IgnoreCase is enabled, file Zeta will be listed after file alfa (Note: file GAMMA will always be listed before file gamma). This option only has an effect if FancyIndexing is also enabled.

NameWidth=[n | *] (Apache 1.3.2 and later)

The NameWidth keyword allows you to specify the width of the filename column in bytes. If the keyword value is '*', then the column is automatically sized to the length of the longest filename in the display.

ScanHTMLTitles

This enables the extraction of the title from HTML documents for fancy indexing. If the file does not have a description given by AddDescription then httpd will read the document for the value of the TITLE tag. This is CPU and disk intensive.

SuppressColumnSorting

If specified, Apache will not make the column headings in a FancyIndexed directory listing into links for sorting. The default behavior is for them to be links; selecting the column heading will sort the directory listing by the values in that column. Only available in Apache 1.3 and later.

SuppressDescription

This will suppress the file description in fancy indexing listings. By default, no file descriptions are defined, and so the use of this option will regain 23 characters of screen space to use for something else. See AddDescription for information about setting the file description. See also the DescriptionWidth index option to limit the size of the description column.

SuppressHTMLPreamble (Apache 1.3 and later)

If the directory actually contains a file specified by the HeaderName directive, the module usually includes the contents of the file after a standard HTML preamble (<HTML>, <HEAD>, et cetera). The SuppressHTMLPreamble option disables this behavior, causing the module to start the display with the header file contents. The header file must contain appropriate HTML instructions in this case. If there is no header file, the preamble is generated as usual.

SuppressLastModified

This will suppress the display of the last modification date, in fancy indexing listings.

SuppressSize

This will suppress the file size in fancy indexing listings.

TrackModified (Apache 1.3.15 and later)

This returns the Last-Modified and ETag values for the listed directory in the HTTP header. It is only valid if the operating system and file system return legitimate stat() results. Most Unix systems do so, as do OS2's JFS and Win32's NTFS volumes. OS2 and Win32 FAT volumes, for example, do not. Once this feature is enabled, the client or proxy can track changes to the list of files when they perform a HEAD request. Note some operating systems correctly track new and removed files, but do not track changes for sizes or dates of the files within the directory.

There are some noticeable differences in the behavior of this directive in recent (post-1.3.0) versions of Apache.

Apache 1.3.2 and earlier:

The default is that no options are enabled. If multiple IndexOptions could apply to a directory, then the most specific one is taken complete; the options are not merged. For example:

<Directory /web/docs>
    IndexOptions FancyIndexing
</Directory>
<Directory /web/docs/spec>
    IndexOptions ScanHTMLTitles
</Directory>

then only ScanHTMLTitles will be set for the /web/docs/spec directory.

Apache 1.3.3 and later:

Apache 1.3.3 introduced some significant changes in the handling of IndexOptions directives. In particular,

• Multiple IndexOptions directives for a single directory are now merged together. The result of the example above will now be the equivalent of IndexOptions FancyIndexing ScanHTMLTitles.
• The addition of the incremental syntax (i.e., prefixing keywords with '+' or '-').

Whenever a '+' or '-' prefixed keyword is encountered, it is applied to the current IndexOptions settings (which may have been inherited from an upper-level directory). However, whenever an unprefixed keyword is processed, it clears all inherited options and any incremental settings encountered so far. Consider the following example:

IndexOptions +ScanHTMLTitles -IconsAreLinks FancyIndexing
IndexOptions +SuppressSize


The net effect is equivalent to IndexOptions FancyIndexing +SuppressSize, because the unprefixed FancyIndexing discarded the incremental keywords before it, but allowed them to start accumulating again afterward.

To unconditionally set the IndexOptions for a particular directory, clearing the inherited settings, specify keywords without either '+' or '-' prefixes.

IndexOrderDefault directive

The IndexOrderDefault directive is used in combination with the FancyIndexing index option. By default, fancyindexed directory listings are displayed in ascending order by filename; the IndexOrderDefault allows you to change this initial display order.

IndexOrderDefault takes two arguments. The first must be either Ascending or Descending, indicating the direction of the sort. The second argument must be one of the keywords Name, Date, Size, or Description, and identifies the primary key. The secondary key is always the ascending filename.

You can force a directory listing to only be displayed in a particular order by combining this directive with the SuppressColumnSorting index option; this will prevent the client from requesting the directory listing in a different order.

ReadmeName directive

The ReadmeName directive sets the name of the file that will be appended to the end of the index listing. Filename is the name of the file to include, and is taken to be relative to the location being indexed.

The filename argument is treated as a stub filename in Apache 1.3.6 and earlier, and as a relative URI in later versions. Details of how it is handled may be found under the description of the HeaderName directive, which uses the same mechanism and changed at the same time as ReadmeName.

See also HeaderName.

Apache HTTP Server Version 1.3