diff options
author | Loïc Hoguin <[email protected]> | 2016-01-09 15:48:41 +0100 |
---|---|---|
committer | Loïc Hoguin <[email protected]> | 2016-01-09 15:48:41 +0100 |
commit | badc6ee4d0d1f01feaf0655c58faffefe5040803 (patch) | |
tree | ba59047980408639fc2e1a39a27740ea5329fd1c /doc/src | |
parent | c512f49ad95c2cffae1de9b80f49228d3430e988 (diff) | |
download | erlang.mk-badc6ee4d0d1f01feaf0655c58faffefe5040803.tar.gz erlang.mk-badc6ee4d0d1f01feaf0655c58faffefe5040803.tar.bz2 erlang.mk-badc6ee4d0d1f01feaf0655c58faffefe5040803.zip |
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.
Diffstat (limited to 'doc/src')
-rw-r--r-- | doc/src/guide/asciidoc.asciidoc | 75 |
1 files changed, 72 insertions, 3 deletions
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. |