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.
Boost list run by bdawes at acm.org, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk