[postgis-devel] SQL comment generation

[Mark Cave-Ayland]

Obe, Regina wrote:

> I was thinking it would be more along the lines of the 
> spatial_ref_sys.sql file.  People remember to run that if they care and 
> I think most people do.

Also one thing to bear in mind is that since PROJ.4 is now compulsory 
for 1.4, it would be good to include this as part of lwpostgis.sql aswell.

> Are you suggesting the comments follow right after the function they define.
> Sounds like too much grunt work. There isn't any reason why the comments 
> should follow the functions they go with and I would actually prefer it 
> not since the person defining the functions is not
> necessarily the same person updating the docs and it would also be too hard
> to hunt around as the docs change to remember in location of 
> lwpostgis.sql where to put the function comments.

Possibly - assuming that if the process is manual, it does seem to be 
easier to organise that way.

> I was thinking we just slap it at the end if we put it in the 
> lwpostgis.sql at all? So we would do it just right before release or 
> whenever we regenerate the comments file we just manually slap it in the 
> lwpostgis.sql at the end.

Hmmm. The problem I was wrestling with yesterday was that autoconf 
doesn't allow us to include extra information within a file, but then I 
remembered we have another stage. The lwpostgis.sql.in.c file runs 
through the C pre-processor and we *can* use #include from within that.

So this suggests that we add your xsltproc command to the documentation 
Makefile as a new target, maybe "make sqlcomments" or similar. Once this 
file has been generated, it would be up to the documentation maintainers 
to commit the new revisions into SVN so that they get pulled in by 
lwpostgis.sql.in.c. Sound reasonable?

I wonder if we should not do the #include in lwpostgis.sql.in.c for 
spatial_ref_sys.sql in trunk too.

> Also I was hoping to integrate Dane's other idea of having a helper 
> table and helper function that
> would use the more detailed combed out descriptions from the extended 
> descriptions section for each function, and properties such as supports 
> 3d, mm compliant, works with curved strings etc. -
> so a user can do a simple help query that asks  "give me anything to do 
> with blah that supports 3d."

Hmmm. I think the comments can be useful from a quick "what parameters 
do I need for that command?" perspective, but I just can't get too 
excited about this part. For detailed explanations, it's just as easy to 
fire up the PostGIS manual on the website or Google.

>  > corner cases would be quite time consuming.
> What corner case?

I had this recollection from this thread that you mentioned some 
function prototypes were causing you issues - optional parameters maybe?


ATB,

Mark.

-- 
Mark Cave-Ayland
Sirius Corporation - The Open Source Experts
http://www.siriusit.co.uk
T: +44 870 608 0063