[postgis-devel] Update Documentation

[Obe, Regina]

Kevin

Very cool.  I especially like the addition of pictures.  One thing I am
thinking to minimize on work. Do we have any XSLT wizards that can take
the first paragraph of each function and 
wrap it in an abstract clause similar to what Dane did already.  His
patch seems pretty decent although it generated some invalid inserts
presumably because of inconsistencies in the documentation.  

Kevin are you thinking the abstract would be the <refpurpose> and
<refsection> would be the full description.

The other nit-pick I have is that the current documentation within each
section is not in alphabetical order.  Is there a reason for that?

The other thought is that having all this in a single .xml file is too
much and we'll want to split each out in a separate xml and stitch back
together (maybe that was Kevin's intent anyway - just thought I would
mention it in passing).  I haven't explored docBook enough to know how
much of an effort this is.

*REALITY CHECK kicking in oh oh - I hate when this happens:
I would be willing to put in some effort into this since I feel its very
important.  

Jumping from where we are now to where we want to be (Kevin's vision) -
seems like a lot of work.

So I propose taking baby steps. 

1) Lets first get current doc in some format that has abstracts
separated out into a separate tag so our parsing into db comments fields
is more or less perfect.  Then when we have that much done - reconvene.


2) Next step after that I think - is blow up the document - again seems
like it is currently structured enough that with an XSLT transform we
can break chapter 6 out into separate little documents - one for each
function.  I presume each file would need another tag to denote what
section of the main document it slides into.  I didn't see that in
Kevin's xml example.


Thanks,
Regina


-----Original Message-----
From: postgis-devel-bounces at postgis.refractions.net
[mailto:postgis-devel-bounces at postgis.refractions.net] On Behalf Of
Kevin Neufeld
Sent: Monday, June 23, 2008 2:00 AM
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
-----------------------------------------
The substance of this message, including any attachments, may be
confidential, legally privileged and/or exempt from disclosure
pursuant to Massachusetts law. It is intended
solely for the addressee. If you received this in error, please
contact the sender and delete the material from any computer.