Date: Tue, 2 Sep 1997 11:05:18 +0100 From: nik@iii.co.uk To: A Joseph Koshy <koshy@india.hp.com> Cc: freebsd-doc@FreeBSD.ORG, jfieber@FreeBSD.ORG Subject: Re: Docbook tools? Message-ID: <19970902110518.05385@strand.iii.co.uk> In-Reply-To: <199709020820.BAA05142@palrel3.hp.com>; from A Joseph Koshy on Tue, Sep 02, 1997 at 01:47:45PM %2B0530 References: <199709020820.BAA05142@palrel3.hp.com>
next in thread | previous in thread | raw e-mail | index | archive | help
[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 <biblio.*> 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
<Pine.BSF.3.96.970726172930.10362N-100000@fallout.campusview.indiana.edu>
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 <bsd.prog.mk>
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 <book> 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
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?19970902110518.05385>