Documentation options: Code or not?

I noticed that git-scm.com's documentation for `git-am` has a different color for the rerere options than it does for the other ones. Those options are imported from rerere-options.adoc, which adds code backticks to the keys:

`--rerere-autoupdate`::
`--no-rerere-autoupdate`::
	After the rerere mechanism reuses a recorded resolution...

I started a quick commit to drop the backticks from rerere-options, but then sampled a few other doc pages. Some use backticks (git-merge, git-repo), and some don't (git-prune, git-name-rev). Is there a preferred style? Would an update to make them consistent be useful or just annoying?

Thank you, Michael

Michael Lyons <git@michael.lyo.nz> writes:

The current trend is to mark-up even the individual items in the description list correctly, so if you were to help improve consistency, you need to go the other direction. Look for messages in the list archive by Jean-Noël Avila, who is the primary person driving this effort, for examples. Or picking one of the resulting commits randomly, see f7316a66 (doc: convert git push to synopsis style, 2025-11-19).

Hi,

The process of converting all the manpages to the `synopsis` style

is ongoing.

The aim is to use the "smart" synopsis format (using backticks for

 inline code), for which a parser makes the special formatting for

 keywords, placeholders and grammatical marks.

I took the path of converting the pages in the order of appearance

on git-scm.com.

For a good idea of the final rendering, you can check git-commit or

git-add. I'm always open to a helping hand in this task, with enough

communication to not duplicate work. To be honest, the conversion process

is far from being completely formalized, so you may need a couple

iterations before the rules are completely clear.

Let me know if you are interested.

JN