[quickbook] Cross-Referencing Source-Snippets
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. -- -Matt Calabrese
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.
On Sun, Oct 14, 2012 at 4:13 AM, John Maddock <boost.regex@virgin.net>wrote:
I'm not sure I completely understand the issue, but I use "__predicate" to link to "predicate".
I can't do that because the text that needs to be replaced by the macro comes imported directly from C++ source-code (via [import]). I need to take text such as "Predicate" that appears in a header file and replace it with a link to the appropriate page in documentation, that way people can read the imported code samples and even be able to click on identifiers to take them to the corresponding documentation. The problem is, if I simply make a macro called "Predicate", it interferes with my quickbook section called "Predicate", which makes the generated table of contents broken because of the macro replacement. Anyway, I figured out a workaround -- what I now do is I define the section as such: [section:predicate P[']redicate] and do something similar for all of the other sections. This way, I get the name that I want without worrying about macro expansion. I updated the documentation here (click on the different names in the inlined code to see the cross-referencing): http://generic.nfshost.com/generic/standard_concepts/concepts/arithmeticlike... I didn't upload the source files so the #include links won't work, but everything else should. -- -Matt Calabrese
participants (2)
-
John Maddock -
Matt Calabrese