Date: Sun, 29 Aug 1999 14:10:04 +0100 From: Nik Clayton <nik@freebsd.org> To: Dan Langille <junkmale@xtra.co.nz> Cc: Nik Clayton <nik@freebsd.org>, doc@freebsd.org Subject: Re: Supporting non-DocBook documents in the tree Message-ID: <19990829141004.A75050@catkin.nothing-going-on.org> In-Reply-To: <19990828104217.PUYK3442178.mta1-rme@wocker>; from Dan Langille on Sat, Aug 28, 1999 at 10:37:40PM %2B1200 References: <19990827132242.A26830@kilt.nothing-going-on.org> <19990828104217.PUYK3442178.mta1-rme@wocker>
next in thread | previous in thread | raw e-mail | index | archive | help
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 <filename> 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
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?19990829141004.A75050>