Re: [PATCH] Document git-runstatus

On Sat, Nov 18, 2006 at 09:04:31PM CET, Sean wrote:

On Sat, 18 Nov 2006 11:37:14 -0800
A Large Angry SCM [off-list ref] wrote:

quoted

I disagree. If a command is install on a system, it's man 
pages/documentation should also be installed.

Well this isn't a huge issue.  One point you made though that struck
a chord is that many of the commands should probably not be in
section 1.

The trouble is that there's no other good place where to put them. But
perhaps we can get away with putting them to section 3? After all, Perl
installs documentation for its modules to section 3 as well.

quoted

I'm also not convinced that there are a "large number of commands [...] 
that should only ever be accessed as plumbing". I am convinced, however, 
that there are a number of relatively low level commands with poor user 
interfaces that are useful on their own.

Is there really a reason for a git user to access these from the
command line rather than a script:

commit-tree, diff-files, diff-index, diff-tree, for-each-ref,
hash-object, http-fetch, http-push, index-pack, local-fetch,
merge-base, merge-index, merge-octopus, merge-one-file, merge-ours,
merge-recur, merge-recursive, merge-recursive-old, merge-resolve,
merge-stupid, merge-tree, receive-pack, runstatus, ssh-fetch, ssh-pull,
ssh-push, ssh-upload, symbolic-ref, unpack-file, unpack-objects,
update-ref, upload-archive, upload-pack, upload-tar, write-tree

Not a complete list, and maybe i overlooked something in there
that is needed from the command line, but for the most part 
these could be installed somewhere other than the users path.

There certainly are reasons, but the situations where it is needed is
sufficiently rare; I think that's a reason good enough, when doing
something exotic like recovery of a corrupted repository it's ok to have
to do something slightly special to execute a lowlevel command.

It has been proposed for a long time that we put the "pure plumbing"
commands to /usr/libexec/git/ or somewhere there (some say /usr/libexec/
is obsolete), and I think it would be a great move.  Note that nowadays
the transition needs to be done carefully because of backwards
compatibility.


BTW, I've finally found a fine example of situation parallel to Git:
TeX!  There are the core TeX commands (plumbing) and plain TeX (basic
porcelain) on top of that as well as a bunch of other macro sets (other
porcelains). Now I need to dig out The TeXbook from wherever I've put it
to see how did Knuth deal with it, documentation-wise.

-- 
				Petr "Pasky" Baudis
Stuff: http://pasky.or.cz/
The meaning of Stonehenge in Traflamadorian, when viewed from above, is:
"Replacement part being rushed with all possible speed."

Joshua N Pritikin wrote:

On Sun, Nov 19, 2006 at 07:13:08PM +0100, Petr Baudis wrote:

quoted

BTW, I've finally found a fine example of situation parallel to Git:
TeX!  There are the core TeX commands (plumbing) and plain TeX (basic
porcelain) on top of that as well as a bunch of other macro sets (other
porcelains). Now I need to dig out The TeXbook from wherever I've put it
to see how did Knuth deal with it, documentation-wise.

Gahh! Please don't use TeX as an example. As far as I know, TeX doesn't 
offer lexical scope. 

It offers grouping.

Hence, action-at-a-distance is commonplace which  
makes program execution extremely difficult for mere mortals to 
predict. I am constantly amazed at popularity of TeX, in spite of its 
grave deficiencies. Perhaps there isn't a good alternative yet.

TeX (even plain TeX) is like assembler of programming languages. One does
usually use one of the TeX macros sets, like LaTeX, ConTeXt or texinfo.
-- 
Jakub Narebski
Warsaw, Poland
ShadeHawk on #git

On Sun, Nov 19, 2006 at 07:13:08PM +0100, Petr Baudis wrote:

BTW, I've finally found a fine example of situation parallel to Git:
TeX!  There are the core TeX commands (plumbing) and plain TeX (basic
porcelain) on top of that as well as a bunch of other macro sets (other
porcelains). Now I need to dig out The TeXbook from wherever I've put it
to see how did Knuth deal with it, documentation-wise.

Gahh! Please don't use TeX as an example. As far as I know, TeX doesn't 
offer lexical scope. Hence, action-at-a-distance is commonplace which 
makes program execution extremely difficult for mere mortals to 
predict. I am constantly amazed at popularity of TeX, in spite of its 
grave deficiencies. Perhaps there isn't a good alternative yet.