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

[Luke Gorrie]

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

Modified Files:
	slime.texi 
Log Message:
Added a section about user-interface conventions and our relationship
with inf-lisp.

Date: Sun Mar 28 19:57:17 2004
Author: lgorrie

Index: slime/doc/slime.texi
diff -u slime/doc/slime.texi:1.4 slime/doc/slime.texi:1.5
--- slime/doc/slime.texi:1.4	Fri Mar 26 09:39:55 2004
+++ slime/doc/slime.texi	Sun Mar 28 19:57:17 2004
@@ -28,7 +28,7 @@
 @end tex
 @end iftex
 @ifnottex
-o
+o at c this comment prevents a newline!
 @end ifnottex
 @end macro
 
@@ -75,7 +75,7 @@
 Lisp. The two sides are connected together with a socket and
 communicate using an @acronym{RPC}-like protocol.
 
-The Lisp server is primarily written in portal Common Lisp. The
+The Lisp server is primarily written in portable Common Lisp. The
 required implementation-specific functionality is specified by a
 well-defined interface and implemented separately for each Lisp
 implementation. This makes @SLIME{} readily portable.
@@ -127,6 +127,16 @@
 
 @code{slime-mode}
 
+* User-interface conventions::  
+* Commands::                    
+
+User-interface conventions
+
+* Temporary buffers::           
+* inferior-lisp::               
+
+Commands
+
 * Compilation::                 
 * Finding definitions::         
 * Lisp Evaluation::             
@@ -206,7 +216,7 @@
 @item
 LispWorks
 @item
-Allegro Common Lisp
+Allegro Common Lisp (@acronym{ACL})
 @end itemize
 
 Most features work uniformly across implementations, but some are
@@ -308,6 +318,78 @@
 describes the @code{slime-mode} and its relatives.
 
 @menu
+* User-interface conventions::  
+* Commands::                    
+ at end menu
+
+ at node User-interface conventions, Commands, slime-mode, slime-mode
+ at section User-interface conventions
+
+To use @SLIME{} comfortably it is important to understand a few
+``global'' user-interface characteristics. The most important
+principles are described in this section.
+
+ at menu
+* Temporary buffers::           
+* inferior-lisp::               
+ at end menu
+
+ at node Temporary buffers, inferior-lisp, User-interface conventions, User-interface conventions
+ at subsection Temporary buffers
+
+Some @SLIME{} commands create temporary buffers to display their
+results. Although these buffers usually have their own special-purpose
+major-modes, certain conventions are observed throughout.
+
+Temporary buffers can be dismissed by pressing @kbd{q}. This kills the
+buffer and restores the window configuration as it was before the
+buffer was displayed. Temporary buffers can also be killed with the
+usual commands like @code{kill-buffer}, in which case the previous
+window configuration won't be restored.
+
+Pressing @kbd{RET} is supposed to ``do the most obvious useful
+thing.'' For instance, in an apropos buffer this prints a full
+description of the symbol at point, and in an @acronym{XREF} buffer it
+displays the source code for the reference at point. This convention
+is inherited from Emacs's own buffers for apropos listings,
+compilation results, etc.
+
+Temporary buffers containing Lisp symbols use @code{slime-mode} in
+addition to any special mode of their own. This makes the usual
+ at SLIME{} commands available for describing symbols, looking up
+function definitions, and so on.
+
+ at node inferior-lisp,  , Temporary buffers, User-interface conventions
+ at subsection @code{*inferior-lisp*} buffer
+
+ at SLIME{} internally uses the @code{inferior-lisp} package to start
+Lisp processes. This has a few user-visible consequences, some good
+and some not-so-terribly. To avoid confusion it is useful to
+understand the interactions.
+
+The buffer @code{*inferior-lisp*} contains the Lisp process's own
+top-level. This direct access to Lisp is useful for troubleshooting,
+and some degree of @SLIME{} integration is available using the
+ at code{inferior-slime-mode}. However, in normal use we recommend using
+the fully-integrated @SLIME{} @REPL{} and ignoring the
+ at code{*inferior-lisp*} buffer.
+
+An unfortunate property of @code{inferior-lisp} is it inserts some
+commands of its own directly into the @code{lisp-mode} keymap, such
+that they aren't easily disabled. This makes Lisp source buffers
+slightly schizophrenic, having both @SLIME{} and @code{inferior-lisp}
+commands bound to keys and operating independently.
+
+ at SLIME{} overrides most key bindings, so in practice you are unlikely
+to accidentally use an @code{inferior-lisp} command. If you do find a
+command that pops up the @code{*inferior-lisp*} buffer, that command
+doesn't belong to @SLIME{}, and you should probably lookup our
+equivalent.
+
+ at node Commands,  , User-interface conventions, slime-mode
+ at section Commands
+
+ at menu
 * Compilation::                 
 * Finding definitions::         
 * Lisp Evaluation::             
