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

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

plugins/asciidoc.mk

@@ -8,12 +8,12 @@ MAN_SECTIONS ?= 3 7
 
 docs:: asciidoc
 
-asciidoc: distclean-asciidoc doc-deps asciidoc-guide asciidoc-manual
+asciidoc: asciidoc-guide asciidoc-manual
 
 ifeq ($(wildcard doc/src/guide/book.asciidoc),)
 asciidoc-guide:
 else
-asciidoc-guide:
+asciidoc-guide: distclean-asciidoc doc-deps
 	a2x -v -f pdf doc/src/guide/book.asciidoc && mv doc/src/guide/book.pdf doc/guide.pdf
 	a2x -v -f chunked doc/src/guide/book.asciidoc && mv doc/src/guide/book.chunked/ doc/html/
 endif
@@ -21,7 +21,7 @@ endif
 ifeq ($(wildcard doc/src/manual/*.asciidoc),)
 asciidoc-manual:
 else
-asciidoc-manual:
+asciidoc-manual: distclean-asciidoc doc-deps
 	for f in doc/src/manual/*.asciidoc ; do \
 		a2x -v -f manpage $$f ; \
 	done
@@ -36,7 +36,7 @@ install-docs:: install-asciidoc
 install-asciidoc: asciidoc-manual
 	for s in $(MAN_SECTIONS); do \
 		mkdir -p $(MAN_INSTALL_PATH)/man$$s/ ; \
-		install -g 0 -o 0 -m 0644 doc/man$$s/*.gz $(MAN_INSTALL_PATH)/man$$s/ ; \
+		install -g `id -u` -o `id -g` -m 0644 doc/man$$s/*.gz $(MAN_INSTALL_PATH)/man$$s/ ; \
 	done
 endif
 

test/plugin_asciidoc.mk

@@ -0,0 +1,158 @@
+# AsciiDoc plugin.
+
+ASCIIDOC_CASES = build docs guide install manual
+ASCIIDOC_TARGETS = $(addprefix asciidoc-,$(ASCIIDOC_CASES))
+
+.PHONY: asciidoc $(ASCIIDOC_TARGETS)
+
+asciidoc: $(ASCIIDOC_TARGETS)
+
+asciidoc-build: build clean
+
+	$i "Bootstrap a new OTP application named $(APP)"
+	$t mkdir $(APP)/
+	$t cp ../erlang.mk $(APP)/
+	$t $(MAKE) -C $(APP) -f erlang.mk bootstrap $v
+
+	$i "Only enable man pages section 3"
+	$t perl -ni.bak -e 'print;if ($$.==1) {print "MAN_SECTIONS = 3\n"}' $(APP)/Makefile
+
+	$i "Run AsciiDoc"
+	$t $(MAKE) -C $(APP) asciidoc $v
+
+	$i "Check that no documentation was generated"
+	$t test ! -e $(APP)/doc/guide.pdf
+	$t test ! -e $(APP)/doc/html/
+	$t test ! -e $(APP)/doc/man3/
+
+	$i "Generate AsciiDoc documentation"
+	$t mkdir -p $(APP)/doc/src/guide/ $(APP)/doc/src/manual/
+	$t printf "%s\n" \
+		"= Erlang.mk tests" "" \
+		"Hello world!" > $(APP)/doc/src/guide/book.asciidoc
+	$t printf "%s\n" \
+		"= erlang_mk(3)" "" \
+		"== Name" "" \
+		"erlang_mk - Erlang.mk test" "" \
+		"== Description" "" \
+		"Hello world!" > $(APP)/doc/src/manual/erlang_mk.asciidoc
+
+	$i "Run AsciiDoc"
+	$t $(MAKE) -C $(APP) asciidoc $v
+
+	$i "Check that the documentation was generated"
+	$t test -f $(APP)/doc/guide.pdf
+	$t test -d $(APP)/doc/html/
+	$t test -f $(APP)/doc/man3/erlang_mk.3.gz
+
+	$i "Distclean the application"
+	$t $(MAKE) -C $(APP) distclean $v
+
+	$i "Check that the generated documentation was removed"
+	$t test ! -e $(APP)/doc/guide.pdf
+	$t test ! -e $(APP)/doc/html/
+	$t test ! -e $(APP)/doc/man3/
+
+	$i "Generate an invalid AsciiDoc file"
+	$t printf "%s\n" \
+		"= fail(3)" "" \
+		"This will fail because the Name section is missing." > $(APP)/doc/src/manual/fail.asciidoc
+
+	$i "Check that AsciiDoc errors out"
+	$t ! $(MAKE) -C $(APP) asciidoc $v
+
+asciidoc-docs: build clean
+
+	$i "Bootstrap a new OTP application named $(APP)"
+	$t mkdir $(APP)/
+	$t cp ../erlang.mk $(APP)/
+	$t $(MAKE) -C $(APP) -f erlang.mk bootstrap $v
+
+	$i "Generate AsciiDoc documentation"
+	$t mkdir -p $(APP)/doc/src/guide/
+	$t printf "%s\n" \
+		"= Erlang.mk tests" "" \
+		"Hello world!" > $(APP)/doc/src/guide/book.asciidoc
+
+	$i "Check that AsciiDoc runs on 'make docs'"
+	$t $(MAKE) -C $(APP) docs $v
+	$t test -f $(APP)/doc/guide.pdf
+	$t test -d $(APP)/doc/html/
+
+asciidoc-guide: build clean
+
+	$i "Bootstrap a new OTP application named $(APP)"
+	$t mkdir $(APP)/
+	$t cp ../erlang.mk $(APP)/
+	$t $(MAKE) -C $(APP) -f erlang.mk bootstrap $v
+
+	$i "Generate AsciiDoc documentation"
+	$t mkdir -p $(APP)/doc/src/guide/ $(APP)/doc/src/manual/
+	$t printf "%s\n" \
+		"= Erlang.mk tests" "" \
+		"Hello world!" > $(APP)/doc/src/guide/book.asciidoc
+	$t printf "%s\n" \
+		"= erlang_mk(3)" "" \
+		"== Name" "" \
+		"erlang_mk - Erlang.mk test" "" \
+		"== Description" "" \
+		"Hello world!" > $(APP)/doc/src/manual/erlang_mk.asciidoc
+
+	$i "Check that only the guide is generated on 'make asciidoc-guide'"
+	$t $(MAKE) -C $(APP) asciidoc-guide $v
+	$t test -f $(APP)/doc/guide.pdf
+	$t test -d $(APP)/doc/html/
+	$t test ! -e $(APP)/doc/man3/
+
+asciidoc-install: build clean
+
+	$i "Bootstrap a new OTP application named $(APP)"
+	$t mkdir $(APP)/
+	$t cp ../erlang.mk $(APP)/
+	$t $(MAKE) -C $(APP) -f erlang.mk bootstrap $v
+
+	$i "Only enable man pages section 3"
+	$t perl -ni.bak -e 'print;if ($$.==1) {print "MAN_SECTIONS = 3\n"}' $(APP)/Makefile
+
+	$i "Generate AsciiDoc documentation"
+	$t mkdir -p $(APP)/doc/src/manual/
+	$t printf "%s\n" \
+		"= erlang_mk(3)" "" \
+		"== Name" "" \
+		"erlang_mk - Erlang.mk test" "" \
+		"== Description" "" \
+		"Hello world!" > $(APP)/doc/src/manual/erlang_mk.asciidoc
+
+	$i "Build and install the man pages to $(APP)/installed/"
+	$t $(MAKE) -C $(APP) install-docs MAN_INSTALL_PATH=installed/share $v
+
+	$i "Check that the documentation was installed properly"
+	$t test -f $(APP)/installed/share/man3/erlang_mk.3.gz
+
+asciidoc-manual: build clean
+
+	$i "Bootstrap a new OTP application named $(APP)"
+	$t mkdir $(APP)/
+	$t cp ../erlang.mk $(APP)/
+	$t $(MAKE) -C $(APP) -f erlang.mk bootstrap $v
+
+	$i "Only enable man pages section 3"
+	$t perl -ni.bak -e 'print;if ($$.==1) {print "MAN_SECTIONS = 3\n"}' $(APP)/Makefile
+
+	$i "Generate AsciiDoc documentation"
+	$t mkdir -p $(APP)/doc/src/guide/ $(APP)/doc/src/manual/
+	$t printf "%s\n" \
+		"= Erlang.mk tests" "" \
+		"Hello world!" > $(APP)/doc/src/guide/book.asciidoc
+	$t printf "%s\n" \
+		"= erlang_mk(3)" "" \
+		"== Name" "" \
+		"erlang_mk - Erlang.mk test" "" \
+		"== Description" "" \
+		"Hello world!" > $(APP)/doc/src/manual/erlang_mk.asciidoc
+
+	$i "Check that only the manual is generated on 'make asciidoc-manual'"
+	$t $(MAKE) -C $(APP) asciidoc-manual $v
+	$t test ! -e $(APP)/doc/guide.pdf
+	$t test ! -e $(APP)/doc/html/
+	$t test -f $(APP)/doc/man3/erlang_mk.3.gz