Formatted output changes only...

Changes with Apache 2.0.23-dev

  *) Introduced new mod_autoindex IndexOptions flags; SuppressIcon to 

     drop the icon column, SuppressRules to drop the <hr> elements, 

     and HTMLTable to create rudimentary HTML table listings (implies 

     FancyIndexing).  [William Rowe]

  *) Re-Introduced the mod_autoindex IndexOptions flag TrackModified

     from Apache 1.3.15.  This is needed for two reasons, first, given

     multiple machines within a server farm, ETags and Last-Modified 

     stamps won't correspond from machine to machine, and second, many 

     Unixes don't capture changes to the date or time stamp of existing 

     files, since these don't modify the dirent itself.  [William Rowe]

  *) Re-Introduced the mod_autoindex InextOptions flag FoldersFirst 

     and DirectoryWidth options from Apache 1.3.10. 

     [William Rowe, Ken Coar]

  *) Eliminated FancyIndexing directive, depricated early in Apache

     1.3 by the IndexOptions FancyIndexing syntax.  [William Rowe]

  *) mod_autoindex now excludes any file names that would result in

     an error, other than a success or redirect.  [William Rowe]

     an error, other than a success or redirect.  Also optimized

     the parent directory, always included except in the URI '/'.

     [William Rowe]

  *) Refactored mod_negotiation and mod_mime to help mod_dir accept

     negotiated index pages, and prevent the server from defaulting

<!--#include virtual="header.html" -->

<H1 ALIGN="CENTER">Module mod_autoindex</H1>

This module provides for automatic directory indexing.

The module mod_autoindex generates directory indexes, automatically, similar to 

the Unix <em>ls</em> command or the Win32 <em>dir</em> shell command.

<P>

Automatic index generation must be enabled with by the <CODE>Options</CODE>

directive's <CODE><I>[+]</I>Indexes</CODE> option. See the

<A HREF="core.html#options"><CODE>Options</CODE></a> directive for

more details.

<P><A

HREF="module-dict.html#Status"

<H2>Summary</H2>

<!-- XXX: This should mention the necessity of Options +Indexes -->

The index of a directory can come from one of two sources:

<UL>

The two functions are separated so that you can completely remove

(or replace) automatic index generation should you want to.

<P>

Automatic index generation is enabled with using 

<CODE>Options +Indexes</CODE>. See the

<A HREF="core.html#options"><CODE>Options</CODE></a> directive for

more details.

<P>

If the <SAMP><A HREF="#indexoptions:fancyindexing">FancyIndexing</A></SAMP> 

option is given  with the <A HREF="#indexoptions"><SAMP>IndexOptions</SAMP></A>

directive, the column headers are links that control the

order of the display.  If you select a header link, the

listing will be regenerated, sorted by the values in that

column.  Selecting the same header repeatedly toggles

between ascending and descending order.  This can be suppressed with

<A HREF="#indexoptions">IndexOptions</A> <SAMP>SuppressColumnSorting</SAMP>.

between ascending and descending order.    These column header links are

suppressed with <A HREF="#indexoptions">IndexOptions</A> directive's

<SAMP>SuppressColumnSorting</SAMP> option.

</P>

<P>

Note that when the display is sorted by "Size",

order) even though they both are shown as "1K".

</P>

<H2>Autoindex Request Query Arguments</H2>

The column sorting headers are self-referencing hyperlinks that add the following

query options, they may be added to any request for the directory resource, where

They have no effect if the  <A HREF="#indexoptions">IndexOptions</A> directive's 

<SAMP>SuppressColumnSorting</SAMP> option is in effect.  In the list below, 

<EM>S</EM> is the desired sort order, either <SAMP>A</SAMP> for ascending or 

<SAMP>D</SAMP> for descending sequence.  

<ul>

<li><SAMP>N=<EM>S</EM></SAMP> sorts the directory by file name

<li><SAMP>M=<EM>S</EM></SAMP> sorts the directory by last-modified date, then file name

<li><SAMP>S=<EM>S</EM></SAMP> sorts the directory by size, then file name

<li><SAMP>D=<EM>S</EM></SAMP> sorts the directory by description, then file name

</ul>

<H2>Directives</H2>

 REL="Help"

><STRONG>Module:</STRONG></A> mod_autoindex<P>

This provides the alternate text to display for a file, instead of an icon, for

<SAMP><A HREF="#indexoptions:fancyindexing">FancyIndexing</A></SAMP>. <EM>File</EM> 

