{"thread":{"id":"64721","subject":"Documentation options: Code or not?","startedAt":"2026-01-04T18:04:21Z","lastAt":"2026-01-05T10:10:35Z","messageCount":3,"participants":["Michael Lyons","Junio C Hamano","Jean-Noël Avila"],"isPatch":false,"patchVersion":null,"patchTotal":null},"messages":[{"id":"532996","messageId":"2076768.usQuhbGJ8B@debian-mbp","threadId":"64721","inReplyTo":null,"subject":"Documentation options: Code or not?","fromName":"Michael Lyons","fromEmail":"git@michael.lyo.nz","sentAt":"2026-01-04T18:04:09Z","receivedAt":"2026-01-04T18:04:21Z","isPatch":false,"sender":{"key":"git@michael.lyo.nz","avatar":null},"body":"I noticed that git-scm.com's documentation for `git-am` has a different color \nfor the rerere options than it does for the other ones. Those options are \nimported from rerere-options.adoc, which adds code backticks to the keys:\n\n`--rerere-autoupdate`::\n`--no-rerere-autoupdate`::\n\tAfter the rerere mechanism reuses a recorded resolution...\n\nI started a quick commit to drop the backticks from rerere-options, but then \nsampled a few other doc pages. Some use backticks (git-merge, git-repo), and \nsome don't (git-prune, git-name-rev). Is there a preferred style? Would an \nupdate to make them consistent be useful or just annoying?\n\nThank you,\nMichael\n\n\n"},{"id":"533006","messageId":"xmqqikdgn7ry.fsf@gitster.g","threadId":"64721","inReplyTo":"2076768.usQuhbGJ8B@debian-mbp","subject":"Re: Documentation options: Code or not?","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-01-05T01:54:41Z","receivedAt":"2026-01-05T01:54:44Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Michael Lyons <git@michael.lyo.nz> writes:\n\n> I started a quick commit to drop the backticks from rerere-options, but then \n\nThe current trend is to mark-up even the individual items in the\ndescription list correctly, so if you were to help improve\nconsistency, you need to go the other direction.  Look for messages\nin the list archive by Jean-Noël Avila, who is the primary person\ndriving this effort, for examples.  Or picking one of the resulting\ncommits randomly, see f7316a66 (doc: convert git push to synopsis\nstyle, 2025-11-19).\n"},{"id":"533015","messageId":"eaf31f3d-83ab-4afc-8b78-0d017de6b580@free.fr","threadId":"64721","inReplyTo":"2076768.usQuhbGJ8B@debian-mbp","subject":"Re: Documentation options: Code or not?","fromName":"Jean-Noël Avila","fromEmail":"jn.avila@free.fr","sentAt":"2026-01-05T10:01:07Z","receivedAt":"2026-01-05T10:10:35Z","isPatch":false,"sender":{"key":"jn.avila@free.fr","avatar":"https://avatars.githubusercontent.com/u/156172?v=4"},"body":"Hi,\n\nThe process of converting all the manpages to the `synopsis` style\n\nis ongoing.\n\nThe aim is to use the \"smart\" synopsis format (using backticks for\n\n inline code), for which a parser makes the special formatting for\n\n keywords, placeholders and grammatical marks.\n\n\nI took the path of converting the pages in the order of appearance\n\non git-scm.com.\n\nFor a good idea of the final rendering, you can check git-commit or\n\ngit-add. I'm always open to a helping hand in this task, with enough\n\ncommunication to not duplicate work. To be honest, the conversion process\n\nis far from being completely formalized, so you may need a couple\n\niterations before the rules are completely clear.\n\n\nLet me know if you are interested.\n\n\nJN\n\n\n"}]}