dotemacs

sly.texi (112238B)

---

 \input texinfo
 @c %**start of header
 @setfilename sly.info
 
 @iftex
 @documentencoding UTF-8
 @codequoteundirected on
 @codequotebacktick on
 @end iftex
 
 @dircategory Emacs
 @direntry
 * SLY: (sly).    Common-Lisp IDE
 @end direntry
 @c %**end of header
 
 @set SLYVER 1.0.42
 @set UPDATED @today{}
 @set TITLE SLY User Manual
 @settitle @value{TITLE}, version @value{SLYVER}
 
 @copying
 Written for SLIME Luke Gorrie and others, rewritten by João
 Távora for SLY.
 
 This file has been placed in the public domain.
 @end copying
 
 @c For screenshots use
 
 @c (make-frame '((height . 32) (width . 90) (font . "Andale Mono 13")))
 @c (make-frame '((height . 32) (width . 90) (font . "DejaVu Sans Mono 10")))
 @c M-x load-theme RET base16-bright-light RET
 
 @c preferably on Mac OSX, then Cmd-Shift-4 SPC and click the window
 
 
 @titlepage
 @title @value{TITLE}
 @sp 10
 @example
           _____    __   __  __
          / ___/   / /   \ \/ /               |\      _,,,---,,_
          \__ \   / /     \  /                /,`.-'`'    -.  ;-;;,_
         ___/ /  / /___   / /                |,4-  ) )-,_..;\ (  `'-'
        /____/  /_____/  /_/                '---''(_/--'  `-'\_)
 
 @end example
 @sp 10
 @subtitle version @value{SLYVER}
 @page
 @insertcopying
 
 @end titlepage
 
 @c Macros
 
 @macro SLY
 @acronym{SLY}
 @end macro
 
 @macro SLIME
 @acronym{SLIME}
 @end macro
 
 @macro SLY-DB
 @acronym{SLY-DB}
 @end macro
 
 @macro REPL
 @acronym{REPL}
 @end macro
 
 @macro Git
 @acronym{Git}
 @end macro
 
 @macro kbditem{key, command}
 @item \key\
 @itemx M-x \command\
 @kindex \key\
 @findex \command\
 @c
 @end macro
 
 @macro kbditempair{key1, key2, command1, command2}
 @item \key1\, M-x \command1\
 @itemx \key2\, M-x \command2\
 @kindex \key1\
 @kindex \key2\
 @findex \command1\
 @findex \command2\
 @c
 @end macro
 
 @macro cmditem{command}
 @item M-x \command\
 @findex \command\
 @c
 @end macro
 
 @macro kbdanchorc{key, command, comment}
 @anchor{\command\}
 @item \key\
 @code{\command\}
 @i{\comment\}@*
 @end macro
 
 @macro fcnindex{name}
 @item \name\
 @xref{\name\}.
 @end macro
 
 @c Merge the variable and concept indices because both are rather short
 @synindex cp vr
 
 
 @c @setchapternewpage off
 @c @shortcontents
 @contents
 
 @ifnottex
 @node Top
 @top SLY
 
 @SLY{} is a Common Lisp IDE for Emacs. This is the manual for version
 @value{SLYVER}. (Last updated @value{UPDATED})
 
 @insertcopying
 @end ifnottex
 
 @menu
 * Introduction::
 * Getting started::
 * A SLY tour for SLIME users::
 * Working with source files::
 * Common functionality::
 * SLY REPL and other special buffers::
 * Customization::
 * Tips and Tricks::
 * Extensions::
 * Credits::
 * Key Index::
 * Command Index::
 * Variable Index::
 
 @detailmenu
  --- The Detailed Node Listing ---
 
 Getting started
 
 * Platforms::
 * Downloading::
 * Basic setup::
 * Running::
 * Basic customization::
 * Multiple Lisps::
 
 Working with source files
 
 * Evaluation::
 * Compilation::
 * Autodoc::
 * Semantic indentation::
 * Reader conditionals::
 * Macro-expansion::
 
 Common functionality
 
 * Finding definitions::
 * Cross-referencing::
 * Completion::
 * Interactive objects::
 * Documentation::
 * Multiple connections::
 * Disassembly::
 * Recovery::
 * Temporary buffers::
 * Multi-threading::
 
 SLY REPL and other special buffers
 
 * REPL::
 * Inspector::
 * Debugger::
 * Trace Dialog::
 * Stickers::
 
 SLY REPL: the ``top level''
 
 * REPL commands::
 * REPL output::
 * REPL backreferences::
 
 The SLY-DB Debugger
 
 * Examining frames::
 * Restarts::
 * Frame Navigation::
 * Miscellaneous::
 
 Customization
 
 * Emacs-side::
 * Lisp-side customization::
 
 Emacs-side
 
 * Keybindings::
 * Keymaps::
 * Defcustom variables::
 * Hooks::
 
 Lisp-side (Slynk)
 
 * Communication style::
 * Other configurables::
 
 Tips and Tricks
 
 * Connecting to a remote Lisp::
 * Loading Slynk faster::
 * Auto-SLY::
 * REPLs and game loops::
 * Controlling SLY from outside Emacs::
 
 Connecting to a remote Lisp
 
 * Setting up the Lisp image::
 * Setting up Emacs::
 * Setting up pathname translations::
 
 Extensions
 
 * Loading and unloading::
 * More contribs::
 
 More contribs
 
 * TRAMP Support::
 * Scratch Buffer::
 
 @end detailmenu
 @end menu
 
 @node Introduction
 @chapter Introduction
 
 @SLY{} is Sylvester the Cat's Common Lisp IDE.  It extends Emacs with
 support for interactive programming in Common Lisp.
 
 The features are centered around an Emacs minor-mode called
 @code{sly-mode}, which complements the standard major-mode
 @code{lisp-mode} for editing Lisp source files.  @code{sly-mode}
 adds support for interacting with a running Common Lisp process for
 compilation, debugging, documentation lookup, and so on.
 
 @SLY{} attempts to follow the example of Emacs's own native Emacs-Lisp
 environment.  Many of the keybindings and interface concepts used to
 interact with Emacs's Elisp machine are reused in @SLY{} to interact
 with the underlying Common Lisp run-times.  Emacs makes requests to
 these processes, asking them to compile files or code snippets; deliver
 introspection information various objects; or invoke commands or
 debugging restarts.
 
 Internally, @SLY{}'s user-interface, written in Emacs Lisp, is connected
 via sockets to one or more instances of a server program called
 ``Slynk'' that is running in the Lisp processes.
 
 The two sides communicate using a Remote Procedure Call (@acronym{RPC})
 protocol.  The Lisp-side server is primarily written in portable Common
 Lisp.  However, because some non-standard functionality is provided
 differently by each Lisp implementation (SBCL, CMUCL, Allegro, etc...)
 the Lisp-side server is again split into two parts -- portable and
 non-portable implementation -- which communicate using a well-defined
 interface.  Each Lisp implementation provides a separate implementation
 of that interface, making @SLY{} as a whole readily portable.
 
 @SLY{} is a direct fork of @acronym{SLIME}, the ``Superior Lisp
 Interaction Mode for Emacs'', which itself derived from previous Emacs
 programs such as @acronym{SLIM} and @acronym{ILISP}.  If you already
 know @acronym{SLIME}, @SLY{}'s closeness to it is immediately apparent.
 However, where @acronym{SLIME} has traditionally focused on the
 stability of its core functionality, @SLY{} aims for a richer feature
 set, a more consistent user interface, and an experience generally
 closer to Emacs' own.
 
 To understand the differences between the two projects read
 @SLY{}'s @uref{https://github.com/joaotavora/sly/blob/master/NEWS.md,,NEWS.md}
 file.  For a hand-on approach to these differences you might want to
 @ref{A SLY tour for SLIME users}.
 
 @node Getting started
 @chapter Getting started
 
 This chapter tells you how to get @SLY{} up and running.
 
 @menu
 * Platforms::
 * Downloading::
 * Basic setup::
 * Running::
 * Basic customization::
 * Multiple Lisps::
 @end menu
 
 @node Platforms
 @section Supported Platforms
 
 @SLY{} supports a wide range of operating systems and Lisp
 implementations. @SLY{} runs on Unix systems, Mac OSX, and Microsoft
 Windows. GNU Emacs versions 24.4 and above are supported. @emph{XEmacs
 or Emacs 23 are notably not supported}.
 
 The supported Lisp implementations, roughly ordered from the
 best-supported, are:
 
 @itemize @bullet
 @item
 CMU Common Lisp (@acronym{CMUCL}), 19d or newer
 @item
 Steel Bank Common Lisp (@acronym{SBCL}), 1.0 or newer
 @item
 Clozure Common Lisp (@acronym{CCL}), version 1.3 or newer
 @item
 LispWorks, version 4.3 or newer
 @item
 Allegro Common Lisp (@acronym{ACL}), version 6 or newer
 @item
 @acronym{CLISP}, version 2.35 or newer
 @item
 Armed Bear Common Lisp (@acronym{ABCL})
 @item
 Scieneer Common Lisp (@acronym{SCL}), version 1.2.7 or newer
 @item
 Embedded Common Lisp (@acronym{ECL})
 @item
 ManKai Common Lisp (@acronym{MKCL})
 @item
 Clasp
 @end itemize
 
 Most features work uniformly across implementations, but some are
 prone to variation. These include the precision of placing
 compiler-note annotations, @acronym{XREF} support, and fancy debugger
 commands (like ``restart frame'').
 
 @node Downloading
 @section Downloading SLY
 
 By far the easiest method for getting @SLY{} up and running is using
 Emacs’ package system configured to the popular MELPA repository. This
 snippet of code should already be in your configuration:
 
 @example
 (add-to-list 'package-archives
              '("melpa" . "https://melpa.org/packages/"))
 (package-initialize)
 @end example
 
 You should now be able to issue the command @kbd{M-x package-install},
 choose @kbd{sly} and have it be downloaded and installed
 automatically. If you don’t find it in the list, ensure you
 run @kbd{M-x package-refresh-contents} first.
 
 In other situations, such as when developing @SLY{} itself, you can
 access the @Git{} repository directly:
 
 @example
 git clone https://github.com/joaotavora/sly.git
 @end example
 
 If you want to hack on @SLY{}, use Github's @emph{fork} functionality
 and submit a @emph{pull request}. Be sure to first read the
 @uref{https://github.com/joaotavora/sly/blob/master/CONTRIBUTING.md,,CONTRIBUTING.md} file first.
 
 @node Basic setup
 @section Basic setup
 
 If you installed @SLY{} from MELPA, it is quite possible that you
 don’t need any more configuration, provided that @SLY{} can find a
 suitable Lisp executable in your @code{PATH} environment variable.
 
 Otherwise, you need to tell it where a Lisp program can be found, so
 customize the variable @code{inferior-lisp-program} (@pxref{Defcustom
 variables}) or add a line like this one to your @file{~/.emacs}
 or @file{~/.emacs.d/init.el} (@pxref{Emacs Init File}).
 
 @example
 (setq inferior-lisp-program "/opt/sbcl/bin/sbcl")
 @end example
 
 After evaluating this, you should be able to execute @kbd{M-x sly} and
 be greeted with a @REPL{}.
 
 If you cloned from the @Git{} repository, you’ll have to add a couple
 of more lines to your initialization file configuration:
 
 @example
 (add-to-list 'load-path "~/dir/to/cloned/sly")
 (require 'sly-autoloads)
 @end example
 
 @node Running
 @section Running SLY
 
 @SLY{} can either ask Emacs to start its own Lisp subprocesss or
 connect to a running process on a local or remote machine.
 
 The first alternative is more common for local development and is
 started via @kbd{M-x sly}. The ``inferior'' Lisp process thus started
 is told to load the Lisp-side server known as ``Slynk'' and then a
 socket connection is established between Emacs and Lisp. Finally
 a @REPL{} buffer is created where you can enter Lisp expressions for
 evaluation.
 
 The second alternative uses @kbd{M-x sly-connect}. This assumes that
 that a Slynk server is running on some local or remote host, and
 listening on a given port. @kbd{M-x sly-connect} prompts the user for
 these values, and upon connection the @REPL{} is established.
 
 @node Basic customization
 @section Basic customization
 
 A big part of Emacs, and Emacs’s extensions, are its near-infinite
 customization possibilities. @SLY{} is no exception, because it runs
 on both Emacs and the Lisp process, there are layers of Emacs-side
 customization and Lisp-side customization. But don’t be put off by
 this! @SLY{} tries hard to provide sensible defaults that don’t
 ``hide'' any fanciness beneath layers of complicated code, so that
 even a setup with no customization at all exposes @SLY{}’s most
 important functionality.
 
 Emacs-side customization is usually done via Emacs-lisp code snippets
 added to the user’s initialization file, usually @file{$HOME/.emacs} or
 @file{$HOME/.emacs.d/init.el} (@pxref{Emacs Init File}).
 
 90% of Emacs-lisp customization happens in either ``keymaps'' or
 ``hooks'' (@pxref{Emacs-side}). Still on the Emacs side, there is also a
 separate interface, appropriately called @code{customize} (or sometimes
 just @code{custom}), that uses a nicer UI with mouse-clickable buttons
 to set some special variables. See @xref{Defcustom variables}.
 
 Lisp-side customization is done exclusively via Common Lisp code
 snippets added to the user’s @file{$HOME/.slynkrc}
 file. See @xref{Lisp-side customization}.
 
 As a preview, take this simple example of a frequently customized part of
 @SLY{}: its keyboard shortcuts, known as ``keybindings''. In the
 following snippet @kbd{M-h} is added to @code{sly-prefix-map} thus
 yielding @kbd{C-c M-h} as a shortcut to
 the @code{sly-documentation-lookup} command.
 
 @example
 (eval-after-load 'sly
   `(define-key sly-prefix-map (kbd "M-h") 'sly-documentation-lookup))
 @end example
 
 @node Multiple Lisps
 @section Multiple Lisps
 
 By default, the command @kbd{M-x sly} starts the program specified
 with @code{inferior-lisp-program}, a variable that you can customize
 (@pxref{Defcustom variables}).  However, if you invoke @kbd{M-x sly}
 with a @emph{prefix argument}, meaning you type @kbd{C-u M-x sly} then
 Emacs prompts for the program which should be started instead.
 
 If you need to do this frequently or if the command involves long
 filenames it's more convenient to set
 the @code{sly-lisp-implementations} variable in your initialization file
 (@pxref{Emacs Init File}).  For example here we define two programs:
 
 @lisp
 (setq sly-lisp-implementations
       '((cmucl ("cmucl" "-quiet"))
         (sbcl ("/opt/sbcl/bin/sbcl") :coding-system utf-8-unix)))
 @end lisp
 
 Now, if you invoke @SLY{} with a @emph{negative} prefix argument,
 @kbd{M-- M-x sly}, you can select a program from that list. When
 called without a prefix, either the name specified in
 @code{sly-default-lisp}, or the first item of the list will be used.
 The elements of the list should look like
 
 @lisp
 (NAME (PROGRAM PROGRAM-ARGS...) &key CODING-SYSTEM INIT INIT-FUNCTION ENV)
 @end lisp
 
 @table @code
 @item NAME
 is a symbol and is used to identify the program.
 @item PROGRAM
 is the filename of the program.  Note that the filename can contain
 spaces.
 @item PROGRAM-ARGS
 is a list of command line arguments.
 @item CODING-SYSTEM
 the coding system for the connection.  (@pxref{sly-net-coding-system})x
 @item INIT
 should be a function which takes two arguments: a filename and a
 character encoding.  The function should return a Lisp expression as a
 string which instructs Lisp to start the Slynk server and to write the
 port number to the file.  At startup, @SLY{} starts the Lisp process
 and sends the result of this function to Lisp's standard input.  As
 default, @code{sly-init-command} is used.  An example is shown in
 @ref{init-example,,Loading Slynk faster}.
 @item INIT-FUNCTION
 should be a function which takes no arguments.  It is called after
 the connection is established. (See also @ref{sly-connected-hook}.)
 @item ENV
 specifies a list of environment variables for the subprocess. E.g.
 @lisp
 (sbcl-cvs ("/home/me/sbcl-cvs/src/runtime/sbcl"
            "--core" "/home/me/sbcl-cvs/output/sbcl.core")
           :env ("SBCL_HOME=/home/me/sbcl-cvs/contrib/"))
 @end lisp
 initializes @code{SBCL_HOME} in the subprocess.
 @end table
 
 @node A SLY tour for SLIME users
 @chapter A SLY tour for SLIME users
 
 The chances are that if you’re into Common Lisp, you already know about
 @SLIME{}, the project that originated @SLY{}.  Itself originating in
 older Emacs extensions @acronym{SLIM} and @acronym{ILISP}, @SLIME{} has
 been around for at least a decade longer than @SLY{} and is quite an
 amazing IDE.  It seems reasonable to assume that most Lispers have some
 experience with it, and perhaps it is an even more reasonable idea to
 provide, in the form of a quick tutorial, a hands-on overview of some of
 the improvements of @SLY{} over @SLIME{}.
 
 When you start @SLY{} with @kbd{M-x sly} (@pxref{Basic setup}) you are
 greeted with its @REPL{}, a common starting point of Lisp hacking
 sessions.  This has been completely redesigned in @SLY{}: you can spawn
 multiple REPL sessions with @code{sly-mrepl-new}; copy objects from most
 places directly into it (with @kbd{M-RET} and @kbd{M-S-RET}); and use a
 much more powerful incremental history search engine (with @kbd{C-r}).
 
 @*@image{images/tutorial-1,350pt}@*
 
 Starting from the new @REPL{}, let's showcase some of @SLY{}’s features.
 Let’s pretend we want to hack an existing Lisp project, say @SLY{}
 itself, or rather a part of its Lisp server which is called Slynk.
 Let's pretend we're intrigued by the way its ``flex''-style completion
 works.  What is ``flex''-style completion, you ask?  Well, if you're at
 the @REPL{} you can try it now: it's a way of @kbd{TAB}-completing
 (@pxref{Completion}) symbol names based on educated guesses of a few
 letters. Thus if we type @code{mvbind}, @SLY{} guesses that we probably
 meant @code{multiple-value-bind}, and if we type @code{domat} it might
 possibly guess @code{cl-ppcre:do-matches}.  Let's dig into the code that
 makes this happen.
 
 Where should we start though, if we know very little about this project?
 Well, a good point to start is always the @emph{apropos} functionality,
 which is a @code{grep} of sorts, but symbolic rather than purely
 textual.  In @SLY{}, @code{sly-apropos} will use the @code{CL-PPCRE}
 library if it finds is it loaded, else it falls back to a regex-less
 mode of searching.  If you
 have @uref{https://www.quicklisp.org/beta/,Quicklisp} you need only
 type @code{(ql:quickload :cl-ppcre)} from the @REPL{}.
 
 So if we want to hack on @SLY{}'s ``flex-completion'' functionality, but
 we don't any of its symbol's names.  We type
 @kbd{C-c C-d C-z} (the shortcut for @kbd{M-x sly-apropos-all}) and
 then type in ``sly.*flex'' at the prompt, followed by @kbd{enter}
 or @kbd{return} (abbreviated @code{RET} or @kbd{C-m}). @SLY{} should
 now present all Lisp symbols matching your search pattern.
 
 @*@image{images/tutorial-2,350pt}@*
 
 In the @code{apropos} buffer, let’s examine, by right-clicking it, the
 symbol @code{SLY-COMPLETIONS:FLEX-COMPLETIONS}.  We’ll be presented with
 a context menu with options for describing the symbol, inspecting it, or
 navigating to its source definition.  In general, the Lisp-side objects
 that SLY presents --- symbols, CLOS objects, function calls, etc... ---
 are right-clickable buttons with such a context menu
 (@pxref{Interactive objects}).  For now, let’s navigate to the source
 definition of the symbol by choosing ``Go To source'' from the menu.  We
 could also have just pressed @kbd{M-.} on the symbol, of course.
 
 From the Lisp source buffer that we landed on (probably
 @file{slynk-completion.lisp}), let’s @emph{trace} the newly found function
 @code{SLY-COMPLETIONS:FLEX-COMPLETIONS}.  However, instead of using the
 regular @code{CL:TRACE}, we’ll use @SLY{}’s Trace Dialog functionality.
 This is how we set it up:
 
 @enumerate
 
 @item
 first type @kbd{C-c C-t} on the function’s name, or enter that in the
 minibuffer prompt;
 
 @item
 now, open the Trace Dialog in a new window by typing @kbd{C-c T} (that’s
 a capital @code{T}).  We should already see our traced function under
 the heading ``Traced specs'';
 
 @item
 thirdly, for good measure, let’s also trace the nearby
 function @code{SLY-COMPLETIONS::FLEX-SCORE} by also typing @kbd{C-c C-t}
 on its name, or just entering it in the minibuffer prompt.
 
 @end enumerate
 
 Now let’s return to the REPL by switching to its
 @code{*sly-mrepl ...} buffer or typing @kbd{C-c C-z}. In the REPL, let’s try to
 complete some typical Lisp string by typing just @code{desbind} and then
 typing @kbd{TAB}. We should see a window popup including the desired
 completion @code{destructuring-bind} (it should also be the top
 match). Of course, we could now select some completion from the list,
 but instead let's just type @kbd{C-g} to dismiss
 the @code{*sly-completions*} window, since  we wanted to test
 completion, not write any actual @code{destructuring-bind} expression.
 
 Remember the traced functions in the Trace Dialog?  Let’s see if we got
 any traces: let's type @kbd{C-c T} to switch to that buffer, and then
 type capital @kbd{G}. This should produce a fair number of traces
 organized in a call graph.
 
 @*@image{images/tutorial-3,350pt}@*
 
 We can later learn more about this mode (@pxref{Trace Dialog}), but for
 now let’s again pretend we expected the function @code{FLEX-SCORE} to
 return a wildly different score for
 @code{COMMON-LISP:DESTRUCTURING-BIND}.  In that case we should like to
 witness said @code{FLEX-SCORE} function respond to any implementation
 improvements we perform.  To do so, it's useful to be able to surgically
 re-run that function with those very same arguments.  Let's do this by
 finding the function call in the Trace Dialog window, right-clicking it
 with the mouse and selecting ``Copy call to REPL''.  As an alternative,
 pressing @kbd{M-S-RET} on it also works.  Whichever way we do this, we
 are automatically transported to the REPL again, where the desired
 function call has already been typed out for us at the command prompt,
 awaiting a confirmation @kbd{RET}, which will run the function call.
 The call may look strange, though:
 
 @example
 ; The actual arguments passed to trace 15
 "desbind"
 "COMMON-LISP:DESTRUCTURING-BIND"
 (12 13 14 26 27 28 29)
 SLYNK-COMPLETION> (slynk-completion::flex-score #v1:0 #v1:1 #v1:2)
 0.003030303 (0.30303028%)
 SLYNK-COMPLETION>
 @end example
 
 @*@image{images/tutorial-4,350pt}@*
 
 So here’s what’s going on: to copy the call to the REPL, @SLY{} first
 copied over its actual arguments, and then wrote the function using
 special @emph{backreferences} to those arguments in the correct place.
 These are the @code{#v4:0} and @code{#v4:1} bits seen at the command
 prompt.  Let’s go ahead and put the cursor on them (or hover the mouse).
 See how this makes them highlight the corresponding object a few lines
 above in the buffer?  Later, you can also try typing ``#v'' at the REPL
 to incrementally write your own backreferences.
 
 For one final demonstration, let’s now suppose say we are still
 intrigued by how that function (@code{FLEX-SCORE}) works internally. So let's navigate to
 its definition using @kbd{M-.} again (or just open
 the @file{slynk-completion.lisp} buffer that you probably still have
 open). The function’s code might look like this:
 
 @example
 (defun flex-score (pattern string indexes)
   "Score the match of PATTERN on STRING.
 INDEXES as calculated by FLEX-MATCHES"
   ;; FIXME: hideously naive scoring
   (declare (ignore pattern))
   (float
    (/ 1
       (* (length string)
          (max 1
               (reduce #'+
                       (loop for (a b) on indexes
                             while b
                             collect (- b a 1))))))))
 @end example
 
 Can this function be working correctly?  What do all those expressions
 return?  Should we reach for good old C-style @code{printf}?  Let's try
 ``stickers'' instead.  SLY's stickers are a form of non-intrusive
 function instrumentation that work like carefully crafted @code{print}
 or @code{(format t ...)}), but are much easier to work with.  You can
 later read more about them (@pxref{Stickers}), but for now you can just
 think of them as colorful labels placed on s-exp’s.  Let’s place a bunch
 here, like this:
 
 @enumerate
 
 @item
 on the last line of @code{flex-score}, place your cursor on the first
 open parenthesis of that line (the opening parenthesis of the expression
 @code{(- b a 1)}) and press @kbd{C-c C-s C-s};
 
 @item
 now do the same for the symbol @code{indexes} a couple of lines above;
 
 @item
 again, the same for the expressions @code{(loop...)},
 @code{(reduce...)}, @code{(max...)}, @code{(length...)},
 @code{(*...)}, @code{(/... )} and @code{(float...)}.  You could have
 done this in any order, by the way;
 
 @end enumerate
 
 Now let’s recompile this definition with @kbd{C-c C-c}.  Beside the
 minibuffer note something about stickers being ``armed'' our function
 should now look like a rainbow in blue.
 
 @*@image{images/tutorial-5,350pt}@*
 
 Now we return to the @SLY{} REPL, but this time let’s use @kbd{C-c ~}
 (that’s @kbd{C-c} followed by ``tilde'') to do so.  This syncs the
 REPL’s local package and local directory to the Lisp file that we’re
 visiting.  This is something not strictly necessary here but generally
 convenient when hacking on a system, because you can now call functions
 from the file you came from without package-qualification.
 
 Now, to re-run the newly instrumented function, by calling it with the
 same arguments.  No need to type all that again, because this REPL
 supports reverse history i-search, remember?  So just type the
 binding @kbd{C-r} and then type something like @kbd{scor} to search
 history backwards and arrive at the function call copied to the REPL
 earlier.  Type @kbd{RET} once to confirm that's the call your after,
 and @kbd{RET} again to evaluate it.  Because those @code{#v...}
 backreferences are still trained specifically on those very same
 function arguments, you can be sure that the function call is
 equivalent.
 
 We can now use the @kbd{C-c C-s C-r} to @emph{replay} the sticker
 recordings of this last function call.  This is a kind of slow
 walk-through conducted in separate navigation window
 called @code{*sly-stickers-replay*} which pops up.  There we can see the
 Lisp value(s) that each sticker @code{eval}’ed to each time (or a note
 if it exited non-locally).  We can navigate recordings with @kbd{n} and
 @kbd{p}, and do the usual things allowed by interactive objects like
 inspecting them and returning them to the REPL. If you need help, toggle
 help by typing @kbd{h}.  There are lots of options here for navigating
 stickers, ignoring some stickers, etc.  When we’re done in this window,
 we press @kbd{q} to quit.
 
 @*@image{images/tutorial-6,350pt}@*
 
 Finally, we declare that we’re finished debugging @code{FLEX-MATCHES}.
 Even though stickers don’t get saved to the file in any way, we decide
 we’re not interested in them anymore.  So let’s open the ``SLY'' menu in
 the menu bar, find the ``Delete stickers from top-level form'' option
 under the ``Stickers'' sub-menu, and click it.  Alternatively, we could
 have typed @kbd{C-u C-c C-s C-s}.
 
 @node Working with source files
 @chapter Working with source files
 
 @SLY{}'s commands when editing a Lisp file are provided via
 @code{sly-editing-mode}, a minor-mode used in conjunction with Emacs's
 @code{lisp-mode}.
 
 This chapter describes @SLY{}’s commands for editing and working in
 Lisp source buffers. There are, of course, more @SLY{}’s commands that
 also apply to these buffers (@pxref{Common functionality}), but
 with very few exceptions these commands will always be run from
 a @code{.lisp} file.
 
 @menu
 * Evaluation::
 * Compilation::
 * Autodoc::
 * Semantic indentation::
 * Reader conditionals::
 * Macro-expansion::
 @end menu
 
 @node Evaluation
 @section Evaluating code
 
 These commands each evaluate a Common Lisp expression in a different
 way. Usually they mimic commands for evaluating Emacs Lisp code. By
 default they show their results in the echo area, but a prefix
 argument @kbd{C-u} inserts the results into the current buffer, while
 a negative prefix argument @kbd{M--} sends them to the kill ring.
 
 @table @kbd
 
 @kbditem{C-x C-e, sly-eval-last-expression}
 
 Evaluate the expression before point and show the result in the echo
 area.
 
 @kbditem{C-M-x, sly-eval-defun}
 Evaluate the current toplevel form and show the result in the echo
 area.  `C-M-x' treats `defvar' expressions specially.  Normally,
 evaluating a `defvar' expression does nothing if the variable it
 defines already has a value.  But `C-M-x' unconditionally resets the
 variable to the initial value specified in the `defvar' expression.
 This special feature is convenient for debugging Lisp programs.
 
 @end table
 
 If @kbd{C-M-x} or @kbd{C-x C-e} is given a numeric argument, it
 inserts the value into the current buffer, rather than displaying it
 in the echo area.
 
 @table @kbd
 @kbditem{C-c :, sly-interactive-eval}
 Evaluate an expression read from the minibuffer.
 
 @kbditem{C-c C-r, sly-eval-region}
 Evaluate the region.
 
 @kbditem{C-c C-p, sly-pprint-eval-last-expression}
 Evaluate the expression before point and pretty-print the result in a
 fresh buffer.
 
 @kbditem{C-c E, sly-edit-value}
 Edit the value of a setf-able form in a new buffer @file{*Edit <form>*}.
 The value is inserted into a temporary buffer for editing and then set
 in Lisp when committed with @kbd{C-c C-c}.
 
 @kbditem{C-c C-u, sly-undefine-function}
 Undefine the function, with @code{fmakunbound}, for the symbol at
 point.
 
 @end table
 
 @node Compilation
 @section Compiling functions and files
 
 @cindex Compilation
 
 @SLY{} has fancy commands for compiling functions, files, and
 packages. The fancy part is that notes and warnings offered by the
 Lisp compiler are intercepted and annotated directly onto the
 corresponding expressions in the Lisp source buffer. (Give it a try to
 see what this means.)
 
 @table @kbd
 @cindex Compiling Functions
 @kbditem{C-c C-c, sly-compile-defun}
 Compile the top-level form at point.  The region blinks shortly to
 give some feedback which part was chosen.
 
 With (positive) prefix argument the form is compiled with maximal
 debug settings (@kbd{C-u C-c C-c}). With negative prefix argument it is compiled for
 speed (@kbd{M-- C-c C-c}). If a numeric argument is passed set debug or speed settings
 to it depending on its sign.
 
 The code for the region is executed after compilation.  In principle,
 the command writes the region to a file, compiles that file, and loads
 the resulting code.
 
 This compilation may arm stickers (@pxref{Stickers}).
 
 @kbditem{C-c C-k, sly-compile-and-load-file}
 Compile and load the current buffer's source file.  If the compilation
 step fails, the file is not loaded.  It's not always easy to tell
 whether the compilation failed: occasionally you may end up in the
 debugger during the load step.
 
 With (positive) prefix argument the file is compiled with maximal
 debug settings (@kbd{C-u C-c C-k}). With negative prefix argument it is compiled for
 speed (@kbd{M-- C-c C-k}). If a numeric argument is passed set debug or speed settings
 to it depending on its sign.
 
 This compilation may arm stickers (@pxref{Stickers}).
 
 @kbditem{C-c M-k, sly-compile-file}
 Compile (but don't load) the current buffer's source file.
 
 @kbditem{C-c C-l, sly-load-file}
 Load a Lisp file.  This command uses the Common Lisp LOAD function.
 
 @cmditem{sly-compile-region}
 Compile the selected region.
 
 This compilation may arm stickers (@pxref{Stickers}).
 
 @end table
 
 The annotations are indicated as underlining on source forms. The
 compiler message associated with an annotation can be read either by
 placing the mouse over the text or with the selection commands below.
 
 @table @kbd
 @kbditem{M-n, sly-next-note}
 Move the point to the next compiler note and displays the note.
 
 @kbditem{M-p, sly-previous-note}
 Move the point to the previous compiler note and displays the note.
 
 @kbditem{C-c M-c, sly-remove-notes}
 Remove all annotations from the buffer.
 
 @kbditem{C-x `, next-error}
 Visit the next-error message.  This is not actually a @SLY{} command
 but @SLY{} creates a hidden buffer so that most of the Compilation
 mode commands (@inforef{Compilation Mode,, emacs}) work similarly for
 Lisp as for batch compilers.
 
 @end table
 
 @node Autodoc
 @section Autodoc
 
 SLY automatically shows information about symbols near the point. For
 function names the argument list is displayed, and for global
 variables, the value.  Autodoc is implemented by means
 of @code{eldoc-mode} of Emacs.
 
 @table @kbd
 @cmditem{sly-arglist NAME}
 Show the argument list of the function NAME.
 
 @cmditem{sly-autodoc-mode}
 Toggles autodoc-mode on or off according to the argument, and
 toggles the mode when invoked without argument.
 @cmditem{sly-autodoc-manually}
 Like sly-autodoc, but when called twice,
 or after sly-autodoc was already automatically called,
 display multiline arglist.
 @end table
 
 If @code{sly-autodoc-use-multiline-p} is set to non-nil,
 allow long autodoc messages to resize echo area display.
 
 @code{autodoc-mode} is a SLY extension  and can be turned off if you
 so wish (@pxref{Extensions})
 
 @node Semantic indentation
 @section Semantic indentation
 
 @SLY{} 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, @SLY{} 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:
 
 @example
 (slynk:print-indentation-lossage)
 @end example
 
 If a collision causes you irritation, don't have a nervous breakdown,
 just override the Elisp symbol's @code{sly-common-lisp-indent-function}
 property to your taste. @SLY{} 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.}
 
 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 sly-update-indentation} to force all symbols to
 be scanned for indentation information.
 
 @node Reader conditionals
 @section Reader conditional fontification
 
 @SLY{} automatically evaluates reader-conditional expressions, like
 @code{#+linux}, in source buffers and ``grays out'' code that will be
 skipped for the current Lisp connection.
 
 @node Macro-expansion
 @section Macro-expansion commands
 
 @cindex Macros
 
 @table @kbd
 @kbditem{C-c C-m, sly-expand-1}
 Macroexpand (or compiler-macroexpand) the expression at point
 once.  If invoked with a prefix argument use macroexpand instead or
 macroexpand-1 (or compiler-macroexpand instead of
 compiler-macroexpand-1).
 
 @cmditem{sly-macroexpand-1}
 Macroexpand the expression at point once.  If invoked with a prefix
 argument, use macroexpand instead of macroexpand-1.
 
 @kbditem{C-c M-m, sly-macroexpand-all}
 Fully macroexpand the expression at point.
 
 @cmditem{sly-compiler-macroexpand-1}
 Display the compiler-macro expansion of sexp at point.
 
 @cmditem{sly-compiler-macroexpand}
 Repeatedly expand compiler macros of sexp at point.
 
 @cmditem{sly-format-string-expand}
 Expand the format-string at point and display it.
 With prefix arg, or if no string at point, prompt the user for a
 string to expand.
 
 @end table
 
 Within a sly macroexpansion buffer some extra commands are provided
 (these commands are always available but are only bound to keys in a
 macroexpansion buffer).
 
 @table @kbd
 @kbditem{C-c C-m, sly-macroexpand-1-inplace}
 Just like sly-macroexpand-1 but the original form is replaced with
 the expansion.
 
 @c @anchor{sly-macroexpand-1-inplace}
 @kbditem{g, sly-macroexpand-1-inplace}
 The last macroexpansion is performed again, the current contents of
 the macroexpansion buffer are replaced with the new expansion.
 
 @kbditem{q, sly-temp-buffer-quit}
 Close the expansion buffer.
 
 @kbditem{C-_, sly-macroexpand-undo}
 Undo last macroexpansion operation.
 
 @end table
 
 @node Common functionality
 @chapter Common functionality
 
 This chapter describes the commands available throughout
 @SLY{}-enabled buffers, which are not only Lisp source buffers, but
 every auxiliary buffer created by @SLY{}, such as the @REPL{},
 Inspector, etc (@pxref{SLY REPL and other special buffers}) In
 general, it’s a good bet that if the buffer’s name starts with
 @code{*sly-...*}, these commands and functionality will be available
 there.
 
 @menu
 * Finding definitions::
 * Cross-referencing::
 * Completion::
 * Interactive objects::
 * Documentation::
 * Multiple connections::
 * Disassembly::
 * Recovery::
 * Temporary buffers::
 * Multi-threading::
 @end menu
 
 @node Finding definitions
 @section Finding definitions
 
 One of the most used keybindings across all of @SLY{} is the
 familiar @kbd{M-.} binding for @kbd{sly-edit-definition}.
 
 Here's the gist of it: when pressed with the cursor over a symbol
 name, that symbol's name definition is looked up by the Lisp process,
 thus producing a Lisp source location, which might be a file, or a
 file-less buffer. For convenience, a type of ``breadcrumb'' is left
 behind at the original location where @kbd{M-.} was pressed, so that
 another keybinding @kbd{M-,} takes the user back to the original
 location. Thus multiple @kbd{M-.} trace a path through lisp sources
 that can be traced back with an equal number of @kbd{M-,}.
 
 @table @kbd
 @kbditem{M-., sly-edit-definition}
 Go to the definition of the symbol at point.
 
 @item M-,
 @itemx M-*
 @itemx M-x sly-pop-find-definition-stack
 @kindex M-,
 @findex sly-pop-find-definition-stack
 Go back to the point where @kbd{M-.} was invoked. This gives multi-level
 backtracking when @kbd{M-.} has been used several times.
 
 @kbditem{C-x 4 ., sly-edit-definition-other-window}
 Like @code{sly-edit-definition} but switches to the other window to
 edit the definition in.
 
 @kbditem{C-x 5 ., sly-edit-definition-other-frame}
 Like @code{sly-edit-definition} but opens another frame to edit the
 definition in.
 @end table
 
 The behaviour of the @kbd{M-.} binding is sometimes affected by the
 type of symbol you are giving it.
 
 @itemize @bullet
 @item
 For single functions or variables, @kbd{M-.} immediately switches
 the current window's buffer and position to the target @code{defun} or
 @code{defvar}.
 
 @item
 For symbols with more than one associated definition, say, generic
 functions, the same @kbd{M-.} finds all methods and presents these
 results in separate window displaying a special @code{*sly-xref*}
 buffer (@pxref{Cross-referencing}).
 @end itemize
 
 @node Cross-referencing
 @section Cross-referencing
 
 Finding and presenting the definition of a function is actually the
 most elementary aspect of broader @emph{cross-referencing} facilities
 framework in @SLY{}. There are other types of questions about the
 source code relations that you can ask the Lisp process.@footnote{This
 depends on the underlying implementation of some of these facilities:
 for systems with no built-in @acronym{XREF} support @SLY{} queries a
 portable
 @acronym{XREF} package, which is taken from the @cite{CMU AI
 Repository} and bundled with @SLY{}.}
 
 The following keybindings behave much like the @kbd{M-.} keybinding
 (@pxref{Finding definitions}): when pressed as is they make a query
 about the symbol at point, but with a @kbd{C-u} prefix argument they
 prompt the user for a symbol. Importantly, they always popup a
 transient @code{*sly-xref*} buffer in a different window.
 
 @table @kbd
 @kbditem{M-?, sly-edit-uses}
 Find all the references to this symbol, whatever the type of that
 reference.
 
 @kbditem{C-c C-w C-c, sly-who-calls}
 Show function callers.
 
 @kbditem{C-c C-w C-w, sly-calls-who}
 Show all known callees.
 
 @kbditem{C-c C-w C-r, sly-who-references}
 Show references to global variable.
 
 @kbditem{C-c C-w C-b, sly-who-binds}
 Show bindings of a global variable.
 
 @kbditem{C-c C-w C-s, sly-who-sets}
 Show assignments to a global variable.
 
 @kbditem{C-c C-w C-m, sly-who-macroexpands}
 Show expansions of a macro.
 
 @cmditem{sly-who-specializes}
 Show all known methods specialized on a class.
 
 @end table
 
 There are two further ``List callers/callees'' commands that operate
 by rummaging through function objects on the heap at a low-level to
 discover the call graph. They are only available with some Lisp
 systems, and are most useful as a fallback when precise @acronym{XREF}
 information is unavailable.
 
 @table @kbd
 @kbditem{C-c <, sly-list-callers}
 List callers of a function.
 
 @kbditem{C-c >, sly-list-callees}
 List callees of a function.
 
 @end table
 
 In the resulting @code{*sly-xref*} buffer, these commands are
 available:
 
 @table @kbd
 @kbditem{RET, sly-show-xref}
 Show definition at point in the other window. Do not leave
 the @code{*sly-xref} buffer.
 
 @kbditem{Space, sly-goto-xref}
 Show definition at point in the other window and close
 the @code{*sly-xref} buffer.
 
 @kbditem{C-c C-c, sly-recompile-xref}
 Recompile definition at point. Uses prefix arguments like
 @code{sly-compile-defun}.
 
 @kbditem{C-c C-k, sly-recompile-all-xrefs}
 Recompile all definitions. Uses prefix arguments like
 @code{sly-compile-defun}.
 
 @end table
 
 @node Completion
 @section Auto-completion
 
 @cindex Completion
 @cindex Symbol Completion
 
 Completion commands are used to complete a symbol or form based on
 what is already present at point. Emacs has many completion mechanisms
 that @SLY{} tries to mimic as much as possible.
 
 SLY provides two styles of completion. The choice between them happens
 in the Emacs customization variable
 @pxref{sly-complete-symbol-function}, which can be set to two values,
 or methods:
 
 @enumerate
 @item @code{sly-flex-completions}
 This method is speculative. It assumes that the letters you've already
 typed aren't necessarily an exact prefix of the symbol you're thinking
 of. Therefore, any possible completion that contains these letters, in
 the order that you have typed them, is potentially a match. Completion
 matches are then sorted according to a score that should reflect the
 probability that you really meant that them.
 
 Flex completion implies that the package-qualification needed to
 access some symbols is automatically discovered for you. However, to
 avoid searching too many symbols unnecessarily, this method makes some
 minimal assumptions that you can override: it assumes, for example,
 that you don't normally want to complete to fully qualified internal
 symbols, but will do so if it finds two consecutive colons (@code{::})
 in your initial pattern. Similarly, it assumes that if you start a
 completion on a word starting @code{:}, you must mean a keyword (a
 symbol from the keyword package.)
 
 Here are the top results for some typical searches.
 
 @example
 CL-USER> (quiloa<TAB>)         ->  (ql:quickload)
 CL-USER> (mvbind<TAB>)         ->  (multiple-value-bind)
 CL-USER> (scan<TAB>)           ->  (ppcre:scan)
 CL-USER> (p::scan<TAB>)        ->  (ppcre::scanner)
 CL-USER> (setf locadirs<TAB>)  ->  (setf ql:*local-project-directories*)
 CL-USER> foobar                ->  asdf:monolithic-binary-op
 @end example
 
 @item @code{sly-simple-completions}
 This method uses ``classical'' completion on an exact prefix. Although
 poorer, this is simpler, more predictable and closer to the default
 Emacs completion method. You type a prefix for a symbol reference and
 @SLY{} let's you choose from symbols whose beginnings match it
 exactly.
 @end enumerate
 
 As an enhancement in @SLY{} over Emacs' built-in completion styles,
 when the @code{*sly-completions*} buffer pops up, some keybindings are
 momentarily diverted to it:
 
 @table @kbd
 @item C-n
 @itemx <down>
 @itemx M-x sly-next-completion
 @kindex C-n
 @findex sly-next-completion
 Select the next completion.
 
 @item C-p
 @itemx <up>
 @itemx M-x sly-prev-completion
 @kindex C-p
 @findex sly-prev-completion
 Select the previous completion.
 
 @item tab
 @itemx RET
 @itemx M-x sly-choose-completion
 @kindex tab
 @findex sly-choose-completion
 Choose the currently selected completion and enter it at point.
 @end table
 
 As soon as the user selects a completion or gives up by
 pressing @kbd{C-g} or moves out of the symbol being completed, the
 @code{*sly-completions*} buffer is closed.
 
 @node Interactive objects
 @section Interactive objects
 
 In many buffers and modes in @SLY{}, there are snippets of text that
 represent objects ``living'' in the Lisp process connected to @SLY{}.
 These regions are known in @SLY{} as interactive values or objects.
 You can tell these objects from regular text by their distinct
 ``face'', is Emacs parlance for text colour, or decoration.  Another
 way to check if bit of text is an interactive object is to hover above
 it with the mouse and right-click (@kbd{<mouse-3>}) it: a context menu
 will appear listing actions that you can take on that object.
 
 @c Yet another way to discover these objects is
 @c with @kbd{sly-button-forward} and @kbd{sly-button-backward}
 
 Depending on the mode, different actions may be active for different
 types of objects. Actions can also be invoked using keybindings active
 only when the cursor is on the button.
 
 @table @kbd
 
 @item @kbd{M-RET}, ``Copy to REPL''
 
 Copy the object to the main @REPL{} (@pxref{REPL output} and @pxref{REPL
 backreferences}).
 
 @item @kbd{M-S-RET}, ``Copy call to REPL''
 
 An experimental feature. On some backtrace frames in the Debugger
 (@pxref{Debugger}) and Trace Dialog (@pxref{Trace Dialog}), copy
 the object to the main @REPL{}. That’s @emph{meta-shift-return}, by
 the way, there’s no capital ``S''.
 
 @item @kbd{.},''Go To Source''
 
 For function symbols, debugger frames, or traced function calls, go to
 the Lisp source, much like with @kbd{M-.}.
 
 @item @kbd{v},''Show Source''
 
 For function symbols, debugger frames, or traced function calls, show
 the Lisp source in another window, but don’t switch to it.
 
 @item @kbd{p},''Pretty Print''
 
 Pretty print the object in a separate buffer, much
 like @code{sly-pprint-eval-last-expression}.
 
 @item @kbd{i},''Inspect''
 
 Inspect the object in a separate inspector buffer (@pxref{Inspector}).
 
 @item @kbd{d},''Describe''
 
 Describe the object in a separate buffer using Lisp’s
 @code{CL:DESCRIBE}.
 
 @end table
 
 @node Documentation
 @section Documentation commands
 
 @SLY{}'s online documentation commands follow the example of Emacs
 Lisp. The commands all share the common prefix @kbd{C-c C-d} and allow
 the final key to be modified or unmodified (@pxref{Keybindings}.)
 
 @table @kbd
 
 @cmditem{sly-info}
 This command should land you in an electronic version of this very
 manual that you can read inside Emacs.
 
 @kbditem{C-c C-d C-d, sly-describe-symbol}
 Describe the symbol at point.
 
 @kbditem{C-c C-d C-f, sly-describe-function}
 Describe the function at point.
 
 @kbditem{C-c C-d C-a, sly-apropos}
 Perform an apropos search on Lisp symbol names for a regular expression
 match and display their documentation strings. By default the external
 symbols of all packages are searched. With a prefix argument you can choose a
 specific package and whether to include unexported symbols.
 
 @kbditem{C-c C-d C-z, sly-apropos-all}
 Like @code{sly-apropos} but also includes internal symbols by default.
 
 @kbditem{C-c C-d C-p, sly-apropos-package}
 Show apropos results of all symbols in a package. This command is for
 browsing a package at a high-level. With package-name completion it
 also serves as a rudimentary Smalltalk-ish image-browser.
 
 @kbditem{C-c C-d C-h, sly-hyperspec-lookup}
 Lookup the symbol at point in the @cite{Common Lisp Hyperspec}. This
 uses the familiar @file{hyperspec.el} to show the appropriate section
 in a web browser. The Hyperspec is found either on the Web or in
 @code{common-lisp-hyperspec-root}, and the browser is selected by
 @code{browse-url-browser-function}.
 
 Note: this is one case where @kbd{C-c C-d h} is @emph{not} the same as
 @kbd{C-c C-d C-h}.
 
 @kbditem{C-c C-d ~, hyperspec-lookup-format}
 Lookup a @emph{format character} in the @cite{Common Lisp Hyperspec}.
 
 @kbditem{C-c C-d #, hyperspec-lookup-reader-macro}
 Lookup a @emph{reader macro} in the @cite{Common Lisp Hyperspec}.
 @end table
 
 @node Multiple connections
 @section Multiple connections
 
 @SLY{} is able to connect to multiple Lisp processes at the same
 time. The @kbd{M-x sly} command, when invoked with a prefix
 argument, will offer to create an additional Lisp process if one is
 already running. This is often convenient, but it requires some
 understanding to make sure that your @SLY{} commands execute in the
 Lisp that you expect them to.
 
 Some @SLY{} buffers are tied to specific Lisp processes. It’s easy
 read that from the buffer’s name which will usually be
 @code{*sly-<something> for <connection>*}, where @code{connection} is
 the name of the connection.
 
 Each Lisp connection has its own main @acronym{REPL} buffer
 (@pxref{REPL}), and all expressions entered or @SLY{} commands invoked
 in that buffer are sent to the associated connection. Other buffers
 created by @SLY{} are similarly tied to the connections they originate
 from, including @SLY-DB{} buffers (@pxref{Debugger}), apropos result
 listings, and so on. These buffers are the result of some interaction
 with a Lisp process, so commands in them always go back to that same
 process.
 
 Commands executed in other places, such as @code{sly-mode} source
 buffers, always use the ``default'' connection. Usually this is the
 most recently established connection, but this can be reassigned via
 the ``connection list'' buffer:
 
 @table @kbd
 @kbditem{C-c C-x c, sly-list-connections}
 Pop up a buffer listing the established connections.
 
 @kbditem{C-c C-x n, sly-next-connection}
 Switch to the next Lisp connection by cycling through all connections.
 
 @kbditem{C-c C-x p, sly-prev-connection}
 Switch to the previous Lisp connection by cycling through all connections.
 
 @end table
 
 The buffer displayed by @code{sly-list-connections} gives a one-line
 summary of each connection. The summary shows the connection's serial
 number, the name of the Lisp implementation, and other details of the
 Lisp process. The current ``default'' connection is indicated with an
 asterisk.
 
 The commands available in the connection-list buffer are:
 
 @table @kbd
 @kbditem{RET, sly-goto-connection}
 Pop to the @acronym{REPL} buffer of the connection at point.
 
 @kbditem{d, sly-connection-list-make-default}
 Make the connection at point the ``default'' connection. It will then
 be used for commands in @code{sly-mode} source buffers.
 
 @kbditem{g, sly-update-connection-list}
 Update the connection list in the buffer.
 
 @kbditem{q, sly-temp-buffer-quit}
 Quit the connection list (kill buffer, restore window configuration).
 
 @kbditem{R, sly-restart-connection-at-point}
 Restart the Lisp process for the connection at point.
 
 @cmditem{sly-connect}
 Connect to a running Slynk server. With prefix argument, asks if all
 connections should be closed first.
 
 @cmditem{sly-disconnect}
 Disconnect all connections.
 
 @cmditem{sly-abort-connection}
 Abort the current attempt to connect.
 
 @end table
 
 @node Disassembly
 @section Disassembly commands
 
 @table @kbd
 
 @kbditem{C-c M-d, sly-disassemble-symbol}
 Disassemble the function definition of the symbol at point.
 
 @kbditem{C-c C-t, sly-toggle-trace-fdefinition}
 Toggle tracing of the function at point.  If invoked with a prefix
 argument, read additional information, like which particular method
 should be traced.
 
 @cmditem{sly-untrace-all}
 Untrace all functions.
 
 @end table
 
 @node Recovery
 @section Abort/Recovery commands
 
 @table @kbd
 @kbditem{C-c C-b, sly-interrupt}
 Interrupt Lisp (send @code{SIGINT}).
 
 @cmditem{sly-restart-inferior-lisp}
 Restart the @code{inferior-lisp} process.
 
 @kbditem{C-c ~, sly-mrepl-sync}
 Synchronize the current package and working directory from Emacs to
 Lisp.
 
 @cmditem{sly-cd}
 Set the current directory of the Lisp process.  This also
 changes the current directory of the REPL buffer.
 
 @cmditem{sly-pwd}
 Print the current directory of the Lisp process.
 
 @end table
 
 @node Temporary buffers
 @section Temporary buffers
 
 Some @SLY{} 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{sly-mode} in
 addition to any special mode of their own. This makes the usual
 @SLY{} commands available for describing symbols, looking up
 function definitions, and so on.
 
 Initial focus of those ``description'' buffers depends on the variable
 @code{sly-description-autofocus}. If @code{nil} (the default),
 description buffers do not receive focus automatically, and vice
 versa.
 
 @node Multi-threading
 @section Multi-threading
 
 If the Lisp system supports multi-threading, SLY spawns a new thread
 for each request, e.g., @kbd{C-x C-e} creates a new thread to evaluate
 the expression.  An exception to this rule are requests from the
 @REPL{}: all commands entered in the @REPL{} buffer are evaluated in a
 dedicated @REPL{} thread.
 
 You can see a listing of the threads for the current connection with
 the command @code{M-x sly-list-threads}, or @code{C-c C-x t}. This
 pops open a @code{*sly-threads*} buffer, where some keybindings to
 control threads are active, if you know what you are doing. The most
 useful is probably @kbd{k} to kill a thread, but type @kbd{C-h m} in
 that buffer to get a full listing.
 
 Some complications arise with multi-threading and special variables.
 Non-global special bindings are thread-local, e.g., changing the value
 of a let bound special variable in one thread has no effect on the
 binding of the variables with the same name in other threads.  This
 makes it sometimes difficult to change the printer or reader behaviour
 for new threads.  The variable
 @code{slynk:*default-worker-thread-bindings*} was introduced for such
 situations: instead of modifying the global value of a variable, add a
 binding the @code{slynk:*default-worker-thread-bindings*}.  E.g., with
 the following code, new threads will read floating point values as
 doubles by default:
 
 @example
 (push '(*read-default-float-format* . double-float)
        slynk:*default-worker-thread-bindings*).
 @end example
 
 @node SLY REPL and other special buffers
 @chapter SLY REPL and other special buffers
 
 @menu
 * REPL::
 * Inspector::
 * Debugger::
 * Trace Dialog::
 * Stickers::
 @end menu
 
 @node REPL
 @section SLY REPL: the ``top level''
 
 @cindex Listener
 
 @SLY{} uses a custom Read-Eval-Print Loop (@REPL{}, also known as a
 ``top level'', or listener):
 
 @itemize @bullet
 @item
 Conditions signalled in @REPL{} expressions are debugged with the
 integrated SLY debugger.
 @item
 Return values are interactive values (@pxref{Interactive objects})
 distinguished from printed output by separate Emacs faces (colors).
 @item
 Output from the Lisp process is inserted in the right place, and
 doesn't get mixed up with user input.
 @item
 Multiple @REPL{}s are possible in the same Lisp connection. This is
 useful for performing quick one-off experiments in different packages
 or directories without disturbing the state of an existing REPL.
 @item
 The REPL is a central hub for much of SLY's functionality, since
 objects examined in the inspector (@pxref{Inspector}), debugger
 (@pxref{Debugger}), and other extensions can be returned there.
 @end itemize
 
 Switching to the @REPL{} from anywhere in a @SLY{} buffer is a very
 common task. One way to do it is to find the @code{*sly-mrepl...*}
 buffer in Emacs’s buffer list, but there are other ways to reach a
 @REPL{}.
 
 @table @kbd
 @kbditem{C-c C-z, sly-mrepl}
 Start or select an existing main @REPL{} buffer.
 
 @cmditem{sly-mrepl-new}
 Start a new secondary @REPL session, prompting for a nickname.
 
 @kbditem{C-c ~, sly-mrepl-sync}
 Go to the REPL, switching package and default directory as
 applicable. More precisely the Lisp variables @code{*package*} and
 @code{*default-pathname-defaults*} are affected by the location
 where the command was issued. In a specific position of a @code{.lisp}
 file, for instance the current package and that file’s directory are
 chosen.
 @end table
 
 @menu
 * REPL commands::
 * REPL output::
 * REPL backreferences::
 @end menu
 
 @node REPL commands
 @subsection REPL commands
 
 @table @kbd
 
 @kbditem{RET, sly-mrepl-return}
 
 Evaluate the expression at prompt and return the result.
 
 @kbditem{TAB, sly-mrepl-indent-and-complete-symbol}
 
 Indent the current line. If line already indented complete the symbol
 at point (@pxref{Completion}). If there is not symbol at point show
 the argument list of the most recently enclosed function or macro in
 the minibuffer.
 
 @kbditem{M-p, sly-mrepl-previous-input-or-button}
 
 When at the current prompt, fetches previous input from the history,
 otherwise jumps to the previous interactive value (@pxref{Interactive
 objects}) representing a Lisp object.
 
 @kbditem{M-n, sly-mrepl-next-input-or-button}
 
 When at the current prompt, fetches next input from the history,
 otherwise jumps to the previous interactive value representing a
 Lisp object.
 
 @kbditem{C-r, isearch-backward}
 
 This regular Emacs keybinding, when invoked at the current @REPL{}
 prompt, starts a special transient mode turning the prompt into the
 string ``History-isearch backward''. While in this mode, the user can
 compose a string used to search backwards through history, and reverse
 the direction of search by pressing @kbd{C-s}. When invoked outside
 the current @REPL{} prompt, does a normal text search through the
 buffer contents.
 
 @kbditem{C-c C-b, sly-interrupt}
 
 Interrupts the current thread of the inferior-lisp process.
 
 For convenience this function is also bound to @kbd{C-c C-c}.
 
 @kbditem{C-M-p, sly-button-backward}
 
 Jump to the previous interactive value representing a Lisp object.
 
 @kbditem{C-M-n, sly-button-forward}
 
 Jump to the next interactive value representing a Lisp object.
 
 @kbditem{C-c C-o, sly-mrepl-clear-recent-output}
 
 Clear output between current and last REPL prompts, keeping results.
 
 @kbditem{C-c M-o, sly-mrepl-clear-repl}
 
 Clear the whole REPL of output and results.
 
 @end table
 
 @node REPL output
 @subsection REPL output
 
 REPLs wouldn’t be much use if they just took user input and didn’t
 print anything back. In @SLY{} the output printed to the REPL can
 come from four different places:
 
 @itemize @bullet
 
 @item
 A function’s return values. One line per return value is printed. Each
 line of printed text, called a @REPL{} result, persists after more
 expressions are evaluated, and is actually a button
 (@pxref{Interactive objects}) presenting the Lisp-side object. You
 can, for instance, inspect it (@pxref{Inspector}) or re-return it to
 right before the current command prompt so that you may conjure it up
 again, as usual in Lisp @REPL{}s, with the special variable @code{*}.
 
 In the @SLY{} @REPL{}, in addition to the @code{*}, @code{**}
 and @code{***} special variables, return values can also be accessed
 through a special backreference (@pxref{REPL backreferences}).
 
 @item
 An object may be copied to the REPL from some other part in @SLY{},
 such as the Inspector (@pxref{Inspector}), Debugger
 (@pxref{Debugger}), etc. using the familiar @kbd{M-RET} binding, or by
 selecting ``Copy to REPL'' from the context menu of an interactive
 object. Aside from not having been produced by the evaluation of a
 Lisp form in the @REPL{}, these objects behaves exactly like a @REPL{}
 result.
 
 @item
 The characters printed to the standard Lisp streams
 @code{*standard-output*}, @code{*error-output*}
 and @code{*trace-output*} as a @emph{synchronous} and direct result of
 the evaluation of an expression in the @REPL{}.
 
 @item
 The characters printed to the standard Lisp streams
 @code{*standard-output*}, @code{*error-output*} and
 @code{*trace-output*} printed, perhaps @emph{asynchronously},
 from others threads, for instance. This feature is optional and
 controlled by the variable @code{SLYNK:*GLOBALLY-REDIRECT-IO*}.
 @end itemize
 
 @noindent
 For advanced users, there are some Lisp-side Slynk variables affecting
 the way Slynk transmits @REPL{} output to @SLY{}.
 
 @table @code
 @item @code{SLYNK:*GLOBALLY-REDIRECT-IO*}
 
 This variable controls the global redirection of the the standard
 streams (@code{*standard-output*}, etc) to the @REPL{} in Emacs. The
 default value is @code{:started-from-emacs}, which means that
 redirection should only take place upon @code{M-x sly} invocations.
 When @code{t}, global redirection happens even for sessions started with
 @code{M-x sly-connect}, meaning output may be diverted from wherever
 you started the Lisp server originally.
 
 When @code{NIL} these streams are only temporarily redirected to Emacs
 using dynamic bindings while handling requests, meaning you only see
 output caused by the commands you issued to the REPL.
 
 Note that @code{*standard-input*} is currently never globally redirected
 into Emacs, because it can interact badly with the Lisp's native @REPL{}
 by having it try to read from the Emacs one.
 
 Also note that secondary @REPL{}s (those started with
 @kbd{sly-mrepl-new}) don’t receive any redirected output.
 
 @item @code{SLYNK:*USE-DEDICATED-OUTPUT-STREAM*}
 
 This variable controls whether to use a separate socket solely for Lisp
 to send printed output to Emacs through, which is more efficient than
 sending the output in protocol messages to Emacs.
 
 The default value is @code{:started-from-emacs}, which means that the
 socket should only be established upon @code{M-x sly} invocations.  When
 @code{t}, it's established even for sessions started with @code{M-x
 sly-connect}.  When @code{NIL} usual protocol messages are used for
 sending input to the @REPL{}.
 
 Notice that using a dedicated output stream makes it more difficult to
 communicate to a Lisp running on a remote host via SSH
 (@pxref{Connecting to a remote Lisp}).  If you connect via @code{M-x
 sly-connect}, the default @code{:started-from-emacs} value should ensure
 this isn't a problem.
 
 @item @code{SLYNK:*DEDICATED-OUTPUT-STREAM-PORT*}
 
 When @code{*USE-DEDICATED-OUTPUT-STREAM*} is @code{t} the stream will
 be opened on this port. The default value, @code{0}, means that the
 stream will be opened on some random port.
 
 @item @code{SLYNK:*DEDICATED-OUTPUT-STREAM-BUFFERING*}
 
 For efficiency, some Lisps backends wait until a certain conditions
 are met in a Lisp character stream before flushing that stream’s
 contents, thus sending it to the @SLY{} @REPL{}. Be advised that this
 sometimes works poorly on some implementations, so it’s probably best
 to leave alone. Possible values are @code{nil} (no
 buffering), @code{t} (enable buffering) or @code{:line} (enable
 buffering on EOL)
 @end table
 
 @node REPL backreferences
 @subsection REPL backreferences
 
 In a regular Lisp REPL, the objects produced by evaluating expressions
 at the command prompt can usually be referenced in future commands
 using the special variables @code{*}, @code{**} and @code{***}. This
 is also true of the @SLY{} @REPL{}, but it also provides a different
 way to re-conjure these objects through a special Lisp reader macro
 character available only in the REPL. The macro character, which
 is @code{#v} by default takes, in a terse syntax, two indexes
 specifying the precise objects in all of the @SLY{} @REPL{}’s recorded
 history.
 
 Consider this fragment of a REPL session:
 
 @example
 ; Cleared REPL history
 CL-USER> (values 'a 'b 'c)
 A
 B
 C
 CL-USER> (list #v0)
 (A)
 CL-USER> (list #v0:1 #v0:2)
 (B C)
 CL-USER> (append #v1:0 #v2:0)
 (A B C)
 CL-USER>
 @end example
 
 @noindent
 Admittedly, while useful, this doesn’t seem terribly easy to use at
 first sight. There are a couple of reasons, however, that should make
 it worth considering:
 
 @itemize @bullet
 @item
 Backreference annotation and highlighting
 
 As soon as the @SLY{} @REPL{} detects that you have pressed @code{#v},
 all the @REPL{} results that can possibly be referenced are
 temporarily annotated on their left with two special numbers. These
 numbers are in the syntax accepted by the @code{#v} macro-character,
 namely @code{#vENTRY-IDX:VALUE-IDX}.
 
 Furthermore, as soon as you type a number for @code{ENTRY-IDX}, only
 that entries values remain highlighted. Then, as you finish the entry
 with @code{VALUE-IDX}, only that exact object remains highlighted. If
 you make a mistake (say, by typing a letter or an invalid number)
 while composing @code{#v} syntax, @SLY{} lets you know by painting the
 backreference red.
 
 Highlighting also happens when you place the cursor over existing
 valid @code{#v} expressions.
 
 @item
 Returning functions calls
 
 An experimental feature in @SLY{} allows copying @emph{function calls}
 to the @REPL{} from the Debugger (@pxref{Debugger}) and the Trace
 Dialog (@pxref{Trace Dialog}). In those buffers, pressing
 keybinding @kbd{M-S-RET} over objects that represent function calls
 will copy the @emph{call}, and not the object, to the @REPL{}. This
 works by first copying over the argument objects in order to the
 @REPL{} results, and then composing an input line that includes the
 called function's name and backreferences to those arguments
 (@pxref{REPL backreferences}).
 
 Naturally, this call isn't @emph{exactly} the same because it doesn’t
 evaluate in the same dynamic environment as the original one. But it's
 a useful debug technique because backreferences are stable
 @footnote{until you clear the @REPL{}’s output, that is}, so repeating
 that very same function call with the very same arguments is just a
 matter of textually copying the previous expression into the command
 prompt, no matter how far ago it happened. And that, in turn,
 is as easy as using @kbd{C-r} and some characters (@pxref{REPL
 commands}) to arrive and repeat the desired @REPL{} history entry.
 @end itemize
 
 @node Inspector
 @section The Inspector
 
 The @SLY{} inspector is a Emacs-based alternative to the
 standard @code{INSPECT} function. The inspector presents objects in
 Emacs buffers using a combination of plain text, hyperlinks to related
 objects.
 
 The inspector can easily be specialized for the objects in your own
 programs. For details see the @code{inspect-for-emacs} generic
 function in @file{slynk-backend.lisp}.
 
 @table @kbd
 
 @kbditem{C-c I, sly-inspect}
 Inspect the value of an expression entered in the minibuffer.
 
 @end table
 
 The standard commands available in the inspector are:
 
 @table @kbd
 
 @kbditem{RET, sly-inspector-operate-on-point}
 If point is on a value then recursively call the inspector on that
 value. If point is on an action then call that action.
 
 @kbditem{D, sly-inspector-describe-inspectee}
 Describe the slot at point.
 
 @kbditem{e, sly-inspector-eval}
 Evaluate an expression in the context of the inspected object. The
 variable @code{*} will be bound to the inspected object.
 
 @kbditem{v, sly-inspector-toggle-verbose}
 Toggle between verbose and terse mode. Default is determined by
 `slynk:*inspector-verbose*'.
 
 @kbditem{l, sly-inspector-pop}
 Go back to the previous object (return from @kbd{RET}).
 
 @kbditem{n, sly-inspector-next}
 The inverse of @kbd{l}. Also bound to @kbd{SPC}.
 
 @kbditem{g, sly-inspector-reinspect}
 Reinspect.
 
 @kbditem{h, sly-inspector-history}
 Show the previously inspected objects.
 
 @kbditem{q, sly-inspector-quit}
 Dismiss the inspector buffer.
 
 @kbditem{>, sly-inspector-fetch-all}
 Fetch all inspector contents and go to the end.
 
 @kbditem{M-RET, sly-mrepl-copy-part-to-repl}
 Store the value under point in the variable `*'.  This can
 then be used to access the object in the REPL.
 
 @kbditempair{TAB, S-TAB, forward-button, backward-button}
 
 Jump to the next and previous inspectable object respectively.
 
 @end table
 
 @node Debugger
 @section The SLY-DB Debugger
 
 @cindex Debugger
 
 @SLY{} has a custom Emacs-based debugger called @SLY-DB{}. Conditions
 signalled in the Lisp system invoke @SLY-DB{} in Emacs by way of the
 Lisp @code{*DEBUGGER-HOOK*}.
 
 @SLY-DB{} pops up a buffer when a condition is signalled. The buffer
 displays a description of the condition, a list of restarts, and a
 backtrace. Commands are offered for invoking restarts, examining the
 backtrace, and poking around in stack frames.
 
 @menu
 * Examining frames::
 * Restarts::
 * Frame Navigation::
 * Miscellaneous::
 @end menu
 
 @node Examining frames
 @subsection Examining frames
 
 Commands for examining the stack frame at point.
 
 @table @kbd
 @kbditem{t, sly-db-toggle-details}
 Toggle display of local variables and @code{CATCH} tags.
 
 @kbditem{v, sly-db-show-frame-source}
 View the frame's current source expression. The expression is
 presented in the Lisp source file's buffer.
 
 @kbditem{e, sly-db-eval-in-frame}
 Evaluate an expression in the frame. The expression can refer to the
 available local variables in the frame.
 
 @kbditem{d, sly-db-pprint-eval-in-frame}
 Evaluate an expression in the frame and pretty-print the result in a
 temporary buffer.
 
 @kbditem{D, sly-db-disassemble}
 Disassemble the frame's function. Includes information such as the
 instruction pointer within the frame.
 
 @kbditem{i, sly-db-inspect-in-frame}
 Inspect the result of evaluating an expression in the frame.
 
 @kbditem{C-c C-c, sly-db-recompile-frame-source}
 Recompile frame. @kbd{C-u C-c C-c} for recompiling with maximum debug settings.
 
 @end table
 
 @node Restarts
 @subsection Invoking restarts
 
 @table @kbd
 @kbditem{a, sly-db-abort}
 Invoke the @code{ABORT} restart.
 
 @anchor{sly-db-quit}
 @kbditem{q, sly-db-quit}
 ``Quit'' -- For @SLY{} evaluation requests, invoke a restart which
 restores to a known program state. For errors in other threads,
 @xref{*SLY-DB-QUIT-RESTART*}.
 
 @kbditem{c, sly-db-continue}
 Invoke the @code{CONTINUE} restart.
 
 @kbditem{0 ... 9, sly-db-invoke-restart-n}
 Invoke a restart by number.
 @end table
 
 Restarts can also be invoked by pressing @kbd{RET} or @kbd{Mouse-2} on
 them in the buffer.
 
 @node Frame Navigation
 @subsection Navigating between frames
 
 @table @kbd
 @kbditempair{n,p,sly-db-down,sly-db-up}
 Move between frames.
 
 @kbditempair{M-n, M-p, sly-db-details-down, sly-db-details-up}
 Move between frames ``with sugar'': hide the details of the original
 frame and display the details and source code of the next. Sugared
 motion makes you see the details and source code for the current frame
 only.
 
 @kbditem{>, sly-db-end-of-backtrace}
 Fetch the entire backtrace and go to the last frame.
 
 @kbditem{<, sly-db-beginning-of-backtrace}
 Go to the first frame.
 
 @end table
 
 @node Miscellaneous
 @subsection Miscellaneous Commands
 
 @table @kbd
 @kbditem{r, sly-db-restart-frame}
 Restart execution of the frame with the same arguments it was
 originally called with. (This command is not available in all
 implementations.)
 
 @kbditem{R, sly-db-return-from-frame}
 Return from the frame with a value entered in the minibuffer. (This
 command is not available in all implementations.)
 
 
 @kbditem{B, sly-db-break-with-default-debugger}
 Exit @SLY-DB{} and debug the condition using the Lisp system's default
 debugger.
 
 @kbditem{C, sly-db-inspect-condition}
 Inspect the condition currently being debugged.
 
 @kbditem{:, sly-interactive-eval}
 Evaluate an expression entered in the minibuffer.
 @kbditem{A, sly-db-break-with-system-debugger}
 Attach debugger (e.g. gdb) to the current lisp process.
 
 @end table
 
 @node Trace Dialog
 @section Trace Dialog
 
 The @SLY{} Trace Dialog, in package @code{sly-trace-dialog}, is a
 tracing facility, similar to Common Lisp's @code{trace}, but
 interactive rather than purely textual.
 
 You use it just like you would regular @code{trace}: after tracing a
 function, calling it causes interesting information about that
 particular call to be reported.
 
 However, instead of printing the trace results to the
 the @code{*trace-output*} stream (usually the REPL), the @SLY{} Trace
 Dialog collects and stores them in your Lisp environment until, on
 user's request, they are fetched into Emacs and displayed in a
 dialog-like interactive view.
 
 After starting up @SLY{}, @SLY{}'s Trace Dialog installs
 a @emph{Trace} menu in the menu-bar of any @code{sly-mode} buffer and
 adds two new commands, with respective key-bindings:
 
 @table @kbd
 @kbditem{C-c C-t, sly-trace-dialog-toggle-trace}
 If point is on a symbol name, toggle tracing of its function
 definition. If point is not on a symbol, prompt user for a function.
 
 With a @kbd{C-u} prefix argument, and if your lisp implementation
 allows it, attempt to decipher lambdas, methods and other complicated
 function signatures.
 
 The function is traced for the @SLY{} Trace Dialog only, i.e. it is
 not found in the list returned by Common Lisp's @code{trace}.
 
 @kbditem{C-c T, sly-trace-dialog}
 Pop to the interactive Trace Dialog buffer associated with the
 current connection (@pxref{Multiple connections}).
 @end table
 
 @page
 Consider the (useless) program:
 
 @example
 (defun foo (n) (if (plusp n) (* n (bar (1- n))) 1))
 (defun bar (n) (if (plusp n) (* n (foo (1- n))) 1))
 @end example
 
 After tracing both @code{foo} and @code{bar} with @kbd{C-c M-t},
 calling call @code{(foo 2)} and moving to the trace dialog with
 @kbd{C-c T}, we are presented with this buffer.
 
 @example
 Traced specs (2)                                  [refresh]
                                                   [untrace all]
   [untrace] common-lisp-user::bar
   [untrace] common-lisp-user::foo
 
 Trace collection status (3/3)                     [refresh]
                                                   [clear]
 
    0 - common-lisp-user::foo
      | > 2
      | < 2
    1 `--- common-lisp-user::bar
         | > 1
         | < 1
    2    `-- common-lisp-user::foo
              > 0
              < 1
 @end example
 
 The dialog is divided into sections displaying the functions already
 traced, the trace collection progress and the actual trace tree that
 follow your program's logic. The most important key-bindings in this
 buffer are:
 
 @table @kbd
 @kbditem{g, sly-trace-dialog-fetch-status}
 Update information on the trace collection and traced specs.
 @kbditem{G, sly-trace-dialog-fetch-traces}
 Fetch the next batch of outstanding (not fetched yet) traces. With a
 @kbd{C-u} prefix argument, repeat until no more outstanding traces.
 @kbditem{C-k, sly-trace-dialog-clear-fetched-traces}
 Prompt for confirmation, then clear all traces, both fetched and
 outstanding.
 @end table
 
 The arguments and return values below each entry are interactive
 buttons. Clicking them opens the inspector
 (@pxref{Inspector}). Invoking @kbd{M-RET}
 (@code{sly-trace-dialog-copy-down-to-repl}) returns them to the REPL
 for manipulation (@pxref{REPL}). The number left of each entry
 indicates its absolute position in the calling order, which might
 differ from display order in case multiple threads call the same
 traced function.
 
 @code{sly-trace-dialog-hide-details-mode} hides arguments and return
 values so you can concentrate on the calling logic. Additionally,
 @code{sly-trace-dialog-autofollow-mode} will automatically
 display additional detail about an entry when the cursor moves over
 it.
 
 @node Stickers
 @section Stickers
 
 @SLY{} Stickers, implemented as the @code{sly-stickers} contrib
 (@pxref{Extensions}), is a tool for ``live'' code annotations. It's an
 alternative to the @code{print} or @code{break} statements you add to
 your code when debugging.
 
 Contrary to these techniques, ``stickers'' are non-intrusive, meaning
 that saving your file doesn't save your debug code along with it.
 
 Here's the general workflow:
 
 @itemize @bullet
 @item
 In Lisp source files, using @kbd{C-c C-s C-s} or @code{M-x
 sly-stickers-dwim} places a sticker on any Lisp form. Stickers can
 exist inside other stickers.
 
 @*@image{images/stickers-1-placed-stickers,350pt}@*
 
 @item
 Stickers are ``armed'' when a definition or a file is compiled with the
 familiar @kbd{C-c C-c} (@code{M-x sly-compile-defun}) or @kbd{C-c C-k}
 (@code{M-x sly-compile-file}) commands. An armed sticker changes color from
 the default grey background to a blue background.
 
 @*@image{images/stickers-2-armed-stickers,350pt}@*
 
 @end itemize
 
 From this point on, when the Lisp code is executed, the results of
 evaluating the underlying forms are captured in the Lisp
 side. Stickers help you examine your program's behaviour in three
 ways:
 @enumerate
 @item
 @kbd{C-c C-s C-r}
 (or @code{M-x sly-stickers-replay}) interactively walks the user
 through recordings in the order that they occurred. In the
 created @code{*sly-stickers-replay*} buffer, type @kbd{h} for a list
 of keybindings active in that buffer.
 
 @*@image{images/stickers-3-replay-stickers,350pt}@*
 
 @item
 To step through stickers as your code is executed, ensure that
 ``breaking stickers'' are enabled via @code{M-x
 sly-stickers-toggle-break-on-stickers}.  Whenever a sticker-covered
 expression is reached, the debugger comes up with useful restarts and
 interactive for the values produced.  You can tweak this behaviour by
 setting the Lisp-side variable
 @code{SLYNK-STICKERS:*BREAK-ON-STICKERS*} to a list with the
 elements @code{:before} and @code{:after}, making @SLY{} break before a
 sticker, after it, or both.
 
 @*@image{images/stickers-4-breaking-stickers,350pt}@*
 
 @item
 @kbd{C-c C-s S} (@code{M-x sly-stickers-fetch}) populates the sticker
 overlay with the latest captured results, called ``recordings''. If a sticker
 has captured any recordings, it will turn green, otherwise it will turn
 red. A sticker whose Lisp expression has caused a non-local exit, will
 be also be marked with a special face.
 
 @*@image{images/stickers-5-fetch-recordings,350pt}@*
 
 @end enumerate
 
 At any point, stickers can be removed with the
 same @code{sly-stickers-dwim} keybinding, by placing the cursor at the
 beginning of a sticker. Additionally adding prefix arguments
 to @code{sly-stickers-dwim} increase its scope, so @kbd{C-u C-c C-s
 C-s} will remove all stickers from the current function and @kbd{C-u
 C-u C-c C-s C-s} will remove all stickers from the current file.
 
 Stickers can be nested inside other stickers, so it is possible to
 record the value of an expression inside another expression which is
 also annotated.
 
 Stickers are interactive parts just like any other part in @SLY{} that
 represents Lisp-side objects, so they can be inspected and returned to
 the REPL, for example. To move through the stickers with the keyboard
 use the existing keybindings to move through compilation
 notes (@kbd{M-p} and @kbd{M-n}) or use @kbd{C-c C-s p} and @kbd{C-c C-s
 n} (@code{sly-stickers-prev-sticker} and
 @code{sly-stickers-next-sticker}).
 
 There are some caveats when using @SLY{} Stickers:
 
 @itemize
 @item
 Stickers on unevaluated forms (such as @code{let} variable bindings, or
 other constructs) are rejected, though the function is still compiled as
 usual. To let the user know about this, these stickers remain grey, and are
 marked as ``disarmed''. A message also appears in the echo area.
 @item
 Stickers placed on expressions inside backquoted expressions in macros
 are always armed, even though they may come to provoke a runtime error
 when the macro's expansion is run. Think of this when setting a sticker
 inside a macro definition.
 @end itemize
 
 @node Customization
 @chapter Customization
 
 @menu
 * Emacs-side::
 * Lisp-side customization::
 @end menu
 
 @node Emacs-side
 @section Emacs-side
 
 @menu
 * Keybindings::
 * Keymaps::
 * Defcustom variables::
 * Hooks::
 @end menu
 
 @node Keybindings
 @subsection Keybindings
 
 In general we try to make our key bindings fit with the overall Emacs
 style.
 
 We never bind @kbd{C-h} anywhere in a key sequence.  This is because
 Emacs has a built-in default so that typing a prefix followed
 by @kbd{C-h} will display all bindings starting with that prefix,
 so @kbd{C-c C-d C-h} will actually list the bindings for all
 documentation commands.  This feature is just a bit too useful to
 clobber!
 
 @quotation
 @i{``Are you deliberately spiting Emacs's brilliant online help facilities? The gods will be angry!''}
 @end quotation
 
 @noindent This is a brilliant piece of advice. The Emacs online help facilities
 are your most immediate, up-to-date and complete resource for keybinding
 information. They are your friends:
 
 @table @kbd
 @kbdanchorc{C-h k <key>, describe-key, ``What does this key do?''}
 Describes current function bound to @kbd{<key>} for focus buffer.
 
 @kbdanchorc{C-h b, describe-bindings, ``Exactly what bindings are available?''}
 Lists the current key-bindings for the focus buffer.
 
 @kbdanchorc{C-h m, describe-mode, ``Tell me all about this mode''}
 Shows all the available major mode keys, then the minor mode keys, for
 the modes of the focus buffer.
 
 @kbdanchorc{C-h l, view-lossage, ``Woah@comma{} what key chord did I just do?''}
 Shows you the literal sequence of keys you've pressed in order.
 
 @c <key> is breaks links PDF, despite that it's not l it's C-h
 @c @kbdanchorc{ <key> l, , ``What starts with?''}
 @c Lists all keybindings that begin with @code{<key>} for the focus buffer mode.
 
 
 @end table
 
 @anchor{Emacs Init File}
 For example, you can add one of the following to your Emacs init file
 (usually @file{~/.emacs} or @file{~/.emacs.d/init.el}, but @pxref{Init
 File,Init File, Emacs Init File, emacs, The Emacs Manual}).
 
 @example
 (eval-after-load 'sly
   `(define-key sly-prefix-map (kbd "M-h") 'sly-documentation-lookup))
 @end example
 
 @SLY{} comes bundled with many extensions (called ``contribs'' for
 historical reasons, @pxref{Extensions}) which you can customize just
 like @SLY{}'s code. To make @kbd{C-c C-c} clear the last REPL prompt's
 output, for example, use
 
 @example
 (eval-after-load 'sly-mrepl
    `(define-key sly-mrepl-mode-map (kbd "C-c C-k")
                 'sly-mrepl-clear-recent-output))
 @end example
 
 @node Keymaps
 @subsection Keymaps
 
 Emacs’s keybindings ``live'' in keymap variables. To customize a
 particular binding and keep it from trampling on other important keys
 you should do it in one of @SLY{}'s keymaps. The following
 non-exhaustive list of @SLY{}-related keymaps is just a reference: the
 manual will go over each associated functionality in detail.
 
 @table @code
 
 @item sly-doc-map
 
 Keymap for documentation commands (@pxref{Documentation}) in
 @SLY{}-related buffers, accessible by the @kbd{C-c C-d} prefix.
 
 @item sly-who-map
 
 Keymap for cross-referencing (``who-calls'') commands
 (@pxref{Cross-referencing}) in @SLY{}-related buffers, accessible by
 the @kbd{C-c C-w} prefix.
 
 @item sly-selector-map
 
 A keymap for @SLY{}-related functionality that should be available in
 globally in all Emacs buffers (not just @SLY{}-related buffers).
 
 @item sly-mode-map
 
 A keymap for functionality available in all @SLY{}-related buffers.
 
 @item sly-editing-mode-map
 
 A keymap for @SLY{} functionality available in Lisp source files.
 
 @item sly-popup-buffer-mode-map
 
 A keymap for functionality available in the temporary ``popup''
 buffers that @SLY{} displays (@pxref{Temporary buffers})
 
 @item sly-apropos-mode-map
 
 A keymap for functionality available in the temporary @SLY{}
 ``apropos'' buffers (@pxref{Documentation}).
 
 @item sly-xref-mode-map
 
 A keymap for functionality available in the temporary @code{xref}
 buffers used by cross-referencing commands
 (@pxref{Cross-referencing}).
 
 @item sly-macroexpansion-minor-mode-map
 
 A keymap for functionality available in the temporary buffers used for
 macroexpansion presentation (@pxref{Macro-expansion}).
 
 @item sly-db-mode-map
 
 A keymap for functionality available in the debugger buffers used to
 debug errors in the Lisp process (@pxref{Debugger}).
 
 @item sly-thread-control-mode-map
 
 A keymap for functionality available in the @SLY{} buffers dedicated
 to controlling Lisp threads (@pxref{Multi-threading}).
 
 @item sly-connection-list-mode-map
 
 A keymap for functionality available in the @SLY{} buffers dedicated
 to managing multiple Lisp connections (@pxref{Multiple connections}).
 
 @item sly-inspector-mode-map
 
 A keymap for functionality available in the @SLY{} buffers dedicated
 to inspecting Lisp objects (@pxref{Inspector}).
 
 @item sly-mrepl-mode-map
 
 A keymap for functionality available in @SLY{}’s REPL buffers
 (@pxref{REPL}).
 
 @item sly-trace-dialog-mode-map
 
 A keymap for functionality available in @SLY{}’s ``Trace Dialog''
 buffers (@pxref{Trace Dialog}).
 
 @end table
 
 
 @node Defcustom variables
 @subsection Defcustom variables
 
 The Emacs part of @SLY{} can be configured with the Emacs
 @code{customize} system, just use @kbd{M-x customize-group sly
 RET}. Because the customize system is self-describing, we only cover a
 few important or obscure configuration options here in the manual.
 
 @table @code
 
 @item sly-truncate-lines
 The value to use for @code{truncate-lines} in line-by-line summary
 buffers popped up by @SLY{}. This is @code{t} by default, which
 ensures that lines do not wrap in backtraces, apropos listings, and so
 on. It can however cause information to spill off the screen.
 
 @anchor{sly-complete-symbol-function}
 @item sly-complete-symbol-function
 The function to use for completion of Lisp symbols. Two completion
 styles are available: @code{sly-simple-completions}
 and @code{sly-flex-completions} (@pxref{Completion}).
 
 @item sly-filename-translations
 This variable controls filename translation between Emacs and the Lisp
 system. It is useful if you run Emacs and Lisp on separate machines
 which don't share a common file system or if they share the filesystem
 but have different layouts, as is the case with @acronym{SMB}-based
 file sharing.
 
 @anchor{sly-net-coding-system}
 @cindex Unicode
 @cindex UTF-8
 @cindex ASCII
 @cindex LATIN-1
 @cindex Character Encoding
 @item sly-net-coding-system
 If you want to transmit Unicode characters between Emacs and the Lisp
 system, you should customize this variable.  E.g., if you use SBCL, you
 can set:
 @example
 (setq sly-net-coding-system 'utf-8-unix)
 @end example
 To actually display Unicode characters you also need appropriate
 fonts, otherwise the characters will be rendered as hollow boxes.  If
 you are using Allegro CL and GNU Emacs, you can also
 use @code{emacs-mule-unix} as coding system.  GNU Emacs has often
 nicer fonts for the latter encoding.  (Different encodings can be used
 for different Lisps, see @ref{Multiple Lisps}.)
 
 @item sly-keep-buffers-on-connection-close
 This variable holds a list of keywords indicating @SLY{} buffer types
 that should be kept around when a connection closes.  For example, if
 the variable's value includes @code{:mrepl} (which is the default),
 @REPL{} buffer is kept around while all other stale buffers (debugger,
 inspector, etc..) are automatically killed.
 
 @end table
 
 @node Hooks
 @subsection Hooks
 
 @table @code
 
 @item sly-mode-hook
 This hook is run each time a buffer enters @code{sly-mode}. It is
 most useful for setting buffer-local configuration in your Lisp source
 buffers. An example use is to enable @code{sly-autodoc-mode}
 (@pxref{Autodoc}).
 
 @anchor{sly-connected-hook}
 @item sly-connected-hook
 This hook is run when @SLY{} establishes a connection to a Lisp
 server. An example use is to pop to a new @REPL{}.
 
 @item sly-db-hook
 This hook is run after @SLY-DB{} is invoked. The hook functions are
 called from the @SLY-DB{} buffer after it is initialized. An example use
 is to add @code{sly-db-print-condition} to this hook, which makes all
 conditions debugged with @SLY-DB{} be recorded in the @REPL{} buffer.
 
 @end table
 
 @node Lisp-side customization
 @section Lisp-side (Slynk)
 
 The Lisp server side of @SLY{} (known as ``Slynk'') offers several
 variables to configure. The initialization file @file{~/.slynk.lisp}
 is automatically evaluated at startup and can be used to set these
 variables.
 
 @menu
 * Communication style::
 * Other configurables::
 @end menu
 
 @node Communication style
 @subsection Communication style
 
 The most important configurable is @code{SLYNK:*COMMUNICATION-STYLE*},
 which specifies the mechanism by which Lisp reads and processes
 protocol messages from Emacs. The choice of communication style has a
 global influence on @SLY{}'s operation.
 
 The available communication styles are:
 
 @table @code
 @item NIL
 This style simply loops reading input from the communication socket
 and serves @SLY{} protocol events as they arise. The simplicity
 means that the Lisp cannot do any other processing while under
 @SLY{}'s control.
 
 @item :FD-HANDLER
 This style uses the classical Unix-style ``@code{select()}-loop.''
 Slynk registers the communication socket with an event-dispatching
 framework (such as @code{SERVE-EVENT} in @acronym{CMUCL} and
 @acronym{SBCL}) and receives a callback when data is available. In
 this style requests from Emacs are only detected and processed when
 Lisp enters the event-loop. This style is simple and predictable.
 
 @item :SIGIO
 This style uses @dfn{signal-driven I/O} with a @code{SIGIO} signal
 handler. Lisp receives requests from Emacs along with a signal,
 causing it to interrupt whatever it is doing to serve the
 request. This style has the advantage of responsiveness, since Emacs
 can perform operations in Lisp even while it is busy doing other
 things. It also allows Emacs to issue requests concurrently, e.g. to
 send one long-running request (like compilation) and then interrupt
 that with several short requests before it completes. The
 disadvantages are that it may conflict with other uses of @code{SIGIO}
 by Lisp code, and it may cause untold havoc by interrupting Lisp at an
 awkward moment.
 
 @item :SPAWN
 This style uses multiprocessing support in the Lisp system to execute
 each request in a separate thread. This style has similar properties
 to @code{:SIGIO}, but it does not use signals and all requests issued
 by Emacs can be executed in parallel.
 
 @end table
 
 The default request handling style is chosen according to the
 capabilities of your Lisp system. The general order of preference is
 @code{:SPAWN}, then @code{:SIGIO}, then @code{:FD-HANDLER}, with
 @code{NIL} as a last resort. You can check the default style by
 calling @code{SLYNK-BACKEND::PREFERRED-COMMUNICATION-STYLE}. You can
 also override the default by setting
 @code{SLYNK:*COMMUNICATION-STYLE*} in your Slynk init file (@pxref{Lisp-side customization}).
 
 @node Other configurables
 @subsection Other configurables
 
 These Lisp variables can be configured via your @file{~/.slynk.lisp}
 file:
 
 @table @code
 
 @item SLYNK:*CONFIGURE-EMACS-INDENTATION*
 This variable controls whether indentation styles for
 @code{&body}-arguments in macros are discovered and sent to Emacs. It
 is enabled by default.
 
 @item SLYNK:*GLOBAL-DEBUGGER*
 When true (the default) this causes @code{*DEBUGGER-HOOK*} to be
 globally set to @code{SLYNK:SLYNK-DEBUGGER-HOOK} and thus for @SLY{}
 to handle all debugging in the Lisp image. This is for debugging
 multithreaded and callback-driven applications.
 
 @anchor{*SLY-DB-QUIT-RESTART*}
 @item SLYNK:*SLY-DB-QUIT-RESTART*
 This variable names the restart that is invoked when pressing @kbd{q}
 (@pxref{sly-db-quit}) in @SLY-DB{}. For @SLY{} evaluation requests this
 is @emph{unconditionally} bound to a restart that returns to a safe
 point. This variable is supposed to customize what @kbd{q} does if an
 application's thread lands into the debugger (see
 @code{SLYNK:*GLOBAL-DEBUGGER*}).
 @example
 (setf slynk:*sly-db-quit-restart* 'sb-thread:terminate-thread)
 @end example
 
 @item SLYNK:*BACKTRACE-PRINTER-BINDINGS*
 @itemx SLYNK:*MACROEXPAND-PRINTER-BINDINGS*
 @itemx SLYNK:*SLY-DB-PRINTER-BINDINGS*
 @itemx SLYNK:*SLYNK-PPRINT-BINDINGS*
 These variables can be used to customize the printer in various
 situations.  The values of the variables are association lists of
 printer variable names with the corresponding value.  E.g., to enable
 the pretty printer for formatting backtraces in @SLY-DB{}, you can use:
 
 @example
 (push '(*print-pretty* . t) slynk:*sly-db-printer-bindings*).
 @end example
 
 The fact that most @SLY{} output (in the @REPL{} for instance,
 @pxref{REPL}) uses @code{SLYNK:*SLYNK-PPRINT-BINDINGS*} may surprise you
 if you expected it to use a global setting for, say,
 @code{*PRINT-LENGTH*}.  The rationale for this decision is that output
 is a very basic feature of @SLY{}, and it should keep operating normally
 even if you (mistakenly) set absurd values for some @code{*PRINT-...*}
 variable.  You, of course, override this protection:
 
 @example
 (setq slynk:*slynk-pprint-bindings*
       (delete '*print-length*
               slynk:*slynk-pprint-bindings* :key #'car))
 @end example
 
 @item SLYNK:*STRING-ELISION-LENGTH*
 @itemx SLYNK:*STRING-ELISION-LENGTH*
 
 This variable controls the maximum length of strings before their pretty
 printed representation in the Inspector, Debugger, @REPL, etc is elided.
 Don't set this variable directly, create a binding for this variable
 in @code{SLYNK:*SLYNK-PPRINT-BINDINGS*} instead.
 
 @item SLYNK:*ECHO-NUMBER-ALIST*
 @itemx SLYNK:*PRESENT-NUMBER-ALIST*
 These variables hold function designators used for displaying numbers
 when SLY presents them in its interface.
 
 The difference between the two functions is that
 @code{*PRESENT-NUMBER-ALIST*}, if non-nil,
 overrides @code{*ECHO-NUMBER-ALIST*} in the context of the @REPL{}, Trace
 Dialog and Stickers (see @ref{REPL}, @ref{Trace Dialog} and
 @ref{Stickers}), while the latter is used for commands like @kbd{C-x
 C-e} or the inspector (see @ref{Evaluation}, @ref{Inspector}).
 
 If in doubt, use @code{*ECHO-NUMBER-ALIST*}.
 
 Both variables have the same structure: each element in the alist takes
 the form @code{(TYPE . FUNCTIONS)}, where @code{TYPE} is a type designator
 and @code{FUNCTIONS} is a list of function designators for displaying
 that number in SLY. Each function takes the number as a single argument
 and returns a string, or nil, if that particular representation is to be
 disregarded.
 
 Additionally if a given function chooses to return @code{t} as its
 optional second value, then all the remaining functions following it
 in the list are disregarded.
 
 For integer numbers, the default value of this variable holds function
 designators that echo an integer number in its binary, hexadecimal and
 octal representation. However, if your application is using integers
 to represent
 @uref{https://en.wikipedia.org/wiki/Unix_time,,Unix Epoch Times} you
 can use this function to display a human-readable time
 whenever you evaluate an integer.
 
 @example
 (defparameter *day-names* '("Monday" "Tuesday" "Wednesday"
                             "Thursday" "Friday" "Saturday"
                             "Sunday"))
 
 (defun fancy-unix-epoch-time (integer)
   "Format INTEGER as a Unix Epoch Time if within 10 years from now."
   (let ((now (get-universal-time))
         (tenyears (encode-universal-time 0 0 0 1 1 1910 0))
         (unix-to-universal
           (+ integer
              (encode-universal-time 0 0 0 1 1 1970 0))))
     (when (< (- now tenyears) unix-to-universal (+ now tenyears))
       (multiple-value-bind
             (second minute hour date month year day-of-week dst-p tz)
           (decode-universal-time unix-to-universal)
         (declare (ignore dst-p))
         (format nil "~2,'0d:~2,'0d:~2,'0d on ~a, ~d/~2,'0d/~d (GMT~@@d)"
                 hour minute second (nth day-of-week *day-names*)
                 month date year (- tz))))))
 
 (pushnew 'fancy-unix-epoch-time
          (cdr (assoc 'integer slynk:*echo-number-alist*)))
 
 42 ; => 42 (6 bits, #x2A, #o52, #b101010)
 1451404675 ; => 1451404675 (15:57:55 on Tuesday, 12/29/2015 (GMT+0), 31 bits, #x5682AD83)
 @end example
 
 @item SLYNK-APROPOS:*PREFERRED-APROPOS-MATCHER*
 This variable holds a function used for performing apropos searches. It
 defaults to @code{SLYNK-APROPOS:MAKE-FLEX-MATCHER}, but can also be set
 to @code{SLYNK-APROPOS:MAKE-CL-PPCRE-MATCHER} (to use a regex-able
 matcher) or @code{SLYNK-APROPOS:MAKE-PLAIN-MATCHER}, for example.
 
 @item SLYNK:*LOG-EVENTS*
 Setting this variable to @code{t} causes all protocol messages
 exchanged with Emacs to be printed to @code{*TERMINAL-IO*}. This is
 useful for low-level debugging and for observing how @SLY{} works
 ``on the wire.'' The output of @code{*TERMINAL-IO*} can be found in
 your Lisp system's own listener, usually in the buffer
 @code{*inferior-lisp*}.
 
 @end table
 
 @node Tips and Tricks
 @chapter Tips and Tricks
 
 @menu
 * Connecting to a remote Lisp::
 * Loading Slynk faster::
 * Auto-SLY::
 * REPLs and game loops::
 * Controlling SLY from outside Emacs::
 @end menu
 
 @node Connecting to a remote Lisp
 @section Connecting to a remote Lisp
 
 One of the advantages of the way @SLY{} is implemented is that we can
 easily run the Emacs side (@code{sly.el} and friends) on one machine
 and the Lisp backend (Slynk) on another. The basic idea is to start up
 Lisp on the remote machine, load Slynk and wait for incoming @SLY{}
 connections. On the local machine we start up Emacs and tell @SLY{} to
 connect to the remote machine. The details are a bit messier but the
 underlying idea is that simple.
 
 @menu
 * Setting up the Lisp image::
 * Setting up Emacs::
 * Setting up pathname translations::
 @end menu
 
 @node Setting up the Lisp image
 @subsection Setting up the Lisp image
 
 The easiest way to load Slynk ``standalone'' (i.e. without
 having @code{M-x sly} start a Lisp that is subsidiary to a particular
 Emacs), is to load the ASDF system definition for Slynk.
 
 Make sure the path to the directory containing Slynk's @code{.asd}
 file is in @code{ASDF:*CENTRAL-REGISTRY*}. This file lives in
 the @code{slynk} subdirectory of @SLY{}. Type:
 
 @example
 (push #p"/path/to/sly/slynk/" ASDF:*CENTRAL-REGISTRY*)
 (asdf:require-system :slynk)
 @end example
 
 inside a running Lisp image@footnote{@SLY{} also SLIME's old-style
 @code{slynk-loader.lisp} loader which does the same thing, but ASDF is preferred}.
 
 Now all we need to do is startup our Slynk server. A working example
 uses the default settings:
 
 @example
 (slynk:create-server)
 @end example
 
 This creates a ``one-connection-only'' server on port 4005 using the
 preferred communication style for your Lisp system. The following
 parameters to @code{slynk:create-server} can be used to change that
 behaviour:
 
 @table @code
 @item :PORT
 Port number for the server to listen on (default: 4005).
 @item :DONT-CLOSE
 Boolean indicating if the server will continue to accept connections
 after the first one (default: @code{NIL}). For ``long-running'' Lisp processes
 to which you want to be able to connect from time to time,
 specify @code{:dont-close t}
 @item :STYLE
 See @xref{Communication style}.
 @end table
 
 So a more complete example will be
 @example
 (slynk:create-server :port 4006  :dont-close t)
 @end example
 
 Finally, since section we're going to be tunneling our connection via
 @acronym{SSH}@footnote{there is a way to connect without an SSH
 tunnel, but it has the side-effect of giving the entire world access
 to your Lisp image, so we're not going to talk about it} we'll only
 have one port open we must tell Slynk's REPL contrib (see @REPL{}) to
 not use an extra connection for output, which it will do by default.
 
 @example
 (setf slynk:*use-dedicated-output-stream* nil)
 @end example
 
 @footnote{Alternatively, a separate tunnel for the port set in
 @code{slynk:*dedicated-output-stream-port*} can also be used if a dedicated output
 is essential.}
 
 @node Setting up Emacs
 @subsection Setting up Emacs
 
 Now we need to create the tunnel between the local machine and the
 remote machine. Assuming a @acronym{UNIX} command-line, this can be
 done with:
 
 @example
 ssh -L4005:localhost:4005 youruser@@remote.example.com
 @end example
 
 This incantation creates a SSH tunnel between the port 4005 on our
 local machine and the port 4005 on the remote machine,
 where @code{youruser} is expected to have an account.  @footnote{By
 default Slynk listens for incoming connections on port 4005, had we
 passed a @code{:port} parameter to @code{slynk:create-server} we'd be
 using that port number instead}.
 
 Finally we start @SLY{} with @code{sly-connect} instead of the usual
 @code{sly}:
 
 @example
 M-x sly-connect RET RET
 @end example
 
 The @kbd{RET RET} sequence just means that we want to use the default
 host (@code{localhost}) and the default port (@code{4005}). Even
 though we're connecting to a remote machine the SSH tunnel fools Emacs
 into thinking it's actually @code{localhost}.
 
 @node Setting up pathname translations
 @subsection Setting up pathname translations
 
 One of the main problems with running slynk remotely is that Emacs
 assumes the files can be found using normal filenames. if we want
 things like @code{sly-compile-and-load-file} (@kbd{C-c C-k}) and
 @code{sly-edit-definition} (@kbd{M-.}) to work correctly we need to
 find a way to let our local Emacs refer to remote files.
 
 There are, mainly, two ways to do this. The first is to mount, using
 NFS or similar, the remote machine's hard disk on the local machine's
 file system in such a fashion that a filename like
 @file{/opt/project/source.lisp} refers to the same file on both
 machines. Unfortunately NFS is usually slow, often buggy, and not
 always feasible. Fortunately we have an ssh connection and Emacs'
 @code{tramp-mode} can do the rest.
 (See @inforef{Top, TRAMP User Manual,tramp}.)
 
 What we do is teach Emacs how to take a filename on the remote machine
 and translate it into something that tramp can understand and access
 (and vice versa). Assuming the remote machine's host name is
 @code{remote.example.com}, @code{cl:machine-instance} returns
 ``remote'' and we login as the user ``user'' we can use @code{sly-tramp}
 contrib to setup the proper translations by simply doing:
 
 @example
 (add-to-list 'sly-filename-translations
              (sly-create-filename-translator
               :machine-instance "remote"
               :remote-host "remote.example.com"
               :username "user"))
 @end example
 
 @node Loading Slynk faster
 @section Loading Slynk faster
 
 In this section, a technique to load Slynk faster on South Bank Common
 Lisp (SBCL) is presented.  Similar setups should also work for other
 Lisp implementations.
 
 A pre-canned solution that automates this technique was developed by
 @uref{https://gitlab.com/ambrevar/lisp-repl-core-dumper,Pierre
 Neidhardt}.
 
 For SBCL, we recommend that you create a custom core file with socket
 support and @acronym{POSIX} bindings included because those modules
 take the most time to load.  To create such a core, execute the
 following steps:
 
 @example
 shell$ sbcl
 * (mapc 'require '(sb-bsd-sockets sb-posix sb-introspect sb-cltl2 asdf))
 * (save-lisp-and-die "sbcl.core-for-sly")
 @end example
 
 After that, add something like this to your @file{~/.emacs} or
 @file{~/.emacs.d/init.el} (@pxref{Emacs Init File}):
 
 @lisp
 (setq sly-lisp-implementations '((sbcl ("sbcl" "--core"
       "sbcl.core-for-sly"))))
 @end lisp
 
 For maximum startup speed you can include the Slynk server directly in
 a core file.  The disadvantage of this approach is that the setup is a
 bit more involved and that you need to create a new core file when you
 want to update @SLY{} or @acronym{SBCL}.  The steps to execute are:
 
 @example
 shell$ sbcl
 * (load ".../sly/slynk-loader.lisp")
 * (slynk-loader:dump-image "sbcl.core-with-slynk")
 @end example
 
 @noindent
 Then add this to the Emacs initializion file:
 
 @anchor{init-example}
 @lisp
 (setq sly-lisp-implementations
       '((sbcl ("sbcl" "--core" "sbcl.core-with-slynk")
               :init (lambda (port-file _)
                       (format "(slynk:start-server %S)\n" port-file)))))
 @end lisp
 
 @node Auto-SLY
 @section Connecting to SLY automatically
 
 To make @SLY{} connect to your lisp whenever you open a lisp file
 just add this to your @file{~/.emacs} or
 @file{~/.emacs.d/init.el} (@pxref{Emacs Init File}):
 
 @example
 (add-hook 'sly-mode-hook
           (lambda ()
             (unless (sly-connected-p)
               (save-excursion (sly)))))
 @end example
 
 @node REPLs and game loops
 @section REPLs and ``Game Loops''
 
 When developing Common Lisp video games or graphical applications, a
 REPL (@pxref{REPL}) is just as useful as anywhere else.  But it is often
 the case that one needs to control exactly the timing of REPL requests
 and ensure they do not interfere with the ``game loop''.  In other
 situations, the choice of communication style (@pxref{Communication
 style}) to the Slynk server may invalidate simultaneous multi-threaded
 operation of REPL and game loop.
 
 Instead of giving up on the REPL or using a complicated solution, SLY's
 REPL can be built into your game loop by using a couple of Slynk Common
 Lisp functions, @code{SLYNK-MREPL:SEND-PROMPT} and
 @code{SLYNK:PROCESS-REQUESTS}.
 
 @example
 (defun my-repl-aware-game-loop ()
   (loop initially
           (princ "Starting our game")
           (slynk-mrepl:send-prompt)
         for i from 0
         do (with-simple-restart (abort "Skip rest of this game loop iteration")
              (when (zerop (mod i 10))
                (fresh-line)
                (princ "doing high-priority 3D game loop stuff"))
              (sleep 0.1)
              ;; When you're ready to serve a potential waiting 
              ;; REPL request, just do this non-blocking thing:
              (with-simple-restart (abort "Abort this game REPL evaluation")
                (slynk:process-requests t)))))
 @end example
 
 Note that this function is to be called @emph{from the REPL}, and will
 enter kind of ``sub-REPL'' inside it.  It'll likely ``just work'' in
 this situation.  However, if you need you need to call this from
 anywhere else (like, say, another thread), you must additionally arrange
 for the variable @code{SLYNK-API:*CHANNEL*} to be bound to the value it
 is bound to in whatever SLY REPL you wish to interact with your game.
 
 @node Controlling SLY from outside Emacs
 @section Controlling SLY from outside Emacs
 
 If your application has a non-SLY, non-Emacs user interface (graphical
 or otherwise), you can use it to exert some control over SLY
 functionality, such as its REPL (@pxref{REPL}) and inspector
 (@pxref{Inspector}).  This requires that you first set, in Emacs,
 variable @code{sly-enable-evaluate-in-emacs} to non-nil.  As the name
 suggests, it lets outside Slynk servers evaluate code in your Elisp
 runtime.  It is set to @code{nil} by default for security purposes.
 
 Once you've done that, you can
 call @code{SLYNK-MREPL:COPY-TO-REPL-IN-EMACS} from your CL code with
 some objects you'd like to manipulate in the REPL.  Then you can have
 this code run from some UI event handler:
 
 @example
 (lambda ()
   (slynk-mrepl:copy-to-repl-in-emacs
      (list 42 'foo)
      :blurb "Just a forty-two and a foo"))
 @end example
 
 And see those objects pop up in your REPL for inspection and
 manipulation.
 
 You can also use the functions @code{SLYNK:INSPECT-IN-EMACS},
 @code{SLYNK:ED-IN-EMACS}, and in general, any exported function ending
 in @code{IN-EMACS}.  See their docstrings for details.
 
 @node Extensions
 @chapter Extensions
 
 @menu
 * Loading and unloading::       More contribs::
 * More contribs::
 @end menu
 
 @cindex Contribs
 @cindex Contributions
 @cindex Plugins
 @cindex Extensions
 
 Extensions, also known as ``contribs'' are Emacs packages that extend
 @SLY{}’s functionality. Contrasting with its ancestor @SLIME{}
 (@pxref{Introduction}), most contribs bundled with @SLY{} are active
 by default, since they are a decent way to split @SLY{} into pluggable
 modules. The auto-documentation (@pxref{Autodoc}), trace (@pxref{Trace
 Dialog}) and Stickers (@pxref{Stickers}) are contribs enabled by
 default, for example.
 
 Usually, contribs differ from regular Emacs plugins in that they are
 partly written in Emacs-lisp and partly in Common Lisp. The former is
 usually the UI that queries the latter for information and then
 presents it to the user. @SLIME{} used to load all the contribs’
 Common Lisp code upfront, but @SLY{} takes care to loading these two
 parts at the correct time. In this way, developers can write
 third-party contribs that live independently of @SLY{} perhaps even in
 different code repositories. The @code{sly-macrostep} contrib
 (@uref{https://github.com/joaotavora/sly-macrostep}) is one such
 example.
 
 A special @code{sly-fancy} contrib package is the only one loaded by
 default. You might never want to fiddle with it (it is the one that
 contains the default extensions), but if you find that you don't like
 some package or you are having trouble with a package, you can modify
 your setup a bit.  Generally, you set the variable @code{sly-contribs}
 with the list of package-names that you want to use.  For example, a
 setup to load only the @code{sly-scratch} and @code{sly-mrepl}
 packages looks like:
 
 @example
 ;; @emph{Setup load-path and autoloads}
 (add-to-list 'load-path "~/dir/to/cloned/sly")
 (require 'sly-autoloads)
 
 ;; @emph{Set your lisp system and some contribs}
 (setq inferior-lisp-program "/opt/sbcl/bin/sbcl")
 (setq sly-contribs '(sly-scratch sly-mrepl))
 @end example
 
 After starting @SLY{}, the commands of both packages should be
 available.
 
 @node Loading and unloading
 @section Loading and unloading ``on the fly''
 
 We recommend that you setup the @code{sly-contribs}
 variable @emph{before} starting @SLY{} via @kbd{M-x sly}, but if you
 want to enable more contribs @emph{after} you that, you can set
 new @code{sly-contribs} variable to another value and call @code{M-x
 sly-setup} or @code{M-x sly-enable-contrib}. Note this though:
 
 @itemize @bullet
 @item
 If you've removed contribs from the list they won't be unloaded
 automatically.
 @item
 If you have more than one @SLY{} connection currently active, you must
 manually repeat the @code{sly-setup} step for each of them.
 @end itemize
 
 Short of restarting Emacs, a reasonable way of unloading contribs is
 by calling an Emacs Lisp function whose name is obtained by
 adding @code{-unload} to the contrib's name, for every contrib you
 wish to unload. So, to remove @code{sly-mrepl}, you must call
 @code{sly-mrepl-unload}. Because the unload function will only, if
 ever, unload the Emacs Lisp side of the contrib, you may also need to
 restart your lisps.
 
 @node More contribs
 @section More contribs
 
 @menu
 * TRAMP Support::
 * Scratch Buffer::
 @end menu
 
 @node TRAMP Support
 @subsection TRAMP
 
 @cindex TRAMP
 
 The package @code{sly-tramp} provides some functions to set up
 filename translations for TRAMP. (@pxref{Setting up pathname
 translations})
 
 @node Scratch Buffer
 @subsection Scratch Buffer
 
 @anchor{sly-scratch}
 The @SLY{} scratch buffer, in contrib package @code{sly-scratch},
 imitates Emacs' usual @code{*scratch*} buffer.
 If @code{sly-scratch-file} is set, it is used to back the scratch
 buffer, making it persistent. The buffer is like any other Lisp
 buffer, except for the command bound to @kbd{C-j}.
 
 @table @kbd
 
 @kbditem{C-j, sly-eval-print-last-expression}
 Evaluate the expression sexp before point and insert a printed
 representation of the return values into the current buffer.
 
 @cmditem{sly-scratch}
 Create a @file{*sly-scratch*} buffer. In this
 buffer you can enter Lisp expressions and evaluate them with
 @kbd{C-j}, like in Emacs's @file{*scratch*} buffer.
 
 @end table
 
 
 @node Credits
 @chapter Credits
 
 @emph{The soppy ending...}
 
 @unnumberedsec Hackers of the good hack
 
 @SLY{} is a fork of SLIME which is itself an Extension
 of @acronym{SLIM} by Eric Marsden. At the time of writing, the authors
 and code-contributors of @SLY{} are:
 
 @include contributors.texi
 
 ... not counting the bundled code from @file{hyperspec.el},
 @cite{CLOCC}, and the @cite{CMU AI Repository}.
 
 Many people on the @code{sly-devel} mailing list have made non-code
 contributions to @SLY{}. Life is hard though: you gotta send code to
 get your name in the manual. @code{:-)}
 
 @unnumberedsec Thanks!
 
 We're indebted to the good people of @code{common-lisp.net} for their
 hosting and help, and for rescuing us from ``Sourceforge hell.''
 
 Implementors of the Lisps that we support have been a great help. We'd
 like to thank the @acronym{CMUCL} maintainers for their helpful
 answers, Craig Norvell and Kevin Layer at Franz providing Allegro CL
 licenses for @SLY{} development, and Peter Graves for his help to
 get @SLY{} running with @acronym{ABCL}.
 
 Most of all we're happy to be working with the Lisp implementors
 who've joined in the @SLY{} development: Dan Barlow and Christophe
 Rhodes of @acronym{SBCL}, Gary Byers of OpenMCL, and Martin Simmons of
 LispWorks. Thanks also to Alain Picard and Memetrics for funding
 Martin's initial work on the LispWorks backend!
 
 @node Key Index
 @unnumbered Key (Character) Index
 @printindex ky
 
 @node Command Index
 @unnumbered Command and Function Index
 @printindex fn
 
 @node Variable Index
 @unnumbered Variable and Concept Index
 @printindex vr
 
 @bye
 Local Variables:
 paragraph-start: "@[a-zA-Z]+\\({[^}]+}\\)?[ \n]\\|[ ]*$"
 paragraph-separate: "@[a-zA-Z]+\\({[^}]+}\\)?[ \n]\\|[ ]*$"
 End:
 
 @c  LocalWords:  RET backreferences defun Autodoc autodoc minibuffer
 @c  LocalWords:  backreference