Re: [Boost-build] New doc format.

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

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