On Fri, Jan 19, 2018 at 4:14 PM, Steven Watanabe via Boost-build <boost-build@lists.boost.org> wrote:
AMDG

On 01/18/2018 09:57 PM, Rene Rivera wrote:
> On Thu, Jan 18, 2018 at 7:09 PM, Steven Watanabe via Boost-build <
> boost-build@lists.boost.org> wrote:
>
>> On 01/14/2018 03:35 PM, Rene Rivera via Boost-build wrote:
>>>
>>> This is just an initial translation.. And will be followed in the future
>>> with more automation, style, additions, rewrites, etc changes. Assuming
>> key
>>> people are okay with this new set of docs.
>>>
>>
>>   One thing that I'm not happy about is the way
>> the docs are included in the sources.
>
>
> Can you explain your unhappiness? As I think having reference documentation
> in the sources is preferable for a variety of reasons.
>

  I don't think it's a bad thing per se, but I find
the way it was handled to be ugly. 

I'm confused on that.. You find the asciidoctor way to be ugly? Something else? 

In addition, I really
want the built-in help to work.

Okay.. But the best you'll be able to do that is to spit back out the plain asciidoc content when one invokes --help. And like I said before.. I don't think the command line is the best place to read documentation. But, hey, if you can make the --help work, great :-) 

  In the past, I
went to the trouble of duplicating the documentation
between the jam sources and docbook, which I really hate.

Right.. I also don't like duplicating this stuff. It's a route to having outdated docs.
 
>> If we're
>> going to have the docs in the jam sources, I think
>> it should be integrated with the --help system,
>> so it can be viewed from the command line and also
>> to fit into the codebase better.  I've made some
>> initial changes to get --help to output adoc (under
>> the assumption that the doc comments are valid
>> asciidoc) and it seems feasible.
>>
>
> Okay.. Not sure if it's worth the effort. But I'm not against that.

  I've just pushed my initial take on this to feature/adoc-help.
It's implemented for asciidoctor.jam and zlib.jam.
What do you think?

I'm trying to understand what you did. You have b2 extract the asciidoc instead of having asciidoctor extract it directly? And you are also taking the "native" b2 doc comments and generating adoc from them? Is there something else?
 
(I really wish that asciidoctor had a way to set an
include path.  Copying files into the source directory
just so they can be found is really annoying.)

There is.. From `asciidoctor --help`:

    -I, --load-path DIRECTORY        add a directory to the $LOAD_PATH
                                     may be specified more than once

Which is already implemented through the usual <include> feature in asciiidoctor.jam.

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