From 632a069eed54f3912c799b5497ece78d4e8a42d0 Mon Sep 17 00:00:00 2001 From: Jose Antonio Ortega Ruiz Date: Tue, 23 Nov 2010 01:58:33 +0100 Subject: 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. --- doc/cheat.texi | 3 +++ doc/img/geiser-mode.png | Bin 62445 -> 37636 bytes doc/img/repl-mod.png | Bin 29938 -> 30503 bytes doc/parens.texi | 33 ++++++++++++++++++++++++--------- doc/repl.texi | 40 ++++++++++++++++++++-------------------- 5 files changed, 47 insertions(+), 29 deletions(-) (limited to 'doc') 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 Binary files a/doc/img/geiser-mode.png and b/doc/img/geiser-mode.png differ diff --git a/doc/img/repl-mod.png b/doc/img/repl-mod.png index 9814b7e..1fee5f0 100644 Binary files a/doc/img/repl-mod.png and b/doc/img/repl-mod.png 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 -- cgit v1.2.3