Revamp the header information

[Joel de Guzman]

(see this thread for context: ​http://tinyurl.com/2b9ywv)

Allow a couple of the (header) items there to be *overridden* in included files. Example:

• copyright (a) or (b)
• authors (a) or (b)
• license (a) or (b)
• last-revision (a), if it's more recent than current value

where:

a) Merge with the current value. b) Use new value only for current file/doc.

I took out all the ones you have as (c) -- Ignore the new value. I also took out source-mode since this can already be overridden.

So, these overrides can be placed anywhere. Example:

main.qbk

[library foo

[quickbook 1.4] [version 1.4] [copyright 2006 Joe Bloke] [authors [Bloke, Joe]] [purpose Whatever...] [license

Distributed under the Boost Software License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at [@http://www.boost.org/LICENSE_1_0.txt])

] [last-revision $Date: 2006/09/16 09:21:08 $]

]

include.qbk

[license

Distributed under the Boost Software License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at [@http://www.boost.org/LICENSE_1_0.txt])

]

[last-revision $Date: 2006/09/16 09:21:08 $]

John (M):

I like the way this is going, but I would actually prune the list of overrides a little more:

[last-revision...]

Definitely needed, as per my original post :-)

[quickbook....]

Also needed so that individual includes can start using new features without having to go through and fix errors in the whole doc.

[version...]

Not sure about this one, shouldn't a library have a single version number?

[copywrite...][authors...]

These would be useful to have: especially for "meta-libraries" like Boost.Math which has many sub-components by different authors.

The ideal world senario - probably not possible (!) - would be to merge all the author names onto the main front page, but for sections just to include the authors who worked on that section. Does that make sence?

[purpose...]

Isn't this used just once on the main page, or maybe the index of libraries? I don't see any great advantage to having more than one such block.

[license...]

Given that everything should be under the same license (as far as Boost is concerned anyway), having more than one such block just complicates things.

[Joel de Guzman]

Also, from John:

Another couple of bug reports, and a couple of feature requests as well (just tell me when to shut up!).

The [category tag] markup inside the the main [library ..] block over-writes previous invocations, so for example in BoostBook I can assign a library to multiple categories (and if you look in boost.xml you'll see several that make use of this), but if I have:

[library Boost.TypeTraits [copyright 2000 2005 blah blah] [purpose Meta-programming support library] [license blah blah] [authors [authors, various]] [category template] [category generic] [last-revision $Date: 2005/04/16 16:29:33 $] ]

Then the last [category ...] seen over-writes whatever other invocations have been made (so the only category in the XML output is "generic" in this case).

To fix this I tried escaping to BoostBook, but any attempt to put a escape inside a [library ..] block produced quickbook errors.

[Daniel James]

(In [62471]) Support multiple categories. Refs #1200.

[Joel de Guzman]

Daniel, I reassigned the Qbk tickets to you. I hope you don't mind. I'm no longer updated with the latest Qbk developments.