[Buildroot] [PATCH 1/2] package/doc-asciidoc: specify TOC depth for all formats

[Arnout Vandecappelle]

On 18/01/2023 08:14, yann.morin at orange.com wrote:
> 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 <yann.morin at orange.com>

  Applied to master, thanks.

  I did fix up the Author entry, though - for some reason, your name dropped 
from it. I guess there's a mailserver somewhere that borks the From line... I 
think it's sufficient to pass --from to git-format-patch to fix this.

  Regards,
  Arnout

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