Re: [boost] Do we need BoostBook?

Subject: Re: [boost] Do we need BoostBook?
From: Robert Ramey (ramey_at_[hidden])
Date: 2014-12-06 02:43:34

Vladimir Prus-3 wrote
>> Maybe the question you might want to ask is ... Should QuickBook be
>> altered
>> to produce html directly?
> 
> QuickBook, likewise, is not required. So the question I really want to ask
> is what
> people's opinion about best documentation solution in 2014. It's
> intentionally
> open-ended.

FWIW the serialization library is still raw html.  I did it that way before
any
tools were around and I've never been motivated convert it to something
else.
I always disliked XML mainly due to its verbosity and I didn't like it's
complexity
either. In the course of writing up my take on this subject for the
incubator
I only required that a submitted library have some sort of online browsable
documentation in html.
http://rrsd.com/blincubator.com/requirements_documentation/

I also spent some time looking at all the alternatives for making
documentation
and posted my conclusions here:
http://rrsd.com/blincubator.com/tools_documentation/
Naturally preferences are going to differ on this and if you would like to
advice
library authors to use raw html,  you could post your own comments on that
page.

My preferred solution has failed to catch on - oh well. 

In any case, I think we want to stick the current and historical policy
of letting each author handle it his preferred way. We could never
agree on how to do this and I don't think it's worth trying to. 

On the other hand, I'm VERY convinced that we should be 
making much more of an effort to demand better documentation content
for boost libraries.  Of course that's a different topic.

Robert Ramey

--
View this message in context: http://boost.2283326.n4.nabble.com/Do-we-need-BoostBook-tp4669821p4669826.html
Sent from the Boost - Dev mailing list archive at Nabble.com.