Re: [PATCH/WIP] Starting work on a man page for /etc/gitweb.conf

From: J.H. <warthog9@kernel.org>
Date: May 12, 2011, 17:24 UTC
Message-ID: <4DCC17BE.7000005@kernel.org>
In-Reply-To: <201105121701.26547.jnareb@gmail.com>

On 05/12/2011 08:01 AM, Jakub Narebski wrote:

Show 11 quoted lines

> On Thu, 12 May 2011, Jonathan Nieder wrote:
>> Drew Northup wrote:
>>
>>> This is a work in progress. Much of what is in it has been pulled
>>> directly from the README and INSTALL files of gitweb. No effort has yet
>>> been made to de-duplicate any of this.
> 
> While it might be a good idea to split main part of gitweb/README into
> gitweb.conf.txt (documenting configuration), and perhaps also separate
> gitweb.txt (main page for gitweb, like SVN::Web manpage), I don't think
> that much of gitweb/INSTALL should be moved.

I would agree with this, if you are shooting for a config file man/txt/html page INSTALL has nothing to do with it, and serves a different purpose.

Show 17 quoted lines

>>> TODO:
>>>   * Clean up README and INSTALL files
>>>   * Add Makefile rules to build man / HTML pages.
>>>   * Remove or rephrase redundant portions of original documentation
>>>   * A lot more...
>>
>> I agree with this TODO list. :)  It should be possible to reuse rules from
>> Documentation/Makefile if you put this under Documentation/.  gitweb already
>> keeps its tests under t/ for convenience; I think it's okay if it
>> puts some documentation under Documentation/.
> 
> Note that git-gui and gitk both also keep their manpages in Documentation/
> as Documentation/git-gui.txt and Documentation/gitk.txt
> 
> We can add "doc" target to gitweb/Makefile, which would delegate work to
> ../Documentation/Makefile, similarly to existing "test" target in
> gitweb/Makefile.

I disagree slightly, I'd personally rather try and keep gitweb more self-contained under gitweb/. I can see the advantage of keeping the docs under Documentation/ but I can also appreciate keeping gitweb self contained, like it is currently.

Show 18 quoted lines

>>> +
>>> +SYNOPSIS
>>> +--------
>>> +/etc/gitweb.conf
> 
> I'd say
> 
>     +SYNOPSIS
>     +--------
>     +gitweb_conf.perl
>     +/etc/gitweb.conf
> 
> or
> 
>     +SYNOPSIS
>     +--------
>     +$GITWEBDIR/gitweb_conf.perl
>     +/etc/gitweb.conf

I'd prefer the later, I don't know of many people who actually use /etc/gitweb.conf, and I'd rather see this be a more generic man page than steering someone who's implementing this to only trying to use /etc/gitweb.conf

Show 7 quoted lines

>> gitweb will also look for gitweb_config.perl along @INC, and
>> the $GITWEB_CONFIG and $GITWEB_CONFIG_SYSTEM envvars can override
>> these paths.
> 
> I think that we don't need to describe envvars in synopsis, but we
> should have per-gitweb configuration file (gitweb_conf.perl) in
> "Synopsis" section.

That sounds more like an INSTALL thing.

[...]

Beyond that I've no real issue that haven't already been brought up, but I do want to make sure that the ultimate plan here is to add the scripts that generate this vs. the final output, right? I mean we already have 2 places this documentation lives (in gitweb.perl and README), I'm not sure we need a 3rd place to update the documentation at by hand. Just asking.

- John 'Warthog9' Hawley