<EM>AddAlt</EM> provides the alternate text to display for a file, instead of an icon, 

for <SAMP><A HREF="#indexoptions:fancyindexing">FancyIndexing</A></SAMP>. <EM>File</EM> 

is a file extension, partial filename, wild-card expression or full filename for 

files to describe. <EM>String</EM> is enclosed in double quotes (<CODE>&quot;</CODE>).

This alternate text is displayed if the client is image-incapable, has image loading 

 REL="Help"

><STRONG>Module:</STRONG></A> mod_autoindex<P>

This provides the alternate text to display for a file, instead of an icon, 

for <SAMP><A HREF="#indexoptions:fancyindexing">FancyIndexing</A></SAMP>. 

<EM>AddAltByEncoding</EM> provides the alternate text to display for a file, instead 

of an icon, for <SAMP><A HREF="#indexoptions:fancyindexing">FancyIndexing</A></SAMP>. 

<EM>MIME-encoding</EM> is a valid content-encoding, such as <SAMP>x-compress</SAMP>.

<EM>String</EM> is enclosed in double quotes (<CODE>&quot;</CODE>).  This alternate 

text is displayed if the client is image-incapable, has image loading disabled, or 

 REL="Help"

><STRONG>Module:</STRONG></A> mod_autoindex<P>

This sets the alternate text to display for a file, instead of an icon, for

<SAMP><A HREF="#indexoptions:fancyindexing">FancyIndexing</A></SAMP>.  

<EM>AddAltByType</EM> sets the alternate text to display for a file, instead of 

an icon, for <SAMP><A HREF="#indexoptions:fancyindexing">FancyIndexing</A></SAMP>.  

<EM>MIME-type</EM> is a valid content-type, such as <SAMP>text/html</SAMP>. 

<EM>String</EM> is enclosed in double quotes (<CODE>&quot;</CODE>).  This 

alternate text is displayed if the client is image-incapable, has image loading 

<BLOCKQUOTE><CODE>AddDescription "The planet Mars" /web/pics/mars.gif

</CODE></BLOCKQUOTE>

<P>

The description field is 23 bytes wide.  7 more bytes may be

added if the directory is covered by an

<CODE>IndexOptions&nbsp;SuppressSize</CODE>, and 19 bytes may be

added if <CODE>IndexOptions&nbsp;SuppressLastModified</CODE> is

in effect.  The widest this column can be is therefore 49 bytes.

The typical, default description field is 23 bytes wide.  6 more bytes are

added by the <CODE>IndexOptions&nbsp;SuppressIcon</CODE> option, 7 bytes are 

added by the <CODE>IndexOptions&nbsp;SuppressSize</CODE> option, and 19 bytes

are added by the <CODE>IndexOptions&nbsp;SuppressLastModified</CODE> option.

Therefore, the widest default the description column is ever assigned is 55 bytes.

<P>

See the <a href="#indexoptions:descriptionwidth">DescriptionWidth</a>

<samp>IndexOptions</samp> keyword for details on overriding the size of this 

column, or allowing descriptions of unlimited length.

</P>

<blockquote>

As of Apache 1.3.10, the

<a href="#indexoptions:descriptionwidth">DescriptionWidth</a>

<samp>IndexOptions</samp> keyword allows you to adjust this width

to any arbitrary size.

</blockquote>

<b>Caution:</b> Descriptive text defined with <samp>AddDescription</samp>

may contain HTML markup, such as tags and character entities.  If the

width of the description column should happen to truncate a tagged

element (such as cutting off the end of a bolded phrase), the results

may affect the rest of the directory listing.

</P>

</blockquote>

<HR>

<H2><A NAME="addicon">AddIcon</A> directive</H2>

  <A

   HREF="directive-dict.html#Compatibility"

   REL="Help"

  ><STRONG>Compatibility:</STRONG></A> some features only available after

 1.3.6; see text

  ><STRONG>Compatibility:</STRONG></A> behavior changed in version 1.3.7;

 see text

<P>

The HeaderName directive sets the name of the file that will be inserted

at the top of the index listing. <EM>Filename</EM> is the name of the file

to include.

</P>

<BLOCKQUOTE><STRONG>Apache 1.3.6 and earlier:</STRONG>

The module first attempts to include <EM>filename</EM><CODE>.html</CODE>

as an HTML document, otherwise it will try to include <EM>filename</EM> as

plain text.  <EM>Filename</EM> is treated as a filesystem path relative

to the directory being indexed.  In no case is SSI processing done.

