Re: [PATCH v2 1/5] doc: git-diff: apply new documentation guidelines

From: Junio C Hamano <gitster@pobox.com>
Date: Nov 12, 2024, 23:01 UTC
Message-ID: <xmqqcyj03vlk.fsf@gitster.g>
In-Reply-To: <45211c3c-e077-4de3-a167-0fc973a78dba@kdbg.org>

Johannes Sixt <j6t@kdbg.org> writes:

Show 8 quoted lines

> Does
>
> `-1`, `--base`::
> `-2`, `--ours`::
> `-3`, `--theirs`::
>
> not work? (I think we agree that grouping synonyms should be done and
> not all tokens moved onto a flat line.)

With the current

    -1 --base::
    -2 --ours::
    -3 --theirs::
	body text

these are coalesced into a single header and get rendered as

    -1 --base, -2 --ours, -3 --theirs
	body text

which reasonably shows that 1 and base belong to the same family that is different from 2 and ours, etc. With an explicit comma in between 1 and base, would we end up with

    -1, --base, -2, --ours, -3, --theirs

which may be worse than what we have currently?

Thanks.

$ cat FOOTERMessages come from the public archive at lore.kernel.org/git, fetched every hour. The front page is chosen and written each morning by an AI editor and can be wrong; the threads themselves are the record. About and API. For agents: an MCP server at https://gitlist.dev/mcp, and any thread, story or person page as Markdown by adding .md to its URL (or sending Accept: text/markdown). Details in /llms.txt.