On Sun, 2004-08-29 at 21:30, Paul W. Frields wrote:
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.
Unfortunately, I'm not that organized, so I don't know when I will
actually have time to work on this. So, an actual timeline might be
tough. This weekend has been a great opportunity to get familiar with
the tools, and start getting some content together.
> 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
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.
No worries. Alt+F4 happens to not be that elusive for me; I've been hit
with enough adware/popups on my windows box that it's familiar.
I've learned to accept that each time I learn a new keybinding in
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:
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!
Well, that was the thing. The XML in general was killing me, and I
wanted to get some basic content put together. SO I just wrote out the
content in kate, and then went back and added the XML tags, modeled
after the doc-guide.
> 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.
So, this should more or less be one monolithic document.
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.
Verbosity, and scope of content was never an issue for me. I used to
handwrite write 1500 word, open book, essays in an hour (in class) when
I was in high school ( a loooong time ago ;). I think that a document
of the magnitude you describe would be no problem for one person if the
content is driving the document.
Our current (and very pressing) need for an Installation Guide seems
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.
How do I do that? How do I know what needs to be done, so that I'm not
That's just a suggestion, because it seems to me that security
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.
True. However, being a security engineer, I tend to place a great deal
of value on security and it's implementation.
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 figured that out, once I got things in order and was able to get
the 'make html' work.
> 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*
I'll post my outline to the bug, and maybe people will have some
suggestions on sections to add. My focus for this doc, has been to use
Fedora "native" utilities to accomplish the task at hand (securing your
system). Introducing third party tools would increase the scope of the
document, and may require additional authors, but I doubt it. ;)
I already feel like I'm getting used to the tags, and having written
HTML for almost 7 years, I should be able to slip right into it.
Thanks again for the tips and the list's patience. ;)
<== dataking's pgp ==>
9287 3334 03E4 965E 0D2D F7CA A6E7 407C 1558 A263