git/list[1] front-page[2] threads[3] people[4] search[5] about
 

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

From
KHKristoffer Haugsbakk <kristofferhaugsbakk@fastmail.com>
Date
Aug 11, 2026, 16:23 UTC
Message-ID
<a495b0d8-b735-4ae4-8cbe-56fd42bbbd3f@app.fastmail.com>
In-Reply-To
<ansWZxZ6lB0tYIJD@pks.im>
On Tue, Aug 11, 2026, at 14:32, Patrick Steinhardt wrote:
Show 12 quoted lines
> 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 :)
Thanks for taking a look.
Show 19 quoted lines
>
>> 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 (`).

> 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: ...
;-)
Previous: Patrick SteinhardtNext: Patrick Steinhardt
Message 4 of 21 in “doc: format-rev: use [synopsis] on code block”
  1. doc: format-rev: use [synopsis] on code blockkristofferhaugsbakk@fastmail.com, Jul 30, 2026
  2. doc: format-rev: use [synopsis] on code blockkristofferhaugsbakk@fastmail.com, Aug 10, 2026
  3. Patrick SteinhardtAug 11, 2026
  4. Kristoffer HaugsbakkAug 11, 2026
  5. Patrick SteinhardtAug 11, 2026
  6. Kristoffer HaugsbakkAug 11, 2026
  7. Kristoffer HaugsbakkAug 11, 2026
  8. 0/2 doc: format-rev: use [synopsis] on code blockkristofferhaugsbakk@fastmail.com, Aug 13, 2026
  9. 1/2 doc: format-rev: quote subject placeholder before and afterkristofferhaugsbakk@fastmail.com, Aug 13, 2026
  10. 2/2 doc: format-rev: use [synopsis] on code blockkristofferhaugsbakk@fastmail.com, Aug 13, 2026
  11. Patrick SteinhardtAug 13, 2026
  12. 0/2 doc: format-rev: use [synopsis] on code blockkristofferhaugsbakk@fastmail.com, Aug 13, 2026
  13. 1/2 doc: format-rev: quote subject placeholder before and afterkristofferhaugsbakk@fastmail.com, Aug 13, 2026
  14. 2/2 doc: format-rev: use [synopsis] on code blockkristofferhaugsbakk@fastmail.com, Aug 13, 2026
  15. Junio C HamanoAug 14, 2026
  16. Kristoffer HaugsbakkAug 14, 2026
  17. Junio C HamanoAug 14, 2026
  18. 0/2 doc: format-rev: use [synopsis] on code blockkristofferhaugsbakk@fastmail.com, Aug 17, 2026
  19. 1/2 doc: format-rev: quote subject placeholder before and afterkristofferhaugsbakk@fastmail.com, Aug 17, 2026
  20. 2/2 doc: format-rev: use [synopsis] on code blockkristofferhaugsbakk@fastmail.com, Aug 17, 2026
  21. Junio C HamanoAug 17, 2026

Read the whole thread, see it on lore, or plain text.

$ cat FOOTERMessages come from the public archive at lore.kernel.org/git, fetched every hour. The front page is chosen and written each morning by an AI editor and can be wrong; the threads themselves are the record. About and API. For agents: an MCP server at https://gitlist.dev/mcp, and any thread, story or person page as Markdown by adding .md to its URL (or sending Accept: text/markdown). Details in /llms.txt.