From owner-freebsd-doc Tue Sep 2 03:02:38 1997 Return-Path: Received: (from root@localhost) by hub.freebsd.org (8.8.7/8.8.7) id DAA28312 for doc-outgoing; Tue, 2 Sep 1997 03:02:38 -0700 (PDT) Received: from tyree.iii.co.uk (tyree.iii.co.uk [193.117.77.66]) by hub.freebsd.org (8.8.7/8.8.7) with ESMTP id DAA28301; Tue, 2 Sep 1997 03:02:27 -0700 (PDT) Received: from carrig.strand.iii.co.uk (carrig.strand.iii.co.uk [192.168.7.25]) by tyree.iii.co.uk (8.8.4/8.8.4) with ESMTP id KAA01501; Tue, 2 Sep 1997 10:59:50 +0100 (BST) Received: (from nik@localhost) by carrig.strand.iii.co.uk (8.8.7/8.8.7) id LAA00470; Tue, 2 Sep 1997 11:05:19 +0100 (BST) Message-ID: <19970902110518.05385@strand.iii.co.uk> Date: Tue, 2 Sep 1997 11:05:18 +0100 From: nik@iii.co.uk To: A Joseph Koshy Cc: freebsd-doc@FreeBSD.ORG, jfieber@FreeBSD.ORG Subject: Re: Docbook tools? References: <199709020820.BAA05142@palrel3.hp.com> Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii X-Mailer: Mutt 0.76e In-Reply-To: <199709020820.BAA05142@palrel3.hp.com>; from A Joseph Koshy on Tue, Sep 02, 1997 at 01:47:45PM +0530 Organization: interactive investor Sender: owner-freebsd-doc@FreeBSD.ORG X-Loop: FreeBSD.org Precedence: bulk [Not speaking for doc@freebsd.org] On Tue, Sep 02, 1997 at 01:47:45PM +0530, A Joseph Koshy wrote: > What is the current state of the Docbook tools? The `instant' based > transpec for docbook is ok, but not quite complete. I've noticed > that some elements in the DocBook Dtd aren't at all handled; > anything under for example. Changing the instant transpec > is not for the faint of heart :(. Agreed. > What is the status of the DSSSL based tools (jade et al), is there any > way of using Jade to convert Docbook to HTML,TeX or *roff? Yep. Make sure you've got the relevant parts of ports/textproc installed, specifically, 'jade', 'iso8879', 'docbook', 'sgmlformat' and 'linuxdoc'. The dependencies are such that you should just be able to install 'sgmlformat' and it will suck down the rest for you. Then make sure your SGML_CATALOG_FILES environment variable is set correctly; I use the following in ~/.tcshrc, YMMV: # SGML catalogs setenv SGML_ROOT /usr/local/share/sgml setenv SGML_CATALOG_FILES ${SGML_ROOT}/docbook/3.0/catalog setenv SGML_CATALOG_FILES ${SGML_CATALOG_FILES}:${SGML_ROOT}/iso8879/catalog setenv SGML_CATALOG_FILES ${SGML_CATALOG_FILES}:${SGML_ROOT}/jade/catalog Now you need some DSSSL stylesheets to do the conversion. You've got a couple of choices. At this point, it's simpler for me to quote one of John Fieber's earlier messages: [Quoting from Written on Sat, 26 Jul 1997 18:23:53 -0500 (EST) With the subject: DSSSL stylsheets for docbook.] > However, using jade's HTML output isn't that useful at this point > because it depends heavily on robust CSS support in the browser, > which doesn't really exist now. > > The other approach to generating HTML with DSSSL is to use the > transformation language part of the DSSSL standard, since docbook > to HTML is effectively a transformation from one DTD to another. > Alas, jade does not yet support the transformation language. As > a stopgap measure, jade supports some non-standard flow objects > that can be used in conjunction with the "-t sgml" output format > that can be used for generating HTML. > > I've put a snapshot of my docbook stylsheets--one for print > output and one for HTML output--up at > ftp://fallout.campusview.indiana.edu/pub/sgml/stylesheet-0.1.tar.gz. > Brief instructions are included. > > Jon Bosak's docbook stylsheet (db070) has been adopted by Norm > Walsh and can be found in its latest incarnation at > http://www.berkshire.net/~norm/dsssl/. Both Norm's stylsheet and > my stylsheets are definately incomplete, although the areas of > incompleteness differ. I've been focusing mostly on the HTML > generation and the features needed to get the handbook moved from > linuxdoc to Docbook. It may ultimately be more practical to drop > my print stylsheet in favor of Norm's. If you've downloaded these, you can then construct a Makefile to do the conversion for you. I use a variant on the following: # Progam locations SGMLS=/usr/local/bin/nsgmls INSTANT=/usr/local/bin/instant JADE=/usr/local/bin/jade SGMLDIR=/usr/local/share/sgml # File locations # Where to find docbook.dcl, relative to SGMLDIR DCL=/docbook/3.0/docbook.dcl # Where my DocBook to HTML stylesheet is kept. I've downloaded it from # Norm Walsh's page, and store it in my home directory. DB_DSL=/export/home/nik/sgml/dsssl/db-current/docbook.dsl # HTML transpec for instant, relative to SGMLDIR HTML-TS=/transpec/docbook-html.ts # Suffix rules. .SUFFIXES: .sgml .html .rtf # Convert from SGML to HTML. Use sgmls and instant. .sgml.html: $(SGMLS) $(SGMLDIR)$(DCL) ${@:R}.sgml | $(INSTANT) \ -t $(SGMLDIR)$(HTML-TS) > $@ # Convert from SGML to RTF .sgml.rtf: $(JADE) -d $(DB_DSL) -t rtf ${@:R}.sgml # Convert from SGML to HTML. Use jade. This will produce the multi-page # format, which I don't particularly like. So it's commented out #.sgml.html: # $(JADE) -d $(DB_DSL) -t sgml ${@:R}.sgml # List the targets you want to generate here # # Assume the source file is foo.sgml ALL= foo.html foo.rtf # List of files to remove on 'make clean' CLEANFILES+=$(ALL) # Default target all: $(ALL) # Random system magic .include Hopefully that's self explanatory. Remember, you can't cut and paste that, since you'll lose the embedded TABs. FWIW, if you use [X]emacs, you also have access to the rather wonderful psgml-mode, which makes editing SGML files much, much easier. As to the actual state of the tools and the stylesheets: I've only really experimented with Norm Walsh's stuff. The RTF generation is fine, albeit slightly buggy. It has a tendency to include blank pages in the output, and the automatic table of contents generation is a little screwy. But for alpha/beta software it works very well. I don't use the HTML generation, since it takes a DocBook and turns it into multiple HTML files. I prefer the single file approach of instant, hence the hybrid approach above. Hope that's useful. N -- --+==[ Nik Clayton is Just Another Perl Hacker at Interactive Investor ]==+-- Diana, the roadkill formally known as Princess, 1961-1997 NC5-RIPE