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

[Gaetan Nadon]

On Tue, 2011-03-22 at 13:23 -0700, Dan Nicholson wrote:

> 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?

The macros have to be backward compatible. In 3 years from now, no one
will have
4.3 installed, so we will need to move up to 4.8. Building older
versions of tarballs
with older versions of docbook will not be possible. 

The version specified has to match exactly, no >= stuff.

> 
> $ 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.

No objection in making better checks. We need to be really sure the code
will not break
as time moves forward. 

> 
> --
> Dan
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.x.org/archives/xorg-devel/attachments/20110322/3020b090/attachment.html>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 197 bytes
Desc: This is a digitally signed message part
URL: <http://lists.x.org/archives/xorg-devel/attachments/20110322/3020b090/attachment.pgp>