Re: [Boost-build] New doc format.

Subject: Re: [Boost-build] New doc format.
From: Robert Ramey (ramey_at_[hidden])
Date: 2018-01-21 02:20:18

On 1/20/18 3:34 PM, Rene Rivera via Boost-build wrote:

> 
> 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 ;-)

Exactly true.

But the wisywig editor I'm recommending gives a very representative 
rendering of the boostbook/docbook source.  It's very convenient and 
easy to use once one has spent a little time with it.  Also I've 
included templates for the types of pages C++ documentation needs - 
Functions, classes, concepts, etc.
> 
>         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/#selecting-an-output-format>
> <http://asciidoctor.org/docs/user-manual/#include-partial>
> <http://asciidoctor.org/docs/user-manual/#by-tagged-regions>

I did see this but didn't really understand what it was referring to.

I sorted expected to find something like Doxygen where one embeds 
Doxygen markdown as part of the comments in the code.  I guess the idea 
would be to insert comments with "tags" so that asciidoc can scan the 
file and extract the asciidoc text from the comments. Doesn't seem to be 
much more than that.  I'm sure you could do the same with quickbook or 
any other markdown.

> 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 :-)

Right - Asciidoc outputs docbook so the rendering should be straight 
forward.  Basically Asciidoc is a docbook editor.  Just not the most 
convenient one.

Robert Ramey