diff --git a/doc/parens.texi b/doc/parens.texi index 6bd5e5f..2c9e59d 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 (specially if you use @ref{paredit,,Paredit}). +that language is sexpy (especially if you use @ref{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 @@ -39,31 +39,31 @@ Indications that everything is working according to plan include the 'Geiser' minor mode indicator in your mode-line and the appearance of a new entry for Geiser in the menu bar. If, moreover, the mode-line indicator is the name of a Scheme implementation, you're indeed in a -perfect world; otherwise, don't despair and keep on reading: i'll tell +perfect world; otherwise, don't despair and keep on reading: I'll tell you how to fix that in a moment. @cindex geiser-mode commands -The menu provides a good synopsis of everthing Geiser brings to the +The menu provides a good synopsis of everything Geiser brings to the party, including those keyboard shortcuts we Emacsers love. If you're -seeing the name of your favourite Scheme implementation in the +seeing the name of your favorites Scheme implementation in the mode-line, have a running REPL and are comfortable with Emacs, you can stop reading now and, instead, discover Geiser's joys by yourself. I've 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 address@hidden geiser}): there's lot of fine tunning available there. You address@hidden geiser}): there's lot of fine-tuning available there. You might also want to take a glance at the @ref{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 functions @code{turn-on-geiser-mode} and @code{turn-off-geiser-mode}. -If, for some reason i cannot fathom, you prefer @i{geiser-mode} not +If, for some reason I cannot fathom, you prefer @i{geiser-mode} not to be active by default, customizing @code{geiser-mode-auto-p} to @code{nil} will do the trick. @cindex scheme file extensions And if you happen to use a funky extension for your Scheme files that is -not recognised as such by Emacs, just tell her about it with: +not recognized as such by Emacs, just tell her about it with: @example (add-to-list 'auto-mode-alist '("\\.funky-extension\\'" . scheme-mode)) @end example @@ -78,7 +78,7 @@ how to make sure that that's actually the case. @node The source and the REPL, Documentation helpers, Activating Geiser, Between the parens @section The source and the REPL -As i've already mentioned a couple of times, @i{geiser-mode} needs a +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; @@ -125,7 +125,7 @@ If we haven't been lucky this far and you have customized @code{geiser-default-implementation} to the name of a supported implementation, we'll follow your lead. @item -See? That's the problem of being a smart alec: one's always outsmarted +See? That's the problem with being a smart aleck: One's always outsmarted by people around. At this point, @i{geiser-mode} will humbly give up and ask you to explicitly choose the Scheme implementation. @end enumerate @@ -191,7 +191,7 @@ As explained before (@pxref{Modus operandi}), all Geiser activities take place in the context of the @i{current namespace}, which, for Scheme buffers, corresponds to the module that the Scheme implementation associates to the source file at hand (for instance, in Racket, there's -a one to one correspondence between paths and modules, while Guile +a one-to-one correspondence between paths and modules, while Guile relies on explicit @code{define-module} forms in the source file). Now that we have @code{geiser-mode} happily alive in our Scheme buffers @@ -207,7 +207,7 @@ can do for us, besides jumping to and fro. The first thing you will notice by moving around Scheme source is that, every now and then, the echo area lightens up with the same autodoc messages we know and love from our REPL forays. This happens every -time the Scheme process is able to recognise an identifier in the +time the Scheme process is able to recognize an identifier in the buffer, and provide information either on its value (for variables) or on its arity and the name of its formal arguments (for procedures and macros). That information will only be available if the module the @@ -237,11 +237,11 @@ enclosed in parenthesis. When an optional argument has a default value (or a form defining its default value), autodoc will display it after the argument name. When the optional arguments are keywords, their names are prefixed with ``#:'' (i.e., their names @i{are} keywords). An -ellipsis (@dots{}) serves as a marker of an indeterminated number of +ellipsis (@dots{}) serves as a marker of an indeterminate number of parameters, as is the case with @i{rest} arguments or when autodoc cannot fathom the exact number of arguments (this is often the case with macros defined using @code{syntax-case}). Another way in which autodoc -displays its ignorance is by using and underscore to display parameters +displays its ignorance is by using an underscore to display parameters whose name is beyond its powers. @img{autodoc-multi, right} It can also be the case that a function or @@ -259,7 +259,7 @@ parenthesis. After all, we're talking about Scheme here. is on a symbol corresponding to a plain variable: you'll see in the echo area its name, preceded by the module where it's defined, and followed by its value, with an intervening arrow for greater effect. This time, -there are no enclosing parenthesis (i hope you see the logic in my +there are no enclosing parenthesis (I hope you see the logic in my madness). @cindex autodoc customized @@ -286,7 +286,7 @@ identifier or module. @cindex documentation for symbol @cindex docstrings, maybe For symbols, the incantation is @kbd{M-x geiser-doc-symbol-at-point}, or address@hidden C-d C-d} for short. If the associated scheme supports address@hidden C-d C-d} for short. If the associated Scheme supports docstrings (as, for instance, Guile does), you'll be teleported to a new Emacs buffer displaying Geiser's documentation browser, filled with information about the identifier, including its docstring (if any; @@ -316,10 +316,10 @@ exactly as you would do @ref{repl-mod,,in 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 named @i{source}: pressing it you'll jump to the symbol's definition. -The second button, dubbed @i{manual}, will open the scheme +The second button, dubbed @i{manual}, will open the Scheme implementation's manual page for the symbol at hand. For Racket, that will open your web browser displaying the corresponding reference's page -(using Emacs' @code{browser-url} command), while in Guile a lookup will +(using Emacs' @code{browser-url} command), while in Guile a look-up will be performed in the texinfo manual. @cindex opening manual pages @@ -336,11 +336,11 @@ navigation commands available in the documentation browser. @cindex philosophy @cindex incremental development One of Geiser's main goals is to facilitate incremental development. You -might have noticed that i've made a big fuss of Geiser's ability to +might have noticed that I've made a big fuss of Geiser's ability to recognize context, by being aware of the namespace where its operations happen. -That awareness is specially important when evaluating code in your +That awareness is especially important when evaluating code in your scheme buffers, using the commands described below. They allow you to send code to the running Scheme with a granularity ranging from whole files to single s-expressions. That code will be evaluated in the module @@ -383,7 +383,7 @@ For all the commands above, the result of the evaluation is displayed in the minibuffer, unless it causes a (scheme-side) error (@pxref{To err perchance to debug}). -At the risk of repeating myself, i'll remember you that all these +At the risk of repeating myself, I'll remind you that all these evaluations will take place in the namespace of the module corresponding to the Scheme file from which you're sending your code, which, in general, will be different from the REPL's current module. And, if @@ -391,7 +391,7 @@ all goes according to plan, (re)defined variables and procedures should be immediately visible inside and, if exported, outside their module. Besides evaluating expressions, definitions and regions, you can also -macro-expand them. The corresponding keybindings start with the prefix +macro-expand them. The corresponding key bindings start with the prefix @kbd{C-c C-m} and end, respectively, with @kbd{C-e}, @kbd{C-x} and @kbd{C-r}. The result of the macro expansion always appears in a pop up buffer. @@ -406,7 +406,7 @@ the capabilities of the underlying Scheme REPL. @cindex error buffer In Racket, you'll be presented with a backtrace, in a new buffer where -file paths locating the origin of the error are clickable (you can +file paths locating the origin of the error are click-able (you can navigate them using the @key{TAB} key, and use @key{RET} or the mouse to jump to the offending spot; or invoke Emacs' stock commands @code{next-error} and @code{previous-error}, bound to @kbd{M-g n} and @@ -415,7 +415,7 @@ jump to the offending spot; or invoke Emacs' stock commands @imgc{eval-error} The Racket backtrace also highlights the exception type, making it -clickable. Following the link will open the documentation corresponding +click-able. Following the link will open the documentation corresponding to said exception type. Both the error and exception link faces are customizable (@code{geiser-font-lock-error-link} and @code{geiser-font-lock-doc-link}). @@ -423,7 +423,7 @@ customizable (@code{geiser-font-lock-error-link} and On the other hand, Guile's reaction to evaluation errors is different: it enters the debugger in its REPL. Accordingly, the REPL buffer will pop up if your evaluation fails in a Guile file, and the error message -and backtrace will be displayed in there, again clickable and all. But +and backtrace will be displayed in there, again click-able and all. But there you have the debugger at your disposal, with the REPL's current module set to that of the offender, and a host of special debugging commands that are described in Guile's fine documentation. @@ -437,8 +437,8 @@ Racket. You can control how picky Guile is reporting warnings by customizing the variable @code{geiser-guile-warning-level}, whose detailed docstring (which see, using, e.g. @kbd{C-h v}) allows me to offer no further explanation here. The customization group address@hidden is also worth a glance, for a couple of options to fine -tune how Geiser interacts with Guile's debugger (and more). Same thing address@hidden is also worth a glance, for a couple of options to +fine-tune how Geiser interacts with Guile's debugger (and more). Same thing for racketeers and @i{geiser-racket}. @node Jumping around, Geiser writes for you, To err perchance to debug, Between the parens @@ -491,7 +491,7 @@ uses the standard Emacs completion machinery to display them. That means, among other things, that partial completion is available: just try to complete @code{d-s} or @code{w-o-t-s} to see why this is a good thing. Partial completion won't work if you have disabled it globally in -your Emacs configuration: if you don't know what i'm talking about, +your Emacs configuration: if you don't know what I'm talking about, never mind: Geiser's partial completion will work for you out of the box.