From owner-freebsd-doc Sun Aug 29 7: 2:38 1999 Delivered-To: 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 (Postfix) with ESMTP id C1B9D14EA1; Sun, 29 Aug 1999 06:57:46 -0700 (PDT) (envelope-from nik@nothing-going-on.demon.co.uk) Received: (from nik@localhost) by nothing-going-on.demon.co.uk (8.9.3/8.9.3) id OAA76793; Sun, 29 Aug 1999 14:10:04 +0100 (BST) (envelope-from nik) Date: Sun, 29 Aug 1999 14:10:04 +0100 From: Nik Clayton To: Dan Langille Cc: Nik Clayton , doc@freebsd.org Subject: Re: Supporting non-DocBook documents in the tree Message-ID: <19990829141004.A75050@catkin.nothing-going-on.org> References: <19990827132242.A26830@kilt.nothing-going-on.org> <19990828104217.PUYK3442178.mta1-rme@wocker> Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii X-Mailer: Mutt 0.95.4i In-Reply-To: <19990828104217.PUYK3442178.mta1-rme@wocker>; from Dan Langille on Sat, Aug 28, 1999 at 10:37:40PM +1200 Organization: FreeBSD Project Sender: owner-freebsd-doc@FreeBSD.ORG Precedence: bulk X-Loop: FreeBSD.org On Sat, Aug 28, 1999 at 10:37:40PM +1200, Dan Langille wrote: > > I get the impression that we're currently viewed as being a bit > > inflexible about the formats that we accept documentation in, and that even > > when we do accept submissions, it takes us a while to get around to > > converting them to DocBook. This is mostly due to lack of manpower. > > What is the main reason for using DocBook as opposed to some other format? The competing formats are basically: Plain text: Very easy to use, because everyone can understand it. But, pretty-printing it is nigh on impossible, can't be adapted to different output formats to take advantage of their capabilities, no hyper-linking. HTML: Also easy to use, the de-facto web standard, and most people know it. As with text, it's difficult to convert it to other formats, and keep the formatting (compare the formatting similarities between the HTML, PS, and RTF versions of the Handbook for an example of what I mean). Doesn't encourage a 'house style' for things like examples that the reader should be entering. You need to have an editor for that. LaTeX: Big. Geared towards Postscript and PDF output. Tricky to learn for your average HTML user (I include myself in this). Processing tools are big. LinuxDoc: SGML DTD (like HTML, so it looks a bit like HTML). Based heavily on LaTeX, which means that, like, HTML, it concentrates on describing what something should look like, rather than what something is. Being phased out by the Linux Documentation Project, in favour of. . . DocBook: Originally created by O'Reilly and HALS, now maintained by the Davenport group. Relatively easy for an HTML or LinuxDoc user to use, as it's just a different set of elements, and their relationships to one another. The toolchain is still relatively young. *Very* geared towards describing technical markup, which means the markup job is actually easier than something like LinuxDoc -- with LinuxDoc (or HTML, for that matter) you end up thinking "Hmm, this is a filename. Italic? Bold? Courier?". With DocBook you end up thinking "Hmm, this is a filename. That'll be the element then.". LinuxDoc documents can be mechanically converted to DocBook (they require some tidying up afterwards though). A very *rich* element set makes it easy to capture lots of useful information, which can be removed as necessary if the target format doesn't need it. For historical accuracy, the real person to ask about this is John Fieber, who was the FDP manager before me. He'd already started the switch to DocBook in the FDP before I became interested in it, and I started using it to support the internal documentation at the company I was working for at the time. 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