Example:

<BLOCKQUOTE><CODE>HeaderName HEADER</CODE></BLOCKQUOTE>

when indexing the directory <CODE>/web</CODE>, the server will first look for

the HTML file <CODE>/web/HEADER.html</CODE> and include it if found, otherwise

it will include the plain text file <CODE>/web/HEADER</CODE>, if it exists.

</BLOCKQUOTE>

<BLOCKQUOTE><STRONG>Apache versions after 1.3.6:</STRONG>

<EM>Filename</EM> 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 "<SAMP>text</SAMP>" (<EM>e.g.</EM>,

<SAMP>text/html</SAMP>, <SAMP>text/plain</SAMP>, <EM>etc.</EM>).

This means that <EM>filename</EM> may refer to a CGI script if the

<BLOCKQUOTE><STRONG>Changes with Apache 1.3.7:</STRONG>

Both HeaderName and <A HREF="#readmename">ReadmeName</A> now treat <EM>Filename</EM> 

as a URI path  relative to the one used to access the directory being indexed.  

<EM>Filename</EM>  must resolve to a document with a major content type of 

"<SAMP>text/*</SAMP>"  (<EM>e.g.</EM>, <SAMP>text/html</SAMP>, <SAMP>text/plain</SAMP>, 

<EM>etc.</EM>). This means that <EM>filename</EM> may refer to a CGI script if the

script's actual file type (as opposed to its output) is marked as

<SAMP>text/html</SAMP> such as with a directive like:

<PRE>

<H2><A NAME="indexoptions">IndexOptions</A> directive</H2>

<!--%plaintext &lt;?INDEX {\tt IndexOptions} directive&gt; -->

<A

 HREF="directive-dict.html#Syntax"

 REL="Help"

><STRONG>Syntax:</STRONG></A> IndexOptions <EM>option</em> 

   [<em>option</em>] ... (Apache 1.3.2 and earlier)

<BR>

<A

 HREF="directive-dict.html#Syntax"

 REL="Help"

 REL="Help"

><STRONG>Compatibility:</STRONG></A> '+/-' syntax and merging of multiple

 <SAMP>IndexOptions</SAMP> directives is only available with

 Apache 1.3.3 and later; the <samp>FoldersFirst</samp> and

 <samp>DescriptionWidth</samp> options are only

 available with Apache 1.3.10 and later

 Apache 1.3.3 and later; specific options are listed below.

<P>

The IndexOptions directive specifies the behavior of the directory indexing.

<EM>Option</EM> can be one of

<DL>

<dt><a name="indexoptions:descriptionwidth">DescriptionWidth=[<em>n</em> | *]

 (<em>Apache 1.3.10 and later</em>)</a>

<dd>

The <samp>DescriptionWidth</samp> keyword allows you to specify the

width of the description column in characters.  If the keyword value

is '<samp>*</samp>', then the column is automatically sized to the

length of the longest filename in the display.

<b>See the section on <a href="#adddescription"><samp>AddDescription</samp></a>

 (<em>Apache 1.3.10 or 2.0.23 and later</em>)</a></dt>

<dd>The <samp>DescriptionWidth</samp> keyword allows you to specify the

width of the description column in characters.</dd>

<dd><samp>-DescriptionWidth</samp> (or unset) allows mod_autoindex to calculate 

the best width.</dd>

<dd><samp>DescriptionWidth=n</samp> fixes the column width to n bytes wide.</dd>

<dd><samp>DescriptionWidth=*</samp> grows the column to the necessary width.</dd>

<dd><b>See the section on <a href="#adddescription"><samp>AddDescription</samp></a>

for dangers inherent in truncating descriptions.</b></dd>

<DT><A NAME="indexoptions:fancyindexing">FancyIndexing</A>

<DD><!--%plaintext &lt;?INDEX {\tt FancyIndexing} index option&gt; -->

This turns on fancy indexing of directories.

<dt><a name="indexoptions:foldersfirst">FoldersFirst

 (<i>Apache 1.3.10 and later</i>)</a></dt>

 (<i>Apache 1.3.10  or 2.0.23 and later</i>)</a></dt>

<dd>

If this option is enabled, subdirectory listings

will <i>always</i> appear first, followed by normal files in the

<b>This option only has an effect if

<a href="#indexoptions:fancyindexing"><samp>FancyIndexing</samp></a>

is also enabled.</b></dd>

<DT><A NAME="indexoptions:htmltable">HTMLTable</A>

 <i>(Experimental, Apache 2.0.23 and later)</i>

