Improve arcanist install documentation

Summary:
See <https://github.com/facebook/arcanist/issues/21>, <https://github.com/facebook/arcanist/issues/22>.

  - Provide more detailed install instructions.
  - Provide advice on managing team installs.
  - Provide information on libphutil path resolution.
  - Provide OSX-specific documentation.
  - Update some of the documentation to reflect evolution of the tools.

Test Plan: Generated and read documentation.

Reviewers: btrahan

Reviewed By: btrahan

CC: jmhsieh, aran, epriestley

Differential Revision: https://secure.phabricator.com/D1990

src/docs/userguide/arcanist.diviner

@@ -1,11 +1,12 @@
 @title Arcanist User Guide
 @group userguide
 
-Guide to Arcanist, a command-line tool for code review and revision management.
+Guide to Arcanist, a command-line interface to Phabricator.
 
-Arcanists glues together several other tools, like Differential and lint. It
+Arcanists provides command-line access to many Phabricator tools (like
-also serves as the CLI to Phabricator, and is used to get changesets into
+Differential, Files, and Paste), integrates with static analysis ("lint") and
-Differential for review.
+unit tests, and manages common workflows like getting changes into Differential
+for review.
 
 A detailed command reference is available by running ##arc help##. This
 document provides a high level overview of common workflows.
@@ -30,7 +31,7 @@ Arcanist allows you to do things like:
   - download a patch from Differential with ##arc export##
   - update Git commit messages after review with ##arc amend##
   - commit SVN changes with ##arc commit##
-  - merge Git and Mercurial changes with ##arc merge##
+  - push Git changes with ##arc land##
   - view enhanced information about Git branches with ##arc branch##
 
 Once you've configured lint and unit test integration, you can also:
@@ -38,6 +39,11 @@ Once you've configured lint and unit test integration, you can also:
   - check your code for syntax and style errors with ##arc lint##
   - run unit tests that cover your changes with ##arc unit##
 
+Arcanist integrates with other tools:
+
+  - upload and download files with ##arc upload## and ##arc download##
+  - create and view pastes with ##arc paste##
+
 Arcanist has some advanced features as well, you can:
 
   - execute Conduit method calls with ##arc call-conduit##
@@ -53,14 +59,61 @@ SVN repositories.
 
 = Installing Arcanist =
 
-Arcanist is meant to be installed on your local machine or development server,
+Arcanist is meant to be installed on your local machine or development server --
-i.e. whatever machine you're editing code on. It runs on Linux and Mac OS X;
+whatever machine you're editing code on. It runs on Linux, Mac OS X, and
-To install it, clone it and libphutil off github:
+Windows (see @{article:Arcanist User Guide: Windows}).
 
-  somewhere/ $ git clone git://github.com/facebook/libphutil.git
+Arcanist is written in PHP, so you need to install the PHP CLI first if you
-  somewhere/ $ git clone git://github.com/facebook/arcanist.git
+don't already have it. Arcanist should run on PHP 5.2 and newer. If you don't
+have PHP installed, you can download it from <http://www.php.net/>.
 
-Now add ##somewhere/arcanist/bin/arc## to your path.
+To install Arcanist, pick an install directory and clone the code from GitHub:
+
+  some_install_path/ $ git clone git://github.com/facebook/libphutil.git
+  some_install_path/ $ git clone git://github.com/facebook/arcanist.git
+
+This should leave you with a directory structure like this
+
+  some_install_path/    # Wherever you chose to install it.
+    arcanist/           # Arcanist-specific code and libraries.
+    libphutil/          # A shared library Arcanist depends upon.
+
+Now add ##some_install_path/arcanist/bin/## to your PATH environment variable.
+When you type "arc", you should see something like this:
+
+  Usage Exception: No command provided. Try 'arc help'.
+
+If you get that far, you've done things correctly. If you get an error or have
+trouble getting this far, see these detailed guides:
+
+  - On Windows: @{Arcanist User Guide: Windows}
+  - On Mac OS X: @{Arcanist User Guide: Mac OS X}
+
+The code changes quickly, so remember to update regularly, by running
+`git pull` on the two directories:
+
+  some_install_path/arcanist/ $ git pull
+  some_install_path/libphutil/ $ git pull
+
+== Installing Arcanist for a Team ==
+
+Arcanist changes quickly and doesn't currently have an auto-update mechanism,
+so it can be something of a headache to get it installed and keep people up to
+date. Here are some approaches you might be able to use:
+
+  - Facebook does most development on development servers, which have a standard
+    environment and NFS mounts. Arcanist and libphutil themselves live on an
+    NFS mount, and the default `.bashrc` adds them to the PATH. Updating the
+    mount source updates everyone's versions, and new employees have a working
+    `arc` when they first log in.
+  - Another common approach is to write an install script as an action into
+    existing build scripts, so users can run `make install-arc` or
+    `ant install-arc` or similar.
+  - In general, if this sucks and is causing you pain, let us know (see
+    @{article:Give Feedback! Get Support!}). We're planning to improve this at
+    some point, but it's somewhat complicated to get right. While it can take a
+    little time to set up, we aren't getting feedback that it's a persistent
+    pain point, so it hasn't been a priority.
 
 == Installing Tab Completion ==
 

