3 files changed, 131 insertions, 0 deletions
diff --git a/doc/src/guide/book.asciidoc b/doc/src/guide/book.asciidoc
index 4a29e83..9e23082 100644
--- a/doc/src/guide/book.asciidoc
+++ b/doc/src/guide/book.asciidoc
@@ -10,6 +10,8 @@ include::overview.asciidoc[Overview]
 
 include::updating.asciidoc[Updating Erlang.mk]
 
+include::limitations.asciidoc[Limitations]
+
 = Code
 
 include::app.asciidoc[Building]
@@ -17,3 +19,7 @@ include::app.asciidoc[Building]
 = Advanced
 
 include::external_plugins.asciidoc[External plugins]
+
+= About Erlang.mk
+
+include::why.asciidoc[Why erlang.mk?]
diff --git a/doc/src/guide/limitations.asciidoc b/doc/src/guide/limitations.asciidoc
new file mode 100644
index 0000000..86ca918
--- /dev/null
+++ b/doc/src/guide/limitations.asciidoc
@@ -0,0 +1,45 @@
+== Limitations
+
+No software is perfect.
+
+It's very important, when evaluating and when using a tool,
+to understand its limitations, so as to avoid making mistakes
+and wasting valuable time.
+
+This chapter lists all known limitations of Erlang.mk.
+
+=== Erlang must be available
+
+Currently Erlang.mk requires you to install Erlang beforehand.
+Installing Erlang is not always easy, particularly if you need
+a specific version of Erlang for a specific project.
+
+In addition, the Erlang being used must be in your `$PATH`
+before you use Erlang.mk.
+
+In the future we envision, Erlang.mk could manage the Erlang
+version you need to use a project. Erlang.mk already does this
+for running tests when using `make ci`, so doing this during
+development is just a step away.
+
+=== Spaces in path
+
+Erlang.mk will currently not work properly if the path to the
+project contains spaces. To check if that is the case, use the
+command `pwd`.
+
+This issue is due to how Makefiles work. There might be ways
+to solve it, we have not given up on it, but it's very low
+priority considering how simple the workaround is.
+
+=== Dependency tracking and modification times
+
+Erlang source files that depend on other files will have their
+modification time updated when they need to be recompiled due
+to a dependency having changed. This could cause some editors to
+think the file changed when it didn't.
+
+Erlang.mk must use this method in order to be able to compile
+files in one `erlc` invocation. The benefits greatly outweigh
+the issue in this case and so there are currently no plans to
+fix this behavior.
diff --git a/doc/src/guide/why.asciidoc b/doc/src/guide/why.asciidoc
new file mode 100644
index 0000000..37aa676
--- /dev/null
+++ b/doc/src/guide/why.asciidoc
@@ -0,0 +1,80 @@
+== Why Erlang.mk
+
+Why would you choose Erlang.mk, if not for its
+link:overview.asciidoc[many features]? This chapter will
+attempt to answer that.
+
+=== Erlang.mk is fast
+
+Erlang.mk is as fast as it gets.
+
+Erlang.mk will group the compilation of files so as to avoid
+running the BEAM more than necessary. This saves many seconds
+compared to traditional Makefiles, even on small projects.
+
+Erlang.mk will not try to be too smart. It provides a simple
+solution that works for most people, and gives additional
+options for projects that run into edge cases, often in the
+form of extra variables or rules to be defined.
+
+=== Erlang.mk gives you the full power of Unix
+
+Erlang.mk is a Makefile.
+
+You could use Erlang.mk directly without configuring anything
+and it would just work. But you can also extend it greatly
+either through configuration or hooks, and you can of course
+add your own rules to the Makefile.
+
+In all cases: for configuration, hooks or custom rules, you
+have all the power of Unix at your disposal, and can call
+any utility _or even any language interpreter_ you want,
+every time you need to. Erlang.mk also allows you to write
+scripts in this small language called Erlang directly inside
+your Makefile if you ever need to...
+
+=== Erlang.mk is a text file
+
+Erlang.mk is a Makefile.
+
+Which means Erlang.mk is a simple text file. You can edit a
+text file. Nothing stops you. If you run into any bug, or
+behavior that does not suit you, you can just open the
+'erlang.mk' file in your favorite editor, fix and/or comment
+a few lines, save, and try again. It's as simple as it gets.
+
+Currently using a binary build tool? Good luck with that.
+
+=== Erlang.mk can manage Erlang itself
+
+Erlang.mk isn't written in Erlang.
+
+That's not a good thing, you say? Well, here's one thing
+that Erlang.mk and Makefiles can do for you that Erlang
+build tool can't easily: choose what version of Erlang is
+to be used for compiling the project.
+
+This really is a one-liner in Erlang.mk (a few more lines
+if you also let it download about build Erlang directly)
+and allows for even greater things, like testing your
+project across all supported Erlang versions in one small
+command: `make -k ci`.
+
+=== Erlang.mk can do more than Erlang
+
+Erlang.mk doesn't care what your dependencies are written in.
+
+Erlang.mk will happily compile any dependency, as long as
+they come with a Makefile. The dependency can be written
+in C, C++ or even Javascript... Who cares, really? If you
+need Erlang.mk to fetch it, then Erlang.mk will fetch it
+and compile it as needed.
+
+=== Erlang.mk integrates nicely in Make and Automake projects
+
+If you are planning to put your project in the middle of
+a Make or Automake-based build environment, then the most
+logical thing to do is to use a Makefile.
+
+Erlang.mk will happily sit in such an environment and behave
+as you expect it to.