<DD><!--%plaintext &lt;?INDEX {\tt HTMLTable} index option&gt; -->

This experimental option with FancyIndexing constructs a simple table for the 

fancy directory listing.  Note this will confuse older browsers.  It is particularly

necessary if file names or description text will alternate between left-to-right 

and right-to-left reading order, as can happen on WinNT or other utf-8 

enabled platforms.

<DT><A NAME="indexoptions:iconheight">IconHeight[=pixels] (<EM>Apache 1.3 and later</EM>)</A>

<DD>

<!--%plaintext &lt;?INDEX {\tt IconHeight} index option&gt; -->

<DT><A NAME="indexoptions:namewidth">NameWidth=[<EM>n</EM> | *] (<EM>Apache 1.3.2 and later</EM>)</A>

<DD>

The NameWidth keyword allows you to specify the width of the

filename column in bytes.  If the keyword value is '<SAMP>*</SAMP>',

then the column is automatically sized to the length of the longest

filename in the display.

<DT><A NAME="indexoptions:versionsort">VersionSort (<EM>Apache 2.0a3 and later</EM>)</A>

<DD>

The VersionSort keyword causes files containing version numbers to

sort in a natural way.  Strings are sorted as usual, except that

substrings of digits in the name and description are compared

according to their numeric value.

For example:

<BLOCKQUOTE><pre>

foo-1.7

foo-1.7.2

foo-1.7.12

foo-1.8.2

foo-1.8.2a

foo-1.12

</pre></BLOCKQUOTE>

If the number starts with a zero, then it is considered to be a

	fraction:

<BLOCKQUOTE><pre>

foo-1.001

foo-1.002

foo-1.030

foo-1.04

</pre></BLOCKQUOTE>

filename column in bytes.  

<dd><samp>-NameWidth</samp> (or unset) allows mod_autoindex to calculate 

the best width.</dd>

<dd><samp>NameWidth=n</samp> fixes the column width to n bytes wide.</dd>

<dd><samp>NameWidth=*</samp> grows the column to the necessary width.</dd>

<DT><A NAME="indexoptions:scanhtmltitles">ScanHTMLTitles</A>

<DD><!--%plaintext &lt;?INDEX {\tt ScanHTMLTitles} index option&gt; -->

This enables the extraction of the title from HTML documents for fancy

<A HREF="#adddescription">AddDescription</A> then httpd will read the

document for the value of the TITLE tag.  This is CPU and disk intensive.

<DT><A NAME="indexoptions:suppresscolumnsorting">SuppressColumnSorting</A>

    (<EM>Apache 1.3 and later</EM>)

<DD>

<!--%plaintext &lt;?INDEX {\tt SuppressColumnSorting} index option&gt; -->

If specified, Apache will not make the column headings in a FancyIndexed

directory listing into links for sorting.  The default behaviour is

for them to be links; selecting the column heading will sort the directory

listing by the values in that column.

<STRONG>Only available in Apache 1.3 and later.</STRONG>

<DT><A NAME="indexoptions:suppressdescription">SuppressDescription</A>

<DD>

<!--%plaintext &lt;?INDEX {\tt SuppressDescription} index option&gt; -->

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.

<DT><A NAME="indexoptions:suppressicon">SuppressIcon</A>

    (<EM>Apache 2.0.23 and later</EM>)

<DD>

<!--%plaintext &lt;?INDEX {\tt SuppressIcon} index option&gt; -->

This will suppress the icon in fancy indexing listings.  Combining

both <EM>SuppressIcon</EM> and <EM>SuppressRules</EM> yeilds proper 

HTML 3.2 output, which by the final specification prohibits IMG and HR 

tags from the PRE block (used to format FancyIndexed listings.)

<DT><A NAME="indexoptions:suppresslastmodified">SuppressLastModified</A>

<DD>

<!--%plaintext &lt;?INDEX {\tt SuppressLastModified} index option&gt; -->

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

indexing listings.

<DT><A NAME="indexoptions:suppressrules">SuppressRules</A>

    (<EM>Apache 2.0.23 and later</EM>)

<DD>

<!--%plaintext &lt;?INDEX {\tt SuppressRules} index option&gt; -->

This will suppress the horizontal rule lines (HR tags) in directory listings.  

Combining both <EM>SuppressIcon</EM> and <EM>SuppressRules</EM> yeilds proper 

HTML 3.2 output, which by the final specification prohibits IMG and HR tags 

