From owner-freebsd-doc Wed Mar 11 07:27:05 1998 Return-Path: Received: (from majordom@localhost) by hub.freebsd.org (8.8.8/8.8.8) id HAA24336 for freebsd-doc-outgoing; Wed, 11 Mar 1998 07:27:05 -0800 (PST) (envelope-from owner-freebsd-doc@FreeBSD.ORG) Received: from tyree.iii.co.uk (tyree.iii.co.uk [195.89.149.230]) by hub.freebsd.org (8.8.8/8.8.8) with ESMTP id HAA24244 for ; Wed, 11 Mar 1998 07:26:53 -0800 (PST) (envelope-from nik@iii.co.uk) From: nik@iii.co.uk Received: from carrig.strand.iii.co.uk (carrig.strand.iii.co.uk [192.168.7.25]) by tyree.iii.co.uk (8.8.8/8.8.8) with ESMTP id PAA23603; Wed, 11 Mar 1998 15:20:42 GMT Received: (from nik@localhost) by carrig.strand.iii.co.uk (8.8.7/8.8.7) id PAA00168; Wed, 11 Mar 1998 15:25:41 GMT Message-ID: <19980311152540.43318@iii.co.uk> Date: Wed, 11 Mar 1998 15:25:40 +0000 To: Jeremy Lea Cc: alexandr@hawk.pearson.udel.edu, Annelise Anderson , freebsd-doc@FreeBSD.ORG Subject: Re: ps2pdf (was: newbies mailing list) References: <199803052049.PAA00460@hawk.pearson.udel.edu.> <19980305215748.36179@iii.co.uk> <19980311170823.64512@shale.csir.co.za> Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii X-Mailer: Mutt 0.85e In-Reply-To: <19980311170823.64512@shale.csir.co.za>; from Jeremy Lea on Wed, Mar 11, 1998 at 05:08:23PM +0200 Organization: interactive investor Sender: owner-freebsd-doc@FreeBSD.ORG Precedence: bulk X-Loop: FreeBSD.org On Wed, Mar 11, 1998 at 05:08:23PM +0200, Jeremy Lea wrote: > On Thu, Mar 05, 1998 at 09:57:48PM +0000, nik@iii.co.uk wrote: > > In the pipeline. When we've got the translation to DocBook sorted out > > (which hopefully won't be too far away) it's a (relatively) trivial > > matter to turn the documentation into a multitude of formats. > > > > Watch this space. > > Is there going to be any reorganisation of the FAQ and Handbook while this > transition is in progress? Short answer: The physical organisation will probably change slightly (i.e., the location of the SGML files in the filesystem might move about a bit). However, for the *immediate* term, the content will stay the same. > It would seem like the right time to me to start > messing with the ordering while your changing all the codes and making big > diffs. It's actually the wrong time. This is largely to keep things as simple as possible for the guys doing the Japanese translation of the Handbook (I'm thinking about the DocBook transformation for the FAQ, but my ideas there are sketchy at best at the moment, I haven't written them down properly). Basically, any commits to the handbook/FAQ should either be markup changes or content changes. But not both in the same commit. > I printed out the FAQ a while back in the hope of getting down to doing a > technical/language edit of it (because its smaller than the handbook :), but > I found that I kept wanting to move chapters around. Is there any published > statement of purpose for the two documents? What makes them different, what > should they cover, etc. I would think that the handbook would be a fairly > static document (excepting big changes in the system :), and the FAQ would > cover the day to day issues like which hardware is supported/recommended, > and such things, but it almost seems to be the other way around. I remember > something from Jordan a while back saying that the handbook was the place > for activity? AFAIK, there isn't. Peter da Silva appears to have dropped off the face of the planet (apologies if you are reading this Peter, but you haven't responded to any of my e-mails over the past month or so). > Also, both the FAQ and handbook have statements to the effect that they are > only for the latest release version and then volumes of text which applies > to all releases and to current. True. This is something I'm thinking of addressing at the SGML level, where content is tagged (or marked, more likely) as being either specific to a particular set of FreeBSD versions, or version independent. This would then allow the creation of Handbooks/FAQs that just contain the information for a particular version of FreeBSD. The precise implementation of this mechanism is not something I've settled on yet (in fact, I don't think I've mentioned it here yet, because at the moment it's just something I'm kicking around at the back of my mind). > I personally would think that any question which lasts over 6 months in the > FAQ is stale and should be properly documented somewhere else. Disagree. It might be there because it is frequently asked. However, I don't doubt that some of the FAQ answers should probably consist of This question is answered in section 'x' of the FreeBSD handbook. with appropriate links. > In a month or so I should have enough time to get back into the editing > process. Do you think that the docbook transition will be done by then? > because I'd rather not do the work twice... I hope it will be. Right now I'm just waiting for someone from the Japanese team to get back to me about some issues regarding the DocBook conversion. 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