Bug 128952 - New tutorial submission: usb-hotplug-tutorial
New tutorial submission: usb-hotplug-tutorial
Status: CLOSED WONTFIX
Product: Fedora Documentation
Classification: Fedora
Component: docs-requests (Show other bugs)
devel
All Linux
medium Severity medium
: ---
: ---
Assigned To: Paul W. Frields
Stuart Ellis
: FutureFeature
Depends On:
Blocks:
  Show dependency treegraph
 
Reported: 2004-08-01 19:40 EDT by Paul W. Frields
Modified: 2009-07-07 00:08 EDT (History)
3 users (show)

See Also:
Fixed In Version:
Doc Type: Enhancement
Doc Text:
Story Points: ---
Clone Of:
Environment:
Last Closed: 2005-10-03 12:33:15 EDT
Type: ---
Regression: ---
Mount Type: ---
Documentation: ---
CRM:
Verified Versions:
Category: ---
oVirt Team: ---
RHEL 7.3 requirements from Atomic Host:
Cloudforms Team: ---


Attachments (Terms of Use)
Tarball of manual source (6.00 KB, application/x-tar)
2004-08-01 19:43 EDT, Paul W. Frields
no flags Details
Updated XML, representing 50% edit (approx. by line) (26.72 KB, text/plain)
2004-09-03 14:47 EDT, Karsten Wade
no flags Details
Patch represents 'diff -u' of my edited XML compared to Paul's original XML (19.86 KB, patch)
2004-09-03 14:49 EDT, Karsten Wade
no flags Details | Diff
New version: 0.5 (incorporates patches and add'l editing) (28.93 KB, text/plain)
2004-09-17 13:35 EDT, Paul W. Frields
no flags Details
My final edits to the 0.5 version of the usb-hotplug-tutorial (30.13 KB, text/plain)
2004-09-26 03:54 EDT, Karsten Wade
no flags Details
Patch to 0.5 version of the usb-hotplug-tutorial. (12.86 KB, patch)
2004-09-26 03:55 EDT, Karsten Wade
no flags Details | Diff
New version: 0.51 (30.66 KB, text/plain)
2004-10-06 09:49 EDT, Paul W. Frields
no flags Details
Patch from 0.5 to 0.51 (2.88 KB, patch)
2004-10-06 09:51 EDT, Paul W. Frields
no flags Details | Diff

  None (edit)
Description Paul W. Frields 2004-08-01 19:40:17 EDT
Additional info:

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.
Comment 1 Paul W. Frields 2004-08-01 19:43:43 EDT
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.
Comment 2 Bill Nottingham 2004-08-10 16:09:52 EDT
One issue is that with the addition of gnome-volume-manager and HAL in
FC3, updfstab is almost certain to go away.
Comment 3 Paul W. Frields 2004-08-10 17:04:40 EDT
Thanks for the info Bill. I will ensure these docs are marked clearly
for FC[12]. 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.
Comment 4 Paul W. Frields 2004-08-12 08:12:56 EDT
Will invalidate earlier attachment. Please look for the newest version
at <http://docs.frields.org>.
Comment 5 Paul W. Frields 2004-08-13 12:37:19 EDT
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! :-)
Comment 6 Paul W. Frields 2004-08-16 11:09:15 EDT
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/>.
Comment 7 Paul W. Frields 2004-08-25 19:58:29 EDT
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:
   <http://docs.frields.org/>
DocBook/XML source:
   <http://svn.frields.org/usb-hotplug-tutorial/>
Subversion checkout:
   <svn://svn.frields.org/fedora-docs/usb-hotplug-tutorial/>
Comment 8 Tammy Fox 2004-08-26 11:18:06 EDT
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.
Comment 9 Karsten Wade 2004-08-26 12:42:53 EDT
I'll take it; I should be able to get through to it by tomorrow (Friday).
Comment 10 Paul W. Frields 2004-08-26 21:33:31 EDT
One correction if you checkout via Subversion directly; the svn URL is
<svn://marilyn.frields.org/fedora-docs/usb-hotplug-tutorial/>. Really,
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
reference.

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?) ;-)
Comment 11 Karsten Wade 2004-08-31 10:53:43 EDT
Quick update -- I'm working on editing this, I intend to get it done
today (Tuesday 31 August). :)
Comment 12 Karsten Wade 2004-09-03 14:46:01 EDT
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
<para/> block.

* Usage of <example/> to surround a <screen/> that is referred to in
the text.

* 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.
Comment 13 Karsten Wade 2004-09-03 14:47:23 EDT
Created attachment 103445 [details]
Updated XML, representing 50% edit (approx. by line)
Comment 14 Karsten Wade 2004-09-03 14:49:03 EDT
Created attachment 103446 [details]
Patch represents 'diff -u' of my edited XML compared to Paul's original XML
Comment 15 Paul W. Frields 2004-09-17 13:35:38 EDT
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.
Comment 16 Karsten Wade 2004-09-26 03:53:21 EDT
Reassigning to Paul to confirm my edits.  I embedded some comments to
explain myself in several locations; you can remove these before
publication.

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
will catch.
Comment 17 Karsten Wade 2004-09-26 03:54:12 EDT
Created attachment 104330 [details]
My final edits to the 0.5 version of the usb-hotplug-tutorial
Comment 18 Karsten Wade 2004-09-26 03:55:21 EDT
Created attachment 104331 [details]
Patch to 0.5 version of the usb-hotplug-tutorial.

As mentioned, this patch looks big because of paragraph filling.
Comment 19 Tammy Fox 2004-09-30 10:55:53 EDT
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.
Comment 20 Paul W. Frields 2004-10-06 09:49:31 EDT
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
magic!
Comment 21 Paul W. Frields 2004-10-06 09:51:01 EDT
Created attachment 104836 [details]
Patch from 0.5 to 0.51

Patch from 0.5, which included all KWade's changes, to 0.51.
Comment 22 Tammy Fox 2004-10-14 10:35:45 EDT
I'm reading this today. Sorry for the delay.
Comment 23 Tammy Fox 2004-10-14 21:44:09 EDT
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
/dev/usbdrive, correct?

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
or /etc/updfstab.conf.default?
Comment 24 Paul W. Frields 2004-10-14 22:34:07 EDT
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
trees.

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. :-)
Comment 25 Tammy Fox 2004-10-15 17:12:24 EDT
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.
Comment 26 Paul W. Frields 2005-06-24 16:33:26 EDT
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;. 
Comment 27 Paul W. Frields 2005-10-03 12:33:15 EDT
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.
Comment 28 eric@christensenplace.us 2009-07-07 00:08:19 EDT
Ticket moved to allow products to be removed from BZ.

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