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

From: Jean-Noël AVILA <jn.avila@free.fr>
Date: Jul 25, 2024, 12:15 UTC
Message-ID: <13562033.uLZWGnKmhe@cayenne>
In-Reply-To: <xmqqcyn2s7ob.fsf@gitster.g>

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

Show 13 quoted lines

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

Show 10 quoted lines

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