[postgis-devel] Update Documentation
Kevin Neufeld
kneufeld at refractions.net
Sun Jun 22 23:00:21 PDT 2008
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
More information about the postgis-devel
mailing list