Re: [Boost-build] New doc format.

Subject: Re: [Boost-build] New doc format.
From: Rene Rivera (grafikrobot_at_[hidden])
Date: 2018-01-22 03:04:18

On Sat, Jan 20, 2018 at 4:59 PM, Rene Rivera <grafikrobot_at_[hidden]> wrote:

> On Sat, Jan 20, 2018 at 4:16 PM, Steven Watanabe via Boost-build <
> boost-build_at_[hidden]> wrote:
>
>> 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.
>>
>
> 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