Re: [Boost-docs] Sphinx integration

Subject: Re: [Boost-docs] Sphinx integration
From: Dave Abrahams (dave_at_[hidden])
Date: 2011-10-05 16:25:32

on Wed Oct 05 2011, "Paul A. Bristow" <pbristow-AT-hetp.u-net.com> wrote:

>> on Wed Oct 05 2011, "Paul A. Bristow" <pbristow-AT-hetp.u-net.com>
> wrote:
>> 
>> >> -----Original Message-----
>> >> [mailto:boost-docs-bounces_at_[hidden]] On Behalf Of Dave
>> >> Abrahams
>
>> *reads* <exaggeration> The need to escape "<" signs in Doxygen
>> comments makes me ill </exaggeration>
>
> What a delicate constitution ;-)

quite.

> But anyway Doxygen comments don't usually have "<" (it's only if you
> want to pin the comment to a particular line).

Or if you want to describe a template specialization.  Never happens in
Boost code, though, I'm sure ;-)

> And it comes out in your comment color, so you don't even 'see' it if
> you are reading C++.

? I think we must be referring to different things.

>> This PDF was produced by FOP, right?  It's horrible to look at (no
>> offense).
>
> Well I like it!  I even slightly prefer it to the html.  And it's a
> single file - easy to send, save and store.  Well opinions vary, but
> whole point is that from Quickbook toolchain you get either or both.

And my point is that nobody should be forced to read FOP-generated PDFs
when we can generate them with LaTeX :-)

>  > Those links are broken
>
> Ah yes - sorry - some are not in SVN  :-(
>
>> Anyway, I confess that I find the presentation of Boost's HTML docs
>> off-putting too.  Maybe I'm just in a grouchy mood this morning.
>> Before I can even appreciate what's been done I think I might need to
>> redesign Boost's stylesheet :(
>
> I think we need to ask the *users* what *they* want to read.
>
> We won't get a unanimous view I'm sure, but it should be a better
> guide than the developers preferences.

I'm not so sure.  The universe of design options is so vast that I think
users need to be presented with alternatives.  I find
http://cpp-next.com far easier to read than most of the Boost pages, for
example.

-- 
Dave Abrahams
BoostPro Computing
http://www.boostpro.com