From owner-freebsd-doc@FreeBSD.ORG Mon May 19 01:04:59 2003 Return-Path: Delivered-To: freebsd-doc@freebsd.org Received: from mx1.FreeBSD.org (mx1.freebsd.org [216.136.204.125]) by hub.freebsd.org (Postfix) with ESMTP id 5328237B401; Mon, 19 May 2003 01:04:59 -0700 (PDT) Received: from wantadilla.lemis.com (wantadilla.lemis.com [192.109.197.80]) by mx1.FreeBSD.org (Postfix) with ESMTP id 6597343F3F; Mon, 19 May 2003 01:04:56 -0700 (PDT) (envelope-from grog@lemis.com) Received: by wantadilla.lemis.com (Postfix, from userid 1004) id ACEF951A95; Mon, 19 May 2003 17:34:52 +0930 (CST) Date: Mon, 19 May 2003 17:34:52 +0930 From: Greg 'groggy' Lehey To: Murray Stokely Message-ID: <20030519080452.GR77354@wantadilla.lemis.com> References: <20030518.095226.115908955.imp@bsdimp.com> <20030518160039.GA25804@submonkey.net> <20030519013706.GN77354@wantadilla.lemis.com> <20030519000908.E8403@freebsdmall.com> Mime-Version: 1.0 Content-Type: multipart/signed; micalg=pgp-sha1; protocol="application/pgp-signature"; boundary="LfQcPIWFRhGivmDw" Content-Disposition: inline In-Reply-To: <20030519000908.E8403@freebsdmall.com> User-Agent: Mutt/1.4i Organization: The FreeBSD Project Phone: +61-8-8388-8286 Fax: +61-8-8388-8725 Mobile: +61-418-838-708 WWW-Home-Page: http://www.FreeBSD.org/ X-PGP-Fingerprint: 9A1B 8202 BCCE B846 F92F 09AC 22E6 F290 507A 4223 cc: doc@FreeBSD.org cc: "M. Warner Losh" Subject: Re: DocBook book X-BeenThere: freebsd-doc@freebsd.org X-Mailman-Version: 2.1.1 Precedence: list List-Id: Documentation project List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Mon, 19 May 2003 08:04:59 -0000 --LfQcPIWFRhGivmDw Content-Type: text/plain; charset=us-ascii Content-Disposition: inline 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 --LfQcPIWFRhGivmDw Content-Type: application/pgp-signature Content-Disposition: inline -----BEGIN PGP SIGNATURE----- Version: GnuPG v1.2.0 (FreeBSD) iD8DBQE+yJAkIubykFB6QiMRAt1hAJ0dEsLk4JGPUifaJMATrO2Bq7mofQCfdsTg gJo7ZADxHDL/mF1GP2VR36M= =hUIm -----END PGP SIGNATURE----- --LfQcPIWFRhGivmDw--