Re: [PATCH resend] doc: format-rev: use [synopsis] on code block

On Tue, Aug 11, 2026 at 06:23:18PM +0200, Kristoffer Haugsbakk wrote:

On Tue, Aug 11, 2026, at 14:32, Patrick Steinhardt wrote:

quoted

On Mon, Aug 10, 2026 at 06:58:05PM +0200,
kristofferhaugsbakk@fastmail.com wrote:

quoted

diff --git a/Documentation/git-format-rev.adoc b/Documentation/git-format-rev.adoc
index 505a52feccd..836ba4b0c24 100644
--- a/Documentation/git-format-rev.adoc
+++ b/Documentation/git-format-rev.adoc

@@ -96,6 +96,7 @@ The mode `--stdin-mode=text` replaces each object name with the
 formatted commit, i.e. the format `%s` would transform some commit
 object name to `<subject>` without any termination. Like this:

+[synopsis]
 ----
 Did we not fix this in "<subject>"?
 ----

Hm. I was always under the impression that `[synopsis]` is used as
exactly that, so it surprises me a bit that you want to use it for a
random block that doesn't look like one at all. But going through our
docs (like for example git-blame(1)) I see that we also do this for
other non-synopsis-like blocks, so maybe this is fine?

To be clear, it’s not this kind of [synopsis]:

    [synopsis]
    git blame [-c] [-b] [-l] [--root] [-t] [-f] [-n] [-s] [-e] [-p] [-w] [--incremental]

This [synopsis] is for a code block to highlight <subject> just like how
<subject> is highlighted in running text when using (_) or (`).

Ah, so we have different kinds of synopsis depending on what it applies
to?

quoted

There's probably a good reason for this, but can't we instead just use
backticks to make `<subject>` render the exact same as four lines above?

It’s a code block and the literal text is supposed to use quotation
marks.

Well. I wrote the text to mean that subject is supposed to be quoted. So
perhaps I should have written `"%s"` instead of `"%s"`:

     i.e. the format `"%s"` would transform some commit object name to
     `"<subject>"` without any termination. Like this: ...

Makes sense, thanks!

Patrick