9 files changed, 155 insertions, 18 deletions
diff --git a/doc/src/guide/asciidoc.asciidoc b/doc/src/guide/asciidoc.asciidoc
index 2fca131..cc8336b 100644
--- a/doc/src/guide/asciidoc.asciidoc
+++ b/doc/src/guide/asciidoc.asciidoc
@@ -1,6 +1,82 @@
 [[asciidoc]]
-== Asciidoc documentation
+== AsciiDoc documentation
 
-// @todo Write it.
+Erlang.mk provides rules for generating documentation from
+AsciiDoc files. It can automatically build a user guide PDF,
+chunked HTML documentation and Unix manual pages.
 
-Placeholder chapter.
+=== Requirements
+
+It is necessary to have http://asciidoc.org/[AsciiDoc], 
+http://xmlsoft.org/XSLT/xsltproc2.html[xsltproc] and
+http://dblatex.sourceforge.net/[dblatex] installed on your
+system for Erlang.mk to generate documentation from AsciiDoc sources.
+
+=== Writing AsciiDoc documentation
+
+http://asciidoc.org/[AsciiDoc] is a text document format for
+writing notes, documentation, articles, books, ebooks, slideshows,
+web pages, man pages and blogs. AsciiDoc files can be translated
+to many formats including HTML, PDF, EPUB, man page.
+
+The http://asciidoc.org/userguide.html[AsciiDoc user guide]
+describes the AsciiDoc syntax.
+
+The https://github.com/ninenines/erlang.mk/tree/master/doc/src/guide[Erlang.mk user guide]
+is written in AsciiDoc and can be used as an example. The entry
+file is https://github.com/ninenines/erlang.mk/blob/master/doc/src/guide/book.asciidoc[book.asciidoc].
+
+Erlang.mk expects you to put your documentation in a specific
+location. This is 'doc/src/guide/' for the user guide, and
+'doc/src/manual/' for the function reference. In the case of
+the user guide, the entry point is always 'doc/src/guide/book.asciidoc'.
+
+For manual pages, it is good practice to use section 3 for
+modules, and section 7 for the application itself.
+
+=== Configuration
+
+All of the AsciiDoc related configuration can be done directly
+inside the files themselves.
+
+=== Usage
+
+To build all documentation:
+
+[source,bash]
+$ make docs
+
+To build only the AsciiDoc documentation:
+
+[source,bash]
+$ make asciidoc
+
+To build only the user guide:
+
+[source,bash]
+$ make asciidoc-guide
+
+To build only the manual:
+
+[source,bash]
+$ make asciidoc-manual
+
+To install man pages on Unix:
+
+[source,bash]
+$ make install-docs
+
+Erlang.mk allows customizing the installation path and sections
+of the man pages to be installed. The `MAN_INSTALL_PATH` variable
+defines where man pages will be installed. It defaults to
+'/usr/local/share/man'. The `MAN_SECTIONS` variable defines
+which manual sections are to be installed. It defaults to `3 7`.
+
+To install man pages to a custom location:
+
+[source,bash]
+$ make install-docs MAN_INSTALL_PATH=/opt/share/man
+
+Note that you may need to run the install commands using
+`sudo` or equivalent if the location is not writeable by
+your user.
diff --git a/doc/src/guide/book.asciidoc b/doc/src/guide/book.asciidoc
index ebef8b7..a39b907 100644
--- a/doc/src/guide/book.asciidoc
+++ b/doc/src/guide/book.asciidoc
@@ -46,8 +46,6 @@ include::eunit.asciidoc[EUnit]
 
 include::common_test.asciidoc[Common Test]
 
-include::property_based_testing.asciidoc[Property based testing]
-
 include::coverage.asciidoc[Code coverage]
 
 include::ci.asciidoc[Continuous integration]
diff --git a/doc/src/guide/contributing.asciidoc b/doc/src/guide/contributing.asciidoc
index 968ea3e..58e5de6 100644
--- a/doc/src/guide/contributing.asciidoc
+++ b/doc/src/guide/contributing.asciidoc
@@ -100,7 +100,8 @@ this is a bug. You can either open a ticket or send a pull
 request.
 
 To make sure that the documentation changes work, install
-Asciidoc on your system and run `make docs`.
+the listed xref:asciidoc[Requirements] on your system and
+run `make docs`.
 
 === Feature requests
 
diff --git a/doc/src/guide/deps.asciidoc b/doc/src/guide/deps.asciidoc
index be7ed52..eb6f2f0 100644
--- a/doc/src/guide/deps.asciidoc
+++ b/doc/src/guide/deps.asciidoc
@@ -334,7 +334,7 @@ Erlang.mk will also export the `REBAR_DEPS_DIR` variable for
 compatibility with Rebar build tools, as long as they are
 recent enough.
 
-=== Dependencies local to the repository
+=== Many applications in one repository
 
 In addition to the dependencies that are fetched, Erlang.mk
 also allows you to have dependencies local to your repository.
