On Sat, Jan 20, 2018 at 8:20 PM, Robert Ramey via Boost-build <boost-build@lists.boost.org> wrote:
On 1/20/18 3:34 PM, Rene Rivera via Boost-build wrote:

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

Yes, Quickbook does that. Because I helped write that feature in Quickbook. Which I use in Predef for its reference documentation. And also use it in B2 the same way (but only for a small test case). Because of that feature it's possible for external contributors to Predef to quickly write not just the code but the documentation in an easy to review PR. Usually without them having to really understand how the documentation works nor actually run the documentation tools.
 
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. 

Note.. That docbook is only one of the formats asciidoctor can output. Although it's likely one of the least used output formats.
 
Basically Asciidoc is a docbook editor.  Just not the most convenient one.

Convenience is subjective. To me it's convenient because I don't have to spend considerable effort to teach contributors how to write documentation. They can bring up whatever editor they are already using to contribute the code and emulate the existing really simple documentation syntax in one place. And hence I suspect it's convenient for them because they don't have to search out, install, and learn an additional tool. It's also convenient for me in that I can look at a PR and understand documentation edits without having to understand XML+BoostBook+Docbook.


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