Re* [PATCH] doc: make HTML manual reproducible

Commit Message

Junio C Hamano Dec. 3, 2020, 2:31 a.m. UTC

Todd Zullinger <[e-mail]> writes:

> I suppose we'd ideally look for a v2 with --stringparam
> replaced with --param as you noted upthread?

Yes.

> And maybe an updated commit message to note that it requires
> docbook-xsl 1.79.1 to be effective, but older versions
> gracefully ignore the option?

Yes, definitely.

Here is what I'd queue tentatively to potentially reduce one
round-trip (if Arnout is happy with this version, we can just hear
"yes, that's good" without a formal v2).

Thanks.

--- >8 ------ >8 ------ >8 ------ >8 ------ >8 ------ >8 ---
From: Arnout Engelen <[e-mail]>
Date: Tue, 1 Dec 2020 09:50:37 +0000
Subject: [PATCH v2] doc: make HTML manual reproducible

Versions of docbook-xsl newer than 1.79.1 allows xsltproc to assign
IDs to nodes in the generated HTML consistently, to make the output
resulting from the same source stable and reproducible.

Pass the generate.consistent.ids parameter from the command line to
ask for this feature.  Older versions of the tool simply ignores the
parameter and produces their output the same way as before this
change, so there is no need to check for toolchain version.

Signed-off-by: Arnout Engelen <[e-mail]>
Helped-by: brian m. carlson <[e-mail]>
Helped-by: Todd Zullinger <[e-mail]>
Signed-off-by: Junio C Hamano <[e-mail]>
---

Notes (amlog):
    Message-Id: <[e-mail]>

 Documentation/Makefile | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

Comments

Arnout Engelen Dec. 3, 2020, 8:07 a.m. UTC | #1

Hi,

First of all, I'm super impressed by the quality of the review here,
thanks for that everyone!

On Thu, Dec 3, 2020 at 3:31 AM Junio C Hamano <[e-mail]> wrote:
> Here is what I'd queue tentatively to potentially reduce one
> round-trip (if Arnout is happy with this version, we can just hear
> "yes, that's good" without a formal v2).

This looks good to me, thank you!


Kind regards,

Arnout

> --- >8 ------ >8 ------ >8 ------ >8 ------ >8 ------ >8 ---
> From: Arnout Engelen <[e-mail]>
> Date: Tue, 1 Dec 2020 09:50:37 +0000
> Subject: [PATCH v2] doc: make HTML manual reproducible
>
> Versions of docbook-xsl newer than 1.79.1 allows xsltproc to assign
> IDs to nodes in the generated HTML consistently, to make the output
> resulting from the same source stable and reproducible.
>
> Pass the generate.consistent.ids parameter from the command line to
> ask for this feature.  Older versions of the tool simply ignores the
> parameter and produces their output the same way as before this
> change, so there is no need to check for toolchain version.
>
> Signed-off-by: Arnout Engelen <[e-mail]>
> Helped-by: brian m. carlson <[e-mail]>
> Helped-by: Todd Zullinger <[e-mail]>
> Signed-off-by: Junio C Hamano <[e-mail]>
> ---
>
> Notes (amlog):
>     Message-Id: <[e-mail]>
>
>  Documentation/Makefile | 5 ++++-
>  1 file changed, 4 insertions(+), 1 deletion(-)
>
> diff --git a/Documentation/Makefile b/Documentation/Makefile
> index 80d1908a44..69dbe4bb0b 100644
> --- a/Documentation/Makefile
> +++ b/Documentation/Makefile
> @@ -380,7 +380,10 @@ SubmittingPatches.txt: SubmittingPatches
>         $(QUIET_GEN) cp $< $@
>
>  XSLT = docbook.xsl
> -XSLTOPTS = --xinclude --stringparam html.stylesheet docbook-xsl.css
> +XSLTOPTS =
> +XSLTOPTS += --xinclude
> +XSLTOPTS += --stringparam html.stylesheet docbook-xsl.css
> +XSLTOPTS += --param generate.consistent.ids 1
>
>  user-manual.html: user-manual.xml $(XSLT)
>         $(QUIET_XSLTPROC)$(RM) $@+ $@ && \
> --
> 2.29.2-589-gfe47622759
>
>

Patch

diff --git a/Documentation/Makefile b/Documentation/Makefile
index 80d1908a44..69dbe4bb0b 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -380,7 +380,10 @@  SubmittingPatches.txt: SubmittingPatches
 	$(QUIET_GEN) cp $< $@
 
 XSLT = docbook.xsl
-XSLTOPTS = --xinclude --stringparam html.stylesheet docbook-xsl.css
+XSLTOPTS =
+XSLTOPTS += --xinclude
+XSLTOPTS += --stringparam html.stylesheet docbook-xsl.css
+XSLTOPTS += --param generate.consistent.ids 1
 
 user-manual.html: user-manual.xml $(XSLT)
 	$(QUIET_XSLTPROC)$(RM) $@+ $@ && \