From: Michael J Gruber <michaeljgruber+gmane@fastmail.fm>
To: git@vger.kernel.org
Subject: Suggestion: doc restructuring [was: Re: Considering teaching plumbing to users harmful]
Date: Fri, 18 Jul 2008 12:14:27 +0200 [thread overview]
Message-ID: <48806D03.30603@fastmail.fm> (raw)
In-Reply-To: <alpine.DEB.1.00.0807161804400.8950@racer>
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? ;)
next prev parent reply other threads:[~2008-07-18 10:15 UTC|newest]
Thread overview: 114+ messages / expand[flat|nested] mbox.gz Atom feed top
2008-07-16 17:21 Considering teaching plumbing to users harmful Johannes Schindelin
2008-07-16 17:50 ` Jesper Eskilson
2008-07-16 18:14 ` Johannes Schindelin
2008-07-16 18:19 ` Jesper Eskilson
2008-07-16 18:27 ` Johannes Schindelin
2008-07-16 17:53 ` Avery Pennarun
2008-07-16 18:12 ` Johannes Schindelin
2008-07-16 18:35 ` Avery Pennarun
2008-07-16 20:13 ` Theodore Tso
2008-07-16 21:53 ` Daniel Barkalow
2008-07-17 11:18 ` David Kastrup
2008-07-17 15:52 ` Jakub Narebski
2008-07-17 16:05 ` David Kastrup
2008-07-17 16:18 ` Subversion's do-everything-via-copying paradigm ( was RE: Re: Considering teaching plumbing to users harmful) Craig L. Ching
2008-07-17 21:05 ` David Kastrup
2008-07-17 22:06 ` Craig L. Ching
2008-07-17 22:07 ` Avery Pennarun
2008-07-17 22:11 ` Junio C Hamano
2008-07-17 20:04 ` Considering teaching plumbing to users harmful Jakub Narebski
2008-07-17 20:12 ` Kevin Ballard
2008-07-17 20:26 ` Petr Baudis
2008-07-17 20:40 ` Kevin Ballard
2008-07-17 21:03 ` Jakub Narebski
2008-07-17 21:10 ` Kevin Ballard
2008-07-17 20:34 ` Jakub Narebski
2008-07-17 20:42 ` Kevin Ballard
2008-07-17 20:15 ` Kevin Ballard
2008-07-17 21:02 ` David Kastrup
2008-07-17 22:32 ` Robin Rosenberg
2008-07-18 7:41 ` Dmitry Potapov
2008-07-17 16:11 ` Subversion is actually not so simple (was RE: Considering teaching plumbing to users harmful) Craig L. Ching
2008-07-17 17:37 ` Jakub Narebski
2008-07-17 19:00 ` Considering teaching plumbing to users harmful Daniel Barkalow
2008-07-16 18:18 ` Junio C Hamano
2008-07-16 18:51 ` Avery Pennarun
2008-07-16 18:59 ` Petr Baudis
2008-07-16 19:22 ` Avery Pennarun
2008-07-16 19:09 ` Junio C Hamano
2008-07-16 19:29 ` Avery Pennarun
2008-07-16 19:34 ` Junio C Hamano
2008-07-16 19:46 ` Avery Pennarun
2008-07-16 20:12 ` Junio C Hamano
2008-07-16 22:32 ` Theodore Tso
2008-07-16 22:41 ` Junio C Hamano
2008-07-16 22:53 ` Sean Kelley
2008-07-16 23:17 ` Nigel Magnay
2008-07-17 3:21 ` Stephen Sinclair
2008-07-18 17:02 ` Ping Yin
2008-07-16 22:24 ` Dmitry Potapov
2008-07-16 22:28 ` Johannes Schindelin
2008-07-16 22:49 ` Theodore Tso
2008-07-17 0:25 ` Johannes Schindelin
2008-07-17 2:47 ` Theodore Tso
2008-07-17 14:21 ` Craig L. Ching
2008-07-17 14:51 ` Petr Baudis
2008-07-17 15:57 ` J. Bruce Fields
2008-07-16 21:16 ` david
2008-07-16 21:59 ` Dmitry Potapov
2008-07-16 20:23 ` Stephen R. van den Berg
2008-07-16 20:27 ` Nicolas Pitre
2008-07-16 20:51 ` Junio C Hamano
2008-07-16 23:05 ` Johannes Schindelin
2008-07-16 23:40 ` Junio C Hamano
2008-07-17 0:02 ` Johannes Schindelin
2008-07-17 6:53 ` Junio C Hamano
2008-07-17 15:55 ` J. Bruce Fields
2008-07-17 16:03 ` Karl Hasselström
2008-07-17 18:16 ` Johannes Schindelin
2008-07-17 18:29 ` Junio C Hamano
2008-07-17 18:43 ` Johannes Schindelin
2008-07-17 19:10 ` Junio C Hamano
2008-07-18 14:35 ` J. Bruce Fields
2008-07-18 9:55 ` Addremove equivalent [was: Re: Considering teaching plumbing to users harmful] Michael J Gruber
2008-07-18 20:18 ` Jay Soffian
2008-07-18 23:03 ` Johannes Schindelin
2008-07-20 3:27 ` Addremove equivalent Junio C Hamano
2008-07-20 3:28 ` [PATCH 1/2] builtin-add.c: restructure the code for maintainability Junio C Hamano
2008-07-20 3:29 ` [PATCH 2/2] git-add -a: add all files Junio C Hamano
2008-07-20 3:32 ` [PATCH 3/2] git-add -a: tests Junio C Hamano
2008-07-20 4:20 ` [PATCH 2/2] git-add -a: add all files Tarmigan
2008-07-20 4:28 ` Tarmigan
2008-07-20 10:56 ` Johannes Schindelin
2008-07-20 12:45 ` Jay Soffian
2008-07-20 18:30 ` Junio C Hamano
2008-07-20 20:46 ` Lars Noschinski
2008-07-20 23:59 ` Jeff King
2008-07-21 0:06 ` Junio C Hamano
2008-07-21 0:17 ` Jeff King
2008-07-21 0:22 ` Jeff King
2008-07-21 2:11 ` Jay Soffian
2008-07-20 20:34 ` Sverre Rabbelier
2008-07-16 21:48 ` Considering teaching plumbing to users harmful Dmitry Potapov
2008-07-16 23:19 ` Johannes Schindelin
2008-07-16 22:09 ` Stephan Beyer
2008-07-16 23:22 ` Johannes Schindelin
2008-07-17 1:01 ` Stephan Beyer
2008-07-17 7:30 ` "Peter Valdemar Mørch (Lists)"
2008-07-17 12:38 ` Dmitry Potapov
2008-07-17 12:55 ` Theodore Tso
2008-07-17 13:35 ` Peter Valdemar Mørch
2008-07-17 14:26 ` Theodore Tso
2008-07-17 16:38 ` Junio C Hamano
2008-07-18 8:19 ` Andreas Ericsson
2008-07-18 18:26 ` Jeff King
2008-07-18 10:14 ` Michael J Gruber [this message]
2008-07-18 18:26 ` Suggestion: doc restructuring [was: Re: Considering teaching plumbing to users harmful] Jon Loeliger
2008-07-18 18:52 ` Craig L. Ching
2008-07-18 19:50 ` Suggestion: doc restructuring Junio C Hamano
2008-07-19 1:19 ` Suggestion: doc restructuring [was: Re: Considering teaching plumbing to users harmful] Johannes Schindelin
2008-07-20 8:14 ` Suggestion: doc restructuring Junio C Hamano
2008-07-20 11:02 ` Johannes Schindelin
2008-07-21 6:41 ` Andreas Ericsson
2008-07-21 10:04 ` Johannes Schindelin
2008-07-21 16:22 ` Junio C Hamano
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
List information: http://vger.kernel.org/majordomo-info.html
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=48806D03.30603@fastmail.fm \
--to=michaeljgruber+gmane@fastmail.fm \
--cc=git@vger.kernel.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this public inbox
https://80x24.org/mirrors/git.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).