Re: [boost] [geometry] Documentation prototype for review

Subject: Re: [boost] [geometry] Documentation prototype for review
From: Paul A. Bristow (pbristow_at_[hidden])
Date: 2010-02-17 11:47:54

> -----Original Message-----
> From: boost-bounces_at_[hidden] [mailto:boost-bounces_at_[hidden]] On
Behalf Of
> Mateusz Loskot
> Sent: Sunday, February 14, 2010 12:38 AM
> To: boost_at_[hidden]
> Subject: [boost] [geometry] Documentation prototype for review

> I'm working on documentation of Boost Geometry based on Quickbook
> and I've prepared a prototype:
> 
> http://mateusz.loskot.net/tmp/ggl/qbk/
> 
> What I'm doing is manually porting the content from Doxygen-based
> (http://geometrylibrary.geodan.nl/) plus restructuring, reformatting
> and completing it with missing details.
> 
> I'd like to ask everyone who is interested in Boost Geometry library
> for comments, impressions and suggestions of improvements.

> The Reference is one of the most important section I'd like to master,
> so please share your comments on the form and completeness of the
> concepts specification, for example:

This is looking nice - but so was the Doxygen based version.

I believe (and found 'eating my own dogfood' -especially the SG plot project)

that the Doxygen produced Reference section is complementary to the more textual
sections that you are writing.

Several libraries use both, see Boost.Units, Accumulator, (and of course the
NotAlibrary SVGPlot Soc 2007/vizisualization)

and I think this is much the best way to go, especially as you have already done
the tedious task of
adding Doxygen style comments to the code, so that you (and readers) would lose
much if you don't provide it.

A drawback is that docs generation time goes up sharply, so you may prefer to
leave it to the end.

I found it was wise also to generate Doxygen only version first to check you
don't have any warnings - its quicker that way.

And users will also find it useful to just have the full doxygen version too -
it is also complementary.

Finally I would say that I found the Quickbook embedded code system very, very
useful.

This ensures that the examples cannot get out of sync with the code.

and I found numbering sections algorithms_append_hpp_1, algorithms_append_hpp_2
... and also using algorithms_append_hpp_output to show some or all of the
output.

I put the output in a C comment like this

/*
//[auto_1d_plot_output
auto_1d_plot.cpp
Linking...
Embedding manifest...
Autorun "j:\Cpp\SVG\debug\auto_1d_plot.exe"
limit value: 1.#INF
6 good values, 1 limit values.
limit value: 1.#INF
x_range() 0, 7
//] [auto_1d_plot_output]

*/

which can be referenced by the QuickBook text.

You will find that trying to produce the pdf is also useful to iron out any
residual bugs - as well as producing a text searchable version that will help
users.

Good luck!

Paul

---
Paul A. Bristow
Prizet Farmhouse
Kendal, UK   LA8 8AB
[phone], mobile [phone]
pbristow_at_[hidden]