From: Junio C Hamano <gitster@pobox.com>
Date: Wed, 24 Jul 2024 23:15:48 GMT
Subject: Re: [PATCH v2 0/3] doc: introducing synopsis para
Message-ID: <xmqqcyn2s7ob.fsf@gitster.g>
In-Reply-To: <pull.1766.v2.git.1721855179.gitgitgadget@gmail.com>

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

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.