Jean-Noël AVILA <avila.jn@xxxxxxxxx> writes: >> Hmmmm, here, true and false are to be given verbatim. > > In such case, it's (`true`|`false`) . As well as the command before. Yes, they should be given like so, I think. >> I know we added the _<placeholder>_ thing, but have we added these >> to Documentation/CodingGuidelines yet? >> >> Thanks. > > No, we haven't. > > I skimmed over different documentation projects and there's no real consensus > on what the formatting should be in detail, except for some common rules. > man-pages(7) gives some good hints that we should adhere to, which are echoed > in the guide of asciidoc: https://docs.asciidoctor.org/asciidoctor/latest/ > manpage-backend/ . Basically, verbatim are in bold, and variables are in > italic. > > In our man pages, the asciidoc verbatim are rendered as bold and asciidoc > emphasis are rendered as underlined, just like italics, which adheres to the > principles, What I meant by "verbatim" was "what the user would give Git verbatim", which are marked up as `true` (or `false`), and typically typeset in monospace in HTML. I just checked the prerendered man pages, and indeed \fB...\fR surrounds verbatim phrases, which was a bit surprising to me. > Note that bold/verbatim are usually also used in terms of description lists. > > I'm totally ok to change the CodingGuidelines and reroll git-clone and git- > init with these new rules. So to go back to the original example, what do we want to do instead of ... 'option deepen-relative' {'true'|'false'}:: ... this? Like this ... `option deepen-relative` (`true`|`false`):: ... or something else? Thanks.
