-----Original Message----- From: Boost [mailto:boost-bounces@lists.boost.org] On Behalf Of Louis Dionne Sent: 31 July 2014 14:16 To: boost@lists.boost.org Subject: Re: [boost] [GSoC] [Boost.Hana] Formal review request
Paul A. Bristow
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