From owner-freebsd-doc Tue Mar 17 01:00:03 1998 Return-Path: Received: (from majordom@localhost) by hub.freebsd.org (8.8.8/8.8.8) id BAA03910 for freebsd-doc-outgoing; Tue, 17 Mar 1998 01:00:03 -0800 (PST) (envelope-from owner-freebsd-doc@FreeBSD.ORG) Received: from dt050n33.san.rr.com (@dt050n33.san.rr.com [204.210.31.51]) by hub.freebsd.org (8.8.8/8.8.8) with ESMTP id AAA03847 for ; Tue, 17 Mar 1998 00:59:56 -0800 (PST) (envelope-from Studded@dal.net) Received: from dal.net (Studded@localhost [127.0.0.1]) by dt050n33.san.rr.com (8.8.8/8.8.8) with ESMTP id AAA14631; Tue, 17 Mar 1998 00:59:54 -0800 (PST) (envelope-from Studded@dal.net) Message-ID: <350E3B8A.F440FBD0@dal.net> Date: Tue, 17 Mar 1998 00:59:54 -0800 From: Studded Organization: Triborough Bridge & Tunnel Authority X-Mailer: Mozilla 4.04 [en] (X11; I; FreeBSD 2.2.6-BETA-0316 i386) MIME-Version: 1.0 To: doc@FreeBSD.ORG CC: "Jordan K. Hubbard" Subject: Re: Documentation plan - handbook, etc. References: <350CF5E6.5DD147F5@dal.net> <7061.890049804@time.cdrom.com> <19980316153125.64380@iii.co.uk> Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: 7bit Sender: owner-freebsd-doc@FreeBSD.ORG Precedence: bulk X-Loop: FreeBSD.org nik@iii.co.uk wrote: > There's about to be a considerable amount of time and effort invested > in migrating the Handbook from the LinuxDoc DTD to the DocBook DTD, and > a large chunk of work has already gone into making sure that this can > be done without affecting the current content. Ok, so am I to understand that the work hasn't actually commenced? > This job would be made much easier if we could start over again, but I > think the decision to keep what we've got has already been made over on > the -doc list. There was considerable discussion about the direction the docs should take on -questions less than a week ago and I never saw any firm statements regarding "This is what we will do," so I thought the debate was still open to be framed. > That's not to say that it won't be trimmed down, re-organised and so on > over the coming months. . . > > Could you guys take this on to the -doc list where it belongs (and where > I've cc'd this message, and set reply-to's accordingly). Ok, done, and I'm on the list now so there's no need to cc me. > Go to your favourite list archive and read back through it for the past > month or 2 (alternatively, mail me at nik@nothing-going-on.demon.co.uk and > I'll forward you my own archives). I tried the archive at the www site and TMK there's no way to search specifying dates. I tried "february and 1998" but only got a few letters, none of which applied to the topic at hand. > Precis: A couple of people (myself included) have suggested pretty much > the same thing on the mailing list. No one's yet but together an outline > of how the Handbook should be structured (and as John Fieber's said) the > Handbook has grown quite organically. Well, I'd say that's a pretty good summary. > Probably the best thing to do would be for you to go through the existing > content in the Handbook (at a fairly high level) and see if the ordering > of the chapters can be improved, or whether or not you think some of the > information should be pulled out and made into its own section (or subsumed > into another, or whatever). Actually the *first* question that needs to be answered is what do we want to end up with. You can't make a good plan without a goal in mind. What was the consensus as to what the end product should be? I would have the following questions re the project, my apologies if these were covered in the previous discussion. 1. What are the benefits of docbook vs. linuxbook? (Other than getting "linux" out of our stuff, which I'm all for. :) 2. Will the final product allow the user to generate docs in multiple formats? The ones I'm most intersted in are http, pdf, ps and straight text. 3. What came of the discussion on making the final product easily printable by the user? I really think that this would increase the value of the final product tremendously. I think that if you're serious about moving it into a new format the best bet would be to make concrete plans on the final format and kill all the birds with one shotgun blast. :) That way we don't have to go back and reformat if the parameters of the project change. And yes, I do think that we need an overall outline before we start, but right now my priority is on the FOO.TXT stuff. Finally, where can I get good info on sgml? I have the stuff installed and I've built the docs on my machine but the man page is a bit thin. Doug -- *** Chief Operations Officer, DALnet IRC network *** *** Proud operator, designer and maintainer of the world's largest *** Internet Relay Chat server. 5,328 clients and still growing. *** Try spider.dal.net on ports 6662-4 (Powered by FreeBSD) To Unsubscribe: send mail to majordomo@FreeBSD.org with "unsubscribe freebsd-doc" in the body of the message