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. As an aside, making the original version of the documentation was an unbelievably contentious exercise involving acrimonious disputes between David Abrahams and myself mostly. What came out of this was: a) Concepts must be addressed explicitly in the documentation of any C++ library which uses templates. b) Concept checking must be part of any C++ library code which uses template parameters. c) "Concept" is a very, very, very unfortunate choice for the idea. It's very misleading and confusing and has led many, many people to understand the idea. This believe is behind my preference for the term "Type Requirements" when I can get a way with this. d) A long, contentious, strident, mailing list interaction with David Abrahams has to be the most unpleasant, and likely most unproductive way to learn anything. I've tried to keep this mind when promoting the concept of "Concepts" (Damn - there's the confusion about "concept" again)> Robert Ramey
Regards, &rzej;
_______________________________________________ Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost