Re: [Boost-build] New doc format.

Subject: Re: [Boost-build] New doc format.
From: Rene Rivera (grafikrobot_at_[hidden])
Date: 2018-01-21 04:50:08

On Sat, Jan 20, 2018 at 8:20 PM, Robert Ramey via Boost-build <
boost-build_at_[hidden]> 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