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.
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[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.
Will invalidate earlier attachment. Please look for the newest version at <http://docs.frields.org>.
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: <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/>
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 <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?) ;-)
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 <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.
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 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.
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 magic!
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 /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?
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. :-)
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.