Subject: Re: [PATCH] doc/gitremote-helpers: fix more missing single-quotes

From: Junio C Hamano <[email-masked]>
Date: Sat, 23 Mar 2024 19:19:38 -0700

Jean-Noël AVILA <[email-masked]> 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.