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
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!
--- This email has been checked for viruses by AVG. http://www.avg.com