On Thu, 2011-05-12 at 10:24 -0700, J.H. wrote: > 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. > > > > 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. As noted earlier, we need to make sure that nothing that should be documented as (reasonably) settable during runtime remains in the INSTALL file if that is to be the case. We aren't there yet. > >>> TODO: > >>> * Clean up README and INSTALL files > >>> * Add Makefile rules to build man / HTML pages. > >>> * Remove or rephrase redundant portions of original documentation ... > > 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. I don't think that in the long term it makes sense to leave the README as it is if we are extracting stuff into other files. As for removing documentation lines from the "executable" itself, I'm not going there. (I almost never recommend removing documentation from a program's source text, even when it is excessive.) This was a FIRST DRAFT. Fun stuff like make scripting and such can start shortly if we continue to think splitting this out into asciidoc is a good idea. (It is sounding like it.) I honestly wasn't planning on a formal v1 without completing (or nearly so) the TODO list above--hence the lack of a sign-off line. -- -Drew Northup ________________________________________________ "As opposed to vegetable or mineral error?" -John Pescatore, SANS NewsBites Vol. 12 Num. 59 -- 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