Re: [boost] Improving Boost Docs

Subject: Re: [boost] Improving Boost Docs
From: Andrzej Krzemienski (akrzemi1_at_[hidden])
Date: 2017-08-16 08:26:47

2017-08-14 18:00 GMT+02:00 Robert Ramey via Boost <boost_at_[hidden]>:

> 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;