Re: [Boost-docs] quickbook question

Subject: Re: [Boost-docs] quickbook question
From: Daniel James (dnljms_at_[hidden])
Date: 2017-05-22 00:22:54

On 10 May 2017 at 21:50, Daniel James <dnljms_at_[hidden]> wrote:
> On 10 May 2017 at 21:23, Robert Ramey via Boost-docs
> <boost-docs_at_[hidden]> wrote:
>>
>>
>> [/ the following fails - invalid link]
>> [section [link nudb.ref.nudb__create create]][endsect]
>
>
> I'm pretty sure this is a quickbook bug/feature. Section titles are
> automatically wrapped in self-links, so that you can right click on them and
> copy their location. In this case it's wrapping putting a link around the
> link which I think is causing an issue with boostbook. There's a command
> line flag to turn that feature off ('quickbook --no-self-linked-headers'),
> but I don't think it's possible to use it from boost build. I'll see if I
> can make it a little smarter.

This should be fixed now on master and develop. It'll just not add a
link if the title contains a link. At first I tried linking the rest
of the title, but messed up links nested in other tags, and feel it's
probably not worth putting the effort in to get that right, and would
end up being more confusing than helpful.

>> [/ the following fails as well]
>> [section]
>> [link nudb.ref.nudb__create create]
>> [endsect]
>
>
> I'm not sure what's happening here, the generated boostbook looks okay.
> Although having an empty section title is probably a bad idea. I'll
> investigate a little more.

As far as I can tell links are working fine. Check if there are any
docbook errors, quickbook can't detect link errors itself as the link
might go to another document. I generally try to avoid linking to
automatically generated ids, as they're quite easily to accidentally
change.

Also, empty section titles aren't a great idea as they're used for the
table of contents. I just changed it on develop so that it won't write
out empty title tags in boostbook, which I think is a little better.
I'm considering adding a warning or strict mode error.