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

[Junio C Hamano <gitster@pobox.com>]

Jean-Noël AVILA <jn.avila@free.fr> writes:

> The form 
>
>     git cmd  [--foo] [--bar] < <input-file>
>
> is completely acceptable , would render correctly and would remove the use of 
> the pipe.

Nice.  I was afraid that it might be interpreted as a placeholder
whose description is "<input-file" ;-)

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

Historically the command was designed to read from "git log" as its
upstream and nothing else, which was where that sample command in
the synopsis originated, but it is unusual to spell out the upstream
(or downstream for that matter) of a pipe even when the command is
often used inside a pipeline in the synopsis section.

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