From badc6ee4d0d1f01feaf0655c58faffefe5040803 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Lo=C3=AFc=20Hoguin?= <essen@ninenines.eu>
Date: Sat, 9 Jan 2016 15:48:41 +0100
Subject: Add AsciiDoc tests and documentation

Also fixes install-docs to allow installing regardless of being
root or a normal user. The current user/group will be used for
the installed files.
---
 doc/src/guide/asciidoc.asciidoc | 75 +++++++++++++++++++++++++++++++++++++++--
 1 file changed, 72 insertions(+), 3 deletions(-)

(limited to 'doc/src/guide/asciidoc.asciidoc')

diff --git a/doc/src/guide/asciidoc.asciidoc b/doc/src/guide/asciidoc.asciidoc
index 2fca131..621f5b5 100644
--- a/doc/src/guide/asciidoc.asciidoc
+++ b/doc/src/guide/asciidoc.asciidoc
@@ -1,6 +1,75 @@
 [[asciidoc]]
-== Asciidoc documentation
+== AsciiDoc documentation
 
-// @todo Write it.
+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.
 
-Placeholder chapter.
+=== 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.
-- 
cgit v1.2.3