Documentation was rewritten and extended.

Author: arnested

README

@@ -1,35 +1,153 @@
-Drupal Mode
-===========
+Drupal mode
 
-Drupal Mode is an advanced minor mode for developing in Drupal.
+Drupal mode is an advanced minor mode for developing in Drupal.
 
-Drupal Mode is based on top of PHP mode and defines among other things
-indentation etc. to match Drupal Coding Standards.
+The approach taken is somewhat different from other attempts at creating
+a Drupal mode.
 
-Mission statement
------------------
+This mode is a minor mode and can be applied to all files in a Drupal
+project no matter what major mode they use - whether it be php-mode or
+something else.
 
--   Don't over do it
-    -   Only provide what makes sense in standard Emacs fashion.
-    -   Leave out what is considered personal taste.
-    -   Provide optional stuff if in doubt.
-    -   ... or provide option to disable if the personal taste is
-        considered good practice.
-    -   The rest can go as advice on EmacsWiki or github wiki or g.d.o.
+Besides giving access to general functionality in all modes (i.e.
+clearing cache through Drush) it will also adapt it self to the major
+mode to enable functionality only for that particular major mode (i.e.
+adhering to Drupals PHP coding standards only in php-mode).
 
--   Development is based on Emacs 24 - but Emacs 23 will be supported
-    for all releases as well (although only a subset).
--   Do the right thing in all relevant major modes:
-    -   php-mode
-    -   javascript mode(s)
-    -   conf-mode (module.info)
+Drupal mode will try not to enforce specific ways of working with Emacs
+on to you. Emacs can be extended in a million different ways and you
+should use the parts and extensions that fit you and your working
+habits.
 
--   Provide the mode via ELPA.
+If Drupal mode recognizes you using an extension that it knows about it
+will adapt the extension to be useful in Drupal mode and with Drupal.
+I.e. it will recognize if you have loaded etags support and setup your
+buffers to use the TAGS file in your DRUPAL_ROOT folder.
 
-Other drupal modes
-------------------
+Drupal mode won't embed other libraries but will suggest some (see
+below) and depend on a few through the packaging system (i.e. php-mode).
 
-There are quite a few attempts at writing a drupal-mode out in the wild:
+Installation
+
+The easiest way to install Drupal mode is probably to install it via the
+ELPA archive at Marmalade.
+
+ELPA (package.el) is part of Emacs 24. For Emacs 23 see Marmalade for
+installation instructions.
+
+Features of Drupal mode
+
+Drupal Coding Standards
+
+Drupal mode will make you write code that adheres to Drupals coding
+standards.
+
+It does this by:
+
+Indentation
+
+In php-mode code will be indented according to Drupals coding standards.
+If not it is considered a bug!
+
+Fixing line endings
+
+If your files are not written with unix style line endings Drupal mode
+will ask your to convert them to unix style line endings on saving
+buffers.
+
+This behavior can be customized be the variable
+drupal-convert-line-ending.
+
+The default is to ask if you want the file to be converted. By asking
+you we hopefully won't trick you into making a commit in your version
+control system consisting of a bunch of functionality changes with every
+line also changed by a new line ending. If you have ever read 1000 of
+commits/diffs you will appreciate this.
+
+Delete trailing white space
+
+In Drupal mode buffers we will enable Emacs' delete-trailing-whitespace.
+
+This behavior can be customized be the variable
+drupal-delete-trailing-whitespace.
+
+Search documentation
+
+You can search Drupal documentation for the symbol at point by issuing
+C-c d f or M-x drupal-search-documentation or from the Drupal menu
+entry.
+
+Files that are part of a Drupal project will try to identify the used
+version of Drupal core and look up the documentation for the
+corresponding version at http://api.drupal.org.
+
+If the symbol at point is believed to be a drush command the
+documentation will be looked up at http://api.drush.org instead. If
+Drush is installed it will identify the version of Drush and look up the
+documentation for that version.
+
+You can change where to search for documentation be customizing
+drupal-search-url (besides api.drupal.org it also has a predefined
+setting for api.drupalcontrib.org) and drupal-drush-search-url.
+
+Clearing all caches
+
+If Drush is installed you can issue a drush cc all from within Emacs by
+issuing C-c d c or M-x drupal-drush-cache-clear or from the Drupal menu
+entry.
+
+Drush editing minor mode
+
+If the buffer you visit is believe to be a Drush command (we think it is
+its name or path contains "drush") we will also enter a Drush minor
+mode.
+
+There is currently no functionality connected to drupal-drush-mode.
+
+Emacs modes and extensions that Drupal mode will enhance
+
+etags
+
+If you have generated a TAGS file in your DRUPAL_ROOT folder Drupal mode
+will setup all buffers running drupal-mode to set tags-file-name to
+point to that TAGS file.
+
+Etags is a builtin part of Emacs.
+
+GNU Globals / gtags
+
+If you load GNU Globals / gtags support in Emacs then Drupal mode will
+set gtags-rootdir to your DRUPAL_ROOT.
+
+ispell
+
+If ispell.el is loaded in Emacs then Drupal mode will set the language
+of your Drupal mode buffers to american as stated in Drupals coding
+standards.
+
+ispell.el is a builtin part of Emacs. A external program must be
+installed to run the actual spell checking, i.e. ispell, aspell, or
+hunspell.
+
+flymake-phpcs
+
+If support for flymake-phpcs.el is loaded in emacs and you have
+installed Drupal Code Sniffer rules then Drupal mode will enable
+flymake-phpcs under php-mode.
+
+For this to work you need:
+
+-   PHP CodeSniffer
+-   flymake-phpcs.el
+-   Drupal Code Sniffer rules
+
+Making all of them work together can be a bit of a puzzle. Especially
+notice the need to run phpcs through a wrapper you get with
+flymake-phpcs.el.
+
+Other takes on a Drupal mode
+
+There are quite a few attempts at writing a Drupal mode out in the wild:
 
 -   Search Github for drupal-mode
 -   At drupal.org:
@@ -38,8 +156,7 @@ There are quite a few attempts at writing a drupal-mode out in the wild:
 
 All of them more or less based on Configuring Emacs.
 
-Installation
-------------
+Development of Drupal mode
 
-The easiest way to install Drupal Mode is probably to install it via the
-ELPA archive at Marmalade.
+Drupal mode is actively developed at GitHub. Feature requests, ideas,
+bug reports, and pull request are more that welcome!