On Wed, 18 Aug 2010, Jonathan Nieder wrote:
> Jakub Narebski wrote:
>
> > 1. Description of build-time configuration variable is in the module
> > that defines it, and each block of variables coming from the same
> > module would have notice where one can find description of those
> > variables
> [...]
> > 2. Description of build-time configuration variables is in gitweb.perl,
> > and in each module there is comment that full description of those
> > variables can be found there, e.g. (proposal):
> >
> > # Values of those variables are set during build time in
> > # gitweb/gitweb.perl (main script). You can find their description
> > # there.
> [...]
> > 3. Duplicate description of those variables
>
> With #2, a person reading the Makefile can grep for some particular
> substitution (++GITWEB_PROJECTROOT++) and quickly find the name and
> description of the variable it is used for. If there were a 1:1
> correspondence between the variables in gitweb.perl and the Makefile,
> I would even suggest moving the description to the Makefile.
There is a bit of difference between Perl variables in gitweb.perl and
make build-time variables in gitweb/Makefile, namely:
our $GIT = "++GIT_BINDIR++/git";
our $site_name = "++GITWEB_SITENAME++"
|| ($ENV{'SERVER_NAME'} || "Untitled") . " Git";
our @stylesheets = ("++GITWEB_CSS++");
our @git_base_url_list = grep { $_ ne '' } ("++GITWEB_BASE_URL++");
our $GITWEB_CONFIG = $ENV{'GITWEB_CONFIG'} || "++GITWEB_CONFIG++";
our $GITWEB_CONFIG_SYSTEM = $ENV{'GITWEB_CONFIG_SYSTEM'}
|| "++GITWEB_CONFIG_SYSTEM++";
Perl variables can be overriden in run-time configuration (testsuite
uses this to test _source_ version i.e. gitweb.perl rather than
generated gitweb.cgi), so they have to be described anyway.
I think that adding description of make variables to gitweb/Makefile,
similar to what main Makefile does, would be a good idea, though I don't
like that it leads to some duplication.
>
> In practice, I suspect the run-time configuration is more important to
> people. That is already fairly well documented in gitweb/README.
Build-time configuration is also described in gitweb/README, in more
detail.
--
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