From 20b0c5e3d2560fce9a424a318b97a70ec425742d Mon Sep 17 00:00:00 2001 From: Jose Antonio Ortega Ruiz Date: Fri, 15 Oct 2010 19:31:03 +0200 Subject: Documentation for smart-tab mode --- README | 185 +++++++++++++++++++++++++++++++++++++++++++++++ README.org | 229 ----------------------------------------------------------- doc/fun.texi | 8 +++ 3 files changed, 193 insertions(+), 229 deletions(-) create mode 100644 README delete mode 100644 README.org diff --git a/README b/README new file mode 100644 index 0000000..00df9b8 --- /dev/null +++ b/README @@ -0,0 +1,185 @@ + -*- org -*- +* 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 . + - In your .emacs: + + #+BEGIN_SRC emacs-lisp + (load-file "/elisp/geiser.el") + #+END_SRC + +*** Byte-compiled + - Create a build directory, `build', say: + #+BEGIN_SRC shell + $ cd + $ mkdir build; cd build + #+END_SRC + - Configure and make: + #+BEGIN_SRC shell + $ ../configure && make + #+END_SRC + + Now, you can use the byte-compiled Geiser in place by adding to + your .emacs: + + #+BEGIN_SRC emacs-lisp + (load "/build/elisp/geiser-load") + #+END_SRC + + or, alternatively, install it with: + + #+BEGIN_SRC shell + $ make install + #+END_SRC + + (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: + + #+BEGIN_SRC emacs-lisp + (require 'geiser-install) + #+END_SRC + + 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: + + #+BEGIN_SRC emacs-lisp + (setq geiser-impl-installed-implementations '(racket guile)) + #+END_SRC + + 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--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. diff --git a/README.org b/README.org deleted file mode 100644 index 304ceac..0000000 --- a/README.org +++ /dev/null @@ -1,229 +0,0 @@ -* 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 . - - In your .emacs: - - #+BEGIN_SRC emacs-lisp - (load-file "/elisp/geiser.el") - #+END_SRC - -*** Byte-compiled - - Create a build directory, `build', say: - #+BEGIN_SRC shell - $ cd - $ mkdir build; cd build - #+END_SRC - - Configure and make: - #+BEGIN_SRC shell - $ ../configure && make - #+END_SRC - - Now, you can use the byte-compiled Geiser in place by adding to - your .emacs: - - #+BEGIN_SRC emacs-lisp - (load "/build/elisp/geiser-load") - #+END_SRC - - or, alternatively, install it with: - - #+BEGIN_SRC shell - $ make install - #+END_SRC - - (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: - - #+BEGIN_SRC emacs-lisp - (require 'geiser-install) - #+END_SRC - - 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: - - #+BEGIN_SRC emacs-lisp - (setq geiser-impl-installed-implementations '(racket guile)) - #+END_SRC - - 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--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. diff --git a/doc/fun.texi b/doc/fun.texi index 746b608..9895443 100644 --- a/doc/fun.texi +++ b/doc/fun.texi @@ -463,6 +463,14 @@ you're at the end of the following partial expression: and press @kbd{M-@key{TAB}}, one of the possible completions will be @code{definite}. +@cindex smart tabs +If you find the @kbd{M} modifier annoying, you always have the option to +activate @code{geiser-smart-tab-mode}, which will make the @key{TAB} key +double duty as the regular Emacs indentation command (when the cursor is +not near a symbol) and Geiser's completion function. If you want this +smarty pants mode always on in Scheme buffers, customize +@code{geiser-mode-smart-tab-p} to @code{t}. + @cindex completion for module names Geiser also knows how to complete module names, but it's not yet smart enough to infer by context that that's what you want. Instead, you must -- cgit v1.2.3