Date: Tue, 24 Aug 1999 18:06:38 +0100 From: Nik Clayton <nik@freebsd.org> To: doc@freebsd.org Subject: ToDo Message-ID: <19990824180638.A78397@kilt.nothing-going-on.org>
next in thread | raw e-mail | index | archive | help
Folks,
I thought various people might like to see my current ToDo list for
the doc/ tree over the next 30 days or so. Partly to get an idea of
what's coming up (or might be coming up, assuming it's not contentious)
and partly so that interested parties can stick their hands in the air
and say that they'd like to do it. Most of the stuff is fairly routine,
but if anyone wants to get their hands dirty they're more than welcome
to take on one or more of these tasks.
* The FAQ
The FAQ has now been converted to DocBook, but it's a stop-gap conversion
only. The conversion process 'cheats', and leaves a lot of
<emphasis remap=tt>...</emphasis>
lying around the place. It also gets some things wrong, assuming that
anything in ALL CAPS is an <acronym>, and that anything that contains an
'@' sign is an e-mail address (amongst many others).
What it needs is someone to go through it, line by line, and correct all
the markup. It is imperative that this is done without making any
whitespace changes, so that it is as easy as possible for translators to
follow. If possible, you should try and use automated tools to do the
changes, and document how you did them. For example, if you can use a
simple search and replace, or some Perl, or some Emacs Lisp to make
a change, document how you did it, so that the translation teams can use
the same approach.
Related to this, the FAQ has stagnated over time -- some of the information
in there is undoubtedly wrong, or out of date. Since you're going to be
looking at each line of the FAQ anyway, it would be helpful if you could
keep notes of anything that looks like it needs to be updated, so that the
FAQ maintainers can jump on it.
* The articles
The articles in doc/en*/articles/* are all marked up as <book> rather
than <article>, and they use the DocBook 3.0 DTD, rather than the FreeBSD
3.1 based extension. These should be converted to <article>, and use the
FreeBSD DTD. Along the way you probably want to take advantage of the
&man.xxx.n; entities.
* The Device Driver Writer's Guide
This is in doc/en*/tutorials/ddwg, and hasn't yet been converted to DocBook.
I'm in two minds whether or not it should be. This is because the
information in the guide is very out of date, and Jeroen Ruigrok is working
on a new one that's up to date. I'm not sure that the effort of converting
it to DocBook is worth the usefulness of the information in the guide.
I'm more than welcome to be corrected on this, if people actually find
the guide useful.
* The Pedantic PPP Primer
This is in doc/en*/tutorials/ppp, and hasn't been converted to DocBook.
This one probably should be converted to DocBook, but someone more
familiar than I am with PPP should look it over and see how much of the
information in it is still appropriate. It may be that the PPP
information in the Handbook is more correct, or it may be that we're
better off updating the information in the Handbook from the Primer.
Or, it might be a better decision to keep the primer as well. I don't
know.
If we do decide to keep the primer it should probably be converted to
a DocBook <book>, rather than an <article> (because of its size), and
the natural place for it to live would be doc/en*/books/ppp-primer/.
* Problems with the Japanese PS and PDF output
I am dismayed that Postscript and PDF output from the Japanese
documentation is not generated properly. I'm no TeXnician, so all I could
do is act as a go-between the Japanese Documentation Project and anyone
with the appropriate TeX experience. If someone else wants to take this
on, please step up to the plate.
There are other tasks as well (for example, bringing in the French
translations) but I plan on definitely handling those myself, because I've
been working with the appropriate people for some time.
Hope that's informative. As I say, if anyone wants to nab one of these
tasks for themselves, please say so.
N
--
[intentional self-reference] can be easily accommodated using a blessed,
non-self-referential dummy head-node whose own object destructor severs
the links.
-- Tom Christiansen in <375143b5@cs.colorado.edu>
To Unsubscribe: send mail to majordomo@FreeBSD.org
with "unsubscribe freebsd-doc" in the body of the message
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?19990824180638.A78397>