Examples in getting-started

[anarthal]

Which documentation does this apply to?
User's Guide

We're using lambda (which will ring a bell of "we already have this in the language", something we're trying to flee from) and iostreams (which we all love). We need a different example.

I propose jumping directly to URL or JSON (even if they're compiled), and provide a note on how to link against header-only libs later.

The current JSON example may be problematic, since it relies on another helper header, and this is not explained.

[alandefreitas]

That's great. I think we should start by listing what libraries requirement we want for both examples.

Ideally, for the first example:

• A header-only library
• Something they can only get from boost
  • Something that's not available in the STL
  • This applies even if it has much better performance, like boost.unordered
• A library that's not too old or unmaintained
• Something with which we can achieve some simple task in few lines of code
• Something without "2" in its name

And for the second example:

• A compiled library
• An example with no external files
• All of the other requirements above

[alandefreitas]

(If we implement a collapsible admonition, the example can even go inline)

[alandefreitas]

The new UI is fancy by the way: https://62.site-docs.prtest2.cppalliance.org/user-guide/getting-started.html

[alandefreitas]

I propose jumping directly to URL or JSON (even if they're compiled), and provide a note on how to link against header-only libs later.

I think we should keep the pattern of an example of a header-only library and then an example of a compiled library. The reason is not that I love header-only libraries, but because their integration is slightly different (Boost::headers as opposed to Boost::module_name) and we have to demonstrate that. Ideally, we would have INTERFACE targets for all header-only libraries, which would make this distinction less relevant. But that requires convincing other people to get onboard with that. Besides, I have to accept some people prefer header-only libraries sometimes.

[alandefreitas]

Well... let's look at some candidates starting from level 0:

For the first example:

• logic (the example would be too boring - unmaintained)
• lambda2 (even though it has a 2 in it)
• describe (might become too verbose)
• mp11 (too advanced for getting started)

For the second example:

• json (might be a little too verbose)
• url (might be too specific)
• nowide (not boring but might be too advanced for getting started)
• system::result (system is in the STL but result is not, but might be too boring)
• asio/beast/mysql (might become too verbose to achieve something simple)

These are the candidates I could think of.

[anarthal]

The most fancy thing I found was UUID for the first one. But it looks unmaintained. I honestly think this is a valuable library, and I may step into as maintainer if there's value.

Anyway, for the second candidate, I'd leave JSON. MySQL requires too much setup.

[anarthal]

Looks like Peter has done some work on it recently though. But the docs from page looks scary.

[alandefreitas]

UUID is interesting. Yes. On the other hand, it is much more interesting than the current lambda.hpp example, which is sort of interactive?