Merge pull request clojure-emacs#84 from uvtc/add-getting-started-emacs-docs

Initial commit of these "Getting Started with Emacs for Clojure" docs.

Author: technomancy

docs/clojure-mode.md

@@ -0,0 +1,6 @@
+Clojure Mode
+============
+
+todo: copy content from technomancy/clojure-mode readme
+
+

docs/gnu-linux-setup.md

@@ -0,0 +1,49 @@
+Emacs Setup on GNU/Linux
+========================
+
+Emacs should be available via your OS's package manager.  For example,
+on Debian-based distros you would typically install Emacs like so:
+
+    sudo apt-get install emacs
+
+We recommend you install the current stable release of Emacs, version
+24. Since v24 was released only very recently, the above command may
+get you v23 instead. Use `apt-cache show emacs` to see which version
+it will provide.
+
+
+
+Ubuntu-based distros
+--------------------
+
+To get Emacs version 24 on an Ubuntu-based distribution, you currently
+need to do the following:
+
+    sudo add-apt-repository ppa:cassou/emacs
+    sudo apt-get update
+    sudo apt-get install emacs-snapshot
+
+
+
+Config Files and Directory
+==========================
+
+Your main Emacs config file is "~/.emacs". You may create
+this file if it does not already exist.
+
+Your main Emacs config and package directory is "~/.emacs.d".
+Create this directory if it does not already exist.
+
+
+
+Other Optional Configuration
+============================
+
+A nice monospace font to use is Inconsolata. To install
+that on modern Debian-based distros:
+
+    sudo apt-get install fonts-inconsolata
+
+You can then select it from within Emacs by using the "Options → Set
+Default Font..." menu item, and then save that setting your ~/.emacs
+file by using the "Options → Save Options" menu item.

docs/index.md

@@ -0,0 +1,111 @@
+Getting Started With Emacs
+==========================
+
+[GNU Emacs](http://www.gnu.org/software/emacs/emacs.html) provides
+excellent support for Clojure programming and is widely used within
+the Clojure community.
+
+
+
+
+Installation
+============
+
+For installing Emacs and generally finding your way around Emacs on
+your platform, proceed now to one of the platform-specific docs:
+
+  * [GNU/Linux setup](gnu-linux-setup.md)
+  * [Mac OS X setup](os-x-setup.md)
+  * [MS Windows setup](ms-windows-setup.md)
+
+
+
+Configuration Overview
+======================
+
+Once you've got Emacs installed, typical configuration for use
+with Clojure includes:
+
+  * enabling the use of a remote Emacs package repository
+  * installing clojure-mode (provides support for syntax highlighting
+    and proper indentation for Clojure files (.clj files))
+  * optionally enabling paredit mode (advanced support for working with
+    expressions in parentheses/brackets)
+
+and then deciding if you want to use an interactive interface to the
+Clojure repl from inside of Emacs. If you want this, the two routes to
+choose from are:
+
+  * use the "inferior-lisp" mode, or
+  * use SLIME and Swank
+
+See below for discussion on each of these options.
+
+
+
+Package Repository
+------------------
+
+Emacs packages extend the editor in various ways, and (as of version
+24) Emacs can install them from a remote repository.  All the packages
+we'll need here can be found in the [Melpa](http://melpa.milkbox.net/)
+repository. Tell Emacs about melpa by adding the following to your
+~/.emacs file:
+
+~~~{.scheme}
+(require 'package)
+(add-to-list 'package-archives
+             '("melpa" . "http://melpa.milkbox.net/packages/") t)
+(package-initialize)
+~~~
+
+
+
+Clojure Mode
+------------
+
+Emacs uses so-called "major modes" (as in, "mode of operation") to
+provide filetype-specific editor support. For example, you edit a Java
+file using the Emacs java mode, and Clojure using a clojure
+mode. Emacs doesn't yet come with a Clojure mode by default, so we
+must install it.
+
+Install clojure-mode while running Emacs. Hit "M-x package-install RET
+clojure-mode". After doing this, Emacs should automatically recognize
+.clj files as Clojure files when you open them.
+
+See [clojure mode](clojure-mode.md) for more info on using it.
+
+
+
+
+Paredit Mode
+------------
+
+todo
+
+
+
+
+REPL Interaction
+================
+
+If you like, you can simply interact with the Clojure repl that
+[Leiningen](http://leiningen.org/index.html) provides for you (via
+`lein repl`) --- totally separate from Emacs. However, Emacs can
+provide access to the repl from within an Emacs buffer if you prefer:
+
+  * The simplest way to interact with the repl from within Emacs is to
+    [use inferior-mode](inferior-mode.md).
+
+  * For more functionality, [use slime & swank](slime-swank.md).
+
+
+
+
+Detailed Emacs Documentation
+============================
+
+GNU Emacs provides excellent built-in documention which is available
+within the editor (see "C-h") and also
+[online](http://www.gnu.org/software/emacs/manual/html_node/emacs/index.html).

docs/inferior-lisp.md

@@ -0,0 +1,4 @@
+Inferior Lisp
+=============
+
+todo: copy content from <http://dev.clojure.org/display/doc/Getting+Started+with+Emacs>

docs/ms-windows-setup.md

@@ -0,0 +1,4 @@
+Emacs Setup on MS Windows
+=========================
+
+todo

docs/os-x-setup.md

@@ -0,0 +1,4 @@
+Emacs Setup on OS X
+===================
+
+todo

docs/slime-swank.md

@@ -0,0 +1,7 @@
+SLIME and Swank
+===============
+
+todo: copy content from
+<http://dev.clojure.org/display/doc/Getting+Started+with+Emacs>
+
+Also: refer to <https://github.com/technomancy/swank-clojure> readme?