I'm currently documenting the Generic library and the documentation itself imports a lot of code from the source files directly (the best documentation for a concept generally involves showing the concept definition itself, and importing it means the code won't be out of sync with the documentation). This imported source code references other concepts and I'd like to be able to have each one of these referenced concepts be a clickable link that brings the person to the documentation for that concept (I.E. in http://generic.nfshost.com/generic/standard_concepts/concepts/equivalencerel... the user should be able to click on "Predicate" in the imported source code to see the documentation for the Predicate concept). So, I tried the simplest solution -- make a quickbook macro called Predicate that results in a link to the corresponding Predicate documentation. After a quick test, everything worked fine with one exception -- the name of the section linked to is also "Predicate" and that seems to be causing the link in the generated table of contents to no longer work properly, pointing to a page that doesn't exist even though it displays the link with the proper name (note that the cross-reference links still seem to work fine, it's just the links in the table of contents that break). I realize that I'm doing something hacky here, so if anyone has a better solution, let me know.
If this is the best approach, is there a way that I can keep the name of the section the same as the macro name? I.E. Is there some trick I can use to prevent the macro from being expanded when I use it in the section declaration? Keep in mind that I can't simply use templates here instead of macros because the macros are expanded from within imported, working code snippets. I also can't postpone defining the macro until after the section is declared since sections are presented in alphabetical order, meaning that an earlier section's code may reference a later section's code based on dependencies.
I'm not sure I completely understand the issue, but I use "__predicate" to link to "predicate". John.