On Sun, Jan 14, 2018 at 5:18 PM, Steven Watanabe via Boost-build <boost-build@lists.boost.org> 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