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

Subject: Re: [boost] [quickbook] Cross-Referencing Source-Snippets
From: John Maddock (boost.regex_at_[hidden])
Date: 2012-10-14 04:13:47

> 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.

I'm not sure I completely understand the issue, but I use "__predicate" to 
link to "predicate".

John.