RE: [pooma-dev] docbook overview

[Allan Stokes]

Hello Scott,

I was having one of my foggy days when I wrote my DocBook overview so I
tried to keep it descriptive without making too many claims about whether
DocBook is a good or a bad thing.  The purpose was to describe DocBook and
the environment around it so that others would have a chance to raise their
concerns.

I don't yet have much experience with DocBook.  I do have some experience
with SGML/XML text manipulation and I generally like that approach.  I
expect that authoring in DocBook will be as easy as writing raw HTML once I
get into it.  I know that in the long run the separation of structure from
presentation pays off.

My biggest concern presently is the equation support.  Just because DocBook
has an "equation" element doesn't mean it won't be onerous.  I will explore
this issue in my trial documents.  I once toyed with IBM's TechExplorer,
which was a plug-in for IE allowing the display of Latex equations.
Convenient, but not very portable.  Equations can be a big problem.

No need for debate on whether the future is SGML or XML.  DocBook is neutral
on this subject.  The difference between a DocBook document formatted in
SGML syntax or in XML syntax are on the level of which way out to hang a
roll of bathroom tissue.

Once XML is further along it will become possible to eliminate the use of
Jade/DSSSL in preference for XSL/XSLT when publishing the documents.  I
ignored XML completely in my description, except to explain that it exists
as a parallel stream.  I guess the point I was trying to make is that the
XML community sees DocBook, someday RSN, as one of its own.

I don't have many concerns about getting good typographic quality.  Jade is
an extremely powerful typesetting tool.  James Clark contributed the GNU
implementation of groff before he started working on Jade, and Jade is
almost certainly a superset in functionality.  However, if you want to be
really picky, you might end up having to modify DSSSL code, which can be
quite a hairball, so I'm hoping we aren't that picky.

Because DocBook knows the structure of the source document, I don't expect
it to emit much "stupid" typography.  I'm picky myself actually.  I know the
difference between an em and an en and it bugs me when these things aren't
handled right.  After I've played with Jade for a while, I'll know better
what to expect.

If you wish to be picky right down to intercharacter whitespace/word-break
level, you'd probably use Jade to emit Latex and then tweak the Latex format
until it looked perfect.  DocBook is a flexible environment where anything
is possible.  The trick is to figure out which modes are effective in
practice.  I wish I had more experience to offer.

>From my point of view, the primary appeal of DocBook is the separation of
structure from presentation.  Ultimately this is the only way to go if you
wish to use one source format to produce a wide range of back-end formats.

I understand the problem with emacs not being wysiwyg.  I hate to impose
something like psgml on others.  However, we need to bear in mind that
wysiwyg brings its own problems.  wysiwyg is only wysiwyg if you are
targetting a single backend format which is specified in advance.  I like to
take a wider view of technical documentation.

wysiwyg can also stand for "what you saw is what you got".  You experience
this whenever you open up old Office documents with a newer version.  I tend
to regard wysiwyg as standing for "what you see is what you've got", i.e as
a useful visual aid during composition.  I'm not amused when people confuse
wysiwyg with camera-ready output.

I'm certainly willing to do my part to make DocBook tolerable for everyone.
Fixing badly-formed DocBook files isn't likely to be much of a chore.  The
SGML world has great tools for this kind of thing and psgml has more blades
than a Swiss army knife.

Converting formats is OK if that makes life easier for others.  As long as
we pick formats which are reasonably equivalent with the understanding that
DocBook provides its own presentation backend and that our decisions about
how much control to take over that process need to be made cautiously.

I looked at many options before I identified DocBook as solving the largest
number of problems.  If it creates problems I'm happy to consider
alternatives.

Allan


-----Original Message-----
From: Scott Haney [mailto:address@hidden
Sent: Tuesday 29 May 2001 08:13
To: address@hidden
Subject: Re: [pooma-dev] docbook overview


Hi Mark,

If Allan were really going to write all of the documentation, I'd grant
your last point. However, I think it is reasonable to suspect that
Proximation folks will have a little to contribute in this area.
Therefore, our concerns should be considered. We can also debate whether
the world is headed to SGML or, as I suspect, XML. However, let's not.

We'll give DocBook a try subject to the caveat that we're not going to
spend time porting this to MacOS X or Windows, which means that we may
be checking in badly-formed files that others will have to debug. Also,
if it sucks for us, we'll provide input in other forms and allow the
DocBook boosters to convert. Sound fair?

Scott