Re: [Boost-build] New doc format.

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 <
boost-build_at_[hidden]> wrote:

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

<http://asciidoctor.org/docs/user-manual/#selecting-an-output-format>

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

<http://asciidoctor.org/docs/user-manual/#include-nonasciidoc>
<http://asciidoctor.org/docs/user-manual/#include-partial>
<http://asciidoctor.org/docs/user-manual/#by-tagged-regions>

One of the B2 source files with embedded documentation: <
https://github.com/boostorg/build/blob/feature/new-doc-format/src/tools/asciidoctor.jam
>

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