{"thread":{"id":"62659","subject":"[PATCH] doc: remove extra quotes in generated docs","startedAt":"2024-12-17T23:47:50Z","lastAt":"2024-12-18T13:21:30Z","messageCount":8,"participants":["Kyle Lippincott via GitGitGadget","Junio C Hamano","Jeff King","Patrick Steinhardt"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"509244","messageId":"pull.1847.git.git.1734479267736.gitgitgadget@gmail.com","threadId":"62659","inReplyTo":null,"subject":"[PATCH] doc: remove extra quotes in generated docs","fromName":"Kyle Lippincott via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2024-12-17T23:47:47Z","receivedAt":"2024-12-17T23:47:50Z","isPatch":true,"sender":{"key":"spectral@google.com","avatar":"https://avatars.githubusercontent.com/u/6371650?v=4"},"body":"From: Kyle Lippincott \n\nCommit moved these variables from the Makefile to\nasciidoc.conf.in, and in doing so added some extraneous quotes. These\nare visible in the generated .xml files, at least, and possibly in other\nlocations:\n\n```\n\n```\n\nSigned-off-by: Kyle Lippincott \n---\n doc: remove extra quotes in generated docs\n\nPublished-As: https://github.com/gitgitgadget/git/releases/tag/pr-git-1847%2Fspectral54%2Fdoc-remove-extra-quotes-v1\nFetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-1847/spectral54/doc-remove-extra-quotes-v1\nPull-Request: https://github.com/git/git/pull/1847\n\n Documentation/asciidoc.conf.in | 6 +++---\n 1 file changed, 3 insertions(+), 3 deletions(-)\n\ndiff --git a/Documentation/asciidoc.conf.in b/Documentation/asciidoc.conf.in\nindex dbe36a52eab..b89bccf2309 100644\n--- a/Documentation/asciidoc.conf.in\n+++ b/Documentation/asciidoc.conf.in\n@@ -21,9 +21,9 @@ tilde=~\n apostrophe='\n backtick=`\n litdd=--\n-manmanual='Git Manual'\n-mansource='Git @GIT_VERSION@'\n-revdate='@GIT_DATE@'\n+manmanual=Git Manual\n+mansource=Git @GIT_VERSION@\n+revdate=@GIT_DATE@\n \n ifdef::backend-docbook[]\n [linkgit-inlinemacro]\n\nbase-commit: 0fc57dec578fcc8dcda5cc3de6b81fa1f6719770\n-- \ngitgitgadget\n"},{"id":"509256","messageId":"xmqqjzbxyfol.fsf@gitster.g","threadId":"62659","inReplyTo":"pull.1847.git.git.1734479267736.gitgitgadget@gmail.com","subject":"Re: [PATCH] doc: remove extra quotes in generated docs","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2024-12-18T00:53:46Z","receivedAt":"2024-12-18T00:53:49Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Kyle Lippincott via GitGitGadget\" writes:\n\n> From: Kyle Lippincott \n>\n> Commit moved these variables from the Makefile to\n\na38edab7 (Makefile: generate doc versions via GIT-VERSION-GEN,\n2024-12-06)\n\n> asciidoc.conf.in, and in doing so added some extraneous quotes. These\n> are visible in the generated .xml files, at least, and possibly in other\n> locations:\n>\n> ```\n>\n> ```\n\nThis is another that was missed? Can you fill it in?\n\n> Signed-off-by: Kyle Lippincott \n> ---\n> doc: remove extra quotes in generated docs\n>\n> Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-git-1847%2Fspectral54%2Fdoc-remove-extra-quotes-v1\n> Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-1847/spectral54/doc-remove-extra-quotes-v1\n> Pull-Request: https://github.com/git/git/pull/1847\n>\n> Documentation/asciidoc.conf.in | 6 +++---\n> 1 file changed, 3 insertions(+), 3 deletions(-)\n>\n> diff --git a/Documentation/asciidoc.conf.in b/Documentation/asciidoc.conf.in\n> index dbe36a52eab..b89bccf2309 100644\n> --- a/Documentation/asciidoc.conf.in\n> +++ b/Documentation/asciidoc.conf.in\n> @@ -21,9 +21,9 @@ tilde=~\n> apostrophe='\n> backtick=`\n> litdd=--\n> -manmanual='Git Manual'\n> -mansource='Git @GIT_VERSION@'\n> -revdate='@GIT_DATE@'\n> +manmanual=Git Manual\n> +mansource=Git @GIT_VERSION@\n> +revdate=@GIT_DATE@\n\nSince 226daba2 (Doc/Makefile: give mansource/-version/-manual\nattributes, 2019-09-16), We used to pass\n\n\t-amanmanual='Git Manual'\n\nas part of the command line to invoke asciidoc, but the commit in\nquestion forgot that the single quotes are for the shell to strip\nand we now have them around the value of the asciidoc attribute.\n\nWell spotted.\n\nThanks.\n"},{"id":"509257","messageId":"pull.1847.v2.git.git.1734483422181.gitgitgadget@gmail.com","threadId":"62659","inReplyTo":"pull.1847.git.git.1734479267736.gitgitgadget@gmail.com","subject":"[PATCH v2] doc: remove extra quotes in generated docs","fromName":"Kyle Lippincott via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2024-12-18T00:57:02Z","receivedAt":"2024-12-18T00:57:05Z","isPatch":true,"sender":{"key":"spectral@google.com","avatar":"https://avatars.githubusercontent.com/u/6371650?v=4"},"body":"From: Kyle Lippincott \n\nCommit a38edab7c8 (Makefile: generate doc versions via GIT-VERSION-GEN,\n2024-12-06) moved these variables from the Makefile to asciidoc.conf.in.\nWhen doing so, some extraneous quotes were added; these are visible in\nthe generated .xml files, at least, and possibly in other locations:\n\n```\n--- a/tmp/orig-git-bisect.xml\n+++ b/Documentation/git-bisect.xml\n@@ -5,14 +5,14 @@\n \n \n git-bisect(1)\n- 2024-12-06\n-2024-12-06\n+ '2024-12-06'^M\n+'2024-12-06'^M\n \n \n git-bisect\n 1\n-Git 2.47.1.409.g9bb10d27e7\n-Git Manual\n+'Git 2.47.1.410.ga38edab7c8'^M\n+'Git Manual'^M\n \n \n git-bisect\n```\n\nSigned-off-by: Kyle Lippincott \n---\n doc: remove extra quotes in generated docs\n\nPublished-As: https://github.com/gitgitgadget/git/releases/tag/pr-git-1847%2Fspectral54%2Fdoc-remove-extra-quotes-v2\nFetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-1847/spectral54/doc-remove-extra-quotes-v2\nPull-Request: https://github.com/git/git/pull/1847\n\nRange-diff vs v1:\n\n 1: c4f2acc9b07 ! 1: 89ce6212c02 doc: remove extra quotes in generated docs\n @@ Metadata\n ## Commit message ##\n doc: remove extra quotes in generated docs\n \n - Commit moved these variables from the Makefile to\n - asciidoc.conf.in, and in doing so added some extraneous quotes. These\n - are visible in the generated .xml files, at least, and possibly in other\n - locations:\n + Commit a38edab7c8 (Makefile: generate doc versions via GIT-VERSION-GEN,\n + 2024-12-06) moved these variables from the Makefile to asciidoc.conf.in.\n + When doing so, some extraneous quotes were added; these are visible in\n + the generated .xml files, at least, and possibly in other locations:\n \n ```\n -\n + --- a/tmp/orig-git-bisect.xml\n + +++ b/Documentation/git-bisect.xml\n + @@ -5,14 +5,14 @@\n + \n + \n + git-bisect(1)\n + - 2024-12-06\n + -2024-12-06\n + + '2024-12-06'^M\n + +'2024-12-06'^M\n + \n + \n + git-bisect\n + 1\n + -Git 2.47.1.409.g9bb10d27e7\n + -Git Manual\n + +'Git 2.47.1.410.ga38edab7c8'^M\n + +'Git Manual'^M\n + \n + \n + git-bisect\n ```\n \n Signed-off-by: Kyle Lippincott \n\n\n Documentation/asciidoc.conf.in | 6 +++---\n 1 file changed, 3 insertions(+), 3 deletions(-)\n\ndiff --git a/Documentation/asciidoc.conf.in b/Documentation/asciidoc.conf.in\nindex dbe36a52eab..b89bccf2309 100644\n--- a/Documentation/asciidoc.conf.in\n+++ b/Documentation/asciidoc.conf.in\n@@ -21,9 +21,9 @@ tilde=~\n apostrophe='\n backtick=`\n litdd=--\n-manmanual='Git Manual'\n-mansource='Git @GIT_VERSION@'\n-revdate='@GIT_DATE@'\n+manmanual=Git Manual\n+mansource=Git @GIT_VERSION@\n+revdate=@GIT_DATE@\n \n ifdef::backend-docbook[]\n [linkgit-inlinemacro]\n\nbase-commit: 0fc57dec578fcc8dcda5cc3de6b81fa1f6719770\n-- \ngitgitgadget\n"},{"id":"509259","messageId":"xmqqfrmlyevk.fsf@gitster.g","threadId":"62659","inReplyTo":"pull.1847.v2.git.git.1734483422181.gitgitgadget@gmail.com","subject":"Re: [PATCH v2] doc: remove extra quotes in generated docs","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2024-12-18T01:11:11Z","receivedAt":"2024-12-18T01:11:14Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Kyle Lippincott via GitGitGadget\" writes:\n\n> From: Kyle Lippincott \n>\n> Commit a38edab7c8 (Makefile: generate doc versions via GIT-VERSION-GEN,\n> 2024-12-06) moved these variables from the Makefile to asciidoc.conf.in.\n> When doing so, some extraneous quotes were added; these are visible in\n> the generated .xml files, at least, and possibly in other locations:\n>\n> ```\n> --- a/tmp/orig-git-bisect.xml\n> +++ b/Documentation/git-bisect.xml\n> @@ -5,14 +5,14 @@\n> \n> \n> git-bisect(1)\n> - 2024-12-06\n> -2024-12-06\n> + '2024-12-06'^M\n> +'2024-12-06'^M\n> \n> \n> git-bisect\n> 1\n> -Git 2.47.1.409.g9bb10d27e7\n> -Git Manual\n> +'Git 2.47.1.410.ga38edab7c8'^M\n> +'Git Manual'^M\n> \n> \n> git-bisect\n> ```\n\nThanks.\n\nWill apply and mark it for 'next' and then 'master'.\n\n"},{"id":"509261","messageId":"xmqqbjx9yedb.fsf@gitster.g","threadId":"62659","inReplyTo":"pull.1847.v2.git.git.1734483422181.gitgitgadget@gmail.com","subject":"Re: [PATCH v2] doc: remove extra quotes in generated docs","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2024-12-18T01:22:08Z","receivedAt":"2024-12-18T01:22:10Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Kyle Lippincott via GitGitGadget\" writes:\n\n> From: Kyle Lippincott \n>\n> Commit a38edab7c8 (Makefile: generate doc versions via GIT-VERSION-GEN,\n> 2024-12-06) moved these variables from the Makefile to asciidoc.conf.in.\n> When doing so, some extraneous quotes were added; these are visible in\n> the generated .xml files, at least, and possibly in other locations:\n>\n> ```\n> --- a/tmp/orig-git-bisect.xml\n> +++ b/Documentation/git-bisect.xml\n> @@ -5,14 +5,14 @@\n> \n> \n> git-bisect(1)\n> - 2024-12-06\n> -2024-12-06\n> + '2024-12-06'^M\n> +'2024-12-06'^M\n> \n> \n> git-bisect\n> 1\n> -Git 2.47.1.409.g9bb10d27e7\n> -Git Manual\n> +'Git 2.47.1.410.ga38edab7c8'^M\n> +'Git Manual'^M\n> \n> \n> git-bisect\n> ```\n\nThanks for filling the blanks in ;-)\n\nThe above differences however seem to be absorbed before these\nstrings reach git-bisect.1 by the documentation toolchain;\nRunning Documentation/doc-diff with --asciidoc or --asciidoctor\noptions do not show the difference in single quotes.\n\nNevertheless it is a \"fix\" to make the conversion a38edab7c8\nattempted to do a more faithful one to the original, so I'll still\ntake it.\n\nThanks.\n"},{"id":"509284","messageId":"20241218113324.GA594795@coredump.intra.peff.net","threadId":"62659","inReplyTo":"xmqqbjx9yedb.fsf@gitster.g","subject":"make GIT_VERSION=foo broken, was Re: [PATCH v2] doc: remove extra quotes in generated docs","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2024-12-18T11:33:24Z","receivedAt":"2024-12-18T11:33:34Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Tue, Dec 17, 2024 at 05:22:08PM -0800, Junio C Hamano wrote:\n\n> > -Git 2.47.1.409.g9bb10d27e7\n> > -Git Manual\n> > +'Git 2.47.1.410.ga38edab7c8'^M\n> > +'Git Manual'^M\n> > \n> > \n> > git-bisect\n> > ```\n> \n> Thanks for filling the blanks in ;-)\n> \n> The above differences however seem to be absorbed before these\n> strings reach git-bisect.1 by the documentation toolchain;\n> Running Documentation/doc-diff with --asciidoc or --asciidoctor\n> options do not show the difference in single quotes.\n\nHmm. I thought that might be because we override the version and date\nstrings in doc-diff to prevent extra output. But it seems that was\nbroken by the same commit. Try:\n\n ./doc-diff a38edab7^ a38edab7\n\nand you'll get a bunch of:\n\n-Git omitted 1970-01-01 GIT-ADD(1)\n+Git 2.47.1.410.ga 2024-12-06 GIT-ADD(1)\n\ndiffs which show the breakage starting (and after that, you get further\nchanges as each version changes by one commit).\n\nThe override is done by setting GIT_VERSION on the make command line.\nAnd indeed, it seems like:\n\n make GIT_VERSION=foobar\n\nno longer has any effect. That could be a problem for packagers, as\nwell, if they try to inject a custom version string (e.g., to represent\nthe upstream version plus their patches). I don't know if anybody does\nthat, though.\n\nThe root of the problem is that we used to generate GIT-VERSION-FILE and\nsource it as a Makefile snippet. That let the usual Makefile precedence\nrules override what was in the file. But after that commit, we use the\nscript to directly generate the version _and_ replace the contents of\nasciidoc.conf, etc.\n\nI think the workaround here would be to manually override asciidoc's\nconfig like this:\n\n make ASCIIDOC='asciidoc -amansource=\"Git omitted\" -arevdate=1970-01-01'\n\nBut besides being horrible, I think that only works because asciidoc\ngives us a layer of indirection. The same problem exists for the\nbuilt-in version-def.h. Try this:\n\n $ git checkout v2.47.0\n $ make GIT_VERSION=super-secret\n [...]\n $ bin-wrappers/git version\n git version super-secret\n\n $ git checkout v2.48.0-rc0\n $ make GIT_VERSION=super-secret\n [...]\n $ bin-wrappers/git version\n git version 2.48.0.rc0\n\nI wondered if this would also leak out over the network via the agent\nstring, but it doesn't seem to. I think because GIT_USER_AGENT is\nhandled specially in the script; we accept the value from the\nenvironment and only default it to git/$GIT_VERSION.\n\nPerhaps the script should be doing the same for GIT_VERSION itself,\nalong with GIT_DATE?\n\n-Peff\n"},{"id":"509287","messageId":"20241218121317.GA696975@coredump.intra.peff.net","threadId":"62659","inReplyTo":"pull.1847.v2.git.git.1734483422181.gitgitgadget@gmail.com","subject":"Re: [PATCH v2] doc: remove extra quotes in generated docs","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2024-12-18T12:13:17Z","receivedAt":"2024-12-18T12:13:19Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Wed, Dec 18, 2024 at 12:57:02AM +0000, Kyle Lippincott via GitGitGadget wrote:\n\n> Commit a38edab7c8 (Makefile: generate doc versions via GIT-VERSION-GEN,\n> 2024-12-06) moved these variables from the Makefile to asciidoc.conf.in.\n> When doing so, some extraneous quotes were added; these are visible in\n> the generated .xml files, at least, and possibly in other locations:\n> \n> ```\n> --- a/tmp/orig-git-bisect.xml\n> +++ b/Documentation/git-bisect.xml\n> @@ -5,14 +5,14 @@\n> \n> \n> git-bisect(1)\n> - 2024-12-06\n> -2024-12-06\n> + '2024-12-06'^M\n> +'2024-12-06'^M\n> \n> \n> git-bisect\n> 1\n> -Git 2.47.1.409.g9bb10d27e7\n> -Git Manual\n> +'Git 2.47.1.410.ga38edab7c8'^M\n> +'Git Manual'^M\n> \n> \n> git-bisect\n> ```\n\nBTW, for git.git patches you should indent example snippets like this\nrather than using markdown backticks.\n\nBecause it's not indented, \"git am\" thinks that \"--- a/tmp/...\" is the\nstart of the diff, and the rest of the commit message is lost (and of\ncourse the patch does not apply, because we have no such file).\n\nLeaving the \"```\" doesn't hurt anything, but of course it is not\nrendered by git-log, etc (nor even GitHub's web interface, since they\ndon't assume commit messages themselves are markdown). IMHO it is ugly\nand not necessary if you've indented.\n\nLooks like Junio kindly fixed this up while applying already, so no need\nto resend. Just thought I'd mention it for the future.\n\n-Peff\n"},{"id":"509290","messageId":"Z2LL9F8WANokZJ7R@pks.im","threadId":"62659","inReplyTo":"20241218113324.GA594795@coredump.intra.peff.net","subject":"Re: make GIT_VERSION=foo broken, was Re: [PATCH v2] doc: remove extra quotes in generated docs","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2024-12-18T13:19:48Z","receivedAt":"2024-12-18T13:21:30Z","isPatch":true,"sender":{"key":"ps@pks.im","avatar":"https://avatars.githubusercontent.com/u/4056630?v=4"},"body":"On Wed, Dec 18, 2024 at 06:33:24AM -0500, Jeff King wrote:\n> Perhaps the script should be doing the same for GIT_VERSION itself,\n> along with GIT_DATE?\n\nI won't be able to have a look today or tomorrow, but will have a look\non Friday and send a patch, unless somebody else beats me to it.\n\nThanks for the report!\n\nPatrick\n"}]}