diff mbox series

[3/6] git-check-ref-format.txt: avoid single quote

Message ID f2a78267fd0f424c5cfa6969c891597af4d5171f.1620928059.git.martin.agren@gmail.com (mailing list archive)
State New
Headers show
Series AsciiDoc vs Asciidoctor, once again | expand

Commit Message

Martin Ågren May 13, 2021, 6:17 p.m. UTC
Asciidoctor renders 'git cat-file' with the single quotes. It's somehow
tricked by the single quote in "srcref\'s" earler in the paragraph. If
we drop the backslash, we'll regress with AsciiDoc. Let's just rewrite
things a bit to avoid "srcref's" entirely.

Add backticks for monospacing around these refs and command invocations
while at it.

Signed-off-by: Martin Ågren <martin.agren@gmail.com>
---
 Documentation/git-check-ref-format.txt | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

Comments

Eric Sunshine May 13, 2021, 7:16 p.m. UTC | #1
On Thu, May 13, 2021 at 2:18 PM Martin Ågren <martin.agren@gmail.com> wrote:
> Asciidoctor renders 'git cat-file' with the single quotes. It's somehow
> tricked by the single quote in "srcref\'s" earler in the paragraph. If

s/earler/earlier/

> we drop the backslash, we'll regress with AsciiDoc. Let's just rewrite
> things a bit to avoid "srcref's" entirely.
>
> Add backticks for monospacing around these refs and command invocations
> while at it.
>
> Signed-off-by: Martin Ågren <martin.agren@gmail.com>
Martin Ågren May 13, 2021, 7:35 p.m. UTC | #2
On Thu, 13 May 2021 at 21:16, Eric Sunshine <sunshine@sunshineco.com> wrote:
>
> On Thu, May 13, 2021 at 2:18 PM Martin Ågren <martin.agren@gmail.com> wrote:
> > Asciidoctor renders 'git cat-file' with the single quotes. It's somehow
> > tricked by the single quote in "srcref\'s" earler in the paragraph. If
>
> s/earler/earlier/

Oops. Thanks!
Junio C Hamano May 13, 2021, 10 p.m. UTC | #3
Martin Ågren <martin.agren@gmail.com> writes:

> Asciidoctor renders 'git cat-file' with the single quotes.

I somehow find this sentence a bit hard to grok.  Do you mean
"instead of typesetting them emphasized, the two-word phrase is
enclosed in a pair of literal single quotes"?

> It's somehow
> tricked by the single quote in "srcref\'s" earler in the paragraph. If
> we drop the backslash, we'll regress with AsciiDoc. Let's just rewrite
> things a bit to avoid "srcref's" entirely.

I also was puzzled by this one and the previous "cat-file" thing,
mostly because I couldn't tell if this is an unrelated problem that
happens to be around the same single-quote letter, or somehow
happens only because the single-quoted 'cat-file' was nearby, until
I checked the patch text (and it seems that this is "here is another
problem around apostrophe").

> Add backticks for monospacing around these refs and command invocations
> while at it.

I have no problem with this particular rephrasing from "srcref's
value" to "value of srcref", but forbidding possessive "'s" from any
future documentation is troubling.

> -. A colon `:` is used as in `srcref:dstref` to mean "use srcref\'s
> -  value and store it in dstref" in fetch and push operations.
> +. A colon `:` is used as in `srcref:dstref` to mean "use the value
> +  of `srcref` and store it in `dstref`" in fetch and push operations.
>    It may also be used to select a specific object such as with
> -  'git cat-file': "git cat-file blob v1.3.3:refs.c".
> +  'git cat-file': `git cat-file blob v1.3.3:refs.c`.

The proposed log message did not explain why you wanted to avoid
double-quote pair on the "cat-file" line.  Is this meant as a
workaround for the "single quotes are shown around git cat-file"
issue?

Thanks.
Jeff King May 14, 2021, 5:30 a.m. UTC | #4
On Thu, May 13, 2021 at 08:17:42PM +0200, Martin Ågren wrote:

> -. A colon `:` is used as in `srcref:dstref` to mean "use srcref\'s
> -  value and store it in dstref" in fetch and push operations.
> +. A colon `:` is used as in `srcref:dstref` to mean "use the value
> +  of `srcref` and store it in `dstref`" in fetch and push operations.
>    It may also be used to select a specific object such as with
> -  'git cat-file': "git cat-file blob v1.3.3:refs.c".
> +  'git cat-file': `git cat-file blob v1.3.3:refs.c`.

I'd perhaps write:

  `srcref`'s value...

but I'm a little afraid to see how it is handled by the various parsers
(I'd write it because it does look OK in most markdown parsers I've
used).

That said, I think in this case "value of `srcref`" is actually an
improvement to the text (but I wouldn't say the same of the earlier
patches, which feel like they are making things clunkier).

-Peff
Martin Ågren May 14, 2021, 9:07 a.m. UTC | #5
On Fri, 14 May 2021 at 00:00, Junio C Hamano <gitster@pobox.com> wrote:
>
> Martin Ågren <martin.agren@gmail.com> writes:
>
> > Asciidoctor renders 'git cat-file' with the single quotes.
>
> I somehow find this sentence a bit hard to grok.  Do you mean
> "instead of typesetting them emphasized, the two-word phrase is
> enclosed in a pair of literal single quotes"?

Yes. I will improve the description.

> I have no problem with this particular rephrasing from "srcref's
> value" to "value of srcref", but forbidding possessive "'s" from any
> future documentation is troubling.

I think this is a case of several things going on in one paragraph in a
way that confuses the tool. As Felipe commented, it's probably correct
to call it out as an Asciidoctor bug. If we hit is *once* across all our
documentation, I think it's correct to work around it [and report the
bug, if we can], but not let the experience impose a blanket rule on
ourselves that we mustn't do anything that even resembles this
paragraph.

