Re: [Boost-build] New doc format.

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 <
boost-build_at_[hidden]> wrote:

> AMDG
>
> 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.
> Assuming
> >>>> 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
> minor.

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
> plain
> > 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
<https://github.com/asciidoctor/asciidoctor/issues/2540>.

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