Red Hat Bugzilla – Bug 128952
New tutorial submission: usb-hotplug-tutorial
Last modified: 2009-07-07 00:08:19 EDT
Standard DocBook XML format. This document describes the steps to add
an unrecognized hotplug storage device to Fedora Core by editing
/etc/updfstab.conf.*, /etc/security/console.perms, and running updfstab.
Created attachment 102345 [details]
Tarball of manual source
This is a tarball of the XML source. It is suitable for extraction into the
fedora-docs/ folder created by the standard Docs Project CVS checkout.
One issue is that with the addition of gnome-volume-manager and HAL in
FC3, updfstab is almost certain to go away.
Thanks for the info Bill. I will ensure these docs are marked clearly
for FC. I'll also try and keep up with g-v-m and HAL so the
document can be polished for FC3 if there's any need for it at that point.
Will invalidate earlier attachment. Please look for the newest version
Dave Parsons is checking for accuracy and readability. So far he has
delivered a detailed list of issues that I am going to address over
the weekend. I've removed the block on the "ready for publishing"
tracker and I see Tammy added the block for the "in progress" tracker.
Thanks for cleaning the place up a bit! :-)
Made a large number of changes thanks to Dave's comments. The newest
version is now available via anonymous access to my Subversion server
at <svn://svn.frields.org/fedora-docs/>. Instructions for download are
available at <http://docs.frields.org/>.
Name has changed to usb-hotplug-tutorial to reflect true scope. I
could really use some help with this one, namely someone to proofread,
tell me if parts are unclear. My original tester had to bail for lack
of time. You can find the following:
HTML nightly build:
I am assigning this to Karsten to at least give you an editor to proof
it, check for correct DocBook, etc. Karsten, are you able to test it
as well? If not, let me know and we'll try to find someone else to
test it. After you are finished editing it, assign it back to me.
I'll take it; I should be able to get through to it by tomorrow (Friday).
One correction if you checkout via Subversion directly; the svn URL is
though, you might as well just use ViewCVS at the HTTP URL. I'm
recording the svn URL here just as a reminder to myself for later
I made some changes earlier tonight, and will leave it alone until I
hear back from you. Thanks a lot, Karsten; I hope it measures up well
enough against your expectations. (Wait a minute, is that a good thing
or not?) ;-)
Quick update -- I'm working on editing this, I intend to get it done
today (Tuesday 31 August). :)
As discussed in private email with Paul, I'm giving back his tutorial
with only 50% edited. There are some language/writing habits I want
to draw his attention to, and I think a read of this new version next
to a diff will demonstrate that to him.
Overall, the writing is very good. It is clear, focused, and concise.
There are some usage habits that Paul has recently been reading about
in the Elements of Style, and like a Psych 101 course where you
discover you are insane ... some have creeped in. I'm going to let
Paul finish the rewrite.
Other changes include:
* Reduction of <screen/> blocks; many usages were fine inline in a
* Usage of <example/> to surround a <screen/> that is referred to in
* Some didactic detail addition in the text.
* Tag changes should be self-evident for their reason.
See following attachments -- updated XML and a diff -u.
Reassigning to Paul for a quick rewrite; then reassign it to me and I
will do a final edit/approval.
Created attachment 103445 [details]
Updated XML, representing 50% edit (approx. by line)
Created attachment 103446 [details]
Patch represents 'diff -u' of my edited XML compared to Paul's original XML
Created attachment 103958 [details]
New version: 0.5 (incorporates patches and add'l editing)
I believe this new version addresses the changes Karsten made. I tried to
follow the style through the rest of the document.
Reassigning to Paul to confirm my edits. I embedded some comments to
explain myself in several locations; you can remove these before
I'll add in the corrected XML and a patch for convenient viewing. It
looks like a big patch because sgml-fill-paragraph rearranges so much
when just one thing is changed. In other words, a single edit becomes
a multi-line diff. There were _very_ few changes, most of them XML
changes. Content changes were mainly typo, spelling, or wordsmithing
on a small scale.
In my judgment, this tutorial is ready for publication. The voice is
good, consistent, and concise. The technical details were accurate,
afaict without a pendrive to test with. :) The principals are all
sound, and the methodology was consistent and well-thought out (/me
detects many painful hours of trial and error to gain this knowledge).
Thanks for a great tutorial, keep 'em coming. :)
When Paul has checked my edits and settled all questions with me,
reassign to Tammy for:
1) Final check-before-Web publication.
2) Addition to fedora-docs/ CVS module.
3) Addition to fedora/docs site.
I can do 2) and 3) now, but I really want to see the results of 1)
from Tammy. I'm not practiced on that edit, and I'm curious what she
Created attachment 104330 [details]
My final edits to the 0.5 version of the usb-hotplug-tutorial
Created attachment 104331 [details]
Patch to 0.5 version of the usb-hotplug-tutorial.
As mentioned, this patch looks big because of paragraph filling.
Paul, let me know when you are ready for me to do the final check. I
have time this weekend if you are ready, but no rush.
Created attachment 104835 [details]
New version: 0.51
This new version represents all KWade's changes, plus a few extra to bring the
document in line with his previous edits. He missed a couple of <command> tags
that should have been <computeroutput> so I fixed them in accordance with his
guidance. I added one tiny section on partition parsing to head off problems
that Dave Pawson reported. I'll also include a patch in the next attachment to
highlight the changes.
Tammy, this is now ready as far as I'm concerned. Please feel free to work your
Created attachment 104836 [details]
Patch from 0.5 to 0.51
Patch from 0.5, which included all KWade's changes, to 0.51.
I'm reading this today. Sorry for the delay.
I committed your tutorial in the fedora-docs CVS module before I made
my edits, and then committed again with my edits so you can read the diff.
Please review them and let me know if you are OK with them. If so,
I'll add them to the website. A few changes I made that I want to
point out to make sure they are correct:
1. In the first orderedlist in the Summary section, the last listitem
reads " The hotplug system runs updfstab to update the /etc/fstab
file with an entry for /etc/usbdrive..." I think you meant
2. Titles should be initial capped. This should be in the style guide
once we finalize it.
3. I moved the umount caution up right after the step to remove the
device so the reader reads it before unplugging.
One general question: Why is it better to create a
/etc/updfstab.conf.custom file instead of modifying /etc/updfstab.conf
Thanks for the extra work; your changes all look good for me. One tiny
niggling change: At the top, the article <subtitle> should probably
use "&FC;" instead of "Fedora Core," right?
1. You are correct.
2. Roger that!
3. This is sensible and good. :-)
Hmm. Maybe it's not better per se. Here's how I reasoned it: Many
facilities use a foobar.d/ "drop directory" in which files can be
added or removed with packages, and simply picked up by the facility
in question. I figured that it was possible that one day, &FC; might
have an /etc/updfstab.d/ folder into which these types of files would
be written when a new device was plugged in. Of course, now that this
facility has been superseded, I guess I was missing the forest for the
The method I outline uses that type of process, in any case, but it's
certainly not a requirement per se. Maybe the doc should point out
that either is acceptable. I also like this process purely from the
standpoint of not mucking around with a preset file that doesn't
require it. I also like it because it's in the "tradition" of drop
directories, as much as possible, and just seems more modular to me.
It would be wrong of me, though, to pretend it's really a big deal in
either way. If you feel having that extra step is too -- I don't know,
precious? -- then by all means remove it. :-)
You are correct about the entity usage. I fixed it in CVS.
It seems like an extra step to me in a process that doesn't need extra
steps, but giving the reader the option to choose which file to modify
is not necessary either. Let me think about it.
Status update ping. Given the fact that FC2 has moved to Legacy at this point,
this document should be subjected to the process for any legacy docs.
(Discussion can ensue on fedora-docs-list if needed.) CVS updated to reflect
official &LEGACYNOTICE; and &BUG-NUM;.
Closing for lack of activity. Once a FLP process is in place, will see if this
doc needs to be moved; until then, retaining in CVS per normal.
Ticket moved to allow products to be removed from BZ.