From fb80d22bf5efa2a634dadc81c6b47f19c929a294 Mon Sep 17 00:00:00 2001 From: Jose Antonio Ortega Ruiz Date: Sun, 9 Jan 2011 16:49:40 +0100 Subject: Docs: better rendering of links in info --- doc/install.texi | 22 +++++++++++++--------- doc/macros.texi | 32 ++++++++++++++++++++++++++------ doc/parens.texi | 40 ++++++++++++++++++++++++---------------- doc/repl.texi | 31 ++++++++++++++++++------------- 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 -- cgit v1.2.3