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

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

On Thu, 12 May 2011, Jonathan Nieder wrote:

quoted

Drew Northup wrote:

quoted

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.

quoted

quoted

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.

quoted

quoted

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

quoted

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