Boost logo

Boost-Build :

Subject: Re: [Boost-build] New doc format.
From: Steven Watanabe (watanabesj_at_[hidden])
Date: 2018-01-19 22:14:35


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. In addition, I really
want the built-in help to work. In the past, I
went to the trouble of duplicating the documentation
between the jam sources and docbook, which I really hate.

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

In Christ,
Steven Watanabe

Boost-Build list run by bdawes at, david.abrahams at, gregod at, cpdaniel at, john at