Documentation for Boost Range
Boost Range is a cool library, but it's sometimes hard to see how to actually use it: which headers to include, how to call it, what the return types are. To improve this situation, I wrote full, self-contained code examples for each function in Boost Range. They are available at: https://greek0.net/boost-range The examples also include links to the official docs and the into the library's source code, as well as a list of headers that give access to a specific function. I hope it's useful for other people as well. If you have any ideas for improvement, please let me know. Kind regards, Chris
On 5/16/16 2:08 AM, Christian Aichinger wrote:
Boost Range is a cool library, but it's sometimes hard to see how to actually use it: which headers to include, how to call it, what the return types are.
To improve this situation, I wrote full, self-contained code examples for each function in Boost Range. They are available at:
https://greek0.net/boost-range
The examples also include links to the official docs and the into the library's source code, as well as a list of headers that give access to a specific function.
I hope it's useful for other people as well. If you have any ideas for improvement, please let me know.
Kind regards, Chris
This looks like a good effort. Are all the examples tested with a boost build script? I would like to see the author of boost range take a serious look at this to consider adding these examples (and tests there of) to the documenation of the range library. Robert Ramey
On 16.05.2016 17:01, Robert Ramey wrote:
On 5/16/16 2:08 AM, Christian Aichinger wrote:
I wrote full, self-contained code examples for each function in Boost Range. They are available at:
This looks like a good effort. Are all the examples tested with a boost build script?
I would like to see the author of boost range take a serious look at this to consider adding these examples (and tests there of) to the documenation of the range library.
[CC'ing Neil: would you be interested in this?] They are built using a Makefile; the "Output" section below the examples is auto-generated by compiling and executing the code. There is currently no provision to test that the output matches the expected output, but that could be added. I've put the source code up on Github: https://github.com/Grk0/boost-range-for-humans Regards, Chris
On 5/16/16 9:59 AM, Christian Aichinger wrote:
On 16.05.2016 17:01, Robert Ramey wrote:
On 5/16/16 2:08 AM, Christian Aichinger wrote:
I wrote full, self-contained code examples for each function in Boost Range. They are available at:
This looks like a good effort. Are all the examples tested with a boost build script?
I would like to see the author of boost range take a serious look at this to consider adding these examples (and tests there of) to the documenation of the range library.
[CC'ing Neil: would you be interested in this?]
They are built using a Makefile; the "Output" section below the examples is auto-generated by compiling and executing the code. There is currently no provision to test that the output matches the expected output, but that could be added.
I've put the source code up on Github: https://github.com/Grk0/boost-range-for-humans
Hmmm - maybe you might consider the following idea fork the boost range project integrate your examples into the current documentation on your fork submit a PR to the author. If he likes it or maybe he'll just pull it into the main project - problem solved !!!
Regards, Chris
Le 16/05/2016 à 19:30, Robert Ramey a écrit :
On 5/16/16 9:59 AM, Christian Aichinger wrote:
On 16.05.2016 17:01, Robert Ramey wrote:
On 5/16/16 2:08 AM, Christian Aichinger wrote:
I wrote full, self-contained code examples for each function in Boost Range. They are available at:
This looks like a good effort. Are all the examples tested with a boost build script?
I would like to see the author of boost range take a serious look at this to consider adding these examples (and tests there of) to the documenation of the range library.
[CC'ing Neil: would you be interested in this?]
They are built using a Makefile; the "Output" section below the examples is auto-generated by compiling and executing the code. There is currently no provision to test that the output matches the expected output, but that could be added.
I've put the source code up on Github: https://github.com/Grk0/boost-range-for-humans
Hmmm - maybe you might consider the following idea
fork the boost range project
integrate your examples into the current documentation on your fork
submit a PR to the author. If he likes it or maybe he'll just pull it into the main project - problem solved !!!
+1 Vicente
-----Original Message----- From: Boost-users [mailto:boost-users-bounces@lists.boost.org] On Behalf Of Christian Aichinger Sent: 16 May 2016 10:08 To: Boost-users@lists.boost.org Subject: [Boost-users] Documentation for Boost Range
Boost Range is a cool library, but it's sometimes hard to see how to actually use it: which headers to include, how to call it, what the return types are.
To improve this situation, I wrote full, self-contained code examples for each function in Boost Range. They are available at:
https://greek0.net/boost-range
The examples also include links to the official docs and the into the library's source code, as well as a list of headers that give access to a specific function.
I hope it's useful for other people as well. If you have any ideas for improvement, please let me know.
Excellent! This looks a shining example of how examples should be provided as part of the documentation of all Boost (and other) libraries. (A jamfile that runs all these would be useful too, allowing one to easily add others). I'd email to the author directly to discuss how this could be amalgamated with the existing docs. (Using a git fork sounds a good idea, but you might be wasting your time if rejected). Paul --- Paul A. Bristow Prizet Farmhouse Kendal UK LA8 8AB +44 (0) 1539 561830
This looks a shining example of how examples should be provided as part of the documentation of all Boost (and other) libraries.
(A jamfile that runs all these would be useful too, allowing one to easily add others).
a jamfile inside the doc directory which would build/test all the examples is absolutely necessary to finish this job. It would only need to be run on an occasional basis, but it needs to be there.
I'd email to the author directly to discuss how this could be amalgamated with the existing docs.
(Using a git fork sounds a good idea, but you might be wasting your time if rejected).
Paul
--- Paul A. Bristow Prizet Farmhouse Kendal UK LA8 8AB +44 (0) 1539 561830
-----Original Message----- From: Boost-users [mailto:boost-users-bounces@lists.boost.org] On Behalf Of Robert Ramey Sent: 17 May 2016 18:15 To: boost-users@lists.boost.org Subject: Re: [Boost-users] Documentation for Boost Range
This looks a shining example of how examples should be provided as part of the documentation of all Boost (and other) libraries.
(A jamfile that runs all these would be useful too, allowing one to easily add others).
a jamfile inside the doc directory which would build/test all the examples is absolutely necessary to finish this job. It would only need to be run on an occasional basis, but it needs to be there.
+1 Ask on the lists if you need help with this.
Paul
Boost Range is a cool library, but it's sometimes hard to see how to actually use it: which headers to include, how to call it, what the return types are. Missing specification of headers or return types would be defects in
On 16 May 2016 at 10:08, Christian Aichinger
To improve this situation, I wrote full, self-contained code examples for each function in Boost Range. They are available at:
https://greek0.net/boost-range
The examples also include links to the official docs and the into the library's source code, as well as a list of headers that give access to a specific function.
I hope it's useful for other people as well. If you have any ideas for improvement, please let me know.
I have spent a few minutes looking through the examples and they look fabulous. Adding examples can only be a good thing. I'd like to ensure that the reference documentation is not deficient as one effort, and to incorporate your examples as another. I have noted on the thread that there was concern the work might be rejected. This is not the case. So long as the work is correct we'll get it in. My preference is to have a git fork that I can simply merge in. I already have a number of examples included in the bjam that are tested with the regression tests. My examples look nowhere near as beautiful. It would be ideal if I also migrated these onto the tooling you have built. I'd like to have all of the output looking as beautiful.
Kind regards, Chris
Thank you very much for your hard work. I'll try and assist where I can, but at the very least keep out of the way so that I'm not becoming a problem. Regards, Neil Groves
On 17.05.2016 21:08, Neil Groves wrote:
Missing specification of headers or return types would be defects in the reference documentation. I've fixed a few. I did some spot checks and found the expected information. If you have specifics that would be very helpful as they should all be corrected.
I have spent a few minutes looking through the examples and they look fabulous. Adding examples can only be a good thing. I'd like to ensure that the reference documentation is not deficient as one effort, and to incorporate your examples as another. I have noted on the thread that there was concern the work might be rejected. This is not the case. So long as the work is correct we'll get it in. My preference is to have a git fork that I can simply merge in.
I already have a number of examples included in the bjam that are tested with the regression tests. My examples look nowhere near as beautiful. It would be ideal if I also migrated these onto the tooling you have built. I'd like to have all of the output looking as beautiful.
Thank you very much for your hard work. I'll try and assist where I can, but at the very least keep out of the way so that I'm not becoming a problem.
Thank you very much for your kind words, Neil! The way the documentation is built is "Examples to Markdown to HTML". The first step is done by a Make/Shell/Python abomination, the second step is done by my homepage publishing system (Pelican). To integrate it with the Boost Range doc system, I would suggest changing that to "Examples -> QuickBook -> *". But that would still impose a Python dependency on the documentation build. Is that OK for you? Essentially, what I'm doing here can't really be done inside Bjam or QuickBook alone TTBOMK, so I'm wondering what external requirements are OK for you (e.g. Python, common UNIX tooling such such as diff or md5sum to compare expected and found output). Regards, Chris
-----Original Message----- From: Boost-users [mailto:boost-users-bounces@lists.boost.org] On Behalf Of Christian Aichinger Sent: 17 May 2016 22:48 To: boost-users@lists.boost.org Subject: Re: [Boost-users] Documentation for Boost Range
On 17.05.2016 21:08, Neil Groves wrote:
Missing specification of headers or return types would be defects in the reference documentation. I've fixed a few. I did some spot checks and found the expected information. If you have specifics that would be very helpful as they should all be corrected.
I have spent a few minutes looking through the examples and they look fabulous. Adding examples can only be a good thing. I'd like to ensure that the reference documentation is not deficient as one effort, and to incorporate your examples as another. I have noted on the thread that there was concern the work might be rejected. This is not the case. So long as the work is correct we'll get it in. My preference is to have a git fork that I can simply merge in.
I already have a number of examples included in the bjam that are tested with the regression tests. My examples look nowhere near as beautiful. It would be ideal if I also migrated these onto the tooling you have built. I'd like to have all of the output looking as beautiful.
Thank you very much for your hard work. I'll try and assist where I can, but at the very least keep out of the way so that I'm not becoming a problem.
Thank you very much for your kind words, Neil!
The way the documentation is built is "Examples to Markdown to HTML". The first step is done by a Make/Shell/Python abomination, the second step is done by my homepage publishing system (Pelican).
To integrate it with the Boost Range doc system, I would suggest changing that to "Examples -> QuickBook -> *". But that would still impose a Python dependency on the documentation build. Is that OK for you?
Essentially, what I'm doing here can't really be done inside Bjam or QuickBook alone TTBOMK, so I'm wondering what external requirements are OK for you (e.g. Python, common UNIX tooling such such as diff or md5sum to compare expected and found output).
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. However, to the great mass of Microsofties, Python, diff and md5sum jump out as non-standard (but that doesn't necessarily rule them out). Paul PS I really didn't like the colors-on-black display. Syntax coloring is wonderful - but intensely personal. --- Paul A. Bristow Prizet Farmhouse Kendal UK LA8 8AB +44 (0) 1539 561830
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. If anyone has ideas how to handle these two challenges, it'd be great to hear about them! Regards, Chris [0]: http://github.com/Grk0/boost-range-for-humans/blob/master/src/reversed.cpp https://greek0.net/boost-range/boost-adaptors-reverse.html https://greek0.net/boost-range/boost-adaptors-reversed.html
-----Original Message----- From: Boost-users [mailto:boost-users-bounces@lists.boost.org] On Behalf Of Christian Aichinger Sent: 19 May 2016 06:11 To: boost-users@lists.boost.org 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 +44 (0) 1539 561830
participants (6)
-
Christian Aichinger -
degski -
Neil Groves -
Paul A. Bristow -
Robert Ramey -
Vicente J. Botet Escriba