Rough start...

[Paul W. Frields]

On Sun, 2004-08-29 at 08:16, D at 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