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).
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
Ouch - and would close the door to pdf and ebook versions of the output. 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