[postgis-devel] Update Documentation

[Kevin Neufeld]

There has recently been some discussion on the uses list about 
self-documenting code.  That is, having comments extracted from 
postgis.xml into database comments on functions.

I personally, like this idea, but I think we first need to work on 
structuring our documentation to perhaps include an abstract sentence 
description, a full description and perhaps an example section for every 
method. In this way, the short abstract could be extracted into db 
comments, or even used in a function table of contents lookup using DocBook.

I spent a little time on this and here is what I've come up with for a 
starting point for a template. 

http://postgis.refractions.net/files/tmp/reference.html

This page was generated by a docbook xml file.
http://postgis.refractions.net/files/tmp/reference.xml

I think I may have a few cycles to spare coming up to work more on this 
(I'm not sure yet), but I wanted to first get a documentation template 
out there for your thoughts.

I propose that we totally rework Chapter 6 of the PostGIS docs to this 
type of DocBook reference pages.  With this type of rework, functional 
abstract sentences can be easily extracted.  You'll also notice that 
this style looks just like a unix man page.  I'm finding that DocBook is 
pretty powerful.

What are your thoughts/feedback/suggestions ... Good idea or bad?

-- Kevin