From owner-freebsd-doc Thu Mar 26 14:35:46 1998 Return-Path: Received: (from majordom@localhost) by hub.freebsd.org (8.8.8/8.8.8) id OAA03622 for freebsd-doc-outgoing; Thu, 26 Mar 1998 14:35:46 -0800 (PST) (envelope-from owner-freebsd-doc@FreeBSD.ORG) Received: from nothing-going-on.demon.co.uk (nothing-going-on.demon.co.uk [193.237.89.66]) by hub.freebsd.org (8.8.8/8.8.8) with ESMTP id OAA03590 for ; Thu, 26 Mar 1998 14:35:30 -0800 (PST) (envelope-from nik@nothing-going-on.demon.co.uk) Received: (from nik@localhost) by nothing-going-on.demon.co.uk (8.8.8/8.8.8) id WAA17325; Thu, 26 Mar 1998 22:12:44 GMT (envelope-from nik) Message-ID: <19980326221244.51275@nothing-going-on.org> Date: Thu, 26 Mar 1998 22:12:44 +0000 From: Nik Clayton To: Studded , Docs Team Subject: Re: Doc projects and status References: <3519829A.E3A44CC6@dal.net> Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii X-Mailer: Mutt 0.89.1i In-Reply-To: <3519829A.E3A44CC6@dal.net>; from Studded on Wed, Mar 25, 1998 at 02:18:02PM -0800 Organization: Nik at home, where there's nothing going on Sender: owner-freebsd-doc@FreeBSD.ORG Precedence: bulk X-Loop: FreeBSD.org 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