diff --git a/doc/src/guide/edoc.asciidoc b/doc/src/guide/edoc.asciidoc
index 7827692..9fc1a74 100644
--- a/doc/src/guide/edoc.asciidoc
+++ b/doc/src/guide/edoc.asciidoc
@@ -1,6 +1,48 @@
 [[edoc]]
 == EDoc comments
 
-// @todo Write it.
+Erlang.mk provides a thin wrapper on top of EDoc, an application
+that generates documentation based on comments found in modules.
 
-Placeholder chapter.
+=== Writing EDoc comments
+
+The http://www.erlang.org/doc/apps/edoc/chapter.html[EDoc user guide]
+explains everything you need to know about EDoc comments.
+
+=== Configuration
+
+The `EDOC_OPTS` variable allows you to specify additional
+EDoc options. Options are documented in the
+http://www.erlang.org/doc/man/edoc.html#run-2[EDoc manual].
+
+A common use for this variable is to enable Markdown in doc
+comments, using the `edown` application:
+
+[source,make]
+DOC_DEPS = edown
+EDOC_OPTS = {doclet, edown_doclet}
+
+=== Usage
+
+To build all documentation, you would typically use:
+
+[source,bash]
+$ make docs
+
+Do note, however, that EDoc comments will only be generated
+automatically if the 'doc/overview.edoc' file exists. If you
+do not want that file and still want to generate doc comments,
+two solutions are available.
+
+You can generate EDoc documentation directly:
+
+[source,bash]
+$ make edoc
+
+You can enable automatic generation on `make docs` by adding
+the following to your Makefile:
+
+[source,make]
+----
+docs:: edoc
+----
diff --git a/doc/src/guide/external_plugins_list.asciidoc b/doc/src/guide/external_plugins_list.asciidoc
index 9d38f8d..f30797f 100644
--- a/doc/src/guide/external_plugins_list.asciidoc
+++ b/doc/src/guide/external_plugins_list.asciidoc
@@ -4,6 +4,11 @@
 This is a non-exhaustive list of Erlang.mk plugins, sorted
 alphabetically.
 
+=== efene.mk
+
+An https://github.com/ninenines/efene.mk[Efene plugin] for Erlang.mk.
+http://efene.org/[Efene] is an alternative language for the BEAM.
+
 === elixir.mk
 
 An https://github.com/botsunit/elixir.mk[Elixir plugin] for
@@ -32,6 +37,12 @@ An https://github.com/ninenines/lfe.mk[LFE plugin] for Erlang.mk.
 LFE, or http://lfe.io/[Lisp Flavoured Erlang], is an alternative
 language for the BEAM.
 
+=== mix.mk
+
+A https://github.com/botsunit/mix.mk[Mix plugin] for Erlang.mk,
+to generate a compatible configuration file for
+http://elixir-lang.org/getting-started/mix-otp/introduction-to-mix.html[Mix].
+
 === reload.mk
 
 A https://github.com/bullno1/reload.mk[live reload plugin] for Erlang.mk.
diff --git a/doc/src/guide/getting_started.asciidoc b/doc/src/guide/getting_started.asciidoc
index 04147b0..ef2f6e8 100644
--- a/doc/src/guide/getting_started.asciidoc
+++ b/doc/src/guide/getting_started.asciidoc
@@ -237,6 +237,23 @@ $ make
 All that's left to do is to open it in your favorite editor
 and make it do something!
 
+=== Hiding Erlang.mk from git
+
+Erlang.mk is a large text file. It can easily take a large part of
+a `git diff` or a `git grep` command. You can avoid this by telling
+Git that 'erlang.mk' is a binary file.
+
+Add this to your '.gitattributes' file. This is a file that you
+can create at the root of your repository:
+
+----
+erlang.mk -diff
+----
+
+The 'erlang.mk' file will still appear in diffs and greps, but
+as a binary file, meaning its contents won't be shown by default
+anymore.
+
 === Getting help
 
 During development, if you don't remember the name of a target,
diff --git a/doc/src/guide/overview.asciidoc b/doc/src/guide/overview.asciidoc
index 3e22790..8fa57fe 100644
--- a/doc/src/guide/overview.asciidoc
+++ b/doc/src/guide/overview.asciidoc
@@ -68,9 +68,7 @@ The xref:shell[make shell] command allows you
 to test your project manually. You can automate these
 unit tests with xref:eunit[EUnit] and test
 your entire system with xref:ct[Common Test].
-xref:property_based_testing[Property based testing]
-with Triq is a strong alternative to writing unit tests
-manually. xref:coverage[Code coverage] can of course
+xref:coverage[Code coverage] can of course
 be enabled during tests.
 
 Erlang.mk comes with features to make your life easier when
diff --git a/doc/src/guide/property_based_testing.asciidoc b/doc/src/guide/property_based_testing.asciidoc
deleted file mode 100644
index 0adacbd..0000000
--- a/doc/src/guide/property_based_testing.asciidoc
+++ /dev/null
@@ -1,6 +0,0 @@
-[[property_based_testing]]
-== Property based testing
-
-// @todo Write it.
-
-Placeholder chapter.