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

Subject: Re: [Boost-docs] interface between library documentation and Boost website
From: Robert Ramey (ramey_at_[hidden])
Date: 2015-07-15 17:38:38

On 7/15/15 10:01 AM, Stefan Seefeld wrote:
> On 15/07/15 12:44 PM, Paul A. Bristow wrote:
>> This relative linking is an issue for most, if not all, documentation, including that produced by
>> the popular Quickbook toolchain.
> True.

> Yes, that would solve this particular issue. Still, there are quite a
> number of frameworks available that allow documentation for various
> media (including html and pdf) to be generated from a much simpler to
> author markup formats,

This is a question going back a long way. The solution was boost book -
derived from docbook. This uses xslt to generate html, pdf or whatever.
Since, editing boostbook is a pain, several solutions options for that
have evolved.

a) quickbook generates boostbook from a marked up file. It has been the
most frequently chosen option for generating boost documentation. I
would say it's been quite successful and the documents created - html
and pdf have been of good quality.

b) my personal favorite is to use a boostbook xml editor - the one that
has worked well for me is described here

c) other options, markdown, doxygen, raw html, I have found to be inferior.

We've sort of decided to not try to impose a common requirement as the
tools have evolved faster than boost library documentation has. And of
the work involved just wouldn't be worth it.

> Still, my original question remains: what is the interface that the
> Boost website integration requires from library documentation ?

Not much. provide one of the following:

a) raw html files generated any way you want
b) boostbook xml files
c) quickbook xml files.

> documentation files need to be present in a given Boost library, and
> what (if any) are the requirements on their content ?

My views are described here. The web page has an opportunity to comment
but no one has ever done so. So, I'm going to assume the fairly
represent the consensus of the community.

> What is the the exact process used to generate the website
> from library docs ?

For using boostbook/quickbook - this is described somewhere. It DOES
work, but it's not totally pain free to setup

How can I run that locally to validate my changes to
> my library docs ?

You can, and I do.

Robert Ramey

This archive was generated by hypermail 2.1.7 : 2017-11-11 08:50:41 UTC