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

From: Jeff King <peff@peff.net>
Date: Dec 18, 2024, 12:13 UTC
Message-ID: <20241218121317.GA696975@coredump.intra.peff.net>
In-Reply-To: <pull.1847.v2.git.git.1734483422181.gitgitgadget@gmail.com>

On Wed, Dec 18, 2024 at 12:57:02AM +0000, Kyle Lippincott via GitGitGadget wrote:

Show 28 quoted lines

> 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