[PATCH util-macros 1/2] Add XORG_WITH_W3M for HTML to text conversion

[Dan Nicholson]

On Tue, Mar 22, 2011 at 10:34 AM, Gaetan Nadon <memsize at videotron.ca> wrote:
> On Mon, 2011-03-21 at 17:46 -0700, Dan Nicholson wrote:
>
> I'm not volunteering to do it, but I always thought it would be nice
> if the doc macros actually tried to generate a test doc instead of
> just checking for tools in the path. It's fairly easy to get xmlto in
> your path but actually have a hosed up docbook toolchain.
>
> There has been attempts to do that. It brings its own problems.
> That amounts to "testing" the software to see if it works well enough.
>
> This is done in the compiler world to test for features or behaviors.
> This world is well tested, highly backward compatible. Not so for doctools.
>
> In order to have a meaningful test (other than a zero byte file), one
> would require something like this:
> <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
>                    "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">
>
> Note the version number. This would eventually break when 4.3 is no longer
> available. By design Docbook is meant not to be backward compatible from
> one major version to another. In our case, util-macros would eventually
> cease
> to build older versions creating hard to diagnose problems.
>
> Currently we test for the path and optionally a version number.
> Nothing prevents us from adding additional tests, providing we are
> sure it works correctly on all platforms and across time as well.

Do we not require a certain version of Docbook for our documents?
Shouldn't we use that version to test? If the user has xmlto installed
but Docbook is 4.2, then the docs could fail anyway, right?

$ cat > blah.xml << "EOF"
<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V6.0//EN"
          "http://www.oasis-open.org/docbook/xml/6.0/docbookx.dtd">
<article>
  <para>This is a test</para>
</article>
EOF
$ xmlto html blah.xml 2>/dev/null
$ echo $?

> Right now, we have a docbook feature which only works with a recent version
> of docbook-xsl as documentation in the README:
>
> The pdf/ps "inside the document" references only started working with
> docbook-xsl v 1.76.1 which is not yet available to your favorite O/S.
> In xorg-fo.xsl, insert.olink.pdf.frag must be set to zero which allows
> the reference to at least point to the top of the document.
>
> I can't think of any test to verify the feature works or not. It would be
> nice if the technology
> had some built-in design to do that. I agree with your requirement but the
> implementation
> is not trivial, even when possible.

It's not _too_ hard to check the version. With xmlto:

$ cat > bar.xml << "EOF"
<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
          "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<article>
  <para>This is a test</para>
</article>
EOF
$ cat > bar.xsl << "EOF"
<?xml version="1.0" encoding="utf-8"?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
                version="1.0">
  <xsl:import href="http://docbook.sourceforge.net/release/xsl/1.76.1/html/docbook.xsl"/>
</xsl:stylesheet>
EOF
$ xmlto html -x bar.xsl bar.xml 2>/dev/null
$ echo $?
1

With xsltproc it's even simpler because you can just use the
stylesheet URI directly:

$ xsltproc --nonet
http://docbook.sourceforge.net/release/xsl/1.76.1/html/docbook.xsl
bar.xml 2>/dev/null
$ echo $?
4

It's not trivial, but I think this could be a nice feature. I was
working on this on my laptop a long time ago when the doc macros were
very different, but I'll see if I can dig it up.

--
Dan