[PATCH] doc: remove extra quotes in generated docs

[PATCH] doc: remove extra quotes in generated docs

[Kyle Lippincott via GitGitGadget]

From: Kyle Lippincott <spectral@google.com>

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:

```

```

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-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(-)

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=&#126;
 apostrophe=&#39;
 backtick=&#96;
 litdd=&#45;&#45;
-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

Re: [PATCH] doc: remove extra quotes in generated docs

[Junio C Hamano]

"Kyle Lippincott via GitGitGadget" <gitgitgadget@gmail.com> writes:

> From: Kyle Lippincott <spectral@google.com>
>
> Commit <FILL THIS IN> moved these variables from the Makefile to

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

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

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

> 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-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(-)
>
> 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=&#126;
>  apostrophe=&#39;
>  backtick=&#96;
>  litdd=&#45;&#45;
> -manmanual='Git Manual'
> -mansource='Git @GIT_VERSION@'
> -revdate='@GIT_DATE@'
> +manmanual=Git Manual
> +mansource=Git @GIT_VERSION@
> +revdate=@GIT_DATE@

Since 226daba2 (Doc/Makefile: give mansource/-version/-manual
attributes, 2019-09-16), We used to pass

	-amanmanual='Git Manual'

as part of the command line to invoke asciidoc, but the commit in
question forgot that the single quotes are for the shell to strip
and we now have them around the value of the asciidoc attribute.

Well spotted.

Thanks.

[PATCH v2] doc: remove extra quotes in generated docs

[Kyle Lippincott via GitGitGadget]

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

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=&#126;
 apostrophe=&#39;
 backtick=&#96;
 litdd=&#45;&#45;
-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

Re: [PATCH v2] doc: remove extra quotes in generated docs

[Junio C Hamano]

"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'.

Re: [PATCH v2] doc: remove extra quotes in generated docs

[Junio C Hamano]

"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.

make GIT_VERSION=foo broken, was Re: [PATCH v2] doc: remove extra quotes in generated docs

[Jeff King]

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

Re: make GIT_VERSION=foo broken, was Re: [PATCH v2] doc: remove extra quotes in generated docs

[Patrick Steinhardt]

On Wed, Dec 18, 2024 at 06:33:24AM -0500, Jeff King wrote:
> Perhaps the script should be doing the same for GIT_VERSION itself,
> along with GIT_DATE?

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

Re: [PATCH v2] doc: remove extra quotes in generated docs

[Jeff King]

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