From 7cfa18914d1ccb85aca33f659c931be0e8a8c894 Mon Sep 17 00:00:00 2001 From: Jose Antonio Ortega Ruiz Date: Sat, 19 Jun 2010 23:35:21 +0200 Subject: The humble beginnings of a user's manual. --- doc/intro.texi | 111 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 111 insertions(+) create mode 100644 doc/intro.texi (limited to 'doc/intro.texi') diff --git a/doc/intro.texi b/doc/intro.texi new file mode 100644 index 0000000..50b3826 --- /dev/null +++ b/doc/intro.texi @@ -0,0 +1,111 @@ +@node Introduction, Installation, Top, Top +@chapter Introduction + +Geiser is an Emacs environment to hack and have fun in Scheme. If that's +enough for you, see @ref{Installation} to get it running and +@ref{Quick start} for the fun. + +@menu +* Manifesto:: +* Modus operandi:: +* Showing off:: +@end menu + +@node Manifesto, Modus operandi, Introduction, Introduction +@section Manifesto + +Geiser is a collection of Emacs major and minor modes that conspire with +one or more Scheme interpreters to keep the Lisp Machine Spirit alive. +It draws inspiration (and a bit more) from environments such as Common +Lisp's Slime, Factor's FUEL, Squeak or Emacs itself, and does its best +to make Scheme hacking inside Emacs (even more) fun. Or, to be precise, +what i consider fun. Geiser is thus my humble contribution to the +dynamic school of expression, and a reaction against what i perceive as +a derailment, in modern times, of standard Scheme towards the static +camp. Because i prefer growing and healing to poking at corpses, the +continuously running Scheme interpreter takes the center of the stage in +Geiser. A bundle of Elisp shims orchestrates the dialog between the +Scheme interpreter, Emacs and, ultimately, the programmer (that means, +hopefully, you). It asks the live image for metadata in real time, +providing access to them using, as much as possible, standard Emacs +idioms. + +That's the dreal. + +@node Modus operandi, Showing off, Manifesto, Introduction +@section Modus operandi + +As already mentioned, Geiser relies on a running Scheme process to +obtain the information it makes accessible to the programmer. There's +little effort, on the Elisp side, to understand, say, the module system +used by the Scheme implementation at hand; instead, a generic interface +between the two worlds is defined, and each supported Scheme includes a +library implementing that API, together with some wee shims in Elisp +allowing the reuse of the Emacs-side framework, which constitutes the +bulk of the code. + +While being as generic as possible, the Scheme-Elisp interface makes +some assumptions about the capabilities and interaction mode of the +corresponding REPL. In particular, Geiser expects the latter to support +namespaces in the form of a module system, and to provide a well defined +way to establish the REPL's current namespace (or module), as well as +the current's file module (or namespace). Thus, all evaluations +performed by Geiser either in the REPL or in a source code buffer happen +in the context of the current namespace. Every time you switch to a +different file, you're switching namespaces automatically; at the REPL, +you must request the switch explicitly (usually just using means +provided by the Scheme implementation itself). + +If your favourite scheme supports the above modus operandi, it has all +that's needed for a bare-bones Geiser mode. But Geiser can, and will, +use any metadata available: procedure arities and argument lists to +display interactive help, documentation strings, location information to +jump to definitions, export lists to provide completion, and so on and +so forth. Although this is not an all-or-none proposition (Geiser can +operate with just part of that functionality available), i've +concentrated initially in supporting those Schemes with the richest (to +my knowledge) introspection capabilities, namely, Guile and Racket. + +@node Showing off, , Modus operandi, Introduction +@section Showing off + +When working with a fully conniving Scheme, Geiser can offer the +following functionality: + +@itemize @bullet +@item +Form evaluation in the context of the current file's module. +@item +Macro expansion. +@item +File/module loading and/or compilation. +@item +Namespace-aware identifier completion (including local bindings, names +visible in the current module, and module names). +@item +Autodoc: the echo area shows information about the signature of the +procedure/macro around point automatically. +@item +Jump to definition of identifier at point. +@item +Access to documentation (including docstrings when the implementation +provides it). +@item +Listings of identifiers exported by a given module. +@item +Listings of callers/callees of procedures. +@item +Rudimentary support for debugging (when the REPL provides a debugging) +and error navigation. +@item +Support for multiple, simultaneous REPLs. +@end itemize + +In the following sections, i'll try to explain what these features +actually are (i'm just swanking here), and how to use them for your +profit. But, before that, let's see how to install Geiser. + +@c Local Variables: +@c mode: texinfo +@c TeX-master: "geiser" +@c End: -- cgit v1.2.3