blob: b379b82059277c068c51801734cf25d98de1b2a8 (
plain) (
tree)
|
|
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta name="description" content="">
<meta name="author" content="Loïc Hoguin based on a design from (Soft10) Pol Cámara">
<meta name="generator" content="Hugo 0.16" />
<title>Nine Nines: AsciiDoc documentation</title>
<link href='http://fonts.googleapis.com/css?family=Open+Sans:400,700,400italic' rel='stylesheet' type='text/css'>
<link href="/css/bootstrap.min.css" rel="stylesheet">
<link href="/css/99s.css" rel="stylesheet">
<link rel="shortcut icon" href="/img/ico/favicon.ico">
<link rel="apple-touch-icon-precomposed" sizes="114x114" href="/img/ico/apple-touch-icon-114.png">
<link rel="apple-touch-icon-precomposed" sizes="72x72" href="/img/ico/apple-touch-icon-72.png">
<link rel="apple-touch-icon-precomposed" href="/img/ico/apple-touch-icon-57.png">
</head>
<body class="">
<header id="page-head">
<div id="topbar" class="container">
<div class="row">
<div class="span2">
<h1 id="logo"><a href="/" title="99s">99s</a></h1>
</div>
<div class="span10">
<div id="side-header">
<nav>
<ul>
<li><a title="Hear my thoughts" href="/articles">Articles</a></li>
<li><a title="Watch my talks" href="/talks">Talks</a></li>
<li class="active"><a title="Read the docs" href="/docs">Documentation</a></li>
<li><a title="Request my services" href="/services">Consulting & Training</a></li>
</ul>
</nav>
<ul id="social">
<li>
<a href="https://github.com/ninenines" title="Check my Github repositories"><img src="/img/ico_github.png" data-hover="/img/ico_github_alt.png" alt="Github"></a>
</li>
<li>
<a title="Keep in touch!" href="http://twitter.com/lhoguin"><img src="/img/ico_microblog.png" data-hover="/img/ico_microblog_alt.png"></a>
</li>
<li>
<a title="Contact me" href="mailto:[email protected]"><img src="/img/ico_mail.png" data-hover="/img/ico_mail_alt.png"></a>
</li>
</ul>
</div>
</div>
</div>
</div>
</header>
<div id="contents" class="two_col">
<div class="container">
<div class="row">
<div id="docs" class="span9 maincol">
<h1 class="lined-header"><span>AsciiDoc documentation</span></h1>
<div class="paragraph"><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>
<div class="sect1">
<h2 id="_requirements">Requirements</h2>
<div class="sectionbody">
<div class="paragraph"><p>It is necessary to have <a href="http://asciidoc.org/">AsciiDoc</a>,
<a href="http://xmlsoft.org/XSLT/xsltproc2.html">xsltproc</a> and
<a href="http://dblatex.sourceforge.net/">dblatex</a> installed on your
system for Erlang.mk to generate documentation from AsciiDoc sources.</p></div>
</div>
</div>
<div class="sect1">
<h2 id="_writing_asciidoc_documentation">Writing AsciiDoc documentation</h2>
<div class="sectionbody">
<div class="paragraph"><p><a href="http://asciidoc.org/">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></div>
<div class="paragraph"><p>The <a href="http://asciidoc.org/userguide.html">AsciiDoc user guide</a>
describes the AsciiDoc syntax.</p></div>
<div class="paragraph"><p>The <a href="https://github.com/ninenines/erlang.mk/tree/master/doc/src/guide">Erlang.mk user guide</a>
is written in AsciiDoc and can be used as an example. The entry
file is <a href="https://github.com/ninenines/erlang.mk/blob/master/doc/src/guide/book.asciidoc">book.asciidoc</a>.</p></div>
<div class="paragraph"><p>Erlang.mk expects you to put your documentation in a specific
location. This is <em>doc/src/guide/</em> for the user guide, and
<em>doc/src/manual/</em> for the function reference. In the case of
the user guide, the entry point is always <em>doc/src/guide/book.asciidoc</em>.</p></div>
<div class="paragraph"><p>For manual pages, it is good practice to use section 3 for
modules, and section 7 for the application itself.</p></div>
</div>
</div>
<div class="sect1">
<h2 id="_configuration">Configuration</h2>
<div class="sectionbody">
<div class="paragraph"><p>All of the AsciiDoc related configuration can be done directly
inside the files themselves.</p></div>
</div>
</div>
<div class="sect1">
<h2 id="_usage">Usage</h2>
<div class="sectionbody">
<div class="paragraph"><p>To build all documentation:</p></div>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight 3.1.8
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>$ make docs</tt></pre></div></div>
<div class="paragraph"><p>To build only the AsciiDoc documentation:</p></div>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight 3.1.8
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>$ make asciidoc</tt></pre></div></div>
<div class="paragraph"><p>To build only the user guide:</p></div>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight 3.1.8
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>$ make asciidoc-guide</tt></pre></div></div>
<div class="paragraph"><p>To build only the manual:</p></div>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight 3.1.8
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>$ make asciidoc-manual</tt></pre></div></div>
<div class="paragraph"><p>To install man pages on Unix:</p></div>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight 3.1.8
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>$ make install-docs</tt></pre></div></div>
<div class="paragraph"><p>Erlang.mk allows customizing the installation path and sections
of the man pages to be installed. The <code>MAN_INSTALL_PATH</code> variable
defines where man pages will be installed. It defaults to
<em>/usr/local/share/man</em>. The <code>MAN_SECTIONS</code> variable defines
which manual sections are to be installed. It defaults to <code>3 7</code>.</p></div>
<div class="paragraph"><p>To install man pages to a custom location:</p></div>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight 3.1.8
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>$ make install-docs <span style="color: #009900">MAN_INSTALL_PATH</span><span style="color: #990000">=</span>/opt/share/man</tt></pre></div></div>
<div class="paragraph"><p>Note that you may need to run the install commands using
<code>sudo</code> or equivalent if the location is not writeable by
your user.</p></div>
</div>
</div>
</div>
<div class="span3 sidecol">
<h3>
Erlang.mk
1
User Guide
</h3>
<ul>
</ul>
<h4 id="docs-nav">Navigation</h4>
<h4>Version select</h4>
<ul>
<li><a href="/docs/en/erlang.mk/1/guide">1</a></li>
</ul>
</div>
</div>
</div>
</div>
<footer>
<div class="container">
<div class="row">
<div class="span6">
<p id="scroll-top"><a href="#">↑ Scroll to top</a></p>
<nav>
<ul>
<li><a href="mailto:[email protected]" title="Contact us">Contact us</a></li><li><a href="https://github.com/ninenines/ninenines.github.io" title="Github repository">Contribute to this site</a></li>
</ul>
</nav>
</div>
<div class="span6 credits">
<p><img src="/img/footer_logo.png"></p>
<p>Copyright © Loïc Hoguin 2012-2016</p>
</div>
</div>
</div>
</footer>
<script src="https://ajax.googleapis.com/ajax/libs/jquery/1.7.1/jquery.min.js"></script>
<script src="/js/bootstrap-carousel.js"></script>
<script src="/js/bootstrap-dropdown.js"></script>
<script src="/js/custom.js"></script>
</body>
</html>
|
