On 01/19/2018 07:34 PM, Rene Rivera wrote:
> On Fri, Jan 19, 2018 at 4:14 PM, Steven Watanabe via Boost-build <
> email@example.com> 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 <
>>> firstname.lastname@example.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
>>>>> with more automation, style, additions, rewrites, etc changes. Assuming
>>>>> 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
>>> 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
Yes. I don't like tag::doc much, although that's relatively
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.
> 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)
>> (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
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:
Add the specified directory to the load path, so that -r can load
extensions from outside the default Ruby load path