QuickBook generate table of references?

older
Query regarding time complexity...

Nat Goodspeed

27 Jan 2016 27 Jan '16

12:03 a.m.

I have a biggish document consisting of a number of different .qbk files -- big enough to make it unreasonable to start over with a different toolchain. I would like to mark up particular methods of particular classes in such a way that QuickBook will produce a consolidated list of links to those methods. I read a little about DocBook being able to generate tables of figures, etc., but between QuickBook syntax and the final output document, my mental model has a big "then a miracle occurs" cloud. Will someone please show me how this is achieved? Thank you!

Show replies by date

Rene Rivera

27 Jan 27 Jan

1:09 a.m.

On Tue, Jan 26, 2016 at 6:03 PM, Nat Goodspeed wrote:

...

I have a biggish document consisting of a number of different .qbk files -- big enough to make it unreasonable to start over with a different toolchain.

I would like to mark up particular methods of particular classes in such a way that QuickBook will produce a consolidated list of links to those methods.

The answer depends on where the methods are and where you want the links to point to.. Are they in C++ sources? Will the links point to quickbook docs you wrote? I read a little about DocBook being able to generate tables of

...

figures, etc., but between QuickBook syntax and the final output document, my mental model has a big "then a miracle occurs" cloud.

The only miracle is that you can directly include DocBook in QuickBook by escaping from one to the other. -- -- Rene Rivera -- Grafik - Don't Assume Anything -- Robot Dreams - http://robot-dreams.net -- rrivera/acm.org (msn) - grafikrobot/aim,yahoo,skype,efnet,gmail

Robert Ramey

2:16 a.m.

On 1/26/16 5:09 PM, Rene Rivera wrote:

...

On Tue, Jan 26, 2016 at 6:03 PM, Nat Goodspeed wrote:

...
I have a biggish document consisting of a number of different .qbk files -- big enough to make it unreasonable to start over with a different toolchain.

I would like to mark up particular methods of particular classes in such a way that QuickBook will produce a consolidated list of links to those methods.

Hmmm - mark up in the source ala DOxygen? You might take a look at processing the Boost Book output produced by quickbook with xsltproc. But xsltproc is a royal pain if you haven't been through it before. Robert Ramey

Paul A. Bristow

10:47 a.m.

...

-----Original Message----- From: Boost [mailto:boost-bounces@lists.boost.org] On Behalf Of Nat Goodspeed Sent: 27 January 2016 00:04 To: boost@lists.boost.org Subject: [boost] QuickBook generate table of references?

I have a biggish document consisting of a number of different .qbk files -- big enough to make it unreasonable to start over with a different toolchain.

I would like to mark up particular methods of particular classes in such a way that QuickBook will produce a consolidated list of links to those methods.

I read a little about DocBook being able to generate tables of figures, etc., but between QuickBook syntax and the final output document, my mental model has a big "then a miracle occurs" cloud.

Will someone please show me how this is achieved? Thank you!

I recommend using Doxygen and marking up the include files containing the methods/functions using the Doxygen Syntax http://www.stack.nl/~dimitri/doxygen/manual/commands.html. You can then use also Boost Autoindex to get an index of all methods (and classes etc). Getting set up to build docs is a bit tiresome, but works slickly once set up. https://svn.boost.org/trac/boost/wiki/BoostDocs/GettingStarted to get the flavour of what you get, you can see some unfinished work in progress: https://dl.dropboxusercontent.com/u/43940943/modular-boost/libs/fixed_point/... Some typical Doxygen syntax comments (starting with /*!) are in this file, for example https://dl.dropboxusercontent.com/u/43940943/modular-boost/libs/fixed_point/... t/fixed_point_negatable.hpp If you are fumbling (I did) with the setup, contact me off-list. I can provide a dummy docs that will allow you to check that all is working right before altering your real project files. Paul --- Paul A. Bristow Prizet Farmhouse Kendal UK LA8 8AB +44 (0) 1539 561830

Nat Goodspeed

12:31 p.m.

Thank you for suggestions so far! I see that I omitted a key phrase: On Tue, Jan 26, 2016 at 7:03 PM, Nat Goodspeed wrote:

...

I would like to mark up <ins>the QuickBook documentation for</ins> particular methods of particular classes in such a way that QuickBook will produce a consolidated list of links to <ins>the documentation for</ins> those methods.

