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

Subject: Re: [Boost-docs] interface between library documentation and Boost website
From: Paul A. Bristow (pbristow_at_[hidden])
Date: 2015-07-15 16:44:34

> -----Original Message-----
> From: Boost-docs [mailto:boost-docs-bounces_at_[hidden]] On Behalf Of Stefan Seefeld
> Sent: 15 July 2015 16:58
> To: boost-docs_at_[hidden]
> Subject: Re: [Boost-docs] interface between library documentation and Boost website
> 
> On 15/07/15 11:49 AM, Robert Ramey wrote:
> > On 7/15/15 8:05 AM, Stefan Seefeld wrote:
> >> Hello,
> >>
> >> I'm reviewing the Boost.Python documentation, which right now consist
> >> almost entirely of raw html.
> >> These html files aren't fully functional as they contain relative
> >> URLs that only work once the docs have been pulled into the main
> >> Boost website.
> >
> > Hmmm - does the usage of relative URLS make it possible to browse the
> > documentation regardless of where it's located?
> 
> In general, yes. But in my case the errors I'm observing stem from dangling references to
stylesheets
> that only exist after the merge, plus some references to pages outside the library docs.

This relative linking is an issue for most, if not all, documentation, including that produced by
the popular Quickbook toolchain.

So, to provide a working view of documentation *in draft*, I have resorted to putting a skeleton
Boost tree
into my DropBox and pasting in the doc/html/ folder into the right place for the library.  This
still requires one to also paste in the folder example contents (and indeed /include/boost folder)
if these are references (good practice).

Although this works, I am not entirely happy doing this and suspect it would be better for each
/html/ folder to be self-contained, at least as far as style sheets and the Boost logo and various
navigation and other icons.

Links to other boost libraries is done by Quickbook using a special @boost: type of link.  This
assumes the existence of the Boost tree as well, unless it could be made to reference items in
boost.org.

(It would be nice if these relative links could be at least reduced so that the style sheets and
logo and icons are right?)

In the case of Python, a brief glance suggest that the appearance come from the use of a local
rather skeletal boost.css rather than boostbook.css.  .  It might be possible to change this to give
a uniform appearance? Some parts like tutorial are written using Quickbook toolchain and look
'normal'.

Paul

PS It is sad that on github, clicking on the index.html file shows the raw html, not what you see
using a browser. There is a github.io bit of javascript, but it is very partially successful :-(