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

From: Fernando Ramos <greenfoo@u92.eu>
Date: Mar 27, 2022, 21:10 UTC
Message-ID: <YkDS3CJEPYpzRoVG@zacax395.localdomain>
In-Reply-To: <001d3ecd-e1bd-39f4-5123-4a8b1bd1b5a8@gmail.com>

Show 12 quoted lines

> > +mergetool.{n,g,}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.
> > +
> 
> I generated the man page for 'git-mergetool' and this bit is included in the 
> Configuration section, that's great. However, it feels a little weird to read
> "see BACKEND SPECIFIC HINTS section of linkgit:git-mergetool[1]" there, since
> that's the help page I'm already reading. So maybe it would be nice to use an
> Asciidoc 'ifndef::git-mergetool[]' directive here to hide the "of linkgit:git-mergetool[1]"
> bit if the current page is git-mergetool[1] ?

Good call. I tried this:

    mergetool.{n,g,}vimdiff.layout::
    	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?

> This whole section above needs some indentation work to format nicely in Asciidoc/
> Asciidoctor. I've fixed it and will send a 'fixup' patch as a reply.

Thanks! I will include your patch in v7

Show 10 quoted lines

> This is OK, but adds a lot of lines to the output. Maybe we could display the help
> on the same line ? Something like:
> 
> $ ./bin-wrappers/git mergetool --tool-help
> 'git mergetool --tool=<tool>' may be set to one of the following:
> 		emerge
> 		opendiff
> 		vimdiff		Layout can be customized. Run 'git help mergetool' and check the 'BACKEND SPECIFIC HINTS' section.
> 		vimdiff1	Layout can be customized. Run 'git help mergetool' and check the 'BACKEND SPECIFIC HINTS' section.
> 		# etc.

Yes. It looks nicer in one line. In addition, right now it doesn't offer enough information to figure out the difference among variants (vimdiff vs vimdiff1 vs ...) that's why I'm going to update v7 to print something like this following your advice:

    $ ./bin-wrappers/git mergetool --tool-help
    'git mergetool --tool=<tool>' may be set to one of the following:
                    araxis
                    meld
                    vimdiff    Use Vim with a custom layout (see `git help mergetool`'s `BACKEND SPECIFIC HINTS` section).
                    vimdiff1   Use Vim with a 2 panes layout (LOCAL and REMOTE)
                    vimdiff2   Use Vim with a 3 panes layout (LOCAL, MERGED and REMOTE)
                    vimdiff3   Use Vim where only the MERGED file is shown
                    ...