Re: [boost] Copy editing documentation - SOC project

From: Matthias Schabel (boost_at_[hidden])
Date: 2007-03-11 17:09:57

> 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). Finally,  
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...

Matthias