Date: Thu, 26 Mar 1998 22:12:44 +0000 From: Nik Clayton <nik@nothing-going-on.demon.co.uk> To: Studded <Studded@dal.net>, Docs Team <FreeBSD-Doc@FreeBSD.ORG> Subject: Re: Doc projects and status Message-ID: <19980326221244.51275@nothing-going-on.org> In-Reply-To: <3519829A.E3A44CC6@dal.net>; from Studded on Wed, Mar 25, 1998 at 02:18:02PM -0800 References: <Pine.BSF.3.95q.980319185443.316I-100000@barnowl.roost.net> <3519829A.E3A44CC6@dal.net>
next in thread | previous in thread | raw e-mail | index | archive | help
How do,
Doug -- do you want to keep an archive of these messages. I'll commit
my changes to the DocProj pages sometime on Monday. When some firm ideas
come out of this discussion, you could write them up for inclusion on
the page. . .
On Wed, Mar 25, 1998 at 02:18:02PM -0800, Studded wrote:
> 1. Initiate discussion about the format for the final form of the docs.
> I'd like to see a unified document (FAQ + Handbook + Tutorials + new
> material) with a consistent style and extensive cross-indexing. I'd also
> like to see a front end for this that takes the form of a "How Do I?"
> index. That's just my view, but I think there's general consensus on the
> first bit anyway.
Yep.
> 2. Go through what we have with a fine-toothed comb prior to the docbook
> conversion so that what's on the page now is as accurate and timely as
> possible. This should be an ongoing "mid-term" goal that just about
> anyone can participate in. This increases the value of the documentation
> we have, and small progress towards the final goal can be made while
> we're discussing the format of that final product.
This can happen at the same time as the DocBook conversion. There's only
one caveat -- changes made to the Handbook fall in to two categories.
(1) changes to the actual content (the copy) and (2) changes to the
markup of the documentation.
Any single commit to the Handbook commits either copy changes or markup
changes, but not both.
This is very useful to the Japanese translators (and the new Spanish)
translator, because it lets them see what's changed, without needing
to check whether copy and markup changes have been combined.
It's handy for me doing the DocBook conversion for the same reason.
> 3. Nik's monumental docbook conversion project. He should be the one who
> fills in the blanks on this. This is a more long-term goal although work
> is progressing.
It could be quite a short term goal, if someone with some TeX knowledge
could come forward.
Basically, we need to make ports out of the all the different TeX macro
packages that are used by the JadeTeX macro set, and then we need to
make a port of the JadeTeX macro set, and make that port dependent on all
the others.
I'm (very slowly) getting there, but I need to find out a lot more about
TeX first.
If no one steps forward to help out with this, what I'll probably do is
1. Tag the CVS tree around the middle of next week.
2. Start the conversion.
3. *commit* the JadeTeX stuff to the -doc distribution. This at least
gives us enough to make the conversion process reasonably self
hosting.
Hopefully the sheer ugliness of this approach will encourage someone
to then step forward and help out.
> 4. Finalize the format of the end product and begin moving toward that
> goal.
Format? Output format or content?
N
--
Work: nik@iii.co.uk | FreeBSD + Perl + Apache
Rest: nik@nothing-going-on.demon.co.uk | Remind me again why we need
Play: nik@freebsd.org | Microsoft?
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?19980326221244.51275>