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

Subject: Re: [boost] [quickbook] error with links when building documentation
From: Daniel James (dnljms_at_[hidden])
Date: 2010-12-13 12:07:44

On 13 December 2010 16:17, Christian Henning <chhenning_at_[hidden]> 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]'.

I also made some markup fixes, top level lists shouldn't be indented
because quickbook thinks that indented blocks are code, code blocks in
lists need to be explicitly marked so that quickbook knows they're
part of the list item (thats the '``' lines) and I converted the
docbook in the license information to quickbook.

To explicitly specify a section id use something like:

    [section:tutorial Tutorial]

The id will still be prefixed by the surrounding ids (i.e. in this
case gil.io.tutorial).

To use an anchor to give a header an id:

    [#gil.io.using_io.supported_formats]
    [h2 Supported image formats]

Anchors aren't implicitly scoped in the way section ids are so I had
to specify a full id. Don't duplicate the generated id or you might
get an xml error (ids are meant to be unique). I might put something
in to deal with that case.

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

Daniel