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

From: Junio C Hamano <gitster@pobox.com>
Date: Mar 24, 2024, 02:19 UTC
Message-ID: <xmqqmsqov0at.fsf@gitster.g>
In-Reply-To: <22254967.EfDdHjke4D@cayenne>

Jean-Noël AVILA <avila.jn@gmail.com> 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.

Show 17 quoted lines

>> 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.