Modify

Opened 10 years ago

Last modified 4 years ago

#1200 new Tasks

Revamp the header information

Reported by: Joel de Guzman Owned by: Daniel James
Milestone: To Be Determined Component: quickbook
Version: Boost 1.34.1 Severity: Problem
Keywords: Cc:

Description

(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.

Attachments (0)

Change History (3)

comment:1 Changed 10 years ago by 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.

comment:2 Changed 8 years ago by Daniel James

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

comment:3 Changed 4 years ago by Joel de Guzman

Owner: changed from Joel de Guzman to Daniel James

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

Modify Ticket

Change Properties
Set your email in Preferences
Action
as new The owner will remain Daniel James.

Add Comment


E-mail address and name can be saved in the Preferences.

 
Note: See TracTickets for help on using tickets.