Re: fr/vimdiff-layout

[Junio C Hamano <gitster@pobox.com>]

Fernando Ramos <greenfoo@u92.eu> writes:

>> It looks like it's emitting a new warning from the "Makefile" in
>> check-docs:
>> 	
>> 	$ (make clean && make check-docs) >/dev/null 2>&1; make check-docs
>> 	make -C Documentation lint-docs
>> 	make[1]: Entering directory '/home/avar/g/git/Documentation'
>> 	make[1]: Nothing to be done for 'lint-docs'.
>> 	make[1]: Leaving directory '/home/avar/g/git/Documentation'
>> 	removed but documented: git-difftool--vimdiff
>> 	removed but documented: git-mergetool--vimdiff
>> 	removed but documented: git-version
>
> Looking at how the Makefile works it looks like this error is triggered
> because...
>
>   1. I have created these two new files:
>      - Documentation/git-difftool--vimdiff.txt
>      - Documentation/git-mergetool--vimdiff.txt
>
>   2. None of them are real programs (such as "git-clone") or scripts (such as
>      "git-mergetool--lib.sh")
>
> All the other "Documentation/*.txt" files are associated to "something" that
> can be executed, but not these two (they are only meant to be accessed from "git
> help" / "man").

Thanks for noticing and reporting, Ævar.

I think the right place to describe how vimdiff or other
configuration should be configured should live next to configuration
documentation for other backends.

Documentation/git-mergetool.txt is the main entry point for those
who want to learn about "git mergetool", i.e. "git mergetool --help"
shows what's in there.

The documentation talks about the "mergetool" front-end, and then
includes config/mergetool.txt for the configuration files.

After all, the topic adds only one mergetool.<tool>.layout
configuration variable.  The file config/mergetool.txt would be the
place to describe that variable, after the entry for
mergetool.meld.useAutoMerge, which is already is about a variable
that is specific to a particular backend.  If we can successfully
can go this route, we do not need any new file added at all.

Alternatively, in the longer run, we may want backend specific
information in the "git mergetool --help" documentation.  Maybe
vimdiff is the first and currently only such backend that wants
documentation specific to it, but it does not has to stay that way
forever.

So adding a new section "BACKENDS SPECIFIC HINTS" after "TEMPORARY
FILES" section, and add "VIMDIFF" as its first (and currently only)
subsection, would be a reasonable thing to do.  Create a
Documentation/mergetools/ subdirectory, add vimdiff.txt file in
there, move the most of what is in git-mergetool--vimdiff.txt, and
include it from Documentation/git-mergetool.txt, perhaps like the
attached patch outlines?



diff --git c/Documentation/config/mergetool.txt w/Documentation/config/mergetool.txt
index cafbbef46a..19ca39d43d 100644
--- c/Documentation/config/mergetool.txt
+++ w/Documentation/config/mergetool.txt
@@ -45,6 +45,11 @@ mergetool.meld.useAutoMerge::
 	value of `false` avoids using `--auto-merge` altogether, and is the
 	default value.
 
+mergetool.vimdiff.layout::
+	The vimdiff backend uses this variable to control how its split
+	windows look like.  See BACKEND SPECIFIC HINTS section of
+	linkgit:git-mergetool[1] for details.
+
 mergetool.hideResolved::
 	During a merge Git will automatically resolve as many conflicts as
 	possible and write the 'MERGED' file containing conflict markers around
diff --git c/Documentation/git-mergetool.txt w/Documentation/git-mergetool.txt
index e587c7763a..6cf3734544 100644
--- c/Documentation/git-mergetool.txt
+++ w/Documentation/git-mergetool.txt
@@ -113,6 +113,16 @@ Setting the `mergetool.keepBackup` configuration variable to `false`
 causes `git mergetool` to automatically remove the backup as files
 are successfully merged.
 
+BACKEND SPECIFIC HINTS
+----------------------
+
+Here we'll give backend specific hints.
+
+vimdiff
+~~~~~~~
+include::mergetools/vimdiff.txt[]
+
+
 GIT
 ---
 Part of the linkgit:git[1] suite
diff --git c/Documentation/mergetools/vimdiff.txt w/Documentation/mergetools/vimdiff.txt
new file mode 100644
index 0000000000..1cac121283
--- /dev/null
+++ w/Documentation/mergetools/vimdiff.txt
@@ -0,0 +1,11 @@
+vimdiff
+~~~~~~~
+
+Vimdiff backend allows `mergetools.vimdiff.layout` to specify how
+the split window is used ...
+
+Layout
+^^^^^^
+
+Text.
+