May 2023 - Boost - lists.preview.boost.org

Full-Text Boost Search
by Mohammad Nejati [Ashtum] 09 May '23

09 May '23

Hi, I'm Mohammed Nejati: a C++ enthusiast, Boost aficionado, and a respecter of good implementation and documentation. I have recently been hired by The C++ Alliance and I am glad that I have a chance to dedicate my time to contribute to the C++ community. We have recently begun to design a new website for boost.org and Boost library documentation: https://github.com/cppalliance/site-docs I am on a quest to add full-text search functionality for the new Boost library documentation website. Now, users can conveniently search in a specific Boost library documentation or all Boost libraries without using an external search engine. A great search experience helps users of libraries quickly refer to the documentation during development. Reference documentation can become more discoverable with a customized search engine. This is as new for me as it likely is for you, and any help and feedback would be appreciated. In the following, I'll explain what we have done and what are our findings so far: We deployed the Antora Lunr Extension on our in-development site docs: https://docs.cppalliance.org/user-guide/index.html Two deployment options exist for search: * In the client. With this model, the index is downloaded to the browser, and the search algorithm is executed using the resources of the browser’s host machine. * In the server. Here the index is hosted in the cloud, and the search algorithm runs on the computing resources of the cloud provider. The client-side strengths: * It is very responsive because there is no request/response involved in the search process. * There is no need for a server-side search engine and keep it updated with new content. * Low maintenance cost because there is no load on the server to respond to search queries. * It can work offline (considering that we can locally build reference documentation). A good example of a client-side search is https://docs.rs/ It is used for searching in the reference documentation for each crate. Here is an example of the search page (searching `socket` in the `Tokio` library): https://docs.rs/tokio/1.28.0/tokio/?search=socket The metadata in these search results is applicable to C++ as well. The server-side strengths: * Wider search scopes: server-hosted search indices can be huge. * Better results: because of more powerful cloud-computing resources. * The possibility of semantic search. * Analytics: server-collected statistics can be used to better serve users. These deployment options are not mutually exclusive; both are deployable, each where appropriate. We are working on a design document for search functionality: https://github.com/cppalliance/site-docs/blob/develop/doc/search-functional…. Please feel free to provide feedback by opening an issue in GitHub or asking questions on the list. We are also currently exploring the possibility of fine-tuning a large language model (LLM) specifically for C++ and Boost-related content. This will be fine-tuned on a vast corpus of code snippets, tutorials, and documentation. Our long-term goal is to create an interactive learning platform where users can ask complex questions in natural language and receive accurate and high-quality answers in return. While this project is still in the experimental stage, we believe that we can create a more engaging and interactive learning experience for users, making it easier for them to learn and use libraries effectively. Thank you for your time, and I look forward to your suggestions and feedback. Best regards, Mohammad Nejati

1 0

Mailgun: Switch back PLEASE
by Vinnie Falco 09 May '23

09 May '23

The lack of threading has surprisingly really bothered me. I didn't realize how important it was until it was broken from the move to Amazon SES. I get that the Boost Foundation is saving some money every month but the mailing list is intolerable now. If the Boost Foundation can authorize Sam Darwin to switch things back to Mailgun, I would be more than happy for them to send us the monthly bill. Vinnie

1 0

Re: [boost] The Future of Boost - deprecating libraries
by Daniele Lupo 09 May '23

09 May '23

