Outdated and innacurate documentation on OpenGL.org considered harmful

I spend some time on other sites helping people with OpenGL problems. And one thing I see almost daily is linking to the OpenGL man pages on this site. However, they almost never link to the up-to-date 4.3 documentation. In almost all cases, they’re links to the 2.1 docs.

That would be fine if the 2.1 docs were accurate even for 2.1. But they’re not. And given the resolution to this bug, they won’t be fixed anytime soon.

Look, I understand that the website and documentation maintainers’ time is limited. So I get why they’re not fixing bugs in the 2.1 docs. What I don’t get is why the highly inaccurate documentation is still available!

This is OpenGL.org; the name is literally what we are. Inaccurate documentation should be the absolute last thing we accept here. And yet, here it is.

I urge the website maintainers to resolve this issue, either by resolving to make the older documentation more accurate or throwing it away. But the current situation, where they pretend that there is no problem with misinforming people about OpenGL, is untenable.

(avoid character minimum) +1

As I’ve gone up the modern Linux + OpenGL learning curve these past few months, I personally don’t feel that the “virtual OpenGL SDK” is working at all. I got very fed up with Microsoft and bolted, but many times lately I’ve been questioning the practicality of having done that. I am forever poring through the implementation details of third party libraries, rarely finding anything that really works, filing bugs, and having to understand way too much of the internals of just about everything. It’s like there’s no API hiding, I just have to examine actual code behavior all the way down. Documentation issues are another symptom of the same thing. The basic ecology simply isn’t funded, so lacks an awful lot in terms of fit and finish.

And thrid party libraries are related to the OpenGL 2.1 API docs how?

The point is the cow is already out of the barn. The infrastructural problem is lack of funding. Docs are out of date and showcased third party libraries don’t work for the same reason. Nobody’s being paid enough to make them work. Alfonse’s concern is what this makes OpenGL look like. It’s all the same concern if you care about people adopting or fleeing OpenGL.

Docs are out of date and showcased third party libraries don’t work for the same reason.

Which libs in particular?

Nobody’s being paid enough to make them work.

I think it’s more likely that nobody gives a damn about the GL 2.1 docs anymore - which is ironic, as major implementors actually do provide support for GL 2.1…

It’s all the same concern if you care about people adopting or fleeing OpenGL.

Everyone who wants to use OpenGL should know that what they get is OpenGL - nothing else - so the risk of having to implement your own stuff or use some third party lib is something we have to live with. Actually it sometimes is comforting not having to rely on some major corporation for other parts of your program. If people want to port an app which mandates the use of legacy GL, mainly due to hardware constraints or sales related counterarguments, then using GL 2.1 should not even be considered and so shouldn’t 3rd party libs layers on legacy GL. And it’s not like every 3rd party lib out there is crap: GLEW, among many others, and glm, DevIL, FreeImage and many others are prime examples of libs that are valuable and just work (except for core profile contexts with GLEW :wink: ). Sure you need to know how they work, but that’s also the case if you have a compilation of libs like DirectX.

Granted, there is room for improvement of the official sources related to OpenGL. The fact that the legacy docs are still online (and faulty) simply makes it more likely that people will stumble over that stuff and actually start off with legacy GL apps, then come here, ask stuff that nobody really cares about anymore or due to mistakes they made because of the docs’ inaccuracy. Aside from frustration on the side of the programmer, people here have to be able to answer questions that have nothing to do anymore with modern OpenGL but due to GL_ARB_compatibility they actually still have a point coming here for help.

The same goes for the old FAQ which has massive amounts of outdated material but still isn’t taken offline. The only thing you’ll see is the note “NOTE: This page contains old archived material and may not be relevant anymore.” at the top of the page. The official SDK hosts links to legacy tutorials, outdated tools and stuff that’s simply a duplicate of pages already available in other parts of opengl.org.

GLEW, in combo with NVIDIA drivers on 3.3 HW and third party sample code that uses ARB_debug_output. The debug context setups simply don’t work. It’s onerous to debug this stack just to get started. FreeGLUT didn’t handle the contexts correctly for some reason. My jury is out on GLFW. It may be better, but at this point I no longer trust anyone’s wrapper over OpenGL and OS stuff. All I ever end up doing is digging, digging, digging to get started on square one. I still haven’t figured out if GLEW is actually worthless, or it’s the windowing libraries such as FreeGLUT or GLFW that cause the problems. I do see giving up on GLEW and rolling my own as a valid scenario, and from a “get started” standpoint, that’s pathetic.

So, stale 2.1 docs? Who cares. I’ve tried to fry so much bigger fish.

Everyone who wants to use OpenGL should know that what they get is OpenGL - nothing else - so the risk of having to implement your own stuff or use some third party lib is something we have to live with. Actually it sometimes is comforting not having to rely on some major corporation for other parts of your program.

I wish I had had the impression up front that I should not rely on third party libraries for anything. It would have saved me two months. I even did the “goody two shoes open source thing” of filing bugs and trying to come up with some fixes. A few of those changes got acted upon, but mostly crickets chirped. The development energy for dealing with the warts simply isn’t there.

Sure you need to know how they work, but that’s also the case if you have a compilation of libs like DirectX.

Using GLEW with OpenGL is like using a third party library just to write straight DirectX code. OpenGL is really junky in this regard, and these third party stacks mess up the basics.

The same goes for the old FAQ which has massive amounts of outdated material but still isn’t taken offline. The only thing you’ll see is the note “NOTE: This page contains old archived material and may not be relevant anymore.” at the top of the page. The official SDK hosts links to legacy tutorials, outdated tools and stuff that’s simply a duplicate of pages already available in other parts of opengl.org.

I think all this OpenGL “SDK” stuff should be burned. It’s a lie. A SDK is something that integrates a bunch of basic components so that developers can download it all at once and be quickly productive. What opengl.org implements is an anti-SDK. An invitation to investigate everything, find out that most things are inconsistent and slightly broken, and develop a complete lack of trust that anything off-the-shelf is worth bothering with.

If not burned, then Khronos should work on a real SDK. 2.1 stuff could be moved to a proper “Legacy” or “Archive” section of such a SDK. It would be there for someone who needs it, but wouldn’t get front page advertizement anymore.