NetCube-Systems-Austria/kumquat-buildroot
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

package/doc-asciidoc: allow docs to request a specific TOC depth

Browse Source 
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>
This commit is contained in:
Yann E. MORIN 2023-01-18 08:14:11 +01:00 committed by Arnout Vandecappelle
parent 09d954fc4e
commit 6a6a11f64b
2 changed files with 34 additions and 23 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

54
docs/manual/adding-packages-asciidoc.txt
View File

@ -66,6 +66,12 @@ information is (assuming the document name is +foo+) :
* +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:
@ -108,26 +114,30 @@ Here is a complete example that uses all variables and all hooks:
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))
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))
----

3
package/doc-asciidoc.mk
View File

@ -87,7 +87,7 @@ $(2)_$(3)_ASCIIDOC_OPTS += -f $$($(2)_$(3)_ASCIIDOC_CONF)
endif
$(2)_$(3)_A2X_OPTS = \
--xsltproc-opts "--stringparam toc.section.depth 1"
--xsltproc-opts "--stringparam toc.section.depth $$(or $$($(2)_TOC_DEPTH_$$(call UPPERCASE,$(4))),$$($(2)_TOC_DEPTH))"
# Handle a2x warning about --destination-dir option only applicable to HTML
# based outputs. So:
@ -161,6 +161,7 @@ $$(BUILD_DIR)/docs/$(1)/.stamp_doc_rsynced:
.PHONY: $(1)-prepare-sources
$(1)-prepare-sources: $$(BUILD_DIR)/docs/$(1)/.stamp_doc_rsynced
$(2)_TOC_DEPTH ?= 1
$(2)_ASCIIDOC_CONF = $$($(2)_DOCDIR)/asciidoc.conf
$(call ASCIIDOC_INNER,$(1),$(2),xhtml,html,html,HTML)