Sorry, I don’t know where to post this message, but I’ve noticed for some time now that the libsdl wiki seems to be missing a lot of information.
For example, I need some info about the audio part of SDL so I go to: SDL2/CategoryAudio - SDL Wiki
There used to be a list of functions, and more, but they seem to be gone. Instead I see things like <<FullSearchCached(category:CategoryAudio -CategoryEnum -CategoryStruct -title:SGFunctions)>> in there.
Can someone fix this?
This is because in the process of the upgrade from SDL2 to SDL3, functions are being removed from the SDL API.
But SDL3 is not there yet…
The wiki that’s currently linked from the SDL website is still the SDL2 wiki.
@scippie the reason is because of moving the Wiki to Github a while back, which has a different system and is why all the <<Whatever::BlahBlah>> stuff is in there. It basically never got cleaned up.
On top of that, recently a bunch of functions got removed from the SDL2 wiki categories section for some reason. Like, the section for SDL_Renderer removed mention of some functions like SDL_RenderGeometry(). I did a pull request to put some of them back in but it looks like it never got approved.
Unfortunately, the only option is tediously scrolling through the “List Functions Alphabetically” section, which will become even more useless with SDL 3 because when making the function names more consistent, instead of choosing the format SDL_{Namespace}{Action} the SDL developers chose SDL_{Action}{Namespace}.
The SDL3 wiki version however does seem to have the full list of functions: SDL3/CategoryAudio - SDL Wiki (libsdl.org)
So it seems like what SDL wiki is doing is to remove articles for deprecated functions from the SDL2 wiki to prepare for the new simplified API (for example the upcoming four-function keyboard API), whereas the SDL3 wiki is a development place for the work in progress of documenting the new implementation of these functions.
The functions aren’t deprecated. For instance, SDL_RenderGeometry() was removed from the SDL_Renderer category in the SDL2 wiki, even though it’s still in the SDL2 alphabetical list and very much still present in SDL3.
The weirdness seemed to happen around the time they made SDL2 a separate branch, though, so it probably is related to that somehow.
I am wondering now, I am starting from scratch with an engine with a specific purpose. I hope that SDL3 won’t come out at the moment my engine is almost finished…
Where can I find more info about where SDL3 stands and how long it will be until it releases?
And for some of us it never will be (I can’t migrate to SDL3 because my app relies on OpenGLES 1.0 which is not supported). So I share your concern that there seems to be a policy of removing or hiding SDL2 documentation, presumably as a not-so-subtle way of persuading people to move to SDL3.
this is just am error of the wiki being migrated from mediawiki to markdown, and it’s only picking up things from markdown in some cases - it’s a small mistake in the php thing that generates the sync between code and the pages and also of the thing that renders these documents to html.
How does that help somebody still developing with SDL2 and needing reference information? Whatever the cause, fixing it is apparently a low priority, I assume because the effort is being put into SDL3 instead.
If you see a bug on the wiki/docs, you should report it on the SDL issue tracker so the developers know the bug is there and can prioritize fixing it. Otherwise they can’t fix what they don’t know about.
There’s no big conspiracy here…
I just meant to explain the issue. The problem is, in current iteraction, the way the php magic works in the wiki stuff, there is no CI, tests or something to easily make a local setup. I can guess the issue on the code by looking at it, but testing and validating is out of my capabilities.
Do you really need to report that the manual is completely broken? Don’t the authors know? I don’t plan to move to SDL3 either…
Is the SDL2 documentation still updated? If it’s not then it might be better to create a static copy somewhere that will remain unaffected throughout time no matter what happens on github and other repositories.
Similar to libsdl.org/release/SDL-1.2.15/docs/ but for SDL 2.
We fixed the wiki a few days ago; as we were moving stuff from MediaWiki to Markdown format, we discovered the script that builds the category pages had a bug, as mentioned, and was since fixed.
There’s still a bunch of <<FullSearchCached cruft in the category pages that needs to be cleaned out manually; this is left over from when we migrated from MoinMoin to our own thing and no one has had the time to clean it up.
We are definitely focused on SDL3 development, but we still make fixes and accept patches to SDL2, and are still making SDL2 releases–2.26.4 just shipped last week!–so it isn’t dead. This include documentation updates.
If you see something in the docs you don’t like or seems broken, you can click the ‘Edit’ button at the bottom of any wiki page to make changes, as one expects a wiki to work, or click the ‘Feedback’ link to tell us what’s wrong and we will eventually fix it for you! You can even just clone the wiki contents as a git repository and make pull requests if you prefer.
Also, all the SDL2 documentation is still there, in the SDL2 section. The SDL3 section is removing and renaming functions, because it would be silly to list a function that doesn’t exist, but this isn’t some secret conspiracy to force a migration to SDL3.
Thanks for fixing! I guess I didn’t look for a feedback button as this is rare these days.