granicus.if.org Git - apache/blob - docs/manual/mod/mod_autoindex.xml

   1 <?xml version="1.0"?>
   2 <!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd">
   3 <?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
   4 <!-- $Revision: 1.25 $ -->
   5
   6 <!--
   7  Copyright 2002-2004 The Apache Software Foundation
   8
   9  Licensed under the Apache License, Version 2.0 (the "License");
  10  you may not use this file except in compliance with the License.
  11  You may obtain a copy of the License at
  12
  13      http://www.apache.org/licenses/LICENSE-2.0
  14
  15  Unless required by applicable law or agreed to in writing, software
  16  distributed under the License is distributed on an "AS IS" BASIS,
  17  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  18  See the License for the specific language governing permissions and
  19  limitations under the License.
  20 -->
  21
  22 <modulesynopsis metafile="mod_autoindex.xml.meta">
  23 <name>mod_autoindex</name>
  24
  25 <description>Generates directory indexes,
  26     automatically, similar to the Unix <code>ls</code> command or the
  27     Win32 <code>dir</code> shell command</description>
  28 <status>Base</status>
  29 <sourcefile>mod_autoindex.c</sourcefile>
  30 <identifier>autoindex_module</identifier>
  31
  32 <summary>
  33       <p>The index of a directory can come from one of two
  34       sources:</p>
  35
  36     <ul>
  37       <li>A file written by the user, typically called
  38       <code>index.html</code>. The <directive
  39       module="mod_dir">DirectoryIndex</directive> directive sets the
  40       name of this file. This is controlled by
  41       <module>mod_dir</module>.</li>
  42
  43       <li>Otherwise, a listing generated by the server. The other
  44       directives control the format of this listing. The <directive
  45       module="mod_autoindex">AddIcon</directive>, <directive
  46       module="mod_autoindex">AddIconByEncoding</directive> and
  47       <directive module="mod_autoindex">AddIconByType</directive> are
  48       used to set a list of icons to display for various file types;
  49       for each file listed, the first icon listed that matches the
  50       file is displayed. These are controlled by
  51       <module>mod_autoindex</module>.</li>
  52     </ul>
  53     <p>The two functions are separated so that you can completely
  54     remove (or replace) automatic index generation should you want
  55     to.</p>
  56
  57     <p>Automatic index generation is enabled with using
  58     <code>Options +Indexes</code>. See the
  59     <directive module="core">Options</directive> directive for
  60     more details.</p>
  61
  62     <p>If the <code><a href="#indexoptions.fancyindexing"
  63     >FancyIndexing</a></code> option is given with the <directive
  64     module="mod_autoindex">IndexOptions</directive> directive,
  65     the column headers are links that control the order of the
  66     display. If you select a header link, the listing will be
  67     regenerated, sorted by the values in that column. Selecting the
  68     same header repeatedly toggles between ascending and descending
  69     order. These column header links are suppressed with
  70     <directive module="mod_autoindex">IndexOptions</directive> directive's
  71     <code>SuppressColumnSorting</code> option.</p>
  72
  73     <p>Note that when the display is sorted by "Size", it's the
  74     <em>actual</em> size of the files that's used, not the
  75     displayed value - so a 1010-byte file will always be displayed
  76     before a 1011-byte file (if in ascending order) even though
  77     they both are shown as "1K".</p>
  78 </summary>
  79
  80 <section id="query">
  81     <title>Autoindex Request Query Arguments</title>
  82
  83     <p>Apache 2.0.23 reorganized the Query Arguments for Column
  84     Sorting, and introduced an entire group of new query options.
  85     To effectively eliminate all client control over the output,
  86     the <code><a href="#indexoptions.ignoreclient">IndexOptions
  87     IgnoreClient</a></code> option was introduced.</p>
  88
  89     <p>The column sorting headers themselves are self-referencing
  90     hyperlinks that add the sort query options shown below. Any
  91     option below may be added to any request for the directory
  92     resource.</p>
  93
  94     <ul>
  95       <li><code>C=N</code> sorts the directory by file name</li>
  96
  97       <li><code>C=M</code> sorts the directory by last-modified
  98       date, then file name</li>
  99
 100       <li><code>C=S</code> sorts the directory by size, then file
 101       name</li>
 102
 103       <li class="separate"><code>C=D</code> sorts the directory by description, then
 104       file name</li>
 105
 106       <li><code>O=A</code> sorts the listing in Ascending
 107       Order</li>
 108
 109       <li class="separate"><code>O=D</code> sorts the listing in Descending
 110       Order</li>
 111
 112       <li><code>F=0</code> formats the listing as a simple list
 113       (not FancyIndexed)</li>
 114
 115       <li><code>F=1</code> formats the listing as a FancyIndexed
 116       list</li>
 117
 118       <li class="separate"><code>F=2</code> formats the listing as an
 119       HTMLTable FancyIndexed list</li>
 120
 121       <li><code>V=0</code> disables version sorting</li>
 122
 123       <li class="separate"><code>V=1</code> enables version sorting</li>
 124
 125       <li><code>P=<var>pattern</var></code> lists only files matching
 126       the given <var>pattern</var></li>
 127     </ul>
 128
 129     <p>Note that the 'P'attern query argument is tested
 130     <em>after</em> the usual <directive module="mod_autoindex"
 131     >IndexIgnore</directive> directives are processed,
 132     and all file names are still subjected to the same criteria as
 133     any other autoindex listing. The Query Arguments parser in
 134     <module>mod_autoindex</module> will stop abruptly when an unrecognized
 135     option is encountered. The Query Arguments must be well formed,
 136     according to the table above.</p>
 137
 138     <p>The simple example below, which can be clipped and saved in
 139     a header.html file, illustrates these query options. Note that
 140     the unknown "X" argument, for the submit button, is listed last
 141     to assure the arguments are all parsed before mod_autoindex
 142     encounters the X=Go input.</p>
 143
 144     <example>
 145       &lt;form action="" method="get"&gt;<br />
 146       <indent>
 147         Show me a &lt;select name="F"&gt;<br />
 148         <indent>
 149           &lt;option value="0"&gt; Plain list&lt;/option&gt;<br />
 150           &lt;option value="1" selected="selected"&gt; Fancy list&lt;/option&gt;<br />
 151           &lt;option value="2"&gt; Table list&lt;/option&gt;<br />
 152         </indent>
 153         &lt;/select&gt;<br />
 154         Sorted by &lt;select name="C"&gt;<br />
 155         <indent>
 156           &lt;option value="N" selected="selected"&gt; Name&lt;/option&gt;<br />
 157           &lt;option value="M"&gt; Date Modified&lt;/option&gt;<br />
 158           &lt;option value="S"&gt; Size&lt;/option&gt;<br />
 159           &lt;option value="D"&gt; Description&lt;/option&gt;<br />
 160         </indent>
 161         &lt;/select&gt;<br />
 162         &lt;select name="O"&gt;<br />
 163         <indent>
 164           &lt;option value="A" selected="selected"&gt; Ascending&lt;/option&gt;<br />
 165           &lt;option value="D"&gt; Descending&lt;/option&gt;<br />
 166         </indent>
 167         &lt;/select&gt;<br />
 168         &lt;select name="V"&gt;<br />
 169         <indent>
 170           &lt;option value="0" selected="selected"&gt; in Normal order&lt;/option&gt;<br />
 171           &lt;option value="1"&gt; in Version order&lt;/option&gt;<br />
 172         </indent>
 173         &lt;/select&gt;<br />
 174         Matching &lt;input type="text" name="P" value="*" /&gt;<br />
 175         &lt;input type="submit" name="X" value="Go" /&gt;<br />
 176       </indent>
 177       &lt;/form&gt;
 178     </example>
 179
 180 </section>
 181
 182 <directivesynopsis>
 183 <name>AddAlt</name>
 184 <description>Alternate text to display for a file, instead of an
 185 icon selected by filename</description>
 186 <syntax>AddAlt <var>string</var> <var>file</var> [<var>file</var>] ...</syntax>
 187 <contextlist><context>server config</context><context>virtual host</context>
 188 <context>directory</context><context>.htaccess</context>
 189 </contextlist>
 190 <override>Indexes</override>
 191
 192 <usage>
 193     <p><directive>AddAlt</directive> provides the alternate text to
 194     display for a file, instead of an icon, for <code><a
 195     href="#indexoptions.fancyindexing">FancyIndexing</a></code>.
 196     <var>File</var> is a file extension, partial filename, wild-card
 197     expression or full filename for files to describe.
 198     If <var>String</var> contains any whitespace, you have to enclose it
 199     in quotes (<code>"</code> or <code>'</code>). This alternate text
 200     is displayed if the client is image-incapable, has image loading
 201     disabled, or fails to retrieve the icon.</p>
 202
 203     <example><title>Examples</title>
 204       AddAlt "PDF file" *.pdf<br />
 205       AddAlt Compressed *.gz *.zip *.Z
 206     </example>
 207 </usage>
 208 </directivesynopsis>
 209
 210 <directivesynopsis>
 211 <name>AddAltByEncoding</name>
 212 <description>Alternate text to display for a file instead of an icon
 213 selected by MIME-encoding</description>
 214 <syntax>AddAltByEncoding <var>string</var> <var>MIME-encoding</var>
 215 [<var>MIME-encoding</var>] ...</syntax>
 216 <contextlist><context>server config</context><context>virtual host</context>
 217 <context>directory</context><context>.htaccess</context>
 218 </contextlist>
 219 <override>Indexes</override>
 220
 221 <usage>
 222     <p><directive>AddAltByEncoding</directive> provides the alternate
 223     text to display for a file, instead of an icon, for <code><a
 224     href="#indexoptions.fancyindexing">FancyIndexing</a></code>.
 225     <var>MIME-encoding</var> is a valid content-encoding, such as
 226     <code>x-compress</code>. If <var>String</var> contains any whitespace,
 227     you have to enclose it in quotes (<code>"</code> or <code>'</code>).
 228     This alternate text is displayed if the client is image-incapable,
 229     has image loading disabled, or fails to retrieve the icon.</p>
 230
 231     <example><title>Example</title>
 232       AddAltByEncoding gzip x-gzip
 233     </example>
 234 </usage>
 235 </directivesynopsis>
 236
 237 <directivesynopsis>
 238 <name>AddAltByType</name>
 239 <description>Alternate text to display for a file, instead of an
 240 icon selected by MIME content-type</description>
 241 <syntax>AddAltByType <var>string</var> <var>MIME-type</var>
 242 [<var>MIME-type</var>] ...</syntax>
 243 <contextlist><context>server config</context><context>virtual host</context>
 244 <context>directory</context><context>.htaccess</context>
 245 </contextlist>
 246 <override>Indexes</override>
 247
 248 <usage>
 249     <p><directive>AddAltByType</directive> sets the alternate text to
 250     display for a file, instead of an icon, for <code><a
 251     href="#indexoptions.fancyindexing">FancyIndexing</a></code>.
 252     <var>MIME-type</var> is a valid content-type, such as
 253     <code>text/html</code>. If <var>String</var> contains any whitespace,
 254     you have to enclose it in quotes (<code>"</code> or <code>'</code>).
 255     This alternate text is displayed if the client is image-incapable,
 256     has image loading disabled, or fails to retrieve the icon.</p>
 257
 258     <example><title>Example</title>
 259       AddAltByType 'plain text' text/plain
 260     </example>
 261 </usage>
 262 </directivesynopsis>
 263
 264 <directivesynopsis>
 265 <name>AddDescription</name>
 266 <description>Description to display for a file</description>
 267 <syntax>AddDescription <var>string file</var> [<var>file</var>] ...</syntax>
 268 <contextlist><context>server config</context><context>virtual host</context>
 269 <context>directory</context><context>.htaccess</context>
 270 </contextlist>
 271 <override>Indexes</override>
 272
 273 <usage>
 274     <p>This sets the description to display for a file, for
 275     <code><a href="#indexoptions.fancyindexing"
 276     >FancyIndexing</a></code>.
 277     <var>File</var> is a file extension, partial filename, wild-card
 278     expression or full filename for files to describe.
 279     <var>String</var> is enclosed in double quotes (<code>"</code>).</p>
 280
 281     <example><title>Example</title>
 282       AddDescription "The planet Mars" /web/pics/mars.gif
 283     </example>
 284
 285     <p>The typical, default description field is 23 bytes wide. 6
 286     more bytes are added by the <code><a href="#indexoptions.suppressicon"
 287     >IndexOptions SuppressIcon</a></code> option, 7 bytes are
 288     added by the <code><a href="#indexoptions.suppresssize"
 289     >IndexOptions SuppressSize</a></code> option, and 19 bytes are
 290     added by the <code><a href="#indexoptions.suppresslastmodified"
 291     >IndexOptions SuppressLastModified</a></code> option.
 292     Therefore, the widest default the description column is ever
 293     assigned is 55 bytes.</p>
 294
 295     <p>See the <a href="#indexoptions.descriptionwidth"
 296     >DescriptionWidth</a> <directive module="mod_autoindex"
 297     >IndexOptions</directive> keyword for details on overriding the size
 298     of this column, or allowing descriptions of unlimited length.</p>
 299
 300     <note><title>Caution</title>
 301       <p>Descriptive text defined with <directive>AddDescription</directive>
 302       may contain HTML markup, such as tags and character entities. If the
 303       width of the description column should happen to truncate a tagged
 304       element (such as cutting off the end of a bolded phrase), the
 305       results may affect the rest of the directory listing.</p>
 306     </note>
 307 </usage>
 308 </directivesynopsis>
 309
 310 <directivesynopsis>
 311 <name>AddIcon</name>
 312 <description>Icon to display for a file selected by name</description>
 313 <syntax>AddIcon <var>icon</var> <var>name</var> [<var>name</var>]
 314 ...</syntax>
 315 <contextlist><context>server config</context><context>virtual host</context>
 316 <context>directory</context><context>.htaccess</context>
 317 </contextlist>
 318 <override>Indexes</override>
 319
 320 <usage>
 321     <p>This sets the icon to display next to a file ending in
 322     <var>name</var> for <code><a href="#indexoptions.fancyindexing"
 323     >FancyIndexing</a></code>. <var>Icon</var> is either a (%-escaped)
 324     relative URL to the icon, or of the format <code>
 325     (<var>alttext</var>,<var>url</var>)</code> where <var>alttext</var>
 326     is the text tag given for an icon for non-graphical browsers.</p>
 327
 328     <p><var>Name</var> is either <code>^^DIRECTORY^^</code> for directories,
 329     <code>^^BLANKICON^^</code> for blank lines (to format the list
 330     correctly), a file extension, a wildcard expression, a partial
 331     filename or a complete filename.</p>
 332
 333     <example><title>Examples</title>
 334       AddIcon (IMG,/icons/image.xbm) .gif .jpg .xbm<br />
 335       AddIcon /icons/dir.xbm ^^DIRECTORY^^<br />
 336       AddIcon /icons/backup.xbm *~
 337     </example>
 338
 339     <p><directive module="mod_autoindex">AddIconByType</directive>
 340     should be used in preference to <directive>AddIcon</directive>,
 341     when possible.</p>
 342 </usage>
 343 </directivesynopsis>
 344
 345 <directivesynopsis>
 346 <name>AddIconByEncoding</name>
 347 <description>Icon to display next to files selected by MIME
 348 content-encoding</description>
 349 <syntax>AddIconByEncoding <var>icon</var> <var>MIME-encoding</var>
 350 [<var>MIME-encoding</var>] ...</syntax>
 351 <contextlist><context>server config</context><context>virtual host</context>
 352 <context>directory</context><context>.htaccess</context>
 353 </contextlist>
 354 <override>Indexes</override>
 355
 356 <usage>
 357     <p>This sets the icon to display next to files with <code><a
 358     href="#indexoptions.fancyindexing">FancyIndexing</a></code>.
 359     <var>Icon</var> is either a (%-escaped) relative URL to the icon,
 360     or of the format <code>(<var>alttext</var>,<var>url</var>)</code>
 361     where <var>alttext</var> is the text tag given for an icon for
 362     non-graphical browsers.</p>
 363
 364     <p><var>MIME-encoding</var> is a wildcard expression matching
 365     required the content-encoding.</p>
 366
 367     <example><title>Example</title>
 368       AddIconByEncoding /icons/compress.xbm x-compress
 369     </example>
 370 </usage>
 371 </directivesynopsis>
 372
 373 <directivesynopsis>
 374 <name>AddIconByType</name>
 375 <description>Icon to display next to files selected by MIME
 376 content-type</description>
 377 <syntax>AddIconByType <var>icon</var> <var>MIME-type</var>
 378 [<var>MIME-type</var>] ...</syntax>
 379 <contextlist><context>server config</context><context>virtual host</context>
 380 <context>directory</context><context>.htaccess</context>
 381 </contextlist>
 382 <override>Indexes</override>
 383
 384 <usage>
 385     <p>This sets the icon to display next to files of type
 386     <var>MIME-type</var> for <code><a
 387     href="#indexoptions.fancyindexing">FancyIndexing</a></code>.
 388     <var>Icon</var> is either a (%-escaped) relative URL to the icon,
 389     or of the format <code>(<var>alttext</var>,<var>url</var>)</code>
 390     where <var>alttext</var> is the text tag given for an icon for
 391     non-graphical browsers.</p>
 392
 393     <p><var>MIME-type</var> is a wildcard expression matching
 394     required the mime types.</p>
 395
 396     <example><title>Example</title>
 397       AddIconByType (IMG,/icons/image.xbm) image/*
 398     </example>
 399 </usage>
 400 </directivesynopsis>
 401
 402 <directivesynopsis>
 403 <name>DefaultIcon</name>
 404 <description>Icon to display for files when no specific icon is
 405 configured</description>
 406 <syntax>DefaultIcon <var>url-path</var></syntax>
 407 <contextlist><context>server config</context><context>virtual host</context>
 408 <context>directory</context><context>.htaccess</context>
 409 </contextlist>
 410 <override>Indexes</override>
 411
 412 <usage>
 413     <p>The <directive>DefaultIcon</directive> directive sets the icon
 414     to display for files when no specific icon is known, for <code><a
 415     href="#indexoptions.fancyindexing">FancyIndexing</a></code>.
 416     <var>Url-path</var> is a (%-escaped) relative URL to the icon.</p>
 417
 418     <example><title>Example</title>
 419       DefaultIcon /icon/unknown.xbm
 420     </example>
 421 </usage>
 422 </directivesynopsis>
 423
 424 <directivesynopsis>
 425 <name>HeaderName</name>
 426 <description>Name of the file that will be inserted at the top
 427 of the index listing</description>
 428 <syntax>HeaderName <var>filename</var></syntax>
 429 <contextlist><context>server config</context><context>virtual host</context>
 430 <context>directory</context><context>.htaccess</context>
 431 </contextlist>
 432 <override>Indexes</override>
 433
 434 <usage>
 435     <p>The <directive>HeaderName</directive> directive sets the name
 436     of the file that will be inserted at the top of the index
 437     listing. <var>Filename</var> is the name of the file to include.</p>
 438
 439     <example><title>Example</title>
 440       HeaderName HEADER.html
 441     </example>
 442
 443     <note>
 444       <p>Both HeaderName and <directive
 445       module="mod_autoindex">ReadmeName</directive> now treat
 446       <var>Filename</var> as a URI path relative to the one used to
 447       access the directory being indexed. If <var>Filename</var> begins
 448       with a slash, it will be taken to be relative to the <directive
 449       module="core">DocumentRoot</directive>.</p>
 450
 451       <example><title>Example</title>
 452         HeaderName /include/HEADER.html
 453       </example>
 454
 455       <p><var>Filename</var> must resolve to a document with a major
 456       content type of <code>text/*</code> (<em>e.g.</em>,
 457       <code>text/html</code>, <code>text/plain</code>, etc.). This means
 458       that <var>filename</var> may refer to a CGI script if the script's
 459       actual file type (as opposed to its output) is marked as
 460       <code>text/html</code> such as with a directive like:</p>
 461
 462       <example>
 463         AddType text/html .cgi
 464       </example>
 465
 466       <p><a href="../content-negotiation.html">Content negotiation</a>
 467       will be performed if <directive module="core">Options</directive>
 468       <code>MultiViews</code> is in effect. If <var>filename</var> resolves
 469       to a static <code>text/html</code> document (not a CGI script) and
 470       either one of the <directive module="core">options</directive>
 471       <code>Includes</code> or <code>IncludesNOEXEC</code> is enabled,
 472       the file will be processed for server-side includes (see the
 473       <module>mod_include</module> documentation).</p>
 474     </note>
 475
 476     <p>If the file specified by <directive>HeaderName</directive> contains
 477     the beginnings of an HTML document (&lt;html&gt;, &lt;head&gt;, etc.)
 478     then you will probably want to set <a
 479     href="#indexoptions.suppresshtmlpreamble"><code>IndexOptions
 480     +SuppressHTMLPreamble</code></a>, so that these tags are not
 481     repeated.</p>
 482 </usage>
 483 </directivesynopsis>
 484
 485 <directivesynopsis>
 486 <name>IndexIgnore</name>
 487 <description>Adds to the list of files to hide when listing
 488 a directory</description>
 489 <syntax>IndexIgnore <var>file</var> [<var>file</var>] ...</syntax>
 490 <contextlist><context>server config</context><context>virtual host</context>
 491 <context>directory</context><context>.htaccess</context>
 492 </contextlist>
 493 <override>Indexes</override>
 494
 495 <usage>
 496     <p>The <directive>IndexIgnore</directive> directive adds to the
 497     list of files to hide when listing a directory. <var>File</var> is a
 498     shell-style wildcard expression or full
 499     filename. Multiple IndexIgnore directives add
 500     to the list, rather than the replacing the list of ignored
 501     files. By default, the list contains <code>.</code> (the current
 502     directory).</p>
 503
 504     <example>
 505       IndexIgnore README .htaccess *.bak *~
 506     </example>
 507 </usage>
 508 </directivesynopsis>
 509
 510 <directivesynopsis>
 511 <name>IndexOptions</name>
 512 <description>Various configuration settings for directory
 513 indexing</description>
 514 <syntax>IndexOptions  [+|-]<var>option</var> [[+|-]<var>option</var>]
 515 ...</syntax>
 516 <contextlist><context>server config</context><context>virtual host</context>
 517 <context>directory</context><context>.htaccess</context>
 518 </contextlist>
 519 <override>Indexes</override>
 520
 521 <usage>
 522     <p>The <directive>IndexOptions</directive> directive specifies the
 523     behavior of the directory indexing. <var>Option</var> can be one
 524     of</p>
 525
 526     <dl>
 527       <dt><a name="indexoptions.descriptionwidth"
 528                id="indexoptions.descriptionwidth"
 529       >DescriptionWidth=[<var>n</var> | *]</a> (<em>Apache 2.0.23 and
 530       later</em>)</dt>
 531
 532       <dd>The <code>DescriptionWidth</code> keyword allows you to
 533       specify the width of the description column in
 534       characters.</dd>
 535
 536       <dd><code>-DescriptionWidth</code> (or unset) allows
 537       <module>mod_autoindex</module> to calculate the best width.</dd>
 538
 539       <dd><code>DescriptionWidth=<var>n</var></code> fixes the column width to
 540       <var>n</var> bytes wide.</dd>
 541
 542       <dd><code>DescriptionWidth=*</code> grows the column to the
 543       width necessary to accommodate the longest description
 544       string.</dd>
 545
 546       <dd><strong>See the section on <directive
 547       module="mod_autoindex">AddDescription</directive> for dangers
 548       inherent in truncating descriptions.</strong></dd>
 549
 550       <dt><a name="indexoptions.fancyindexing"
 551                id="indexoptions.fancyindexing">FancyIndexing</a></dt>
 552
 553       <dd>This turns on fancy indexing of directories.</dd>
 554
 555       <dt><a name="indexoptions.foldersfirst"
 556                id="indexoptions.foldersfirst">FoldersFirst</a> (<em>Apache
 557       2.0.23 and later</em>)</dt>
 558
 559       <dd>If this option is enabled, subdirectory listings will
 560       <em>always</em> appear first, followed by normal files in the
 561       directory. The listing is basically broken into two
 562       components, the files and the subdirectories, and each is
 563       sorted separately and then displayed subdirectories-first.
 564       For instance, if the sort order is descending by name, and
 565       <code>FoldersFirst</code> is enabled, subdirectory
 566       <code>Zed</code> will be listed before subdirectory
 567       <code>Beta</code>, which will be listed before normal files
 568       <code>Gamma</code> and <code>Alpha</code>. <strong>This option
 569       only has an effect if <a href="#indexoptions.fancyindexing"
 570       ><code>FancyIndexing</code></a> is also enabled.</strong></dd>
 571
 572       <dt><a name="indexoptions.htmltable"
 573                id="indexoptions.htmltable">HTMLTable</a> (<em>Experimental,
 574       Apache 2.0.23 and later</em>)</dt>
 575
 576       <dd>This experimental option with FancyIndexing constructs a
 577       simple table for the fancy directory listing. Note this will
 578       confuse older browsers. It is particularly necessary if file
 579       names or description text will alternate between
 580       left-to-right and right-to-left reading order, as can happen
 581       on WinNT or other utf-8 enabled platforms.</dd>
 582
 583       <dt><a name="indexoptions.iconsarelinks"
 584                id="indexoptions.iconsarelinks">IconsAreLinks</a></dt>
 585
 586       <dd>This makes the icons part of the anchor for the filename, for
 587       fancy indexing.</dd>
 588
 589       <dt><a name="indexoptions.iconheight"
 590                id="indexoptions.iconheight">IconHeight[=<var
 591                >pixels</var>]</a></dt>
 592
 593       <dd>Presence of this option, when used with IconWidth, will cause
 594       the server to include <code>height</code> and <code>width</code>
 595       attributes in the <code>img</code> tag for the file icon. This allows
 596       browser to precalculate the page layout without having to wait until
 597       all the images have been loaded. If no value is given for the option,
 598       it defaults to the standard height of the icons supplied with the Apache
 599       software.</dd>
 600
 601       <dt><a name="indexoptions.iconwidth"
 602                id="indexoptions.iconwidth">IconWidth[=<var
 603                >pixels</var>]</a></dt>
 604
 605       <dd>Presence of this option, when used with <code>IconHeight</code>,
 606       will cause the server to include <code>height</code> and
 607       <code>width</code> attributes in the <code>img</code> tag for
 608       the file icon. This allows browser to precalculate the page
 609       layout without having to wait until all the images have been
 610       loaded. If no value is given for the option, it defaults to
 611       the standard width of the icons supplied with the Apache
 612       software.</dd>
 613
 614       <dt><a name="indexoptions.ignorecase"
 615                id="indexoptions.ignorecase">IgnoreCase</a></dt>
 616
 617       <dd>If this option is enabled, names are sorted in a case-insensitive
 618       manner.  For instance, if the sort order is ascending by name, and
 619       IgnoreCase is enabled, file Zeta  will be listed after file alfa
 620       (Note: file GAMMA will always be listed before file gamma). </dd>
 621
 622       <dt><a name="indexoptions.ignoreclient"
 623                id="indexoptions.ignoreclient">IgnoreClient</a></dt>
 624
 625       <dd>This option causes <module>mod_autoindex</module> to ignore all
 626       query variables from the client, including sort order (implies
 627       <code><a href="#indexoptions.suppresscolumnsorting"
 628       >SuppressColumnSorting</a></code>.)</dd>
 629
 630       <dt><a name="indexoptions.namewidth"
 631                id="indexoptions.namewidth">NameWidth=[<var>n</var>
 632                | *]</a></dt>
 633
 634       <dd>The <code>NameWidth</code> keyword allows you to specify the width
 635       of the filename column in bytes.</dd>
 636
 637       <dd><code>-NameWidth</code> (or unset) allows <module
 638       >mod_autoindex</module> to calculate the best width.</dd>
 639
 640       <dd><code>NameWidth=<var>n</var></code> fixes the column width to
 641       <var>n</var> bytes wide.</dd>
 642
 643       <dd><code>NameWidth=*</code> grows the column to the necessary
 644       width.</dd>
 645
 646       <dt><a name="indexoptions.scanhtmltitles"
 647                id="indexoptions.scanhtmltitles">ScanHTMLTitles</a></dt>
 648
 649       <dd>This enables the extraction of the title from HTML documents
 650       for fancy indexing. If the file does not have a description
 651       given by <directive module="mod_autoindex">AddDescription</directive>
 652       then httpd will read the document for the value of the
 653       <code>title</code> element. This is CPU and disk intensive.</dd>
 654
 655       <dt><a name="indexoptions.showforbidden"
 656                id="indexoptions.showforbidden">ShowForbidden</a></dt>
 657
 658       <dd>If specified, Apache will show files normally hidden because
 659       the subrequest returned HTTP_UNAUTHORIZED or HTTP_FORBIDDEN</dd>
 660
 661       <dt><a name="indexoptions.suppresscolumnsorting"
 662                id="indexoptions.suppresscolumnsorting"
 663                >SuppressColumnSorting</a></dt>
 664
 665       <dd>If specified, Apache will not make the column headings in a
 666       FancyIndexed directory listing into links for sorting. The
 667       default behavior is for them to be links; selecting the
 668       column heading will sort the directory listing by the values
 669       in that column. <strong>Prior to Apache 2.0.23, this also
 670       disabled parsing the Query Arguments for the sort
 671       string.</strong> That behavior is now controlled by <a
 672       href="#indexoptions.ignoreclient">IndexOptions
 673       IgnoreClient</a> in Apache 2.0.23.</dd>
 674
 675       <dt><a name="indexoptions.suppressdescription"
 676                id="indexoptions.suppressdescription"
 677                >SuppressDescription</a></dt>
 678
 679       <dd>This will suppress the file description in fancy indexing
 680       listings. By default, no file descriptions are defined, and
 681       so the use of this option will regain 23 characters of screen
 682       space to use for something else. See <directive module="mod_autoindex"
 683       >AddDescription</directive> for information about setting the file
 684       description. See also the <code><a
 685       href="#indexoptions.descriptionwidth">DescriptionWidth</a></code>
 686       index option to limit the size of the description column.</dd>
 687
 688       <dt><a name="indexoptions.suppresshtmlpreamble"
 689                id="indexoptions.suppresshtmlpreamble"
 690                >SuppressHTMLPreamble</a></dt>
 691
 692       <dd>If the directory actually contains a file specified by the
 693       <directive module="mod_autoindex">HeaderName</directive>
 694       directive, the module usually includes the contents of the file
 695       after a standard HTML preamble (<code>&lt;html&gt;</code>,
 696       <code>&lt;head&gt;</code>, <em>et cetera</em>). The
 697       <code>SuppressHTMLPreamble</code> option disables this behaviour,
 698       causing the module to start the display with the header file
 699       contents. The header file must contain appropriate HTML instructions
 700       in this case. If there is no header file, the preamble is generated
 701       as usual.</dd>
 702
 703       <dt><a name="indexoptions.suppressicon"
 704                id="indexoptions.suppressicon">SuppressIcon</a> (<em>Apache
 705       2.0.23 and later</em>)</dt>
 706
 707       <dd>This will suppress the icon in fancy indexing listings.
 708       Combining both <code>SuppressIcon</code> and
 709       <code>SuppressRules</code> yields proper HTML 3.2 output, which
 710       by the final specification prohibits <code>img</code> and
 711       <code>hr</code> elements from the <code>pre</code> block (used to
 712       format FancyIndexed listings.)</dd>
 713
 714       <dt><a name="indexoptions.suppresslastmodified"
 715                id="indexoptions.suppresslastmodified"
 716                >SuppressLastModified</a></dt>
 717
 718       <dd>This will suppress the display of the last modification date,
 719       in fancy indexing listings.</dd>
 720
 721       <dt><a name="indexoptions.suppressrules"
 722                id="indexoptions.suppressrules">SuppressRules</a>
 723       (<em>Apache 2.0.23 and later</em>)</dt>
 724
 725       <dd>This will suppress the horizontal rule lines (<code>hr</code>
 726       elements) in directory listings. Combining both <code>SuppressIcon</code> and
 727       <code>SuppressRules</code> yields proper HTML 3.2 output, which
 728       by the final specification prohibits <code>img</code> and
 729       <code>hr</code> elements from the <code>pre</code> block (used to
 730       format FancyIndexed listings.)</dd>
 731
 732       <dt><a name="indexoptions.suppresssize"
 733                id="indexoptions.suppresssize">SuppressSize</a></dt>
 734
 735       <dd>This will suppress the file size in fancy indexing listings.</dd>
 736
 737       <dt><a name="indexoptions.trackmodified"
 738                id="indexoptions.trackmodified">TrackModified</a> (<em>Apache
 739       2.0.23 and later</em>)</dt>
 740
 741       <dd>This returns the Last-Modified and ETag values for the listed
 742       directory in the HTTP header. It is only valid if the
 743       operating system and file system return appropriate stat()
 744       results. Some Unix systems do so, as do OS2's JFS and Win32's
 745       NTFS volumes. OS2 and Win32 FAT volumes, for example, do not.
 746       Once this feature is enabled, the client or proxy can track
 747       changes to the list of files when they perform a <code>HEAD</code>
 748       request. Note some operating systems correctly track new and
 749       removed files, but do not track changes for sizes or dates of
 750       the files within the directory. <strong>Changes to the size
 751       or date stamp of an existing file will not update the
 752       Last-Modified header on all Unix platforms.</strong> If this
 753       is a concern, leave this option disabled.</dd>
 754
 755       <dt><a name="indexoptions.versionsort"
 756                id="indexoptions.versionsort">VersionSort</a>
 757       (<em>Apache 2.0a3 and later</em>)</dt>
 758
 759       <dd>The <code>VersionSort</code> keyword causes files containing
 760       version numbers to sort in a natural way. Strings are sorted as
 761       usual, except that substrings of digits in the name and
 762       description are compared according to their numeric value.
 763
 764       <example><title>Example:</title>
 765         foo-1.7<br />
 766         foo-1.7.2<br />
 767         foo-1.7.12<br />
 768         foo-1.8.2<br />
 769         foo-1.8.2a<br />
 770         foo-1.12
 771       </example>
 772
 773       <p>If the number starts with a zero, then it is considered to
 774       be a fraction:</p>
 775
 776       <example>
 777         foo-1.001<br />
 778         foo-1.002<br />
 779         foo-1.030<br />
 780         foo-1.04
 781       </example>
 782       </dd>
 783
 784       <dt><a name="indexoptions.xhtml"
 785                id="indexoptions.xhtml">XHTML</a>
 786       (<em>Apache 2.0.49 and later</em>)</dt>
 787
 788       <dd>The <code>XHTML</code> keyword forces <module>mod_autoindex</module>
 789       to emit XHTML 1.0 code instead of HTML 3.2.</dd>
 790     </dl>
 791
 792    <!--
 793      XXX: we should consider to allow sections inside <usage>
 794      this would require some xslt changes...
 795    -->
 796    <dl><dt>Incremental IndexOptions</dt>
 797    <dd>
 798      <p>Apache 1.3.3 introduced some significant changes in the
 799      handling of <directive>IndexOptions</directive> directives. In
 800      particular:</p>
 801
 802      <ul>
 803      <li>Multiple <directive>IndexOptions</directive> directives for a
 804      single directory are now merged together. The result of:
 805
 806      <example>
 807        &lt;Directory /foo&gt;
 808        <indent>
 809          IndexOptions HTMLTable<br />
 810          IndexOptions SuppressColumnsorting
 811        </indent>
 812        &lt;/Directory&gt;
 813      </example>
 814
 815      <p>will be the equivalent of</p>
 816
 817      <example>
 818        IndexOptions HTMLTable SuppressColumnsorting
 819      </example>
 820      </li>
 821
 822      <li>The addition of the incremental syntax (<em>i.e.</em>, prefixing
 823      keywords with <code>+</code> or <code>-</code>).</li>
 824      </ul>
 825
 826      <p>Whenever a '+' or '-' prefixed keyword is encountered, it
 827      is applied to the current <directive>IndexOptions</directive>
 828      settings (which may have been inherited from an upper-level
 829      directory). However, whenever an unprefixed keyword is processed, it
 830      clears all inherited options and any incremental settings encountered
 831      so far. Consider the following example:</p>
 832
 833      <example>
 834        IndexOptions +ScanHTMLTitles -IconsAreLinks FancyIndexing<br />
 835        IndexOptions +SuppressSize
 836      </example>
 837
 838      <p>The net effect is equivalent to <code>IndexOptions FancyIndexing
 839      +SuppressSize</code>, because the unprefixed <code>FancyIndexing</code>
 840      discarded the incremental keywords before it, but allowed them to
 841      start accumulating again afterward.</p>
 842
 843      <p>To unconditionally set the <directive>IndexOptions</directive> for
 844      a particular directory, clearing the inherited settings, specify
 845      keywords without any <code>+</code> or <code>-</code> prefixes.</p>
 846    </dd>
 847    </dl>
 848 </usage>
 849 </directivesynopsis>
 850
 851 <directivesynopsis>
 852 <name>IndexOrderDefault</name>
 853 <description>Sets the default ordering of the directory index</description>
 854 <syntax>IndexOrderDefault Ascending|Descending
 855 Name|Date|Size|Description</syntax>
 856 <default>IndexOrderDefault Ascending Name</default>
 857 <contextlist><context>server config</context><context>virtual host</context>
 858 <context>directory</context><context>.htaccess</context>
 859 </contextlist>
 860 <override>Indexes</override>
 861
 862 <usage>
 863     <p>The <directive>IndexOrderDefault</directive> directive is used
 864     in combination with the <code><a href="#indexoptions.fancyindexing"
 865     >FancyIndexing</a></code> index option. By default, fancyindexed
 866     directory listings are displayed in ascending order by filename; the
 867     <directive>IndexOrderDefault</directive> allows you to change this
 868     initial display order.</p>
 869
 870     <p><directive>IndexOrderDefault</directive> takes two
 871     arguments. The first must be either <code>Ascending</code> or
 872     <code>Descending</code>, indicating the direction of the sort.
 873     The second argument must be one of the keywords <code>Name</code>,
 874     <code>Date</code>, <code>Size</code>, or <code>Description</code>,
 875     and identifies the primary key. The secondary key is
 876     <em>always</em> the ascending filename.</p>
 877
 878     <p>You can force a directory listing to only be displayed in a
 879     particular order by combining this directive with the <code><a
 880     href="#indexoptions.suppresscolumnsorting"
 881     >SuppressColumnSorting</a></code> index option; this will prevent
 882     the client from requesting the directory listing in a different
 883     order.</p>
 884 </usage>
 885 </directivesynopsis>
 886
 887 <directivesynopsis>
 888 <name>IndexStyleSheet</name>
 889 <description>Adds a CSS stylesheet to the directory index</description>
 890 <syntax>IndexStyleSheet <var>url-path</var></syntax>
 891 <contextlist><context>server config</context><context>virtual host</context>
 892 <context>directory</context><context>.htaccess</context>
 893 </contextlist>
 894 <override>Indexes</override>
 895
 896 <usage>
 897     <p>The <directive>IndexStyleSheet</directive> directive sets the name of
 898     the file that will be used as the CSS for the index listing.
 899     </p>
 900     <example>
 901       <title>Example</title>
 902       IndexStyleSheet "/css/style.css"
 903     </example>
 904 </usage>
 905 </directivesynopsis>
 906
 907 <directivesynopsis>
 908 <name>ReadmeName</name>
 909 <description>Name of the file that will be inserted at the end
 910 of the index listing</description>
 911 <syntax>ReadmeName <var>filename</var></syntax>
 912 <contextlist><context>server config</context><context>virtual host</context>
 913 <context>directory</context><context>.htaccess</context>
 914 </contextlist>
 915 <override>Indexes</override>
 916
 917 <usage>
 918     <p>The <directive>ReadmeName</directive> directive sets the name
 919     of the file that will be appended to the end of the index
 920     listing. <var>Filename</var> is the name of the file to include, and
 921     is taken to be relative to the location being indexed. If
 922     <var>Filename</var> begins with a slash, it will be taken to be
 923     relative to the <directive module="core">DocumentRoot</directive>.
 924     </p>
 925
 926     <example><title>Example</title>
 927       ReadmeName FOOTER.html
 928     </example>
 929
 930     <example><title>Example 2</title>
 931       ReadmeName /include/FOOTER.html
 932     </example>
 933
 934     <p>See also <directive module="mod_autoindex"
 935     >HeaderName</directive>, where this behavior is described in greater
 936     detail.</p>
 937 </usage>
 938 </directivesynopsis>
 939
 940 </modulesynopsis>