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
> http://rrsd.com/blincubator.com/tools_documentation/

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 Boost.org 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 ?

    Stefan

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