From owner-freebsd-doc@FreeBSD.ORG Mon May 19 02:13:19 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 3006937B401; Mon, 19 May 2003 02:13:19 -0700 (PDT) Received: from builder.freebsdmall.com (builder.freebsdmall.com [65.86.180.18]) by mx1.FreeBSD.org (Postfix) with ESMTP id 66D0C43FA3; Mon, 19 May 2003 02:13:18 -0700 (PDT) (envelope-from murray@builder.freebsdmall.com) Received: (from root@localhost) by builder.freebsdmall.com (8.12.9/8.11.6) id h4J9DBoG010524; Mon, 19 May 2003 02:13:11 -0700 (PDT) (envelope-from murray) Date: Mon, 19 May 2003 02:13:10 -0700 From: Murray Stokely To: "Greg 'groggy' Lehey" Message-ID: <20030519021310.F8403@freebsdmall.com> References: <20030518.095226.115908955.imp@bsdimp.com> <20030518160039.GA25804@submonkey.net> <20030519013706.GN77354@wantadilla.lemis.com> <20030519000908.E8403@freebsdmall.com> <20030519080452.GR77354@wantadilla.lemis.com> Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline User-Agent: Mutt/1.2.5.1i In-Reply-To: <20030519080452.GR77354@wantadilla.lemis.com>; from grog@FreeBSD.org on Mon, May 19, 2003 at 05:34:52PM +0930 X-GPG-Key-ID: 1024D/0E451F7D X-GPG-Key-Fingerprint: E2CA 411D DD44 53FD BB4B 3CB5 B4D7 10A2 0E45 1F7D 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 09:13:19 -0000 On Mon, May 19, 2003 at 05:34:52PM +0930, Greg 'groggy' Lehey wrote: > > 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. Well then you have a problem with the whole paradigm behind SGML and DocBook, and it's clear why you don't like it. The first chapter of the book in question says : "An SGML document contains all the information that a typesetter needs to lay out and typeset a printed page in the most effective and consistent way, but it does not specify the layout or the type." Yet it seems like this is exactly what your complaint is about. At least, I can't find any other complaints about DocBook in this or other messages from you except that you can't control the formatting like you can with nroff. That's fine, I'm a fan of TeX myself. > > 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. No they're not. DocBook (as with other SGML DTDs) has almost no typesetting information. This is a silly conversation, Greg. I know you know what semantic markup is, and it's clearly at odds with the way you prefer to work. In the FDP, the presentation of the DocBook SGML is done with Jade and DSSSL stylesheets. > 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. DocBook would be a poor choice for writing a letter. That's well outside of what it is intended to do. Slides are pretty far also but some modifications have been made into a separate slide-like DTD/schema and some example stylesheets to create slide PDFs. You can find the slide DTD here : http://sourceforge.net/projects/docbook I wouldn't waste my own time trying to create a presentation with DocBook though. > 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. In this entire paragraph you haven't said what your problem was, or why you found it useless. I can only infer that you still have complaints that it is not nroff and that you can't control the typesetting. That is fine but it's not a failing of the DocBook DTD. What tags could be added to this DTD to make it acceptable to you? None, because your complaints aren't about the DocBook DTD, they are about the entire paradigm. > > 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? One of the many XSLT books by O'Reilly or the larger XSLT book by Wrox Press. We use DSSSL stylesheets in the FDP but DSSSL didn't catch on with the rest of the world because the lisp-based stylesheet language is programmer and implementor-unfriendly. Both DSSSL and XSLT are standard languages to transform XML/SGML documents. I'm not even aware of any printed books about DSSSL, but there are tens of books about XSLT. - Murray