src/docs/userguide/arcanist_mac_os_x.diviner

@@ -0,0 +1,26 @@
+@title Arcanist User Guide: Mac OS X
+@group userguide
+
+Explains how to install Arcanist on Mac OS X.
+
+= Required Components =
+
+You need to install:
+
+  - PHP, which should be installed by default.
+  - Arcanist itself, see @{article:Arcanist User Guide}.
+  - SVN, Git, or Mercurial.
+
+Then, configure:
+
+  - Your PATH environmental variable should include `arcanist/bin`, and
+    `php` and your VCS command (`svn`, `hg`, `git`) should be in PATH. When you
+    type `php`, `arc`, or (for example) `git` from the command line, they should
+    all do something.
+  - Your EDITOR environmental variable should point at some valid CLI editor,
+    like `nano`, which is the best editor.
+
+You can edit your `~/.profile` to permanently configure environmental variables.
+
+Now you should be able to run `arc` like a normal command.
+

src/docs/userguide/arcanist_new_project.diviner

@@ -50,3 +50,52 @@ Other options include:
   - **copyright_holder**: used by @{class@arcanist:ArcanistLicenseLinter} to
     apply license notices to source files.
   - **phutil_libraries**: map of additional Phutil libraries to load at startup.
+    See below for details about path resolution, or see
+    @{article:libphutil Libraries User Guide} for a general introduction to
+    libphutil libraries.
+
+= How Libraries Are Located =
+
+If you specify an external library to load, like 'examplelib', and use a
+relative path like this:
+
+  {
+    ...
+    "load_libraries": {
+      "examplelib" : "examplelib/src"
+    },
+    ...
+  }
+
+...arc looks for it by trying these paths:
+
+  - `path/to/root/examplelib/src/` First, arc looks in the project's root
+    directory (where the .arcconfig lives) to see if the library is part of
+    the project. This makes it easy to just put project-specific code in a
+    project.
+  - `path/to/root/../examplelib/src/` Next, arc looks //next to// the project's
+    root directory to see if the library is in a sibling directory. If you
+    work with several repositories, this makes it easy to put all the `arc`
+    code in one repository and just check it out in the same directory as
+    everything else.
+  - `php/include/path/examplelib/src` Finally, arc falls back to PHP, which
+    will look in paths described in the `include_path` php.ini setting. This
+    allows you to install libraries in some global location if you prefer.
+
+You can alternately supply an absolute path, like `/var/arc/examplelib/src`, but
+then everyone will need to install the library at that exact location.
+
+NOTE: Specify the path to the directory which includes
+`__phutil_library_init__.php`. For example, if your init file is in
+`examplelib/src/__phutil_library_init__.php`, specify `examplelib/src`,
+not just `examplelib/`.
+
+The general intent here is:
+
+  - Put project-specific code in some directory in the project, like
+    `support/arc/src/`.
+  - Put shared code (e.g., which enforces general coding standards or hooks
+    up to unit tests or whatever) in a separate repository and check it out
+    next to other repositories.
+  - Or put everything in some standard location and add it to `include_path`.
+