Tagging the minimum C++ standard level for Boost libs
I had previously proposed that we tag the minimum C++ standard level for Boost libs by adding information to the json meta information in libraries.json for each library. I would like to revisit that proposal, which involved more elaborate suggestions, with this simpler overall proposal: for each Boost C++ library whose minimum C++ standard level is C++11 or above we add a json field called 'cxxstd' whose value corresponds to one of the same values as currently exists in Boost.Build for the 'cxxstd' feature, ie. 11,14,17,20, to the libraries.json file for that library. This json value can then be used in Boost documentation of each library to specify the minimum C++ standard level needed by an end-user in order to use that library. Obviously we can also add "cxxstd": "03" for the many Boost libraries which can still be used at the C++98/C++03 compilation level also, even though I would argue that not having a "cxxstd" json field should mean C++98/C++03 by default. I would be willing to create the necessary PRs for each library, as I have a pretty good internal list of this information. The gist of this proposal is to make it much easier for end-users wishing to use a Boost library to immediately know whether the library they wish to use is usable at the C++ standard compilation level they are using for compilation, without having to spend time searching for such information, which is often not readily available, in the documentation of the library they are considering. I can go ahead and start doing this now, but of course I am willing to listen to what others think about this. But let's not let another round of inertia stop doing at all what should be a simple means of telling end-user's whether a Boost library is at least minimally usable by them in their C++ projects.
Edward Diener wrote:
I had previously proposed that we tag the minimum C++ standard level for Boost libs by adding information to the json meta information in libraries.json for each library. I would like to revisit that proposal, which involved more elaborate suggestions, with this simpler overall proposal: for each Boost C++ library whose minimum C++ standard level is C++11 or above we add a json field called 'cxxstd' whose value corresponds to one of the same values as currently exists in Boost.Build for the 'cxxstd' feature, ie. 11,14,17,20, to the libraries.json file for that library. This json value can then be used in Boost documentation of each library to specify the minimum C++ standard level needed by an end-user in order to use that library. Obviously we can also add "cxxstd": "03" for the many Boost libraries which can still be used at the C++98/C++03 compilation level also, even though I would argue that not having a "cxxstd" json field should mean C++98/C++03 by default. I would be willing to create the necessary PRs for each library, as I have a pretty good internal list of this information.
The gist of this proposal is to make it much easier for end-users wishing to use a Boost library to immediately know whether the library they wish to use is usable at the C++ standard compilation level they are using for compilation, without having to spend time searching for such information, which is often not readily available, in the documentation of the library they are considering.
I see nothing wrong with adding this field to meta/libraries.json. However, libraries.json is not for end users. It's input to the scripts that generate the libraries page. So if we add the field, we should also change the scripts to read it and display it in the library list. Unfortunately all those scripts were written and maintained by Daniel James who isn't available, so someone else would need to figure this out.
On 12/15/2020 1:14 PM, Peter Dimov via Boost wrote:
Edward Diener wrote:
I had previously proposed that we tag the minimum C++ standard level for Boost libs by adding information to the json meta information in libraries.json for each library. I would like to revisit that proposal, which involved more elaborate suggestions, with this simpler overall proposal: for each Boost C++ library whose minimum C++ standard level is C++11 or above we add a json field called 'cxxstd' whose value corresponds to one of the same values as currently exists in Boost.Build for the 'cxxstd' feature, ie. 11,14,17,20, to the libraries.json file for that library. This json value can then be used in Boost documentation of each library to specify the minimum C++ standard level needed by an end-user in order to use that library. Obviously we can also add "cxxstd": "03" for the many Boost libraries which can still be used at the C++98/C++03 compilation level also, even though I would argue that not having a "cxxstd" json field should mean C++98/C++03 by default. I would be willing to create the necessary PRs for each library, as I have a pretty good internal list of this information.
The gist of this proposal is to make it much easier for end-users wishing to use a Boost library to immediately know whether the library they wish to use is usable at the C++ standard compilation level they are using for compilation, without having to spend time searching for such information, which is often not readily available, in the documentation of the library they are considering.
I see nothing wrong with adding this field to meta/libraries.json. However, libraries.json is not for end users. It's input to the scripts that generate the libraries page. So if we add the field, we should also change the scripts to read it and display it in the library list.
Of course !
Unfortunately all those scripts were written and maintained by Daniel James who isn't available, so someone else would need to figure this out.
I can look at it once this information is added to libraries.json where appropriate. Without looking I will guess that Daniel James used Python, which I know pretty well, but if it is something else it should not be impossible to figure out.
On Tue, Dec 15, 2020 at 2:35 PM Edward Diener wrote:
I can look at it once this information is added to libraries.json where appropriate. Without looking I will guess that Daniel James used Python, which I know pretty well, but if it is something else it should not be impossible to figure out.
https://github.com/boostorg/website/blob/master/common/code/boost_library.ph... Glen
On 12/15/2020 2:50 PM, Glen Fernandes via Boost wrote:
On Tue, Dec 15, 2020 at 2:35 PM Edward Diener wrote:
I can look at it once this information is added to libraries.json where appropriate. Without looking I will guess that Daniel James used Python, which I know pretty well, but if it is something else it should not be impossible to figure out.
https://github.com/boostorg/website/blob/master/common/code/boost_library.ph...
Thanks ! I can do php if necessary, but then most anybody can also do php <g>. I will look at updating the code once I get all the individual C++11 on up libraries to except the PRs for updating their libraries.json. The code can always wait until the rest is done first. If anybody else who is probably more knowledgeable than me regarding php wants to update the website code they can of course do it if they like.
On 12/15/2020 3:26 PM, Vinnie Falco via Boost wrote:
On Tue, Dec 15, 2020 at 10:14 AM Peter Dimov via Boost <boost@lists.boost.org> wrote:
Unfortunately all those scripts were written and maintained by Daniel James who isn't available, so someone else would need to figure this out.
Sam Darwin can and should do this.
Is he active on this list ? Does he have an email and should I contact him there or should I add an Issue for the boostorg.website git ?
On Tue, Dec 15, 2020 at 12:43 PM Edward Diener via Boost <boost@lists.boost.org> wrote:
Sam Darwin can and should do this.
Is he active on this list ? Does he have an email and should I contact him there or should I add an Issue for the boostorg.website git ?
Sam is on cpplang Slack as Sam Darwin Thanks
On 12/15/2020 7:35 PM, Vinnie Falco via Boost wrote:
On Tue, Dec 15, 2020 at 12:43 PM Edward Diener via Boost <boost@lists.boost.org> wrote:
Sam Darwin can and should do this.
Is he active on this list ? Does he have an email and should I contact him there or should I add an Issue for the boostorg.website git ?
Sam is on cpplang Slack as Sam Darwin
Why do you say he can and should program the website doc page ?
On 12/15/2020 1:14 PM, Peter Dimov via Boost wrote:
Edward Diener wrote:
I had previously proposed that we tag the minimum C++ standard level for Boost libs by adding information to the json meta information in libraries.json for each library. I would like to revisit that proposal, which involved more elaborate suggestions, with this simpler overall proposal: for each Boost C++ library whose minimum C++ standard level is C++11 or above we add a json field called 'cxxstd' whose value corresponds to one of the same values as currently exists in Boost.Build for the 'cxxstd' feature, ie. 11,14,17,20, to the libraries.json file for that library. This json value can then be used in Boost documentation of each library to specify the minimum C++ standard level needed by an end-user in order to use that library. Obviously we can also add "cxxstd": "03" for the many Boost libraries which can still be used at the C++98/C++03 compilation level also, even though I would argue that not having a "cxxstd" json field should mean C++98/C++03 by default. I would be willing to create the necessary PRs for each library, as I have a pretty good internal list of this information.
The gist of this proposal is to make it much easier for end-users wishing to use a Boost library to immediately know whether the library they wish to use is usable at the C++ standard compilation level they are using for compilation, without having to spend time searching for such information, which is often not readily available, in the documentation of the library they are considering.
I see nothing wrong with adding this field to meta/libraries.json. However, libraries.json is not for end users. It's input to the scripts that generate the libraries page. So if we add the field, we should also change the scripts to read it and display it in the library list.
Unfortunately all those scripts were written and maintained by Daniel James who isn't available, so someone else would need to figure this out.
Does anybody else understand the Boost website and how it is programmed ? I can see the PHP code but I am not sure how this code is being called from the web pages or how web pages are being generated through the code. I have worked in the past with PHP before, it is not a complicated language, but I do not understand the interaction between the code and the web pages.
Am 15.12.20 um 18:12 schrieb Edward Diener via Boost:
Obviously we can also add "cxxstd": "03" for the many Boost libraries which can still be used at the C++98/C++03 compilation level also, even though I would argue that not having a "cxxstd" json field should mean C++98/C++03 by default.
I would not treat a missing cxxstd as "C++03" because that makes the proposal mostly useless: Your goal was to tell end users whether they can use the library given their std level. Now you treat libraries with missing information as "compatible with everything" so end users will become confused and annoyed and will ultimately not use this. I'd hence make it explicit and never assume. BTW: This will ultimately end up at (e.g.) https://www.boost.org/doc/libs/1_75_0/, won't it? Or where would that be displayed? If so the field "Standard" should be clarified. I'm not sure what it means here and it often is empty (which I'd simply remove)
On 12/16/2020 2:51 AM, Alexander Grund via Boost wrote:
Am 15.12.20 um 18:12 schrieb Edward Diener via Boost:
Obviously we can also add "cxxstd": "03" for the many Boost libraries which can still be used at the C++98/C++03 compilation level also, even though I would argue that not having a "cxxstd" json field should mean C++98/C++03 by default.
I would not treat a missing cxxstd as "C++03" because that makes the proposal mostly useless: Your goal was to tell end users whether they can use the library given their std level. Now you treat libraries with missing information as "compatible with everything" so end users will become confused and annoyed and will ultimately not use this. I'd hence make it explicit and never assume.
All I meant here is that no 'cxxstd' field for a library means C++03 as the minimal level. How we decide to display this to the end-user can be discussed and I will go along with whatever others think is best. Obviously we can display the library information by specifying C++03 as the minimal level, or adversely we can display nothing for that given library as a C++ minimal standard level, including even the mention of a "Minimum C++ standard compilation level', and let the user assume that since nothing is displayed the library is usable with any C++ standard level.
BTW: This will ultimately end up at (e.g.) https://www.boost.org/doc/libs/1_75_0/, won't it? Or where would that be displayed?
The idea is that upcoming release docs would incorporate the information, but I am not adverse showing this for 1.75 if people want that.
If so the field "Standard" should be clarified. I'm not sure what it means here and it often is empty (which I'd simply remove)
I agree, and some better, and longer phrase than just 'standard' should probably be chosen. I do believe the phrase was meant to specify the C++ standard release in which the library was accepted as a C++ standard library, but I have no idea what meta information, with what sort of value, was supposed to supply this information.
I would not treat a missing cxxstd as "C++03" because that makes the proposal mostly useless: Your goal was to tell end users whether they can use the library given their std level. Now you treat libraries with missing information as "compatible with everything" so end users will become confused and annoyed and will ultimately not use this. I'd hence make it explicit and never assume.
BTW: This will ultimately end up at (e.g.) https://www.boost.org/doc/libs/1_75_0/, won't it? Or where would that be displayed? The idea is that upcoming release docs would incorporate the information, but I am not adverse showing this for 1.75 if people want
All I meant here is that no 'cxxstd' field for a library means C++03 as the minimal level. How we decide to display this to the end-user can be discussed and I will go along with whatever others think is best. Obviously we can display the library information by specifying C++03 as the minimal level, or adversely we can display nothing for that given library as a C++ minimal standard level, including even the mention of a "Minimum C++ standard compilation level', and let the user assume that since nothing is displayed the library is usable with any C++ standard level. But that would be wrong, wouldn't it? A C++11 library which hasn't merged the PR adding the cxxstd field (there are quite some inactive ones) would be shown/treated as "C++03 is the minimum required", which is not correct. So I'd rather not display anything if the information is missing to show exactly that: No information is available. Authors who care will then add this information as appropriate. that. Sorry, didn't mean 1.75 specifically, only this page. So one can rather watch https://www.boost.org/doc/libs/develop I guess
BTW: That pages show "Revised $Date$" at the bottom And the new field needs to be added at https://www.boost.org/development/library_metadata.html
If so the field "Standard" should be clarified. I'm not sure what it means here and it often is empty (which I'd simply remove)
I agree, and some better, and longer phrase than just 'standard' should probably be chosen. I do believe the phrase was meant to specify the C++ standard release in which the library was accepted as a C++ standard library, but I have no idea what meta information, with what sort of value, was supposed to supply this information.
I would just remove it. On the above docu page it says: std: A list of the standardization status of the library. Currently just supports 'tr1' for included in TR1 and 'proposal' for a current proposal. Will add more in the future.. At the current state "more" wasn't added and all information is pretty much outdated
On 12/16/2020 3:52 AM, Alexander Grund via Boost wrote:
I would not treat a missing cxxstd as "C++03" because that makes the proposal mostly useless: Your goal was to tell end users whether they can use the library given their std level. Now you treat libraries with missing information as "compatible with everything" so end users will become confused and annoyed and will ultimately not use this. I'd hence make it explicit and never assume.
All I meant here is that no 'cxxstd' field for a library means C++03 as the minimal level. How we decide to display this to the end-user can be discussed and I will go along with whatever others think is best. Obviously we can display the library information by specifying C++03 as the minimal level, or adversely we can display nothing for that given library as a C++ minimal standard level, including even the mention of a "Minimum C++ standard compilation level', and let the user assume that since nothing is displayed the library is usable with any C++ standard level. But that would be wrong, wouldn't it? A C++11 library which hasn't merged the PR adding the cxxstd field (there are quite some inactive ones) would be shown/treated as "C++03 is the minimum required", which is not correct.
I had decided to wait on programming anything on the appropriate web page(s) until all libraries to which I have submitted the PR merged it. This does not have to be a rush job and it will take me some time to figure out the PHP code on the web pages so I can alter them to use the JSON cxxstd value appropriately.
So I'd rather not display anything if the information is missing to show exactly that: No information is available. Authors who care will then add this information as appropriate.
BTW: This will ultimately end up at (e.g.) https://www.boost.org/doc/libs/1_75_0/, won't it? Or where would that be displayed? The idea is that upcoming release docs would incorporate the information, but I am not adverse showing this for 1.75 if people want that. Sorry, didn't mean 1.75 specifically, only this page. So one can rather watch https://www.boost.org/doc/libs/develop I guess
OK, that seems like the right page.
BTW: That pages show "Revised $Date$" at the bottom
And the new field needs to be added at https://www.boost.org/development/library_metadata.html
Thanks for pointing that out.
If so the field "Standard" should be clarified. I'm not sure what it means here and it often is empty (which I'd simply remove)
I agree, and some better, and longer phrase than just 'standard' should probably be chosen. I do believe the phrase was meant to specify the C++ standard release in which the library was accepted as a C++ standard library, but I have no idea what meta information, with what sort of value, was supposed to supply this information.
I would just remove it. On the above docu page it says:
std: A list of the standardization status of the library. Currently just supports 'tr1' for included in TR1 and 'proposal' for a current proposal. Will add more in the future..
At the current state "more" wasn't added and all information is pretty much outdated
I agree with you.
participants (5)
-
Alexander Grund -
Edward Diener -
Glen Fernandes -
Peter Dimov -
Vinnie Falco