Re: [Boost-users] Documentation for Boost Range

Subject: Re: [Boost-users] Documentation for Boost Range
From: Paul A. Bristow (pbristow_at_[hidden])
Date: 2016-05-19 04:02:29

> -----Original Message-----
> From: Boost-users [mailto:boost-users-bounces_at_[hidden]] On Behalf Of Christian Aichinger
> Sent: 19 May 2016 06:11
> To: boost-users_at_[hidden]
> Subject: Re: [Boost-users] Documentation for Boost Range
> 
> On 18.05.2016 11:23, Paul A. Bristow wrote:
> > I'm surprised that you think it can't be done with the current Boost docs and examples system,
> > but I haven't looked at it in detail.
> 
> The complication here is the Boost Range adaptors. They have two
> syntaxes (function call and pipe) that I generate from a single source
> file[0]:
> 
>      std::cout << "Reversed abc: "
>                << PARENWRAP(CALL0(boost::adaptors::REVERSE,str))
> 
> generates two files, one with
> 
>      std::cout << "Reversed abc: "
>                << boost::adaptors::reverse(str)
> 
> and one with
> 
>      std::cout << "Reversed abc: "
>                << (str | boost::adaptors::reversed)
> 
> Ideally, I would like to keep it that way, for DRY reasons and to make
> sure the call/pipe examples stay symmetric, so people can compare what
> difference the two syntax makes. I don't know how to do that with bjam
> alone.
> 
> Further, I would like to compile and run the examples, and compare them
> against pre-recorded output to make sure output is as intended, and that
> code/output are in sync. The difficult part here is the file-diffing,
> which I don't really know how to do in bjam alone without calling
> external programs. Might be possible though.

I understand better how difficult a task you have set yourself!

(But I worry that comparing with 'expected' output is combining/confusing testing with documentation?)

Is/could it be possible to change the syntax coloring with change to a (possibly external) CSS files?

A jamfile to run all of these examples would still be really good.

Paul

PS I'd also point out that one could add the examples to Doxygen-syntax comments.
For anyone starting on documenting a new library, this might be easier?  But you didn't start from there...

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