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

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

[Jeff King]

There are a few cases left in gitremote-helpers.txt that are missing a
closing quote, so you end up with:

  'option deepen-since <timestamp>

with a stray opening quote instead of rendering correctly in italics.
These should have been part of 51d41dc243 (doc/gitremote-helpers: fix
missing single-quote, 2024-03-07), but apparently my eyesight is not
what it once was. Hopefully this is now all of them.

Signed-off-by: Jeff King <peff@peff.net>
---
This should go on top of jk/doc-remote-helpers-markup-fix.

 Documentation/gitremote-helpers.txt | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/Documentation/gitremote-helpers.txt b/Documentation/gitremote-helpers.txt
index 83e99192e1..cd4e16abad 100644
--- a/Documentation/gitremote-helpers.txt
+++ b/Documentation/gitremote-helpers.txt
@@ -470,14 +470,14 @@ set by Git if the remote helper has the 'option' capability.
 'option depth' <depth>::
 	Deepens the history of a shallow repository.
 
-'option deepen-since <timestamp>::
+'option deepen-since' <timestamp>::
 	Deepens the history of a shallow repository based on time.
 
-'option deepen-not <ref>::
+'option deepen-not' <ref>::
 	Deepens the history of a shallow repository excluding ref.
 	Multiple options add up.
 
-'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".
 
-- 
2.44.0.650.g4615f65fe0

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

[Junio C Hamano]

Jeff King <peff@peff.net> writes:

> There are a few cases left in gitremote-helpers.txt that are missing a
> closing quote, so you end up with:
>
>   'option deepen-since <timestamp>
>
> with a stray opening quote instead of rendering correctly in italics.
> These should have been part of 51d41dc243 (doc/gitremote-helpers: fix
> missing single-quote, 2024-03-07), but apparently my eyesight is not
> what it once was. Hopefully this is now all of them.

Thanks.

  $ git grep -e "^\(['][^']*['][^']*\)*['][^']*::" Documentation

does not have any more hits after this patch.

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

[Jean-Noël Avila]

Le 20/03/2024 à 10:17, Jeff King a écrit :
> There are a few cases left in gitremote-helpers.txt that are missing a
> closing quote, so you end up with:
> 
>   'option deepen-since <timestamp>
> 
> with a stray opening quote instead of rendering correctly in italics.
> These should have been part of 51d41dc243 (doc/gitremote-helpers: fix
> missing single-quote, 2024-03-07), but apparently my eyesight is not
> what it once was. Hopefully this is now all of them.
> 
> Signed-off-by: Jeff King <peff@peff.net>
> ---
> This should go on top of jk/doc-remote-helpers-markup-fix.
> 
>  Documentation/gitremote-helpers.txt | 6 +++---
>  1 file changed, 3 insertions(+), 3 deletions(-)
> 
> diff --git a/Documentation/gitremote-helpers.txt b/Documentation/gitremote-helpers.txt
> index 83e99192e1..cd4e16abad 100644
> --- a/Documentation/gitremote-helpers.txt
> +++ b/Documentation/gitremote-helpers.txt
> @@ -470,14 +470,14 @@ set by Git if the remote helper has the 'option' capability.
>  'option depth' <depth>::
>  	Deepens the history of a shallow repository.
>  
> -'option deepen-since <timestamp>::
> +'option deepen-since' <timestamp>::
>  	Deepens the history of a shallow repository based on time.
>  
> -'option deepen-not <ref>::
> +'option deepen-not' <ref>::
>  	Deepens the history of a shallow repository excluding ref.
>  	Multiple options add up.
>  
> -'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).

Also, in my reworks of syntax, I chose to remove all formatting from the
term parts of the description lists.

Thanks

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

[Junio C Hamano]

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.

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

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

[Jean-Noël AVILA]

Le jeudi 21 mars 2024, 17:25:56 CET Junio C Hamano a écrit :
> 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.

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

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

[Junio C Hamano]

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.

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

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

[Jean-Noël AVILA]

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.

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

[Junio C Hamano]

Jean-Noël AVILA <avila.jn@gmail.com> writes:

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

OK.  Thanks.

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

[Jeff King]

On Thu, Mar 21, 2024 at 11:28:01AM +0100, Jean-Noël Avila wrote:

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

I don't have an opinion on the typesetting of true/false here, but this
does match the rest of the document. If you have another series fixing
them all up, I'm happy if it overrides this patch (as long as the
rendering error is fixed one way or the other).

-Peff