Stop spreading misinformation about Racket's help browser
[geiser.git] / README
blob4e31bde9b569584891731cbc6f1dff77c9120106
1 * Overview
3   Geiser is a generic Emacs/Scheme interaction mode, featuring an
4   enhanced REPL and a set of minor modes improving Emacs' basic scheme
5   major mode. The main functionalities provided are:
7     - Evaluation of forms in the namespace of the current module.
8     - Macro expansion.
9     - File/module loading.
10     - Namespace-aware identifier completion (including local bindings,
11       names visible in the current module, and module names).
12     - Autodoc: the echo area shows information about the signature of
13       the procedure/macro around point automatically.
14     - Jump to definition of identifier at point.
15     - Access to documentation (including docstrings when the
16       implementation provides it).
17     - Listings of identifiers exported by a given module.
18     - Listings of callers/callees of procedures.
19     - Rudimentary support for debugging (list of
20       evaluation/compilation error in an Emacs' compilation-mode
21       buffer).
22     - Support for inline images in schemes, such as Racket, that treat
23       them as first order values.
25    NOTE: if you're not in a hurry, Geiser's website
26    (http://www.nongnu.org/geiser/) contains a nicer manual, also
27    included in Geiser tarballs as a texinfo file (doc/geiser.info).
29 * Requirements
31     Geiser needs Emacs 23.2 or better, and at least one of the
32     supported scheme implementations:
33       - Guile 2.0 or better.
34       - PLT Racket 5.3 or better.
36 * Installation
38   The easiest way is to use ELPA/Marmalade, and just type
39   `M-x install-package RET geiser` inside emacs.
41   Geiser can be used either directly from its uninstalled source tree
42   or byte-compiled and installed after perfoming the standard
43   configure/make/make install dance.  See the INSTALL file for more details.
45 * Basic configuration
47   The loading invocations above install all supported Scheme
48   implementations. You can list explicitly the ones that you want by
49   setting the variable `geiser-impl-installed-implementations' *before*
50   loading geiser.el. For instance:
52   (setq geiser-impl-installed-implementations '(racket guile))
54    On opening a scheme file, Geiser will try to guess its Scheme,
55    defaulting to the first in the list. Use `C-c C-s' to select the
56    implementation by hand (on a per file basis).
58   Check the geiser customization group for some options with:
60       M-x customize-group RET geiser RET
62   In particular, customize `geiser-<impl>-binary', which should point
63   to an executable in your path.
65   To start a REPL, M-x geiser.
67 ** Completion with company-mode
69     Geiser offers identifier and module name completion, bound to
70     M-TAB and M-` respectively. Only names visible in the current
71     module are offered.
73     While that is cool and all, things are even better: if you have
74     company-mode (http://nschum.de/src/emacs/company-mode/) installed,
75     Geiser's completion will use it. Just require company-mode and,
76     from then on, any new scheme buffer or REPL will use it. If you
77     didn't know about Nikolaj Schumacher's awesome mode, check this
78     screencast: http://goo.gl/yxLQ.
80 * Quick key reference
82 ** In Scheme buffers:
84     |-------------+-------------------------------------------------|
85     | C-c C-z     | Switch to REPL                                  |
86     | C-c C-a     | Switch to REPL and current module               |
87     | C-c C-s     | Specify Scheme implementation for buffer        |
88     |-------------+-------------------------------------------------|
89     | M-.         | Go to definition of identifier at point         |
90     | M-,         | Go back to where M-. was last invoked           |
91     | C-c C-e m   | Ask for a module and open its file              |
92     | C-c C-e C-l | Add a given directory to Scheme's load path     |
93     | C-c C-e [   | Toggle between () and [] for current form       |
94     |-------------+-------------------------------------------------|
95     | C-M-x       | Eval definition around point                    |
96     | C-c M-e     | Eval definition around point and switch to REPL |
97     | C-x C-e     | Eval sexp before point                          |
98     | C-c C-r     | Eval region                                     |
99     | C-c M-r     | Eval region and switch to REPL                  |
100     |-------------+-------------------------------------------------|
101     | C-c C-m x   | Macro-expand definition around point            |
102     | C-c C-m e   | Macro-expand sexp before point                  |
103     | C-c C-m r   | Marcro-expand region                            |
104     |-------------+-------------------------------------------------|
105     | C-c C-k     | Compile and load current file                   |
106     |-------------+-------------------------------------------------|
107     | C-c C-d d   | See documentation for identifier at point       |
108     | C-c C-d s   | See short documentation for identifier at point |
109     | C-c C-d i   | Look up manual for identifier at point          |
110     | C-c C-d m   | See a list of a module's exported identifiers   |
111     | C-c C-d a   | Toggle autodoc mode                             |
112     |-------------+-------------------------------------------------|
113     | C-c <       | Show callers of procedure at point              |
114     | C-c >       | Show callees of procedure at point              |
115     |-------------+-------------------------------------------------|
116     | M-TAB       | Complete identifier at point                    |
117     | M-`, C-.    | Complete module name at point                   |
118     | TAB         | Complete identifier at point or indent          |
119     |             | (If `geiser-mode-smart-tab-p' is t)             |
120     |-------------+-------------------------------------------------|
122 ** In the REPL
124     |-------------+----------------------------------------------------|
125     | C-c C-z     | Start Scheme REPL, or jump to previous buffer      |
126     | C-c M-o     | Clear scheme output                                |
127     | C-c C-q     | Kill Scheme process                                |
128     | C-c C-k     | Nuke REPL: use it if the REPL becomes unresponsive |
129     |-------------+----------------------------------------------------|
130     | M-.         | Edit identifier at point                           |
131     | TAB, M-TAB  | Complete identifier at point                       |
132     | M-`, C-.    | Complete module name at point                      |
133     | M-p, M-n    | Prompt history, matching current prefix            |
134     |-------------+----------------------------------------------------|
135     | C-c C-m     | Set current module                                 |
136     | C-c C-i     | Import module into current namespace               |
137     | C-c C-r     | Add a given directory to scheme's load path        |
138     |-------------+----------------------------------------------------|
139     | C-c C-d C-d | See documentation for symbol at point              |
140     | C-c C-d C-m | See documentation for module                       |
141     | C-c C-d C-a | Toggle autodoc mode                                |
142     |-------------+----------------------------------------------------|
144 ** In the documentation browser:
146     |----------+----------------------------------------------|
147     | f        | Next page                                    |
148     | b        | Previous page                                |
149     |----------+----------------------------------------------|
150     | TAB, n   | Next link                                    |
151     | S-TAB, p | Previous link                                |
152     | N        | Next section                                 |
153     | P        | Previous section                             |
154     |----------+----------------------------------------------|
155     | k        | Kill current page and go to previous or next |
156     | g, r     | Refresh page                                 |
157     | c        | Clear browsing history                       |
158     |----------+----------------------------------------------|
159     | ., M-.   | Edit identifier at point                     |
160     | z        | Switch to REPL                               |
161     |----------+----------------------------------------------|
162     | q        | Bury buffer                                  |
163     |----------+----------------------------------------------|
165 ** In backtrace (evaluation/compile result) buffers:
167     - M-g n, M-g p, C-x ` for error navigation.
168     - q to bury buffer.