On 1/20/18 12:43 PM, Rene Rivera via Boost-build wrote:

On Sat, Jan 20, 2018 at 11:44 AM, Robert Ramey via Boost-build <boost-build@lists.boost.org <mailto:boost-build@lists.boost.org>> 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.

Hmmm - I'm not seeing PDF, epub etc.

    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.

LOL - because you're doing it wrong.

It also has the drawback that we are not able to embed the documentation in source files.

Hmmm - I looked at the asciidoc documentation and didn't find a way to do this.  But I'll take your word for it that it's doable.  I don't know what the source code looks like afterward.

It's a fatal flaw.

    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.

Right.  But docbook isn't the problem.  It's the editing of docbook which is the problem.

Which very few of us are comfortable editing.

I 100% agree that editing docbook with a text editor is a non-starter.

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.

If you want b2 to be a thing, it should be a shorter term goal.

PS - there IS one thing that might be worthy of discussion.  That is BoostBook vs DocBook.  BoostBook adds a bunch of very specific C++ tags which are processed into DocBook tags via an XSLT transform.  But as it turns out, very few if any BoostBook tags are actually used in boost documentation.  So things wouldn't change much if the BoostBook layer were dropped and one wrote (via whatever editor he wanted) and worked with DocBook directly.  (Quickbook might require an update though). This is not a big deal, it would just make the processing a little simpler.