From 6a6a11f64b305e272d34e84d1e9e9b61ada24218 Mon Sep 17 00:00:00 2001 From: "Yann E. MORIN" Date: Wed, 18 Jan 2023 08:14:11 +0100 Subject: [PATCH] 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 Signed-off-by: Arnout Vandecappelle --- docs/manual/adding-packages-asciidoc.txt | 54 ++++++++++++++---------- package/doc-asciidoc.mk | 3 +- 2 files changed, 34 insertions(+), 23 deletions(-) diff --git a/docs/manual/adding-packages-asciidoc.txt b/docs/manual/adding-packages-asciidoc.txt index 0bfe99d22e..d68978b1cb 100644 --- a/docs/manual/adding-packages-asciidoc.txt +++ b/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_+, optionals, the depth of the + table of content for this document, which can be overridden for the + specified format ++ (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)) ---- diff --git a/package/doc-asciidoc.mk b/package/doc-asciidoc.mk index 931c5136d4..6b8eaa81b3 100644 --- a/package/doc-asciidoc.mk +++ b/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)