From patchwork Wed Jan 18 07:14:10 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: "Yann E. MORIN" X-Patchwork-Id: 1728009 Return-Path: X-Original-To: incoming-buildroot@patchwork.ozlabs.org Delivered-To: patchwork-incoming-buildroot@legolas.ozlabs.org Authentication-Results: legolas.ozlabs.org; spf=pass (sender SPF authorized) smtp.mailfrom=buildroot.org (client-ip=2605:bc80:3010::138; helo=smtp1.osuosl.org; envelope-from=buildroot-bounces@buildroot.org; receiver=) Received: from smtp1.osuosl.org (smtp1.osuosl.org [IPv6:2605:bc80:3010::138]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature ECDSA (P-384) server-digest SHA384) (No client certificate requested) by legolas.ozlabs.org (Postfix) with ESMTPS id 4NxcT06Rlwz23gM for ; Wed, 18 Jan 2023 18:14:28 +1100 (AEDT) Received: from localhost (localhost [127.0.0.1]) by smtp1.osuosl.org (Postfix) with ESMTP id 06BC081E7D; Wed, 18 Jan 2023 07:14:27 +0000 (UTC) DKIM-Filter: OpenDKIM Filter v2.11.0 smtp1.osuosl.org 06BC081E7D X-Virus-Scanned: amavisd-new at osuosl.org Received: from smtp1.osuosl.org ([127.0.0.1]) by localhost (smtp1.osuosl.org [127.0.0.1]) (amavisd-new, port 10024) with ESMTP id B_rAWh1PGRkw; Wed, 18 Jan 2023 07:14:26 +0000 (UTC) Received: from ash.osuosl.org (ash.osuosl.org [140.211.166.34]) by smtp1.osuosl.org (Postfix) with ESMTP id 2C69381E51; Wed, 18 Jan 2023 07:14:25 +0000 (UTC) DKIM-Filter: OpenDKIM Filter v2.11.0 smtp1.osuosl.org 2C69381E51 X-Original-To: buildroot@lists.busybox.net Delivered-To: buildroot@osuosl.org Received: from smtp4.osuosl.org (smtp4.osuosl.org [140.211.166.137]) by ash.osuosl.org (Postfix) with ESMTP id 631081BF3D2 for ; Wed, 18 Jan 2023 07:14:23 +0000 (UTC) Received: from localhost (localhost [127.0.0.1]) by smtp4.osuosl.org (Postfix) with ESMTP id 4A4614160B for ; Wed, 18 Jan 2023 07:14:23 +0000 (UTC) DKIM-Filter: OpenDKIM Filter v2.11.0 smtp4.osuosl.org 4A4614160B X-Virus-Scanned: amavisd-new at osuosl.org Received: from smtp4.osuosl.org ([127.0.0.1]) by localhost (smtp4.osuosl.org [127.0.0.1]) (amavisd-new, port 10024) with ESMTP id nQpkRUSwdlcj for ; Wed, 18 Jan 2023 07:14:21 +0000 (UTC) X-Greylist: from auto-whitelisted by SQLgrey-1.8.0 DKIM-Filter: OpenDKIM Filter v2.11.0 smtp4.osuosl.org D510341606 Received: from relais-inet.orange.com (relais-inet.orange.com [80.12.70.35]) by smtp4.osuosl.org (Postfix) with ESMTPS id D510341606 for ; Wed, 18 Jan 2023 07:14:20 +0000 (UTC) Received: from opfednr06.francetelecom.fr (unknown [xx.xx.xx.70]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits)) (No client certificate requested) by opfednr27.francetelecom.fr (ESMTP service) with ESMTPS id 4NxcSp3RYrz4wyv for ; Wed, 18 Jan 2023 08:14:18 +0100 (CET) Received: by tl-lnx-nyma7486 (sSMTP sendmail emulation); Wed, 18 Jan 2023 08:14:11 +0100 From: To: Date: Wed, 18 Jan 2023 08:14:10 +0100 Message-ID: <7653_1674026058_63C79C4A_7653_242_1_e5a79e14d6b9a1d81047cdd6605184ecae6803f8.1674025553.git.yann.morin@orange.com> X-Mailer: git-send-email 2.25.1 MIME-Version: 1.0 X-Originating-IP: [10.115.26.52] X-ClientProxiedBy: OPE16NORMBX607.corporate.adroot.infra.ftgroup (10.115.27.31) To OPE16NORMBX305.corporate.adroot.infra.ftgroup (10.115.27.10) X-Mailman-Original-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=orange.com; s=ORANGE001; t=1674026058; bh=bQ/qs9k4cunkErcTsjMxMW0iMW0CtxCsLZy7eqNMh7Q=; h=From:To:Subject:Date:Message-ID:MIME-Version: Content-Transfer-Encoding:Content-Type; b=hE4NRv8C+n7idnMxbmJNwIvwfMVsNS6Kr+V+fWgLHyz/OebBKaMTYSg3lM637jNef OcSuEi7g7eyeJ0t4gE1TXSBW2YlNJ34tGgdB+IzFM1YUexoPLLE+4a0N8uH85ssYGy 5B6hyBLMfGltXHgTfjNiO+uJYWAocefFG7gWtoHydxFokXIkDbbI0jhhR3NbZReRIN HRPVDs5qbFZSvDc74bnrRLJqxG2rw+pGH7ZNOB+anW8mcgqUg7JDYAuMnQfR/qtxdw 5kuEKagABzusFu5mPHBVg3ySVhXofxmSbCRe60TnJ/llo2QgotXYkmkc3/3/WmXTls 6CNepqkZp70cg== X-Mailman-Original-Authentication-Results: smtp4.osuosl.org; dkim=pass (2048-bit key) header.d=orange.com header.i=@orange.com header.a=rsa-sha256 header.s=ORANGE001 header.b=hE4NRv8C Subject: [Buildroot] [PATCH 1/2] package/doc-asciidoc: specify TOC depth for all formats X-BeenThere: buildroot@buildroot.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: Discussion and development of buildroot List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: yann.morin@orange.com Errors-To: buildroot-bounces@buildroot.org Sender: "buildroot" Commit 17feaf00160d (manual: set toc depth to 4 for html outputs) did not explain why it set the depth of the table of content (TOC) only for the html and split-html formats. From memory, but it is a bit fuzzy after all those years, the TOC for HTML documentation was by default deeper than for the other formats, so it was really useless to expand it more than one-level deep, while for other formats, the default was acceptable. However, it does not make much sense to limit/enforce the depth of the TOC only for specific formats, and keep the default for the others; indeed, there is nothing that prevents the default to change with various versions of asciidoc and the rendering backends. Render all the formats with the same, explicit level of TOC. We move the assignment of _A2X_OPTS above the comment, because the comment does not apply to the TOC setting. Also note that the previous assignment to an empty value was completely superfluous... Signed-off-by: Yann E. MORIN --- package/doc-asciidoc.mk | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/package/doc-asciidoc.mk b/package/doc-asciidoc.mk index 2bd761edfb..931c5136d4 100644 --- a/package/doc-asciidoc.mk +++ b/package/doc-asciidoc.mk @@ -86,11 +86,13 @@ ifneq ($$(wildcard $$($(2)_$(3)_ASCIIDOC_CONF)),) $(2)_$(3)_ASCIIDOC_OPTS += -f $$($(2)_$(3)_ASCIIDOC_CONF) endif +$(2)_$(3)_A2X_OPTS = \ + --xsltproc-opts "--stringparam toc.section.depth 1" + # Handle a2x warning about --destination-dir option only applicable to HTML # based outputs. So: # - use the --destination-dir option if possible (html and split-html), # - otherwise copy the generated document to the output directory -$(2)_$(3)_A2X_OPTS = ifneq ($$(filter $(4),html split-html),) $(2)_$(3)_A2X_OPTS += --destination-dir="$$(@D)" else @@ -161,11 +163,9 @@ $(1)-prepare-sources: $$(BUILD_DIR)/docs/$(1)/.stamp_doc_rsynced $(2)_ASCIIDOC_CONF = $$($(2)_DOCDIR)/asciidoc.conf -$(call ASCIIDOC_INNER,$(1),$(2),xhtml,html,html,HTML,\ - --xsltproc-opts "--stringparam toc.section.depth 1") +$(call ASCIIDOC_INNER,$(1),$(2),xhtml,html,html,HTML) -$(call ASCIIDOC_INNER,$(1),$(2),chunked,split-html,chunked,split HTML,\ - --xsltproc-opts "--stringparam toc.section.depth 1") +$(call ASCIIDOC_INNER,$(1),$(2),chunked,split-html,chunked,split HTML) # dblatex needs to pass the '--maxvars ...' option to xsltproc to prevent it # from reaching the template recursion limit when processing the (long) target From patchwork Wed Jan 18 07:14:11 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: "Yann E. MORIN" X-Patchwork-Id: 1728010 Return-Path: X-Original-To: incoming-buildroot@patchwork.ozlabs.org Delivered-To: patchwork-incoming-buildroot@legolas.ozlabs.org Authentication-Results: legolas.ozlabs.org; spf=pass (sender SPF authorized) smtp.mailfrom=buildroot.org (client-ip=140.211.166.136; helo=smtp3.osuosl.org; envelope-from=buildroot-bounces@buildroot.org; receiver=) Received: from smtp3.osuosl.org (smtp3.osuosl.org [140.211.166.136]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature ECDSA (P-384) server-digest SHA384) (No client certificate requested) by legolas.ozlabs.org (Postfix) with ESMTPS id 4NxcTF45kMz23gM for ; Wed, 18 Jan 2023 18:14:41 +1100 (AEDT) Received: from localhost (localhost [127.0.0.1]) by smtp3.osuosl.org (Postfix) with ESMTP id 80E7960BBF; Wed, 18 Jan 2023 07:14:39 +0000 (UTC) DKIM-Filter: OpenDKIM Filter v2.11.0 smtp3.osuosl.org 80E7960BBF X-Virus-Scanned: amavisd-new at osuosl.org Received: from smtp3.osuosl.org ([127.0.0.1]) by localhost (smtp3.osuosl.org [127.0.0.1]) (amavisd-new, port 10024) with ESMTP id qsAFg_j-SYjm; Wed, 18 Jan 2023 07:14:38 +0000 (UTC) Received: from ash.osuosl.org (ash.osuosl.org [140.211.166.34]) by smtp3.osuosl.org (Postfix) with ESMTP id 9F33E60AAD; Wed, 18 Jan 2023 07:14:37 +0000 (UTC) DKIM-Filter: OpenDKIM Filter v2.11.0 smtp3.osuosl.org 9F33E60AAD X-Original-To: buildroot@lists.busybox.net Delivered-To: buildroot@osuosl.org Received: from smtp2.osuosl.org (smtp2.osuosl.org [140.211.166.133]) by ash.osuosl.org (Postfix) with ESMTP id 406391BF3D2 for ; Wed, 18 Jan 2023 07:14:24 +0000 (UTC) Received: from localhost (localhost [127.0.0.1]) by smtp2.osuosl.org (Postfix) with ESMTP id 28ECC40377 for ; Wed, 18 Jan 2023 07:14:24 +0000 (UTC) DKIM-Filter: OpenDKIM Filter v2.11.0 smtp2.osuosl.org 28ECC40377 X-Virus-Scanned: amavisd-new at osuosl.org Received: from smtp2.osuosl.org ([127.0.0.1]) by localhost (smtp2.osuosl.org [127.0.0.1]) (amavisd-new, port 10024) with ESMTP id gFrImsDXKTHG for ; Wed, 18 Jan 2023 07:14:23 +0000 (UTC) X-Greylist: from auto-whitelisted by SQLgrey-1.8.0 DKIM-Filter: OpenDKIM Filter v2.11.0 smtp2.osuosl.org BC0BF40253 Received: from relais-inet.orange.com (relais-inet.orange.com [80.12.70.36]) by smtp2.osuosl.org (Postfix) with ESMTPS id BC0BF40253 for ; Wed, 18 Jan 2023 07:14:22 +0000 (UTC) Received: from opfednr06.francetelecom.fr (unknown [xx.xx.xx.70]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits)) (No client certificate requested) by opfednr25.francetelecom.fr (ESMTP service) with ESMTPS id 4NxcSr1TDZzCr83 for ; Wed, 18 Jan 2023 08:14:20 +0100 (CET) Received: by tl-lnx-nyma7486 (sSMTP sendmail emulation); Wed, 18 Jan 2023 08:14:13 +0100 From: To: Date: Wed, 18 Jan 2023 08:14:11 +0100 Message-ID: <5608_1674026060_63C79C4C_5608_450_1_3268e156530869e8fea307493cc0ee3d8d8df679.1674025553.git.yann.morin@orange.com> X-Mailer: git-send-email 2.25.1 In-Reply-To: References: MIME-Version: 1.0 X-Originating-IP: [10.115.26.50] X-ClientProxiedBy: OPE16NORMBX102.corporate.adroot.infra.ftgroup (10.115.26.3) To OPE16NORMBX305.corporate.adroot.infra.ftgroup (10.115.27.10) X-Mailman-Original-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=orange.com; s=ORANGE001; t=1674026060; bh=uFjVsG1OVv9amXHAmAcxKsAeAo3ZCOv9G6FIZ7lp4vw=; h=From:To:Subject:Date:Message-ID:MIME-Version: Content-Transfer-Encoding:Content-Type; b=azPK7Mo/oEbUHNRfPC60jQGXR+8TaDpj7PzeqfXPdhyuP/OnEZymNYWjlTpY9oSys 4aC2e1xvY/Bd7HBnUzj+rPMd4K8eLxFf49CxAlDtRnvmnAI9U1Bk9nb1fICsZYtx/R eCVSXgsVbVa7Un4muQzPTE4gMBMKLHRsmuOA0yReWX0bvq/H42G1Tn8S6H7OFIeCe2 Ftbg5Xe3Udwiva9Qu63EClUgFWMLtYwz6srhyBk7vCmErKyeaEFMdruwLJsc8dTnT6 0LgLTl7x7XmyrPl9x48yQh0b9JPyMT58tZ/CQdrb5tE34/M/RvEvU7m5ocdERYPTA0 Zs332R6p4RBIQ== X-Mailman-Original-Authentication-Results: smtp2.osuosl.org; dkim=pass (2048-bit key) header.d=orange.com header.i=@orange.com header.a=rsa-sha256 header.s=ORANGE001 header.b=azPK7Mo/ Subject: [Buildroot] [PATCH 2/2] package/doc-ssciidoc: allow docs to request a specific TOC depth X-BeenThere: buildroot@buildroot.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: Discussion and development of buildroot List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: yann.morin@orange.com Errors-To: buildroot-bounces@buildroot.org Sender: "buildroot" 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 --- 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)