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.