On Sat, Jan 20, 2018 at 4:59 PM, Rene Rivera <grafikrobot@gmail.com> wrote:
On Sat, Jan 20, 2018 at 4:16 PM, Steven Watanabe via Boost-build <boost-build@lists.boost.org> wrote:

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@lists.boost.org> 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:
// Organize the class hierarchy in a separate section
// and put them in the order we want

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.

Looks reasonable. 

One thing that occurred to me after some stewing.. I would want to make sure that there's still a mechanism for using custom tags (even if the syntax is different than the asciidoctor syntax). I don't want to be painted into a corner as to what kind of documentation structure I must use. As the inevitable will happen and we will find contexts in which the default doesn't work (or is not ideal). And I can't tell from the changes if you preserved that capability.

-- Rene Rivera
-- Grafik - Don't Assume Anything
-- Robot Dreams - http://robot-dreams.net