[slime-cvs] CVS update: slime/doc/slime.texi

[Luke Gorrie]

Update of /project/slime/cvsroot/slime/doc
In directory common-lisp.net:/tmp/cvs-serv25874/doc

Modified Files:
	slime.texi 
Log Message:
(Semantic indentation): Documented new
automatically-learn-how-to-indent-macros feature.  Added auto version
control header in subtitle.

Date: Mon Apr  5 02:19:24 2004
Author: lgorrie

Index: slime/doc/slime.texi
diff -u slime/doc/slime.texi:1.5 slime/doc/slime.texi:1.6
--- slime/doc/slime.texi:1.5	Sun Mar 28 19:57:17 2004
+++ slime/doc/slime.texi	Mon Apr  5 02:19:23 2004
@@ -1,7 +1,7 @@
 \input texinfo   @c -*-texinfo-*-
 @c %**start of header
 @setfilename slime.info
- at settitle SLIME User Manual
+ at settitle The Superior Lisp Interaction Mode for Emacs
 @c %**end of header
 
 @macro SLIME
@@ -37,13 +37,13 @@
 @code{\command\}@*
 @end macro
 
- at set EDITION Draft
- at set UPDATED March 2004
+ at set EDITION DRAFT
+ at set UPDATED @code{$Id: slime.texi,v 1.6 2004/04/05 06:19:23 lgorrie Exp $}
 
 @titlepage
 @title SLIME User Manual
 @subtitle The Superior Lisp Interaction Mode for Emacs
- at subtitle @value{EDITION}, updated @value{UPDATED}
+ at subtitle @value{EDITION}, @value{UPDATED}
 @author
 @end titlepage
 
@@ -129,6 +129,7 @@
 
 * User-interface conventions::  
 * Commands::                    
+* Semantic indentation::        
 
 User-interface conventions
 
@@ -283,7 +284,8 @@
 @node Installation, Running, Downloading, Getting started
 @section Installation
 
-Installation just requires a few lines in your @file{~/.emacs}:
+On Unix-like systems, installation just requires a few lines in your
+ at file{~/.emacs}:
 
 @example
 (setq inferior-lisp-program "@emph{the path to your Lisp system}")
@@ -320,6 +322,7 @@
 @menu
 * User-interface conventions::  
 * Commands::                    
+* Semantic indentation::        
 @end menu
 
 @node User-interface conventions, Commands, slime-mode, slime-mode
@@ -386,7 +389,7 @@
 doesn't belong to @SLIME{}, and you should probably lookup our
 equivalent.
 
- at node Commands,  , User-interface conventions, slime-mode
+ at node Commands, Semantic indentation, User-interface conventions, slime-mode
 @section Commands
 
 @menu
@@ -655,6 +658,51 @@
 @item M-x slime-profile-reset
 Reset profiler data.
 @end table
+
+ at node Semantic indentation,  , Commands, slime-mode
+ at section Semantic indentation
+
+ at SLIME{} automatically discovers how to indent the macros in your Lisp
+system. To do this the Lisp side scans all the macros in the system and
+reports to Emacs all the ones with @code{&body} arguments. Emacs then
+indents these specially, putting the first arguments four spaces in and
+the ``body'' arguments just two spaces, as usual.
+
+This should ``just work.'' If you are a lucky sort of person you needn't
+read the rest of this section.
+
+To simplify the implementation, @SLIME{} doesn't distinguish between
+macros with the same symbol-name but different packages. This makes it
+fit nicely with Emacs's indentation code. However, if you do have
+several macros with the same symbol-name then they will all be indented
+the same way, arbitrarily using the style from one of their
+arglists. You can find out which symbols are involved in collisions
+with:
+
+ at example
+(swank:print-indentation-lossage)
+ at end example
+
+If a collision causes you irritation, don't have a nervous breakdown,
+just override the Elisp symbol's @code{common-lisp-indent-function}
+property to your taste. @SLIME{} won't override your custom settings, it
+just tries to give you good defaults.
+
+A more subtle issue is that imperfect caching is used for the sake of
+performance. @footnote{@emph{Of course} we made sure it was actually too
+slow before making the ugly optimization.}
+ at c
+In an ideal world, Lisp would automatically scan every symbol for
+indentation changes after each command from Emacs. However, this is too
+expensive to do every time. Instead Lisp usually just scans the symbols
+whose home package matches the one used by the Emacs buffer where the
+request comes from. That is sufficient to pick up the indentation of
+most interactively-defined macros. To catch the rest we make a full scan
+of every symbol each time a new Lisp package is created between commands
+-- that takes care of things like new systems being loaded.
+
+You can use @kbd{M-x slime-update-indentation} to force all symbols to
+be scanned for indentation information.
 
 @node REPL, Debugger, slime-mode, Top
 @chapter @REPL{}: the ``top level''