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 13:13:03

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

No the link ID has to match the name of the target, suppose you have:

[article My Library
[/ stuff in here]
]

[section:one ONE]
[section:two TWO]

[endsect]
[endsect]

Then to link to the start of the section titled "TWO" you would use the link 
ID "my_library.one.two" or "my_library.one" to link to "ONE".  So the the 
link ID does not appear explicitly in the source anywhere which is why your 
grep doesn't find it.  As I mentioned before, the html "chunking" 
stylesheets use section ID's for file and directory names, so in the above 
example you would likely end up with:

html/
    index.html
    my_library/
        one.html
            one/
            two.html

Some gochas to watch out for:

* If you don't give a section a name (the bit after the colon) then it gets 
assigned a random numerical ID, so you won't be able to link easily to the 
section.
* You can add explicit link targets, but:
    * If you add them directly below the title then the title may scroll off 
the top of the page when you jump to that link.
    * If you add them directly above the title, then the link actually ends 
up on the wrong page altogether!

In other words it's best to save explicit link targets for for cases where 
you want to link to some point in the text that is not the start of a 
section.

HTH, John