Subject: Re: [Boost-build] New doc format.
From: Rene Rivera (grafikrobot_at_[hidden])
Date: 2018-01-20 23:34:44
On Sat, Jan 20, 2018 at 3:16 PM, Robert Ramey via Boost-build <
> 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_at_[hidden] <mailto: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.
> Hmmm - I'm not seeing PDF, epub etc.
html, html5, xhtml, xhtml5, docbook, docbook5, docbook45, manpage, pdf,
epub3, latex, mallard
> 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.
Haha.. Let me put it another way.. If you are using a "wisywig" or similar
editor, you are not editing docbook. You're editing a pseudo format as
defined by the tool. And in that respect it's no different than me editing
quickbook or asciidoc ;-)
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.
One of the B2 source files with embedded documentation: <
It's a fatal flaw.
Everything has flaws except what doesn't exist.
> 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.. And reducing the barrier to entry of creating documentation to only
a text editor maximizes the opportunity for documentation to exist.
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.
Perhaps long term was incorrect.. It's some place between short term and
medium term. I'm hoping to have something in this year.
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.
Haha.. Well there's currently *zero* C++ in B2 :-)
-- -- Rene Rivera -- Grafik - Don't Assume Anything -- Robot Dreams - http://robot-dreams.net
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