Document 1.3.0 features.

PLUGINS.md

@@ -74,11 +74,9 @@ to and a function to perform the wrapping:
     (add-hook #'leiningen.test/test skip-integration-hook)
 
 Hooks compose, so be aware that your hook may be running inside
-another hook. Hooks are loaded by looking for all namespaces under
-leiningen.hooks.* on the classpath and loading them in alphabetical
-order.
-
-TODO: document hook loading
+another hook. To take advantage of this functionality, projects must
+set the :hooks key in project.clj to a seq of namespaces to load that
+call add-hook.
 
 See [the documentation for
 Hooke](http://github.com/technomancy/robert-hooke/blob/master/README.md)

README.md

@@ -54,12 +54,22 @@ project, but here are the commonly-used tasks:
 
     $ lein jar # package up the whole project as a .jar file
 
+    $ lein install [NAME VERSION] # install a project
+
 Use <tt>lein help</tt> to see a complete list. <tt>lein help
 $TASK</tt> shows the usage for a specific one.
 
-TODO: document chaining tasks
+You can also chain tasks together in a single command by using commas:
+
+    $ lein clean, test foo.test-core, jar
 
-TODO: document user-level init script and plugins
+Most tasks need to be run from somewhere inside a project directory to
+work, but some (<tt>new</tt>, <tt>help</tt>, <tt>version</tt> and the
+two-argument version of <tt>install</tt>) may run from anywhere.
+
+The install task places shell scripts in the <tt>~/.lein/bin</tt>
+directory for projects that include them, so if you want to take
+advantage of this, you should put it on your $PATH.
 
 ## Configuration
 
@@ -79,6 +89,12 @@ appropriate starting point from which you can work. See the
 [sample.project.clj](http://github.com/technomancy/leiningen/blob/master/sample.project.clj)
 file for a detailed listing of configuration options.
 
+You can also have user-level configuration that applies for all
+projects. The ~/.lein/init.clj file will be loaded every time
+Leiningen launches; any arbitrary code may go there. Place jars
+containing plugins in ~/.lein/plugins to have them available globally
+for the current user.
+
 ## FAQ
 
 **Q:** How do you pronounce Leiningen?  

TUTORIAL.md

@@ -238,15 +238,17 @@ of Leiningen projects:
 * A library
 * A server-side application
 
-For the first, you will want to build an uberjar. For libraries, you
-will want to have them published to a repository like Clojars. For
-server-side applications it varies as described below.
+For the first, you can either build an uberjar or use a shell-wrapper.
+For libraries, you will want to have them published to a repository
+like Clojars. For server-side applications it varies as described
+below.
 
 ### Uberjar
 
-The <tt>uberjar</tt> task is used to create a standalone, executable
-jar. For this to work you'll need to specify a namespace as your :main
-in project.clj. By this point our project.clj file should look like this:
+The simplest thing to do is to distribute an uberjar. This is a single
+standalone executable jar file. For this to work you'll need to
+specify a namespace as your :main in project.clj. By this point our
+project.clj file should look like this:
 
     (defproject myproject "1.0.0-SNAPSHOT"
       :description "This project is MINE."
@@ -293,7 +295,35 @@ You can run a regular (non-uber) jar with the <tt>java</tt>
 command-line tool, but that requires constructing the classpath
 yourself, so it's not a good solution for end-users.
 
-TODO: document shell wrappers
+### Shell Wrappers
+
+There are a few downsides to uberjars. It's relatively awkward to
+invoke them compared to other command-line tools. You also can't
+control how the JVM is launched. To solve this, you can include a
+shell script in your jar file that can be used to launch the
+project. Leiningen places this shell script into the
+<tt>~/.lein/bin</tt> directory at install time.
+
+If you simply include <tt>:shell-wrapper true</tt> in your
+project.clj, Leiningen automatically generates a simple shell script
+wrapper when you create your jar file. However, if you need more
+control you can provide a map instead:
+
+    :shell-wrapper {:main myproject.core
+                    :bin "bin/myproject"}
+
+Normally the shell wrapper will invoke the -main function in your
+project's :main namespace, but specifying this option triggers AOT for
+uberjars, so if you wish to avoid this or use a different :main for
+the shell wrapper vs uberjar you can specify a :main ns inside the
+:shell-wrapper map. You may also specify a :bin key, which should
+point to a file in <tt>resources/</tt> directory to use as a shell
+wrapper template instead of the default. The <tt>format</tt> function
+is called with the contents of this file along with the necessary
+classpath and the main namespace, so put %s in the right place. See
+[the default
+wrapper](http://github.com/technomancy/leiningen/blob/master/resources/script-template)
+for an example.
 
 ### Publishing
 

src/leiningen/install.clj

@@ -34,7 +34,9 @@
         install-shell-wrapper)))
 
 (defn install
-  "Install the project and its dependencies in your local repository."
+  "With no arguments, installs the current project and its dependencies in
+your local repository. With two arguments, downloads and installs a project
+from a remote repository. May place shell wrappers in ~/.lein/bin."
   ([project]
      (let [jarfile (file (jar project))
            model (make-model project)

src/leiningen/repl.clj

@@ -70,8 +70,8 @@
     (recur port)))
 
 (defn repl
-  ;; TODO: document socket repl
-  "Start a repl session for the current project."
+  "Start a repl session. A socket-repl will also be launched in the
+background; use the LEIN_REPL_PORT environment variable to set the port."
   [project]
   (let [host (or (System/getenv "LEIN_REPL_HOST") "localhost")
         port (Integer. (or (System/getenv "LEIN_REPL_PORT")

todo.org

@@ -8,6 +8,7 @@ Leiningen TODOs
 * For 1.4.0 or later
 ** TODO add option to use ~/.m2-based classpath instead of copying to lib/?
 ** TODO lein add $DEPENDENCY (inserts it into :dependencies in project.clj)
+** TODO shell wrappers should support multiple versions
 ** TODO classifiers for specifying what clojure version to use?
 ** TODO test classification using metadata; run a subset of tests
 ** TODO a list of dirs to include in the jar when building