[PATCH] gitweb/INSTALL: Simplify description of GITWEB_CONFIG_SYSTEM

From

Jakub Narębski <jnareb@gmail.com>

Date

Apr 12, 2013, 22:20 UTC

Message-ID

<516888C0.90501@gmail.com>

In-Reply-To

<7vy5cnd0m4.fsf@alter.siamese.dyndns.org>

On Fri, 12 April 2013, Junio C Hamano wrote:

> Jonathan Nieder <jrnieder@gmail.com> writes:
>
>>    Note that if per-instance configuration file exists, then system-wide
>> -  configuration is _not used at all_.  This is quite untypical and suprising
>> +  configuration is _not used at all_.  This is quite untypical and surprising
>>    behavior.  On the other hand changing current behavior would break backwards
>>    compatibility and can lead to unexpected changes in gitweb behavior.
>>    Therefore gitweb also looks for common system-wide configuration file,
>
> Hmm, "atypical", isn't it?
>
> The flow of the text is awkward.  "This is bad. Oh the other hand,
> better is broken. Therefore ..." forces readers to make multiple
> guesses while reading: "ok, bad, so you plan to change it and warn
> us about upcoming change?  oh, not that, changing it is bad, so we
> have to live with it?  oh, not that, there is another one that is
> common and that is what we can use".
>
> It may be a good idea to rewrite this paragraph to avoid such a
> mental roller-coaster in the first place.
>
>     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 file to keep common default
>     settings that apply to all instances.
>
> or something.
>
> Not asking for a re-roll, but it may be a potential follow-up candidate.

Perhaps something like this?

-- >8 --
Subject: [PATCH] gitweb/INSTALL: Simplify description of GITWEB_CONFIG_SYSTEM

Signed-off-by: Junio Hamano <gitster@pobox.com>
Signed-off-by: Jakub Narebski <jnareb@gmail.com>
---
 gitweb/INSTALL |   14 ++++++--------
 1 file changed, 6 insertions(+), 8 deletions(-)

diff --git a/gitweb/INSTALL b/gitweb/INSTALL
index 6d45406..7ad1050 100644
--- a/gitweb/INSTALL
+++ b/gitweb/INSTALL
@@ -243,14 +243,12 @@ for gitweb (in gitweb/README), and gitweb.conf(5) manpage.
   GITWEB_CONFIG_SYSTEM build configuration variable, and override it
   through the GITWEB_CONFIG_SYSTEM environment variable.
 
-  Note that if per-instance configuration file exists, then system-wide
-  configuration is _not used at all_.  This is quite untypical and suprising
-  behavior.  On the other hand changing current behavior would break backwards
-  compatibility and can lead to unexpected changes in gitweb behavior.
-  Therefore gitweb also looks for common system-wide configuration file,
-  normally /etc/gitweb-common.conf (set during build time using build time
-  configuration variable GITWEB_CONFIG_COMMON, set it at runtime using
-  environment variable with the same name).  Settings from per-instance or
+
+  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.
 

-- 
1.7.10.4