Re: [Boost-build] New doc format.

Subject: Re: [Boost-build] New doc format.
From: Rene Rivera (grafikrobot_at_[hidden])
Date: 2018-01-15 02:21:49

On Sun, Jan 14, 2018 at 5:18 PM, Steven Watanabe via Boost-build <
boost-build_at_[hidden]> wrote:

> AMDG
>
> On 01/14/2018 03:35 PM, Rene Rivera via Boost-build wrote:
> > After asking about documentation tools some months back I ended up doing
> a
> > full "trial" with asciidoctor to see how it would work out for the new B2
> > documentation. I realize that others had ideas as to what might be a
> better
> > tool. But after looking into some others I decided asciidoctor was the
> > least effort to attempt to change to. And that the features, with regards
> > to B2, where sufficiently equivalent with the other top contenders.
> >
> > You can peruse the result here <https://grafikrobot.github.io/b2doc/>.
> >
>
> At a quick glance:
> - On the front page: s/totorial/tutorial/
>

D'oh.. Fixed.

> - Navigation is really annoying because there is only a single
>   global TOC which is restricted to a depth of two levels.
>

Switched it the side-bar TOC and made it three levels. Makes it a bit
better I think. What do you think?

> - The index is missing.
>

Yea.. Not sure that's coming back. First, the index entries got lost in
translation. Second, although asciidoctor supports marking index entries,
it only seems to support them for PDF and docbook output. But.. First, if
the docs stay as one html doc an index is not needed terribly as one can
just search in the page. Second, the index entries we have in the existing
docs are almost entirely useless and rather minimal. So I wouldn't miss
having the index. And I would definitely not mind not having to update it
:-)

> > There are only some minor items missing in the docs (examples only
> AFAIK).
> > The process for transferring the docs turned out to involve using
> quickbook
> > to generate boostbook for the non boostbook parts. And using pandoc to
> mass
> > translate from boostbook (assuming it was close enough to docbook)
>
>   Any reason you didn't convert boostbook to docbook?

Just building the docs normally, creates
> standalone.docbook as an intermediate step.
>

Actually.. I don't remember.. I may have done that :-) It's been a while
since I did the initial translation to remember accurately. But I suspect
the reason I probably did not was to keep the same set of files (i.e.
one-to-one xml-to-adoc).

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