Re: [PATCH] gitweb/INSTALL: Simplify description of GITWEB_CONFIG_SYSTEM

On Tue, Apr 16, 2013 at 12:36 AM, Junio C Hamano [off-list ref] wrote:

Drew Northup [off-list ref] writes:

quoted

quoted

+  Note that the GITWEB_CONFIG_SYSTEM system-wide configuration file is
+  only used for instances that lack per-instance configuration file.
+  You can use GITWEB_CONFIG_COMMON common system-wide configuration
+  file (normally /etc/gitweb-common.conf) to keep common default
+  settings that apply to all instances.  Settings from per-instance or
   system-wide configuration file override those from common system-wide
   configuration file.

That's the point of explaining SPECIFICALLY why the then current
behavior wasn't being replaced, and this other mechanism (which would
otherwise have no obvious reason for existing) was being introduced.

In order to just pick and use the more appropriate one (or a useful
combination of the two), a clean description of what each of them do
without historical cruft is more readable and useful, isn't it?

I am not demanding the retention of cruft, and the rewording is
definitely more pleasant to read.

 I
would expect that most of them who are newly configuring a system
would pick COMMON one and override per instance as needed, without
touching the SYSTEM one (fallback default) after reading the above,
and that is what we want to happen.

Do you think sysadmins need a history lesson to understand why there
are two different possibilities?

We don't need a full history lesson. What we do need to know is that
"Hey, they don't do that the way everybody else does because it would
break things." That's enough to get the point across, and as Jakub
noted gitweb.conf.txt is the correct place for it.

For example, bash reads some but not all possible configuration
files. I would expect .bashrc to be read even for login shells after
reading .bash_login; alas, that is not what happens.  The manual
does not apologize that the authors now know better and understand
that it is a stupid behaviour.  The order the rc files are read is
just described matter-of-factly, and it gives sufficient information
without unnecessary backstory.

I think the new text conveys the necessary information to the
intended audience with more clarity without the history lesson or
the record of your past frustration. Am I mistaken?

The back-story isn't needed; the "Hey this is different" part is. I
think Jakub's suggestion of covering that (succinctly) in
gitweb.conf.txt is the correct solution.

--
-Drew Northup
--------------------------------------------------------------
"As opposed to vegetable or mineral error?"
-John Pescatore, SANS NewsBites Vol. 12 Num. 59