Improve docs for archives

Signed-off-by: José Valim <jose.valim@plataformatec.com.br>

Author: José Valim

lib/mix/lib/mix/tasks/archive.build.ex

@@ -7,14 +7,24 @@ defmodule Mix.Tasks.Archive.Build do
   Builds an archive according to the specification of the
   [Erlang Archive Format](http://www.erlang.org/doc/man/code.html).
 
+  Archives are meant to contain small projects, usually installed
+  locally. Archives may be installed into a Mix environment by
+  running `mix archive.install`. Once installed, the archive is
+  available to all Mix projects. For this reason, the functionality
+  behind archives is limited. For instance, archives do not include
+  dependencies, as those would conflict with any dependency in a
+  Mix project after the archive is installed. In general, we recommend
+  the usage of archives to be limited for extensions of Mix, such
+  as custom SCMs, package managers, etc. For general scripts to be
+  installed into machines, please see `mix escript.build`.
+
   The archive will be created in the current directory (which is
   expected to be the project root), unless an argument `-o` is
   provided with the file name.
 
-  Archives are meant to contain small projects, usually installed
-  locally.  By default, this command archives the current project
-  but the `-i` and `-o` options can be used to archive any directory.
-  For example, `mix archive.build` with no options translates to:
+  By default, this command archives the current project but the `-i`
+  option can be used to archive any directory. For example,
+  `mix archive.build` with no options translates to:
 
       mix archive.build -i _build/ENV/lib/APP -o APP-VERSION.ez
 

lib/mix/lib/mix/tasks/archive.install.ex

@@ -6,14 +6,15 @@ defmodule Mix.Tasks.Archive.Install do
   @moduledoc """
   Installs an archive locally.
 
-  If no argument is supplied but there is an archive in the project's root directory
-  (created with `mix archive.build`), then the archive will be installed
-  locally. For example:
+  If no argument is supplied but there is an archive in the project's
+  root directory (created with `mix archive.build`), then the archive
+  will be installed locally. For example:
 
       mix do archive.build, archive.install
 
-  If an argument is provided, it should be a local path or a URL to a prebuilt archive,
-  a git repository, a github repository, or a hex package.
+  If an argument is provided, it should be a local path or a URL to a
+  prebuilt archive, a git repository, a github repository, or a hex
+  package.
 
       mix archive.install archive.ez
       mix archive.install path/to/archive.ez