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

AMDG

On 01/19/2018 07:34 PM, Rene Rivera wrote:
> On Fri, Jan 19, 2018 at 4:14 PM, Steven Watanabe via Boost-build <
> boost-build@lists.boost.org> wrote:
>
>> 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?
>

Yes. I don't like tag::doc much, although that's relatively
minor.

Yea, minor point. Although I do like the flexibility it provides in being able to mark up the sections in, hopefully, meaningful ways.

What's more important is that it's essentially
folding two independent files which have no understanding
of each other into one. It's not too bad as long as you just
have a single adoc block at the top, but in general the
linear order of the code is not necessarily the order in
which the documentation needs to appear--fixing that requires
a lot of manual bookkeeping.

That's a really good point. Although I've also found that any ordering I could program it to come out with, say with the --help system, would also be wrong. And hence the best arrangement would only be possible manually, with a bunch of bookkeeping. So I guess the key is to find a way to reduce the bookkeeping to make it possible to arrange the reference documentation in the ideal way.

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

That's fine. asciidoc is mostly readable as is.
I just stripped out a few of the obvious things
like ```. (I actually considered piping it through
asciidoctor -bmanpage -o - - | man -l -, but that
may not be available)

OK, makes sense. I do like the idea of supporting both. Just didn't think it was worth the effort :-) As I just want better documentation.

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

That's the first thing I tried. It doesn't do what you
think it does. Here's a slightly different description
from the online docs:

-I, --load-path=DIRECTORY

Add the specified directory to the load path, so that -r can load
extensions from outside the default Ruby load path

That is unfortunate.. But I'm okay with them getting put in the src dir and added to git also. As they should be stable enough for version control. Regardless.. I also submitted an issue to hopefully get a search path added <https://github.com/asciidoctor/asciidoctor/issues/2540>.

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