1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
|
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8"/>
<title>Erlang.mk User Guide</title>
<style type="text/css"><!--
body{background:white;color:black;font-family:"Open Sans", "Helvetica Neue", Helvetica, Arial, sans-serif;justify-content:center;margin:0 auto;padding:0;width:600px}
header {align-items:center;display:flex;justify-content:center}
header nav.left{text-align:right;width:150px}
header nav.right{text-align:left;width:150px}
header nav a{display:block;margin:1.5em 1em}
main{margin-top:2em;text-align:justify}
main h2, main h3{margin-top:2em}
main h1, main div.chapter>div.titlepage h2{font-size:2em;margin-top:.67em}
a{color:#d9230f;text-decoration:none}
a:hover{text-decoration:underline}
a.xref{display:none}
h1, h2, h3{font-weight:normal}
div.navfooter{margin-bottom:1em}
--></style>
</head>
<body>
<header>
<nav class="left">
<a href="index.html">User guide</a>
<a href="getting_started.html">Tutorials</a>
</nav>
<a href="/" class="logo"><img src="../res/logo-small.png" alt="Erlang.mk" title="Erlang.mk: A build tool for Erlang that just works" height="200" width="206"/></a>
<nav class="right">
<a href="https://github.com/ninenines/erlang.mk/tree/master/index">470+ packages</a>
<a href="https://github.com/ninenines/erlang.mk/issues">Issues?</a>
</nav>
</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>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="_requirements"></a>12.1. Requirements</h2></div></div></div><p>It is necessary to have <a class="ulink" href="http://asciidoc.org/" target="_top">AsciiDoc</a>,
<a class="ulink" href="http://xmlsoft.org/XSLT/xsltproc2.html" target="_top">xsltproc</a> and
<a class="ulink" href="http://dblatex.sourceforge.net/" target="_top">dblatex</a> installed on your
system for Erlang.mk to generate documentation from AsciiDoc sources.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_writing_asciidoc_documentation"></a>12.2. 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.3. 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.4. 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>
|
