summaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
authorJose Antonio Ortega Ruiz <jao@gnu.org>2010-11-23 01:58:33 +0100
committerJose Antonio Ortega Ruiz <jao@gnu.org>2010-11-23 01:58:33 +0100
commit3b24e917fdfebc8df3fefbbcc747963eb4bbd126 (patch)
treea44d5f0cb47639d47bdb57f2233b2db5e5a878b7 /doc
parenta53249b83cdc0711f23b1b8860cd3582977230c6 (diff)
downloadgeiser-guile-3b24e917fdfebc8df3fefbbcc747963eb4bbd126.tar.gz
geiser-guile-3b24e917fdfebc8df3fefbbcc747963eb4bbd126.tar.bz2
Document browser improvements, and Racket using them
We have a new "manual lookup" command, and Racket now displays a doc browser buffer for help with a button activating it. In the process, we've cleaned-up a little mess in geiser-eval.el and geiser-doc.el, and refactored the affected Racket modules. Next in line is providing manual lookup for Guile.
Diffstat (limited to 'doc')
-rw-r--r--doc/cheat.texi3
-rw-r--r--doc/img/geiser-mode.pngbin62445 -> 37636 bytes
-rw-r--r--doc/img/repl-mod.pngbin29938 -> 30503 bytes
-rw-r--r--doc/parens.texi33
-rw-r--r--doc/repl.texi40
5 files changed, 47 insertions, 29 deletions
diff --git a/doc/cheat.texi b/doc/cheat.texi
index 108d5a2..f6e1924 100644
--- a/doc/cheat.texi
+++ b/doc/cheat.texi
@@ -137,6 +137,9 @@
@item C-c C-d C-d
@tab geiser-doc-symbol-at-point
@tab See documentation for symbol at point
+@item C-c C-d C-i
+@tab geiser-doc-lookup-manual
+@tab Lookup manual for symbol at point
@item C-c C-d C-m
@tab geiser-repl--doc-module
@tab See documentation for module
diff --git a/doc/img/geiser-mode.png b/doc/img/geiser-mode.png
index 6e6e564..799745c 100644
--- a/doc/img/geiser-mode.png
+++ b/doc/img/geiser-mode.png
Binary files differ
diff --git a/doc/img/repl-mod.png b/doc/img/repl-mod.png
index 9814b7e..1fee5f0 100644
--- a/doc/img/repl-mod.png
+++ b/doc/img/repl-mod.png
Binary files differ
diff --git a/doc/parens.texi b/doc/parens.texi
index 439e56c..c4aa228 100644
--- a/doc/parens.texi
+++ b/doc/parens.texi
@@ -278,10 +278,10 @@ controls how the current argument position is highlighted.
@subsubheading Other documentation commands
-Sometimes, autodoc won't provide enough information for you to
-understand what a function does. In those cases, you can ask Geiser to
-ask the running Scheme for further information on a given identifier or
-module.
+@anchor{doc-browser}Sometimes, autodoc won't provide enough information
+for you to understand what a function does. In those cases, you can ask
+Geiser to ask the running Scheme for further information on a given
+identifier or module.
@cindex documentation for symbol
@cindex docstrings, maybe
@@ -301,14 +301,29 @@ navigation commands available in that buffer, which you can discover by
means of its menu or via the good old @kbd{C-h m} command.
For Racket, which does not support docstrings out of the box, this
-command will invoke Racket's @code{help} procedure, thereby opening your
-configured web browser with the corresponding manual page for you to
-peruse.
+command will provide less information, but the documentation browser
+will display the corresponding contract when it's available.
You can also ask Geiser to display information about a module, in the
form of a list of its exported identifiers, using @kbd{C-c C-d C-m},
-exactly as you would do @ref{repl-mod,,in the REPL}. This commands works
-with all supported Schemes, no strings attached.
+exactly as you would do @ref{repl-mod,,in the REPL}.
+
+In both cases, the documentation browser will show a couple of buttons
+giving you access to further documentation. First, you'll see a button
+named @i{source}: pressing it you'll jump to the symbol's definition.
+The second button, dubbed @i{manual}, will open the scheme
+implementation's manual page for the symbol at hand. For Racket, that
+will open your web browser displaying the corresponding reference's page
+(using Emacs' @code{browser-url} command), while in Guile a lookup will
+be performed in the texinfo manual.
+
+@cindex opening manual pages
+You can also jump directly to the manual page for the symbol at point
+with the command @code{geiser-doc-lookup-manual}, bound to @kbd{C-c C-d
+i}.
+
+See also our @xref{Documentation browser,,cheat-sheet} for a list of
+navigation commands available in the documentation browser.
@node To eval or not to eval, To err perchance to debug, Documentation helpers, Between the parens
@section To eval or not to eval
diff --git a/doc/repl.texi b/doc/repl.texi
index ffb733b..a87c547 100644
--- a/doc/repl.texi
+++ b/doc/repl.texi
@@ -217,11 +217,26 @@ argument is a keyword argument, its name has ``#:'' as a prefix.
@cindex help on identifier
If that's not enough documentation for you, @kbd{C-c C-d d} will open a
-separate documentation buffer with help on the symbol at point. For some
-implementations (e.g. Racket), this separate buffer will actually be a
-web page displaying the corresponding page in the manual, while for
-implementations supporting docstrings (e.g. (you guessed it) Guile)
-it'll be a real Emacs buffer displaying that information.
+separate documentation buffer with help on the symbol at point. This
+buffer will contain implementation-specific information about the
+identifier (e.g., its docstring for Guile, or its contract, if any, for
+Racket), and a handy button to open the corresponding manual entry for
+the symbol, which will open an HTML page (for Racket) or the texinfo
+manual (for Guile).
+
+@cindex module exports
+@anchor{repl-mod} Geiser can also produce for you a list, classified by
+kind, of the identifiers exported by a given module: all you need to do
+is press @kbd{C-c C-d m}, and type or complete the desired module's
+name.
+
+@imgc{repl-mod}
+
+The list of exported bindings is shown, again, in a buffer belonging to
+Geiser's documentation browser, where you have at your disposal a bunch
+of navigation commands listed in @xref{Documentation browser,,our
+cheat-sheet}. We'll have a bit more to say about the documentation
+browser in @xref{doc-browser,,a later section}.
@cindex jump, at the REPL
If that's still not enough, Geiser can jump, via @kbd{M-.}, to the
@@ -232,21 +247,6 @@ 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.
-@cindex module exports
-@anchor{repl-mod}
-Finally, Geiser can produce for you a list, classified by kind, of the
-identifiers exported by a given module: all you need to do is press
-@kbd{C-c C-d m}, and type or complete the desired module's name.
-
-@imgc{repl-mod}
-
-The list of exported bindings is shown in a buffer belonging to Geiser's
-documentation browser, of which more details are given in forthcoming
-sections (but just perusing its associated key bindings, by any of the
-methods we've already mentioned, will give you enough information to use
-it). Racketeers will be pleased (i hope) to note that contracts are part
-of the information displayed.
-
@node Customization and tips, , Autodoc and friends, The REPL
@section Customization and tips