#include<what?>

The various kinds of #include directives have always puzzled me, but now I think I may have a serious need to understand them. I have seen that some of them are implemented by methods on $xwiki (includeForm, includeTopic, in two incarnations each - with or without rendering, I assume), but I have no understanding of why they are all different. Add in the parse directives and XWiki methods and I am completely confused. Can anyone give me a synopsis of what these are all about? I understand this much: that Velocity directives are read once at parse time, whereas methods can be invoked multiple times in a loop. The problem I need to solve, however, may be a Velocity problem or a caching problem. A menu is called from the left-side navigation menu XWiki.Menu. I have included it via #includeTopic, and it use #includeMacros to bring in a macro that reads a document with a list of objects describing menu items, with a menu label, an href, and a long description. If the href field is a complete URL, it's output as a plain link; if it's a local Wiki document, it's output with XWiki's bracket syntax and its place is held in the menu as a navigational aid. If it is also in the Web reserved for such documents, it's a submenu, and the menu macro is called again (thanks to the earlier thread, I did use a copy of the argument, which is call-by-reference, and saved headaches). All of this works just fine except the first time it's called after the server starts. Instead of the menu text, all I see is the invocation of the macro. Viewing the menu document directly (as I did when I sought to debug it) fixes the problem for all until the next reboot. So what is this? I read some discussion on the velocity-user mailing list about when and how macro templates are loaded, but didn't understand it well; in addition, there is all this confusion about when to include in what way. brain[sic]