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

From: Jean-Noël AVILA <avila.jn@gmail.com>
Date: Mar 23, 2024, 19:58 UTC
Message-ID: <22254967.EfDdHjke4D@cayenne>
In-Reply-To: <xmqq7chvblgr.fsf@gitster.g>

Le jeudi 21 mars 2024, 17:25:56 CET Junio C Hamano a écrit :

Show 10 quoted lines

> Jean-Noël Avila <avila.jn@gmail.com> writes:
> 
> >> -'option deepen-relative {'true'|'false'}::
> >> +'option deepen-relative' {'true'|'false'}::
> >>  	Deepens the history of a shallow repository relative to
> >>  	current boundary. Only valid when used with "option depth".
> >
> > The syntax for describing alternatives is specified as (true|false).
> 
> Hmmmm, here, true and false are to be given verbatim.

In such case, it's (`true`|`false`) . As well as the command before.

Show 10 quoted lines

> 
> > Also, in my reworks of syntax, I chose to remove all formatting from the
> > term parts of the description lists.
> 
> 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,

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.