Re: [PATCH] doc: make HTML manual reproducible

[Todd Zullinger <tmz@pobox.com>]

Hi Arnout,

[cc: brian, Martin, and peff, for their collective wisdom in
the area of docs and involvement in the last discussion of
docbook-xsl requirements.]

Arnout Engelen wrote:
> This makes sure the generated id's inside the html version of the
> documentation use the same id's when the same version of the
> manual is generated twice.
> 
> Signed-off-by: Arnout Engelen <arnout@bzzt.net>
> ---
>  Documentation/Makefile | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
> 
> diff --git a/Documentation/Makefile b/Documentation/Makefile
> index 80d1908a44..4d1fd5e31f 100644
> --- a/Documentation/Makefile
> +++ b/Documentation/Makefile
> @@ -380,7 +380,7 @@ SubmittingPatches.txt: SubmittingPatches
>  	$(QUIET_GEN) cp $< $@
>  
>  XSLT = docbook.xsl
> -XSLTOPTS = --xinclude --stringparam html.stylesheet docbook-xsl.css
> +XSLTOPTS = --xinclude --stringparam html.stylesheet docbook-xsl.css --stringparam generate.consistent.ids 1
>  
>  user-manual.html: user-manual.xml $(XSLT)
>  	$(QUIET_XSLTPROC)$(RM) $@+ $@ && \

I think this would raise the minimum supported version of
docbook-xsl to 1.77.1.  That might be fine, but we'd
probably want to make sure it doesn't negatively impact
OS/distributions which build the docs as a likely group who
care about reproducible builds.  And we'd want to update the
requirement in INSTALL, of course.

The minimum docbook-xsl version was raised from 1.73 to
1.74, in 5a80d85bbe (INSTALL: drop support for docbook-xsl
before 1.74, 2020-03-29).  That change was discussed in
<cover.1585486103.git.martin.agren@gmail.com>¹.

AFAICT, the generate.consistent.ids param was added in
docbook-xsl-1.77.1 which was released in June 2012.  The
commit which added it is 74735098e (New param to support
replacing generate-id() with xsl:number for more consistent
id values., 2011-10-24).

In any case, a minimum of 1.77.1 is present in the supported
releases of CentOS/RHEL and Debian/Ubuntu, at least (most
have 1.79.x).  Those are certainly not the only systems Git
cares about; they're simply the systems with which I am at
least mildly familiar.

¹ https://lore.kernel.org/git/cover.1585486103.git.martin.agren@gmail.com/

-- 
Todd