2017-08-14 18:00 GMT+02:00 Robert Ramey via Boost
On 8/14/17 8:29 AM, Andrzej Krzemienski via Boost wrote:
I do not even know if there is a consensus about what "look and feel" is. Is it only the fonts and colors, or is it also the same structure of documentaion in all libraries: short intro first, then tutorial, then reference section. If the latter, according to my knowledge, boostbook does not offer the ability to generate reference from source code annotations, so it might just put off people. You need to set up a collection of additional tools.
No question that addressing this is very difficult.
This apart, some libraries have only plain HTML documentation, and some do
not have it at all, so they would benefit immediately from being converted to boostbook.
Hmmm, that's not all that clear to me. Let's use the serialization library as an example. It is crafted with raw HTML. It uses the boost.css so it looks similar to many of the other boost libraries. It was made before boostbook was available. Writing in HTML was tedious - but not nearly as complicated as using the tools now popular. And once it was done, it was pretty much done. Whenever someone pointed out some error or it needed a small enhancement, it is is pretty simple to update. It's been 15 years without much hassle. What would be actually gained by conversion to boostbook? I don't know that we generate the PDF anymore. It looks pretty close the the official boostbook output. And has my cool documentation navigator which would be lost.
What I actually meant was Boost.Utility. What I don't like about it is the lack of information rather than the tooling. But both the tooling and information could be fixed at the same time, which makes the ratio of benefits to effort more attractive. Regards, &rzej;