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

[Jeff King <peff@peff.net>]

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.

>    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 appropraite that is, though.

> >   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.

> 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. 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).

If you're going to do that, though, there's no point in having
merge-options separate. make-config-list should just generate both
lists.

> >        format.pretty::
> >                The default pretty format for log/show/whatchanged command,
> >                See linkgit:git-log[1], linkgit:git-show[1],
> >                linkgit:git-whatchanged[1].
> [...]
> 
> Actually the above block describing `format.pretty` is from beginning in
> config-vars-src.txt, and is not added / created by said script.

Oh, you're right. I was browsing the output and just assumed it was
created by the script, since it is of a similar form.

> >      [1]: I assume the single line of block description is an error in
> >           your script.
> 
> Hmmm?

The comma at the end made it look to me like a sentence had been cut off
during parsing. But looking at config.txt, it is simply a typo.  The
comma should be a period.

-Peff