Re: [Refdb-devel] man pages

[Michael S. <sm...@xm...>]

Markus Hoenicka <mar...@mh...> writes:

> Michael Smith <sm...@xm...> was heard to say:
>=20
> > Yes. If the commands are all marked up as Refentry instances.
>=20
> Well, currently they are not, but each tool has a cmdsynopsis and a descr=
iption
> of the options, so it'll take only some rearrangement to end up with Refe=
ntry
> instances.

OK. You might be able to transform those parts of your source docs
into Refentry instances programatically using XSLT. Or if you
already have created roff versions of them, you can use
doclifter to convert those, and then paste the results back into
your DocBook source doc for the manual.

> There's just a minor issue. I'm currently maintaining the manual as a SGML
> document because I still can't get PDF output from the RefDB manual if I
> convert it to XML.

There is a relatively new DocBook-to-PDF tool called "dblatex"
that you might try.

  http://dblatex.sourceforge.net/

Despite that fact that it is based on LaTeX, it is designed to be
as easy to use as possible. You invoke it like this:

  dblatex foo.sgml

And it generates a foo.pdf file in the same directory.

It uses a set of XSLT stylesheets to do the conversion to LaTex
(and then transparently does the PDF conversion from that), but if
you feed it an SGML file, it will attempt to convert it to XML
before running the XSLT transformation.

However, it uses an ad-hoc Perl script to do the SGML to XML
conversion. I suspect that script might be a little fragile and
might not work with many real-world DocBook SGML instances. But I
can't say because I have never actually tried to convert any
DocBook SGML instances myself.

That said, the docs for dblatex itself are actually SGML instances
(doctype "-//OASIS//DTD DocBook V3.1//EN"), and converts those to
PDFs successfully at least.

Anyway, it is in very active development right now and that
actually already works pretty well with many DocBook docs. It
might work with yours if you try it.

> The XML is valid, FOP works in general, but it dies on my system
> on this particular document with a memory exception.

Have you tried running FOP with the "-Xmx" switch passed to Java.
to set the maximum heap size. The default max heap size for Java
is just 64M (I think). I think that is not nearly enough for
processing more real-world docs with FOP (or with XEP). So you
need to set it at least 96M or 128M, preferably more -- 256M or
512M if you can. If you are running FOP from a system script (it's
/usr/bin/fop in Debian system), you might be able to set the max
heap size to a bigger value by doing this:

  JAVA_OPTS=3D-Xmx256M fop ...

Or if you invoking Java directly to run FOP, like this:

  java -Xmx256M org.apache.fop.apps.Fop ...

     --Mike

--=20
Michael Smith
http://sideshowbarker.net/