6a6a11f64b
For some documents, we may want a terse or deeper TOC depth. For example, short documents may want just the level-0 in the TOC, while longer documents may want depth 1 or 2, or even deeper; also, some documents may not use the document-title levels [0], only section levels [1], and so may want to increase the TOC depth. Additionally, allow per-format depth. For example, split-html has a single page dedicated to the TOC, so there we may want a deeper TOC, while on the html output, where the TOC is on the same page as the whole document, a shorter TOC is preferred. [0] https://docs.asciidoctor.org/asciidoc/latest/syntax-quick-reference/#document-header [1] https://docs.asciidoctor.org/asciidoc/latest/syntax-quick-reference/#section-titles Signed-off-by: Yann E. MORIN <yann.morin@orange.com> Signed-off-by: Arnout Vandecappelle <arnout@mind.be>
144 lines
5.2 KiB
Plaintext
144 lines
5.2 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.
|
|
|
|
* +FOO_TOC_DEPTH+, +FOO_TOC_DEPTH_<FMT>+, optionals, the depth of the
|
|
table of content for this document, which can be overridden for the
|
|
specified format +<FMT>+ (see the list of rendered formats, above,
|
|
but in uppercase, and with dash replaced by underscore; see example,
|
|
below). By default: +1+.
|
|
|
|
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: FOO_TOC_DEPTH = 2
|
|
11: FOO_TOC_DEPTH_HTML = 1
|
|
12: FOO_TOC_DEPTH_SPLIT_HTML = 3
|
|
13:
|
|
14: define FOO_GEN_EXTRA_DOC
|
|
15: /path/to/generate-script --outdir=$(@D)
|
|
16: endef
|
|
17: FOO_POST_RSYNC_HOOKS += FOO_GEN_EXTRA_DOC
|
|
18:
|
|
19: define FOO_CHECK_MY_PROG
|
|
20: if ! which my-prog >/dev/null 2>&1; then \
|
|
21: echo "You need my-prog to generate the foo document"; \
|
|
22: exit 1; \
|
|
23: fi
|
|
24: endef
|
|
25: FOO_CHECK_DEPENDENCIES_HOOKS += FOO_CHECK_MY_PROG
|
|
26:
|
|
27: define FOO_CHECK_MY_OTHER_PROG
|
|
28: if ! which my-other-prog >/dev/null 2>&1; then \
|
|
29: echo "You need my-other-prog to generate the foo document as PDF"; \
|
|
30: exit 1; \
|
|
31: fi
|
|
32: endef
|
|
33: FOO_CHECK_DEPENDENCIES_PDF_HOOKS += FOO_CHECK_MY_OTHER_PROG
|
|
34:
|
|
35: $(eval $(call asciidoc-document))
|
|
----
|