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 $(pkgdir)/*)) 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 69There are also additional hooks (see xref:hooks[] for general information 70on hooks), that a document may set to define extra actions to be done at 71various steps: 72 73* +FOO_POST_RSYNC_HOOKS+ to run additional commands after the sources 74 have been copied by Buildroot. This can for example be used to 75 generate part of the manual with information extracted from the 76 tree. As an example, Buildroot uses this hook to generate the tables 77 in the appendices. 78 79* +FOO_CHECK_DEPENDENCIES_HOOKS+ to run additional tests on required 80 components to generate the document. In AsciiDoc, it is possible to 81 call filters, that is, programs that will parse an AsciiDoc block and 82 render it appropriately (e.g. http://ditaa.sourceforge.net/[ditaa] or 83 https://pythonhosted.org/aafigure/[aafigure]). 84 85* +FOO_CHECK_DEPENDENCIES_<FMT>_HOOKS+, to run additional tests for 86 the specified format +<FMT>+ (see the list of rendered formats, above). 87 88Here is a complete example that uses all variables and all hooks: 89 90---- 9101: ################################################################################ 9202: # 9303: # foo-document 9404: # 9505: ################################################################################ 9606: 9707: FOO_SOURCES = $(sort $(wildcard $(pkgdir)/*)) 9808: FOO_RESOURCES = $(sort $(wildcard $(pkgdir)/ressources)) 9909: 10010: define FOO_GEN_EXTRA_DOC 10111: /path/to/generate-script --outdir=$(@D) 10212: endef 10313: FOO_POST_RSYNC_HOOKS += FOO_GEN_EXTRA_DOC 10414: 10515: define FOO_CHECK_MY_PROG 10616: if ! which my-prog >/dev/null 2>&1; then \ 10717: echo "You need my-prog to generate the foo document"; \ 10818: exit 1; \ 10919: fi 11020: endef 11121: FOO_CHECK_DEPENDENCIES_HOOKS += FOO_CHECK_MY_PROG 11222: 11323: define FOO_CHECK_MY_OTHER_PROG 11424: if ! which my-other-prog >/dev/null 2>&1; then \ 11525: echo "You need my-other-prog to generate the foo document as PDF"; \ 11626: exit 1; \ 11727: fi 11828: endef 11929: FOO_CHECK_DEPENDENCIES_PDF_HOOKS += FOO_CHECK_MY_OTHER_PROG 12030: 12131: $(eval $(call asciidoc-document)) 122---- 123