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

Subject: Re: [Boost-docs] interface between library documentation and Boost website
From: Stefan Seefeld (stefan_at_[hidden])
Date: 2015-07-15 17:49:33

On 15/07/15 01:38 PM, Robert Ramey wrote:
> 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.

Right. But it's a new language (and toolchain) to learn. NIH syndrome
written all over it. :-)

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

Yes, I have been using XXE, and generally am a big fan of DocBook (I
even once mentored a student to port the BoostBook vocabulary to DocBook 5).

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

"Inferior" is a big word. It's always about tradeoffs between what your
goals are and what effort you are willing to put into it.
>From a quick glance at the current Boost.Python docs it appears
something like ReST (python-sphinx or docutils) would work good enough.

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

Right, that's my current thinking: just pick something that's already in
widespread use and live with the limitations.

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

Fine. So what's the entry point ? A single top-level index.html file in
the doc/ directory ?

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

How ?


      ...ich hab' noch einen Koffer in Berlin...

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