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

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@orange.com>
---
 package/doc-asciidoc.mk | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

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

Arnout, All,

On 2023-04-10 22:05 +0200, Arnout Vandecappelle spake thusly:
> On 18/01/2023 08:14, yann.morin@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@orange.com>
> 
>  Applied to master, thanks.

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.

Yup, sorry, no idea where that happens in the chain... I've fixed my
~/.gitconfig appropriately now.

Regards,
Yann E. MORIN.

>  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