Re: [Boost-build] New doc format.

Subject: Re: [Boost-build] New doc format.
From: Rene Rivera (grafikrobot_at_[hidden])
Date: 2018-01-20 22:59:37

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.

  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.

Right. There's also types and utils to document.

> It's
> mostly the internal modules that have more complex
> relationships or that are implicitly imported
> which may need to be handled specially.
>

Sure.

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