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

From: Jean-Noël AVILA <avila.jn@gmail.com>
Date: Mar 24, 2024, 15:41 UTC
Message-ID: <1812061.VLH7GnMWUR@cayenne>
In-Reply-To: <xmqqmsqov0at.fsf@gitster.g>

Le dimanche 24 mars 2024, 03:19:38 CET Junio C Hamano a écrit :

Show 16 quoted lines

> 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

Show 6 quoted lines

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

Show 8 quoted lines

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

Show 12 quoted lines

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