Re: [PATCH v2 3/5] doc: git-diff: apply format changes to diff-format

From: Junio C Hamano <gitster@pobox.com>
Date: Nov 12, 2024, 23:03 UTC
Message-ID: <xmqq8qto3vhy.fsf@gitster.g>
In-Reply-To: <6c1c1ae2-f38a-4458-a9ad-2fad3e56fc32@kdbg.org>

Johannes Sixt <j6t@kdbg.org> writes:

Show 10 quoted lines

> Am 11.11.24 um 17:53 schrieb Jean-Noël Avila via GitGitGadget:
>> -The raw output format from "git-diff-index", "git-diff-tree",
>> -"git-diff-files" and "git diff --raw" are very similar.
>> +The raw output format from `git-diff-index`, `git-diff-tree`,
>> +`git-diff-files` and `git diff --raw` are very similar.
>
> Throughout this document we see a lot of commands with dashes `git-foo`.
> Does this have any significance, or should they be corrected to the
> dashless form `git foo`? It could even be a "while at it"-change as you
> are touching every instance anyway.

Yup, these "git-foo" are historical wart from pre Git 1.6 days.

Show 10 quoted lines

>>  These commands all compare two sets of things; what is
>>  compared differs:
>>  
>> -git-diff-index <tree-ish>::
>> -        compares the <tree-ish> and the files on the filesystem.
>> +`git-diff-index <tree-ish>`::
>> +	compares the _<tree-ish>_ and the files on the filesystem.
>
> Now that the backtick formats the content as in the synopsis, why is it
> written _<tree-ish>_ and not `<tree-ish>` in the running text?

Perhaps that is because the body text does want to show the placeholder in _italics_ but not as a `literal` string?