From: Jon Loeliger <jdl@freescale.com>
Date: Fri, 18 Jul 2008 18:26:09 GMT
Subject: Re: Suggestion: doc restructuring [was: Re: Considering teaching plumbing to users harmful]
Message-ID: <4880E041.8070001@freescale.com>
In-Reply-To: <48806D03.30603@fastmail.fm>

Michael J Gruber wrote:
> Johannes Schindelin venit, vidit, dixit 16.07.2008 19:21:
> ...
>>
>> Am I the only one who deems teaching plumbing to users ("I like it 
>> raw!  So I teach it the same way!") harmful?
>>
>> Ciao,
>> Dscho "who is sad"
> 
> In an attempt at making not only Dscho happier I suggest a restructuring 
> of the man pages in the following way:
> 
> In each man page, put a note which says something like:
> "This is part of linkgit:gitplumbing[7]." and the like
> It should be in a prominent place, such as the last line of "DESCRIPTION".
> 
> gitplumbing[7] etc. pages should contain:
> - a definition of the respective term together with appropriate usage 
> advice (regular use/scripting..., "Let there be dragons.")
> - a list of commands like we have in git[1] right now
> 
> With the current situation, people don't look at git[1] in order to find 
> out what they're supposed to use. It's too long anyways, and could link 
> the above pages instead.
> 
> If there's enough interest/agreement I'd come up with a refactoring patch.
> 
> Michael

I'd like to throw my beef with the main Git man page
out there for consideration as well...

When I hit the man page, which I do on line quite frequently,
I usually use it as an index to get to the real, current man
page for a particular command.  (I am at git.kernel.org for
other reasons all the time, so it is convenient.)

The current sub-setting and organization is painful because
it doesn't have a comprehensive, linear, alphabetized list
of commands from which to select the real man page.  I never
know which "section" to find a given command.  Is it an
Ancillary "manipulator" command?  Or maybe just a "Manipulation"
command, or maybe an "Interrogation" command?  A "Helper"?

I always have to painfully search the page for it instead.

I'm not saying get rid of the Categorical organization.
I am saying, we need a first-page with a straight, alphabetized
command index somewhere easy and located conveniently.

Thanks for listening,
jdl