Re: [Boost-docs] [boostbook] Docbook processing instructions get stripped out?

Subject: Re: [Boost-docs] [boostbook] Docbook processing instructions get stripped out?
From: Daniel James (dnljms_at_[hidden])
Date: 2010-10-28 17:44:58

On 28 October 2010 17:04, John Maddock <boost.regex_at_[hidden]> wrote:
> Thanks, that gets it for me, is there anyway we can verify that this doesn't
> break anything before committing to Trunk?

I can rebuild the documentation and check that it hasn't changed.
Also, I've started on some better tests for the boostbook to docbook
stage. You can see them at 'tools/boostbook/test/more'. It's currently
a python script that requires lxml (used for its xslt support and to
change the generated xml so that it uses consistent ids). I'm thinking
about changing it to use xsltproc for xslt and then using the xml
modules that come with python (which aren't particularly good, but
it'll make the script easier to run).

> 1) There's currently no way to know for sure what the current build target
> is:  bjam knows this information, so we can inject it into a command line
> such as an XSL param, but as far as I can see there's no way to get at this
> information within quickbook (or to pass it to quickbook?) so that we could
> use quickbook's conditional feature?

A few releases ago I added a feature to set macros at the command
line, although I didn't test it properly and it didn't work. It should
be fixed in this release. This could then be used with a conditional
phrase. So for something like:

    [article Test

    [template thing[x] [?foo [x]]]

    [thing hello!]

Use 'quickbook -D foo test.qbk' and it outputs 'hello!', use
'quickbook test.qbk' and it doesn't. I was also working on adding
support to boost build. I've attached a patch, but I'm not sure if
it'll work (it was a few months back, I've been sidetracked by other

This is a bit limited as conditional phrases can't contain block
elements - such as macro and template definitions. That's something
else I was working on.

> 2) I would need a way to insert random chunks of HTML into the <head>
> section of each chunk to load the equation processor, I guess I could write
> a program to do this and have it run post-html-build.  Unless there's an
> easier way (preferably without making our stylesheets even more complex)?

I think we'd have to add a 'user.head.content' template to
html-base.xsl. It shouldn't be too complex.

> 3) I can foresee opposition to having documentation relying on third party
> JavaScript code - in fact having just checked it's 124Mb which I think rules
> out inserting it into the Boost SVN tree :-(  We could put it on the server
> only I guess, but then that would rule out off-line browsing.  Dang,
> snookered :-(

Don't some browsers support MathML natively? Could an offline copy
work on them? I think for Boost.Math you could make a valid argument
for requiring an appropriate browser. Also, if it's the fonts which
make it so large, it might be possible for users to install them
separately (they might even already be installed on some machines).
That's maybe a bit of a pain, and could be confusing for anyone who
jumps into the middle of the offline documentation.


This archive was generated by hypermail 2.1.7 : 2017-11-11 08:50:41 UTC