Re: [Boost-build] New doc format.

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 
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.

Robert Ramey