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