On Sun, 2004-08-29 at 08:16, D@7@k|N& wrote: > I've been doing some work on the hardening tutorial and I've gotten to > the point where I have a few questions. > > First of all, do I need to do anything to the bugzilla report to show > that work is actually being done on this guide? You could put your timeline and/or milestones in there for when you expect to have certain things done. See previous threads, and Tammy and Karsten's process documents, for more on that. > I've tried writing in emacs, and I feel like I'm fighting the program so > much that I haven't been able to write any of the actual tutorial. So, > I did some work in Kate, and am trying to back port it with the XML tags > to make it fit the model. I followed the steps in the Doc Guide for > setting up emacs, and I think I got it right, but tag completion, and > coloring, etc. doesn't seem to be really intuitive. I felt the same way when I started. Push through, and try working on something that is *not* your actual document, so you don't feel pressure about "getting things done," and are free to simply try the features out. I think it's probably too much for people to try to memorize the whole chart of Emacs/psgml key bindings in the Doc Guide. Here's what I did to start: 0. Spend a couple days avoiding all editors except Emacs, no matter *what* I was doing, FDP or other work. Spent an hour or so on the Emacs tutorial to learn some basic keystrokes -- only a few of which I've actually memorized, but just enough so that I'm not completely flailing 100% of the time. 1. Pull the .emacs stuff in the Doc Guide into my ~/.emacs file. 2. Download the CVS for fedora-docs, using the steps in the Doc Guide or on the front page of the FDP site. 3. Copy example-tutorial/ folder to foobar/ folder. 4. Open up foobar/example-tutorial-en.xml in Emacs. (A lot of times, I hit Alt+X, type "xml-mode" and hit ENTER to force XML mode, which makes some tag markup work better... do this as optional step 4B. I'm not sure if this is the "right" thing to do, but it stops psgml from acting strangely on tags that self-close, like <xref linkend="sn-some-target"/>.) 5. Hit Ctrl+C, Ctrl+P to parse the DTD stuff at the top. Colors should appear shortly thereafter. NOTE: Like you, I don't really feel this is "intuitive," but then, neither is :wq in vi, or hitting Alt+F4 to close a GUI application. They're just things you have to learn. After you use a step enough, it will be second nature to you. (Not being preachy, just matter o' fact. I've learned to accept that each time I learn a new keybinding in Emacs, it takes a few days of use to become habit. I can live with that!) 6. When writing a tag, hit Ctrl+C, < to open the tag, type the beginning of the tag, then TAB to autocomplete. I used this feature to discover a lot of other tags, but I try to stick mainly with the ones in the Doc Guide. If I find a situation not covered, I visit: <http://docbook.org/tdg/en/html/docbook.html> The ToC there has a list of tags with short summaries of what each is for. That's really helpful! 7. If you have to port in XML written elsewhere (I call that a "last resort," avoidable if you really spend some time with Emacs), make sure you have a DTD section at the top just like the example-tutorial. Parse DTD with Ctrl+C, Ctrl+P, then Ctrl+C Ctrl+Q to resculpt the indentation. This part can get ugly, which is why I prefer to just write in Emacs! > Anyhow, I've taken a look at the CVS stuff, and thought that the Install > Guide my be a good one to use as an example, but that looks like a WIP. > So, I took a look at the Doc Guide, and that's a little more complete. > The layout of the Doc Guide implies that each chapter should be a > separate document. Is this true? Or, if you build one monolithic > document, will the Makefile parse all of the info correctly so that the > different chapters break out into different pages? The only reason to have separate documents is if you are doing a truly long work, and the amount of content requires it. (It means chapters can be assigned separately, for instance.) The Installation Guide's a no-brainer for that; so is the Doc Guide. But for what we do, the FDP suggests that you stick with tutorials that can be completed by one person without too much hassle. If you think your hardening guide is going to be much longer than 6-8 sections of a few pages each, then you might be better off writing an outline and posting it to Bugzilla and the list, to solicit more writers. Our current (and very pressing) need for an Installation Guide seems to say to me that you may want to participate on that as your "initial" project, and then move on to this once you've cut your teeth there. That's just a suggestion, because it seems to me that security and hardening is a somewhat open-ended topic, while installation is somewhat self-limiting, and therefore easier to tackle first. A hardening tutorial (or even a larger Security Guide) is a great idea, I just question the priority. If you write a tutorial as an <article> as suggested in the Doc Guide, each first-level <section> will break out into a separate HTML page. Doing the "make html" just takes care of it. You only need to edit the DOCNAME of the document in the Makefile. > Finally, once I get documents complete, what's the best way to submit > stuff to my editor? CVS? Bugzilla? Email? What items should be > included in the submission? The best way to do it IMHO is to submit a tarball of the XML stuff to Bugzilla, e-mail the list (maybe CC the editor), and point to the bug. Or, if you have a private web site, you can use that to serve out the XML source, but make sure the site clearly marks the document as a draft that is not official. Typically, you will want to write your document in a subfolder of the fedora-docs/ folder you downloaded through CVS. For instance, I have a ~/fedora-docs/usb-hotplug-tutorial/ folder, which contains a Makefile and usb-hotplug-tutorial-en.xml, the XML source. Just tarball your document by sitting in the fedora-docs/ folder and: tar czf my-tutorial.tar.gz my-tutorial/ Then any editor can simply pop the tarball out into the fedora-docs/ folder and have it automagically work for building. > Thanks for hand-holding me right now. Once I get the hang of it, things > should be a little easier, and I should be a little more prolific. > After looking at the Doc Guide, writing in emacs/XML doesn't seem so > daunting, so hopefully that won't be as much of an issue as I continue. Believe me, I know JUST where you're standing now, I'm only a few feet away on the other side of the hedge row. I occasionally glimpse Karsten and Dave P., yonder over the hill. Sometimes they throw things. *BONK* -- Paul W. Frields, RHCE