from the PRE block (used to format FancyIndexed listings.)

<DT><A NAME="indexoptions:suppresssize">SuppressSize</A>

<DD>

<!--%plaintext &lt;?INDEX {\tt SuppressSize} index option&gt; -->

This will suppress the file size in fancy indexing listings.

</DL>

<P>

There are some noticeable differences in the behaviour of this

directive in recent (post-1.3.0) versions of Apache.

</P>

<DL>

<DT>Apache 1.3.2 and earlier:</DT>

<DT><A NAME="indexoptions:trackmodified">TrackModified 

(<EM>Apache 1.3.15 or 2.0.23 and later</EM>)</A>

<DD>

<P>

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:

<!--%plaintext &lt;?INDEX {\tt TrackModified} index option&gt; -->

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 appropriate stat() results.  Some 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.

<STRONG>Changes to the size or date stamp of an existing file will not

update the Last-Modified header on all Unix platforms.</STRONG> If this

is a concern, leave this option disabled.

<DT><A NAME="indexoptions:versionsort">VersionSort (<EM>Apache 2.0a3 and later</EM>)</A>

<DD>

The VersionSort keyword causes files containing version numbers to

sort in a natural way.  Strings are sorted as usual, except that

substrings of digits in the name and description are compared

according to their numeric value.

For example:

<BLOCKQUOTE><pre>

<Directory /web/docs>

    IndexOptions FancyIndexing

</Directory>

<Directory /web/docs/spec>

    IndexOptions ScanHTMLTitles

</Directory>

foo-1.7

foo-1.7.2

foo-1.7.12

foo-1.8.2

foo-1.8.2a

foo-1.12

</pre></BLOCKQUOTE>

then only <CODE>ScanHTMLTitles</CODE> will be set for the /web/docs/spec

directory.

</P>

</DD>

<DT>Apache 1.3.3 and later:</DT>

<DD>

<P>

Apache 1.3.3 introduced some significant changes in the handling of

If the number starts with a zero, then it is considered to be a

	fraction:

<BLOCKQUOTE><pre>

foo-1.001

foo-1.002

foo-1.030

foo-1.04

</pre></BLOCKQUOTE>

<DT><H3>Incremental IndexOptions</H3>

<DD>Apache 1.3.3 introduced some significant changes in the handling of

<SAMP>IndexOptions</SAMP> directives.  In particular,

</P>

<BR /><BR />

<UL>

 <LI>Multiple <SAMP>IndexOptions</SAMP> directives for a single

  directory are now merged together.  The result of the example above

  keywords with '+' or '-').

 </LI>

</UL>

<P>

<BR />

Whenever a '+' or '-' prefixed keyword is encountered, it is applied

to the current <SAMP>IndexOptions</SAMP> 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:

</P>

<BLOCKQUOTE><CODE>IndexOptions +ScanHTMLTitles -IconsAreLinks FancyIndexing

<BR>

<BR />

IndexOptions +SuppressSize

<BR>

<BR />

</CODE></BLOCKQUOTE>

<P>

The net effect is equivalent to

<CODE>IndexOptions&nbsp;FancyIndexing&nbsp;+SuppressSize</CODE>, because

the unprefixed <CODE>FancyIndexing</CODE> discarded the incremental

keywords before it, but allowed them to start accumulating again

afterward.

</P>

<P>

<BR /><BR />

To unconditionally set the <CODE>IndexOptions</CODE> for a

particular directory, clearing the inherited settings, specify

keywords without either '+' or '-' prefixes.

</P>

keywords without any '+' or '-' prefixes.

</DD>

</DL>

   HREF="directive-dict.html#Compatibility"

   REL="Help"

  ><STRONG>Compatibility:</STRONG></A> some features only available after

 1.3.6; see text

 1.3.6; see <A HREF="#headername">HeaderName</A>

<P>

The ReadmeName directive sets the name of the file that will be appended

to the end of the index listing. <EM>Filename</EM> is the name of the file

to include, and is taken to be relative to the location being indexed.

</P>

<BLOCKQUOTE>

<STRONG>The <EM>filename</EM> 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 <A HREF="#headername">HeaderName</A> directive, which uses the

same mechanism and changed at the same time as ReadmeName.</STRONG>

</BLOCKQUOTE>

<P>See also <A HREF="#headername">HeaderName</A>.<P>

<P>See also <A HREF="#headername">HeaderName</A>, where this behavior is

described in greater detail.<P>

<!--#include virtual="footer.html" -->