Quality of examples

[madebr]

I believe the quality of a lot of examples is lacking.
What low bar do we want to set?
Should the example be as short as possible, requiring modifications by users?
Or should it be a minimal standalone executable that can be copied to a project to test things out?

I believe every example should be a complete standalone executable.
Take getopt(3) as an example.
It contains 2 complete programs, showing usage of getopt and getopt_long.

[slouken]

Sure, now that we're able to extract the examples and build them, I think it makes a lot of sense to have minimal complete examples in most cases.

Does it make sense to move these into the SDL repo in an examples directory? I'm not sure how we'd name them or indicate what they're examples of, but that might be helpful for new users downloading the source.

[icculus]

I mostly want to avoid "Here's how you call a C function" examples that don't actually add anything about how to use the API.

// why bother having this SDL_CreateWindow example at all? (for example).
if (SDL_CreateWindow("Hello SDL", 640, 480, 0) == NULL) {
    // deal with failure here!!
}

I'm fine with complete programs, as long as they show one thing well and are fairly short.

I think it's notable that Linux manpages seem to only have code examples for things that are poorly designed^W^Wcomplex APIs that you can't just jump in and use correctly without a deeper understanding.

Like, strlen(3) and chdir(2) don't have an example, but wait(2) and select(2) do.

Which is to say, complexity can be unavoidable, but let's talk about what functions need an example and if that is a sign we should change that API before we lock down SDL3.

[icculus]

Does it make sense to move these into the SDL repo in an examples directory? I'm not sure how we'd name them or indicate what they're examples of, but that might be helpful for new users downloading the source.

The only reason I won't say "no" outright is because there was the idea these would be nice in the manpages, but the manpages need this data from the wiki and thus might not be available when building from source code...so we could bridge this stuff. But that code doesn't currently exist and I'm not sure it's worth writing.

We maybe should change the offline HTML .zip file we generate of the wiki to include the example code, using @madebr's work here, though. You end up with stuff like...

examples/SDL_CreateWindow.c
examples/SDL_OpenAudioDevice.c
(or whatever)

...and that's about as concise as you're going to get. :)

[madebr]

We maybe should change the offline HTML .zip file we generate of the wiki to include the example code, using @madebr's work here, though. You end up with stuff like...

The c/cpp files are present in the artifact in examples/*.

I'm fine with complete programs, as long as they show one thing well and are fairly short.

Perhaps we should weaken this a bit and simply require the examples to be copy-paste buildable, and not linkable.
Adding SDL_Init/SDL_CreateWindowAndRenderer everywhere does not make concise examples.

I think it's notable that Linux manpages seem to only have code examples for things that are poorly designed^W^Wcomplex APIs that you can't just jump in and use correctly without a deeper understanding.

That's a good observation.
SDL3's dynapi currently has 1014 entries, of which 95 have an example in the sdl wiki. So around 10%.

...so we could bridge this stuff. But that code doesn't currently exist and I'm not sure it's worth writing.

I leave that final decision with you. It's a nontrivial amount of work to write and maintain.

[slouken]

Maybe we can take advantage of the new callback application style and have the copy/pastable bits be application callbacks that can drop into a standard example skeleton?

[madebr]

Maybe we can take advantage of the new callback application style and have the copy/pastable bits be application callbacks that can drop into a standard example skeleton?

Shouldn't that skeleton then also be rendered on the wiki and man page?
If so, then the example becomes "bloated" again.
A skeleton will also complicate things, because some SDL functions only make sense in SDL_AppInit. Others only in SDL_AppIterate or SDL_AppEvent.

Alternatively, by adding some JavaScript to expand the example when clicked and/or copy code to the clipboard, we can combine the best of both worlds.

Lots of SDL functions are closely related. Perhaps we can allow more complicated examples by combining functions from the same category?
Some wiki pages currently already share the same example, or have complicated examples. 1 2 3

[slouken]

I don’t know, I’m just brainstorming here. I trust you to make something awesome. 😊

[icculus]

Assigning this to me for now, so I can add the example source files that @madebr's work generates to the offline wiki zip file, but I'm not going to get to this soon, and we probably need to do more on this topic after that work is done, too.

[madebr]

The Old New Thing blog regularly uses scratch programs to experiment with.

Would something similar be useful here? Or only for selected api's?
The markdown format makes this a bit harder to do.

[captain0xff]

Would it be possible to do something like Raylib where the examples have a web build that are run on the web and one can scroll down to see the source? https://www.raylib.com/examples.html

[slouken]

This is actually pretty awesome. These are more like mini-tutorials, but they are super small and useful.

@icculus, what do you think?

[icculus]

The entire thing is great, I would love something like this, but we would need to build it and have carefully-curated code examples. I think even if we just automated something from the current contents of the wiki, it would be a mess.