Hi from a lurker. Just my two cents about deprecation: I totally agree with deprecation: some libraries are basically not used anymore because they were included in the standard libraries, or because there are better alternatives. Removing them means more focusing on more useful libraries. If a software is stuck with a very old library, they will continue to use that version of boost. It's simple. At least it should be possible to create a bugfix release if needed (i.e. 1.80.1 if the library is removed in 1.81). It's necessary anyway to set some rule about deprecation, so users can handle them properly. The main rule in my opinion is to define the number of releases between the deprecation and the deletion of the library from boost. I.e. it's possible to say that when a library is deprecated, it will be removed from three to five future releases. This gives the users a clear view on the future use of that library: "I'm finishing the project in six months, so it's ok to continue to use it", or "The project will last for three years, maybe is better to remove it and find an alternative". I've seen projects that are stucks to very old libraries because the were not well organized about deprecation for lack of information about them, and then libraries will be removed without any warning and people was not able to organize the code to handle the deletion of that library in time. Also, when a library will be deprecated, at least other two information will be needed: * The reason (lack of maintenance, alternatives in modern c++ etc). * At least one alternative to the library, if any (i.e. use std::thread instead of boost::thread). This will give to us the needed information to handle the deprecated library that we are using in our projects. I don't agree with "zombies" libraries. If a library is deprecated, should be deprecated also for boost developers. If you want to remove it also boost libraries that use that should be updated as well. If not, there's no reason to deprecate a library since it will continue to be used. Boost developers can use the deprecation time range defined before to organize the switch in order to remove that dependency. If it's not possible for any reason, the library should not be deprecated. Unmantained libraries are also dangerous. If you continue to ship a unmaintained library, is possible to find a bug that will last for much time, and there's the risk that boost will not be seen as stable as they usually are. No library should be marked as "unmaintained": if noone can handle it maybe it's better to think to deprecate it (usually a unmaintained library is a old one in my experience), or it's better to maintain a public bug tracking system in the main site, so everyone can contribute with a patch if he wants (also the bugs that are present in a specific release should be notified in the changelog). During the boost development then you can take an eye to the bug tracking system, and maybe sometime it's better to stop the development of new libraries and features, and focus the effort on a bugfixing release. I don't expect that there will be many bugs, because there are very few of them at the moment, but there must be a specific time during development in which you should decide about what to do on that dozen of bugs in "unmaintained" libraries, that no one will fix because there are no maintainers. This is only my point of view. I hope it can help. Regards Daniele Lupo On 08/05/2023 20:15, John Maddock via Boost wrote: > >> Stagnation >> * There are fewer new libraries proposed. >> * Formal reviews get less participation. >> * Review managers are typically scarce now. >> * The mailing list volume is thinning; younger folks don’t use lists. >> * There is no second order effect: new libraries rarely use Boost. >> >> Quality >> * Some libraries are unmaintained and create a negative user experience. >> * Users open issues, and no one replies to them. >> * Pull requests are submitted to abandoned repositories. >> * Scant financial resources for infrastructure or staff. > > I think this is correct. I have somewhat suggested this before (as > others have suggested a Boost-2), and for various perfectly good > reasons nothing has ever happened. > > I think at this point we should be somewhat aggressive in deprecating > and then removing libraries which are unmaintained and no longer up to > scratch. Call it a once in a decade spring clean ;) > > So far I think we have only removed one library - one of mine (TR1) > under my direction and even getting that done was a bit of a rigmarole > as I remember :( > > So, how about something like this: > > We have three categories: > > "Deprecated" libraries are marked for removal at some specific future > date in time. This gives users/developers who care about those > libraries time to step up to the plate and a) complain, and b) do some > actual maintenance. After deprecation, libraries that are actually > removed go into a separate zip, probably on their own github page, and > this is the last release they ever get. > > "Zombie" libraries are deprecated, but are still used within Boost. A > good example would be static_assert, which should not now be used in > new libraries, but may still be needed by existing code. Zombie > libraries would still be shipped with Boost, but their documentation > would not be listed in our main index. We might however, have a > separate index for them just in case anyone still needs to find them. > Should we have a new Boost.Compat there could be quite a few of these > in time. > > "Unmaintained": speaks for itself, the library is important enough to > keep around, but has no maintainer. We need a procedure for acquiring > new maintainers, but traditionally we've recruited from existing > authors who are a small, and rather busy pool of people. The > alternative is to recruit from outside, but we often get enthusiastic, > but not very experienced people coming forward. Getting them to submit > PR's and having an experienced old hand check them through is very > time consuming and unsatisfactory for both parties. So how about > this: anyone that wants to step up and enhance/maintain an > unmaintained library can do so - *in their own fork of the github > repro* - then when they're ready for a release, they ask for something > akin to a mini-review - if it's positive they get to merge to Boost > and become an official maintainer, if not they get feedback on what > they need to change. Who knows, maybe this will even stimulate some > discussion and innovation again as well as bringing in new blood? > > Just thinking out loud here, John. > > > _______________________________________________ > Unsubscribe & other changes: > http://lists.boost.org/mailman/listinfo.cgi/boost

1 0

Re: [boost] The Future of Boost
by Vinnie Falco 09 May '23

09 May '23

On Mon, May 8, 2023 at 10:44 AM John Maddock via Boost <boost(a)lists.boost.org> wrote: > I wish you the very best of luck, Thanks! > ...I also note wryly that all your motivations match exactly > those behind choosing Docbook and then adding quickbook on top ;) You lost me there.. MrDox extracts comments and declarations from C++ programs, while Dockbook and Quickbook are document format and markdown systems respectively...I'm not seeing the connection? Thanks

1 0

Re: [boost] The Future of Boost
by Andrey Semashev 08 May '23

08 May '23

