Re: [boost] Asynchronous library now in Boost Library Incubator

Subject: Re: [boost] Asynchronous library now in Boost Library Incubator
From: Paul A. Bristow (pbristow_at_[hidden])
Date: 2016-12-01 05:27:32

> -----Original Message-----
> From: Boost [mailto:boost-bounces_at_[hidden]] On Behalf Of Christophe Henry
> Sent: 30 November 2016 20:34
> To: boost_at_[hidden]
> Subject: Re: [boost] Asynchronous library now in Boost Library Incubator
> 
> >I'm trying to digest the docs for this monster work.
> >
> >One things that strikes me immediately is that the doc preparation
> >does not use code snippets, and so code is in boring old
> >black'n'white rather than colored syntax.
> >For me, that makes it significantly harder to read (and understand) the
> code examples.
> 
> Ok, I'll see if I can improve this.
> 
> >It also means that one doesn't have the assurance that 'What You See is
> What Compiles'.
> 
> For most features, the doc provides a link to an example, which I regularly
> compile.
> 
> >(I've also having trouble finding things in all the plentiful 'good
> stuff'.
> >But that's a common (and largely still unsolved)
> >problem with all documentation.)

> Please let me know what is the "good stuff" for you and I'll make it more
visible.

It isn't visibility that's the problem, it's the seeing the wood for the trees.
The more good stuff you write, the more trees there are and the more difficult it is to get to what you want.

Indexes and the 'find key' are two helpers. 

With html, you can't use the 'find key' in the *whole* docs, so you can't get to all the references to, say', "future".  Searching
*all* the document is why Google does so well for us.

I googled "boost quickbook code snippets" and got to a page, but I had to use the 'find key' to get to the info I wanted to give
you.

Code Snippet Markup

Note how the code snippets in stub.cpp get marked up. We use distinguishable comments following the form:

//[furtures_example_1
  some code here
...
//] [/furtures_example_1]

(Hint: A  [/furtures_example_1]    comment here helps you avoid mismatched 'brackets' confusion).

My experience of maintaining Boost.Math is that it is all too easy to alter the example code, but forget to alter the copy'n'pasted
part into the docs.

Recommended.

Paul

---
Paul A. Bristow
Prizet Farmhouse
Kendal UK LA8 8AB
[phone]