Re: [Boost-build] New doc format.

Subject: Re: [Boost-build] New doc format.
From: Rene Rivera (grafikrobot_at_[hidden])
Date: 2018-01-20 20:43:33

On Sat, Jan 20, 2018 at 11:44 AM, Robert Ramey via Boost-build <
boost-build_at_[hidden]> wrote:

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

Right.. We also get that with asciidoctor.

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

I don't find boost book (aka docbook) easy to edit.

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 kind of tweaking possible in the final rendering with asciidoc would
vary depending on the process and output type. For HTML most likely it
would be CSS (or alternative). For docbook output you would be able to use
XSLT or whatever XML transforms or styling the eventual target output lets
you use. No idea for PDF, and other formats though.

> 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/xmledit
> or/license_xxe_perso.html also see http://www.xmlmind.com/xmledit
> or/boostbook.shtml

That is a gigantic fly.. more like a Lucanus maculifemoratus. For Boost
Build with it's current 100 individual contributors it would be impractical
to ask them to deal with XML or any particular XML editing software. It
also has the drawback that we are not able to embed the documentation in
source files.

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

That particular one is key, as the reason it's not kept more up to date is
that it's written in docbook. Which very few of us are comfortable editing.
And which deviates from what the source code actually does because it's
separate from that code.

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.

Right.. Those need more work. That's a long term goal. And one that will
take time and multiple people to make a dent in it.

-- 
-- Rene Rivera
-- Grafik - Don't Assume Anything
-- Robot Dreams - http://robot-dreams.net