Bug 83982 - RFE: example usage for --bind in mount manpage
Summary: RFE: example usage for --bind in mount manpage
Keywords:
Status: CLOSED WONTFIX
Alias: None
Product: Red Hat Linux
Classification: Retired
Component: mount
Version: 8.0
Hardware: All
OS: Linux
low
medium
Target Milestone: ---
Assignee: Elliot Lee
QA Contact: Brian Brock
URL:
Whiteboard:
Depends On:
Blocks:
TreeView+ depends on / blocked
 
Reported: 2003-02-10 18:04 UTC by Scott R. Godin
Modified: 2007-03-27 04:00 UTC (History)
0 users

Fixed In Version:
Doc Type: Enhancement
Doc Text:
Clone Of:
Environment:
Last Closed: 2003-08-14 14:50:57 UTC
Embargoed:


Attachments (Terms of Use)

Description Scott R. Godin 2003-02-10 18:04:21 UTC
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 :-)

Comment 1 Scott R. Godin 2003-02-10 18:10:57 UTC
*grumble* you can see how confused this has gotten me... =8)

make that 

    mount -t proc --bind /proc /mnt/chroot/proc

Comment 2 Elliot Lee 2003-07-30 20:14:19 UTC
-t fstype isn't necessary

the rest I'll try to get in one of these days.

Comment 3 Elliot Lee 2003-08-13 21:03:17 UTC
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". :) 

Comment 4 Scott R. Godin 2003-08-14 05:31:17 UTC
(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. :-)

Comment 5 Elliot Lee 2003-08-14 14:50:57 UTC
Sorry. Talk to the upstream maintainers. I happen to agree with you, but don't have time to 
fix man pages like you want.

Comment 6 Jef Spaleta 2003-08-14 20:25:00 UTC
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. 


Note You need to log in before you can comment on or make changes to this bug.