> > -. A colon `:` is used as in `srcref:dstref` to mean "use srcref\'s
> > -  value and store it in dstref" in fetch and push operations.
> > +. A colon `:` is used as in `srcref:dstref` to mean "use the value
> > +  of `srcref` and store it in `dstref`" in fetch and push operations.
> >    It may also be used to select a specific object such as with
> > -  'git cat-file': "git cat-file blob v1.3.3:refs.c".
> > +  'git cat-file': `git cat-file blob v1.3.3:refs.c`.
>
> The proposed log message did not explain why you wanted to avoid
> double-quote pair on the "cat-file" line.  Is this meant as a
> workaround for the "single quotes are shown around git cat-file"
> issue?

Hmm, I've somehow tended to think that it's 'git foo' the tool and `git
foo --bar baz` the actual invocation. SQs for the former, backticks for
the latter. Like, `git cat-file` is not a correct invocation of 'git
cat-file'. But I think I'm starting to see the error in my ways --
CodingGuidelines says to use backticks around command names, so it
really should be `git cat-file`. And changing that might just happen to
avoid the issue that triggered this patch.

Thanks for your comments.

Martin
Martin Ågren May 14, 2021, 9:08 a.m. UTC | #6
On Fri, 14 May 2021 at 07:30, Jeff King <peff@peff.net> wrote:
>
> That said, I think in this case "value of `srcref`" is actually an
> improvement to the text (but I wouldn't say the same of the earlier
> patches, which feel like they are making things clunkier).

Ok, if it's an improvement on its own, that's good. Thanks for calling
out that the others are not.

Martin
Felipe Contreras May 14, 2021, 12:30 p.m. UTC | #7
Martin Ågren wrote:
> On Fri, 14 May 2021 at 00:00, Junio C Hamano <gitster@pobox.com> wrote:

> > The proposed log message did not explain why you wanted to avoid
> > double-quote pair on the "cat-file" line.  Is this meant as a
> > workaround for the "single quotes are shown around git cat-file"
> > issue?
> 
> Hmm, I've somehow tended to think that it's 'git foo' the tool and `git
> foo --bar baz` the actual invocation. SQs for the former, backticks for
> the latter. Like, `git cat-file` is not a correct invocation of 'git
> cat-file'. But I think I'm starting to see the error in my ways --
> CodingGuidelines says to use backticks around command names, so it
> really should be `git cat-file`. And changing that might just happen to
> avoid the issue that triggered this patch.

Hmmm. `git status`, `git branch`, `git diff`, `git log`.

All these are both "tools" **and** invocations. In fact, you an pretty
much "invoke" any thing: `git checkout` might not do anything... But it
runs.
diff mbox series

Patch

diff --git a/Documentation/git-check-ref-format.txt b/Documentation/git-check-ref-format.txt
index ee6a4144fb..71d53ffb60 100644
--- a/Documentation/git-check-ref-format.txt
+++ b/Documentation/git-check-ref-format.txt
@@ -70,10 +70,10 @@  reference name expressions (see linkgit:gitrevisions[7]):
 . A tilde `~` and caret `^` are used to introduce the postfix
   'nth parent' and 'peel onion' operation.
 
-. A colon `:` is used as in `srcref:dstref` to mean "use srcref\'s
-  value and store it in dstref" in fetch and push operations.
+. A colon `:` is used as in `srcref:dstref` to mean "use the value
+  of `srcref` and store it in `dstref`" in fetch and push operations.
   It may also be used to select a specific object such as with
-  'git cat-file': "git cat-file blob v1.3.3:refs.c".
+  'git cat-file': `git cat-file blob v1.3.3:refs.c`.
 
 . at-open-brace `@{` is used as a notation to access a reflog entry.