docs/manual/mod/mod_speling.xml

<?xml version="1.0"?>
<!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd">
<?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
<!-- $LastChangedRevision$ -->

<!--
 Licensed to the Apache Software Foundation (ASF) under one or more
 contributor license agreements.  See the NOTICE file distributed with
 this work for additional information regarding copyright ownership.
 The ASF licenses this file to You under the Apache License, Version 2.0
 (the "License"); you may not use this file except in compliance with
 the License.  You may obtain a copy of the License at

     http://www.apache.org/licenses/LICENSE-2.0

 Unless required by applicable law or agreed to in writing, software
 distributed under the License is distributed on an "AS IS" BASIS,
 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 See the License for the specific language governing permissions and
 limitations under the License.
-->

<modulesynopsis metafile="mod_speling.xml.meta">

<name>mod_speling</name>
<description>Attempts to correct mistaken URLs by ignoring
capitalization, or attempting to correct various minor
misspellings.</description>
<status>Extension</status>
<sourcefile>mod_speling.c</sourcefile>
<identifier>speling_module</identifier>



<summary>

    <p>Requests to documents sometimes cannot be served by the core
    apache server because the request was misspelled or
    miscapitalized. This module addresses this problem by trying to
    find a matching document, even after all other modules gave up.
    It does its work by comparing each document name in the
    requested directory against the requested document name
    <strong>without regard to case</strong>, and allowing
    <strong>up to one misspelling</strong> (character insertion /
    omission / transposition or wrong character). A list is built
    with all document names which were matched using this
    strategy. <strong>Erroneous extension</strong> can also be fixed
    by this module.</p>

    <p>If, after scanning the directory,</p>

    <ul>
      <li>no matching document was found, Apache will proceed as
      usual and return an error (<code>404 - document not found</code>).</li>

      <li>only one document is found that "almost" matches the
      request, then it is returned in the form of a redirection
      response (<code>301 - Moved Permanently</code>).</li>

      <li>more than one document with a close match was found, then
      the list of the matches is returned to the client, and the
      client can select the correct candidate (<code>300 - Multiple
      Choices</code>).</li>
    </ul>

</summary>


<directivesynopsis>
<name>CheckSpelling</name>
<description>Enables the spelling
module</description>
<syntax>CheckSpelling on|off</syntax>
<default>CheckSpelling Off</default>
<contextlist>
<context>server config</context>
<context>virtual host</context>
<context>directory</context>
<context>.htaccess</context>
</contextlist>
<override>Options</override>

<usage>
    <p>This directive enables or disables the spelling module. When
    enabled, keep in mind that</p>

    <ul>
      <li>the directory scan which is necessary for the spelling
      correction will have an impact on the server's performance
      when many spelling corrections have to be performed at the
      same time.</li>

      <li>the document trees should not contain sensitive files
      which could be matched inadvertently by a spelling
      "correction".</li>

      <li>the module is unable to correct misspelled user names (as
      in <code>http://my.host/~apahce/</code>), just file names or
      directory names.</li>

      <li>spelling corrections apply strictly to existing files, so
      a request for the <code>&lt;Location /status&gt;</code> may
      get incorrectly treated as the negotiated file
      "<code>/stats.html</code>".</li>
    </ul>

    <!-- XXX: is that really true?! -nd -->
    <p><module>mod_speling</module> should not be enabled in <a href="mod_dav.html">DAV</a>
    enabled directories, because it will try to "spell fix" newly created
    resource names against existing filenames, e.g., when trying to upload
    a new document <code>doc43.html</code> it might redirect to an existing
    document <code>doc34.html</code>, which is not what was intended.
    </p>
</usage>
</directivesynopsis>

<directivesynopsis>
<name>CheckCaseOnly</name>
<description>Limits the action of the speling module to case corrections</description>
<syntax>CheckCaseOnly on|off</syntax>
<default>CheckCaseOnly Off</default>
<contextlist>
<context>server config</context>
<context>virtual host</context>
<context>directory</context>
<context>.htaccess</context>
</contextlist>
<override>Options</override>

<usage>
    <p>When set, this directive limits the action of the spelling correction
    to lower/upper case changes.  Other potential corrections are not performed,
    except when <directive module="mod_speling">CheckBasenameMatch</directive> is also set.</p>
</usage>
</directivesynopsis>

<directivesynopsis>
<name>CheckBasenameMatch</name>
<description>Also match files with differing file name extensions.</description>
<syntax>CheckBasenameMatch on|off</syntax>
<default>CheckBasenameMatch On</default>
<contextlist>
<context>server config</context>
<context>virtual host</context>
<context>directory</context>
<context>.htaccess</context>
</contextlist>
<override>Options</override>
<compatibility>Available in httpd 2.5.0 and later</compatibility>

<usage>
    <p>When set, this directive extends the action of the spelling correction
    to the file name extension. For example a file <code>foo.gif</code> will
    match a request for <code>foo</code> or <code>foo.jpg</code>. This can be
    particularly useful in conjunction with
    <a href="../content-negotiation.html">MultiViews</a>.</p>
</usage>
</directivesynopsis>

</modulesynopsis>