Merge Matt’s documentation updates

Closes #25.

smart-tabs-mode.el

@@ -45,39 +45,54 @@
 
 ;;; Installation:
 
-;; To use, save smart-tabs-mode.el to a a directory on your load-path
+;; The easiest and preferred way to install smart-tabs-mode is to use
+;; the package available on MELPA.
+;;
+;; Manual installation:
+;;
+;; Save smart-tabs-mode.el to a a directory on your load-path
 ;; (e.g., ~/.emacs.d/elisp), then add the following to your .emacs file:
 ;;
 ;;  (autoload 'smart-tabs-mode "smart-tabs-mode"
 ;;    "Intelligently indent with tabs, align with spaces!")
 ;;  (autoload 'smart-tabs-mode-enable "smart-tabs-mode")
 ;;  (autoload 'smart-tabs-advice "smart-tabs-mode")
+;;  (autoload 'smart-tabs-insinuate "smart-tabs-mode")
+;;
+
+;;; Enabling smart-tabs-mode within language modes:
+
+;; As of version 1.0 of this package, the easiest and preferred way to
+;; enable smart-tabs-mode is with the smart-tabs-insinuate function;
+;; for example,
+;;
+;;  (smart-tabs-insinuate 'c 'c++ 'java 'javascript 'cperl 'python
+;;                        'ruby 'nxml)
+;;
+;; will enable smart-tabs-mode with all supported language modes.
 ;;
-;; Then, for each language you want to use smart tabs, set up a hook
-;; and advice like so:
+;; (See below for instructions on adding additional language support.)
+;;
+;; The old method of manually enabling smart-tabs-mode is still
+;; available, but is no longer recommended; smart-tabs-insinuate
+;; wraps the functionality below in a convenient manner.
+;;
+;; For reference, the basic manual method looks like this:
 ;;
 ;;  (add-hook 'MODE-HOOK 'smart-tabs-mode-enable)
 ;;  (smart-tabs-advice INDENT-FUNC TAB-WIDTH-VAR)
 ;;
 ;; Note that it might be preferable to delay calling smart-tabs-advice
-;; until after the major mode is loaded and evaluated:
-;;
-;; (eval-after-load 'MODE-FEATURE
-;;   '(smart-tabs-advice INDENT-FUNC TAB-WIDTH-VAR))
-;;
-;; Or:
+;; until after the major mode is loaded and evaluated, so the lines
+;; above would be better written like this:
 ;;
 ;;  (add-hook 'MODE-HOOK (lambda ()
 ;;                         (smart-tabs-mode-enable)
 ;;                         (smart-tabs-advice INDENT-FUNC TAB-WIDTH-VAR)))
 ;;
-;; Here are some specific examples for a few popular languages which
-;; can be enabled by 'smart-tab-insinuate':
+;; Here are some specific examples for a few popular languages:
 ;;
-;;  ;; Load all the following in one pass
-;;  (smart-tabs-insinuate 'c 'javascript 'cperl 'python 'ruby)
-;;
-;;  ;; C/C++
+;;  ;; C
 ;;  (add-hook 'c-mode-hook 'smart-tabs-mode-enable)
 ;;  (smart-tabs-advice c-indent-line c-basic-offset)
 ;;  (smart-tabs-advice c-indent-region c-basic-offset)
@@ -93,12 +108,8 @@
 ;;  ;; Python
 ;;  (add-hook 'python-mode-hook 'smart-tabs-mode-enable)
 ;;  (smart-tabs-advice python-indent-line-1 python-indent)
-;;
-;;  ;; Ruby
-;;  (add-hook 'ruby-mode-hook 'smart-tabs-mode-enable)
-;;  (smart-tabs-advice ruby-indent-line ruby-indent-level)
 
-;;; Adding Language Support
+;;; Adding language support
 
 ;; Language support can be added through the use of the macro
 ;; `smart-tabs-add-language-support'. Pass in the symbol you wish
@@ -114,7 +125,6 @@
 ;; NOTE: All language support must be added before the call to
 ;;      `smart-tabs-insinuate'.
 
-
 ;;; Code:
 
 (require 'advice)