Re: [PATCH] doc: make HTML manual reproducible

[Junio C Hamano <gitster@pobox.com>]

Todd Zullinger <tmz@pobox.com> writes:

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

I think it is in general a good thing to do (can we lose some lines
from doc-diff, I wonder?) and many of the result of your study shown
above should be in the log message in a summarised form.  Here is a
starter.

    Generated ID's in the HTML version of the documentation does not
    stay the same even when they are generated from the identical
    source.  Pass generate.consistent.ids=1 to the xsltproc tool to
    make them stable, which would help reproducible build product.

    We currently only support docbook-xsl version 1.74 or newer, but
    this option requires version at least 1.77.1 (released in June
    2012), which would be OK for supported releases of CentOS/RHEL
    and Debian/Ubuntu (most have 1.79.x).

We may probably want to talk about versions commonly distributed for
macOS and BSDs as well (I do not know if we want to list minor Linux
distros).  And we definitely need to update INSTALL as you pointed
out.

Thanks and thanks for CC'ing those who may know the area well.