[prev in list] [next in list] [prev in thread] [next in thread] 

List:       maradns-list
Subject:    Re: Plans for the next MaraDNS release
From:       Joe Cooper <joe () swelltech ! com>
Date:       2002-02-28 6:24:06
[Download RAW message or body]

e8mhpsznamq001@sneakemail.com wrote:

> The next release of MaraDNS will deal with two issues which
> people have brought up here.
> 
> First of all, yes the EJ format is a little strange; a lot of
> people are more comfortable working in a format they already
> know, such as docbook.  Since EJ and docbook are, in many ways,
> very similar, it should be a simple matter to make docbook2ej
> and ej2docbook filters.  Docbook is, as far as I can tell, the
> closest thing to a SGML-based standard documentation format.
> Or, perhaps, I will make ej2linuxdoc and linuxdoc2ej filters
> (I get the sense that Linuxdoc is docbook with Linux-specific
> extensions).


LinuxDoc is a tiny subset with some weirdnesses thrown in.  It is a 
non-SGML format that kind of looks like SGML.  LinuxDoc is exceedingly 
easy to write in for first time markup language users, but is considered 
deprecated for all of the major documentation projects--there are good 
reasons for this which aren't worth discussing here.  DocBook XML, which 
almost completely compatible with the older DocBook SGML so don't worry 
about warring formats, is the future of all of the major Open Source and 
Free Software documentation projects that I keep up with.

DocBook SGML/XML is a truly wonderful markup specification, with a lot 
of great free tools for processing them.  I recommend it.

LinuxDoc was a useful interim solution that worked simply and reliably 
with very little study on the part of the person doing the markup. 
However, it is an extremely limited format with next to no development 
effort going into it.  If DocBooks large number of tags is daunting to 
begin with, there is a Simplified DocBook specification, allowing 
DocBook the format to be used without quite so many tags.  However, I 
don't see any reason to choose the crippled DocBook over the real 
thing--just use the tags you like and forget the ones you don't.


> Naturally, I don't know that much about docbook; however,
> www.linuxdoc.org or (possibly) www.docbook.org should have
> the information I am seeking.


Unfortunately, the process of /using/ DocBook is not well documented in 
any one place (there is an irony in that somewhere), and the tools are a 
rapidly moving target.  That said, all of the major documentation 
projects do have decent docs on processing files to suit the purpose of 
each project.  The FreeBSD doc folks have put together the best tutorial 
I've seen so far--it is very straightforward with no tangents that 
distract from the core of the problem (the problem being, "How do I turn 
my marked up document into something nice to read").  The KDE folks have 
also written some nice docs, and the e-Smith guys have another good 
document on DocBook.

Here are some links worth reading if considering DocBook SGML or XML 
(I'll reiterate that it doesn't matter which toolchain you choose, the 
same document will process either in an XML or SGML toolchain with very 
very few modifications--my docs required a one line modification at the 
top of the file, plus a few tag-closing cleanups; about fifteen minutes 
for a 250 page book).

Nik Clayton's getting SGML DocBook guide called "FreeBSD Documentation 
Project Primer for New Contributors" is linked from here along with some 
other relevant links about the standards and groups supporting those 
standards:

http://www.freebsd.org/docproj/sgml.html

Eric Bischoff, Mark Galassi and David Rugge wrote this for the KDE 
folks, and it has been poked and prodded by a lot of folks on the 
DocBook-tools mailing list, so it is quite solid and accurate:

http://www.caldera.de/~eric/crash-course/HTML/index.html

The Linux Documentation Project contributors guide (The HOWTO-HOWTO) is 
also quite informative, but I found it left a lot of questions 
unanswered and at the end of following it I did not have a processing 
system that worked.  This has probably long been fixed (I started using 
DocBook instead of LinuxDoc almost two years ago).  The Gnome 
Documentation Project also has a few guides, but I have never read them 
so can't say whether they are superior to the FreeBSD or KDE guides.  I 
believe reading the FreeBSD and KDE guides, plus asking a couple of 
questions on the DocBook-tools list is all that a new user would need to 
do to be producing complete docs with the older SGML tool-chain.  The 
newer XML toolchains are a mess, and I can't make them work right even 
today--I've gotten a few to work, but reverted to SGML because the 
output of DocBook XML was inferior using current tools.

And finally, DocBook: The Definitive Guide is available for free online 
to provide the real definitive source for the markup language itself. 
If you're comfortable with HTML, or LinuxDoc, the move to DocBook is not 
a big stretch.  Just remember to close your tags (all of them, paragraph 
included) and use consistent capitalization (all lower case is the best 
choice, IMHO).


> The problem with TeX based systems (LaTeX; gnu's Info format,
> etc.) is that I would have to install TeX on my laptop to look
> in those kinds of systems; my hard disk is not as big as I
> would like.


TeX is cool (and is the backend for the DocBook SGML print output). 
You'll need it to process DocBook into print formats (but not HTML).

I would not start a major writing project in TeX today.  DocBook is so 
much better suited to the task of technical writing.

-- 
Joe Cooper <joe@swelltech.com>
http://www.swelltech.com
Web Caching Appliances and Support

[prev in list] [next in list] [prev in thread] [next in thread]