Ideally I'd like to define a QuickBook template that will (a) insert a bit of boilerplate text into the method description, and (b) add an entry to a central table of references linking back to this anchor. I've already used QuickBook templates enough to be able to accomplish (a). My question concerns (b). I don't know whether that makes it easier or harder, but at least I need to ask the right question.

Paul A. Bristow

3:08 p.m.

...

-----Original Message----- From: Boost [mailto:boost-bounces@lists.boost.org] On Behalf Of Nat Goodspeed Sent: 27 January 2016 12:31 To: boost@lists.boost.org Subject: Re: [boost] QuickBook generate table of references?

Thank you for suggestions so far! I see that I omitted a key phrase:

On Tue, Jan 26, 2016 at 7:03 PM, Nat Goodspeed wrote:

...
I would like to mark up <ins>the QuickBook documentation for</ins> particular methods of particular classes in such a way that QuickBook will produce a consolidated list of links to <ins>the documentation for</ins> those methods.

Ideally I'd like to define a QuickBook template that will (a) insert a bit of boilerplate text into the method description, and (b) add an entry to a central table of references linking back to this anchor. I've already used QuickBook templates enough to be able to accomplish (a). My question concerns (b).

I don't know whether that makes it easier or harder, but at least I need to ask the right question.

I'm not clear what you mean by "central table of references linking ..." Do you mean an index (as might be produced by Boost.Autoindex by adding item to index.idx file)? Or a Quickbook table containing links? Or? Paul

Nat Goodspeed

3:16 p.m.

On Wed, Jan 27, 2016 at 10:08 AM, Paul A. Bristow wrote:

...

...
-----Original Message----- From: Boost [mailto:boost-bounces@lists.boost.org] On Behalf Of Nat Goodspeed Sent: 27 January 2016 12:31 To: boost@lists.boost.org Subject: Re: [boost] QuickBook generate table of references?

Ideally I'd like to define a QuickBook template that will (a) insert a bit of boilerplate text into the method description, and (b) add an entry to a central table of references linking back to this anchor. I've already used QuickBook templates enough to be able to accomplish (a). My question concerns (b).

...

I'm not clear what you mean by "central table of references linking ..."

Do you mean an index (as might be produced by Boost.Autoindex by adding item to index.idx file)?

Or a Quickbook table containing links?

I would like to insert into the middle of the document (well, early on, but whatever) a list of class::method names, each of which links to its own documentation section. I can be flexible concerning the exact presentation of that list.

Nat Goodspeed

3:17 p.m.

On Wed, Jan 27, 2016 at 10:16 AM, Nat Goodspeed wrote:

...

I would like to insert into the middle of the document (well, early on, but whatever) a list of class::method names, each of which links to its own documentation section.

But this should be a list of the specifically marked class::methods, rather than a comprehensive list of all methods described in the document.

Paul A. Bristow

5:18 p.m.

...

-----Original Message----- From: Boost [mailto:boost-bounces@lists.boost.org] On Behalf Of Nat Goodspeed Sent: 27 January 2016 15:18 To: boost@lists.boost.org Subject: Re: [boost] QuickBook generate table of references?

On Wed, Jan 27, 2016 at 10:16 AM, Nat Goodspeed wrote:

...
I would like to insert into the middle of the document (well, early on, but whatever) a list of class::method names, each of which links to its own documentation section.

But this should be a list of the specifically marked class::methods, rather than a comprehensive list of all methods described in the document.

I can't see how to do this automatically rather than a manual Quickbook table one of whose fields is links to the matching anchor for the method documentation. If you are willing to go the Doxygen syntax route, then you could * control which methods *generate documentation* by using the Doxygen setting to only include methods for which doxygen syntax documentation is provided (in the header file of course - where it belongs IMO) and then * insert an index of methods anywhere you like in the Quickbook document. This would look like the method index in the example I gave earlier, but not provide links to anchor, but links to the Doxygen syntax documentation directly. Sounds like you shouldn't start from where you are! I suspect that you are better off doing it by hand, however tedious. But of course if you change anything, you will have to change the documentation by hand, exactly what an automated system is trying to avoid. Paul --- Paul A. Bristow Prizet Farmhouse Kendal UK LA8 8AB +44 (0) 1539 561830

3227

Age (days ago)

3227

Last active (days ago)

List overview

Download

8 comments

4 participants

participants (4)

Nat Goodspeed
Paul A. Bristow
Rene Rivera
Robert Ramey