4f59ababc0
The doc-asciidoc infra allows document to define sources and resources, and those can only be local (there is no download support for documents). The currently documented way to specify those is to use the $(pkgdir) macro to point to the document sources and resources when they are along the .mk. However, this works only for sources and not for resources. Indeed, sources are used to generate Makefile dependency rules, so $(pkgdir) is expanded and evaluated during the call to $(doc-asciidoc), while resources are expanded and evaluated when the rules are executed, which always happen after all the parsing has be done, at which point $(pkgdir) expands to the last Makefile that was parsed, which is always Buildroot's own manual. This went unnoticed so far because Buildroot's manual is 1) the last to be parsed, and 2) not using $(pkgdir) anyway. Additionally, $(pkgdir) is mostly an internal macro, that is, as this change demonstrates, difficult to use, and thus should not be used, in packages or in documents. We fix that by introducing $(FOO_DOCDIR), similar to $(FOO_PKGDIR), which points to the document directory. We choose not to name the variable FOO_PKGDIR, because it semantically is not a package. As a consequence, the last argument to the doc-asciidoc macro is now superfluous, so it is removed, which causes a little bit of churn in the main macro. As a further consequence, the third argument in the inner macro is no longer needed either, so it too is removed, which causes a bit more churn yet in the inner macro. Signed-off-by: Yann E. MORIN <yann.morin@orange.com> Cc: Frederic GARDES <frederic.gardes@orange.com> Signed-off-by: Arnout Vandecappelle (Essensium/Mind) <arnout@mind.be>
134 lines
4.8 KiB
Plaintext
134 lines
4.8 KiB
Plaintext
// -*- mode:doc; -*-
|
|
// vim: syntax=asciidoc
|
|
|
|
=== Infrastructure for asciidoc documents
|
|
|
|
[[asciidoc-documents-tutorial]]
|
|
|
|
The Buildroot manual, which you are currently reading, is entirely written
|
|
using the http://asciidoc.org/[AsciiDoc] mark-up syntax. The manual is then
|
|
rendered to many formats:
|
|
|
|
* html
|
|
* split-html
|
|
* pdf
|
|
* epub
|
|
* text
|
|
|
|
Although Buildroot only contains one document written in AsciiDoc, there
|
|
is, as for packages, an infrastructure for rendering documents using the
|
|
AsciiDoc syntax.
|
|
|
|
Also as for packages, the AsciiDoc infrastructure is available from a
|
|
xref:outside-br-custom[br2-external tree]. This allows documentation for
|
|
a br2-external tree to match the Buildroot documentation, as it will be
|
|
rendered to the same formats and use the same layout and theme.
|
|
|
|
==== +asciidoc-document+ tutorial
|
|
|
|
Whereas package infrastructures are suffixed with +-package+, the document
|
|
infrastructures are suffixed with +-document+. So, the AsciiDoc infrastructure
|
|
is named +asciidoc-document+.
|
|
|
|
Here is an example to render a simple AsciiDoc document.
|
|
|
|
----
|
|
01: ################################################################################
|
|
02: #
|
|
03: # foo-document
|
|
04: #
|
|
05: ################################################################################
|
|
06:
|
|
07: FOO_SOURCES = $(sort $(wildcard $(FOO_DOCDIR)/*))
|
|
08: $(eval $(call asciidoc-document))
|
|
----
|
|
|
|
On line 7, the Makefile declares what the sources of the document are.
|
|
Currently, it is expected that the document's sources are only local;
|
|
Buildroot will not attempt to download anything to render a document.
|
|
Thus, you must indicate where the sources are. Usually, the string
|
|
above is sufficient for a document with no sub-directory structure.
|
|
|
|
On line 8, we call the +asciidoc-document+ function, which generates all
|
|
the Makefile code necessary to render the document.
|
|
|
|
==== +asciidoc-document+ reference
|
|
|
|
The list of variables that can be set in a +.mk+ file to give metadata
|
|
information is (assuming the document name is +foo+) :
|
|
|
|
* +FOO_SOURCES+, mandatory, defines the source files for the document.
|
|
|
|
* +FOO_RESOURCES+, optional, may contain a space-separated list of paths
|
|
to one or more directories containing so-called resources (like CSS or
|
|
images). By default, empty.
|
|
|
|
* +FOO_DEPENDENCIES+, optional, the list of packages (most probably,
|
|
host-packages) that must be built before building this document.
|
|
|
|
There are also additional hooks (see xref:hooks[] for general information
|
|
on hooks), that a document may set to define extra actions to be done at
|
|
various steps:
|
|
|
|
* +FOO_POST_RSYNC_HOOKS+ to run additional commands after the sources
|
|
have been copied by Buildroot. This can for example be used to
|
|
generate part of the manual with information extracted from the
|
|
tree. As an example, Buildroot uses this hook to generate the tables
|
|
in the appendices.
|
|
|
|
* +FOO_CHECK_DEPENDENCIES_HOOKS+ to run additional tests on required
|
|
components to generate the document. In AsciiDoc, it is possible to
|
|
call filters, that is, programs that will parse an AsciiDoc block and
|
|
render it appropriately (e.g. http://ditaa.sourceforge.net/[ditaa] or
|
|
https://pythonhosted.org/aafigure/[aafigure]).
|
|
|
|
* +FOO_CHECK_DEPENDENCIES_<FMT>_HOOKS+, to run additional tests for
|
|
the specified format +<FMT>+ (see the list of rendered formats, above).
|
|
|
|
Buildroot sets the following variable that can be used in the definitions
|
|
above:
|
|
|
|
* +$(FOO_DOCDIR)+, similar to +$(FOO_PKGDIR)+, contains the path to the
|
|
directory containing +foo.mk+. It can be used to refer to the document
|
|
sources, and can be used in the hooks, especially the post-rsync hook
|
|
if parts of the documentation needs to be generated.
|
|
|
|
* +$(@D)+, as for traditional packages, contains the path to the directory
|
|
where the document will be copied and built.
|
|
|
|
Here is a complete example that uses all variables and all hooks:
|
|
|
|
----
|
|
01: ################################################################################
|
|
02: #
|
|
03: # foo-document
|
|
04: #
|
|
05: ################################################################################
|
|
06:
|
|
07: FOO_SOURCES = $(sort $(wildcard $(FOO_DOCDIR)/*))
|
|
08: FOO_RESOURCES = $(sort $(wildcard $(FOO_DOCDIR)/ressources))
|
|
09:
|
|
10: define FOO_GEN_EXTRA_DOC
|
|
11: /path/to/generate-script --outdir=$(@D)
|
|
12: endef
|
|
13: FOO_POST_RSYNC_HOOKS += FOO_GEN_EXTRA_DOC
|
|
14:
|
|
15: define FOO_CHECK_MY_PROG
|
|
16: if ! which my-prog >/dev/null 2>&1; then \
|
|
17: echo "You need my-prog to generate the foo document"; \
|
|
18: exit 1; \
|
|
19: fi
|
|
20: endef
|
|
21: FOO_CHECK_DEPENDENCIES_HOOKS += FOO_CHECK_MY_PROG
|
|
22:
|
|
23: define FOO_CHECK_MY_OTHER_PROG
|
|
24: if ! which my-other-prog >/dev/null 2>&1; then \
|
|
25: echo "You need my-other-prog to generate the foo document as PDF"; \
|
|
26: exit 1; \
|
|
27: fi
|
|
28: endef
|
|
29: FOO_CHECK_DEPENDENCIES_PDF_HOOKS += FOO_CHECK_MY_OTHER_PROG
|
|
30:
|
|
31: $(eval $(call asciidoc-document))
|
|
----
|