Re: [boost] [GSoC] [Boost.Hana] Formal review request

Subject: Re: [boost] [GSoC] [Boost.Hana] Formal review request
From: Paul A. Bristow (pbristow_at_[hidden])
Date: 2014-07-31 10:15:38

> -----Original Message-----
> From: Boost [mailto:boost-bounces_at_[hidden]] On Behalf Of Louis Dionne
> Sent: 31 July 2014 14:16
> To: boost_at_[hidden]
> Subject: Re: [boost] [GSoC] [Boost.Hana] Formal review request
> 
> Paul A. Bristow <pbristow <at> hetp.u-net.com> writes:
> >
> > Excellent!  (Are they *live* links, updating the docs when you modify
> > the
> > example?)
> 
> Well, I currently update the documentation by hand:
> 
>     make gh-pages.update
>     cd doc/gh-pages && git push
> 
> The first command regenerates the doc and creates the commit on the gh-pages
> branch, and then I push it after a quick validation on my part. So the
examples are
> always up-to-date, but the whole process could surely be more automatic.
> Something like a post commit hook could regenerate the doc, but I don't know
how
> to set that up and I've more urgent things to do right now.

That isn't quite what Quickbook does - it marks the start and end of the snippet
in the example .cpp.

So What You Mark is What You Get - always.

No eyeballing!
 
> > How about an alphabetic index of functions, names, words, concepts, ideas
...?
> >
> > We are used to using the index in books, but they are less common in e-docs.
> > Despite hyperlinks, navigation and search are still troublesome.
> > I find the index really useful when dealing with the monster
> > Boost.Math docs - and I wrote some of it!
> 
> I disabled the index because I thought the documentation was best browsed by
using
> the type classes structure. Of course, this implies that one knows which
methods are
> in which type class, and that's circular. I'll see if the Doxygen-generated
index makes
> some sense and I'll re-enable it if it does.

I recommend this - makes docs bigger by who cares?

But Doxygen index isn't an index like a book - to words etc in the body of the
text.

So if you don't know the name of the function, you are stuck.

Most of us are blindly using a Famous Search Engine - with mixed results in my
experience.

However, your docs are at least as good as most, and I think this issue of
finding things is still largely unsolved.

I'd concentrate on other issues.

Good luck

Paul