From Bugzilla Helper: User-Agent: Mozilla/5.0 Galeon/1.2.6 (X11; Linux i686; U;) Gecko/20020830 Description of problem: As a newbie to this, the usage of --bind seems a little cryptic until you know what it could be useful for. (It's not all that obvious if you're unfamiliar with it, despite how it might seem otherwise to experienced users.) Therefore I propose that the following example be added to the mount manpage to further illustrate the usage of --bind: <<"END" For example when setting up a chroot environment in which you want a /proc directory as well, you do : mount -o proc --bind /proc /mnt/chroot/proc END Version-Release number of selected component (if applicable): How reproducible: Always Steps to Reproduce: 1. read manpage 2. come away still confused :-) 3. run in circles, scream and shout 4. go ask someone in #redhat what good it is :-)
*grumble* you can see how confused this has gotten me... =8) make that mount -t proc --bind /proc /mnt/chroot/proc
-t fstype isn't necessary the rest I'll try to get in one of these days.
The man page says "mount --bind olddir newdir". That shouldn't require any more explanation. If it does, you may want to consider going back to the beginning. The man pages don't exist to explain "why", only "how". :)
(I realize that your response triggered somewhat of a rant on my part but please do read through it as some of it is entertaining, and the rest is quite pertinent to the problem at hand that I have with the current state of ALL the manpages.) this is a shortcoming insofar as I am concerned. I am NOT a unix wizard, a C++ guru or anyone with a long history of sysadminning. When someone comes online and asks questions about a certain command, they are invariably told to RTFM. Without useful examples so that you can actually SEE _how_ [your word, by the way] something is to be used, the usefulness of the command generally will escape most people. I re-iterate my request to add a short example on the useage of --bind to the mount manpage, as the 'description' is lacking in explanation of usage, and it is not clear HOW it would be useful. The only thing that IS clear from the manpage is "here's yet-another-command-line-option-I-have-no-use-for-since-I-don't-understand-what-good-it-is." This is the one thing that many schoolteachers fail in -- for example, explaining where and how you would find various math equations useful in your life. What's the difference between 'average' 'mean' and 'median' and when do you use each? If teachers don't take the time to explain WHY they might need to know it, kids'll never remember it. (much less be able to use it at a time when they might actually need to know it, later in life.) IMHO The manpages are inadequate, and need to be improved. The Info pages are a pale semblance of an alternative that DESPITE the "more info is available in the info pages" tripe, RARELY contain anything OTHER than the exact contents of the manpage one just looked at. 95% of the time, /usr/share/doc is no more helpful than the manpages, which are oftentimes COMPLETELY MISSING as well. Why are we bothering to include manpages and info pages if we aren't going to DO ANYTHING ABOUT MAKING THEM AS USEFUL AS WE WOULD LIKE TO PRETEND THEY ARE WHEN WE TELL NEWBIES TO GO _RTFM_? I have almost 18 years of experience with computers and I'm _skilled_ in grasping concepts that are unfamiliar to me, and *I* don't grok half this stuff because the FM's are so vague and so rarely have useful examples. (when the manpages exist at all in the first place) The Perl perldoc is THE quintessential example of well-done manuals (that are also getting continually improved and updated with each successive release of Perl). One could literally teach themselves to program in perl reading nothing but the perldocs. The Camel (Programming Perl by O'Reilly) is little more than a collation OF the perldocs. I'm sick of excuses as to why the manpages are good enough. They aren't. This is a SIMPLE change that A> Doesn't take a lot of bandwidth to store, B> EVERYONE benefits from, C> Can be propagated upstream so OTHER linux users can benefit, and D> helps to explain an obscure option to an often used command whose benefits would escape everyone but the most seasoned and experienced users -- who are THE LAST PEOPLE WHO NEED TO _READ_ the dang manpage to find out what it does and _how it's useful_! =8) for god's sake, it's only three lines of 80-column text we're talking about adding, here! :-) I don't understand the difficulty OR the reluctance to improve the product. Do you WANT people to _have_ to call technical support or use search engines or other online resources that take time and effort away from doing what they want to do when the manual that comes with the product you're selling could potentially be adequate enough ? =:-o I even went to the trouble of coming up with a _useful example_ that people will likely often use, with a good explanation of WHY they'd want to --bind, that is understandable almost immediately provided you know what chroot is for and when to use THAT. c'mon, have a heart. improve the planet. better documentation benefits everyone, and saves everyone else the time and trouble of explaining it to yet more newbies. :-)
Sorry. Talk to the upstream maintainers. I happen to agree with you, but don't have time to fix man pages like you want.
I would suggest that maybe the manpage in this instance be deprecated due to developer time constraints. But more seriously, an organized documentation review team that scours the docs provided in the rhl apps might be a good idea. The team could review docs and provide a patched versions that rolls up several useful changes in one shot. Patches to the manpages are accepted right? I can imagine having to do a crapload of individual 3 line manpage patches could become burdensome. But if there was an organized group of people that wanted to clean up manpages and infopages in a largescale way, providing perldoc like completeness...would that kind of effort from outside be acceptable? Perl is be a good example of an upstream project that takes very good care of documentation as a priority...its going to take a rather large cluestick to get other upstream maintainers to see the value of that much care in the manpage equivalent to perldoc. Having upstream maintainers incorporate community driven documentation enhancements would be nice...but in the meantime...it would also be pretty nice to have redhat accept patched manpages from the community as well.