Reword a few things in READMEs, todo tweaks.

README.md

@@ -4,10 +4,10 @@
  alt="Leiningen logo" title="The man himself" align="right" />
 
 > "Leiningen!" he shouted. "You're insane! They're not creatures you can
-> fight--they're an elemental--an 'act of God!' Ten miles long, two
-> miles wide--ants, nothing but ants! And every single one of them a
+> fight—they're an elemental—an 'act of God!' Ten miles long, two
+> miles wide—ants, nothing but ants! And every single one of them a
 > fiend from hell..."
-> -- from Leiningen Versus the Ants by Carl Stephenson
+> - from Leiningen Versus the Ants by Carl Stephenson
 
 Leiningen is for automating Clojure projects without setting your hair on fire.
 
@@ -26,7 +26,7 @@ upon the first run on unix, so the first run will take longer.
 2. Place it on your `$PATH`. (I like to use `~/bin`)
 3. Set it to be executable. (`chmod 755 ~/bin/lein`)
 
-The instructions above will install the stable release. The Leiningen 2
+The link above will get you the stable release. The Leiningen 2
 [preview release](https://raw.github.com/technomancy/leiningen/preview/bin/lein)
 has some great new features, but not all projects and plugins have
 been upgraded to work with it yet. Please see the
@@ -56,7 +56,7 @@ project, but here are the commonly-used tasks:
 
     $ lein jar # package up the whole project as a .jar file
 
-    $ lein install # install a project
+    $ lein install # install a project into the local repository
 
     $ lein search [TERM] # find jars for your project.clj dependencies
 
@@ -83,19 +83,14 @@ The `project.clj` file in the project root should look like this:
   :plugins [[lein-ring "0.4.5"]])
 ```
 
-To find specific versions of a dependency, use `lein search`.
+To find specific versions of a dependency, use `lein search`, though
+note that this can be extremely slow the first time you use it.
 
-The `lein new` task generates a project skeleton with an
-appropriate starting point from which you can work. See the
+The `lein new` task generates a project skeleton with an appropriate
+starting point from which you can work. See the
 [sample.project.clj](https://github.com/technomancy/leiningen/blob/preview/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. This code is
-executed inside Leiningen itself, not in your project. Set the
-`:init-ns` key in `:repl-options` in project.clj to point to a
-namespace if you want code executed inside your project in the repl.
+file (also available via `lein help sample`) for a detailed listing of
+configuration options.
 
 ### Profiles
 
@@ -107,9 +102,11 @@ Clojure available in every project you hack on without modifying every
 single project.clj you use.
 
 By default the `:dev`, `:user`, and `:default` profiles are activated
-for each task. Each profile is defined as a map which gets merged into
-your project map. To add resources directories during development, add
-a `:profiles` key to project.clj like so:
+for each task, but the settings they provide are not propagated
+downstream to projects that depend upon yours. Each profile is defined
+as a map which gets merged into your project map. To add resources
+directories during development, add a `:profiles` key to project.clj
+like so:
 
 ```clj
 (defproject myproject "0.5.0-SNAPSHOT"
@@ -230,6 +227,15 @@ explains how to write plugins.
   any of their dependencies by using the `:exclusions` key. See
   `lein help sample` for details.
 
+**Q:** Why doesn't `deps` task populate the `lib` directory in version 2?  
+**A:** The only reason version 1 copied the jars around in the first
+  place was to support existing tooling that needed a cheap way to
+  calculate a project's classpath. Now that Leiningen has a mature
+  plugin ecosystem, this is no longer needed; jars can be referenced
+  directly out of the `~/.m2/repository` directory. If you need to see
+  a listing of all the dependencies that will be used and their
+  versions, use `lein deps :tree`.
+
 **Q:** What does `java.lang.NoSuchMethodError: clojure.lang.RestFn.<init>(I)V` mean?  
 **A:** It means you have some code that was AOT (ahead-of-time)
   compiled with a different version of Clojure than the one you're
@@ -251,7 +257,7 @@ explains how to write plugins.
 **Q:** What can be done to speed up launch?  
 **A:** The main delay involved in Leiningen comes from starting the
   JVM. Most people use a development cycle that involves keeping a
-  single process running for as long as you're working on that
+  single REPL process running for as long as you're working on that
   project. Depending on your editor you may be able to do this via its
   Clojure integration. (See
   [swank-clojure](http://github.com/technomancy/swank-clojure) or
@@ -267,10 +273,10 @@ explains how to write plugins.
 **Q:** Why is Leiningen 2 still in a preview release?  
 **A:** As of the preview3 release, Leiningen 2 is very stable and
   recommended for general use. The main thing keeping it from a final
-  release is the fact that the Clojars repository
+  release is the fact that the current Clojars repository
   [mingles snapshots with releases](https://github.com/ato/clojars-web/issues/24),
   which is undesirable. Since switching the default repositories to a
-  releases-only Clojars (which hasn't been implemented yet) would be a
+  releases-only Clojars (which is still in development) would be a
   breaking change, a series of previews is being released in the mean time.
 
 **Q:** I don't have access to stdin inside my project.  
@@ -284,15 +290,16 @@ explains how to write plugins.
 ## Contributing
 
 Please report issues on the
-[Github issue tracker](https://github.com/technomancy/leiningen/issues)
+[GitHub issue tracker](https://github.com/technomancy/leiningen/issues)
 or the [mailing list](http://groups.google.com/group/leiningen).
 Personal email addresses are **not** appropriate for bug reports. See
-the readme for the `leiningen-core` library and `doc/PLUGINS.md` for
-more details on how Leiningen's codebase is structured. Design
-discussions also occur in the
+the
+[readme for the leiningen-core library](https://github.com/technomancy/leiningen/blob/master/leiningen-core/README.md)
+and `doc/PLUGINS.md` for more details on how Leiningen's codebase is
+structured. Design discussions also occur in the
 [#leiningen channel on Freenode](irc://chat.freenode.net#leiningen).
 
-Patches are preferred as Github pull requests, though patches from
+Patches are preferred as GitHub pull requests, though patches from
 `git format-patch` are also welcome on the mailing list. Please use
 topic branches when sending pull requests rather than committing
 directly to master in order to minimize unnecessary merge commit
@@ -306,7 +313,7 @@ merging if you ask on IRC or the mailing list.
 
 Contributors are also welcome to request a free
 [Leiningen sticker](http://twitpic.com/2e33r1) by asking on the
-mailing list and mailing a SASE.
+mailing list and mailing a self-addressed, stamped envelope.
 
 ## Building
 

leiningen-core/README.md

@@ -1,13 +1,12 @@
 # Leiningen Core
 
 This library provides the core functionality of Leiningen. This
-consists of the task execution implementation and helper functions
-without any of the tasks or launcher scripts.
+consists of the task execution implementation, project configuration,
+and helper functions. The built-in tasks and the launcher scripts are
+kept in the main `leiningen` project.
 
-More [copious documentation is available](http://technomancy.github.com/leiningen/).
-
-The tasks that get run come from Leiningen itself as well as any
-Leiningen plugins that may be active.
+More detailed [API reference](http://leiningen.org/reference.html) is
+available.
 
 ## Namespaces
 
@@ -23,8 +22,6 @@ Leiningen plugins that may be active.
     implements the isolation of project code from Leiningen's own code.
 * **leiningen.core.user** just has a handful of functions which handle
     user-level configuration.
-* **leiningen.core.ns** contains helper functions for finding
-    namespaces on the classpath.
 
 ## Running Tasks
 
@@ -51,11 +48,19 @@ visible to the project's functions.
 Leiningen currently implements this by launching a sub-process using
 `leiningen.core.eval/eval-in-project`. Any code that must execute
 within the context of the project (AOT compilation, test runs, repls)
-needs to go through this function. This sub-process (referred to as
-the "project JVM") is an entirely new invocation of the `java` command
-with its own classpath calculated from functions in the
-`leiningen.core.classpath` namespace. It can only communicate with
-Leiningen's process via the file system, sockets, and its exit code.
+needs to go through this function. Before the process is launched, the
+project must be "prepped", which consists of running all the tasks
+named in the project's `:prep-tasks` key. This defaults to `javac` and
+`compile`, but `defproject` or profiles may add additional tasks as
+necessary. All prep tasks must be cheap to call if nothing has changed
+since their last invocation.
+
+The sub-process (referred to as the "project JVM") is an entirely new
+invocation of the `java` command with its own classpath calculated
+from functions in the `leiningen.core.classpath` namespace. It can
+even use a different version of the JVM from Leiningen if the
+`:java-cmd` key is provided. It can only communicate with Leiningen's
+process via the file system, sockets, and its exit code.
 
 The exception to this rule is when `:eval-in-leiningen` in
 `project.clj` is true, as is commonly used for Leiningen plugins.

leiningen-core/src/leiningen/core/user.clj

@@ -10,6 +10,7 @@
                       (io/file (System/getProperty "user.home") ".lein"))]
     (.getAbsolutePath (doto lein-home .mkdirs))))
 
+;; TODO: is this still needed now that we have the user profile?
 (def init
   "Load the user's ~/.lein/init.clj file, if present."
   (memoize (fn []

project.clj

@@ -34,6 +34,7 @@
 ;; * test self-install
 ;; * git tag
 ;; * push, push tags, update stable branch
+;; * publish leiningen-core docs
 ;; * announce on mailing list
 ;; * bump version numbers back to snapshot
 ;; * regenerate pom.xml

todo.org

@@ -5,9 +5,10 @@ See also https://github.com/technomancy/leiningen/issues
 * For 2.0.0
 ** preview4
    - [X] Don't re-extract native deps (#535)
-   - [ ] Install task outside projects (#546) (LHF)
+   - [X] Make offline profile use dev profile (#514) (LHF)
+   - [ ] Fix $JVM_OPTS (#565)
+   - [ ] Move lein-newnew plugin into default profile (#540)
    - [ ] Force checking of snapshots (#518) (LHF)
-   - [ ] Make offline profile use dev profile (#514) (LHF)
 ** Intermediate
    - [X] Pretty-print pom
    - [X] deps :tree