Re: [RFC PATCH v2 0/3] Documentation: refactor config variable descriptions

[Jakub Narebski <jnareb@gmail.com>]

On Mon, 25 Oct 2010, Jeff King wrote:
> On Mon, Oct 25, 2010 at 02:44:06PM +0200, Jakub Narebski wrote:
> 
> > 2. With checking for CONFIGURATION-like, we would miss the following
> >    configuration variables:
> > 
> >      http.getanyfile:: (for git-http-backend, in 'SERVICES')
> >      http.uploadpack:: (for git-http-backend, in 'SERVICES')
> >      http.receivepack:: (for git-http-backend, in 'SERVICES')
> > 
> >    These are in git-http-backend manpage, in 'SERVICES' section, which 
> >    probably should be named then 'CONFIGURING SERVICES'.
> 
> I would argue those should probably go in a CONFIGURATION section for
> consistency with the rest of the manpages.

What consistency ;-)?  But I agree, if we can switch all the following 
variants to 'CONFIGURATION', it should also go in 'CONFIGURATION'
section.  If we cannot, then 'CONFIGURING SERVICES' as section name,
and /^Config/i as a regexp detecting if we are in relevant section.

> >    BTW, CONFIGURATION-like means:
> > 
> >     * Configuration
> >     * CONFIGURATION
> >    
> >   but also
> > 
> >     * CONFIG FILE-ONLY OPTIONS
> >     * CONFIGURATION FILE
> >     * Configuration Mechanism
> >     * CONFIG VARIABLES
> >     * CONFIGURATION VARIABLES
> >     * Configuring database backend
> 
> Again, I think for consistency for the reader, it may make sense to
> switch them all to CONFIGURATION. I'd have to look at each page and see
> how appropriate that is, though.

Right.

> > >   2. You recursively follow includes via include::. This means that the
> > >      make rule is not accurate. E.g., try:
> > [...]
> > We do that: see 'doc.dep' target in Documentation/Makefile.  We just
> > need for this target to also add dependencies for config-vars.txt
> > (perhaps separate mode for make-config-list.perl, or perhaps 
> > build-docdep.perl should be config-vars-src.txt aware...).
> 
> Yeah, that would definitely work.

Though simpler would be just to not use or turn off following includes,
as it turned out that it doesn't matter to follow includes in manpages:
if we include with config variables, it is to also include it in 
config-vars-src.txt.

Well, assuming that we don't have to follow includes in config-vars-src.txt;
otherwise we have to generate line in doc.dep for that include anyway.

> > Note however that make-config-list.perl only creates minimal documentation,
> > just link(s) to appropriate mapage(s).  Include-ing merge-config.txt both
> > in git-merge.txt and config-vars-src.txt means that we have merg config
> > variables defined in git-config(1) manpage, which I think is nice to have.
> 
> I disagree. I think one of the benefits of this exercise is generating a
> more concise list. 

I can agree with eliminating those blocks that consist only of list of
variables and reference to main page, like the following[1]

  sendemail.<identity>.*::
        Identity-specific versions of the 'sendemail.*' parameters
        found below, taking precedence over those when the this
        identity is selected, through command-line or
        'sendemail.identity'.

  sendemail.aliasesfile::
  sendemail.aliasfiletype::
  sendemail.bcc::
  sendemail.cc::
  [...]
  sendemail.thread::
  sendemail.validate::
        See linkgit:git-send-email[1] for description.


and perhaps also this block

  imap::
        The configuration variables in the 'imap' section are described
        in linkgit:git-imap-send[1].

[1] Though only if we can ensure that they are added below 
'sendemail.<identity>.*', which refers to them.

> That being said, I don't think there's any reason we
> can't have a terse list in gitconfig(7) and a much larger one in
> gitconfigfull(7) or something like that (or even put it later in the
> manpage of gitconfig(7), or whatever).

You can mechanically move or copy description of config variables from
config-vars-src.txt to individual manpages.  Moving in reverse direction,
like in your autogenerated gitconfigfull(7) proposal, is not that easy:
description of config variables in individual manpages can refer to
other parts of said manpage (and barring AI you cannot reliably detect
such situation).

-- 
Jakub Narebski
Poland