8 files changed, 34 insertions, 33 deletions
diff --git a/doc/src/guide/app.asciidoc b/doc/src/guide/app.asciidoc
index 43582d2..99ff052 100644
--- a/doc/src/guide/app.asciidoc
+++ b/doc/src/guide/app.asciidoc
@@ -77,7 +77,7 @@ $ make deps
 This will fetch and compile all dependencies and their
 dependencies, recursively.
 
-link:deps.asciidoc[Packages and dependencies] are covered
+xref:deps[Packages and dependencies] are covered
 in the next chapter.
 
 ==== Release
@@ -94,7 +94,7 @@ the application and all dependencies:
 [source,bash]
 $ make rel
 
-Consult the link:releases.asciidoc[Releases] chapter for more
+Consult the xref:relx[Releases] chapter for more
 information about what releases are and how they are generated.
 
 === Application resource file
@@ -152,7 +152,7 @@ DEPS = cowlib ranch
 
 Any space before and after the value is dropped.
 
-link:deps.asciidoc[Dependencies] are covered in details in
+xref:deps[Dependencies] are covered in details in
 the next chapter.
 
 ==== Legacy method
@@ -225,7 +225,7 @@ then built normally.
 
 In addition, Erlang.mk keeps track of header files (`.hrl`)
 as described at the end of this chapter. It can also compile
-C code, as described in the link:ports.asciidoc[NIFs and port drivers]
+C code, as described in the xref:ports[NIFs and port drivers]
 chapter.
 
 Erlang.mk also comes with plugins for the following formats:
diff --git a/doc/src/guide/common_test.asciidoc b/doc/src/guide/common_test.asciidoc
index 2ef1675..aec8747 100644
--- a/doc/src/guide/common_test.asciidoc
+++ b/doc/src/guide/common_test.asciidoc
@@ -87,5 +87,5 @@ as a dependency, you can run the following directly:
 [source,bash]
 $ make -C deps/cowboy ct-http t=http_compress
 
-Finally, link:coverage.asciidoc[code coverage] is available,
+Finally, xref:coverage[code coverage] is available,
 but covered in its own chapter.
diff --git a/doc/src/guide/compat.asciidoc b/doc/src/guide/compat.asciidoc
index 381e845..8c8f935 100644
--- a/doc/src/guide/compat.asciidoc
+++ b/doc/src/guide/compat.asciidoc
@@ -21,7 +21,7 @@ and adds a Makefile to the project that Erlang.mk can then
 use for building:
 
 _Autoload_ is documented in more details in the
-link:deps.asciidoc[Packages and dependencies] chapter.
+xref:deps[Packages and dependencies] chapter.
 
 === Erlang.mk projects as Rebar dependencies
 
@@ -50,11 +50,12 @@ the `DEPS` and `ERLC_OPTS` variables, among others. This
 means that the Rebar family builds your project much the
 same way as Erlang.mk.
 
+// @todo Sanity check chapter.
 Careful though! Different build tools have different fetching
 strategies. If some applications provide differing dependencies,
 they might be fetched differently by other build tools. Check
-the link:sanity_check.asciidoc[Sanity check] chapter to find
-out how to detect such issues.
+the upcoming Sanity check chapter to find out how to detect such
+issues.
 
 You can automatically generate this file when you build
 your application, by making it a dependency of the `app`
diff --git a/doc/src/guide/deps.asciidoc b/doc/src/guide/deps.asciidoc
index 9093d74..be7ed52 100644
--- a/doc/src/guide/deps.asciidoc
+++ b/doc/src/guide/deps.asciidoc
@@ -73,7 +73,7 @@ dep_leveldb = git https://github.com/basho/leveldb 2.1.3
 This dependency will be built before your application, so
 you could easily copy the resulting shared file into your
 'priv/' directory as part of the build process. More information
-about that in the link:ports.asciidoc[NIFs and port drivers]
+about that in the xref:ports[NIFs and port drivers]
 chapter.
 
 Another variable, `LOCAL_DEPS`, allows specifying runtime
diff --git a/doc/src/guide/eunit.asciidoc b/doc/src/guide/eunit.asciidoc
index 62188d9..496b674 100644
--- a/doc/src/guide/eunit.asciidoc
+++ b/doc/src/guide/eunit.asciidoc
@@ -118,5 +118,5 @@ you can run the following directly:
 [source,bash]
 $ make -C deps/cowlib eunit t=cow_http_hd
 
-Finally, link:coverage.asciidoc[code coverage] is available,
+Finally, xref:coverage[code coverage] is available,
 but covered in its own chapter.
diff --git a/doc/src/guide/getting_started.asciidoc b/doc/src/guide/getting_started.asciidoc
index 8a01ac0..04147b0 100644
--- a/doc/src/guide/getting_started.asciidoc
+++ b/doc/src/guide/getting_started.asciidoc
@@ -75,7 +75,7 @@ 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
+xref:updating[Updating Erlang.mk] chapter for more
 information.
 
 Of course, the generated project can now be compiled:
@@ -126,7 +126,7 @@ $ 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]
+depend on. Consult the xref:deps[Packages and dependencies]
 chapter for more information.
 
 When you run `make` from now on, Erlang.mk will compile your
@@ -151,7 +151,7 @@ _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]
+hardware just yet. Just consult the xref:relx[Releases]
 chapter for various tips to speed up build time during
 development.
 
diff --git a/doc/src/guide/overview.asciidoc b/doc/src/guide/overview.asciidoc
index fd62d0b..3e22790 100644
--- a/doc/src/guide/overview.asciidoc
+++ b/doc/src/guide/overview.asciidoc
@@ -10,20 +10,20 @@ 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]
+Erlang.mk will happily build all xref:building[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].
+when you are working on xref:ports[a NIF or a port driver].
 
-Erlang.mk embraces the concept of link:deps.asciidoc[source dependencies].
+Erlang.mk embraces the concept of xref:deps[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].
+Erlang.mk will automatically xref:relx[generate releases]
+when applicable. It can also xref:escript[generate escripts].
 
 === Exploring the package index
 
-Erlang.mk comes with a link:deps.asciidoc[built-in package index].
+Erlang.mk comes with a xref:deps[built-in package index].
 It is built as an extension of the dependency system and is
 meant to be used for discovery purposes.
 
@@ -47,14 +47,14 @@ $ make search q=cowboy
 
 Erlang.mk supports _EDoc_ and _Asciidoc_.
 
-link:edoc.asciidoc[EDoc] generates HTML documentation directly from
+xref:edoc[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
+The xref: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.
@@ -64,26 +64,26 @@ your repository.
 Erlang.mk supports a lot of different testing and static
 analysis tools.
 
-The link:shell.asciidoc[make shell] command allows you
+The xref:shell[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]
+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. link:coverage.asciidoc[Code coverage] can of course
+manually. xref:coverage[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].
+setting up and using xref:ci[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.
+support for xref:dialyzer[Dialyzer] and xref:xref[Xref],
+to perform success typing analysis and cross referencing
+of the code.
 
 === 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
+Not convinced yet? You can read about xref:why[why you should use Erlang.mk]
+and its xref:history[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/why.asciidoc b/doc/src/guide/why.asciidoc
index a48461b..e91b64c 100644
--- a/doc/src/guide/why.asciidoc
+++ b/doc/src/guide/why.asciidoc
@@ -2,7 +2,7 @@
 == Why Erlang.mk
 
 Why would you choose Erlang.mk, if not for its
-link:overview.asciidoc[many features]? This chapter will
+xref:overview[many features]? This chapter will
 attempt to answer that.
 
 === Erlang.mk is fast