Add documentation about using Racket with popular text editors.

collects/scribblings/guide/editor.scrbl

@@ -0,0 +1,215 @@
+#lang scribble/manual
+
+@title{Using Racket with Your Editor of Choice}
+@author["Vincent St-Amour" "Asumu Takikawa" "Jon Rafkind"]
+
+Do you want to program with Racket but would rather use your editor of choice
+instead of DrRacket? Then this page is for you.
+
+Included is a brief summary of tools that will improve your Racketeering
+experience.
+
+@section{Command-line Tools}
+Racket provides, as part of its standard distribution, a number of useful
+command-line tools that can make Racketeering more pleasant.
+
+@subsection{Raco}
+The @exec{raco} utility provides access to Racket's build tools, package
+management utilities, documentation search and much more. For more information,
+see @other-doc['(lib "scribblings/raco/raco.scrbl")].
+
+@subsection{XREPL}
+Racket ships with an eXtended REPL which provides everything you expect from a
+modern interactive environment. For instance, XREPL provides an @tt{,enter}
+command to have a REPL that runs in the context of a given module, and an
+@tt{,edit} command to invoke your @tt{$EDITOR} on the file you entered. A
+@tt{,drracket} command is also provided to make it easy to use your favorite
+editor to write code, and still have DrRacket easily available to try things
+out.
+
+For more information, see @racketmodname[xrepl].
+
+@subsection{Bash completion}
+Shell auto-completion for @exec{bash} is available in
+@tt{collects/meta/contrib/completion/racket-completion.bash}.
+To enable it, just run the file from your @tt{.bashrc}.
+
+Note: the @tt{meta} collection is only available in the Racket Full
+distribution. The completion script is also available
+@hyperlink["https://raw.github.com/plt/racket/master/collects/meta/contrib/completion/racket-completion.bash"]{online}.
+
+
+@section{Emacs}
+Emacs has long been a favorite among Lispers and Schemers, and is popular among
+Racketeers as well.
+
+@subsection{Major Modes}
+
+@subsubsection{Quack}
+@hyperlink["http://www.neilvandyke.org/quack/"]{Quack} is an extension of
+Emacs's @tt{scheme-mode} that provides enhanced support for Racket, including
+highlighting and indentation of Racket-specific forms, and documentation
+integration.
+
+Quack is included in the Debian and Ubuntu repositories as part of the
+@tt{emacs-goodies-el} package. A Gentoo port is also available (under the name
+@tt{app-emacs/quack}).
+
+@subsubsection{Geiser}
+@hyperlink["http://www.nongnu.org/geiser/"]{Geiser} provides a programming
+environment where the editor is tightly integrated with the Racket
+REPL. Programmers accustomed to environments such as Slime or Squeak should
+feel at home using Geiser. Geiser requires GNU Emacs 23.2 or better.
+
+Quack and Geiser can be used together, and complement each other nicely. More
+information is available in the
+@hyperlink["http://www.nongnu.org/geiser/"]{Geiser manual}.
+
+Debian and Ubuntu packages for Geiser are available under the name
+@tt{geiser}.
+
+@subsubsection{scheme-mode}
+Emacs ships with a major mode for Scheme, @tt{scheme-mode}, that while not as
+featureful as the above options works well for editing Racket code. However,
+this mode does not provide support for Racket-specific forms.
+
+
+@subsubsection{Scribble Mode}
+No Racket program is complete without documentation. Scribble support for emacs
+is available with Neil Van Dyke's
+@hyperlink["http://www.neilvandyke.org/scribble-emacs/"]{Scribble Mode}.
+
+@subsubsection{Other Modes for Scribble}
+In addition to the above Scribble mode, @tt{texinfo-mode} (included with GNU
+Emacs) and plain text modes work well when editing Scribble documents. The
+Racket major modes above are not really suited to this task, given how
+different Scribble's syntax is from Racket's.
+
+
+@subsection{Minor Modes}
+
+@subsubsection{Paredit}
+@hyperlink["http://mumble.net/~campbell/emacs/paredit.el"]{Paredit} is a minor
+mode for pseudo-structurally editing programs in Lisp-like languages. In
+addition to providing high-level S-expression editing commands, it prevents you
+from accidentally unbalancing parentheses.
+
+Debian and Ubuntu packages for Paredit are available under the name
+@tt{paredit-el}.
+
+@subsubsection{scheme-complete}
+Alex Shinn's
+@hyperlink["http://synthcode.com/wiki/scheme-complete"]{scheme-complete}
+provides intelligent, context-sensitive code completion. It also integrates
+with Emacs's @tt{eldoc} mode to provide live documentation in the minibuffer.
+
+While this mode was designed for R5RS Scheme, it can still be useful for Racket
+development. However, this means that the tool is unaware of large portions of
+the Racket standard library, and there may be some discrepancies in the live
+documentation in cases where Scheme and Racket have diverged.
+
+@subsubsection{Rainbow Delimiters}
+The @hyperlink["http://www.emacswiki.org/emacs/RainbowDelimiters"]{rainbow
+delimiters} mode colors parentheses and other delimiters according to their
+nesting depth. It makes it easier to know, at a glance, which parentheses
+match.
+
+
+@section{Vim}
+
+@subsection{Settings}
+
+Many distributions of vim ship with support for Scheme, which will mostly work
+for Racket. You can enable filetype detection of Racket files as Scheme with the
+following:
+
+@verbatim|{
+if has("autocmd")
+  au BufReadPost *.rkt,*.rktl set filetype=scheme
+endif
+}|
+
+Alternatively, you may want settings that are specific to Racket and not to
+Scheme.  To turn these settings on conditionally on Racket source files, add
+something like the following to your vimrc:
+
+@verbatim|{
+if has("autocmd")
+  au BufReadPost *.rkt,*.rktl set filetype=racket
+  au filetype racket set lisp
+  au filetype racket set autoindent
+endif
+}|
+
+However, if you take this path you may need to do more work when installing
+plugins because many Lisp-related plugins and scripts for vim are not aware of
+Racket. You can also set these conditional commands in a @tt{scheme.vim} or
+@tt{racket.vim} file in the @tt{ftplugin} subdirectory of your vim folder.
+
+Most installations of vim will automatically have useful defaults enabled,
+but if your installation does not, you will want to set at least the following
+in your .vimrc file:
+
+@verbatim|{
+" Syntax highlighting
+syntax on
+
+" These lines make vim load various plugins
+filetype on
+filetype indent on
+filetype plugin on
+
+" No tabs!
+set expandtab
+}|
+
+@subsection{Indentation}
+
+You can enable indentation for Racket by setting both the @tt{lisp} and
+@tt{autoindent} options. However, the indentation is limited and not as
+complete as what you can get in Emacs. Using Dorai Sitaram's
+@hyperlink["http://evalwhen.com/scmindent/index.html"]{scmindent} is
+recommended for better indentation of Racket code. The instructions on how to
+use the indenter are available on the website.
+
+If you use the built-in indenter, you can customize it by setting how to
+indent certain keywords (add this to your .vimrc):
+
+@verbatim|{
+" By default vim will indent arguments after the function name
+" but sometimes you want to only indent by 2 spaces similar to
+" how DrRacket indents define. Set the `lispwords' variable to
+" add function names that should have this type of indenting.
+
+set lispwords+=public-method,override-method,private-method,syntax-case,syntax-rules
+set lispwords+=..more..
+}|
+
+@subsection{Highlighting}
+
+The @hyperlink["http://www.vim.org/scripts/script.php?script_id=1230"]{Rainbow
+Parenthesis} script for vim can be useful for more visible parenthesis
+matching. Syntax highlighting for Scheme is shipped with vim on many platforms,
+which will work for the most part with Racket.
+
+If you use a racket filetype as shown above, you can copy the "scheme.vim"
+indentation file from wherever your OS has it installed (e.g. on a Debian
+GNU/Linux machine you would find it at @tt{/usr/share/vim/vim73/syntax}) and
+rename it as "racket.vim" in the @tt{syntax} subdirectory of your vim folder.
+You may want to modify the keywords to highlight Racket-specific identifiers.
+
+@subsection{Structured editing}
+
+The @hyperlink["http://www.vim.org/scripts/script.php?script_id=2531"]{Slimv}
+plugin has a paredit mode that works like paredit in Emacs. However, the plugin
+is not aware of Racket. You can either set vim to treat Racket as Scheme files
+or you can modify the paredit script to load on @tt{*.rkt} files.
+
+@subsection{Miscellaneous}
+
+If you are installing many vim plugins (not necessary specific to Racket), we
+recommend using a plugin that will make loading other plugins easier.
+@hyperlink["http://www.vim.org/scripts/script.php?script_id=2332"]{Pathogen} is
+one plugin that does this; using it, you can install new plugins by extracting
+new plugins from archives and just put them in a new subdirectory in the
+@tt{bundle} folder.

collects/scribblings/guide/guide.scrbl

@@ -10,8 +10,8 @@ some part of Racket. It assumes programming experience, so if you are
 new to programming, consider instead reading @|HtDP|. If you want an
 especially quick introduction to Racket, start with @|Quick|.
 
-@seclink["to-scheme"]{Chapter 2} provides a brief introduction to
-Racket. From @seclink["datatypes"]{Chapter 3} on, this guide dives
+@seclink["to-scheme"]{Chapter 3} provides a brief introduction to
+Racket. From @seclink["datatypes"]{Chapter 4} on, this guide dives
 into details---covering much of the Racket toolbox, but leaving
 precise details to @|Racket| and other reference manuals.
 
@@ -19,6 +19,8 @@ precise details to @|Racket| and other reference manuals.
 
 @include-section["welcome.scrbl"]
 
+@include-section["editor.scrbl"]
+
 @include-section["to-scheme.scrbl"]
 
 @include-section["data.scrbl"]