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:
> > On Mon, Aug 10, 2026 at 06:58:05PM +0200,
> > [email protected] wrote:
> >> 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?

> > 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