[quickbook] feature request
All (especially documenters), I seem to be rewriting much of the Boost.Graph documentation as I slowly translate it into quickbook format, and augment it with concepts from my SoC project. However, I've run into a "small-ish" missing feature in quickbook that I might need to do the job correctly: bibliography support. Boost.Graph has a (growing) bibliography of about 60 different references. What I would like to be able to do is something like this... # somewhere in graph.qbk [include bibliography.qbk] The bibliography should contains a set of structured records that define bibliographic entries that we can cite in then documentation proper. It would probably be worthwhile to support a number of different entry types. # book references [bibbook [authors [Aho, A.V.] [Hopcroft J.E.] [Ullman J.D.]] [title Data Structures and Algorithms] [year 1983] [publisher Addison-Wesley] ] # journal articles [bibarticle # ... [journal [title Software - Practice and Experience] [volume 25] [issue 8]] [year 1995] [date Aug] [pages 863-889] ] # conference proceedings [bibproceedings # ... [conference 23rd International Conference on Software Maintenance] [location Paris, France] [year 2007] [date Oct 2-5] ] There are probably others to support (i.e., theses and dissertations). Citations should be easy since they're basically just links. A citation might look something like: [bibref aho_1983_data_structures_and_algorithms] This could generate something like: [<a href="...#...">Aho'1983</a>] Although there are a number of different represent references. They could simply be numbers. Does this sound like something that might be useful for quickbook? I was thinking about trying to write it myself, but I'm a little busy between SoC and my narrowing down a dissertation topic. I still might give it a shot, but I don't really know anything about the back-end formatting. Thoughts? Comments? Andrew Sutton asutton@cs.kent.edu
On 6/21/07, Andrew Sutton <asutton@cs.kent.edu> wrote:
All (especially documenters),
I seem to be rewriting much of the Boost.Graph documentation as I slowly translate it into quickbook format, and augment it with concepts from my SoC project. However, I've run into a "small-ish" missing feature in quickbook that I might need to do the job correctly: bibliography support. Boost.Graph has a (growing) bibliography of about 60 different references.
What I would like to be able to do is something like this...
# somewhere in graph.qbk [include bibliography.qbk]
The bibliography should contains a set of structured records that define bibliographic entries that we can cite in then documentation proper. It would probably be worthwhile to support a number of different entry types.
# book references [bibbook [authors [Aho, A.V.] [Hopcroft J.E.] [Ullman J.D.]] [title Data Structures and Algorithms] [year 1983] [publisher Addison-Wesley] ]
# journal articles [bibarticle # ... [journal [title Software - Practice and Experience] [volume 25] [issue 8]] [year 1995] [date Aug] [pages 863-889] ]
# conference proceedings [bibproceedings # ... [conference 23rd International Conference on Software Maintenance] [location Paris, France] [year 2007] [date Oct 2-5] ]
There are probably others to support (i.e., theses and dissertations). Citations should be easy since they're basically just links. A citation might look something like:
[bibref aho_1983_data_structures_and_algorithms]
This could generate something like:
[<a href="...#...">Aho'1983</a>]
Although there are a number of different represent references. They could simply be numbers.
Does this sound like something that might be useful for quickbook? I was thinking about trying to write it myself, but I'm a little busy between SoC and my narrowing down a dissertation topic. I still might give it a shot, but I don't really know anything about the back-end formatting.
Thoughts? Comments?
I think it is a nice feature. It is supported in boostbook so I do not see a reason for not adding it to quickbook. Thanks for pointing it out! Best regards Matias
Matias Capeletto wrote: [snip biblios]
Does this sound like something that might be useful for quickbook? I was thinking about trying to write it myself, but I'm a little busy between SoC and my narrowing down a dissertation topic. I still might give it a shot, but I don't really know anything about the back-end formatting.
Thoughts? Comments?
I think it is a nice feature. It is supported in boostbook so I do not see a reason for not adding it to quickbook.
Thanks for pointing it out!
Sure. Ehm... templates? Regards, -- Joel de Guzman http://www.boost-consulting.com http://spirit.sf.net
Sure. Ehm... templates?
I'm not really that familiar with the feature (or really the internals of the documentation environment) so let me know if I'm stepping wrong somewhere. I think if we try to do it with templates, then people will have to copy the boilerplate template into the documentary structure of every library that has (or wants to have) bibliography. My feeling is that bibliographies and citations support should be a first-class feature of the documentation environment rather than an add-on. It promotes good habits. Also, there might be too much nested structure within bibliography entries for templates. But this is where I might be wrong. I figured I'd spend the morning playing with quickbook and boostbook. Maybe I'll have a rudimentary biblio patch for quickbook by noon - fingers crossed. Andrew Sutton asutton@cs.kent.edu
I figured I'd spend the morning playing with quickbook and boostbook. Maybe I'll have a rudimentary biblio patch for quickbook by noon - fingers crossed.
Well... rudimentary is right. I've got the basic outline of the implemetation. I can mostly parse bib entries and I'm actually generating xml, so that's good. Here's the beginning of a patch. I also fixed 2 warnings - one was the ordering of initializers, the other an unused variable. This is definitely not the prettiest code I've ever written, but it is serviceable. Andrew Sutton asutton@cs.kent.edu
participants (3)
-
Andrew Sutton -
Joel de Guzman -
Matias Capeletto