Re: [Boost-build] New doc format.

Subject: Re: [Boost-build] New doc format.
From: Rene Rivera (grafikrobot_at_[hidden])
Date: 2018-01-16 17:01:57

On Tue, Jan 16, 2018 at 10:45 AM, Steven Watanabe via Boost-build <
boost-build_at_[hidden]> wrote:

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

It's in the "feature/new-doc-format" branch <
https://github.com/boostorg/build/tree/feature/new-doc-format>.

> - Quite a lot of links are dead.  (It seems like only links to
>   a section are active.)
>

Hmm.. I'll have to figure out how to find and revive missing links.

> - The translation is somewhat out-dated vs. develop.
>

I made some catch up changes yesterday. And I have one more to do in that
regard (the relevant feature doc addition).

> - There's no syntax highlighting for Jam.
>

Was that syntax highlighting manual before? We could certainly work on
adding support for syntax coloring for that component. But that would be
separate work as it's an off-the-shelf syntax coloring module it uses
(which you can configure to use different ones).

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

Yea, they do.. Perhaps just renaming those heading to "Version X.Y.X" would
help.

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

I didn't have to do much fixing. Mostly some regex search-replace for some
things. Most of the time was reading the doc carefully to ensure everything
was there. Although it took a long calendar time.. In reality it only took
less than a week of actual work as I had lots of other things in between,
including holidays and vacation :-)

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