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

[Patrick Steinhardt <ps@pks.im>]

On Mon, Aug 10, 2026 at 06:58:05PM +0200, kristofferhaugsbakk@fastmail.com wrote:
> From: Kristoffer Haugsbakk <code@khaugsbakk.name>
> 
> This code block uses the placeholder `<subject>`. Let’s highlight this
> placeholder properly by using the `synopsis` block definition which was
> introduced in a34d1d53 (doc: convert git-show to synopsis style,
> 2026-02-06).

I'm not particularly knowledgeable in AsciiDoc, I only picked it up
because nobody else did. So please consider me even more clueless than I
typically am :)

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

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?

Thanks!

Patrick