1*4882a593Smuzhiyun// -*- mode:doc; -*- 2*4882a593Smuzhiyun// vim: syntax=asciidoc 3*4882a593Smuzhiyun 4*4882a593Smuzhiyun=== Infrastructure for asciidoc documents 5*4882a593Smuzhiyun 6*4882a593Smuzhiyun[[asciidoc-documents-tutorial]] 7*4882a593Smuzhiyun 8*4882a593SmuzhiyunThe Buildroot manual, which you are currently reading, is entirely written 9*4882a593Smuzhiyunusing the http://asciidoc.org/[AsciiDoc] mark-up syntax. The manual is then 10*4882a593Smuzhiyunrendered to many formats: 11*4882a593Smuzhiyun 12*4882a593Smuzhiyun* html 13*4882a593Smuzhiyun* split-html 14*4882a593Smuzhiyun* pdf 15*4882a593Smuzhiyun* epub 16*4882a593Smuzhiyun* text 17*4882a593Smuzhiyun 18*4882a593SmuzhiyunAlthough Buildroot only contains one document written in AsciiDoc, there 19*4882a593Smuzhiyunis, as for packages, an infrastructure for rendering documents using the 20*4882a593SmuzhiyunAsciiDoc syntax. 21*4882a593Smuzhiyun 22*4882a593SmuzhiyunAlso as for packages, the AsciiDoc infrastructure is available from a 23*4882a593Smuzhiyunxref:outside-br-custom[br2-external tree]. This allows documentation for 24*4882a593Smuzhiyuna br2-external tree to match the Buildroot documentation, as it will be 25*4882a593Smuzhiyunrendered to the same formats and use the same layout and theme. 26*4882a593Smuzhiyun 27*4882a593Smuzhiyun==== +asciidoc-document+ tutorial 28*4882a593Smuzhiyun 29*4882a593SmuzhiyunWhereas package infrastructures are suffixed with +-package+, the document 30*4882a593Smuzhiyuninfrastructures are suffixed with +-document+. So, the AsciiDoc infrastructure 31*4882a593Smuzhiyunis named +asciidoc-document+. 32*4882a593Smuzhiyun 33*4882a593SmuzhiyunHere is an example to render a simple AsciiDoc document. 34*4882a593Smuzhiyun 35*4882a593Smuzhiyun---- 36*4882a593Smuzhiyun01: ################################################################################ 37*4882a593Smuzhiyun02: # 38*4882a593Smuzhiyun03: # foo-document 39*4882a593Smuzhiyun04: # 40*4882a593Smuzhiyun05: ################################################################################ 41*4882a593Smuzhiyun06: 42*4882a593Smuzhiyun07: FOO_SOURCES = $(sort $(wildcard $(pkgdir)/*)) 43*4882a593Smuzhiyun08: $(eval $(call asciidoc-document)) 44*4882a593Smuzhiyun---- 45*4882a593Smuzhiyun 46*4882a593SmuzhiyunOn line 7, the Makefile declares what the sources of the document are. 47*4882a593SmuzhiyunCurrently, it is expected that the document's sources are only local; 48*4882a593SmuzhiyunBuildroot will not attempt to download anything to render a document. 49*4882a593SmuzhiyunThus, you must indicate where the sources are. Usually, the string 50*4882a593Smuzhiyunabove is sufficient for a document with no sub-directory structure. 51*4882a593Smuzhiyun 52*4882a593SmuzhiyunOn line 8, we call the +asciidoc-document+ function, which generates all 53*4882a593Smuzhiyunthe Makefile code necessary to render the document. 54*4882a593Smuzhiyun 55*4882a593Smuzhiyun==== +asciidoc-document+ reference 56*4882a593Smuzhiyun 57*4882a593SmuzhiyunThe list of variables that can be set in a +.mk+ file to give metadata 58*4882a593Smuzhiyuninformation is (assuming the document name is +foo+) : 59*4882a593Smuzhiyun 60*4882a593Smuzhiyun* +FOO_SOURCES+, mandatory, defines the source files for the document. 61*4882a593Smuzhiyun 62*4882a593Smuzhiyun* +FOO_RESOURCES+, optional, may contain a space-separated list of paths 63*4882a593Smuzhiyun to one or more directories containing so-called resources (like CSS or 64*4882a593Smuzhiyun images). By default, empty. 65*4882a593Smuzhiyun 66*4882a593Smuzhiyun* +FOO_DEPENDENCIES+, optional, the list of packages (most probably, 67*4882a593Smuzhiyun host-packages) that must be built before building this document. 68*4882a593Smuzhiyun 69*4882a593SmuzhiyunThere are also additional hooks (see xref:hooks[] for general information 70*4882a593Smuzhiyunon hooks), that a document may set to define extra actions to be done at 71*4882a593Smuzhiyunvarious steps: 72*4882a593Smuzhiyun 73*4882a593Smuzhiyun* +FOO_POST_RSYNC_HOOKS+ to run additional commands after the sources 74*4882a593Smuzhiyun have been copied by Buildroot. This can for example be used to 75*4882a593Smuzhiyun generate part of the manual with information extracted from the 76*4882a593Smuzhiyun tree. As an example, Buildroot uses this hook to generate the tables 77*4882a593Smuzhiyun in the appendices. 78*4882a593Smuzhiyun 79*4882a593Smuzhiyun* +FOO_CHECK_DEPENDENCIES_HOOKS+ to run additional tests on required 80*4882a593Smuzhiyun components to generate the document. In AsciiDoc, it is possible to 81*4882a593Smuzhiyun call filters, that is, programs that will parse an AsciiDoc block and 82*4882a593Smuzhiyun render it appropriately (e.g. http://ditaa.sourceforge.net/[ditaa] or 83*4882a593Smuzhiyun https://pythonhosted.org/aafigure/[aafigure]). 84*4882a593Smuzhiyun 85*4882a593Smuzhiyun* +FOO_CHECK_DEPENDENCIES_<FMT>_HOOKS+, to run additional tests for 86*4882a593Smuzhiyun the specified format +<FMT>+ (see the list of rendered formats, above). 87*4882a593Smuzhiyun 88*4882a593SmuzhiyunHere is a complete example that uses all variables and all hooks: 89*4882a593Smuzhiyun 90*4882a593Smuzhiyun---- 91*4882a593Smuzhiyun01: ################################################################################ 92*4882a593Smuzhiyun02: # 93*4882a593Smuzhiyun03: # foo-document 94*4882a593Smuzhiyun04: # 95*4882a593Smuzhiyun05: ################################################################################ 96*4882a593Smuzhiyun06: 97*4882a593Smuzhiyun07: FOO_SOURCES = $(sort $(wildcard $(pkgdir)/*)) 98*4882a593Smuzhiyun08: FOO_RESOURCES = $(sort $(wildcard $(pkgdir)/ressources)) 99*4882a593Smuzhiyun09: 100*4882a593Smuzhiyun10: define FOO_GEN_EXTRA_DOC 101*4882a593Smuzhiyun11: /path/to/generate-script --outdir=$(@D) 102*4882a593Smuzhiyun12: endef 103*4882a593Smuzhiyun13: FOO_POST_RSYNC_HOOKS += FOO_GEN_EXTRA_DOC 104*4882a593Smuzhiyun14: 105*4882a593Smuzhiyun15: define FOO_CHECK_MY_PROG 106*4882a593Smuzhiyun16: if ! which my-prog >/dev/null 2>&1; then \ 107*4882a593Smuzhiyun17: echo "You need my-prog to generate the foo document"; \ 108*4882a593Smuzhiyun18: exit 1; \ 109*4882a593Smuzhiyun19: fi 110*4882a593Smuzhiyun20: endef 111*4882a593Smuzhiyun21: FOO_CHECK_DEPENDENCIES_HOOKS += FOO_CHECK_MY_PROG 112*4882a593Smuzhiyun22: 113*4882a593Smuzhiyun23: define FOO_CHECK_MY_OTHER_PROG 114*4882a593Smuzhiyun24: if ! which my-other-prog >/dev/null 2>&1; then \ 115*4882a593Smuzhiyun25: echo "You need my-other-prog to generate the foo document as PDF"; \ 116*4882a593Smuzhiyun26: exit 1; \ 117*4882a593Smuzhiyun27: fi 118*4882a593Smuzhiyun28: endef 119*4882a593Smuzhiyun29: FOO_CHECK_DEPENDENCIES_PDF_HOOKS += FOO_CHECK_MY_OTHER_PROG 120*4882a593Smuzhiyun30: 121*4882a593Smuzhiyun31: $(eval $(call asciidoc-document)) 122*4882a593Smuzhiyun---- 123