Re: [Boost-build] New doc format.

Subject: Re: [Boost-build] New doc format.
From: Steven Watanabe (watanabesj_at_[hidden])
Date: 2018-01-14 23:18:19

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/
- Navigation is really annoying because there is only a single
  global TOC which is restricted to a depth of two levels.
- The index is missing.

> 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.

> to
> asciidoctor. THen it was a matter of going through all the docs and fixing
> up any translation errors.
> 
> 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.
> 

In Christ,
Steven Watanabe