@@ -319,8 +401,8 @@
 * Profiling::                   
 @end menu
 
- at node Compilation, Finding definitions, slime-mode, slime-mode
- at section Compilation commands
+ at node Compilation, Finding definitions, Commands, Commands
+ at subsection Compilation commands
 
 @SLIME{} has fancy commands for compiling functions, files, and
 packages. The fancy part is that notes and warnings offered by the
@@ -357,8 +439,8 @@
 
 @end table
 
- at node Finding definitions, Lisp Evaluation, Compilation, slime-mode
- at section Finding definitions (``Meta-Point'').
+ at node Finding definitions, Lisp Evaluation, Compilation, Commands
+ at subsection Finding definitions (``Meta-Point'').
 
 The familiar @kbd{M-.} command is provided. For generic functions this
 command finds all methods, and with some systems it does other fancy
@@ -377,8 +459,8 @@
 
 @end table
 
- at node Lisp Evaluation, Documentation, Finding definitions, slime-mode
- at section Lisp Evaluation
+ at node Lisp Evaluation, Documentation, Finding definitions, Commands
+ at subsection Lisp Evaluation
 
 @table @kbd
 
@@ -404,8 +486,8 @@
 
 @end table
 
- at node Documentation, Programming Helpers, Lisp Evaluation, slime-mode
- at section Documentation
+ at node Documentation, Programming Helpers, Lisp Evaluation, Commands
+ at subsection Documentation
 
 @SLIME{}'s online documentation commands follow the example of Emacs
 Lisp.
@@ -434,8 +516,8 @@
 @code{browse-url-browser-function}.
 @end table
 
- at node Programming Helpers, Recovery, Documentation, slime-mode
- at section Programming Helpers
+ at node Programming Helpers, Recovery, Documentation, Commands
+ at subsection Programming Helpers
 
 @table @kbd
 @kbditem{M-TAB, slime-complete-symbol}
@@ -461,8 +543,8 @@
 
 @end table
 
- at node Recovery, Cross-reference, Programming Helpers, slime-mode
- at section Abort/Recovery
+ at node Recovery, Cross-reference, Programming Helpers, Commands
+ at subsection Abort/Recovery
 
 @table @kbd
 
@@ -478,8 +560,8 @@
 
 @end table
 
- at node Cross-reference, Inspector, Recovery, slime-mode
- at section Cross-reference
+ at node Cross-reference, Inspector, Recovery, Commands
+ at subsection Cross-reference
 
 @SLIME{}'s cross-reference commands are based on the support provided
 by the Lisp system, which varies widely between Lisps. For systems
@@ -525,8 +607,8 @@
 List callees of a function.
 @end table
 
- at node Inspector, Profiling, Cross-reference, slime-mode
- at section Inspector
+ at node Inspector, Profiling, Cross-reference, Commands
+ at subsection Inspector
 
 The @SLIME{} inspector is an Emacs-based version of the Lisp function
 @code{INSPECT}. The inspected object is presented in a buffer with one
@@ -558,8 +640,8 @@
 
 @end table
 
- at node Profiling,  , Inspector, slime-mode
- at section Profiling
+ at node Profiling,  , Inspector, Commands
+ at subsection Profiling
 
 @table @kbd
 @item M-x slime-toggle-profile-fdefinition