On Tue, Mar 22, 2011 at 2:27 PM, Gaetan Nadon <[email protected]> wrote: > On Tue, 2011-03-22 at 13:23 -0700, Dan Nicholson wrote: > > On Tue, Mar 22, 2011 at 10:34 AM, Gaetan Nadon <[email protected]> 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.
That's a good point. It only works if you have multiple versions of docbook installed. Fortunately, many distros can and do install the older versions of docbook. However, if you have an older tarball with XML files that call out Docbook version 4.2, how does changing this macro affect it? Maybe it wouldn't work out that well, though. Going back to your original point, though. If the docbook version needs to be hardcoded into the xml files in the tree anyway, then that version could easily be passed to the macro. XORG_DOCBOOK_TEXT(4.5) Which generates the test with V4.5 in the doctype. When you're ready to move your docs up to version 5, you change your xml files and the argument to the macro. Not sure it's 100% foolproof, though. -- Dan _______________________________________________ [email protected]: X.Org development Archives: http://lists.x.org/archives/xorg-devel Info: http://lists.x.org/mailman/listinfo/xorg-devel
