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

From: Junio C Hamano <[email-masked]>
Date: Wed, 24 Jul 2024 16:15:48 -0700

"Jean-Noël Avila via GitGitGadget" <[email-masked]> 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>]

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.

Thanks.