Subject: Re: [boost] Improving Boost Docs
From: Soul Studios (matt_at_[hidden])
Date: 2017-08-15 03:53:35
> You can take a look at the doc jamfile in numerous Boost libraries that
> use quickbook to see how to set things up, including my own tti or vmd.
> The main dependency for quickbook is boostbook/docbook, with alternate
> dependencies on auto_index and doxygen. That is 3, not 12.
A 'main' dependency is not 'all' dependencies.
I can't even find the documentation I tried to follow in order to do it,
but when I tried to build it, there were about 12 dependencies (it
may've shrunk since then, I don't know). XSLT, java, various others.
Most of them had no documentation.
You can break it down in a way that makes it sound like less than it is,
but overall I'm just not interested in the system.
> I understand the frustration in the almost total lack of formal docs for
> going from quickbook to html/pdf. But quickbook itself is a piece of
> cake, is very well documented, and blissfully easy to specify most
> everything you need to do in creating library documentation.
I think if you're already familiar with all of the technologies
involved, it's easy. But it's actually not from the point of view of
someone coming in on the 'ground floor'. I don't waste what little
energy I have learning technologies merely to build docs.
There seems to be tacit disapproval, reading through this, of people
building straight HTML for documentation, and I think that's a real shame.
I worked in XML/XSLT once and I understand the advantages, but if boost
is around longer than HTML, I'll be very, very surprised. And the
disadvantages of complication for something as transitory as a code
library is not worth it.
Boost list run by bdawes at acm.org, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk