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
--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html