Re: [Boost-docs] interface between library documentation and Boost website

Subject: Re: [Boost-docs] interface between library documentation and Boost website
From: Rene Rivera (grafikrobot_at_[hidden])
Date: 2015-07-17 18:32:15

On Fri, Jul 17, 2015 at 12:22 PM, Stefan Seefeld <stefan_at_[hidden]>
wrote:

> On 17/07/15 02:15 PM, Rene Rivera wrote:
> >
> >     Comparing the above docs with
> >     http://www.boost.org/doc/libs/1_58_0/libs/python/doc/index.html, I
> >     notice a couple of differences, suggesting that the process of
> merging
> >     the Boost.Python docs into the Boost.org website isn't quite as
> >     straight-forward as dropping in some html files into the appropriate
> >     place(s).
> >
> >
> > Which differences are you concerned about? I ask because depending on
> > which ones I may have different answers :-)
>
> Well, I'm concerned about the very fact that there are differences,
> suggesting the process isn't what it is claimed to be. (Either the html
> files are post-processed, or regenerated differently).
>
> The differences I can see (so far) are all minor, and don't really
> concern me per se.
>
> So, I'm interested in all answers you may be able to give. :-)
>
> (The tutorial is generated from quickbook, so I can imagine some
> slightly different stylesheets to be used in the process, but the
> reference manual exists only as raw html, suggesting some tool
> manipulates the html directly (yuck !). I'm considering moving the
> reference manual to quickbook, too, to simplify the overall process,
> before I start editing the content.)
>

OK then..

* Yes, the HTML files as presented on the web site are dynamically
post-process with some PHP scripting. I know, yuck.. But it was the easiest
way to not have to support making the docs match the style of the website,
avoid changing the doc build process, and support browsing docs from
different Boost releases.

* The post-process is not done for all libraries. As some library docs are
too complicated. It's mostly just the ones that use QuickBook/BoostBook.

* The style sheets are different on the web site. They are somewhat more
complex than the regular doc ones.

* Some of the navigation elements/links are removed. Basically the ones in
the header as we try and keep the global web site header around, if
possible, everywhere.

-- 
-- Rene Rivera
-- Grafik - Don't Assume Anything
-- Robot Dreams - http://robot-dreams.net
-- rrivera/acm.org (msn) - grafikrobot/aim,yahoo,skype,efnet,gmail