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
--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html
