diff options
author | Loïc Hoguin <[email protected]> | 2016-03-28 15:36:42 +0200 |
---|---|---|
committer | Loïc Hoguin <[email protected]> | 2016-03-28 15:36:42 +0200 |
commit | fe3492a98de29942477b061cd02c92246f4bf85a (patch) | |
tree | 2255b796a657e6e4dfb72beec1141258d17f1220 /docs/en/erlang.mk/1/guide/asciidoc.asciidoc | |
download | ninenines.eu-fe3492a98de29942477b061cd02c92246f4bf85a.tar.gz ninenines.eu-fe3492a98de29942477b061cd02c92246f4bf85a.tar.bz2 ninenines.eu-fe3492a98de29942477b061cd02c92246f4bf85a.zip |
Initial commit, new website system
Diffstat (limited to 'docs/en/erlang.mk/1/guide/asciidoc.asciidoc')
-rw-r--r-- | docs/en/erlang.mk/1/guide/asciidoc.asciidoc | 82 |
1 files changed, 82 insertions, 0 deletions
diff --git a/docs/en/erlang.mk/1/guide/asciidoc.asciidoc b/docs/en/erlang.mk/1/guide/asciidoc.asciidoc new file mode 100644 index 00000000..cc8336bf --- /dev/null +++ b/docs/en/erlang.mk/1/guide/asciidoc.asciidoc @@ -0,0 +1,82 @@ +[[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. |