1// -*- mode:doc; -*-
2// vim: syntax=asciidoc
3
4=== Infrastructure for asciidoc documents
5
6[[asciidoc-documents-tutorial]]
7
8The Buildroot manual, which you are currently reading, is entirely written
9using the http://asciidoc.org/[AsciiDoc] mark-up syntax. The manual is then
10rendered to many formats:
11
12* html
13* split-html
14* pdf
15* epub
16* text
17
18Although Buildroot only contains one document written in AsciiDoc, there
19is, as for packages, an infrastructure for rendering documents using the
20AsciiDoc syntax.
21
22Also as for packages, the AsciiDoc infrastructure is available from a
23xref:outside-br-custom[br2-external tree]. This allows documentation for
24a br2-external tree to match the Buildroot documentation, as it will be
25rendered to the same formats and use the same layout and theme.
26
27==== +asciidoc-document+ tutorial
28
29Whereas package infrastructures are suffixed with +-package+, the document
30infrastructures are suffixed with +-document+. So, the AsciiDoc infrastructure
31is named +asciidoc-document+.
32
33Here is an example to render a simple AsciiDoc document.
34
35----
3601: ################################################################################
3702: #
3803: # foo-document
3904: #
4005: ################################################################################
4106:
4207: FOO_SOURCES = $(sort $(wildcard $(FOO_DOCDIR)/*))
4308: $(eval $(call asciidoc-document))
44----
45
46On line 7, the Makefile declares what the sources of the document are.
47Currently, it is expected that the document's sources are only local;
48Buildroot will not attempt to download anything to render a document.
49Thus, you must indicate where the sources are. Usually, the string
50above is sufficient for a document with no sub-directory structure.
51
52On line 8, we call the +asciidoc-document+ function, which generates all
53the Makefile code necessary to render the document.
54
55==== +asciidoc-document+ reference
56
57The list of variables that can be set in a +.mk+ file to give metadata
58information is (assuming the document name is +foo+) :
59
60* +FOO_SOURCES+, mandatory, defines the source files for the document.
61
62* +FOO_RESOURCES+, optional, may contain a space-separated list of paths
63  to one or more directories containing so-called resources (like CSS or
64  images). By default, empty.
65
66* +FOO_DEPENDENCIES+, optional, the list of packages (most probably,
67  host-packages) that must be built before building this document.
68
69* +FOO_TOC_DEPTH+, +FOO_TOC_DEPTH_<FMT>+, optionals, the depth of the
70  table of content for this document, which can be overridden for the
71  specified format +<FMT>+  (see the list of rendered formats, above,
72  but in uppercase, and with dash replaced by underscore; see example,
73  below). By default: +1+.
74
75There are also additional hooks (see xref:hooks[] for general information
76on hooks), that a document may set to define extra actions to be done at
77various steps:
78
79* +FOO_POST_RSYNC_HOOKS+ to run additional commands after the sources
80  have been copied by Buildroot. This can for example be used to
81  generate part of the manual with information extracted from the
82  tree. As an example, Buildroot uses this hook to generate the tables
83  in the appendices.
84
85* +FOO_CHECK_DEPENDENCIES_HOOKS+ to run additional tests on required
86  components to generate the document. In AsciiDoc, it is possible to
87  call filters, that is, programs that will parse an AsciiDoc block and
88  render it appropriately (e.g. http://ditaa.sourceforge.net/[ditaa] or
89  https://pythonhosted.org/aafigure/[aafigure]).
90
91* +FOO_CHECK_DEPENDENCIES_<FMT>_HOOKS+, to run additional tests for
92  the specified format +<FMT>+ (see the list of rendered formats, above).
93
94Buildroot sets the following variable that can be used in the definitions
95above:
96
97* +$(FOO_DOCDIR)+, similar to +$(FOO_PKGDIR)+, contains the path to the
98  directory containing +foo.mk+. It can be used to refer to the document
99  sources, and can be used in the hooks, especially the post-rsync hook
100  if parts of the documentation needs to be generated.
101
102* +$(@D)+, as for traditional packages, contains the path to the directory
103  where the document will be copied and built.
104
105Here is a complete example that uses all variables and all hooks:
106
107----
10801: ################################################################################
10902: #
11003: # foo-document
11104: #
11205: ################################################################################
11306:
11407: FOO_SOURCES = $(sort $(wildcard $(FOO_DOCDIR)/*))
11508: FOO_RESOURCES = $(sort $(wildcard $(FOO_DOCDIR)/ressources))
11609:
11710: FOO_TOC_DEPTH = 2
11811: FOO_TOC_DEPTH_HTML = 1
11912: FOO_TOC_DEPTH_SPLIT_HTML = 3
12013:
12114: define FOO_GEN_EXTRA_DOC
12215:     /path/to/generate-script --outdir=$(@D)
12316: endef
12417: FOO_POST_RSYNC_HOOKS += FOO_GEN_EXTRA_DOC
12518:
12619: define FOO_CHECK_MY_PROG
12720:     if ! which my-prog >/dev/null 2>&1; then \
12821:         echo "You need my-prog to generate the foo document"; \
12922:         exit 1; \
13023:     fi
13124: endef
13225: FOO_CHECK_DEPENDENCIES_HOOKS += FOO_CHECK_MY_PROG
13326:
13427: define FOO_CHECK_MY_OTHER_PROG
13528:     if ! which my-other-prog >/dev/null 2>&1; then \
13629:         echo "You need my-other-prog to generate the foo document as PDF"; \
13730:         exit 1; \
13831:     fi
13932: endef
14033: FOO_CHECK_DEPENDENCIES_PDF_HOOKS += FOO_CHECK_MY_OTHER_PROG
14134:
14235: $(eval $(call asciidoc-document))
143----
144