{"thread":{"id":"54739","subject":"[PATCH] doc: make HTML manual reproducible","startedAt":"2020-12-01T09:51:58Z","lastAt":"2020-12-03T08:08:49Z","messageCount":15,"participants":["Arnout Engelen","Todd Zullinger","Martin Ågren","Junio C Hamano","brian m. carlson","Jeff King"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"411042","messageId":"20201201095037.20715-1-arnout@bzzt.net","threadId":"54739","inReplyTo":null,"subject":"[PATCH] doc: make HTML manual reproducible","fromName":"Arnout Engelen","fromEmail":"arnout@bzzt.net","sentAt":"2020-12-01T09:50:37Z","receivedAt":"2020-12-01T09:51:58Z","isPatch":true,"sender":{"key":"arnout@bzzt.net","avatar":null},"body":"This makes sure the generated id's inside the html version of the\ndocumentation use the same id's when the same version of the\nmanual is generated twice.\n\nSigned-off-by: Arnout Engelen \n---\n Documentation/Makefile | 2 +-\n 1 file changed, 1 insertion(+), 1 deletion(-)\n\ndiff --git a/Documentation/Makefile b/Documentation/Makefile\nindex 80d1908a44..4d1fd5e31f 100644\n--- a/Documentation/Makefile\n+++ b/Documentation/Makefile\n@@ -380,7 +380,7 @@ SubmittingPatches.txt: SubmittingPatches\n \t$(QUIET_GEN) cp $< $@\n \n XSLT = docbook.xsl\n-XSLTOPTS = --xinclude --stringparam html.stylesheet docbook-xsl.css\n+XSLTOPTS = --xinclude --stringparam html.stylesheet docbook-xsl.css --stringparam generate.consistent.ids 1\n \n user-manual.html: user-manual.xml $(XSLT)\n \t$(QUIET_XSLTPROC)$(RM) $@+ $@ && \\\n-- \n2.29.2\n\n"},{"id":"411073","messageId":"20201201154115.GP748@pobox.com","threadId":"54739","inReplyTo":"20201201095037.20715-1-arnout@bzzt.net","subject":"Re: [PATCH] doc: make HTML manual reproducible","fromName":"Todd Zullinger","fromEmail":"tmz@pobox.com","sentAt":"2020-12-01T15:41:15Z","receivedAt":"2020-12-01T15:42:20Z","isPatch":true,"sender":{"key":"tmz@pobox.com","avatar":"https://avatars.githubusercontent.com/u/806319?v=4"},"body":"Hi Arnout,\n\n[cc: brian, Martin, and peff, for their collective wisdom in\nthe area of docs and involvement in the last discussion of\ndocbook-xsl requirements.]\n\nArnout Engelen wrote:\n> This makes sure the generated id's inside the html version of the\n> documentation use the same id's when the same version of the\n> manual is generated twice.\n> \n> Signed-off-by: Arnout Engelen \n> ---\n> Documentation/Makefile | 2 +-\n> 1 file changed, 1 insertion(+), 1 deletion(-)\n> \n> diff --git a/Documentation/Makefile b/Documentation/Makefile\n> index 80d1908a44..4d1fd5e31f 100644\n> --- a/Documentation/Makefile\n> +++ b/Documentation/Makefile\n> @@ -380,7 +380,7 @@ SubmittingPatches.txt: SubmittingPatches\n> \t$(QUIET_GEN) cp $< $@\n> \n> XSLT = docbook.xsl\n> -XSLTOPTS = --xinclude --stringparam html.stylesheet docbook-xsl.css\n> +XSLTOPTS = --xinclude --stringparam html.stylesheet docbook-xsl.css --stringparam generate.consistent.ids 1\n> \n> user-manual.html: user-manual.xml $(XSLT)\n> \t$(QUIET_XSLTPROC)$(RM) $@+ $@ && \\\n\nI think this would raise the minimum supported version of\ndocbook-xsl to 1.77.1. That might be fine, but we'd\nprobably want to make sure it doesn't negatively impact\nOS/distributions which build the docs as a likely group who\ncare about reproducible builds. And we'd want to update the\nrequirement in INSTALL, of course.\n\nThe minimum docbook-xsl version was raised from 1.73 to\n1.74, in 5a80d85bbe (INSTALL: drop support for docbook-xsl\nbefore 1.74, 2020-03-29). That change was discussed in\n¹.\n\nAFAICT, the generate.consistent.ids param was added in\ndocbook-xsl-1.77.1 which was released in June 2012. The\ncommit which added it is 74735098e (New param to support\nreplacing generate-id() with xsl:number for more consistent\nid values., 2011-10-24).\n\nIn any case, a minimum of 1.77.1 is present in the supported\nreleases of CentOS/RHEL and Debian/Ubuntu, at least (most\nhave 1.79.x). Those are certainly not the only systems Git\ncares about; they're simply the systems with which I am at\nleast mildly familiar.\n\n¹ https://lore.kernel.org/git/cover.1585486103.git.martin.agren@gmail.com/\n\n-- \nTodd\n"},{"id":"411085","messageId":"CAN0heSpzA2ecKkjz0kMD8k66x8tDipKs93OHQ0+2efQyrS9_=A@mail.gmail.com","threadId":"54739","inReplyTo":"20201201154115.GP748@pobox.com","subject":"Re: [PATCH] doc: make HTML manual reproducible","fromName":"Martin Ågren","fromEmail":"martin.agren@gmail.com","sentAt":"2020-12-01T19:18:45Z","receivedAt":"2020-12-01T19:19:56Z","isPatch":true,"sender":{"key":"martin.agren@gmail.com","avatar":null},"body":"On Tue, 1 Dec 2020 at 16:41, Todd Zullinger wrote:\n\n> Arnout Engelen wrote:\n> > This makes sure the generated id's inside the html version of the\n> > documentation use the same id's when the same version of the\n> > manual is generated twice.\n\nThanks for this. Your mail still hasn't reached me through the list, so\nI'm replying to Todd's reply here.\n\nLooking through the word-diff of the resulting user-manual.html, I see\nbasically three changes. I've applied some light copy-editing to try to\nmake them more readable (the lack of spaces means the notion of \"word\"\ndiff is a bit off). Do you also have these three changes?\n\n 1. Git User Manual\n\n 2. \n\n 3. \n\nThese names and links don't strike me as particularly useful. But even\nso, reproducibility makes sense. I guess you're not really after linking\nto these, but want to have binary-identical user-manual.html when\nbuilding from the same commit?\n\n> > @@ -380,7 +380,7 @@ SubmittingPatches.txt: SubmittingPatches\n> > $(QUIET_GEN) cp $< $@\n> >\n> > XSLT = docbook.xsl\n> > -XSLTOPTS = --xinclude --stringparam html.stylesheet docbook-xsl.css\n> > +XSLTOPTS = --xinclude --stringparam html.stylesheet docbook-xsl.css --stringparam generate.consistent.ids 1\n\nNit: Maybe add a new line\n\n XSLTOPTS += --stringparam generate.consistent.ids 1\n\ninstead to keep within 80 characters.\n\n> I think this would raise the minimum supported version of\n> docbook-xsl to 1.77.1. That might be fine, but we'd\n> probably want to make sure it doesn't negatively impact\n> OS/distributions which build the docs as a likely group who\n> care about reproducible builds. And we'd want to update the\n> requirement in INSTALL, of course.\n\nThanks for digging out the version number. Agreed that this change\nshould be reflected in INSTALL.\n\n> The minimum docbook-xsl version was raised from 1.73 to\n> 1.74, in 5a80d85bbe (INSTALL: drop support for docbook-xsl\n> before 1.74, 2020-03-29). That change was discussed in\n> ¹.\n\nAs mentioned there, it's not like I went out and tested with 1.74. So\nwhether we *actually* support 1.74 right now is anyone's guess.\n\n> AFAICT, the generate.consistent.ids param was added in\n> docbook-xsl-1.77.1 which was released in June 2012. The\n> commit which added it is 74735098e (New param to support\n> replacing generate-id() with xsl:number for more consistent\n> id values., 2011-10-24).\n>\n> In any case, a minimum of 1.77.1 is present in the supported\n> releases of CentOS/RHEL and Debian/Ubuntu, at least (most\n> have 1.79.x). Those are certainly not the only systems Git\n> cares about; they're simply the systems with which I am at\n> least mildly familiar.\n\nSeems to me like we can go with a change like this. If you're on a\npre-1.77.1 system and want user-manual.html, but don't want to update\nyour tool chain, you should still be able to clone the \"htmldocs\" repo.\nI'm not sure exactly where the cut-off point is, but I think moving up\nto mid-2012 should be ok.\n\nMartin\n"},{"id":"411087","messageId":"xmqqpn3tpbsl.fsf@gitster.c.googlers.com","threadId":"54739","inReplyTo":"20201201154115.GP748@pobox.com","subject":"Re: [PATCH] doc: make HTML manual reproducible","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2020-12-01T19:27:06Z","receivedAt":"2020-12-01T19:28:10Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Todd Zullinger writes:\n\n> Hi Arnout,\n>\n> [cc: brian, Martin, and peff, for their collective wisdom in\n> the area of docs and involvement in the last discussion of\n> docbook-xsl requirements.]\n>\n> Arnout Engelen wrote:\n>> This makes sure the generated id's inside the html version of the\n>> documentation use the same id's when the same version of the\n>> manual is generated twice.\n>> \n>> Signed-off-by: Arnout Engelen \n>> ---\n>> Documentation/Makefile | 2 +-\n>> 1 file changed, 1 insertion(+), 1 deletion(-)\n>> \n>> diff --git a/Documentation/Makefile b/Documentation/Makefile\n>> index 80d1908a44..4d1fd5e31f 100644\n>> --- a/Documentation/Makefile\n>> +++ b/Documentation/Makefile\n>> @@ -380,7 +380,7 @@ SubmittingPatches.txt: SubmittingPatches\n>> \t$(QUIET_GEN) cp $< $@\n>> \n>> XSLT = docbook.xsl\n>> -XSLTOPTS = --xinclude --stringparam html.stylesheet docbook-xsl.css\n>> +XSLTOPTS = --xinclude --stringparam html.stylesheet docbook-xsl.css --stringparam generate.consistent.ids 1\n>> \n>> user-manual.html: user-manual.xml $(XSLT)\n>> \t$(QUIET_XSLTPROC)$(RM) $@+ $@ && \\\n>\n> I think this would raise the minimum supported version of\n> docbook-xsl to 1.77.1. That might be fine, but we'd\n> probably want to make sure it doesn't negatively impact\n> OS/distributions which build the docs as a likely group who\n> care about reproducible builds. And we'd want to update the\n> requirement in INSTALL, of course.\n>\n> The minimum docbook-xsl version was raised from 1.73 to\n> 1.74, in 5a80d85bbe (INSTALL: drop support for docbook-xsl\n> before 1.74, 2020-03-29). That change was discussed in\n> ¹.\n>\n> AFAICT, the generate.consistent.ids param was added in\n> docbook-xsl-1.77.1 which was released in June 2012. The\n> commit which added it is 74735098e (New param to support\n> replacing generate-id() with xsl:number for more consistent\n> id values., 2011-10-24).\n>\n> In any case, a minimum of 1.77.1 is present in the supported\n> releases of CentOS/RHEL and Debian/Ubuntu, at least (most\n> have 1.79.x). Those are certainly not the only systems Git\n> cares about; they're simply the systems with which I am at\n> least mildly familiar.\n>\n> ¹ https://lore.kernel.org/git/cover.1585486103.git.martin.agren@gmail.com/\n\nI think it is in general a good thing to do (can we lose some lines\nfrom doc-diff, I wonder?) and many of the result of your study shown\nabove should be in the log message in a summarised form. Here is a\nstarter.\n\n Generated ID's in the HTML version of the documentation does not\n stay the same even when they are generated from the identical\n source. Pass generate.consistent.ids=1 to the xsltproc tool to\n make them stable, which would help reproducible build product.\n\n We currently only support docbook-xsl version 1.74 or newer, but\n this option requires version at least 1.77.1 (released in June\n 2012), which would be OK for supported releases of CentOS/RHEL\n and Debian/Ubuntu (most have 1.79.x).\n\nWe may probably want to talk about versions commonly distributed for\nmacOS and BSDs as well (I do not know if we want to list minor Linux\ndistros). And we definitely need to update INSTALL as you pointed\nout.\n\nThanks and thanks for CC'ing those who may know the area well.\n\n"},{"id":"411090","messageId":"CAN0heSo6Cd3cd6iBHbSU7ESKF79Kwk24KEcioiEdQ_=iBZRQ-g@mail.gmail.com","threadId":"54739","inReplyTo":"xmqqpn3tpbsl.fsf@gitster.c.googlers.com","subject":"Re: [PATCH] doc: make HTML manual reproducible","fromName":"Martin Ågren","fromEmail":"martin.agren@gmail.com","sentAt":"2020-12-01T19:57:40Z","receivedAt":"2020-12-01T19:58:56Z","isPatch":true,"sender":{"key":"martin.agren@gmail.com","avatar":null},"body":"On Tue, 1 Dec 2020 at 20:27, Junio C Hamano wrote:\n>\n> Todd Zullinger writes:\n>\n> > Arnout Engelen wrote:\n> >> This makes sure the generated id's inside the html version of the\n> >> documentation use the same id's when the same version of the\n> >> manual is generated twice.\n\n> >> XSLT = docbook.xsl\n> >> -XSLTOPTS = --xinclude --stringparam html.stylesheet docbook-xsl.css\n> >> +XSLTOPTS = --xinclude --stringparam html.stylesheet docbook-xsl.css --stringparam generate.consistent.ids 1\n> >>\n> >> user-manual.html: user-manual.xml $(XSLT)\n> >> $(QUIET_XSLTPROC)$(RM) $@+ $@ && \\\n> >\n\n> I think it is in general a good thing to do (can we lose some lines\n> from doc-diff, I wonder?) and many of the result of your study shown\n\nThis is only about user-manual.html, which is outside the scope of our\ndoc-diff tool, both by being html not man, and by being user-manual. So\nno, no reduction in any doc-diff, unfortunately.\n\nMartin\n"},{"id":"411126","messageId":"X8bhdyu/OlscI1ME@camp.crustytoothpaste.net","threadId":"54739","inReplyTo":"20201201154115.GP748@pobox.com","subject":"Re: [PATCH] doc: make HTML manual reproducible","fromName":"brian m. carlson","fromEmail":"sandals@crustytoothpaste.net","sentAt":"2020-12-02T00:36:07Z","receivedAt":"2020-12-02T00:37:27Z","isPatch":true,"sender":{"key":"sandals@crustytoothpaste.net","avatar":"https://avatars.githubusercontent.com/u/497054?v=4"},"body":"On 2020-12-01 at 15:41:15, Todd Zullinger wrote:\n> I think this would raise the minimum supported version of\n> docbook-xsl to 1.77.1. That might be fine, but we'd\n> probably want to make sure it doesn't negatively impact\n> OS/distributions which build the docs as a likely group who\n> care about reproducible builds. And we'd want to update the\n> requirement in INSTALL, of course.\n\nI don't think that's necessarily the case. I just tested using a random\nname with another DocBook project I have and it seems to work fine, so\nthere shouldn't be a problem with specifying a name undefined in the\nstylesheet using xsltproc.\n\nIf we want this to be effective, then yes, people will need to upgrade.\nBut if they're happy with the old behavior on ancient systems, that\nshouldn't be a problem.\n\nRegardless, I think this is a valuable change, since there's no good\nreason not to use consistent IDs and at least Debian is switching to all\nreproducible builds so vendors will appreciate this change.\n\n> AFAICT, the generate.consistent.ids param was added in\n> docbook-xsl-1.77.1 which was released in June 2012. The\n> commit which added it is 74735098e (New param to support\n> replacing generate-id() with xsl:number for more consistent\n> id values., 2011-10-24).\n\nIf this was released in 2012, we should be fine.\n\n> In any case, a minimum of 1.77.1 is present in the supported\n> releases of CentOS/RHEL and Debian/Ubuntu, at least (most\n> have 1.79.x). Those are certainly not the only systems Git\n> cares about; they're simply the systems with which I am at\n> least mildly familiar.\n\nYeah, CentOS 6 went EOL on November 30, which is very convenient. I'm\npretty sure nobody else is using such an old version, and even so, I\ndon't see a backwards compatibility problem with this change.\n-- \nbrian m. carlson (he/him or they/them)\nHouston, Texas, US\n"},{"id":"411127","messageId":"X8bis7ZnU8FViHjk@camp.crustytoothpaste.net","threadId":"54739","inReplyTo":"20201201095037.20715-1-arnout@bzzt.net","subject":"Re: [PATCH] doc: make HTML manual reproducible","fromName":"brian m. carlson","fromEmail":"sandals@crustytoothpaste.net","sentAt":"2020-12-02T00:41:23Z","receivedAt":"2020-12-02T00:42:10Z","isPatch":true,"sender":{"key":"sandals@crustytoothpaste.net","avatar":"https://avatars.githubusercontent.com/u/497054?v=4"},"body":"On 2020-12-01 at 09:50:37, Arnout Engelen wrote:\n> This makes sure the generated id's inside the html version of the\n> documentation use the same id's when the same version of the\n> manual is generated twice.\n> \n> Signed-off-by: Arnout Engelen \n> ---\n> Documentation/Makefile | 2 +-\n> 1 file changed, 1 insertion(+), 1 deletion(-)\n> \n> diff --git a/Documentation/Makefile b/Documentation/Makefile\n> index 80d1908a44..4d1fd5e31f 100644\n> --- a/Documentation/Makefile\n> +++ b/Documentation/Makefile\n> @@ -380,7 +380,7 @@ SubmittingPatches.txt: SubmittingPatches\n> \t$(QUIET_GEN) cp $< $@\n> \n> XSLT = docbook.xsl\n> -XSLTOPTS = --xinclude --stringparam html.stylesheet docbook-xsl.css\n> +XSLTOPTS = --xinclude --stringparam html.stylesheet docbook-xsl.css --stringparam generate.consistent.ids 1\n\nI think we'll want --param here, not --stringparam. This is documented\nto be an integer, not a string. The difference is that --stringparam\nsets the value to \"1\" (that is, a string with a single character)\ninstead of the integer 1.\n\nWe may also want to wrap this to the next line like so:\n\n XSLTOPTS = --xinclude --stringparam html.stylesheet docbook-xsl.css\n XSLTOPTS += --param generate.consistent.ids 1\n\nOtherwise, I think this is a valuable change, as I've mentioned\ndownthread. I already use this option on my own projects for the same\nreason.\n-- \nbrian m. carlson (he/him or they/them)\nHouston, Texas, US\n"},{"id":"411131","messageId":"X8bz8c9enMl8Wqbe@coredump.intra.peff.net","threadId":"54739","inReplyTo":"CAN0heSpzA2ecKkjz0kMD8k66x8tDipKs93OHQ0+2efQyrS9_=A@mail.gmail.com","subject":"Re: [PATCH] doc: make HTML manual reproducible","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2020-12-02T01:54:57Z","receivedAt":"2020-12-02T01:55:40Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Tue, Dec 01, 2020 at 08:18:45PM +0100, Martin Ågren wrote:\n\n> Seems to me like we can go with a change like this. If you're on a\n> pre-1.77.1 system and want user-manual.html, but don't want to update\n> your tool chain, you should still be able to clone the \"htmldocs\" repo.\n> I'm not sure exactly where the cut-off point is, but I think moving up\n> to mid-2012 should be ok.\n\nYeah, I think this is the key thing. We can afford to be a bit more\naggressive with the doc toolchain requirements in general because\nthere's an easy fallback.\n\n(Though I think even without that, it sounds like this version is pretty\nsafe, and the proposed change would not even break the old versions, but\nkeep them with the same behavior).\n\nThe overall proposal sounds like a good idea to me, as long as the\nreview comments I saw elsewhere.\n\n-Peff\n"},{"id":"411167","messageId":"20201202160755.GX748@pobox.com","threadId":"54739","inReplyTo":"X8bhdyu/OlscI1ME@camp.crustytoothpaste.net","subject":"Re: [PATCH] doc: make HTML manual reproducible","fromName":"Todd Zullinger","fromEmail":"tmz@pobox.com","sentAt":"2020-12-02T16:07:55Z","receivedAt":"2020-12-02T16:09:00Z","isPatch":true,"sender":{"key":"tmz@pobox.com","avatar":"https://avatars.githubusercontent.com/u/806319?v=4"},"body":"brian m. carlson wrote:\n> On 2020-12-01 at 15:41:15, Todd Zullinger wrote:\n>> I think this would raise the minimum supported version of\n>> docbook-xsl to 1.77.1. That might be fine, but we'd\n>> probably want to make sure it doesn't negatively impact\n>> OS/distributions which build the docs as a likely group who\n>> care about reproducible builds. And we'd want to update the\n>> requirement in INSTALL, of course.\n> \n> I don't think that's necessarily the case. I just tested using a random\n> name with another DocBook project I have and it seems to work fine, so\n> there shouldn't be a problem with specifying a name undefined in the\n> stylesheet using xsltproc.\n\nOh, that's very good to know. Thanks for testing the fine\ndetails. I checked that works on a CentOS 6 system where\nthe docbook-xsl version is 1.75.2, to test whether an older\ndocbook-xsl is similarly forgiving of unknown --param's.\n\n> If we want this to be effective, then yes, people will need to upgrade.\n> But if they're happy with the old behavior on ancient systems, that\n> shouldn't be a problem.\n\nIndeed. Is it worth mentioning this at all in INSTALL?\nSomething like:\n\n - The minimum supported version of docbook-xsl is 1.74.\n + The minimum supported version of docbook-xsl is 1.74. For consistent\n + IDs in the HTML version of the user-manual, 1.79.1 or newer is\n + necessary.\n\nperhaps?\n\nThe explicit mention of the user-manual may be overkill,\nparticularly if we later apply a similar change to other\nHTML docs (if any other HTML docs even need it)?\n\n-- \nTodd\n"},{"id":"411182","messageId":"xmqqim9jltum.fsf@gitster.c.googlers.com","threadId":"54739","inReplyTo":"20201202160755.GX748@pobox.com","subject":"Re: [PATCH] doc: make HTML manual reproducible","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2020-12-02T22:35:13Z","receivedAt":"2020-12-02T22:36:27Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Todd Zullinger writes:\n\n> brian m. carlson wrote:\n> ...\n>> I don't think that's necessarily the case. I just tested using a random\n>> name with another DocBook project I have and it seems to work fine, so\n>> there shouldn't be a problem with specifying a name undefined in the\n>> stylesheet using xsltproc.\n>\n> Oh, that's very good to know. Thanks for testing the fine\n> details. I checked that works on a CentOS 6 system where\n> the docbook-xsl version is 1.75.2, to test whether an older\n> docbook-xsl is similarly forgiving of unknown --param's.\n\nThat is very good, indeed.\n"},{"id":"411186","messageId":"X8gnItjchqX4wwmt@camp.crustytoothpaste.net","threadId":"54739","inReplyTo":"20201202160755.GX748@pobox.com","subject":"Re: [PATCH] doc: make HTML manual reproducible","fromName":"brian m. carlson","fromEmail":"sandals@crustytoothpaste.net","sentAt":"2020-12-02T23:45:38Z","receivedAt":"2020-12-02T23:46:56Z","isPatch":true,"sender":{"key":"sandals@crustytoothpaste.net","avatar":"https://avatars.githubusercontent.com/u/497054?v=4"},"body":"On 2020-12-02 at 16:07:55, Todd Zullinger wrote:\n> brian m. carlson wrote:\n> > If we want this to be effective, then yes, people will need to upgrade.\n> > But if they're happy with the old behavior on ancient systems, that\n> > shouldn't be a problem.\n> \n> Indeed. Is it worth mentioning this at all in INSTALL?\n> Something like:\n> \n> - The minimum supported version of docbook-xsl is 1.74.\n> + The minimum supported version of docbook-xsl is 1.74. For consistent\n> + IDs in the HTML version of the user-manual, 1.79.1 or newer is\n> + necessary.\n> \n> perhaps?\n\nI don't know that that's even necessary. Anyone doing reproducible\nbuilds is already aware of the required versions in order to do a\nreproducible build, and I don't think the average user is going to be\nsuper interested.\n\nWe can if you feel strongly about it, but I don't personally see it as a\nbig deal.\n-- \nbrian m. carlson (he/him or they/them)\nHouston, Texas, US\n"},{"id":"411195","messageId":"xmqqy2ifisg5.fsf@gitster.c.googlers.com","threadId":"54739","inReplyTo":"X8gnItjchqX4wwmt@camp.crustytoothpaste.net","subject":"Re: [PATCH] doc: make HTML manual reproducible","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2020-12-03T01:33:46Z","receivedAt":"2020-12-03T01:34:35Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"brian m. carlson\" writes:\n\n> On 2020-12-02 at 16:07:55, Todd Zullinger wrote:\n>> brian m. carlson wrote:\n>> > If we want this to be effective, then yes, people will need to upgrade.\n>> > But if they're happy with the old behavior on ancient systems, that\n>> > shouldn't be a problem.\n>> \n>> Indeed. Is it worth mentioning this at all in INSTALL?\n>> Something like:\n>> \n>> - The minimum supported version of docbook-xsl is 1.74.\n>> + The minimum supported version of docbook-xsl is 1.74. For consistent\n>> + IDs in the HTML version of the user-manual, 1.79.1 or newer is\n>> + necessary.\n>> \n>> perhaps?\n>\n> I don't know that that's even necessary. Anyone doing reproducible\n> builds is already aware of the required versions in order to do a\n> reproducible build, and I don't think the average user is going to be\n> super interested.\n>\n> We can if you feel strongly about it, but I don't personally see it as a\n> big deal.\n\nI tend to agree.\n\nThe tool being lenient and ignoring a parameter from the future\nmakes things very simple, and the way the patch is structured,\n\"stable ID\" is not even a build option the builder can enable.\nFor some version of the toolchain, the option means stable ID and\nsome older version, it does not mean anything, and that is fine.\n\nWe ship our Makefile with \"CFLAGS = -g -O2 -Wall\" and we do not say\nthings like \"Such and such optimizations are only available if you\nuse GCC newer than version X.Y\"; it is fine to treat the \"--param\"\nthe same way here.\n\n"},{"id":"411197","messageId":"20201203020059.GY748@pobox.com","threadId":"54739","inReplyTo":"X8gnItjchqX4wwmt@camp.crustytoothpaste.net","subject":"Re: [PATCH] doc: make HTML manual reproducible","fromName":"Todd Zullinger","fromEmail":"tmz@pobox.com","sentAt":"2020-12-03T02:00:59Z","receivedAt":"2020-12-03T02:02:06Z","isPatch":true,"sender":{"key":"tmz@pobox.com","avatar":"https://avatars.githubusercontent.com/u/806319?v=4"},"body":"brian m. carlson wrote:\n> On 2020-12-02 at 16:07:55, Todd Zullinger wrote:\n>> Indeed. Is it worth mentioning this at all in INSTALL?\n>> Something like:\n>> \n>> - The minimum supported version of docbook-xsl is 1.74.\n>> + The minimum supported version of docbook-xsl is 1.74. For consistent\n>> + IDs in the HTML version of the user-manual, 1.79.1 or newer is\n>> + necessary.\n>> \n>> perhaps?\n> \n> I don't know that that's even necessary. Anyone doing reproducible\n> builds is already aware of the required versions in order to do a\n> reproducible build, and I don't think the average user is going to be\n> super interested.\n> \n> We can if you feel strongly about it, but I don't personally see it as a\n> big deal.\n\nNah, I definitely don't feel strongly about it. I debated\nthe same point you made -- that those most likely to care\nabout the feature would likely know the versions (perhaps\npainfully) well.\n\nThis is a nice change that, conveniently, has all pros and\nno cons, it seems.\n\nI suppose we'd ideally look for a v2 with --stringparam\nreplaced with --param as you noted upthread?\n\nAnd maybe an updated commit message to note that it requires\ndocbook-xsl 1.79.1 to be effective, but older versions\ngracefully ignore the option? That may be helpful to a\nfuture reader who wonders why the requirement wasn't raised.\n\n-- \nTodd\n"},{"id":"411199","messageId":"xmqqim9jipre.fsf_-_@gitster.c.googlers.com","threadId":"54739","inReplyTo":"20201203020059.GY748@pobox.com","subject":"Re* [PATCH] doc: make HTML manual reproducible","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2020-12-03T02:31:49Z","receivedAt":"2020-12-03T02:32:50Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Todd Zullinger writes:\n\n> I suppose we'd ideally look for a v2 with --stringparam\n> replaced with --param as you noted upthread?\n\nYes.\n\n> And maybe an updated commit message to note that it requires\n> docbook-xsl 1.79.1 to be effective, but older versions\n> gracefully ignore the option?\n\nYes, definitely.\n\nHere is what I'd queue tentatively to potentially reduce one\nround-trip (if Arnout is happy with this version, we can just hear\n\"yes, that's good\" without a formal v2).\n\nThanks.\n\n--- >8 ------ >8 ------ >8 ------ >8 ------ >8 ------ >8 ---\nFrom: Arnout Engelen \nDate: Tue, 1 Dec 2020 09:50:37 +0000\nSubject: [PATCH v2] doc: make HTML manual reproducible\n\nVersions of docbook-xsl newer than 1.79.1 allows xsltproc to assign\nIDs to nodes in the generated HTML consistently, to make the output\nresulting from the same source stable and reproducible.\n\nPass the generate.consistent.ids parameter from the command line to\nask for this feature. Older versions of the tool simply ignores the\nparameter and produces their output the same way as before this\nchange, so there is no need to check for toolchain version.\n\nSigned-off-by: Arnout Engelen \nHelped-by: brian m. carlson \nHelped-by: Todd Zullinger \nSigned-off-by: Junio C Hamano \n---\n\nNotes (amlog):\n Message-Id: <20201201095037.20715-1-arnout@bzzt.net>\n\n Documentation/Makefile | 5 ++++-\n 1 file changed, 4 insertions(+), 1 deletion(-)\n\ndiff --git a/Documentation/Makefile b/Documentation/Makefile\nindex 80d1908a44..69dbe4bb0b 100644\n--- a/Documentation/Makefile\n+++ b/Documentation/Makefile\n@@ -380,7 +380,10 @@ SubmittingPatches.txt: SubmittingPatches\n \t$(QUIET_GEN) cp $< $@\n \n XSLT = docbook.xsl\n-XSLTOPTS = --xinclude --stringparam html.stylesheet docbook-xsl.css\n+XSLTOPTS =\n+XSLTOPTS += --xinclude\n+XSLTOPTS += --stringparam html.stylesheet docbook-xsl.css\n+XSLTOPTS += --param generate.consistent.ids 1\n \n user-manual.html: user-manual.xml $(XSLT)\n \t$(QUIET_XSLTPROC)$(RM) $@+ $@ && \\\n-- \n2.29.2-589-gfe47622759\n\n\n"},{"id":"411210","messageId":"CACDuYhu83q8L6DfDVJJgn9sOfrpnDtXT4JPQ5ea-BEKBhDaPiQ@mail.gmail.com","threadId":"54739","inReplyTo":"xmqqim9jipre.fsf_-_@gitster.c.googlers.com","subject":"Re: Re* [PATCH] doc: make HTML manual reproducible","fromName":"Arnout Engelen","fromEmail":"arnout@bzzt.net","sentAt":"2020-12-03T08:07:43Z","receivedAt":"2020-12-03T08:08:49Z","isPatch":true,"sender":{"key":"arnout@bzzt.net","avatar":null},"body":"Hi,\n\nFirst of all, I'm super impressed by the quality of the review here,\nthanks for that everyone!\n\nOn Thu, Dec 3, 2020 at 3:31 AM Junio C Hamano wrote:\n> Here is what I'd queue tentatively to potentially reduce one\n> round-trip (if Arnout is happy with this version, we can just hear\n> \"yes, that's good\" without a formal v2).\n\nThis looks good to me, thank you!\n\n\nKind regards,\n\nArnout\n\n> --- >8 ------ >8 ------ >8 ------ >8 ------ >8 ------ >8 ---\n> From: Arnout Engelen \n> Date: Tue, 1 Dec 2020 09:50:37 +0000\n> Subject: [PATCH v2] doc: make HTML manual reproducible\n>\n> Versions of docbook-xsl newer than 1.79.1 allows xsltproc to assign\n> IDs to nodes in the generated HTML consistently, to make the output\n> resulting from the same source stable and reproducible.\n>\n> Pass the generate.consistent.ids parameter from the command line to\n> ask for this feature. Older versions of the tool simply ignores the\n> parameter and produces their output the same way as before this\n> change, so there is no need to check for toolchain version.\n>\n> Signed-off-by: Arnout Engelen \n> Helped-by: brian m. carlson \n> Helped-by: Todd Zullinger \n> Signed-off-by: Junio C Hamano \n> ---\n>\n> Notes (amlog):\n> Message-Id: <20201201095037.20715-1-arnout@bzzt.net>\n>\n> Documentation/Makefile | 5 ++++-\n> 1 file changed, 4 insertions(+), 1 deletion(-)\n>\n> diff --git a/Documentation/Makefile b/Documentation/Makefile\n> index 80d1908a44..69dbe4bb0b 100644\n> --- a/Documentation/Makefile\n> +++ b/Documentation/Makefile\n> @@ -380,7 +380,10 @@ SubmittingPatches.txt: SubmittingPatches\n> $(QUIET_GEN) cp $< $@\n>\n> XSLT = docbook.xsl\n> -XSLTOPTS = --xinclude --stringparam html.stylesheet docbook-xsl.css\n> +XSLTOPTS =\n> +XSLTOPTS += --xinclude\n> +XSLTOPTS += --stringparam html.stylesheet docbook-xsl.css\n> +XSLTOPTS += --param generate.consistent.ids 1\n>\n> user-manual.html: user-manual.xml $(XSLT)\n> $(QUIET_XSLTPROC)$(RM) $@+ $@ && \\\n> --\n> 2.29.2-589-gfe47622759\n>\n>\n"}]}