doc: remove extra quotes in generated docs

From: Kyle Lippincott <[email protected]>

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:

```

```

---
doc: remove extra quotes in generated docs

Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-git-1847%2Fspectral54%2Fdoc-remove-extra-quotes-v1
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-1847/spectral54/doc-remove-extra-quotes-v1
Pull-Request: https://github.com/git/git/pull/1847

 Documentation/asciidoc.conf.in | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

index dbe36a52eab..b89bccf2309 100644
@@ -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]

base-commit: 0fc57dec578fcc8dcda5cc3de6b81fa1f6719770

gitgitgadget

a38edab7 (Makefile: generate doc versions via GIT-VERSION-GEN, 2024-12-06)

This is another <FILL THIS IN> that was missed? Can you fill it in?

From: Kyle Lippincott <[email protected]>

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

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

 Documentation/asciidoc.conf.in | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

index dbe36a52eab..b89bccf2309 100644
@@ -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]

base-commit: 0fc57dec578fcc8dcda5cc3de6b81fa1f6719770

gitgitgadget

Thanks.

Will apply and mark it for 'next' and then 'master'.

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.

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

I won't be able to have a look today or tomorrow, but will have a look on Friday and send a patch, unless somebody else beats me to it.

Thanks for the report!

Patrick

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