DocBook book

[Greg 'groggy' Lehey]

On Monday, 19 May 2003 at  0:09:08 -0700, Murray Stokely wrote:
> On Mon, May 19, 2003 at 11:07:06AM +0930, Greg 'groggy' Lehey wrote:
>> I have it, and I can't recommend it.  Despite the name, it's a
>> reference, not a guide.  For an example of the kind of book I'm
>> looking for, see http://www.alltel.net/~kollar/utp/.  That's about
>> troff, not DocBook, but it's a well written book.  I don't think
>> anything similar is available for DocBook.
>
> I can recommend DocBook TDG strongly if you are trying to author
> something in DocBook for the first time.

That's exactly what I was trying to do.  I can't recommend it.

> The whole point of SGML is that it is a totally different paradigm
> from something like troff.  Authors aren't supposed to have to worry
> abou the complications of presentation.

I have a problem with that, but I don't think it's relevant.

> This book teaches you the tags that have been defined to describe
> technical content.  It is another problem domain (usually dealt with
> by a separate person) to write an XML application to query that
> document for semantic information, process the SGML document and
> turn it into another output format, process the SGML document and
> create a audio rendering, etc..

I can accept that division of labour.  But they're both part of
DocBook.

> The book you reference has chapters on learning vi, Unix
> fundamentals, and all kinds of typesetting information, all of which
> is completely irrellevant in the SGML/XML world.

Certainly the chapters about vi and UNIX in general are irrelevant.
But it also has chapters leading you through how to create a document,
how to influence the layout, etc.  You may say "but you shouldn't be
influencing the layout", but I disagree.  If I want, say, to write a
letter or a set of slides in DocBook, I need to know how to get the
effects I want.  This book doesn't tell me.

In the case in point, I was writing my book "The Complete FreeBSD".
O'Reilly supplied the presentation details you refer to above, so I
really only needed to do what you say the book is for.  In addition,
since it's an O'Reilly book, you would expect it to be a particularly
good match.  In fact, I found it almost useless.  O'Reilly did supply
me with a basic introduction to how to do things, and apologized for
not having anything better, so I'm sure they recognize the problem.
In the end I gave up and wrote in groff.

> If Warner would like to know more about the process of rendering
> DocBook SGML files into different output formats, then the wrong
> question was asked and a different book would have been recommended.

Out of interest, which one?

Greg
--
See complete headers for address and phone numbers
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 187 bytes
Desc: not available
URL: <http://lists.freebsd.org/pipermail/freebsd-doc/attachments/20030519/3e1b0b19/attachment.sig>