Re: [PATCH v6 3/3] vimdiff: add tool documentation

From: Junio C Hamano <gitster@pobox.com>
Date: Mar 27, 2022, 21:43 UTC
Message-ID: <xmqqmthb5aw8.fsf@gitster.g>
In-Reply-To: <YkDS3CJEPYpzRoVG@zacax395.localdomain>

Fernando Ramos <greenfoo@u92.eu> writes:

> Good call. I tried this:
>
>     mergetool.{n,g,}vimdiff.layout::

It is not like we have infinite variants of these. Spelling them out like

	mergetool.vimdiff.layout::
	mergetool.gvimdiff.layout::
	mergetool.nvimdiff.layout::

would probably be a better idea.

Show 12 quoted lines

>     	The vimdiff backend uses this variable to control how its split
>     	windows look like.  See BACKEND SPECIFIC HINTS section
>     ifndef::git-mergetool[] 
>     	(on linkgit:git-mergetool[1])
>     endif::[]
>     	for details.
>
> ...does it look good?
>
> I'm asking because I ran "make doc" and the generated man page always contains
> the extra piece. When are those asciidoc directives processed? Should two
> versions of the same man page be generated?

Are you signalling the above part that it is (or isn't) included in git-mergetool.txt by defining

	:git-mergetool: 1

before the piece gets included with

	include::config/mergetool.txt

See for example how git-rev-list.txt tweaks what gets included from rev-list-description.txt by doing:

    'git rev-list' [<options>] <commit>... [[--] <path>...]

    DESCRIPTION
    -----------

    :git-rev-list: 1
    include::rev-list-description.txt[]

    'rev-list' is a very essential Git command, since it