On 5/8/23 18:46, Vinnie Falco via Boost wrote: > > Documentation Improvement > > Our vision for documentation is to ensure that every Boost library has > the option to adopt a well-maintained toolchain that is easily > deployed, produces high-quality output befitting the Boost brand, is > itself well-documented and easy to use, and has behind it full-time > staff working continuously to make improvements and provide technical > support. > > After researching the domain extensively (by just asking Peter Dimov) > we have discovered that the markdown format Asciidoc is a very popular > format with a simple and well maintained toolchain. Several regularly > active Boost authors have already switched their libraries to using > Asciidoctor. The authors of the Asciidoctor tool are also the authors > of “Antora,” a modular, multi-repository documentation site generator: > > https://docs.antora.org/antora/latest/ > > We have built a new, modern set of additional scripts capable of > building the Boost release and documentation, including the capability > of rendering “Antora-enabled Boost library repositories” using this > Antora system. The results are beautiful and modern, and the > Asciidoctor / Antora toolchain holds the promise of being popular and > well-maintained for a long time. The use of Asciidoc or Antora is > optional; this is just an additional choice. I don't know about Antora, but Asciidoc is a too low-level tool for writing docs. In particular, the fact that one Asciidoc document translates to one HTML page is a problem. I'm aware of AsciiDoxy, but I got the impression that it is a bit half-baked and not a widespread solution. > Peter Turcan is our full-time Senior Technical Writer who is > modernizing the instructions for users, maintainers, contributors, and > formal review participants. You can see Peter’s work along with the > quality of Antora’s output here (note that the user-interface is stock > and will be restyled soon): > > https://docs.cppalliance.org/ > > The website above has a new full-text search feature (try it!). We are > investing in a search experience which includes the site docs, > library docs, library references, and even the public header files. We > are also investing in the deployment of a large language model > (ChatGPT-style AI) trained in Boost and C++ specifics to answer > questions for users. We have a new talented and eager staff engineer > working full-time exclusively on this, and I don’t want to steal his > thunder so I will let him explain further soon. I'm not an expert in AI technology by any means, but judging by the ChatGPT-related news I come across it looks like AI as a consultant is more harm than good, at least at the current state of affairs. That is, it is more likely that it will give useless or harmful advice than a useful one. I got a similar impression from the AI-assisted code writers, BTW. Maybe I'm biased, I don't know. All this is not to say that AI technology could not be useful. For example, it could help as part of a search engine. Though we could probably just reuse Google search or something. > Some Boost libraries currently generate their documentation reference > pages using Doxygen combined with other obscure tools such as xsltproc > or Saxon-HE to render into Boost Quickbook, an obsolete form of > markdown which only we use. This Quickbook is rendered into BoostBook, > which is a flavor of DocBook. The BoostBook is converted into HTML by > a DocBook renderer. This rapidly obsolescing toolchain is painful to > work with and is a form of technical debt which costs us. I think you are painting an overly dark picture here. Feature-wise, there simply is no alternative to QuickBook+Doxygen currently. There just isn't. Yes, there are quirks in this toolchain, but once it is set up and working, there really is no problem using it. I have configured QuickBook/BoostBook/Doxygen on my system decades ago and didn't have to touch it ever since, it just works(tm). (Well, I did recompile QuickBook from time to time, but that was mostly out of boredom and had zero issues.) Also, I'm not sure what state it is in, but I think there was some work in QuickBook to directly generate HTML as output. I imagine, there would be limitations with this, as QuickBook supports injecting BoostBook bits in it, but for the most part it seems doable. > I have begun work on a new command-line tool called MrDox (“mister > docs”) which uses the unstable clang libtooling API to extract the > documentation comments and declarations from C++ programs, and turn > them into beautiful Asciidoc reference pages. You can see that work > here: > > https://github.com/cppalliance/mrdox > > The core principles of the design of MrDox is to always understand the > very latest C++ constructs and extract them with high fidelity. For > example it recognizes conditional noexcept, constexpr, deduction > guides, all attributes, and many other things that other documentation > toolchains cannot fathom. In a nutshell I intend to bring the same > level of Boost quality to the documentation toolchain that Boost has > brought to the C++ libraries themselves. > > MrDox intends to completely replace Doxygen, xsltproc, Saxon-HE, > Quickbook, Boostbook, and Docbook, as the only requirement to render > its results is to run the Asciidoctor tool, which has no other > dependencies. This toolchain offers modernization and simplification > for anyone who opts-in to it, which reduces long-term risks and > improves results. This unfortunately delays the development of my > other libraries, but enhancements in the documentation toolchain are a > force multiplier; many Boost libraries can benefit. >From the readme page it seems like there is a fair bit of NIH syndrome in there. :) But, if MrDox will transparently replace Doxygen (that is, it will understand comments in Doxygen format and generate output in various formats, including XML) then it may make a very good alternative. I sincerely wish you luck with it.

1 0

Re: [boost] The Future of Boost - CI
by Andrey Semashev 08 May '23

08 May '23

