On 1/20/18 9:03 AM, Rene Rivera via Boost-build wrote:

    I'm very happy with the boost book approach.


What aspect(s) of it are you happy with?

a) I like the fact that it separates the content from the presentation so that one can edit the content once and generate as needed renderings in html, singlepage html, pdf, epub or perhaps something else.

b) I find boost book very easy to edit.  Combined with a) above it lets me edit boost book without much regard for the final rendering which is addresses separately.

c) I can tweak the formating of the final rendering via some xmlt. Granted xml transform is a kludgy system, but I does actually work and generally their is very little of this work to do.

The fly in the ointment is the actual editing of boost book.  But I have found this nicely addressed by XMLmind personal edition which can be downloaded for free http://www.xmlmind.com/xmleditor/license_xxe_perso.html also see http://www.xmlmind.com/xmleditor/boostbook.shtml

    I've always been of the the view that B2 documenation content would
    benefit from some investment of effort.

Yes.

    Doing both of the above in one shot seems a bad idea to me.

Not doing both at the same time. First step in this is putting the existing documentation in a format and arrangement that facilitates the editing, creation, and presentation of that documentation to as many audiences as possible.

see above

Part of this is also looking forward at a time when B2 will not be primarily advertised as a member of Boost.

Right - Worthy goals.

FWIW - I've never thought that the documentation for B2 was bad - as far as it goes.  I've felt that:

a) it can be added to and kept more up to date.

b) it's hard to write.  There are two ways of looking at this.

1) Work harder at writing it.
2) Think about why it's hard to write.

I think the correct approach is 2).  When something is really hard to describe, maybe it's a sign that the thing we're trying to describe needs to be considered.  Often times it's easier to fix the tool/library so it makes more sense that to try to describe something that is actually more complex than it needs to be.  Sources of problems are implicit behavior, side effects, global settings/variables, non-obvious inherited behavior, etc.