summaryrefslogtreecommitdiff
path: root/README.org
diff options
context:
space:
mode:
authorJose Antonio Ortega Ruiz <jao@gnu.org>2010-10-15 17:05:49 +0200
committerJose Antonio Ortega Ruiz <jao@gnu.org>2010-10-15 17:05:49 +0200
commitf3d1d1d934fbe92c56718c75fc5344f837f916a8 (patch)
tree1118bd69909a0147250f903e6219f373b7aef0cd /README.org
parent436362cc5d773815cc687b6bd04a4cad978acfc1 (diff)
downloadgeiser-f3d1d1d934fbe92c56718c75fc5344f837f916a8.tar.gz
geiser-f3d1d1d934fbe92c56718c75fc5344f837f916a8.tar.bz2
README -> README.org
Diffstat (limited to 'README.org')
-rw-r--r--README.org182
1 files changed, 182 insertions, 0 deletions
diff --git a/README.org b/README.org
new file mode 100644
index 0000000..203a877
--- /dev/null
+++ b/README.org
@@ -0,0 +1,182 @@
+* Overview
+
+ Geiser is a generic Emacs/Scheme interaction mode, featuring an
+ enhanced REPL and a set of minor modes improving Emacs' basic scheme
+ major mode. The main functionalities provided are:
+
+ - Evaluation of forms in the namespace of the current module.
+ - Macro expansion.
+ - File/module loading.
+ - Namespace-aware identifier completion (including local bindings,
+ names visible in the current module, and module names).
+ - Autodoc: the echo area shows information about the signature of
+ the procedure/macro around point automatically.
+ - Jump to definition of identifier at point.
+ - Access to documentation (including docstrings when the
+ implementation provides it).
+ - Listings of identifiers exported by a given module.
+ - Listings of callers/callees of procedures.
+ - Rudimentary support for debugging (list of
+ evaluation/compilation error in an Emacs' compilation-mode
+ buffer).
+
+ NOTE: if you're not in a hurry, [[http://www.nongnu.org/geiser/][Geiser's website]] contains a nicer
+ manual, also included in Geiser tarballs as a texinfo file
+ (doc/geiser.info).
+
+* Supported scheme implementations
+
+ - Guile 2.0 (not released yet: use the latest git master branch).
+ - PLT Racket 5.0.1 or better.
+
+* Installation
+ Geiser can be used either directly from its uninstalled source tree
+ or byte-compiled and installed after perfoming the standard
+ configure/make/make install dance.
+
+*** In place
+ - Extract the tarball or clone the git repository anywhere in your
+ file system. Let's call that place <path-to-geiser>.
+ - In your .emacs:
+
+ (load-file "<path-to-geiser>/elisp/geiser.el")
+
+*** Byte-compiled
+ - Create a build directory, `build', say:
+ $ cd <path-to-geiser>
+ $ mkdir build; cd build
+ - Configure and make:
+ $ ../configure && make
+
+ Now, you can use the byte-compiled Geiser in place by adding to
+ your .emacs:
+
+ (load "<path-to-geiser>/build/elisp/geiser-load")
+
+ or, alternatively, install it with:
+
+ $ make install
+
+ (you might need to get root access, depending on your installation
+ directory) and, instead of the above load forms, require
+ 'geiser-install (not 'geiser, mind you) in your emacs
+ initialization file:
+
+ (require 'geiser-install)
+
+ You're ready to go!
+
+* Basic configuration
+ The loading invocations above install all supported Scheme
+ implementations. You can list explicitly the ones that you want by
+ setting the variable `geiser-impl-installed-implementations' *before*
+ loading geiser.el. For instance:
+
+ (setq geiser-impl-installed-implementations '(racket guile))
+
+ On opening a scheme file, Geiser will try to guess its Scheme,
+ defaulting to the first in the list. Use `C-c C-s' to select the
+ implementation by hand (on a per file basis).
+
+ Check the geiser customization group for some options with:
+
+ M-x customize-group RET geiser RET
+
+ In particular, customize `geiser-<impl>-binary', which should point
+ to an executable in your path.
+
+ To start a REPL, M-x geiser.
+
+*** Completion with company-mode
+ Geiser offers identifier and module name completion, bound to
+ M-TAB and M-` respectively. Only names visible in the current
+ module are offered.
+
+ While that is cool and all, things are even better: if you have
+ [[http://nschum.de/src/emacs/company-mode/][company-mode]] installed, Geiser's completion will use it. Just
+ require company-mode and, from then on, any new scheme buffer or
+ REPL will use it. If you didn't know about Nikolaj Schumacher's
+ awesome mode, check [[http://www.screentoaster.com/watch/stU0lSRERIR1pYRFVdXVlRVFFV/company_mode_for_gnu_emacs][this screencast]].
+
+* Quick key reference
+
+*** In Scheme buffers:
+
+ |---------------------+-------------------------------------------------|
+ | C-c C-z | Switch to REPL |
+ | C-u C-c C-z | Switch to REPL and current module |
+ | C-c C-s | Specify Scheme implementation for buffer |
+ |---------------------+-------------------------------------------------|
+ | M-. | Go to definition of identifier at point |
+ | M-, | Go back to where M-. was last invoked |
+ | C-c C-e m | Ask for a module and open its file |
+ |---------------------+-------------------------------------------------|
+ | C-M-x | Eval definition around point |
+ | C-c M-e | Eval definition around point and switch to REPL |
+ | C-x C-e | Eval sexp before point |
+ | C-c C-r | Eval region |
+ | C-c M-r | Eval region and switch to REPL |
+ |---------------------+-------------------------------------------------|
+ | C-c C-m x | Macro-expand definition around point |
+ | C-c C-m e | Macro-expand sexp before point |
+ | C-c C-m r | Marcro-expand region |
+ | C-u C-c C-m [x,e,r] | (With prefix, macro expansions are recursive) |
+ |---------------------+-------------------------------------------------|
+ | C-c C-k | Compile and load current file |
+ | C-c C-l | Load current file |
+ |---------------------+-------------------------------------------------|
+ | C-c C-d d | See documentation for identifier at point |
+ | C-c C-d m | See a list of a module's exported identifiers |
+ | C-c C-d a | Toggle autodoc mode |
+ |---------------------+-------------------------------------------------|
+ | C-c< | Show callers of procedure at point |
+ | C-c> | Show callees of procedure at point |
+ | C-c C-x f | See a generic's methods signatures |
+ |---------------------+-------------------------------------------------|
+ | M-TAB | Complete identifier at point |
+ | M-`, C-. | Complete module name at point |
+ | TAB | Complete identifier at point or indent |
+ | | (If `geiser-mode-smart-tab-p' is t) |
+ |---------------------+-------------------------------------------------|
+
+*** In the REPL
+
+ |-------------+----------------------------------------------------|
+ | C-c C-z | Start Scheme REPL, or jump to previous buffer |
+ | C-c C-q | Kill Scheme process |
+ |-------------+----------------------------------------------------|
+ | M-. | Edit identifier at point |
+ | TAB, M-TAB | Complete identifier at point |
+ | M-`, C-. | Complete module name at point |
+ |-------------+----------------------------------------------------|
+ | M-p, M-n | Prompt history, matching current prefix |
+ |-------------+----------------------------------------------------|
+ | C-c C-k | Nuke REPL: use it if the REPL becomes unresponsive |
+ |-------------+----------------------------------------------------|
+ | C-c C-m | Set current module |
+ | C-c C-i | Import module into current namespace |
+ | C-c C-l | Load scheme file |
+ |-------------+----------------------------------------------------|
+ | C-c C-d C-d | See documentation for symbol at point |
+ | C-c C-d C-m | See documentation for module |
+ | C-c C-d C-a | Toggle autodoc mode |
+ |-------------+----------------------------------------------------|
+
+*** In the documentation browser:
+
+ |------------+----------------------------------------------|
+ | n, f | Next page |
+ | p, b | Previous page |
+ | TAB, S-TAB | Next/previous link |
+ | k | Kill current page and go to previous or next |
+ | g, r | Refresh page |
+ | c | Clear browsing history |
+ | ., M-. | Edit identifier at point |
+ | z | Switch to REPL |
+ | q | Bury buffer |
+ |------------+----------------------------------------------|
+
+*** In backtrace (evaluation/compile result) buffers:
+
+ - TAB, M-TAB for error navigation.
+ - q to bury buffer.