Rename the API

NB: As this is now an independant subproject from OpenGLEAN, I am much more inclined to carry out this proposal. But doing so is a low-priority issue at the moment, and may be superceded by the a new API design in any case.

Introduction

This proposal is just a random thought for public consumption. freeglut forked the GLUT API and after 5 years of work is still incomplete. OpenGLUT forked the freeglut codebase and provided new man-pages. (freeglut never had any man-pages, relying on the old GLUT man-pages instead.) It turns out that the old GLUT API also had man-pages, though they were never widely distributed.

Now, OpenGLEAN has forked OpenGLUT, and the OpenGLUT man-pages.

Why this is not sufficient.

Unfortunately, you start to run into collisions if you try to install man-pages for GLUT, OpenGLUT, and OpenGLEAN. Whose glutCreateWindow.[03] do you install? Right now, the answer may seem pretty straightforward: OpenGLUT and OpenGLEAN both normally install man-pages, GLUT man-pages are rare. OpenGLUT and OpenGLEAN provide almost identical man-pages that are fairly complete and which address features not found in old GLUT. So, install either OpenGLUT or OpenGLEAN man pages and forget it, right?

The problem is that OpenGLEAN has already removed one obsolete function and will remove many others. And, of course, one of the reasons for stripping deadwood from OpenGLEAN is to make the library more nimble. It is expected that the documentation for both libraries will eventually include references to things that don't exist in the other without documenting the portability issue.

Another problem is that OpenGLUT tries to force its own man-page installation, and OpenGLEAN presently inherits this---and both install to the autoconf ${PREFIX} path, in section "3". So you will get conflicts if you try to install both libraries.

The Advantage As It Is:

Currently, old programs just work. Skills and knowledge can go back and forth.

Workarounds

There are some workarounds that you can employ, such as using the 3f man-page section, or presuming that one set is in the base-system while another is added only as a package, with a wholly separate directory tree. OpenGLEAN may provide a way for you to specify a non-default library section for OpenGLEAN documentation or to disable man-pages altogether.

Renaming

Renaming the API is relatively easy. Just change all "glut" symbol prefixes to "glean" (and "GLUT" to "GLEAN"). Done. (Warning: It turns out that there is a project called glean that has nothing to do with OpenGLEAN. However, that project appears to be dead, and I'm not really going to rename OpenGLEAN yet again, after producing the OpenGLUT fork and OpenGLEAN. Renaming a project is more work than just renaming the API! Enough is enough.)

Coping With the Fallout

If OpenGLEAN's API is renamed to avoid clashing with GLUT/freeglut/OpenGLUT, some optional #define symbols can be added, so that porting between GLUT, freeglut, OpenGLUT, and OpenGLEAN can still be done with a few tweaks to the compilation command-line.

Conclusion

I'm not terribly happy with this idea at present, but it's something that I wanted to put down in writing for reflection. At least for now, OpenGLEAN will retain the GLUT API.

Supported in part by SourceForge.net.

Generated on Sun Sep 18 12:47:35 2005 for gleanfonts by doxygen 1.4.3
The OpenGLEAN Fonts project is hosted by SourceForge.