From: Junio C Hamano <gitster@pobox.com>
Date: Mon, 12 Jan 2026 03:13:39 GMT
Subject: Re: [PATCH 1/1] doc: git-bisect: convert to new doc format
Message-ID: <xmqq1pjvplp8.fsf@gitster.g>
In-Reply-To: <20260111204316.836446-2-git@michael.lyo.nz>

Michael Lyons <git@michael.lyo.nz> writes:

> - Change placeholders to glossary terms

I see you changed <rev> to <commit> and I guess the point above is a
reference to that change, but I cannot be sure if (1) there are
things other than <rev> that you changed for the same reason, and
(2) if "glossary has it" is the reason for the change (we have
"revision" in there, and it is widely known that "rev" is an
abbreviation for it in the context of these documentation pages).

You can rephrase the above, perhaps like

    Some parameters are described with placeholders with less common
    words, which is unnecessarily harder to understand by new
    readers.  Use <commit> instead of <rev>.

to avoid the problem, if <rev> -> <commit> is the only change for
this reason.  If there are more words you addressed, perhaps you can
replace the last sentence.


> - Refer to placeholders in prose
> - Delimit runnable commands and CLI args with backticks
> - Link internal heading

The same comments may apply to these three.

Thanks.