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