Re: [boost] Copy editing documentation - SOC project

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.

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

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
http://dblatex.sourceforge.net/examples.html 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.

Regards,
-- 
Joel de Guzman
http://www.boost-consulting.com
http://spirit.sf.net