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

Subject: Re: [boost] [quickbook] error with links when building documentation
From: Christian Henning (chhenning_at_[hidden])
Date: 2010-12-13 11:17:27

Hi John,

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

I have to admit I cannot follow the logic. It's probably because of my
lack of understanding of quickbook and the documentation compilation
process.

I understand that a link is defined as follows:

[link ID Text]

According to your explanation the ID has to be something meaningful,
like "math_toolkit.dist.dist_ref.dists.weibull_dist". But again when I
search all *.qbk file in the doc/ there is no other reference of this
ID. I tried "gil.io.tutorial" as an ID but quickbook didn't understand
that either. The "gil.io" is my documentation id and "tutorial" is a
top level section.

So my question remains, taken my single .qbk file, how do I define a
link to my Tutorial section.

Here a link to my .qbk file

http://gil-contributions.googlecode.com/svn/trunk/gil_2/libs/gil/io_new/doc/io.qbk

Thanks,
Christian