Re: [Boost-build] New doc format.

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

AMDG

On 01/20/2018 10:49 AM, Rene Rivera wrote:
> On Fri, Jan 19, 2018 at 11:01 PM, Steven Watanabe via Boost-build <
> boost-build_at_[hidden]> wrote:
> 
>> 
>> <snip>
>> 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.
>>
> 
> That's a really good point. Although I've also found that any ordering I
> could program it to come out with, say with the --help system, would also
> be wrong. And hence the best arrangement would only be possible manually,
> with a bunch of bookkeeping. So I guess the key is to find a way to reduce
> the bookkeeping to make it possible to arrange the reference documentation
> in the ideal way.
> 

  I think I want the final structure to be specified in
a single place, outside the source.  (I'd rather try
to keep the code readable and put all the fussy formatting
somewhere else)

So, ideally the documentation would look something like this:

include::asciidoctor.adoc[] // The default ordering just works

// We need to put things right manually:
include::targets.adoc[tag=!class]
// Organize the class hierarchy in a separate section
// and put them in the order we want
include::targets.adoc[tag=abstract-target]
include::targets.adoc[tag=basic-target]

I think it shouldn't be too hard to auto-generate
tags wrapping each part.  It should be unambiguous,
since it's the name of whatever jam construct is
being documented.

  I imagine that most tool modules will just have
a single main block of documentation + documentation
of initialization + documentation of features, which
we can just lay out in a standardized format.  It's
mostly the internal modules that have more complex
relationships or that are implicitly imported
which may need to be handled specially.

>>
>>>> (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.)
>>>>
>>>
>>> <snip>
>>
> 
> That is unfortunate.. But I'm okay with them getting put in the src dir and
> added to git also. As they should be stable enough for version control.

  It's not necessary to add them to git.  I made the
Jamfile write them to the correct place.  (I remember
we used to do the same thing with quickbook, a
long time ago when the boostbook toolchain wasn't
able to process the implicit-dependencies)

> Regardless.. I also submitted an issue to hopefully get a search path added
> <https://github.com/asciidoctor/asciidoctor/issues/2540>.
> 

In Christ,
Steven Watanabe