Documentation updates0.2.2

10 files changed, 136 insertions, 357 deletions

diff --git a/INSTALL b/INSTALL
index 35a90ca..5148ea4 100644
--- a/INSTALL
+++ b/INSTALL
@@ -1,318 +1,57 @@
 Installing Geiser.
 ------------------
 
-You'll find below the generic build and installation instructions for
-an autotools package, which Geiser happens to be. As you know, they can be
-summarised as:
+Geiser is usable from its source tree, with no configuration
+whatsoever, or can be installed from ELPA with `M-x install-package'
+is Marmalade is in your list of archives.  You can also (byte) compile
+and install it with the usual configure/make/make install dance.
 
-  mkdir build && cd build
-  ../configure
-  make
-  make install
+* From ELPA
 
-And, in our case, we'll need to tell emacs about this new little
-package with
+Add Marmalade to your `package-archives' list:
 
-  (require 'geiser-install)
+  (require 'package)
+  (add-to-list 'package-archives
+    '("marmalade" . "http://marmalade-repo.org/packages/"))
+  (package-initialize)
 
-in your moral equivalent to ~/.emacs.
+and run `M-x install-package RET geiser`.  You can also use
+http://download.savannah.gnu.org/releases/geiser/packages as a repo,
+or download directly the package from there and use M-x
+package-install-file.
 
-As explained in the README file, Geiser is also directly usable from
-its source tree, with no configuration whatsoever. Read that README to
-see how.
+* 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:
 
-As promised, here you have the gory details of the autotools jazz,
-which you can freely and safely skip on a first, second and third
-reading.
+      (load-file "<path-to-geiser>/elisp/geiser.el")
 
-Installation Instructions
-*************************
+* Byte-compiled
+    - Create a build directory, `build', say:
+      $ cd <path-to-geiser>
+      $ mkdir build; cd build
+    - Configure and make:
+      $ ../configure && make
 
-Copyright (C) 1994, 1995, 1996, 1999, 2000, 2001, 2002, 2004, 2005,
-2006, 2007, 2008, 2009 Free Software Foundation, Inc.
+    Now, you can use the byte-compiled Geiser in place by adding to
+    your .emacs:
 
-   This file is free documentation; the Free Software Foundation gives
-unlimited permission to copy, distribute and modify it.
+    (load "<path-to-geiser>/build/elisp/geiser-load")
 
-Basic Installation
-==================
+    or, alternatively, install it with:
 
-   Briefly, the shell commands `./configure; make; make install' should
-configure, build, and install this package.  The following
-more-detailed instructions are generic; see the `README' file for
-instructions specific to this package.
+    $ make install
 
-   The `configure' shell script attempts to guess correct values for
-various system-dependent variables used during compilation.  It uses
-those values to create a `Makefile' in each directory of the package.
-It may also create one or more `.h' files containing system-dependent
-definitions.  Finally, it creates a shell script `config.status' that
-you can run in the future to recreate the current configuration, and a
-file `config.log' containing compiler output (useful mainly for
-debugging `configure').
+    (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:
 
-   It can also use an optional file (typically called `config.cache'
-and enabled with `--cache-file=config.cache' or simply `-C') that saves
-the results of its tests to speed up reconfiguring.  Caching is
-disabled by default to prevent problems with accidental use of stale
-cache files.
+    (require 'geiser-install)
 
-   If you need to do unusual things to compile the package, please try
-to figure out how `configure' could check whether to do them, and mail
-diffs or instructions to the address given in the `README' so they can
-be considered for the next release.  If you are using the cache, and at
-some point `config.cache' contains results you don't want to keep, you
-may remove or edit it.
-
-   The file `configure.ac' (or `configure.in') is used to create
-`configure' by a program called `autoconf'.  You need `configure.ac' if
-you want to change it or regenerate `configure' using a newer version
-of `autoconf'.
-
-The simplest way to compile this package is:
-
-  1. `cd' to the directory containing the package's source code and type
-     `./configure' to configure the package for your system.
-
-     Running `configure' might take a while.  While running, it prints
-     some messages telling which features it is checking for.
-
-  2. Type `make' to compile the package.
-
-  3. Optionally, type `make check' to run any self-tests that come with
-     the package.
-
-  4. Type `make install' to install the programs and any data files and
-     documentation.
-
-  5. You can remove the program binaries and object files from the
-     source code directory by typing `make clean'.  To also remove the
-     files that `configure' created (so you can compile the package for
-     a different kind of computer), type `make distclean'.  There is
-     also a `make maintainer-clean' target, but that is intended mainly
-     for the package's developers.  If you use it, you may have to get
-     all sorts of other programs in order to regenerate files that came
-     with the distribution.
-
-  6. Often, you can also type `make uninstall' to remove the installed
-     files again.
-
-Compilers and Options
-=====================
-
-   Some systems require unusual options for compilation or linking that
-the `configure' script does not know about.  Run `./configure --help'
-for details on some of the pertinent environment variables.
-
-   You can give `configure' initial values for configuration parameters
-by setting variables in the command line or in the environment.  Here
-is an example:
-
-     ./configure CC=c99 CFLAGS=-g LIBS=-lposix
-
-   *Note Defining Variables::, for more details.
-
-Compiling For Multiple Architectures
-====================================
-
-   You can compile the package for more than one kind of computer at the
-same time, by placing the object files for each architecture in their
-own directory.  To do this, you can use GNU `make'.  `cd' to the
-directory where you want the object files and executables to go and run
-the `configure' script.  `configure' automatically checks for the
-source code in the directory that `configure' is in and in `..'.
-
-   With a non-GNU `make', it is safer to compile the package for one
-architecture at a time in the source code directory.  After you have
-installed the package for one architecture, use `make distclean' before
-reconfiguring for another architecture.
-
-   On MacOS X 10.5 and later systems, you can create libraries and
-executables that work on multiple system types--known as "fat" or
-"universal" binaries--by specifying multiple `-arch' options to the
-compiler but only a single `-arch' option to the preprocessor.  Like
-this:
-
-     ./configure CC="gcc -arch i386 -arch x86_64 -arch ppc -arch ppc64" \
-                 CXX="g++ -arch i386 -arch x86_64 -arch ppc -arch ppc64" \
-                 CPP="gcc -E" CXXCPP="g++ -E"
-
-   This is not guaranteed to produce working output in all cases, you
-may have to build one architecture at a time and combine the results
-using the `lipo' tool if you have problems.
-
-Installation Names
-==================
-
-   By default, `make install' installs the package's commands under
-`/usr/local/bin', include files under `/usr/local/include', etc.  You
-can specify an installation prefix other than `/usr/local' by giving
-`configure' the option `--prefix=PREFIX'.
-
-   You can specify separate installation prefixes for
-architecture-specific files and architecture-independent files.  If you
-pass the option `--exec-prefix=PREFIX' to `configure', the package uses
-PREFIX as the prefix for installing programs and libraries.
-Documentation and other data files still use the regular prefix.
-
-   In addition, if you use an unusual directory layout you can give
-options like `--bindir=DIR' to specify different values for particular
-kinds of files.  Run `configure --help' for a list of the directories
-you can set and what kinds of files go in them.
-
-   If the package supports it, you can cause programs to be installed
-with an extra prefix or suffix on their names by giving `configure' the
-option `--program-prefix=PREFIX' or `--program-suffix=SUFFIX'.
-
-Optional Features
-=================
-
-   Some packages pay attention to `--enable-FEATURE' options to
-`configure', where FEATURE indicates an optional part of the package.
-They may also pay attention to `--with-PACKAGE' options, where PACKAGE
-is something like `gnu-as' or `x' (for the X Window System).  The
-`README' should mention any `--enable-' and `--with-' options that the
-package recognizes.
-
-   For packages that use the X Window System, `configure' can usually
-find the X include and library files automatically, but if it doesn't,
-you can use the `configure' options `--x-includes=DIR' and
-`--x-libraries=DIR' to specify their locations.
-
-Particular systems
-==================
-
-   On HP-UX, the default C compiler is not ANSI C compatible.  If GNU
-CC is not installed, it is recommended to use the following options in
-order to use an ANSI C compiler:
-
-     ./configure CC="cc -Ae"
-
-and if that doesn't work, install pre-built binaries of GCC for HP-UX.
-
-   On OSF/1 a.k.a. Tru64, some versions of the default C compiler cannot
-parse its `<wchar.h>' header file.  The option `-nodtk' can be used as
-a workaround.  If GNU CC is not installed, it is therefore recommended
-to try
-
-     ./configure CC="cc"
-
-and if that doesn't work, try
-
-     ./configure CC="cc -nodtk"
-
-Specifying the System Type
-==========================
-
-   There may be some features `configure' cannot figure out
-automatically, but needs to determine by the type of machine the package
-will run on.  Usually, assuming the package is built to be run on the
-_same_ architectures, `configure' can figure that out, but if it prints
-a message saying it cannot guess the machine type, give it the
-`--build=TYPE' option.  TYPE can either be a short name for the system
-type, such as `sun4', or a canonical name which has the form:
-
-     CPU-COMPANY-SYSTEM
-
-where SYSTEM can have one of these forms:
-
-     OS KERNEL-OS
-
-   See the file `config.sub' for the possible values of each field.  If
-`config.sub' isn't included in this package, then this package doesn't
-need to know the machine type.
-
-   If you are _building_ compiler tools for cross-compiling, you should
-use the option `--target=TYPE' to select the type of system they will
-produce code for.
-
-   If you want to _use_ a cross compiler, that generates code for a
-platform different from the build platform, you should specify the
-"host" platform (i.e., that on which the generated programs will
-eventually be run) with `--host=TYPE'.
-
-Sharing Defaults
-================
-
-   If you want to set default values for `configure' scripts to share,
-you can create a site shell script called `config.site' that gives
-default values for variables like `CC', `cache_file', and `prefix'.
-`configure' looks for `PREFIX/share/config.site' if it exists, then
-`PREFIX/etc/config.site' if it exists.  Or, you can set the
-`CONFIG_SITE' environment variable to the location of the site script.
-A warning: not all `configure' scripts look for a site script.
-
-Defining Variables
-==================
-
-   Variables not defined in a site shell script can be set in the
-environment passed to `configure'.  However, some packages may run
-configure again during the build, and the customized values of these
-variables may be lost.  In order to avoid this problem, you should set
-them in the `configure' command line, using `VAR=value'.  For example:
-
-     ./configure CC=/usr/local2/bin/gcc
-
-causes the specified `gcc' to be used as the C compiler (unless it is
-overridden in the site shell script).
-
-Unfortunately, this technique does not work for `CONFIG_SHELL' due to
-an Autoconf bug.  Until the bug is fixed you can use this workaround:
-
-     CONFIG_SHELL=/bin/bash /bin/bash ./configure CONFIG_SHELL=/bin/bash
-
-`configure' Invocation
-======================
-
-   `configure' recognizes the following options to control how it
-operates.
-
-`--help'
-`-h'
-     Print a summary of all of the options to `configure', and exit.
-
-`--help=short'
-`--help=recursive'
-     Print a summary of the options unique to this package's
-     `configure', and exit.  The `short' variant lists options used
-     only in the top level, while the `recursive' variant lists options
-     also present in any nested packages.
-
-`--version'
-`-V'
-     Print the version of Autoconf used to generate the `configure'
-     script, and exit.
-
-`--cache-file=FILE'
-     Enable the cache: use and save the results of the tests in FILE,
-     traditionally `config.cache'.  FILE defaults to `/dev/null' to
-     disable caching.
-
-`--config-cache'
-`-C'
-     Alias for `--cache-file=config.cache'.
-
-`--quiet'
-`--silent'
-`-q'
-     Do not print messages saying which checks are being made.  To
-     suppress all normal output, redirect it to `/dev/null' (any error
-     messages will still be shown).
-
-`--srcdir=DIR'
-     Look for the package's source code in directory DIR.  Usually
-     `configure' can determine that directory automatically.
-
-`--prefix=DIR'
-     Use DIR as the installation prefix.  *Note Installation Names::
-     for more details, including other options available for fine-tuning
-     the installation locations.
-
-`--no-create'
-`-n'
-     Run the configure checks, but stop before creating any output
-     files.
-
-`configure' also accepts some other, not widely useful, options.  Run
-`configure --help' for more details.
+    You're ready to go!
 
+Geiser's makefile accepts also all those other standard autotools
+targets that you've come to know and love and that are documented
+in virtually all boilerplate INSTALL files out there.
diff --git a/NEWS b/NEWS
index 7cd1087..c6491da 100644
--- a/NEWS
+++ b/NEWS
@@ -1,4 +1,7 @@
-* Version 0.2.2
+* Version 0.2.2 (Sep 30, 2012)
+
+   - ELPA support.  We have now ELPA packages.  Thanks to Grant Rettke
+     and Daniel Hackney.
 
 * Version 0.2.1 (Sep 15, 2012)
 
diff --git a/README b/README
index 14d11a8..110f506 100644
--- a/README
+++ b/README
@@ -34,43 +34,16 @@
       - PLT Racket 5.3 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:
+  The easiest way is to use ELPA/Marmalade, and just type
+  `M-x install-package RET geiser` inside emacs.
 
-    $ 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!
+  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.  See the INSTALL file for more details.
 
 * 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*
@@ -91,7 +64,8 @@
 
   To start a REPL, M-x geiser.
 
-*** Completion with company-mode
+** 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.
@@ -105,7 +79,7 @@
 
 * Quick key reference
 
-*** In Scheme buffers:
+** In Scheme buffers:
 
     |-------------+-------------------------------------------------|
     | C-c C-z     | Switch to REPL                                  |
@@ -145,7 +119,7 @@
     |             | (If `geiser-mode-smart-tab-p' is t)             |
     |-------------+-------------------------------------------------|
 
-*** In the REPL
+** In the REPL
 
     |-------------+----------------------------------------------------|
     | C-c C-z     | Start Scheme REPL, or jump to previous buffer      |
@@ -166,7 +140,7 @@
     | C-c C-d C-a | Toggle autodoc mode                                |
     |-------------+----------------------------------------------------|
 
-*** In the documentation browser:
+** In the documentation browser:
 
     |----------+----------------------------------------------|
     | f        | Next page                                    |
@@ -187,7 +161,7 @@
     | q        | Bury buffer                                  |
     |----------+----------------------------------------------|
 
-*** In backtrace (evaluation/compile result) buffers:
+** In backtrace (evaluation/compile result) buffers:
 
     - M-g n, M-g p, C-x ` for error navigation.
     - q to bury buffer.
diff --git a/THANKS b/THANKS
index 187e315..67deed0 100644
--- a/THANKS
+++ b/THANKS
@@ -13,6 +13,9 @@ ideas and bug reports.
 Michael Wilber convinced me that image support for Racket was not only
 fun, but easy, with the best argument: actual code!
 
+Daniel Hackney and Grant Rettke created the first ELPA packages for
+Geiser and taught me to fish.
+
 Eduardo Cavazos' contagious enthusiasm has helped in many ways to keep
 Geiser alive, and he's become its best evangelist in R6RS circles.
 
diff --git a/doc/geiser.texi b/doc/geiser.texi
index 898bba6..d8c356d 100644
--- a/doc/geiser.texi
+++ b/doc/geiser.texi
@@ -68,7 +68,8 @@ Introduction
 Installation
 
 * Must needs::
-* Setting it up::
+* The easy and quick way::
+* From the source's mouth::
 * Friends::
 
 The REPL
diff --git a/doc/install.texi b/doc/install.texi
index 9a69464..70b73bd 100644
--- a/doc/install.texi
+++ b/doc/install.texi
@@ -3,11 +3,12 @@
 
 @menu
 * Must needs::
-* Setting it up::
+* The easy and quick way::
+* From the source's mouth::
 * Friends::
 @end menu
 
-@node Must needs, Setting it up, Installation, Installation
+@node Must needs, The easy and quick way, Installation, Installation
 @section Must needs
 
 @cindex supported versions
@@ -28,13 +29,67 @@ better
 Since Geiser supports multiple REPLs, having both of them will just add
 to the fun.
 
+You'll also need Geiser itself.  The quickest installation is via its
+ELPA package, as described in the next section.  If you prefer to use
+the source code directly, it's not that difficult either: just keep on
+reading.
+
+@node The easy and quick way, From the source's mouth, Must needs, Installation
+@section The easy and quick way
+
+@cindex quick install
+@cindex ELPA
+Did i mention that the easiest way of installing Geiser is using its
+@uref{http://emacswiki.org/emacs/ELPA, ELPA} package?  If you're using
+Emacs 24, @uref{http://emacswiki.org/emacs/ELPA, ELPA} is already there;
+for earlier versions, the page i just linked to twice will tell you
+where to find the goodies.
+
+ELPA packages live in repositories accessible via HTTP.  You can find
+Geiser's package either in @uref{http://marmalade-repo.org, Marmalade}
+or in Geiser's repository, located at
+@code{http://download.savannah.gnu.org/releases/geiser/packages}.  To
+tell Emacs that a repo exists, you add it to @code{package-archives}:
+
+@example
+(require 'package)
+(add-to-list 'package-archives
+  '("marmalade" . "http://marmalade-repo.org/packages/"))
+;; You don't need this one if you have marmalade:
+;; (add-to-list 'package-archives
+;;  '("geiser" . "http://download.savannah.gnu.org/releases/geiser/packages"))
+(package-initialize)
+@end example
+
+And then installing Geiser is as easy as:
+
+@example
+M-x install-package RET geiser RET
+@end example
+
+Alternatively, you can manually download the @uref{@value{PACKAGE},
+package file}, and install from your local disk with @kbd{M-x
+package-install-file}
+
+With that, you are pretty much all set up.  See @ref{The REPL} to start
+using Geiser.
+
+@ifnotinfo
+And, by the way, if you prefer to keep reading this manual within Emacs,
+@kbd{C-h i m Geiser RET} will bring you to the info version of it that
+you just installed!
+@end ifnotinfo
+
+@node From the source's mouth, Friends, The easy and quick way, Installation
+@section Installing from source
+
 @subsubheading Downloading Geiser
 
 @cindex use the source, Luke
-You'll also need Geiser itself.  The latest release tarball can be found
-@downfile{, here}, while older versions are @uref{@value{OLD_DOWN_BASE}/,
-here}.  Just download @downfile{@value{TARBALL}, @value{TARBALL}}
-and untar it in a directory of your choice.
+The latest release tarball can be found @downfile{, here}, while older
+versions are @uref{@value{OLD_DOWN_BASE}/, here}.  Just download
+@downfile{@value{TARBALL}, @value{TARBALL}} and untar it in a directory
+of your choice.
 
 If you feel like living on the bleeding edge, just grab Geiser from its
 Git repository @uref{http://git.savannah.nongnu.org/cgit/geiser.git/, over
@@ -60,8 +115,7 @@ synchronized with the one at Savannah.
 Either way, you'll now be in possession of a copy of Geiser's libre
 code.  I'll follow you into its directory and the next section.
 
-@node Setting it up, Friends, Must needs, Installation
-@section Setting it up
+@subsubheading Setting it up
 
 Geiser is ready to be used out of the box without much more ado.  For the
 sake of concreteness, let's assume you put its source in the directory
@@ -155,7 +209,7 @@ manual, in Info format, where Emacs can find it, so you can continue to
 learn about Geiser inside its natural habitat.  See you there and into
 the next chapter!
 
-@node Friends,  , Setting it up, Installation
+@node Friends,  , From the source's mouth, Installation
 @section Friends
 
 Although Geiser does not need them, it plays well with (and is enhanced
diff --git a/doc/macros.texi b/doc/macros.texi
index 5bf402d..3f9eb02 100644
--- a/doc/macros.texi
+++ b/doc/macros.texi
@@ -4,7 +4,9 @@
 @set RACKET_VERSION 5.3
 @set EMACS_VERSION 23.2
 @set DOWN_BASE https://github.com/@/jaor/@/geiser/@/downloads
-@set OLD_DOWN_BASE http://download.savannah.nongnu.org/@/releases/@/geiser
+@set OLD_DOWN_BASE http://download.savannah.gnu.org/@/releases/@/geiser
+@set PACKAGE_REPO @value{OLD_DOWN_BASE}/@/packages
+@set PACKAGE @value{PACKAGE_REPO}/@/geiser-@value{VERSION}.tar
 @set TARBALL geiser-@value{VERSION}.tar.gz
 
 @macro downfile{FILE, CAPT}
diff --git a/doc/parens.texi b/doc/parens.texi
index 3a6a0e0..f3693fc 100644
--- a/doc/parens.texi
+++ b/doc/parens.texi
@@ -34,12 +34,12 @@ process giving you the REPL, make those Scheme buffers come to life.
 
 @cindex geiser-mode
 @img{geiser-mode, right} With Geiser installed following any of the
-procedures described in @ref{Setting it up}, Emacs will automatically
-activate @i{geiser-mode} when opening a Scheme buffer.  Geiser also
-instructs Emacs to consider files with the extension @file{rkt} part of
-the family, so that, in principle, there's nothing you need to do to
-ensure that Geiser's extensions will be available, out of the box, when
-you start editing Scheme code.
+procedures described in @ref{The easy and quick way} or @ref{From the
+source's mouth}, Emacs will automatically activate @i{geiser-mode} when
+opening a Scheme buffer.  Geiser also instructs Emacs to consider files
+with the extension @file{rkt} part of the family, so that, in principle,
+there's nothing you need to do to ensure that Geiser's extensions will
+be available, out of the box, when you start editing Scheme code.
 
 Indications that everything is working according to plan include the
 'Geiser' minor mode indicator in your mode-line and the appearance of a
diff --git a/doc/repl.texi b/doc/repl.texi
index dcc1bd0..445811a 100644
--- a/doc/repl.texi
+++ b/doc/repl.texi
@@ -1,7 +1,7 @@
 @node The REPL
 @chapter The REPL
 @anchor{quick-start}
-If you've followed the instructions in @ref{Setting it up}, your Emacs is
+If you've followed the instructions in @ref{Installation}, your Emacs is
 now ready to start playing.  Otherwise, i'll wait for you: when you're
 ready, just come back here and proceed to the following sections.
 
diff --git a/doc/thanks.texi b/doc/thanks.texi
index 87230c8..a614ed6 100644
--- a/doc/thanks.texi
+++ b/doc/thanks.texi
@@ -16,6 +16,9 @@ ideas and bug reports.
 Michael Wilber convinced me that image support for Racket was not only
 fun, but easy, with the best argument: actual code!
 
+Daniel Hackney and Grant Rettke created the first ELPA packages for
+Geiser and taught me to fish.
+
 Eduardo Cavazos' contagious enthusiasm has helped in many ways to keep
 Geiser alive, and he's become its best evangelist in R6RS circles.