Re: [Boost-build] New doc format.

Subject: Re: [Boost-build] New doc format.
From: Rene Rivera (grafikrobot_at_[hidden])
Date: 2018-01-20 02:34:40

On Fri, Jan 19, 2018 at 4:14 PM, Steven Watanabe via Boost-build <
boost-build_at_[hidden]> 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_at_[hidden]> 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