Re: [Boost-build] New doc format.

Subject: Re: [Boost-build] New doc format.
From: Steven Watanabe (watanabesj_at_[hidden])
Date: 2018-01-20 05:01:36

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_at_[hidden]> 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_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?
> 

  Yes.  I don't like tag::doc much, although that's relatively
minor.  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)

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

  It isn't the best way, but it's often the most
convenient for checking something quickly.

> <snip>
>>   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?

  Right.  I'm also adding some structural components
and headings.  I had it use #|! (a la doxygen), although
it still handles plain comments (as long as they're in
exactly the right place).

> And you are also taking
> the "native" b2 doc comments and generating adoc from them?

  Yeah.  They're basically plain text, with a few preformatted
blocks, so just passing them through works.  I switched the
preformatted text to use asciidoc syntax.

> Is there
> something else?
> 

- The module and rule docs have a section implicitly
  defined, if you don't put a heading on it explicitly.
  The also get an id equivalent to the jam name, to
  make linking easier.
- class members are structured inside the class rather
  than being read sequentially.

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

In Christ,
Steven Watanabe