Hi Daniel, thanks for helping out. On Sun, Dec 12, 2010 at 7:21 PM, Daniel James <dnljms@gmail.com> wrote:

On 12 December 2010 22:49, Christian Henning <chhenning@gmail.com> 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

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/... Thanks, Christian

Hi Daniel On Mon, Dec 13, 2010 at 12:07 PM, Daniel James <dnljms@gmail.com> wrote:

On 13 December 2010 16:17, Christian Henning <chhenning@gmail.com> wrote:

...

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

See the attached patch. I fixed a couple of links. The link ids are the ones that quickbook automatically generates from the section title or header text - '[section Tutorial]' gives gil.io.tutorial, '[h2 Supported Image Formats]' gives 'gil.io.using_io.supported_image_formats' because it's inside '[section Using Io]'.

Thanks for your help. It makes sense now to me. I could get rid of the two remaining unconstrained ID myself.

Also, you might want to set up subversion so that newlines are dealt with correctly, they currently check out as windows newlines on all computers. Our suggested setup is at:

https://svn.boost.org/trac/boost/wiki/BoostSubversion#MIMETypesandEnd-Of-Lin...

I'll have a look. Thanks again, Christian

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

On 13 December 2010 21:15, Christian Henning <chhenning@gmail.com> wrote:

I suppose you cannot label a subsection with an ID? Like this:

[h2:link_id Something]

You will be able to in a future version. Actually, you can already if you use the [quickbook 1.6] tag in your document info, but that's considered 'unstable' - I might make changes that will break your document, including the algorithm for generating ids so I wouldn't recommend doing that. For now you're stuck with using anchors (see my earlier post). Daniel

...

I suppose you cannot label a subsection with an ID? Like this:

[h2:link_id Something]

You will be able to in a future version. Actually, you can already if you use the [quickbook 1.6] tag in your document info, but that's considered 'unstable' - I might make changes that will break your document, including the algorithm for generating ids so I wouldn't recommend doing that. For now you're stuck with using anchors (see my earlier post).

Note that headings do have ID's now, it's just that you can't control what they're called - so you need to generate the HTML and click on the heading and see what it's link name is to work out what it's ID is - OK you look at the xml to get it's ID as well, but it's easier from the html page IMO. HTH, John.

On 13 December 2010 21:34, Daniel James <dnljms@gmail.com> wrote:

I'm working on this for sections now, and I found some other bugs in the anchor implementation (anchors in the middle of paragraphs currently appear before the paragraph), I meant to deal with this ages ago but it slipped my mind.

Quickbook in trunk now lets you use anchors for sections (ie. '[#anchor][section Section Title]'), and works well with headings. There are a few edge cases where it's still a bit weird but it seems to be better for the existing documentation. Daniel