Re: [boost] [quickbook] error with links when building documentation

Subject: Re: [boost] [quickbook] error with links when building documentation
From: John Maddock (boost.regex_at_[hidden])
Date: 2010-12-13 04:32:08

>> It means that you're linking to an id that doesn't exist. You've got
>> '[link _Tutorial_ Tutorial]' but nothing with the id '_Tutorial_'.
>> It's probably should be '[link gil.io.tutorial Tutorial]'.
>
> My way of writing documentation pretty much comes from
> boost::accumulators. Here links are defined like this:
>
> in accumulators.qbk[75]:
> Boost.Accumulators, check the [link accumulators_framework_reference
> Reference] section.
>
> There is no other mention of "accumulators_framework_reference" in the
> whole file. And so, I define links the same way:

I suspect that because accumulators uses Doxygen for it's reference section, 
that you're seeing a link to something generated by Doxygen, but I can't be 
sure of that.

Basically: every [link something some text] must have a target called 
"something" somewhere in the docs, if you give your sections meaningful 
names, then the ID of each section will be something like: 
book_name.level1.level2 assuming you have two nested sections called 
"level1" and "level2".  Alternatively: generate the docs, then navigate to 
the the html page for the section you want to link to, if the part after the 
/html/ path is say "math_toolkit/dist/dist_ref/dists/weibull_dist.html" then 
the section id will be "math_toolkit.dist.dist_ref.dists.weibull_dist" ie 
replace the /'s with .'s and remove the .html from the end.

Something we did in Boost.Math to make this easier was define a macro for 
links to each of the main pages with an obvious and easy to remember name:

[def __weibull_distrib [link math_toolkit.dist.dist_ref.dists.weibull_dist 
Weibull Distribution]]

So now every link to the Weibull distribution is simply in the text as 
__weibull_distrib and that takes care of both the link and the link text.

HTH, John.