summaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
authorJose Antonio Ortega Ruiz <jao@gnu.org>2011-01-09 16:49:40 +0100
committerJose Antonio Ortega Ruiz <jao@gnu.org>2011-01-09 16:49:40 +0100
commitfb80d22bf5efa2a634dadc81c6b47f19c929a294 (patch)
treeb05629e1a8da9eb7824986027e9c6641f053cad3 /doc
parent8e02a5215e82ea8377942e9b30c9b0c2b1b6edde (diff)
downloadgeiser-fb80d22bf5efa2a634dadc81c6b47f19c929a294.tar.gz
geiser-fb80d22bf5efa2a634dadc81c6b47f19c929a294.tar.bz2
Docs: better rendering of links in info
Diffstat (limited to 'doc')
-rw-r--r--doc/install.texi22
-rw-r--r--doc/macros.texi32
-rw-r--r--doc/parens.texi40
-rw-r--r--doc/repl.texi31
4 files changed, 81 insertions, 44 deletions
diff --git a/doc/install.texi b/doc/install.texi
index 4e6b197..f356c3e 100644
--- a/doc/install.texi
+++ b/doc/install.texi
@@ -45,17 +45,17 @@ at Savannah}, either with the following incantation:
git clone git://git.sv.gnu.org/geiser.git
@end example
-@noindent or, if you happen to live under a firewall, with the alternative:
+@noindent or, if you happen to live behind a firewall, with the alternative:
@example
git clone http://git.sv.gnu.org/r/geiser.git
@end example
-@noindent You can also follow Geiser's development in
+You can also follow Geiser's development in
@uref{https://github.com/jaor/geiser, one}
@uref{http://repo.or.cz/w/geiser.git, or}
-@uref{http://gitorious.org/geiser, three} mirrors that
-are kept synchronized with the one at Savannah.
+@uref{http://gitorious.org/geiser, three} mirrors that are kept
+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.
@@ -76,11 +76,15 @@ its moral equivalents):
@noindent
or simply evaluate that form inside Emacs (you wouldn't kill a friend
just to start using Geiser, would you?). That's it: you're ready to
-@ref{quick-start,,go}. If you obtained the Geiser source tree from a
-release tarball, you can even continue to read this fine manual inside
-Emacs by opening @file{doc/geiser.info} using @kbd{C-u C-h i}. The
-manual is also available in PDF format
-@downfile{geiser-manual-@value{STABLE_VERSION}.pdf, here}.
+@alt{@ref{quick-start,,go}., go (@pxref{The REPL}).}
+
+@ifnotinfo
+If you obtained the Geiser source tree from a release tarball, you can
+even continue to read this fine manual inside Emacs by opening
+@file{doc/geiser.info} using @kbd{C-u C-h i}. The manual is also
+available in PDF format @downfile{geiser-manual-@value{VERSION}.pdf,
+here}.
+@end ifnotinfo
@cindex byte-compilation
What? You still here? I promise the above is all that's needed to start
diff --git a/doc/macros.texi b/doc/macros.texi
index 9e1646b..b722f67 100644
--- a/doc/macros.texi
+++ b/doc/macros.texi
@@ -1,7 +1,31 @@
@set VERSION 0.1.1
-@set STABLE_VERSION 0.1
@set DOWN_BASE http://download.savannah.nongnu.org/releases/geiser
-@set TARBALL geiser-@value{STABLE_VERSION}.tar.gz
+@set TARBALL geiser-@value{VERSION}.tar.gz
+
+@macro downfile{FILE, CAPT}
+@uref{@value{DOWN_BASE}/@value{VERSION}/\FILE\, \CAPT\}
+@end macro
+
+@macro alt{HTML, NOHTML}
+@ifhtml
+\HTML\
+@end ifhtml
+@ifnothtml
+\NOHTML\
+@end ifnothtml
+@end macro
+
+@macro altr{LINK, TXT, TLINK}
+@ifhtml
+@ref{\LINK\,,\TXT\}
+@end ifhtml
+@ifinfo
+@pxref{\LINK\,\TXT\}
+@end ifinfo
+@iftex
+@ref{\TLINK\}
+@end iftex
+@end macro
@macro img{FILE, ALIGN}
@ifhtml
@@ -18,7 +42,3 @@
@end html
@end ifhtml
@end macro
-
-@macro downfile{FILE, CAPT}
-@uref{@value{DOWN_BASE}/@value{STABLE_VERSION}/\FILE\, \CAPT\}
-@end macro
diff --git a/doc/parens.texi b/doc/parens.texi
index b5c7565..b72e03f 100644
--- a/doc/parens.texi
+++ b/doc/parens.texi
@@ -6,7 +6,7 @@ hacking environment. Well, perhaps a bit more than a half; but, at any
rate, one surely needs also a pleasant way of editing source code. Don't
pay attention to naysayers: Emacs comes with an excellent editor
included for about any language on Earth, and just the best one when
-that language is sexpy (especially if you use @ref{paredit,,Paredit}).
+that language is sexpy (especially if you use @alt{@ref{paredit,,Paredit}).,Paredit).}
Geiser's support for writing Scheme code adds to Emacs'
@code{scheme-mode}, rather than supplanting it; and it does so by means
of a minor mode (unimaginatively dubbed @code{geiser-mode}) that defines
@@ -52,7 +52,8 @@ tried to make Geiser as self-documenting as any self-respecting Emacs
package should be. If you follow this route, make sure to take a look at
Geiser's customization buffers (@kbd{M-x customize-group @key{RET}
geiser}): there's lot of fine-tuning available there. You might also
-want to take a glance at the @ref{Cheat sheet}.
+want to take a glance at @alt{@ref{Cheat sheet}., the tables in
+@pxref{Cheat sheet, the cheat sheet}.}
Since @i{geiser-mode} is a minor mode, you can toggle it with
@kbd{M-x geiser-mode}, and control its activation in hooks with the
@@ -81,8 +82,9 @@ how to make sure that that's actually the case.
As i've already mentioned a couple of times, @i{geiser-mode} needs a
running REPL to be operative. Thus, a common usage pattern will be
-for you to first call @code{run-geiser} (or one of its variants, see
-them described @ref{choosing-impl,,here}), and then open Scheme files;
+for you to first call @code{run-geiser} or one of its variants
+(@pxref{choosing-impl,choosing implementations}), and then open
+some Scheme files;
but there's nothing wrong in first opening a couple Scheme buffers and
then starting the REPL (you can even find it more convenient, since
pressing @kbd{C-c C-z} in a Scheme buffer will start the REPL for
@@ -90,9 +92,12 @@ you). Since Geiser supports more than one Scheme implementation, though,
there's the problem of knowing which of them is to be associated with
each Scheme source file. Serviceable as it is, @i{geiser-mode} will try
to guess the correct implementation for you, according to the algorithm
-described below. If you find that Geiser is already guessing right the
-Scheme implementation, feel free to skip to the
-@ref{switching-repl-buff,,next subsection}.
+described below.
+@ifhtml
+If you find that Geiser is already guessing right the Scheme
+implementation, feel free to skip to the @ref{switching-repl-buff,,next
+subsection}.
+@end ifhtml
@subsubheading How Geiser associates a REPL to your Scheme buffer
@cindex scheme implementation, choosing
@@ -177,10 +182,11 @@ C-z}. Those shortcuts map to the interactive command
@cindex switching to module
If you use a numeric prefix, as in @kbd{C-u C-c C-z}, besides being
-teleported to the REPL, the latter will switch to the namespace of
-the Scheme source file (as if you had used @kbd{C-c C-m} in the REPL,
-with the source file's module as argument; cf. @ref{Switching context}).
-This command is also bound to @kbd{C-c C-Z}, with a capital zed.
+teleported to the REPL, the latter will switch to the namespace of the
+Scheme source file (as if you had used @kbd{C-c C-m} in the REPL, with
+the source file's module as argument; cf. discussion in
+@altr{Switching context,,Switching context}). This command is also
+bound to @kbd{C-c C-Z}, with a capital zed.
Once you're in the REPL, the same @kbd{C-c C-z} shortcut will bring
you back to the buffer you jumped from, provided you don't kill the
@@ -191,8 +197,9 @@ really handy, if you ask me.
@cindex switching schemes
If for some reason you're not happy with the Scheme implementation that
Geiser has assigned to your file, you can change it with @kbd{C-c C-s},
-and probably take a look at @ref{switching-repl-buff,,the previous
-subsection} to make sure that Geiser doesn't get confused again.
+and probably take a look at @alt{@ref{switching-repl-buff,,the previous
+subsection}, the previous subsection} to make sure that Geiser doesn't
+get confused again.
@subsubheading A note about context
As explained before (@pxref{Modus operandi}), all Geiser activities take
@@ -327,7 +334,7 @@ some other tidbits for re-exported identifiers.
You can also ask Geiser to display information about a module, in the
form of a list of its exported identifiers, using @kbd{C-c C-d C-m},
-exactly as you would do @ref{repl-mod,,in the REPL}.
+exactly as you would do in @altr{repl-mod,the REPL,The REPL}.
In both cases, the documentation browser will show a couple of buttons
giving you access to further documentation. First, you'll see a button
@@ -343,8 +350,9 @@ You can also jump directly to the manual page for the symbol at point
with the command @code{geiser-doc-look-up-manual}, bound to @kbd{C-c C-d
i}.
-See our @ref{Documentation browser,,cheat-sheet} for a list of all
-navigation commands available in the documentation browser.
+A list of all navigation commands in the documentation browser is
+available in
+@altr{Documentation browser,our cheat-sheet,Documentation browser}.
@node To eval or not to eval, To err perchance to debug, Documentation helpers, Between the parens
@section To eval or not to eval
diff --git a/doc/repl.texi b/doc/repl.texi
index 073c544..7976f0d 100644
--- a/doc/repl.texi
+++ b/doc/repl.texi
@@ -22,22 +22,25 @@ To start a Scheme REPL (meaning, a Scheme process offering you a
Read-Eval-Print Loop), Geiser provides the generic interactive command
@command{run-geiser}. If you run it (via, as is customary in Emacs,
@kbd{M-x run-geiser}, you'll be saluted by a prompt asking which one of
-the supported implementations you want to launch (yes, you can stop the
-asking: see @ref{active-implementations,,below}). Tabbing for completion
-will offer you, as of this writing, @code{guile} and @code{racket}. Just
-choose your poison, and a new REPL buffer will pop-up.
+the supported implementations you want to launch---yes, you can stop the
+asking, see @altr{active-implementations,below,Customization and tips}.
+Tabbing for completion will offer you, as of this writing, @code{guile}
+and @code{racket}. Just choose your poison, and a new REPL buffer will
+pop-up.
@imgc{repls}
If all went according to plan, you'll be facing an
implementation-dependent banner, followed by an interactive prompt.
Going according to plan includes having the executable of the Scheme you
-chose in your path. If that's not the case, you can tell Emacs where it
-is, as described @ref{impl-binary,, below}. Returning to our REPL,
+chose in your path. If that's not the case, you can tell Emacs where it
+is, as described in @altr{impl-binary,a moment,Customization and tips}.
+Returning to our REPL,
the first thing to notice is that the funny prompt is telling you your
current module: its name is the part just after the @@ sign (in Guile,
that means @code{guile-user}, while Racket's top namespace doesn't have
-a name; cf. @ref{Switching context} below). Other than that, this is
+a name; cf. discussion in @altr{Switching context,,Switching context}).
+Other than that, this is
pretty much equivalent to having a command-line interpreter in a
terminal, with a bunch of add-ons that we'll be reviewing below. You can
start typing sexps right there: Geiser will only dispatch them for
@@ -119,9 +122,9 @@ mercilessly kill the process (but not before stowing your history in the
file system). Unless you're using a remote REPL, that is, in which case
both commands will just sever the connection and leave the remote
process alone. If worse comes to worst and the process is dead, @kbd{C-c
-C-z} will restart it (but the same shortcut, issued when the REPL is
+C-z} will restart it. However, the same shortcut, issued when the REPL is
alive, will bring you back to the buffer you came from, as explained
-@ref{switching-repl-buff,,here}).
+in @altr{switching-repl-buff,this section,The source and the REPL}.
The remaining commands are meatier, and deserve sections of their own.
@@ -129,7 +132,8 @@ The remaining commands are meatier, and deserve sections of their own.
@section Switching context
@cindex current module, in REPL
-In tune with Geiser's @ref{current-module,,modus operandi}, evaluations
+In tune with Geiser's @alt{@ref{current-module,,modus operandi},modus
+operandi}, evaluations
in the REPL take place in the namespace of the current module. As
noted above, the REPL's prompt tells you the name of the current
module. To switch to a different one, you can use the command
@@ -234,9 +238,10 @@ name.
The list of exported bindings is shown, again, in a buffer belonging to
Geiser's documentation browser, where you have at your disposal a bunch
-of navigation commands listed in @xref{Documentation browser,,our
-cheat-sheet}. We'll have a bit more to say about the documentation
-browser in @xref{doc-browser,,a later section}.
+of navigation commands listed in @altr{Documentation browser,our
+cheat-sheet,Documentation browser}. We'll have a bit more to say about
+the documentation browser in
+@altr{doc-browser,a later section,Documentation helpers}.
@cindex jump, at the REPL
If that's still not enough, Geiser can jump, via @kbd{M-.}, to the