[[asciidoc]]
== AsciiDoc documentation

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.

=== Requirements

It is necessary to have http://asciidoc.org/[AsciiDoc], 
http://xmlsoft.org/XSLT/xsltproc2.html[xsltproc] and
http://dblatex.sourceforge.net/[dblatex] installed on your
system for Erlang.mk to generate documentation from AsciiDoc sources.

=== Writing AsciiDoc documentation

http://asciidoc.org/[AsciiDoc] 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.

The http://asciidoc.org/userguide.html[AsciiDoc user guide]
describes the AsciiDoc syntax.

The https://github.com/ninenines/erlang.mk/tree/master/doc/src/guide[Erlang.mk user guide]
is written in AsciiDoc and can be used as an example. The entry
file is https://github.com/ninenines/erlang.mk/blob/master/doc/src/guide/book.asciidoc[book.asciidoc].

Erlang.mk expects you to put your documentation in a specific
location. This is 'doc/src/guide/' for the user guide, and
'doc/src/manual/' for the function reference. In the case of
the user guide, the entry point is always 'doc/src/guide/book.asciidoc'.

For manual pages, it is good practice to use section 3 for
modules, and section 7 for the application itself.

=== Configuration

All of the AsciiDoc related configuration can be done directly
inside the files themselves.

=== Usage

To build all documentation:

[source,bash]
$ make docs

To build only the AsciiDoc documentation:

[source,bash]
$ make asciidoc

To build only the user guide:

[source,bash]
$ make asciidoc-guide

To build only the manual:

[source,bash]
$ make asciidoc-manual

To install man pages on Unix:

[source,bash]
$ make install-docs

Erlang.mk allows customizing the installation path and sections
of the man pages to be installed. The `MAN_INSTALL_PATH` variable
defines where man pages will be installed. It defaults to
'/usr/local/share/man'. The `MAN_SECTIONS` variable defines
which manual sections are to be installed. It defaults to `3 7`.

To install man pages to a custom location:

[source,bash]
$ make install-docs MAN_INSTALL_PATH=/opt/share/man

Note that you may need to run the install commands using
`sudo` or equivalent if the location is not writeable by
your user.