@@ -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))
----
@@ -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)
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. Additioanlly, 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> --- docs/manual/adding-packages-asciidoc.txt | 54 ++++++++++++++---------- package/doc-asciidoc.mk | 3 +- 2 files changed, 34 insertions(+), 23 deletions(-)