Update user guide

1 files changed, 20 insertions, 1 deletions

diff --git a/guide/asciidoc.html b/guide/asciidoc.html
index 8903668..ed4222b 100644
--- a/guide/asciidoc.html
+++ b/guide/asciidoc.html
@@ -33,7 +33,26 @@ div.navfooter{margin-bottom:1em}
 </header>
 <main>
 
-<div class="navheader"><table width="100%" summary="Navigation header"><tr><td width="20%" align="left"><a accesskey="p" href="docs.html">Prev</a> </td><th width="60%" align="center"> </th><td width="20%" align="right"> <a accesskey="n" href="edoc.html">Next</a></td></tr></table><hr /></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a id="asciidoc"></a>Chapter 12. Asciidoc documentation</h2></div></div></div><p>Placeholder chapter.</p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="docs.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="docs.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="edoc.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top"> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> </td></tr></table></div>
+<div class="navheader"><table width="100%" summary="Navigation header"><tr><td width="20%" align="left"><a accesskey="p" href="docs.html">Prev</a> </td><th width="60%" align="center"> </th><td width="20%" align="right"> <a accesskey="n" href="edoc.html">Next</a></td></tr></table><hr /></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a id="asciidoc"></a>Chapter 12. AsciiDoc documentation</h2></div></div></div><p>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.</p><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_writing_asciidoc_documentation"></a>12.1. Writing AsciiDoc documentation</h2></div></div></div><p><a class="ulink" href="http://asciidoc.org/" target="_top">AsciiDoc</a> 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.</p><p>The <a class="ulink" href="http://asciidoc.org/userguide.html" target="_top">AsciiDoc user guide</a>
+describes the AsciiDoc syntax.</p><p>The <a class="ulink" href="https://github.com/ninenines/erlang.mk/tree/master/doc/src/guide" target="_top">Erlang.mk user guide</a>
+is written in AsciiDoc and can be used as an example. The entry
+file is <a class="ulink" href="https://github.com/ninenines/erlang.mk/blob/master/doc/src/guide/book.asciidoc" target="_top">book.asciidoc</a>.</p><p>Erlang.mk expects you to put your documentation in a specific
+location. This is <span class="emphasis"><em>doc/src/guide/</em></span> for the user guide, and
+<span class="emphasis"><em>doc/src/manual/</em></span> for the function reference. In the case of
+the user guide, the entry point is always <span class="emphasis"><em>doc/src/guide/book.asciidoc</em></span>.</p><p>For manual pages, it is good practice to use section 3 for
+modules, and section 7 for the application itself.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_configuration_2"></a>12.2. Configuration</h2></div></div></div><p>All of the AsciiDoc related configuration can be done directly
+inside the files themselves.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_usage"></a>12.3. Usage</h2></div></div></div><p>To build all documentation:</p><pre class="programlisting">$ make docs</pre><p>To build only the AsciiDoc documentation:</p><pre class="programlisting">$ make asciidoc</pre><p>To build only the user guide:</p><pre class="programlisting">$ make asciidoc-guide</pre><p>To build only the manual:</p><pre class="programlisting">$ make asciidoc-manual</pre><p>To install man pages on Unix:</p><pre class="programlisting">$ make install-docs</pre><p>Erlang.mk allows customizing the installation path and sections
+of the man pages to be installed. The <code class="literal">MAN_INSTALL_PATH</code> variable
+defines where man pages will be installed. It defaults to
+<span class="emphasis"><em>/usr/local/share/man</em></span>. The <code class="literal">MAN_SECTIONS</code> variable defines
+which manual sections are to be installed. It defaults to <code class="literal">3 7</code>.</p><p>To install man pages to a custom location:</p><pre class="programlisting">$ make install-docs MAN_INSTALL_PATH=/opt/share/man</pre><p>Note that you may need to run the install commands using
+<code class="literal">sudo</code> or equivalent if the location is not writeable by
+your user.</p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="docs.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="docs.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="edoc.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top"> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> </td></tr></table></div>
 </main>
 </body>
 </html>