Re: [boost] Improving Boost Docs

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.

M