Re: [RFC] Another way to provide help details. (was Re: [PATCH] Add help details to git help command.)

[David Greaves <david@dgreaves.com>]

Petr Baudis wrote:
> Dear diary, on Tue, Apr 19, 2005 at 03:40:54AM CEST, I got a letter
> where Steven Cole <elenstev@mesatop.com> told me that...
> 
>>Here is perhaps a better way to provide detailed help for each
>>git command.  A command.help file for each command can be
>>written in the style of a man page.
> 
> 
> I don't like it. I think the 'help' command should serve primarily as a
> quick reference, which does not blend so well with a manual page - it's
> too long and too convoluted by repeated output.
> 
> I'd just print the top comment from each file. :-)
> 

On the other hand, having more complete docs seems like an excellent 
idea (and other threads support that)
I'd certainly like to see more specification oriented documentation...
(even if it turns out to be disposable)

Steven, if you carry on sending more verbose docs I'll certainly read 
and work with you on editing them...

Nb kernel-doc doesn't seem appropriate for user level docs.
maybe, whilst there's so much flux, have:
   git man command
that just outputs text

If Petr wants the top comment to be extracted by help then maybe a 
bottom comment block could contain the more complete text?
I *really* think that the user docs should live in the source for now 
(hence I think that git man is better than going straight to man/docbook).

I wasn't sure whether to perlise the code or do a shell-lib - but 
looking at the algorithms needed in things like git status I reckon the 
shell will end up becoming a hackish mess of awk/sed/tr/sort/uniq/pipe 
(ie perl) anyway.

So I'm going to have a go at that - Petr, if you have a minute could you 
send me, off list, a bit of perl code that epitomises the style you like?

David