On Thursday, 25 July 2024 01:15:48 CEST Junio C Hamano wrote:
> "Jean-Noël Avila via GitGitGadget" <gitgitgadget@xxxxxxxxx> 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
