Re: [boost] [fusion] html docs woes

Subject: Re: [boost] [fusion] html docs woes
From: Joel de Guzman (joel_at_[hidden])
Date: 2011-07-18 03:33:17

On 7/18/2011 3:12 PM, Thomas Heller wrote:
> On Sunday, July 17, 2011 11:33:22 PM Eric Niebler wrote:
>> 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. :-/
> 
> I wouldn't necessarily say so. For one, the doc toolchain setup is not very 
> easy and second, the docs take quite a while to build.
> Additionally, if i just instruct the user: go checkout current trunk for 
> feature X, I can directly point her to the svn url to the documentation of 
> said feature, even before he checks out the complete svn trunk.

I think what Eric is saying is that if you have to update from SVN anyway,
then Daniel James's solution is reasonable: redirects in subversion
to take you to the rebuilt docs, which means that 1) when you do a regen
of the docs, you don't commit the HTML pages 2) You upload the docs somewhere
where you can redirect to.

Seems reasonable...

What I am not sure about is that it seems that the steps needed to do this
is basically the same (or even more laborious ?) than just committing the
HTMLs. After all, quickbook/docbook is now better at avoiding extra diffs
from regens.

Regards,
-- 
Joel de Guzman
http://www.boostpro.com
http://boost-spirit.com