Re: [boost] [Range] Proposal: a sub-maintainer of Boost.Range

Subject: Re: [boost] [Range] Proposal: a sub-maintainer of Boost.Range
From: Neil Groves (neil_at_[hidden])
Date: 2013-01-03 04:14:15

On Thu, Jan 3, 2013 at 7:34 AM, Michel Morin <mimomorin_at_[hidden]> wrote:

> Nathan Ridge wrote:
> > What is the purpose of having each of the following:
> >
> > 1. The code snippet containing an example of using the
> 'adjacent_filtered'
> >    range adaptor in
> libs/range/doc/reference/adaptors/adjacent_filtered.qbk
>
> This code snippet should be replaced by the example file of 2.
> This can be done using "import" directive:
>
> http://boost-sandbox.sourceforge.net/doc/html/quickbook/syntax/block.html#quickbook.syntax.block.import
> Its qbk file (tools/quickbook/doc/block.qbk) and the imported cpp file
> (stub.cpp) are an good example of how to use "import" directive.
>
>
This is a good suggestion. I didn't realise this was possible. This is the
only reason for the redundancy.

>
> > 2. libs/range/doc/reference/adaptors/examples/adjacent_filtered.cpp
> >    (seems to be the exact same as the code snippet).
>
>
It is the same. I have been aware that of the redundancy, but at the time
failed to find a solution that was practical within my release time frame.
I added tests for all examples so this redundancy is entirely my fault. I
didn't realise there was a better way. Hence if you see something better
please feel free to abandon my suboptimal practices. Feel empowered to do
whatever makes sense. Your recent work has more than earned this freedom.

> > 3. libs/range/test/adaptor_test/adjacent_filtered_example.cpp
> >    (seems to be the exact same plus some Boost.Test stuff)
>
> Hmm..., to remove this redundancy, I think we need to
> add "code snippet markup" to the test file and import it into qbk doc
> (and delete the example file):
>
> http://boost-sandbox.sourceforge.net/doc/html/quickbook/syntax/block.html#quickbook.syntax.block.import.code_snippet_markup
>
> Attached a sample of a marked-up cpp file. The code snippet can be
> imported into adjacent_filtered.qbk by replacing `` ... `` with
>   [import ../../../test/adaptor_test/adjacent_filtered_example.cpp]
>   [foo]
>
> You might want to ask what the best markup for this purpose is
> at Boost.Documentation mailing list.
>
>
This is fantastic! I did not realise this was possible. I hoped and I
looked but I failed to find this feature. Clearly, on reflection, I should
have asked the list.

>
> Regards,
> Michel
>

Thank you Michel and Nathan for your excellent help with Boost.Range.

Regards,
Neil Groves