Subject: Re: [Boost-build] New doc format.
From: Robert Ramey (ramey_at_[hidden])
Date: 2018-01-20 17:44:13
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
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
> I've always been of the the view that B2 documenation content would
> benefit from some investment of effort.
> 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.
> 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.
Boost-Build list run by bdawes at acm.org, david.abrahams at rcn.com, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk