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

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>

docs/manual/adding-packages-asciidoc.txt

@@ -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))
 ----

package/doc-asciidoc.mk

@@ -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)