git/list[1] front-page[2] threads[3] people[4] search[5] about
 

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

From
Drew Northup <drew.northup@maine.edu>
Date
May 12, 2011, 18:16 UTC
Message-ID
<1305224164.24667.87.camel@drew-northup.unet.maine.edu>
In-Reply-To
<4DCC17BE.7000005@kernel.org>
On Thu, 2011-05-12 at 10:24 -0700, J.H. wrote:
Show 14 quoted lines
> 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
...
Show 7 quoted lines
> 
> 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
Previous: J.H.Next: Jakub Narebski
Message 6 of 11 in “Starting work on a man page for /etc/gitweb.conf”
  1. Starting work on a man page for /etc/gitweb.confDrew Northup, May 11, 2011
  2. Jonathan NiederMay 12, 2011
  3. Jakub NarebskiMay 12, 2011
  4. Drew NorthupMay 12, 2011
  5. J.H.May 12, 2011
  6. Drew NorthupMay 12, 2011
  7. Jakub NarebskiMay 12, 2011
  8. Jakub NarebskiMay 12, 2011
  9. Drew NorthupMay 12, 2011
  10. Jakub NarebskiMay 12, 2011
  11. gitweb: Starting work on a man page for gitweb (WIP)Jakub Narebski, May 15, 2011

Read the whole thread, see it on lore, or plain text.

$ cat FOOTERMessages come from the public archive at lore.kernel.org/git, fetched every hour. The front page is chosen and written each morning by an AI editor and can be wrong; the threads themselves are the record. About and API. For agents: an MCP server at https://gitlist.dev/mcp, and any thread, story or person page as Markdown by adding .md to its URL (or sending Accept: text/markdown). Details in /llms.txt.