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

From: Jeff King <peff@peff.net>
Date: Oct 25, 2010, 15:11 UTC
Message-ID: <20101025151125.GD28278@sigill.intra.peff.net>
In-Reply-To: <201010251444.08780.jnareb@gmail.com>

On Mon, Oct 25, 2010 at 02:44:06PM +0200, Jakub Narebski wrote:

Show 9 quoted lines

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

Show 13 quoted lines

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

Show 7 quoted lines

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

Show 8 quoted lines

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