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 AsciiDoc, xsltproc and dblatex installed on your system for Erlang.mk to generate documentation from AsciiDoc sources.

Writing AsciiDoc documentation

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 AsciiDoc user guide describes the AsciiDoc syntax.

The Erlang.mk user guide is written in AsciiDoc and can be used as an example. The entry file is 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:

$ make docs

To build only the AsciiDoc documentation:

$ make asciidoc

To build only the user guide:

$ make asciidoc-guide

To build only the manual:

$ make asciidoc-manual

To install man pages on Unix:

$ 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:

$ 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.