From: Andreas Ericsson <ae@op5.se>
Date: Mon, 21 Jul 2008 06:41:44 GMT
Subject: Re: Suggestion: doc restructuring
Message-ID: <48842FA8.5070309@op5.se>
In-Reply-To: <7vk5fhc6qo.fsf@gitster.siamese.dyndns.org>

Junio C Hamano wrote:
> Johannes Schindelin <Johannes.Schindelin@gmx.de> writes:
> 
>> So what I really would like is this: leave the plumbing pages as they are, 
>> but enhance those pages that users (especially new ones) are likely to see 
>> most often.
> 
> Regarding the original "do we want to ever teach plumbing to new users?"
> issue, I suspect that, with sufficient enhancement to Porcelain, we might
> be able to reach a point where end users can work without ever touching a
> single plumbing command at all.
> 
> 	Side note, that was why I suggested us to first think about use
> 	cases in our every day work that we still need to resort to the
> 	plumbing, so that we can identify what that enhancement would
> 	consist of.
> 

Half a year or so ago, there were some mailings to the list along the lines
of "what git commands do you use?", using the bash history and a shell
oneliner to dig out some crude intel. Here's mine:
cat ~/.bash_history | grep ^git | awk '{ print $2 }' | grep -v '^--' | sort | uniq --count | sort -nr
     29 status
     26 diff
     19 show
     17 log
     11 branch
      9 grep
      8 pull
      8 commit
      7 fetch
      7 describe
      6 rev-list
      5 help
      4 push
      4 merge
      3 reset
      3 config
      3 clone
      3 add
      2 rev-parse
      2 format-patch
      1 stash
      1 checkout
      1 apply

To be fair, rev-parse and rev-list are on there due to some oneline scripting.
I needed to move commits from several different branches to a single place,
filtering on author.

> When we reach that point, we might want to restructure the documentation
> into two volumes.  One volume for end-users who exclusively use the stock
> git Porcelain, and another that describes plumbing commands for Porcelain
> writers.
> 
> Perhaps move the plumbing documentation to section 3; just like Perl has
> DBI.3pm and friends there, /usr/share/man/man3/git-cat-file.3git will
> describe what scripts can do with the command.

I like this idea, although newbie users may not know what section 3 is for.

-- 
Andreas Ericsson                   andreas.ericsson@op5.se
OP5 AB                             www.op5.se
Tel: +46 8-230225                  Fax: +46 8-230231