Le jeudi 21 mars 2024, 17:25:56 CET Junio C Hamano a écrit :
> Jean-Noël Avila <avila.jn@xxxxxxxxx> 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.
>
> > 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.
