Re: [boost] Boost documentation

From: troy d straszheim (troy_at_[hidden])
Date: 2007-06-25 02:50:16

On Sun, Jun 24, 2007 at 08:24:42PM +0800, Joel de Guzman wrote:
> 
> No, "get rid" is too strong a term. The real goal is to provide
> alternative back ends (e.g. direct HTML, LaTEX, DocUtils,  etc.,
> in addition to DocBook). This can be achieved through a set of
> back end template libraries. And, no, I don't think it is a short
> term goal. 

If I understand correctly, pandoc,

  http://sophos.berkeley.edu/macfarlane/pandoc/

works like this.  It works well.  I did my best to switch to pandoc
but I found markdown to be too limited, especially the lack of code
syntax highlighting.  So a pandocish tool in C++, that reads Quickbook
and writes HTML/latex/whatever, and where one can just add back-ends
for new formats/tools...  very cool.

> The short term goal is to simplify quickbook a lot
> more than it is now (a targeted 90% reduction in c++ code size)
> by moving to template libraries. We'll end up with a standard
> template library with 90% of the functionality of quickbook
> plus a set of intrinsics in c++ code. *** We're actually
> striving to make quickbook simpler, not more complex ***
>
> Why? some people, do not like the elaborate tool chain that
> Doc/BoostBook requires. Some parts of the tool chain, e.g. FOP,
> is severely broken, XSLT is so slow and difficult to understand
> and maintain, etc. DocBook is not perfect, you know. It too has
> its own sets of problems.

I'm one of those people.  I wrote a lot of docs in quickbook at one
point and lost a couple of days to trying to get FOP to make PDFs.
I'd hacked quickbook a little (which itself was fun and educational),
but it was nearly impossible to tell where the errors were occurring
(xsltproc, the stylesheets, apache-fop... egh.)  It was also
frustrating that nothing that came of the process was contributable
back to boost, just a bunch of shell scripts that didn't do anything
generally useful.  

-t