Subject: Re: [boost] Improving Boost Docs
From: Robert Ramey (ramey_at_[hidden])
Date: 2017-08-14 16:00:53
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
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)>
> Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Boost list run by bdawes at acm.org, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk