Experimenting with equation (MathJax) support

I've been experimenting with the tentative equation handling support in 
Trunk, and have some observations:

* There's no docs.... took me a while to figure out what to do...
* I added quickbook markup as follows to doc/test/test.qbk to test both 
LaTex and MathML support:

[section Equations]

This equation is formatted from Latex text:

'''<inlinemediaobject><textobject role="tex">ax^2 + bx + c = 
0</textobject></inlinemediaobject>'''

This equation is formed from MathML:

'''<inlinemediaobject><textobject role="MathML"><?dbhtml-include 
href="test.mml"?></textobject></inlinemediaobject>'''

[endsect]

Then I modified the Jamfile to add an xsl:path attribute so that test.mml 
could be found in the current directory, and everything builds OK, raw HTML 
output looks OK to.

* The equations are both rendered correctly in Firefox, but MathJax support 
is only present in the HTML if a Tex object is present - I guess some change 
to our XSL stylesheets is required for the latter (and that I can't set the 
role to "tex" as the HTML output won't be correct)?
* IE9 renders neither equation correctly - is this a fatal flaw, or is there 

More equation woes.....

Some more experimentation reveals that:

* IE9 will only support the MathJax scripts if the script is loaded from a 
subdirectory of the one containing the HTML (a non-starter) otherwise you 
get a security warning (which I missed the first time), and if you either 
miss the warning or just follow IE9's advice and block the script then all 
the equations disappear 
* I tried using SVG's instead of MathML or Tex, and Oh dear that's as bad 

Yes IE9 supports SVG's, but in order for a graceful fallback be provided for 
earlier IE users you have to use <object> tags - that's OK that's what the 
Docbook stylesheets generate - except IE9 (and only IE9) won't then display 
either the SVG or the fallback image unless the image has explicit width and 
height attributes.  If that's not bad enough, IE and all the other browsers 
handle the width and height attributes differently.   I'm mean seriously 
what the &&^%$$ does MS think it's doing here?  Anyhow, I simply can't find 
a magic combination of factors that works on all the browsers... possibly 
removing the width/height attributes from the SVG and adding them to the 
HTML only would work (just checked it does work - but content gets blocked 
by default, and breaks PDF generation, besides how do you know what 
attributes to use once they're gone from the SVG?  Two sets of SVG's 
maybe?????), having the attributes on both just totally screws up the IE 
display BTW.   Likewise using <embed> doesn't help at all.

Sorry for the rant, but really, there's no way this should be this hard!

Anyhow, if anyone wants to play, I've committed an equation test page to the 
test project under doc/test.  Just don't use IE.

Still looking for ideas yours, John. 

Re: More equation woes.....

> -----Original Message-----
> From: boost-docs-bounces <at> lists.boost.org [mailto:boost-docs-bounces <at> lists.boost.org] On
Behalf Of
> John Maddock
> Sent: Thursday, February 02, 2012 11:19 AM
> To: Discussion of Boost Documentation
> Subject: [Boost-docs] More equation woes.....
> 
> Some more experimentation reveals that:
> 
> * IE9 will only support the MathJax scripts if the script is loaded from a subdirectory of the one
containing
> the HTML (a non-starter) otherwise you get a security warning (which I missed the first time), and
if you
> either miss the warning or just follow IE9's advice and block the script then all the equations
disappear 

Looks a non-starter 

But MathML should 'just work'. IE9 says clearly

"Note: Your browser does not support Native MathML rendering".

So IE users will not get equations - end of story?

> * I tried using SVG's instead of MathML or Tex, and Oh dear that's as bad  Yes IE9 supports
SVG's,

   - they all look the same, and are nice and sharp and can be magnified without going fuzzy.

Re: More equation woes.....

On 02/02/2012 01:19 PM, John Maddock wrote:

> Still looking for ideas yours, John.

Never tested this myself:

   http://en.wikipedia.org/wiki/MathPlayer

Also, have you tried using an Apache RewriteRule to redirect all MathJax 
requests into subdirectories into a unique location?

Disclaimer: Never heard about MathJax before this.

Mika Heiskanen

Re: More equation woes.....

>> Still looking for ideas yours, John.
>
> Never tested this myself:
>
>   http://en.wikipedia.org/wiki/MathPlayer
>
> Also, have you tried using an Apache RewriteRule to redirect all MathJax 
> requests into subdirectories into a unique location?
>
> Disclaimer: Never heard about MathJax before this.

Unfortunately neither help with offline reading of the docs - we could 
probably get MathJax working acceptably well for online docs - it's reading 
the docs on your hard drive that's the issue.

Cheers, John. 

QuickBook Chapter Numbers

Hi,

Some library documentations start with Chapter 1.0, for example: bimap, 
ICL, and also Boost.Geometry.

Many do have a proper chapter number. How is this number assigned? I 
cannot find the difference between our main QBK and for example that of 
Chrono, which has a proper chapter number.

Should we add a dependency in doc\Jamfile.v2 ?

Because I see this line <implicit-dependency>../libs/chrono/doc//chrono 
it seems logical that geometry (and some other libs) should be added 
there. Is then a chapter number assigned?

Or does it work otherwise?

Thanks, Barend

Why not use the xml catalog in Linux?

Trying to build the boost documentation on openSUSE fails because the
stylesheets are in /usr/share/xml/docbook/stylesheet/nwalsh/current (a
symlink to the current version) and not in
/usr/share/xml/docbook/stylesheet/nwalsh where boost.book searches. This
begs the question why you check that at all on Linux. All standard stylesheets and
dtds can be found via the catalog so /etc/xml/catalog is the only thing that
needs to be referenced besides the boost.book specific stuff.

Being not very familiar with JAM (boost is the only package I maintain for
SLES/openSUSE that uses it), how would I have to change boostbook.jam in
order to conditionally not use docbook-xsl-dir and docbook-dtd-dir?

Currently I simply use the attached patch for boostbook.jam but that doesn't
make it conditional on OS.

Philipp

Index: tools/build/v2/tools/boostbook.jam
===================================================================
--- tools/build/v2/tools/boostbook.jam.orig	2011-06-06 22:36:21.000000000 +0200
+++ tools/build/v2/tools/boostbook.jam	2012-02-29 09:10:31.362992417 +0100
@@ -491,40 +491,7 @@ rule generate-xml-catalog ( target : sou
     "  <rewriteURI uriStartString=\"http://www.boost.org/tools/boostbook/dtd/\" rewritePrefix=\"file://$(boostbook-dtd-dir)/\"/>"
     : true ;

-  local docbook-xsl-dir = [ boostbook.docbook-xsl-dir ] ;    
-  if ! $(docbook-xsl-dir) 
-  {
-    ECHO "BoostBook warning: no DocBook XSL directory specified." ;

Re: Why not use the xml catalog in Linux?

On 29 February 2012 10:10, Philipp Thomas <pth <at> suse.de> wrote:
> Trying to build the boost documentation on openSUSE fails because the
> stylesheets are in /usr/share/xml/docbook/stylesheet/nwalsh/current (a
> symlink to the current version) and not in
> /usr/share/xml/docbook/stylesheet/nwalsh where boost.book searches.

You can set the path in your user-config.jam file. Something like:

using boostbook : /usr/share/xml/docbook/stylesheet/nwalsh/current ;

> This
> begs the question why you check that at all on Linux. All standard stylesheets and
> dtds can be found via the catalog so /etc/xml/catalog is the only thing that
> needs to be referenced besides the boost.book specific stuff.

I didn't implement it, so I can't say for sure. Probably just to have
a single method for all platforms. It originally required you to
explicitly specify the paths, checking known locations is a pretty
recent addition.

There are problems with relying on the standard catalog. There's a
fairly good chance that on some machines it won't be correct, or will
be missing an entry. For example, if the stylesheets were installed
manually or the packaged versions were uninstalled badly.

> Being not very familiar with JAM (boost is the only package I maintain for
> SLES/openSUSE that uses it), how would I have to change boostbook.jam in
> order to conditionally not use docbook-xsl-dir and docbook-dtd-dir?
>
> Currently I simply use the attached patch for boostbook.jam but that doesn't