Add first three chapters of new documentation

7 files changed, 430 insertions, 0 deletions

diff --git a/.gitignore b/.gitignore
index 30d0d8e..3d5a519 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,3 +1,5 @@
+doc/guide.pdf
+doc/html
 test/app1/
 test/pkgs.log
 test/temp-python/
diff --git a/Makefile b/Makefile
index 9e71e35..625a38e 100644
--- a/Makefile
+++ b/Makefile
@@ -31,3 +31,6 @@ else
 check:
 	$(MAKE) -C test pkg-$(p)
 endif
+
+docs:
+	$(MAKE) -f core/core.mk -f core/docs.mk -f plugins/asciidoc.mk asciidoc
diff --git a/README.md b/README.md
index cf0551d..5557282 100644
--- a/README.md
+++ b/README.md
@@ -5,6 +5,8 @@ Common Makefile rules for building and testing Erlang applications.
 
 Also features support for dependencies and a package index.
 
+[Check out our upcoming documentation!](doc/src/guide/book.asciidoc)
+
 Why erlang.mk?
 --------------
 
diff --git a/doc/src/guide/book.asciidoc b/doc/src/guide/book.asciidoc
new file mode 100644
index 0000000..e858ae8
--- /dev/null
+++ b/doc/src/guide/book.asciidoc
@@ -0,0 +1,11 @@
+// a2x: --dblatex-opts "-P latex.output.revhistory=0 -P doc.publisher.show=0 -P index.numbered=0"
+// a2x: -d book --attribute tabsize=4
+
+= Erlang.mk User Guide
+Loïc Hoguin <[email protected]>
+
+include::getting_started.asciidoc[Getting started]
+
+include::overview.asciidoc[Overview]
+
+include::updating.asciidoc[Updating Erlang.mk]
diff --git a/doc/src/guide/getting_started.asciidoc b/doc/src/guide/getting_started.asciidoc
new file mode 100644
index 0000000..3fd9ebd
--- /dev/null
+++ b/doc/src/guide/getting_started.asciidoc
@@ -0,0 +1,262 @@
+== Getting started
+
+This chapter explains how to get started using Erlang.mk.
+
+=== Creating a folder for your project
+
+The first step is always to create a new folder that will
+contain your project.
+
+[source,bash]
+$ mkdir hello_joe
+$ cd hello_joe
+
+Most people tend to put all their projects side by side in
+a common folder. We recommend keeping an organization similar
+to your remote repositories. For example, for GitHub users,
+put all your projects in a common folder with the same name
+as your username. For example '$HOME/ninenines/cowboy' for
+the Cowboy project.
+
+=== Downloading Erlang.mk
+
+At the time of writing, Erlang.mk is unlikely to be present
+in your Erlang distribution, or even in your OS packages.
+
+The next step is therefore to download it:
+
+[source,bash]
+$ wget https://raw.githubusercontent.com/ninenines/erlang.mk/master/erlang.mk
+
+Or:
+
+[source,bash]
+$ curl https://raw.githubusercontent.com/ninenines/erlang.mk/master/erlang.mk
+
+Alternatively, just https://raw.githubusercontent.com/ninenines/erlang.mk/master/erlang.mk[click on this link].
+
+Make sure you put the file inside the folder we created previously.
+
+=== Getting started with OTP applications
+
+An OTP application is an Erlang application that has a supervision
+tree. In other words, it will always have processes running.
+
+This kind of project can be automatically generated by Erlang.mk.
+All you need to do is use the `bootstrap` target:
+
+[source,bash]
+$ make -f erlang.mk bootstrap
+
+Something similar to the following snippet will then appear
+on your screen:
+
+[source,bash]
+----
+git clone https://github.com/ninenines/erlang.mk .erlang.mk.build
+Cloning into '.erlang.mk.build'...
+remote: Counting objects: 4035, done.
+remote: Compressing objects: 100% (12/12), done.
+remote: Total 4035 (delta 8), reused 4 (delta 4), pack-reused 4019
+Receiving objects: 100% (4035/4035), 1.10 MiB | 784.00 KiB/s, done.
+Resolving deltas: 100% (2442/2442), done.
+Checking connectivity... done.
+if [ -f build.config ]; then cp build.config .erlang.mk.build; fi
+cd .erlang.mk.build && make
+make[1]: Entering directory '/home/essen/tmp/hello_joe/.erlang.mk.build'
+awk 'FNR==1 && NR!=1{print ""}1' core/core.mk index/*.mk core/index.mk core/deps.mk plugins/protobuffs.mk core/erlc.mk core/docs.mk core/test.mk plugins/asciidoc.mk plugins/bootstrap.mk plugins/c_src.mk plugins/ci.mk plugins/ct.mk plugins/dialyzer.mk plugins/edoc.mk plugins/elvis.mk plugins/erlydtl.mk plugins/escript.mk plugins/eunit.mk plugins/relx.mk plugins/shell.mk plugins/triq.mk plugins/xref.mk plugins/cover.mk \
+	| sed 's/^ERLANG_MK_VERSION = .*/ERLANG_MK_VERSION = 1.2.0-642-gccd2b9f/' > erlang.mk
+make[1]: Leaving directory '/home/essen/tmp/hello_joe/.erlang.mk.build'
+cp .erlang.mk.build/erlang.mk ./erlang.mk
+rm -rf .erlang.mk.build
+----
+
+This is Erlang.mk bootstrapping itself. Indeed, the file you
+initially downloaded contains nothing more than the code needed
+to bootstrap. This operation is done only once. Consult the
+link:updating.asciidoc[Updating Erlang.mk] chapter for more
+information.
+
+Of course, the generated project can now be compiled:
+
+[source,bash]
+$ make
+
+Cheers!
+
+=== Getting started with OTP libraries
+
+An OTP library is an Erlang application that has no supervision
+tree. In other words, it is nothing but modules.
+
+This kind of project can also be generated by Erlang.mk, using
+the `bootstrap-lib` target:
+
+[source,bash]
+$ make -f erlang.mk bootstrap-lib
+
+Erlang.mk will once again bootstrap itself and generate all
+the files for your project. You can now compile it:
+
+[source,bash]
+$ make
+
+Enjoy!
+
+=== Getting started with OTP releases
+
+An OTP release is the combination of the Erlang RunTime System (ERTS)
+along with all the libraries and files that your node will need
+to run. It is entirely self contained, and can often be sent as-is
+to your production system and run without any extra setup.
+
+Erlang.mk can of course bootstrap your project to generate releases.
+You can use the `bootstrap-rel` target for this purpose:
+
+[source,bash]
+$ make bootstrap-rel
+
+This target can be combined with `bootstrap` or `bootstrap-lib` to
+create a project that will build a release:
+
+[source,bash]
+$ make -f erlang.mk bootstrap-lib bootstrap-rel
+
+It is often very useful to keep the top-level project for
+commands useful during operations, and put the components
+of the system in separate applications that you will then
+depend on. Consult the link:deps.asciidoc[Packages and dependencies]
+chapter for more information.
+
+When you run `make` from now on, Erlang.mk will compile your
+project and build the release:
+
+[source,bash]
+$ make
+ APP    hello_joe.app.src
+ GEN    distclean-relx-rel
+ GEN    /home/essen/tmp/hello_joe/relx
+===> Starting relx build process ...
+===> Resolving OTP Applications from directories:
+          /home/essen/tmp/hello_joe/ebin
+          /usr/lib/erlang/lib
+          /home/essen/tmp/hello_joe/deps
+===> Resolved hello_joe_release-1
+===> Including Erts from /usr/lib/erlang
+===> release successfully created!
+
+The first time you run this command, Erlang.mk will download
+_relx_, the release building tool. So don't worry if you see
+more output than above.
+
+If building the release is slow, no need to upgrade your
+hardware just yet. Just consult the link:relx.asciidoc[Releases]
+chapter for various tips to speed up build time during
+development.
+
+You can start the release using the './_rel/hello_joe_release/bin/hello_joe_release'
+script, or simply run `make run`. The latter will also compile
+your project and build the release if it wasn't already:
+
+[source,bash]
+----
+$ make run
+ APP    hello_joe.app.src
+ GEN    distclean-relx-rel
+===> Starting relx build process ...
+===> Resolving OTP Applications from directories:
+          /home/essen/tmp/hello_joe/ebin
+          /usr/lib/erlang/lib
+          /home/essen/tmp/hello_joe/deps
+===> Resolved hello_joe_release-1
+===> Including Erts from /usr/lib/erlang
+===> release successfully created!
+Exec: /home/essen/tmp/hello_joe/_rel/hello_joe_release/erts-7.0/bin/erlexec -boot /home/essen/tmp/hello_joe/_rel/hello_joe_release/releases/1/hello_joe_release -boot_var ERTS_LIB_DIR /home/essen/tmp/hello_joe/_rel/hello_joe_release/erts-7.0/../lib -env ERL_LIBS /home/essen/tmp/hello_joe/_rel/hello_joe_release/releases/1/lib -config /home/essen/tmp/hello_joe/_rel/hello_joe_release/releases/1/sys.config -args_file /home/essen/tmp/hello_joe/_rel/hello_joe_release/releases/1/vm.args -- console
+Root: /home/essen/tmp/hello_joe/_rel/hello_joe_release
+/home/essen/tmp/hello_joe/_rel/hello_joe_release
+heart_beat_kill_pid = 16389
+Erlang/OTP 18 [erts-7.0] [source] [64-bit] [smp:4:4] [async-threads:10] [hipe] [kernel-poll:false]
+
+Eshell V7.0  (abort with ^G)
+([email protected])1> 
+----
+
+Simple as that!
+
+=== Using templates
+
+It is no secret that Erlang's OTP behaviors tend to have some
+boilerplate. It is rarely an issue of course, except when
+creating new modules. That's why Erlang.mk not only comes with
+templates for generating projects, but also individual modules!
+
+You can list all available templates with the `list-templates`
+target:
+
+[source,bash]
+$ make list-templates
+Available templates: cowboy_http cowboy_loop cowboy_rest cowboy_ws gen_fsm gen_server ranch_protocol supervisor
+
+To generate a module, let's say a `gen_server`, all you need to
+do is to call `make new` with the appropriate arguments:
+
+[source,bash]
+$ make new t=gen_server n=my_server
+
+This will create a module located in 'src/my_server.erl'
+using the `gen_server` template.
+
+This module is automatically compiled the next time you run
+`make`:
+
+[source,bash]
+$ make
+ ERLC   my_server.erl
+ APP    hello_joe.app.src
+
+All that's left to do is to open it in your favorite editor
+and make it do something!
+
+=== Getting help
+
+During development, if you don't remember the name of a target,
+you can always run `make help`:
+
+[source,bash]
+----
+$ make help
+erlang.mk (version 1.2.0-642-gccd2b9f) is distributed under the terms of the ISC License.
+Copyright (c) 2013-2015 Loïc Hoguin <[email protected]>
+
+Usage: [V=1] make [-jNUM] [target]...
+
+Core targets:
+  all           Run deps, app and rel targets in that order
+  app           Compile the project
+  deps          Fetch dependencies (if needed) and compile them
+  search q=...  Search for a package in the built-in index
+  rel           Build a release for this project, if applicable
+  docs          Build the documentation for this project
+  install-docs  Install the man pages for this project
+  check         Compile and run all tests and analysis for this project
+  tests         Run the tests for this project
+  clean         Delete temporary and output files from most targets
+  distclean     Delete all temporary and output files
+  help          Display this help and exit
+  erlang-mk     Update erlang.mk to the latest version
+
+Bootstrap targets:
+  bootstrap          Generate a skeleton of an OTP application
+  bootstrap-lib      Generate a skeleton of an OTP library
+  bootstrap-rel      Generate the files needed to build a release
+  new t=TPL n=NAME   Generate a module NAME based on the template TPL
+  list-templates     List available templates
+...
+----
+
+This guide should provide any other answer. If not, please
+open a ticket on https://github.com/ninenines/erlang.mk/issues[the official repository]
+and we will work on improving the guide.
+
+Commercial support is available through Nine Nines. Please contact
+Loïc Hoguin by sending an email to mailto:[email protected][].
diff --git a/doc/src/guide/overview.asciidoc b/doc/src/guide/overview.asciidoc
new file mode 100644
index 0000000..a81dd7a
--- /dev/null
+++ b/doc/src/guide/overview.asciidoc
@@ -0,0 +1,88 @@
+== Overview
+
+Now that you know how to get started, let's take a look at
+what Erlang.mk can do for you.
+
+=== Building your project
+
+Erlang.mk is first and foremost a build tool. It is especially
+tailored for Erlang developers and follows widely accepted
+practices in the Erlang community.
+
+Erlang.mk will happily build all link:app.asciidoc[Erlang-specific files]
+you throw at it. Other kinds of files too, like C or C++ code
+when you are working on link:ports.asciidoc[a NIF or a port driver].
+
+Erlang.mk embraces the concept of link:deps.asciidoc[source dependencies].
+It can fetch dependency source code using a variety of mechanisms,
+including fetching from Git, Mercurial or SVN.
+
+Erlang.mk will automatically link:relx.asciidoc[generate releases]
+when applicable. It can also link:escripts.asciidoc[generate escripts].
+
+=== Exploring the package index
+
+Erlang.mk comes with a link:deps.asciidoc[built-in package index].
+It is built as an extension of the dependency system and is
+meant to be used for discovery purposes.
+
+No package is ever installed, they are only used as dependencies
+and are always project-specific. They can be thought of as a
+shortcut over plain dependencies.
+
+You can get a list of all packages known to Erlang.mk by using
+the `search` target:
+
+[source,bash]
+$ make search
+
+You can also use this target to search across all packages, for
+example to find all packages related to Cowboy:
+
+[source,bash]
+$ make search q=cowboy
+
+=== Generating documentation
+
+Erlang.mk supports _EDoc_ and _Asciidoc_.
+
+link:edoc.asciidoc[EDoc] generates HTML documentation directly from
+your source code.
+
+While it is convenient, ask yourself: if all the documentation is
+inside the source code, why not just open the source code directly?
+That's where _Asciidoc_ comes in.
+
+The link:asciidoc.asciidoc[Asciidoc] plugin expects all documentation
+to be separate from source. It will generate HTML, PDF, man pages and
+more from the documentation you write in the 'doc/src/' folder in
+your repository.
+
+=== Running tests
+
+Erlang.mk supports a lot of different testing and static
+analysis tools.
+
+The link:shell.asciidoc[make shell] command allows you
+to test your project manually. You can automate these
+unit tests with link:eunit.asciidoc[EUnit] and test
+your entire system with link:common_test.asciidoc[Common Test].
+link:property_based_testing.asciidoc[Property based testing]
+with Triq is a strong alternative to writing unit tests
+manually. link:coverage.asciidoc[Code coverage] can of course
+be enabled during tests.
+
+Erlang.mk comes with features to make your life easier when
+setting up and using link:ci.asciidoc[Continuous integration].
+
+On the static analysis side of things, Erlang.mk comes with
+support for link:dialyzer.asciidoc[Dialyzer], link:xref.asciidoc[Xref]
+and link:elvis.asciidoc[Elvis], performing success typing
+analysis, cross reference and style reviewing.
+
+=== Need more?
+
+Not convinced yet? You can read about link:why.asciidoc[why you should use Erlang.mk]
+and its link:history.asciidoc[history]. And if you're still not
+convinced after that, it's OK! The world would be boring if
+everyone agreed on everything all the time.
diff --git a/doc/src/guide/updating.asciidoc b/doc/src/guide/updating.asciidoc
new file mode 100644
index 0000000..ecd4a70
--- /dev/null
+++ b/doc/src/guide/updating.asciidoc
@@ -0,0 +1,62 @@
+== Updating Erlang.mk
+
+This chapter describes how to update the 'erlang.mk' file
+in your repository.
+
+=== Initial bootstrap
+
+The first time you use Erlang.mk, it will bootstrap itself.
+It always uses the most recent version for this, so you don't
+have to update after creating your project.
+
+=== Updating
+
+Later on though, updating becomes a necessity. Erlang.mk
+developers and contributors relentlessly improve the project
+and add new features; it would be a waste not to benefit
+from this.
+
+That's why updating Erlang.mk is so simple. All you need
+to do is to call `make erlang-mk`:
+
+[source,bash]
+----
+$ make erlang-mk
+git clone https://github.com/ninenines/erlang.mk .erlang.mk.build
+Cloning into '.erlang.mk.build'...
+remote: Counting objects: 4035, done.
+remote: Compressing objects: 100% (12/12), done.
+remote: Total 4035 (delta 8), reused 4 (delta 4), pack-reused 4019
+Receiving objects: 100% (4035/4035), 1.10 MiB | 1000.00 KiB/s, done.
+Resolving deltas: 100% (2442/2442), done.
+Checking connectivity... done.
+if [ -f build.config ]; then cp build.config .erlang.mk.build; fi
+cd .erlang.mk.build && make
+make[1]: Entering directory '/home/essen/tmp/emkg/hello_joe/.erlang.mk.build'
+awk 'FNR==1 && NR!=1{print ""}1' core/core.mk index/*.mk core/index.mk core/deps.mk plugins/protobuffs.mk core/erlc.mk core/docs.mk core/test.mk plugins/asciidoc.mk plugins/bootstrap.mk plugins/c_src.mk plugins/ci.mk plugins/ct.mk plugins/dialyzer.mk plugins/edoc.mk plugins/elvis.mk plugins/erlydtl.mk plugins/escript.mk plugins/eunit.mk plugins/relx.mk plugins/shell.mk plugins/triq.mk plugins/xref.mk plugins/cover.mk \
+	| sed 's/^ERLANG_MK_VERSION = .*/ERLANG_MK_VERSION = 1.2.0-642-gccd2b9f/' > erlang.mk
+make[1]: Leaving directory '/home/essen/tmp/emkg/hello_joe/.erlang.mk.build'
+cp .erlang.mk.build/erlang.mk ./erlang.mk
+rm -rf .erlang.mk.build
+----
+
+All that's left to do is to commit the file!
+
+Yep, it's that easy.
+
+=== Customizing the build
+
+Erlang.mk allows you to customize which plugins are to be included
+in the 'erlang.mk' file. You can do so by maintaining your own
+'build.config' file in your repository. Erlang.mk will automatically
+use it the next time you run `make erlang-mk`.
+
+The 'build.config' file contains the list of all files that will
+be built into the resulting 'erlang.mk' file. You can start from
+the https://github.com/ninenines/erlang.mk/blob/master/build.config[most recent version]
+and customize to your needs.
+
+You can also name the file differently or put it in a separate folder
+by modifying the value for `ERLANG_MK_BUILD_CONFIG`. You can also
+tell Erlang.mk to use a different temporary directory by changing
+the `ERLANG_MK_BUILD_DIR` variable.