Boost logo

Boost :

From: Joel de Guzman (joel_at_[hidden])
Date: 2007-03-11 19:42:01

Matthias Schabel wrote:
>> FYI, QuickBook already has the reverse-lit feature. It lets you
>> "import" code snippets from actual code. Rene and I are using it
>> right now to great effect.
> I have to say, as a non-CS person, I'm finding it hard to even keep
> track of the differences between DocBook, BoostBook, and QuickBook,
> much less figure out how to accomplish anything with them... Just as
> a side note, given that documentation is already generally regarded as
> one of the most painful parts of library development, I think it
> would be
> a good idea for Boost to standardize on one system or another and
> then provide a good tutorial on how to use it... For example, after
> browsing all the QuickBook documentation I could find, I still have
> no idea how to implement the code snippet import feature you
> described; furthermore, as far as I can tell, there is no .qbk source
> in Boost (from recent CVS-HEAD) that I could use to try to emulate
> your Spirit documentation (assuming that is the documentation that
> uses this reverse-lit import, which I can't know a priori).

Have you looked at the QuickBook documentation itself? It's
in the Boost CVS HEAD at /tools/quickbook/index.html under
section "Import". That feature is a fairly new addition.

Oh, and Spirit does not use QuickBook. The docs predate QuickBook.
Actually, the Spirit docs motivated its development.

> while
> there appears to be some way to have DocBook output LaTeX, it
> isn't clear to me that there is any way to have it parse and process
> LaTeX source in, for example, the way that Doxygen does so that
> you can get images of typeset equations in the HTML output. Maybe
> it's possible, but it is certainly far from obvious, and the amount of
> time I would have to invest learning a completely new system hardly
> seems to justify the potential benefit. Anyway, sorry for the rant - it
> just doesn't seem like this should be this painful...

DocBook can output LaTEX but it cannot parse and process LaTeX
source. There's a way to get MathML in, however. That avenue is
being explored as we speak. You might want to take a look at for example. That's
the possibilities we are investigating on.

I understand your rant perfectly. You do understand that we are
first and foremost library writers and not really tool makers,
right? That is why I keep on urging people to help in any way
they can. The tools we use work, but they are far from perfect.
There are only a handful of people actively participating in the
doc tools department. We basically have a grasp on what needs
to be done, yet, what we do lack is the needed time to actually
implement them.


Joel de Guzman

Boost list run by bdawes at, gregod at, cpdaniel at, john at