Is someone willing to make a definitive writeup of this? If you want to sit down and work together on this just let me know, and I'll help where I can.
I see so many parts of code snippets, and comments that it worked as well as comments that it didn't work, that I can't make heads or tails out of how it is supposed to be done.
Please if you post something try to be as clear and complete as possible so that people can understand, or maybe it is just me?
From what I gather:
Were supposed to do this in template.php, and only call the output result in the template file (but which variables, how and why).
The theme function got replaced by the render function.
For background info please see this support issue:
How to display a menu in a template file?
If I may make the suggestion we consilidate efforts there on working on the issue before adding it to the final draft of the doc page.
I've opened up a book page to build a documentation page on this, if you know how to do this the proper way please write it down so we can all save some time on this in the future. The book page can be found at How To Do Theming Examples Made Simple in Drupal 7. You can then add a child page for the subject.
Thank you for your participation! :-)