Suggestion: doc restructuring [was: Re: Considering teaching plumbing to users harmful]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

 



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


P.S.: For me
porcellaine = artistic, fragile
plumbing = plain, robust
Which one would you choose for daily hard work? ;)

--
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

[Index of Archives]     [Linux Kernel Development]     [Gcc Help]     [IETF Annouce]     [DCCP]     [Netdev]     [Networking]     [Security]     [V4L]     [Bugtraq]     [Yosemite]     [MIPS Linux]     [ARM Linux]     [Linux Security]     [Linux RAID]     [Linux SCSI]     [Fedora Users]

  Powered by Linux