Re: [Boost-docs] cross-referencing multiple documents with quickbook

Subject: Re: [Boost-docs] cross-referencing multiple documents with quickbook
From: Daniel James (dnljms_at_[hidden])
Date: 2015-08-04 22:04:35

On 18 July 2015 at 16:11, John Maddock <jz.maddock_at_[hidden]> wrote:
>
>
> On 18/07/2015 04:52, Stefan Seefeld wrote:
>>
>> Hello,
>>
>> is it possible to cross-reference multiple stand-alone documents with
>> QuickBook ?
>>
>> I have tried to create a master document that includes the other
>> documents.
>> While that works fine, it doesn't display the individual documents'
>> authors.
>>
>> (For comparison, DocBook supports separate <info> (including author and
>> other metadata) for each chapter, section, etc.)
>
>
> I think you would need to make each "chapter" a separate quickbook doc, and
> then combine them in a single docbook xml book, rather like
> doc/src/boost.xml

You can do that in quickbook 1.6, so this is a 'part' (part of a book):

https://github.com/boostorg/quickbook/blob/feature/doc-tools-documentation/doc/boost-doc-tools/boost-doc-tools.qbk

Which includes 'chapter' files like:

https://github.com/boostorg/quickbook/blob/feature/doc-tools-documentation/doc/boost-doc-tools/install.qbk

Only the containing document needs to be quickbook 1.6, which means
that existing documentation can be included without updating it.

I wrote a little documentation, maybe it's not that clear:

http://www.boost.org/doc/libs/1_58_0/doc/html/quickbook/syntax/structure.html#quickbook.syntax.structure.docinfo.nesting
http://www.boost.org/doc/libs/1_58_0/doc/html/quickbook/versions.html#language_versions.1_6.docinfo

I haven't supported it in a single file (yet?) as the semantics aren't
that clear, and the current implementation doesn't make it easy.