diff options
author | William A. Rowe Jr <wrowe@apache.org> | 2001-08-07 06:33:58 +0200 |
---|---|---|
committer | William A. Rowe Jr <wrowe@apache.org> | 2001-08-07 06:33:58 +0200 |
commit | 5c1fdbd27d71456eaa99e9024e04b4441a18892c (patch) | |
tree | e8722235a7d1a733f3d826b23f2a28cb3bb648cd /docs | |
parent | Fix a segfault (was getting triggered by mod_include at least) caused (diff) | |
download | apache2-5c1fdbd27d71456eaa99e9024e04b4441a18892c.tar.xz apache2-5c1fdbd27d71456eaa99e9024e04b4441a18892c.zip |
Formatted output changes only...
Introduced new mod_autoindex IndexOptions flags; SuppressIcon to
drop the icon column and SuppressRules to drop the <hr> elements.
These are necessary for HTML 3.2 final formatting rules.
Introduced HTMLTable to create rudimentary HTML table listings
(implies FancyIndexing). Necessary for alternate charsets, since
the columns are borked by multibyte characters.
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.
[Originally for 1.3 by me]
Re-Introduced the mod_autoindex InextOptions flag FoldersFirst
and DirectoryWidth options from Apache 1.3.10.
[Originally for 1.3 by Ken Coar]
git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@89979 13f79535-47bb-0310-9956-ffa450edef68
Diffstat (limited to 'docs')
-rw-r--r-- | docs/manual/mod/mod_autoindex.html | 275 |
1 files changed, 145 insertions, 130 deletions
diff --git a/docs/manual/mod/mod_autoindex.html b/docs/manual/mod/mod_autoindex.html index dab43f9e83..d793b2e353 100644 --- a/docs/manual/mod/mod_autoindex.html +++ b/docs/manual/mod/mod_autoindex.html @@ -15,7 +15,14 @@ <!--#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" @@ -35,7 +42,6 @@ REL="Help" <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> @@ -55,14 +61,20 @@ are controlled by <CODE>mod_autoindex</CODE>. 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", @@ -72,6 +84,22 @@ always be displayed before a 1011-byte file (if in ascending 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> @@ -121,8 +149,8 @@ HREF="mod_dir.html#directoryindex">DirectoryIndex</A>.</p> 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>"</CODE>). This alternate text is displayed if the client is image-incapable, has image loading @@ -154,8 +182,8 @@ disabled, or fails to retrieve the icon. 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>"</CODE>). This alternate text is displayed if the client is image-incapable, has image loading disabled, or @@ -187,8 +215,8 @@ fails to retrieve the icon. 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>"</CODE>). This alternate text is displayed if the client is image-incapable, has image loading @@ -229,23 +257,23 @@ quotes (<CODE>"</CODE>). Example: <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 SuppressSize</CODE>, and 19 bytes may be -added if <CODE>IndexOptions 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 SuppressIcon</CODE> option, 7 bytes are +added by the <CODE>IndexOptions SuppressSize</CODE> option, and 19 bytes +are added by the <CODE>IndexOptions 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> @@ -437,31 +465,20 @@ in Apache 2.0. <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> @@ -518,12 +535,6 @@ IndexIgnore README .htaccess *~ <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" ><STRONG>Syntax:</STRONG></A> IndexOptions [+|-]<em>option</em> [[+|-]<em>option</em>] ... (Apache 1.3.3 and later) <BR> @@ -550,28 +561,27 @@ IndexIgnore README .htaccess *~ 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 <?INDEX {\tt FancyIndexing} index option> --> 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 @@ -585,6 +595,14 @@ subdirectory <samp>Zed</samp> will be listed before subdirectory <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 <?INDEX {\tt HTMLTable} index option> --> +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 <?INDEX {\tt IconHeight} index option> --> @@ -613,34 +631,11 @@ software. <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 <?INDEX {\tt ScanHTMLTitles} index option> --> This enables the extraction of the title from HTML documents for fancy @@ -648,13 +643,13 @@ indexing. If the file does not have a description given by <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 <?INDEX {\tt SuppressColumnSorting} index option> --> 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 <?INDEX {\tt SuppressDescription} index option> --> @@ -673,45 +668,75 @@ cetera</EM>). The SuppressHTMLPreamble option disables this behaviour, 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 <?INDEX {\tt SuppressIcon} index option> --> +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 <?INDEX {\tt SuppressLastModified} index option> --> 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 <?INDEX {\tt SuppressRules} index option> --> +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 <?INDEX {\tt SuppressSize} index option> --> 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 <?INDEX {\tt TrackModified} index option> --> +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 @@ -722,30 +747,26 @@ Apache 1.3.3 introduced some significant changes in the handling of 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 FancyIndexing +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> @@ -839,21 +860,15 @@ the client from requesting the directory listing in a different order. 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" --> |