[boost] [quickbook] Cross-Referencing Source-Snippets

Subject: [boost] [quickbook] Cross-Referencing Source-Snippets
From: Matt Calabrese (rivorus_at_[hidden])
Date: 2012-10-13 17:19:12

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/equivalencerelation.html
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.

-- 
-Matt Calabrese