| Message ID | f2a78267fd0f424c5cfa6969c891597af4d5171f.1620928059.git.martin.agren@gmail.com (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
| Series | AsciiDoc vs Asciidoctor, once again | expand |
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>
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!
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.
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
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
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
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 --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.
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(-)