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

From: Junio C Hamano <gitster@pobox.com>
Date: Jul 24, 2024, 23:15 UTC
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.