On Fri, 14 May 2021 at 00:00, Junio C Hamano <gitster@xxxxxxxxx> wrote: > > Martin Ågren <martin.agren@xxxxxxxxx> 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
