Subject: Re: [boost] Improving Boost Docs
From: Edward Diener (eldiener_at_[hidden])
Date: 2017-08-14 15:15:37
On 8/14/2017 10:37 AM, Robert Ramey via Boost wrote:
> On 8/14/17 12:40 AM, Andrzej Krzemienski via Boost wrote:
>> I do not know anything about the project, so I am not really addressing
>> your question,but I wonder how it is possible to get a unified look and
>> feel across all the libraries when library authors are given freedom
>> to use
>> whatever format for their documentation, whatever tool, and whatever
>> approach to documentation.
> I don't think it is possible.
> This leaves us with a couple of options:
> a) Enforce the usage of boost book for documentation as condition of
> acceptance and inclusion of a library in boost. This would guarantee
> consistent look and feel across libraries.
> b) Encourage everyone to "do their own thing". Which would almost
> certainly result in a wide variation of look and field.
> c) Improve the boostbook documentation and related tooling to make it so
> compelling that only an idiot or egomaniac would decide not to use it.
> This would be the best of course. But it's a lot of work and we're not
> there yet. And of course in any large organization, there's always a
> couple of idiots/ecomaniacs or people who act that way on an occasional
> Actually, this was the motivation for my post. I think when this
> initiative was announced we were on the right track. But I think we
> lost our way on this one. I don't know if it's possible to all get back
> on the same page, but it would be a good thing if we could.
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.
I do understand that other issues have been mentioned, such as lack of
support for diagrams ( graphviz ? ) or formulas ( MathML ? ) directly in
quickbook. 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.
> Robert Ramey