On 5/8/23 20:40, John Maddock via Boost wrote: > > Vinnie, > > First of all, let me thank you for taking the time to write all this up, > and put into words, probably what we've all been thinking! > >>Continuous Integration > > CI is wonderful, and horrible! > > The main issues I see are that: > > a) It needs continual maintenance, as the host runner upgrades/changes > the systems they support. > > b) Stuff breaks without notice because we never know when the hosting CI > service will change something. > > c) Knowledge of fairly obscure scripting is required to make the most of > it. > > Strictly IMO, the issues that Robert Ramey was complaining about in CI > recently were due to the above rather than anything wrong with the > concept, or indeed Boost. > > So... in my ideal world Boost CI would look something like this: > > * The library author does nothing more than list (maybe in json or > something similarly popular) the systems they want to test on - and > these would be abstract Boost-wide names like "core", "bleeding edge", > "legacy-msvc" etc. Exactly what these map to would be defined > elsewhere. But the point is that now, library authors would almots > never need to update their CI script *and* all Boost libraries get > tested on the same "core" which would also form our release criteria. While I can see the appeal of treating the CI as a black box, I personally want the opposite. That is, I want to know *exactly* what I'm testing and how I'm testing. This goes beyond listing specific compilers or even their versions; it is not uncommon for me to configure environment, including installing additional packages or setting up environment variables and compiler switches as part of the CI run. This is one of the reasons why I'm not using Boost.CI in my libraries. > * Updates and changes to CI would be announced here first, if in doubt > new compilers *might* go in "bleeding-edge" first and "core" a release > later. I think, making such lists of compilers commonly accepted is unrealistic. One compiler or a list of compiler options might be important for one library and not important at all for another one (meaning, it would be a waste of CI resources to run that configuration for that library). The only practical use case for such a list would be the list of the compilers we declare as "officially tested" in our Boost-wide release notes. > Machine time could well be donated by volunteers and perhaps replace the > current test/status matrix, which is fine, but requires you to go off > seeking for results, which may or may not have cycled yet. Plus that > matrix relies on a "build the whole of Boost" approach which > increasingly simply does not scale. I'm really grateful to the volunteers that run the tests and maintain the official test matrix, but honestly, I'm not paying attention to it anymore. I have three main issues with it: 1. Slow turnaround. From my memory, it could take weeks or more for the runners to run the tests over a commit I made. With this order of times, it is impossible to perform continued development while maintaining code in working state. 2. Lack of notifications. 3. Problematic debugging. It was not uncommon that a test run failed because of some misconfiguration on the runner's side. And it was also not uncommon that build logs were unavailable. So, while, again, I'm most grateful to the people that made public testing possible at all before we had the current CI services, today we do have CI services with the above problems fixed (more or less), and I'm spoiled by them. It is true that the public CI resources are limited and insufficient at times, so, IMHO, the way forward would be towards fixing this problem without losing the convenience of the CI services we've become used to.

1 0

Re: [boost] The Future of Boost - deprecating libraries
by Peter Dimov 08 May '23

08 May '23

Vinnie Falco wrote: > This is all very nice but why didn’t you reply to my post instead of starting a > new thread? Someone hasn't read the thread about Amazon SES breaking threads.

1 0

Re: [boost] The Future of Boost - deprecating libraries
by Vinnie Falco 08 May '23

08 May '23

On Mon, May 8, 2023 at 11:08 AM John Maddock via Boost < boost(a)lists.boost.org> > … This is all very nice but why didn’t you reply to my post instead of starting a new thread? > -- Regards, Vinnie Follow me on GitHub: https://github.com/vinniefalco

1 0

Re: [boost] The Future of Boost - deprecating libraries
by Robert Ramey 08 May '23

08 May '23

On 5/8/23 11:08 AM, John Maddock via Boost wrote: > I think at this point we should be somewhat aggressive in deprecating > and then removing libraries which are unmaintained and no longer up to > scratch. Call it a once in a decade spring clean ;) > I don't see this could be done without having any information on library usage. No one has figured out how to get this. Robert Ramey > > _______________________________________________ > Unsubscribe & other changes: > http://lists.boost.org/mailman/listinfo.cgi/boost

1 0

Re: [boost] Problem with homegrown. porting to ipv6
by Georg Gast 08 May '23

08 May '23

Am Mon, 8 May 2023 10:47:02 +0000 schrieb Tarun Batra via Boost <boost(a)lists.boost.org>: > What I wanted to ask is, is there any way in boost by which we can > first try things on ipv6 and if that doesn't work fall to ipv4. Do you want to test if IPv6 is supported on this machine or do you want test if it has public IPv6 address or if it can connect by IPv6 to some address? There are things like NAT66, ULAs and other stuff that happens not on this machine .... Local IPv6 might be available for most of all "modern" platforms. Bye Georg

1 0