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

Subject: Re: [boost] [Range] Proposal: a sub-maintainer of Boost.Range
From: Michel Morin (mimomorin_at_[hidden])
Date: 2013-01-03 02:34:39

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.

> 2. libs/range/doc/reference/adaptors/examples/adjacent_filtered.cpp
>    (seems to be the exact same as the code snippet).

> 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.

Regards,
Michel