[postgis-devel] Update Documentation

[James DeMichele]

GREAT idea. The more documentation and total rework of Chapter 6 that we
can do would be extremely useful.

-James

-----Original Message-----
From: postgis-devel-bounces at postgis.refractions.net
[mailto:postgis-devel-bounces at postgis.refractions.net] On Behalf Of
Kevin Neufeld
Sent: Sunday, June 22, 2008 11:00 PM
To: PostGIS Development Discussion
Subject: [postgis-devel] Update Documentation

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
_______________________________________________
postgis-devel mailing list
postgis-devel at postgis.refractions.net
http://postgis.refractions.net/mailman/listinfo/postgis-devel