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

From: Junio C Hamano <[email-masked]>
Date: Sun, 27 Mar 2022 14:43:51 -0700

Fernando Ramos <[email-masked]> 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.

>     	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