| Message ID | pull.1847.v2.git.git.1734483422181.gitgitgadget@gmail.com (mailing list archive) |
|---|---|
| State | New |
| Headers | show |
| Series | [v2] doc: remove extra quotes in generated docs | expand |
"Kyle Lippincott via GitGitGadget" <gitgitgadget@gmail.com> writes: > From: Kyle Lippincott <spectral@google.com> > > Commit a38edab7c8 (Makefile: generate doc versions via GIT-VERSION-GEN, > 2024-12-06) moved these variables from the Makefile to asciidoc.conf.in. > When doing so, some extraneous quotes were added; these are visible in > the generated .xml files, at least, and possibly in other locations: > > ``` > --- a/tmp/orig-git-bisect.xml > +++ b/Documentation/git-bisect.xml > @@ -5,14 +5,14 @@ > <refentry lang="en"> > <refentryinfo> > <title>git-bisect(1)</title> > - <date>2024-12-06</date> > -<revhistory><revision><date>2024-12-06</date></revision></revhistory> > + <date>'2024-12-06'</date>^M > +<revhistory><revision><date>'2024-12-06'</date></revision></revhistory>^M > </refentryinfo> > <refmeta> > <refentrytitle>git-bisect</refentrytitle> > <manvolnum>1</manvolnum> > -<refmiscinfo class="source">Git 2.47.1.409.g9bb10d27e7</refmiscinfo> > -<refmiscinfo class="manual">Git Manual</refmiscinfo> > +<refmiscinfo class="source">'Git 2.47.1.410.ga38edab7c8'</refmiscinfo>^M > +<refmiscinfo class="manual">'Git Manual'</refmiscinfo>^M > </refmeta> > <refnamediv> > <refname>git-bisect</refname> > ``` Thanks. Will apply and mark it for 'next' and then 'master'.
"Kyle Lippincott via GitGitGadget" <gitgitgadget@gmail.com> writes: > From: Kyle Lippincott <spectral@google.com> > > Commit a38edab7c8 (Makefile: generate doc versions via GIT-VERSION-GEN, > 2024-12-06) moved these variables from the Makefile to asciidoc.conf.in. > When doing so, some extraneous quotes were added; these are visible in > the generated .xml files, at least, and possibly in other locations: > > ``` > --- a/tmp/orig-git-bisect.xml > +++ b/Documentation/git-bisect.xml > @@ -5,14 +5,14 @@ > <refentry lang="en"> > <refentryinfo> > <title>git-bisect(1)</title> > - <date>2024-12-06</date> > -<revhistory><revision><date>2024-12-06</date></revision></revhistory> > + <date>'2024-12-06'</date>^M > +<revhistory><revision><date>'2024-12-06'</date></revision></revhistory>^M > </refentryinfo> > <refmeta> > <refentrytitle>git-bisect</refentrytitle> > <manvolnum>1</manvolnum> > -<refmiscinfo class="source">Git 2.47.1.409.g9bb10d27e7</refmiscinfo> > -<refmiscinfo class="manual">Git Manual</refmiscinfo> > +<refmiscinfo class="source">'Git 2.47.1.410.ga38edab7c8'</refmiscinfo>^M > +<refmiscinfo class="manual">'Git Manual'</refmiscinfo>^M > </refmeta> > <refnamediv> > <refname>git-bisect</refname> > ``` Thanks for filling the blanks in ;-) The above differences however seem to be absorbed before these strings reach git-bisect.1 by the documentation toolchain; Running Documentation/doc-diff with --asciidoc or --asciidoctor options do not show the difference in single quotes. Nevertheless it is a "fix" to make the conversion a38edab7c8 attempted to do a more faithful one to the original, so I'll still take it. Thanks.
On Tue, Dec 17, 2024 at 05:22:08PM -0800, Junio C Hamano wrote: > > -<refmiscinfo class="source">Git 2.47.1.409.g9bb10d27e7</refmiscinfo> > > -<refmiscinfo class="manual">Git Manual</refmiscinfo> > > +<refmiscinfo class="source">'Git 2.47.1.410.ga38edab7c8'</refmiscinfo>^M > > +<refmiscinfo class="manual">'Git Manual'</refmiscinfo>^M > > </refmeta> > > <refnamediv> > > <refname>git-bisect</refname> > > ``` > > Thanks for filling the blanks in ;-) > > The above differences however seem to be absorbed before these > strings reach git-bisect.1 by the documentation toolchain; > Running Documentation/doc-diff with --asciidoc or --asciidoctor > options do not show the difference in single quotes. Hmm. I thought that might be because we override the version and date strings in doc-diff to prevent extra output. But it seems that was broken by the same commit. Try: ./doc-diff a38edab7^ a38edab7 and you'll get a bunch of: -Git omitted 1970-01-01 GIT-ADD(1) +Git 2.47.1.410.ga 2024-12-06 GIT-ADD(1) diffs which show the breakage starting (and after that, you get further changes as each version changes by one commit). The override is done by setting GIT_VERSION on the make command line. And indeed, it seems like: make GIT_VERSION=foobar no longer has any effect. That could be a problem for packagers, as well, if they try to inject a custom version string (e.g., to represent the upstream version plus their patches). I don't know if anybody does that, though. The root of the problem is that we used to generate GIT-VERSION-FILE and source it as a Makefile snippet. That let the usual Makefile precedence rules override what was in the file. But after that commit, we use the script to directly generate the version _and_ replace the contents of asciidoc.conf, etc. I think the workaround here would be to manually override asciidoc's config like this: make ASCIIDOC='asciidoc -amansource="Git omitted" -arevdate=1970-01-01' But besides being horrible, I think that only works because asciidoc gives us a layer of indirection. The same problem exists for the built-in version-def.h. Try this: $ git checkout v2.47.0 $ make GIT_VERSION=super-secret [...] $ bin-wrappers/git version git version super-secret $ git checkout v2.48.0-rc0 $ make GIT_VERSION=super-secret [...] $ bin-wrappers/git version git version 2.48.0.rc0 I wondered if this would also leak out over the network via the agent string, but it doesn't seem to. I think because GIT_USER_AGENT is handled specially in the script; we accept the value from the environment and only default it to git/$GIT_VERSION. Perhaps the script should be doing the same for GIT_VERSION itself, along with GIT_DATE? -Peff
On Wed, Dec 18, 2024 at 12:57:02AM +0000, Kyle Lippincott via GitGitGadget wrote: > Commit a38edab7c8 (Makefile: generate doc versions via GIT-VERSION-GEN, > 2024-12-06) moved these variables from the Makefile to asciidoc.conf.in. > When doing so, some extraneous quotes were added; these are visible in > the generated .xml files, at least, and possibly in other locations: > > ``` > --- a/tmp/orig-git-bisect.xml > +++ b/Documentation/git-bisect.xml > @@ -5,14 +5,14 @@ > <refentry lang="en"> > <refentryinfo> > <title>git-bisect(1)</title> > - <date>2024-12-06</date> > -<revhistory><revision><date>2024-12-06</date></revision></revhistory> > + <date>'2024-12-06'</date>^M > +<revhistory><revision><date>'2024-12-06'</date></revision></revhistory>^M > </refentryinfo> > <refmeta> > <refentrytitle>git-bisect</refentrytitle> > <manvolnum>1</manvolnum> > -<refmiscinfo class="source">Git 2.47.1.409.g9bb10d27e7</refmiscinfo> > -<refmiscinfo class="manual">Git Manual</refmiscinfo> > +<refmiscinfo class="source">'Git 2.47.1.410.ga38edab7c8'</refmiscinfo>^M > +<refmiscinfo class="manual">'Git Manual'</refmiscinfo>^M > </refmeta> > <refnamediv> > <refname>git-bisect</refname> > ``` BTW, for git.git patches you should indent example snippets like this rather than using markdown backticks. Because it's not indented, "git am" thinks that "--- a/tmp/..." is the start of the diff, and the rest of the commit message is lost (and of course the patch does not apply, because we have no such file). Leaving the "```" doesn't hurt anything, but of course it is not rendered by git-log, etc (nor even GitHub's web interface, since they don't assume commit messages themselves are markdown). IMHO it is ugly and not necessary if you've indented. Looks like Junio kindly fixed this up while applying already, so no need to resend. Just thought I'd mention it for the future. -Peff
--- a/tmp/orig-git-bisect.xml +++ b/Documentation/git-bisect.xml @@ -5,14 +5,14 @@ <refentry lang="en"> <refentryinfo> <title>git-bisect(1)</title> - <date>2024-12-06</date> -<revhistory><revision><date>2024-12-06</date></revision></revhistory> + <date>'2024-12-06'</date>^M +<revhistory><revision><date>'2024-12-06'</date></revision></revhistory>^M </refentryinfo> <refmeta> <refentrytitle>git-bisect</refentrytitle> <manvolnum>1</manvolnum> -<refmiscinfo class="source">Git 2.47.1.409.g9bb10d27e7</refmiscinfo> -<refmiscinfo class="manual">Git Manual</refmiscinfo> +<refmiscinfo class="source">'Git 2.47.1.410.ga38edab7c8'</refmiscinfo>^M +<refmiscinfo class="manual">'Git Manual'</refmiscinfo>^M </refmeta> <refnamediv> <refname>git-bisect</refname> ``` Signed-off-by: Kyle Lippincott <spectral@google.com> --- doc: remove extra quotes in generated docs Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-git-1847%2Fspectral54%2Fdoc-remove-extra-quotes-v2 Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-1847/spectral54/doc-remove-extra-quotes-v2 Pull-Request: https://github.com/git/git/pull/1847 Range-diff vs v1: 1: c4f2acc9b07 ! 1: 89ce6212c02 doc: remove extra quotes in generated docs @@ Metadata ## Commit message ## doc: remove extra quotes in generated docs - Commit <FILL THIS IN> moved these variables from the Makefile to - asciidoc.conf.in, and in doing so added some extraneous quotes. These - are visible in the generated .xml files, at least, and possibly in other - locations: + Commit a38edab7c8 (Makefile: generate doc versions via GIT-VERSION-GEN, + 2024-12-06) moved these variables from the Makefile to asciidoc.conf.in. + When doing so, some extraneous quotes were added; these are visible in + the generated .xml files, at least, and possibly in other locations: ``` - + --- a/tmp/orig-git-bisect.xml + +++ b/Documentation/git-bisect.xml + @@ -5,14 +5,14 @@ + <refentry lang="en"> + <refentryinfo> + <title>git-bisect(1)</title> + - <date>2024-12-06</date> + -<revhistory><revision><date>2024-12-06</date></revision></revhistory> + + <date>'2024-12-06'</date>^M + +<revhistory><revision><date>'2024-12-06'</date></revision></revhistory>^M + </refentryinfo> + <refmeta> + <refentrytitle>git-bisect</refentrytitle> + <manvolnum>1</manvolnum> + -<refmiscinfo class="source">Git 2.47.1.409.g9bb10d27e7</refmiscinfo> + -<refmiscinfo class="manual">Git Manual</refmiscinfo> + +<refmiscinfo class="source">'Git 2.47.1.410.ga38edab7c8'</refmiscinfo>^M + +<refmiscinfo class="manual">'Git Manual'</refmiscinfo>^M + </refmeta> + <refnamediv> + <refname>git-bisect</refname> ``` Signed-off-by: Kyle Lippincott <spectral@google.com> Documentation/asciidoc.conf.in | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/Documentation/asciidoc.conf.in b/Documentation/asciidoc.conf.in index dbe36a52eab..b89bccf2309 100644 --- a/Documentation/asciidoc.conf.in +++ b/Documentation/asciidoc.conf.in @@ -21,9 +21,9 @@ tilde=~ apostrophe=' backtick=` litdd=-- -manmanual='Git Manual' -mansource='Git @GIT_VERSION@' -revdate='@GIT_DATE@' +manmanual=Git Manual +mansource=Git @GIT_VERSION@ +revdate=@GIT_DATE@ ifdef::backend-docbook[] [linkgit-inlinemacro]
From: Kyle Lippincott <spectral@google.com> Commit a38edab7c8 (Makefile: generate doc versions via GIT-VERSION-GEN, 2024-12-06) moved these variables from the Makefile to asciidoc.conf.in. When doing so, some extraneous quotes were added; these are visible in the generated .xml files, at least, and possibly in other locations: ``` base-commit: 0fc57dec578fcc8dcda5cc3de6b81fa1f6719770