Re: [boost] [fusion] html docs woes

Subject: Re: [boost] [fusion] html docs woes
From: Eric Niebler (eric_at_[hidden])
Date: 2011-07-18 02:33:22

On 7/17/2011 9:02 PM, Joel de Guzman wrote:
> On 7/18/2011 11:07 AM, Eric Niebler wrote:
>>
>> On 7/17/2011 3:18 AM, Joel de Guzman wrote:
>>> On 7/17/2011 5:50 PM, Daniel James wrote:
>>>>> * No way for folks to read the HTML until it's actually released.
>>>
>>>> I upload the trunk documentation on the sourceforge sandbox site every
>>>> time I build it, and there are redirects in subversion to take you
>>>> there.
>>>
>>> That's a very good compromise. The only drawback is that
>>> it requires an Internet connection, which is a PITA if you
>>> have to go offline and don't have access to the docs. This
>>> happens to me a lot of times and I hate it when it does.
>>
>> If you know you are going offline, you can just build Fusion's docs from
>> the source locally. Proto's docs are both integrated into the main doc
>> build as well as build-able standalone. To do it, you just go to
>> libs/proto/doc and type bjam. Blam-o! local HTML docs that you can read
>> offline in a jiffy. (That's also how I test that Proto's docs build
>> correctly and look good.)
> 
> Sure, but again, that requires you to be quickbook/docbook savvy.
> I have no problem with it, but I do not want to require the users
> to have to install the tool-chain just to be able to read the docs.
> We all know how painful that is. So essentially, we are telling users:
> if you want to read the docs, you must either be online, or be
> quickbook-savvy and gen the docs yourself.

Or use the docs from a released version of boost that you have saved
locally, which (I guess) is how the majority of people do it. So in
essence, I'm echoing what Phil Richards said previously: the developers
working with the svn tree are a different category as boost's end-users.

Isn't it safe to assume that if you're using svn (which requires a net
connection to do anything useful), then you have net access? In essence,
you're optimizing for svn users who don't have net access and aren't
savvy enough to set up the doc toolchain. I'd wager that that's a set
with a very small membership. :-/

-- 
Eric Niebler
BoostPro Computing
http://www.boostpro.com