Re: [Boost-docs] Using Quickbook for TR2 proposals?

Subject: Re: [Boost-docs] Using Quickbook for TR2 proposals?
From: Paul A. Bristow (pbristow_at_[hidden])
Date: 2011-11-29 17:36:36

> -----Original Message-----
> From: boost-docs-bounces_at_[hidden] [mailto:boost-docs-bounces_at_[hidden]] On Behalf Of
> Beman Dawes
> Sent: Tuesday, November 29, 2011 5:08 PM
> To: Boost Documentation List
> Subject: [Boost-docs] Using Quickbook for TR2 proposals?
> 
> Presumably, several Boost developers will be working on TR2 proposals soon, and Quickbook seems
like it
> might be an attractive way to create and maintain those proposals as they go through the committee
> process.
> 
> In particular, I'd like to maintain a single source for reference documentation.  Since I already
follow the
> standard library's conventions for specifications, the textual differences like different
namespaces should
> be easy to cope with using quickbook macros and conditions.
> 
> Is the FAQ "Can I use QuickBook for non-Boost documentation?" entry the best place to start?
> 
> http://www.boost.org/doc/libs/1_48_0/doc/html/quickbook/faq.html
> 
> It might be helpful if we could put together an example for generating
> TR2 proposals.
> 
> Is Quickbook a reasonable approach?

As you know, I'm a Quickbook fan.

In my experience, it hits the sweet spot of giving enough control of layout without being too
complicated.  Any editor will work (though color and bracket matching is desirable).

Its handling of C++ (including syntax coloring) will be just as good for TR2 as for Boost libraries.

It's 'snippets' system allow on the ensure that examples shown are from stuff that actually compiles
(and if it runs, then the actual output as well.  This is especially useful during development when
it is all too easy for examples (synopsis etc) to get out step with the docs.

Footnotes and callouts work well.

I didn't find the auto-conversion from html worked well for me for the translation I was doing.  I
found just copying and pasting the plain text into a Quickbook doc worked as well and forced me to
look more closely at what I was writing.

With some further toolchain setup work, it can also produce (effectively) identical read-only single
file PDF documents.  Despite some unenthusiastic views on the appearance (which might be improved
with some expert input), I think PDF docs still have some advantages.  They can be searched for
strings - something I have been reduced to doing with the C++ Standards.

You can also produce an index fairly automatically.  To be effective, indexing will require some
intelligent human input, but once done, the index is automatically regenerated.

You can have any logo you like.

The downside is that the toolchain is complex to set up - but works fine once going.

Go for it!

Paul

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