Subject: Re: [Boost-build] New doc format.
From: Rene Rivera (grafikrobot_at_[hidden])
Date: 2018-01-20 17:49:59
On Fri, Jan 19, 2018 at 11:01 PM, Steven Watanabe via Boost-build <
> 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.
> >>>> 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
Yea, minor point. Although I do like the flexibility it provides in being
able to mark up the sections in, hopefully, meaningful ways.
> 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.
> > 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
> > 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)
OK, makes sense. I do like the idea of supporting both. Just didn't think
it was worth the effort :-) As I just want better documentation.
> >> (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
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.
Regardless.. I also submitted an issue to hopefully get a search path added
-- -- Rene Rivera -- Grafik - Don't Assume Anything -- Robot Dreams - http://robot-dreams.net
Boost-Build list run by bdawes at acm.org, david.abrahams at rcn.com, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk