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-12 19:53:06

Hi Daniel, thanks for helping out.

On Sun, Dec 12, 2010 at 7:21 PM, Daniel James <dnljms_at_[hidden]> wrote:
> On 12 December 2010 22:49, Christian Henning <chhenning_at_[hidden]> wrote:
>> Hi there, I keep getting these strange errors when building my documentation:
>>
>> Error: no ID for constraint linkend: _Tutorial_.
>> Error: no ID for constraint linkend: _extenting_io_.
>> Error: no ID for constraint linkend: _Supported_Formats_.
>> Error: no ID for constraint linkend: _Supported_Formats_.
>
> 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:

in io.qbk[36]
in section [link _Tutorial_ Tutorial]. Also, this extension requires
Boost version 1.42 and up.

Again there is no further reference for "_Tutorial_" in the whole file.

What am I missing?

>
> I'd also suggest you use sections or anchors for anything you want to
> link to, so that you can specify the id explicitly as id generation is
> a bit odd at times. Quickbook 1.6 will improve matters and be able to
> have explicit ids on headers, but that won't be stable (or documented)
> for a while.

Do you have an example at hand. My quickbook zen is not very good, I'm afraid.

Thanks again for your help,
Christian