Re: EDU-HOW TO Revisions

[Roger Dingledine <arma@mit.edu>]

> I will post revisions to my first notes.  But first I have a few questions.
> 1) I am currently doing this as a text file.  I figure it will be easier to
> put into the proper format later.  Any ideas on how to make it more readable.
> 2) Any ideas on what the format should be?

Just to put another spoke in the wheel, I would recommend doing it in html
for a while, because that's simplest and most directly useful to readers.
(You can put it on a webpage, and direct people there.) Eventually, if it's
a howto it should be in the sgml format specified by the Linux Doc Project.
I believe Doug has some direct experience reformatting documents to match
the ldp's sgml format, from the cpah (http://www.seul.org/pub/howto/cpah.html)
that he wrote for us a while ago.

Somebody mentioned XML -- it's a nice idea, and yes, in theory it's very
flexible, but I haven't seen any easy editors out there. Certainly from what
I've seen you'd have to write a dtd (or decide upon a prewritten one, in
which case you're pretty close to picking sgmltools anyway), and it would
generally be a mess compared to say notepad.

I guess my basic point is that switching between formats shouldn't be too
bad, so use a format you're comfortable with that can present enough
information.

> 3) Any ideas on keeping track of revisions, etc?

You can use the cvs repository on cran if you like. Do you have a seul
account, and/or would you like one? This would allow multiple authors
to work together well, and coincidentally it would put the current
versions available on the seul website.

Alternatively, you can simply use rcs on your own, if you're going to be the
only author.

Thanks,
--Roger