[documentation] [task] Clean URLs - example of how to rewrite a handbook page to include information in comments.

[Amazon]

Issue status update for 
http://drupal.org/node/43780
Post a follow up: 
http://drupal.org/project/comments/add/43780

 Project:      Documentation
 Version:      <none>
 Component:    Installation
 Category:     tasks
 Priority:     critical
 Assigned to:  Anonymous
 Reported by:  Amazon
 Updated by:   Amazon
 Status:       active

Here is an example of how to submit a re-write of a handbook page that
has many comments.  Rewrite the page and then file as an issue for the
documentation team to update.  In this case I have already updated the
page: http://drupal.org/node/15365


By default, Drupal passes path arguments to itself via its internally
generated URLs.  This results in URLs that look like the following:
"http://www.example.com/?q=node/83."  This can make URLs hard to read
and it also stops many search engines, like Google, from indexing the
pages with these URLs.


You can tell Drupal to use "clean URLs", eliminating the "?q=" in
internal URLs.  Note that this works only for Apache servers which have
the LoadModule rewrite_module configured and mod_rewrite enabled in
httpd.conf configuration file.


There are two ways to enable URL rewrites in Apache.  If there is
complete control of the Apache webserver clean URLs should be enabled
in the httpd.conf as this has better performance and security [1].


*Warning. *Enabling "Clean URLs" if your server is not properly
configured can make it difficult to navigate back to administration
pages to undo your mistake.  If you find yourself in this situation,
you can return to the administrative settings page by typing in the URL
in the 'non-clean' form: http://www.example.com/?q=admin/settings.


Enabling clean URLs involves three steps:



* Enable mod_rewrite for Apache.  Please talk to your web host or
consult the Apache documentation [2]  for mod_rewrite to get more
information on how to do this.  At a minimum, this will involve making
sure that mod_rewrite is enabled for your installation of Apache.  It
will have to be either compiled-in or made available as a loadable
module.  Generally speaking, you can tell Apache to load the module by
including
 LoadModule rewrite_module modules/mod_rewrite.so


in your Apache configuration file.  Note that this may not be the case
for all distributions of *nix operating systems.  Consult your
distribution's documentation that came packaged with your Apache
software.  We also recommend disabling multiviews in Apache as they
conflict with clean URLs.

* Edit your Apache configuration files for your site:  the
configuration information may be found in httpd.conf, a
virtual-host-specific file, or in an .htaccess file in your Drupal
installation directory.  The main configuration option which may need
to be changed for your site is the RewriteBase.  For example, if your
Apache DocumentRoot is /var/www/ (i.e., /var/www/index.html is what is
displayed when you point your browser at http://www.example.com/) and
your Drupal installation is installed in the subdirectory
/var/www/mysite/, then the RewriteBase should be set to /mysite. In
some configurations setting RewriteBase / will allow mod rewrite to
work.  You will also need to set the Allow Override settings so that
local .htaccess commands will be run for you site.  If you are changing
the .htaccess file in the Drupal distribution want to set it to Allow
Override All to ensure rewrites are enabled.

* You must ensure your Drupal site has the path module enabled and the
correct permissions set.  You can enable the path module in *administer
>> modules*.  You can then set permissions to administer URL aliases and
*create URL aliases*. Enable clean URLs on your *administration >>
settings* page.  First, see if you can go to the settings page on your
site using clean URLs: type in the URL
http://www.example.com/admin/settings (where www.example.com is
replaced by your hostname). If you get no errors and get to the same
page you would have gotten to by clicking on "administer" then
"settings" , then you know that you have setup the ReWriteRule rules
successfully and can then click the Yes checkbox for "Clean URLs:" . 
If you have problem you can read the instructions to unset clean URLs
[3]. If you If you still have problems with clean URLs you can set the
Drupal Settings.php $conf['clean_url']=1;.

*Note:* The standard Drupal installation contains a sample .htaccess
file which supports clean URLs.  It is easy to miss copying this file,
because of the leading "dot".


*Note Regarding MultiViews:* The Apache webserver supports a feature
called "MultiViews" (more generally: "Content Negotiation"), which
allows navigation to your pages without the need for file extensions.
For instance, if you had a file called "evaluation.txt", a
MultiViews-enabled site could access this file with the URL
"example.com/evaluation". While MultiViews can be a handy feature when
used knowingly, they can cause problems when Drupal's Clean URLs are
enabled. Unless you know what you're doing, you should consider
disabling MultiViews if you plan to use the clean URLs feature of
Drupal. Be aware that there's a good chance that MultiViews is
/already/ disabled, however; it's not enabled in a default Apache
installation. Consult the Apache documentation for further information
about MultiViews [4].
[1] http://www.serverwatch.com/tutorials/article.php/3436911
[2] http://httpd.apache.org/docs/1.3/mod/mod_rewrite.html
[3] http://drupal.org/node/5590
[4] http://httpd.apache.org/docs/mod/core.html#options




Amazon