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

["Jean-Noël AVILA" <avila.jn@gmail.com>]

Le dimanche 24 mars 2024, 03:19:38 CET Junio C Hamano a écrit :
> 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.
> 
> >> 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.
> 

In asciidoc legacy mode, the "verbatim" is two-sided : tell asciidoc to not 
interpret the content (in modern mode, this is no longer true) but also format 
the snippet in a way to indicate to the reader that this is a constant part of 
the syntax.

On this formatting surprise, the current behavior, verbatim as bold, is 
inherited from xmlto's special option manpage-bolt-literal.xsl of processing 
docbook and differs from asciidoctor's direct conversion which formats the 
verbatim as monospace in the roff output.
When converting the roff file to ps or pdf, the format difference stands out and 
some form of markup is preserved, but in the console, monospace is lost. 

So, with our current setup, if we shift to pure asciidoctor for compiling the 
docs, without further postprocessing, we may end up loosing in part this 
useful formatting for console manpages, something I had overlooked. If we keep 
using the docbook format as a pivot format, then we're safe.

Side Note : for man pages that are translated, pure asciidoctor is currently 
used and this special conversion is not applied.

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

With our currrent guidelines, this latest markup is the right one.

I will change the CodingGuidelines in another patch series to add more 
litteral formats in the synopsis and in the terms of description lists, so as 
to converge toward the generally accepted format of manpages.