Re: [boost] Improving Boost Docs

Subject: Re: [boost] Improving Boost Docs
From: John Maddock (jz.maddock_at_[hidden])
Date: 2017-08-14 17:37:52

> The main objection to the quickbook - boostbook - doxygen way of 
> generating documentation, as I understand it, is that it is very hard 
> to generate a different look-and-feel to the documentation from the 
> standard one created by the stylesheets. OTOH others think having the 
> same look-and-feel of all Boost docs is an advantage. So I do not 
> think there is any way around this basic disagreement.

If you want a different look and feel, then yes things could be a lot 
better.  However, within boost the consistency is a good thing IMO.

BTW the look and feel is in 2 parts:

* Different stylesheet, fluorescent dancing C++ keywords etc.... this is 
actually trivial to do.
* Different Docbook customisation layer (and yes there are some 
formatting options that can only be addressed in XSL, not in XSL 
params).  This is the hard one - or at least its the hard one if we're 
using Jamfiles.  From the command line it's trivial if you don't mind 
writing a... ahem... makefile ;)

BTW is there any reason to continue using the Boostbook customisation 
layer?  Is anyone actually using it?  I'm fairly sure quickbook doesn't, 
and it would sure simplify the build process to leave out one level of 
XSL transformation.  Sadly we would need an XSL expert to sort that mess 
out I suspect :(

>
> I do understand that other issues have been mentioned, such as lack of 
> support for diagrams ( graphviz ? ) or formulas ( MathML ? ) directly 
> in quickbook. 

Since graphviz can generate SVG's, it would I assume be trivial for 
quickbook to shell out to "dot" to render inline graphviz text.  Or you 
can just invoke it yourself (though I accept this may be less convenient).

Equations are probably a more pressing need, and IMO it's a problem that 
no one has properly solved (unless you live entirely within the LatTex 
universe perhaps).  MathML is useless as a format to write in, comes in 
2 flavours (presentation and content with different tools supporting 
each - for example last I checked OpenOffice generates content, but most 
presentation tools expect presentation format).   MathJax almost 
completely solves these issues, and looks quite lovely... but... because 
it relies on external Javascript files, it gets blocked by browsers 
unless everything is on the server (ie not on the local disk).   
Boost.Math renders it's equations as SVG's which works well, but it's a 
pain to author them separately from the actual text.  I'm sure we would 
have more/better equations if they were inline in the quickbook.  We 
could embed LaTex, but the conversion to SVG appears to be long and 
flaky involving quite a few tools  (though it appears MathJax can do 
this in one step, but there are some comments that it generate "odd" SVG 
XML).  Might be worth looking into though.

Perhaps more pressing is the ability to generate a navigation panel - 
all the information we need is present in the Docbook - and frankly I 
simply cannot believe that the Docbook XSL stylesheets don't support 
this already (Ah they do - sort of  - via a "webpage" project, but it's 
not vanilla docbook).  Doing it ourselves probably means pre-processing 
the generating HTML or something similarly yucky :(

> But we have the source for quickbook and can modify it accordingly, so 
> I do not think that quickbook is itself the problem. I do agree that 
> writing directly in boostbook ( or docbook ) is a real pain, which I 
> have always found I could forgo, but quickbook has always been 
> supremely easy to use for me.

+1, me too!

John.

---
This email has been checked for viruses by AVG.
http://www.avg.com