* Documentation options: Code or not?
@ 2026-01-04 18:04 Michael Lyons
2026-01-05 1:54 ` Junio C Hamano
2026-01-05 10:01 ` Jean-Noël Avila
0 siblings, 2 replies; 3+ messages in thread
From: Michael Lyons @ 2026-01-04 18:04 UTC (permalink / raw)
To: git
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
^ permalink raw reply [flat|nested] 3+ messages in thread
* Re: Documentation options: Code or not?
2026-01-04 18:04 Documentation options: Code or not? Michael Lyons
@ 2026-01-05 1:54 ` Junio C Hamano
2026-01-05 10:01 ` Jean-Noël Avila
1 sibling, 0 replies; 3+ messages in thread
From: Junio C Hamano @ 2026-01-05 1:54 UTC (permalink / raw)
To: Michael Lyons; +Cc: git
Michael Lyons <git@michael•lyo.nz> writes:
> I started a quick commit to drop the backticks from rerere-options, but then
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).
^ permalink raw reply [flat|nested] 3+ messages in thread
* Re: Documentation options: Code or not?
2026-01-04 18:04 Documentation options: Code or not? Michael Lyons
2026-01-05 1:54 ` Junio C Hamano
@ 2026-01-05 10:01 ` Jean-Noël Avila
1 sibling, 0 replies; 3+ messages in thread
From: Jean-Noël Avila @ 2026-01-05 10:01 UTC (permalink / raw)
To: git; +Cc: git
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
^ permalink raw reply [flat|nested] 3+ messages in thread
end of thread, other threads:[~2026-01-05 10:10 UTC | newest]
Thread overview: 3+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2026-01-04 18:04 Documentation options: Code or not? Michael Lyons
2026-01-05 1:54 ` Junio C Hamano
2026-01-05 10:01 ` Jean-Noël Avila
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox