Re: [Boost-docs] boost-root/doc/test needed

Subject: Re: [Boost-docs] boost-root/doc/test needed
From: Eric Niebler (eric_at_[hidden])
Date: 2008-07-30 20:34:28

Daniel James wrote:
> On 30/07/2008, John Maddock <john_at_[hidden]> wrote:
>>  Some docs on the docs would be a start though I guess...
> 
> There is some out of date guidelines:
> 
> http://www.boost.org/doc/libs/1_35_0/more/writingdoc/introduction.html
> 
> I've been meaning to bring it up to date for a while. I'll try to do so soonish.

That'd be great, thanks.

> Also, in the last few days I've started trying to pull together simple
> installation instructions for various platforms at:
> 
> http://svn.boost.org/trac/boost/wiki/BoostDocs/GettingStarted
> 
> It's very rough, as I've really just been recording my attempts at
> getting various platforms to work.

Looks like a good start. For native win32 latex and dvips, I've use 
MiKTeX in the past.

> I might bring all of this together with the quickbook and boostbook
> documentation in their own section of the combined documentation.
> Although the documentation guidelines might be better suited to the
> website.

This is much needed, thanks for stepping up. I've been back and forth 
with Doug Gregor over the past few days about the BoostBook reference 
docs (http://www.boost.org/doc/libs/1_35_0/doc/html/reference.html). 
Firstly, they are incomplete (See ticket 
http://svn.boost.org/trac/boost/ticket/2153).

Secondly, the file tools/boostbook/doc/reference.xml was originally 
generated from tools/boostbook/doc/reference.dtdxml, which was itself 
originally generated from tools/boostbook/dtd/boostbook.dtd via a tool 
called dtdparse. However, reference.dtdxml has since been hand-edited 
and cannot be regenerated, even though the dtd has changed. Worse, 
reference.xml has also been edited, and so it cannot be regenerated from 
reference.dtdxml. This is a Big Mess. Best option is to give up on 
reference.dtdxml (and delete it), keep editing reference.xml by hand and 
work to keep it in sync with boostbook.dtd.

-- 
Eric Niebler
BoostPro Computing
http://www.boostpro.com