# Documentation options: Code or not? 3 messages from 2026-01-04 to 2026-01-05. Participants: Michael Lyons, Junio C Hamano, Jean-Noël Avila. Thread: https://gitlist.dev/t/64721 ## Michael Lyons, 2026-01-04 18:04 Subject: Documentation options: Code or not? Message-ID: <2076768.usQuhbGJ8B@debian-mbp> URL: https://gitlist.dev/e/2076768.usQuhbGJ8B%40debian-mbp ``` 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 ``` ## Junio C Hamano, 2026-01-05 01:54 Subject: Re: Documentation options: Code or not? Message-ID: URL: https://gitlist.dev/e/xmqqikdgn7ry.fsf%40gitster.g In-Reply-To: <2076768.usQuhbGJ8B@debian-mbp> ``` Michael Lyons 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). ``` ## Jean-Noël Avila, 2026-01-05 10:01 Subject: Re: Documentation options: Code or not? Message-ID: URL: https://gitlist.dev/e/eaf31f3d-83ab-4afc-8b78-0d017de6b580%40free.fr In-Reply-To: <2076768.usQuhbGJ8B@debian-mbp> ``` 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 ```