Re: [boost] Improving Boost Docs

Subject: Re: [boost] Improving Boost Docs
From: Robert Ramey (ramey_at_[hidden])
Date: 2017-08-15 00:31:14

On 8/14/17 10:37 AM, John Maddock via Boost wrote:
> * 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 ;)

or a simple shell script
> 
> 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 think there's a little more to this:

a) There are special tags like class, struct, etc. etc.  Which permit 
tagging for different aspects of C++ syntax.  Somehow I doubt anyone is 
using this stuff.  It would be pain to edit it and it would presume that 
every class,struct etc would have the same documentation structure which 
might be inconvenient.  Also the documentation for this is reference and 
doesn't give much in the way of sample output etc.  Upshot I'm doubtful 
that anyone is using it.

b) There is the xsl directory which includes special boost extenstions 
to docbook tags.  I'm pretty sure that these matter.  For example it is 
here that the program listing syntax coloring is implemented.  Modifying 
this is very problematic due to xml/xsl syntax and lack of good tools. 
I know this because I have tried to do it.

Due to b) I don't know if you want to leave out this level of 
tranformation.  One can make good looking docs with docbook but it's 
unclear what the boostbook transformation adds here.

>> 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).

This one reason I'm not crazy about quickbook - it's not open ended enough.
> 
> 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).  

Hmm - I had hopes for this.  I'll have to check it out.

> 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). 

Ouch - and would close the door to pdf and ebook versions of the output.

> 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 
I think this is eminently doable and not particularly difficult either. 
The main obstacle is the xsl syntax which is like dragging one's 
fingernails on a chalkboard.  I've toyed with taking it up myself as 
I've had to become more familiar than I wanted to with xsl.  I also made 
the (in)famous navigation panel for the serialization library.  We also 
have a similar but likely better implementation of this idea with the 
streams library.  So this should actually be moved to higher priority. 
Implementing this would create a good incentive to keep using 
boostbook/docbook and use it better since it would only include 
documenation for those libraries which use boost/docbook.  It's a 
textbook example of what xsl is meant to be used for.

>> 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.

To me, there are couple of fatal mistakes

a) creating library documentation (html, pdf) not in the library 
directory but in some "other" directory.
b) invoking the boost documentation build through bjam.

Without this, it would be much easier to tweak ones documentation build 
to get it exactly right.

> +1, me too!
> 
> John.
> 
> 
> 
> ---
> This email has been checked for viruses by AVG.
> http://www.avg.com
> 
> 
> _______________________________________________
> Unsubscribe & other changes: 
> http://lists.boost.org/mailman/listinfo.cgi/boost
>