Re: [PATCH] doc: make HTML manual reproducible

From: Todd Zullinger <tmz@pobox.com>
Date: Dec 1, 2020, 15:41 UTC
Message-ID: <20201201154115.GP748@pobox.com>
In-Reply-To: <20201201095037.20715-1-arnout@bzzt.net>

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:

Show 22 quoted lines

> 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