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.
And SDL_GL_GetProcAddress has segmentstion fault grrr But I need cancel my SDL in C#
The API reference by category of the SDL2 wiki is still a mess, arguably to the point of being worse than nothing since it lacks indication of how incomplete it is and people coming to libsdl.org are pointed toward it as the main documentation rather than the header files. Did you ever run the rebuild on the SDL2 wiki, or only SDL3?
Compare the current category page for SDL_video.h with the equivalent page from the archive of the old wiki:
https://web.archive.org/web/20210210032231/http://wiki.libsdl.org/CategoryVideo
The new wiki page is a list of 19 links in alphabetical order, with enums, structs, and functions jumbled together and no indication of which each link is. The old wiki page has separate lists of 10 enums, 6 structs, and 86 functions.
While we’re at it, compare the SDL3 version with the old wiki as well:
I assume it’s complete, but It’d be nice if the enums, structs, and functions were separated from each other, and the links weren’t double-spaced (maybe double-columned so you can get the whole list on screen at once, currently it’s a 4-page scroll on my 1080p monitor).
Subcategories smaller than header files would be nice. You could have a cloud of words appearing in the names (Window, GL, Get, etc.), and filter by selected word(s).
As for “you can click the ‘Edit’ button at the bottom of any wiki page to make changes, as one expects a wiki to work”, this is not really the case. The edit button lets you log into github to submit a pull request to a repo through a wiki-editing-like interface, and some of those pull requests have been sitting open for over two years. This is not how a wiki works, which is why obvious and severe problems are sitting on the “wiki” for years without being fixed by users who are bothered by them. Wikis recruit effort with low friction and immediacy of results. This edit button is more of a suggestion box.
Anyway, I’m not sure there’s any benefit to having the API reference be published as wiki content. It could probably be both a lot nicer and easier to maintain as a set of static pages automatically generated from the header files (which have comments containing information that’s very complete, but also clearly organized to be machine-processed, to the detriment of human readability).
Hello,
I really can’t believe how long the SDL2 wiki’s API by Category pages have been broken now. Years? I am astonished every time I check back and find the same sad situation. I am certain that I’m not the only long-time SDL user who uses the API by Category pages to quickly find the functions I need.
This is obviously not the whole video reference: SDL2/CategoryVideo - SDL Wiki (literally all SDL_GetWindowXXX and SDL_SetWindowXXX are missing, just for a start)
…and what a comperehensive threading API, with only one enum and nothing else! SDL2/CategoryThread - SDL Wiki.
I can’t give more examples since new users can only post two links…but no doubt everyone already knows. It seems to be no secret that the wiki is busted.
Look. I get that ‘SDL3’ and ‘priorities’ and ‘wiki migration’ and whatever, but here is the reality: as of this very moment, the API reference for the current major release of one of the most popular libraries in existence is badly broken, and the fix in many cases is as simple as editing a static html page to include all the missing stuff (at this point, it’s clear that whatever automated system is in place is not working, so let’s be realistic and start talking about the maybe-a-few-hours-worth of manual labor that it’s going to take to fix the HTML…)
So…hello?
(Sorry for harshness, I really do love SDL, Sam et al are my heroes; this is coming from a place of love and concern…)
Yeah…
…
That’s all I can say about it… We’re almost 1 year from when I started this thread.