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

["J.H." <warthog9@kernel.org>]

On 05/12/2011 08:01 AM, Jakub Narebski wrote:
> 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.

>>> 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.

>>> +
>>> +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

>> 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