Re: [RFC/PATCHv3 4/5] gitweb: Starting work on a man page for /etc/gitweb.conf (WIP)

[Jakub Narebski <jnareb@gmail.com>]

On Tue, 7 June 2011, Drew Northup wrote:
> On Tue, 2011-06-07 at 10:00 -0700, Junio C Hamano wrote:
>> Drew Northup <drew.northup@maine.edu> writes:
>> 
>>> On Tue, 2011-06-07 at 08:44 -0500, Jonathan Nieder wrote:
>>> ...
>>> If this is what you are proposing then we should be working on a
>>> "gitweb_config.perl" manpage and not a "gitweb.conf" manpage. I know a
>>> fair number of people around here put priority on the former and would
>>> just as soon ignore the latter. That's what your proposed change says to
>>> me (while I also understand that your own position is likely far more
>>> nuanced than that).
>> 
>> Hmm, do you want to have two (and then three, see below) separate manpages
>> that essentially describe the same thing, and refer to each other when
>> they talk about the precedence order?
> 
> No, I am just saying that if this isn't primarily meant to be
> about /etc/gitweb.conf (which is what I was told to use here on this
> very list) then we shouldn't name it after gitweb.conf,

We have to name it somehow.  For example ssh_config(5) is named after 
system-wide settings file, while it describes also user settings in
.ssh/config.  We would follow this example with gitweb.conf(5)

A bit closed, gitignore(5) and gitattributes(5) both are named after
in-tree file '.gitignore' and '.gitattributes', but describe also
private $GIT_DIR/info/exclude (not ignore!) and $GIT_DIR/info/attributes
respectively.


Anyway we can use symlinks or hardlinks (or just a plain copy) to have
this manpage under both gitweb.conf(5) and gitweb_config(5) or 
gitweb_config.perl(5).  There is precedent: many function manpages
are grouped together.  For example printf,  fprintf, sprintf, snprintf,
vprintf, vfprintf, vsprintf, vsnprintf all use single printf(3) manpage.

But that is better left for a separate commit, if we decide to do this.

> nor should we focus on gitweb.conf

Manpage describing gitweb.conf also describes gitweb_conf.perl.  The
difference is minuscule, so it is IMVHO better to cover both with one
manpage, and add a few paragraphs about precedence etc.  Isn't it?

> (the removal of the gitweb.conf we are then 
> effectively deprecating can be discussed later; I have already voiced my
> opinion on this strategy of ignoring /etc/gitweb.conf but still having
> it anyway and been summarily declared insane).

The problem is backward compatibility.  To not repeat myself, see my
thoughts on this issue later, at the end of this email.

> 
> The change he made isn't, to me anyway, one of precedence order but is
> one of focus and theme. Perhaps most people around here aren't trained
> to hew so closely to the stated purpose of a work as I am and therefore
> don't see the change he suggested as starkly. So be it. 
> I really don't like starting work on something for a project because I
> was told that (1) it was needed and, (2) it would be welcome only to
> find that neither statement was particularly true. I'd strongly prefer
> to have been told from the outset "Don't bother to document that, as
> you're the only one using it that way," and, "Document this instead, as
> just because you're not using it doesn't mean that we don't think
> everyone else should be."

Actually it both was needed and welcome.  Thanks again for your work.

The fact that your hard and welcome work on gitweb.conf manpage with
small additions (which you don't need to put yourself; we can do it
instead) is more general manpage about gitweb config files is a happy
thing.
 

>> I vaguely recall that there was an effort to document /etc/gitweb.conf as
>> a mere "fallback default", not a "system-wide configuration file", which
>> is what it is, and also to introduce a true "system-wide configuration" as
>> a separate file, so that the system-wide one will be read, and then either
>> per-instance gitweb_config.perl or the fallback default /etc/gitweb.conf
>> will update it. What happened to that effort?

If the "version C" effort, namely introducing gitweb-common.conf in

  [PATCH/RFC 2/2 (version C)] gitweb: Introduce common system-wide settings for convenience
  Message-Id: <201105261658.20140.jnareb@gmail.com>
  http://thread.gmane.org/gmane.comp.version-control.git/174424/focus=174517

in thread titled

  [PATCH 0/2] gitweb: Improve handling of configuration files

is not in cooking stage, but fell into cracks, I can always resend said
patch.
 
> You shot it down, that's what. Or more correctly you shot down the use
> of /etc/gitweb.conf as a system-wide source of default settings instead
> proposing that it be used as a fallback (?) and that
> an /etc/gitweb-defaults.conf (or something like that) be used as a
> per-item default (or at least that's what I got out of what was said).
> I'm not sure what to think of that, but I haven't had the chance to test
> that patch-set in any case, much less incorporate it into the
> documentation. All of that would come after I'm no longer confused as to
> what the intended end-result would be.
>> 
>> In any case, with the current design, /etc/gitweb.conf is _not_ the
>> system-wide configuration file but it is a fallback default for instances
>> that do not have per-instance configuration, so the quoted part would need
>> rewording anyway, I think.
> 
> And THAT is the problem. If it isn't a system-wide configuration file
> then let's stop putting it in /etc, deprecate it, and get it over with.
> I didn't even know that to be the case when I started writing this, I
> was just trying to make more readily available the advice I'd been given
> on this list. Only after getting started did I learn that gitweb treats
> a file in /etc like nothing else I normally use (aside from
> adduser/useradd's use of /etc/skel as a directory template).

What about /etc/bashrc ?  Isn't is treated as fallback, and you have to
source it explicitly?

Anyway, because of backward compatibility (bug-compatible) we have to
name new system-wide config file /etc/gitweb-common.conf, fallback config
be at /etc/gitweb.conf, and per-instance config file gitweb_config.perl
Note that these are only defaults; they can be overridden at build time
(though you cannot change names of respective environmental variables).

Perhaps at some flag day (1.8.0 is probably to close) we can change it so
that system-wide config file is /etc/gitweb.conf, per-instance config file
(overriding system-wide settings) is gitweb_config.perl, and fallback
system-installed config file used if per-instance config file does not
exists is /etc/gitweb_config.perl

But still the manpage should IMVHO be gitweb.conf(5)!

-- 
Jakub Narebski
Poland