Re: [boost] [fusion] html docs woes

Subject: Re: [boost] [fusion] html docs woes
From: Thomas Heller (thom.heller_at_[hidden])
Date: 2011-07-18 03:12:12

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.