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 -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html