Try to document some smie changes

* doc/lispref/modes.texi (SMIE Customization): New section.

* doc/lispref/elisp.texi (Top): Update detailed menu.

* etc/NEWS: Related edits.

4 files changed, 60 insertions, 1 deletions

diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog
index d50ba585c31..1a76554dd55 100644
--- a/doc/lispref/ChangeLog
+++ b/doc/lispref/ChangeLog
@@ -1,3 +1,8 @@
+2014-03-05  Glenn Morris  <rgm@gnu.org>
+
+        * modes.texi (SMIE Customization): New section.
+        * elisp.texi (Top): Update detailed menu.
+
 2014-03-04  Martin Rudalics  <rudalics@gmx.at>
 
         * windows.texi (Windows and Frames): Add some missing &optional
diff --git a/doc/lispref/elisp.texi b/doc/lispref/elisp.texi
index a0f447f94f4..8442c3dbcfe 100644
--- a/doc/lispref/elisp.texi
+++ b/doc/lispref/elisp.texi
@@ -903,6 +903,7 @@ Simple Minded Indentation Engine
 * SMIE Indentation::        Specifying indentation rules.
 * SMIE Indentation Helpers:: Helper functions for indentation rules.
 * SMIE Indentation Example:: Sample indentation rules.
+* SMIE Customization::      Customizing indentation.
 
 Documentation
 
diff --git a/doc/lispref/modes.texi b/doc/lispref/modes.texi
index e12d00a5b59..30b0f758c27 100644
--- a/doc/lispref/modes.texi
+++ b/doc/lispref/modes.texi
@@ -3383,6 +3383,7 @@ resorting to some special tricks (@pxref{SMIE Tricks}).
 * SMIE Indentation::            Specifying indentation rules.
 * SMIE Indentation Helpers::    Helper functions for indentation rules.
 * SMIE Indentation Example::    Sample indentation rules.
+* SMIE Customization::          Customizing indentation.
 @end menu
 
 @node SMIE setup
@@ -3961,6 +3962,52 @@ the previous @code{"else"}, rather than going all the way back to the
 first @code{"if"} of the sequence.
 @end itemize
 
+@c In some sense this belongs more in the Emacs manual.
+@node SMIE Customization
+@subsubsection Customizing Indentation
+
+If you are using a mode whose indentation is provided by SMIE, you can
+customize the indentation to suit your preferences.  You can do this
+on a per-mode basis (using the option @code{smie-config}), or a
+per-file basis (using the function @code{smie-config-local} in a
+file-local variable specification).
+
+@defopt smie-config
+This option lets you customize indentation on a per-mode basis.
+It is an alist with elements of the form @code{(@var{mode} . @var{rules})}.
+For the precise form of rules, see the variable's documentation; but
+you may find it easier to use the command @code{smie-config-guess}.
+@end defopt
+
+@deffn Command smie-config-guess
+This command tries to work out appropriate settings to produce
+your preferred style of indentation.  Simply call the command while
+visiting a file that is indented with your style.
+@end deffn
+
+@deffn Command smie-config-save
+Call this command after using @code{smie-config-guess}, to save your
+settings for future sessions.
+@end deffn
+
+@deffn Command smie-config-show-indent &optional move
+This command displays the rules that are used to indent the current
+line.
+@end deffn
+
+@deffn Command smie-config-set-indent
+This command adds a local rule to adjust the indentation of the current line.
+@end deffn
+
+@defun smie-config-local rules
+This function adds @var{rules} as indentation rules for the current buffer.
+These add to any mode-specific rules defined by the @code{smie-config} option.
+To specify custom indentation rules for a specific file, add an entry
+to the file's local variables of the form:
+@code{eval: (smie-config-local '(@var{rules}))}.
+@end defun
+
+
 @node Desktop Save Mode
 @section Desktop Save Mode
 @cindex desktop save mode
diff --git a/etc/NEWS b/etc/NEWS
index 24b3f16556a..52fc2769cf7 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -904,11 +904,17 @@ All non-ancient Bash versions support this option.
 
 ** SMIE
 
-*** You can customize the indentation of modes that use SMIE via `smie-config'.
++++
+*** You can customize the SMIE indentation of a mode via `smie-config'.
 The command `smie-config-guess' can help you derive the appropriate
 indentation settings, if you provide it with an indented sample file.
 Use `smie-config-save' to save the result.
 
++++
+*** You can customize the SMIE indentation of a file by adding an entry to
+the file's local variables of the form: `eval: (smie-config-local '(RULES)'.
+
++++
 *** New commands `smie-config-show-indent' and `smie-config-set-indent'.
 
 ---