David Greaves wrote:
Petr Baudis wrote:
Dear diary, on Tue, Apr 19, 2005 at 03:40:54AM CEST, I got a letter
where Steven Cole <[EMAIL PROTECTED]> 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...
I only did those first two as a straw man. Doing the others is a couple
hours (or less) work, but I don't want to do it if folks don't want it.
Having the help files separate has advantages/disadvantages.
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
Funny you should mention Perl. Here is small bit of code:
[EMAIL PROTECTED] git-pasky-testing]$ cat print_help_header.pl
#!/usr/bin/perl
# reads from stdin writes to stdout no error checking
<STDIN>;<STDIN>;
while (substr( $line=<STDIN>, 0, 1) eq "#") {
print $line;
}
[EMAIL PROTECTED] git-pasky-testing]$ ./print_help_header.pl <gitdiff.sh | grep ^# | grep
-v "(c)" | cut -c 3-
Make a diff between two GIT trees.
By default compares the current working tree to the state at the
last commit. You can specify -r rev1:rev2 or -r rev1 -r rev2 to
tell it to make a diff between the specified revisions. If you
do not specify a revision, the current working tree is implied
(note that no revision is different from empty revision - -r rev:
compares between rev and HEAD, while -r rev compares between rev
and working tree).
-p instead of one ID denotes a parent commit to the specified ID
(which must not be a tree, obviously).
Outputs a diff converting the first tree to the second one.
-------end of output from perl plus grep and cut.
Without the perl, extra comments came out (plus the dreaded first blank line).
[EMAIL PROTECTED] git-pasky-testing]$ cat gitdiff.sh | grep -v "/bin" | grep ^# |
grep -v "(c)" | cut -c 3-
Make a diff between two GIT trees.
By default compares the current working tree to the state at the
last commit. You can specify -r rev1:rev2 or -r rev1 -r rev2 to
tell it to make a diff between the specified revisions. If you
do not specify a revision, the current working tree is implied
(note that no revision is different from empty revision - -r rev:
compares between rev and HEAD, while -r rev compares between rev
and working tree).
-p instead of one ID denotes a parent commit to the specified ID
(which must not be a tree, obviously).
Outputs a diff converting the first tree to the second one.
FIXME: The commandline parsing is awful.
-------end of output from grep and cut.
David,
I'm a bit pressed for time, so if you or anyone else would like to
use this code to fix up my earlier patch, you're welcome to it.
Otherwise, it will be later this evening or tomorrow before I can
do any more with this.
Steven
-
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to [EMAIL PROTECTED]
More majordomo info at http://vger.kernel.org/majordomo-info.html
