Image support documented in user manual

5 files changed, 43 insertions, 5 deletions

diff --git a/doc/geiser.texi b/doc/geiser.texi
index c0d3ef8..898bba6 100644
--- a/doc/geiser.texi
+++ b/doc/geiser.texi
@@ -9,7 +9,7 @@
 @copying
 This manual documents Geiser, an Emacs environment to hack in Scheme.
 
-Copyright @copyright{} 2010, 2011  Jose Antonio Ortega Ruiz
+Copyright @copyright{} 2010, 2011, 2012  Jose Antonio Ortega Ruiz
 
 @quotation
 Permission is granted to copy, distribute and/or modify this document
@@ -78,6 +78,7 @@ The REPL
 * Switching context::
 * Completion and error handling::
 * Autodoc and friends::
+* Seeing is believing::
 * Customization and tips::
 
 Between the parens
diff --git a/doc/img/repl-images.png b/doc/img/repl-images.png
new file mode 100644
index 0000000..7108e27
--- /dev/null
+++ b/doc/img/repl-images.png
diff --git a/doc/intro.texi b/doc/intro.texi
index 57e4fb5..00207cd 100644
--- a/doc/intro.texi
+++ b/doc/intro.texi
@@ -80,6 +80,9 @@ Rudimentary support for debugging (when the REPL provides a
 debugger) and error navigation.
 @item
 Support for multiple, simultaneous REPLs.
+@item
+Support for image display in those Schemes that treat them as first
+class values.
 @end itemize
 
 In the following pages, i'll try to explain what these features
diff --git a/doc/parens.texi b/doc/parens.texi
index b4df02e..3a6a0e0 100644
--- a/doc/parens.texi
+++ b/doc/parens.texi
@@ -440,9 +440,16 @@ way, but it also teleports you to REPL after the evaluation.
 region.  Again, there's an @i{and-go} version available,
 @code{geiser-eval-region-and-go}, bound to @kbd{C-c M-r}.
 
+@cindex evaluating images
+@cindex image display
 For all the commands above, the result of the evaluation is displayed in
 the minibuffer, unless it causes a (Scheme-side) error (@pxref{To err
-perchance to debug}).
+perchance to debug}), or, for schemes supporting them (such as Racket),
+the evaluation yields an image, in which case you'll see it in popping
+up in the Geiser debug buffer (if your Emacs runs under the auspices of
+a graphical toolkit), or via an external viewer if you set
+@c{geiser-image-viewer} to the path of an appropriate visualization
+program (see also @ref{Seeing is believing} for more on image support).
 
 At the risk of repeating myself, i'll remind you that all these
 evaluations will take place in the namespace of the module corresponding
diff --git a/doc/repl.texi b/doc/repl.texi
index 99b928c..560f3eb 100644
--- a/doc/repl.texi
+++ b/doc/repl.texi
@@ -1,4 +1,4 @@
-@node The REPL, Between the parens, Installation, Top
+@node The REPL
 @chapter The REPL
 @anchor{quick-start}
 If you've followed the instructions in @ref{Setting it up}, your Emacs is
@@ -11,6 +11,7 @@ ready, just come back here and proceed to the following sections.
 * Switching context::
 * Completion and error handling::
 * Autodoc and friends::
+* Seeing is believing::
 * Customization and tips::
 @end menu
 
@@ -211,7 +212,7 @@ the last prompt, @kbd{@key{TAB}} will move to the next error in the
 buffer, and you can use @kbd{@key{BACKTAB}} everywhere to go to the
 previous one.
 
-@node Autodoc and friends, Customization and tips, Completion and error handling, The REPL
+@node Autodoc and friends, Seeing is believing, Completion and error handling, The REPL
 @section Autodoc and friends
 
 Oftentimes, there's more you'll want to know about an identifier
@@ -274,7 +275,33 @@ will see, these commands are also available in Scheme buffers.  @kbd{M-.}
 also works for modules: if your point is on an unambiguous module name,
 the file where it's defined will be opened for you.
 
-@node Customization and tips,  , Autodoc and friends, The REPL
+@node Seeing is believing, Customization and tips, Autodoc and friends, The REPL
+@section Seeing is believing
+
+@cindex image support
+In schemes that support images as values (currently, that means Racket),
+the REPL will display them inline if you're using them in a
+graphics-aware Emacs.
+
+@imgc{repl-images}
+
+@cindex external image viewer
+@cindex image viewer
+For the terminal, images will appear as buttons: press return on them to
+invoke an external viewer (configurable via @code{geiser-image-viewer})
+that will show you the image at hand.  You can also ask for the same
+behaviour on all emacsen by customising
+@code{geiser-repl-inline-images-p} to @code{nil}.
+
+@cindex image cache
+Geiser keeps a cache of the last displayed images in the directory
+@code{geiser-image-cache-dir}, which defaults to the system's temp
+directory, with up to @code{geiser-image-cache-keep-last} files.  You
+can invoke the external image viewer on any of them with @command{M-x
+geiser-view-last-image}, which takes a prefix argument to indicate which
+image number you want, 0 corresponding to the newest one.
+
+@node Customization and tips,  , Seeing is believing, The REPL
 @section Customization and tips
 
 @cindex REPL customization