Re: [Boost-docs] quickbook/boostbook relationship

Subject: Re: [Boost-docs] quickbook/boostbook relationship
From: Paul A. Bristow (pbristow_at_[hidden])
Date: 2012-03-20 10:16:11

> -----Original Message-----
> From: boost-docs-bounces_at_[hidden] [mailto:boost-docs-bounces_at_[hidden]] On Behalf Of
> Robert Ramey
> Sent: Sunday, March 18, 2012 7:30 PM
> To: boost-docs_at_[hidden]
> Subject: Re: [Boost-docs] quickbook/boostbook relationship
> 
> Daniel James wrote:
> > On 9 March 2012 23:05, Robert Ramey <ramey_at_[hidden]> wrote:
> >>
> >> I don't see how one would generate all this with the quickbook
> >> syntax. In other words it looks like quickbook is "quick" because it
> >> skips a lot of the boostbook elements structure but maintains the
> >> formating - which is really quite a different thing than boostbook.
> >
> > Quickbook doesn't have any support for writing boostbook reference
> > documentation, most people write it using doxygen, write it directly
> > in boostbook, or write it in quickbook. Quickbook does have support
> > for linking to boostbook reference document (funcref, classref etc.)
> > so it integrates well with it and isn't just a docbook generation
> > tool.
> >
> > AFAIK there's no one has ever expressed any desire for writing
> > boostbook reference documentation in quickbook, I don't think it'd be
> > a particularly good match. It might be possible to do something using
> > escaped boostbook and templates.
> 
> Thanks for your response.  I've become quite interested in ways to make effective documentation
simpler
> to generate and more useful.
> 
> Soooo, just to make sure I understand all this more or less correctly.
> 
> a) In the beginning there was DocBook
> b) Doug Gregor made BoostBook as DocBook with an extra layer of sauce for detailed specification
of
> functions, classes, member functions, etc.
> c) A couple of libraries have used BoostBook directly. Any, DateTime but those don't seem to use
all the
> detail that BoostBook has.
> d) Joel Guzman made quickdoc as a quick way to generate HTML from a simpler mini-language
> e) Eric Neibler used this to make quickbook which generates BoostBook.
> The generated BoostBook doesn't included all the BoostBook "detail"
> because the quickbook mini-language doesn't have a syntax to specify it and also because no one
seemed
> suffiiciently interested to do this because 1) It's a pain the butt, and 2) no other tools rely on
or exploit it.
> f) Doxygen has been used to generate XML which is then processed using xsltproc to BoostBook which
is
> then linked into the quickbook generated documents.
> 
> I think that's how things are and how they got to be this way.

I don't think that this is quite the end of the story because you haven't mentioned PDF.
 
> Which is OK.  Since the de-facto canonical form of boost documents is HTML it really doesn't
matter how
> one get's here.

Although HTML is a requirement, for me PDF is also an extremely desirable end product of the
documentation process.

The docs are  a single document and can be searched from end to end and used offline.  All the
hyperlinking works as well as the HTML, version including indexes.

Steven Watanabe and John Maddock have done a lot of work to get this to function and many Boost
libraries are also available in this format.

> So I think I understand the whole process.  There are a number of things I don't like about it,
but that
> would be going off topic.

I don't like the whole tool chain either, but once (if painfully) set up, it does the business quite
smoothly.

Paul

---
Paul A. Bristow,
Prizet Farmhouse, Kendal LA8 8AB  UK
[phone]  07714330204
pbristow_at_[hidden]