Date: Mon, 29 Mar 1999 10:57:41 +0100 From: nclayton@lehman.com To: Kris Kennaway <kkennawa@physics.adelaide.edu.au>, Nik Clayton <nik@nothing-going-on.demon.co.uk> Cc: current@freebsd.org, doc@freebsd.org Subject: Re: Handbook DocBook cutover complete Message-ID: <19990329105741.L23968@lehman.com> In-Reply-To: <Pine.OSF.4.10.9903281636550.2929-100000@bragg>; from Kris Kennaway on Sun, Mar 28, 1999 at 04:40:22PM %2B0930 References: <19990327162554.K3136@catkin.nothing-going-on.org> <Pine.OSF.4.10.9903281636550.2929-100000@bragg>
next in thread | previous in thread | raw e-mail | index | archive | help
Kris,
On Sun, Mar 28, 1999 at 04:40:22PM +0930, Kris Kennaway wrote:
> On Sat, 27 Mar 1999, Nik Clayton wrote:
> > Almost a year ago I started the project to switch the Handbook over
> > from LinuxDoc to DocBook.
>
> Can I ask what the differences and benefits are?
As follows;
* LinuxDoc is descended from the QWERTZ DTD, and was designed to serve
the needs of the Linux Documentation Project.
DocBook has been designed to mark up technical books and articles,
and has been designed by representatives from a large number of
companies (this, for once, has not been a bad thing). It's large,
comprehensive, and well supported.
* LinuxDoc is designed to be quite close to LaTeX. This means there's
a lot of presentational markup (i.e., markup that describes things as
being bold, or italic, and so on), a lot like HTML.
DocBook contains *no* presentational markup, it's entirely semantic.
To write a filename in LinuxDoc you would write
<tt>/path/to/some/file</tt>
where "<tt>" means "teletype", i.e., a monospaced font. If you wanted
to write a command the user types in, you would use the same thing,
<tt>ls /etc</tt>
In DocBook, you would write
<filename>/path/to/some/file</filename>
<command>ls /etc</command>
When processed, both those might be displayed in a monospaced font.
However, the DocBook version includes extra information. We don't do
it yet, but the DocBook Handbook will eventually include several
indices. One of these will be a list of each page where each filename
is mentioned, allowing you to quickly see all the places where (for
example) ppp.conf is referred to.
This index would catch every reference to ppp.conf used as a filename,
but would ignore those where it was mentioned as part of a command.
So "<filename>ppp.conf</filename>" would be indexed, but "<command>vi
ppp.conf</command>" wouldn't.
The only way to do this using LinuxDoc would be to index everywhere
'ppp.conf' appeared, which would *also* catch the second example,
which is not what you want.
* DocBook is extensible. It's relatively easy to add your own elements,
for things that are missing from DocBook. I've done this for the
Handbook, adding things like "<hostid>" and "<maketarget>". This is
harder to with LinuxDoc.
* The Linux Documentation Project is moving away from LinuxDoc to DocBook.
I *think* the FreeBSD Doc. Proj. switched first, and I'm pretty certain
the FreeBSD Handbook is the largest free set of documentation that
currently uses DocBook. I could be wrong about that though.
* There's an XML implementation of DocBook (currently unofficial). This
will be more important in the future, as XML browsers become more
widespread.
* Tools to convert DocBook to other formats are not quite as advanced
as the LinuxDoc tools, but are getting their rapidly.
As it currently stands in the repository, the DocBook Handbook can be
converted to HTML, Postscript, plain text, and Microsoft RTF. A bug
that I'll fix this week is currently preventing PDF generation.
Word .doc support is in the pipeline as well, probably for the end of
this week too (I've now given some money to the evil empire so I can
test the output myself).
Next on the list will be whatever internal format the Palm Pilot uses.
I imagine this won't be too useful for the Handbook, but will probably
be quite handy for the FAQ. . .
More information at
http://www.freebsd.org/~nik/primer/index.html
N
--
--+==[ Systems Administrator, Year 2000 Test Lab, Lehman Brothers, Inc. ]==+--
--+==[ 1 Broadgate, London, EC2M 7HA 0171-601-0011 x5514 ]==+--
--+==[ Year 2000 Testing: It's about time. . . ]==+--
To Unsubscribe: send mail to majordomo@FreeBSD.org
with "unsubscribe freebsd-current" in the body of the message
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?19990329105741.L23968>