Re: [Boost-build] New doc format.

Subject: Re: [Boost-build] New doc format.
From: Steven Watanabe (watanabesj_at_[hidden])
Date: 2018-01-16 16:45:48

AMDG

On 01/14/2018 07:21 PM, Rene Rivera wrote:
> On Sun, Jan 14, 2018 at 5:18 PM, Steven Watanabe via Boost-build <
> boost-build_at_[hidden]> wrote:
> 
>> On 01/14/2018 03:35 PM, Rene Rivera via Boost-build wrote:
>>>
>>> You can peruse the result here <https://grafikrobot.github.io/b2doc/>.
>>>

- Where is the source?  I've about reached the limit of
  what I have to say about the generated html.
- Quite a lot of links are dead.  (It seems like only links to
  a section are active.)
- The translation is somewhat out-dated vs. develop.
- There's no syntax highlighting for Jam.

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

  Yeah, that's better, though I have to say that
the section numbers in the TOC for "History" just
look weird, since you have to look closely to see
where the section id ends and the version # starts.

> 
>> - 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
> :-)
> 

  I don't think it's a great idea to have single
html page.  It's already quite large, and it's
not even close to being complete.  I've been
updating the index for everything I touch.  I've
also been considering passing it though autoindex.

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

  Depending on how much fixing up you had to do, it might
be easier to just split the final output manually.

In Christ,
Steven Watanabe