Re: [PATCH v2 0/3] doc: introducing synopsis para

["Jean-Noël AVILA" <jn.avila@free.fr>]

On Thursday, 25 July 2024 01:15:48 CEST Junio C Hamano wrote:
> "Jean-Noël Avila via GitGitGadget" <gitgitgadget@gmail.com> writes:
> 
> > Following several issues with the way the formatting of synopsis is done 
in
> > the manpages that were recently reworked, this patch series introduces the
> > processing of a new custom paragraph attribute 'synopsis'.
> 
> The rendered result looks OK but the source being just like what we
> would write in plain text files without any extra mark-up makes it
> look quite nice.
> 
> I wonder what we want to do with some oddballs, like git-shortlog
> that uses "|" not as an alternative but literally a pipe (i.e. "feed
> the output of this other command via a pipe to this command"),
> though.
> 
>     git log --pretty=short | git shortlog [<options>]

I must confess that while reviewing my patch, by switching all [verse] to 
[synopsis] , I looked at this line and understood the pipe as an alternative 
from the grammar, not as a shell pipe. I also noted a few spots where the 
grammar may be misinterpreted e.g. parenthesis in git-grep.

In theory the typesetting should tell the keyword apart from the grammar, but 
for signs such as pipes and parenthesis  the rendering does not change enough.

> 
> There may be also some page that indicates "this command takes its
> input from its standard input" by using something like
> 
>     git cmd [--foo] [--bar] <input-file
> 
> which we may need to think how to handle.  The easiest way out may
> be to say "don't do these to indicate/force where the input comes
> from".  I dunno.
> 

The form 

    git cmd  [--foo] [--bar] < <input-file>

is completely acceptable , would render correctly and would remove the use of 
the pipe. The thing is that this pipe isn't even part of the command. It is 
just an example. Maybe it should not appear in the synopsis at all.

For keyword signs that are already used in expressing the grammar, we could 
quote the sign to indicate that it is a keyword : "(" .

Thanks