[postgis-devel] SQL comment generation

[Mark Cave-Ayland]

Obe, Regina wrote:
> Mark,
>> 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? 
> 
> Yap , that was along the lines of what I was thinking.

Okay. It should be reasonably straightforward to add a suitable target 
to the Makefile, add a #include to lwpostgis.sql.in.c and commit the 
generated .sql file into SVN - want to have a go? If you're unsure about 
committing (i.e. it breaks things like regression tests) then send a 
local patch to the list and we can work through it together.

One thing I did forget to mention in my previous email regarding your 
.xsl file was lack of comments - it doesn't have to be too comprehensive 
but a few comments along the lines of "we match the documentation on 
these tags and then do ...." would be useful. Oh, and don't forget the 
copyright notice either.

> The only side case situation I can think of is with aggregates - recall
> in old installs that have been faithfully upgrading we had that issue
> with new aggregates not being created unless you do a full dump reload.
> I think that still is an issue.  The comment sql part would
> fail since it will never find the ST_ function aggregate parent.  This
> could be a good thing or bad thing however you look at it.
> 
> Good in that if you combine into the lwpostgis.sql people with faulty
> installations would certainly know it since their install will fail.
> Bad in that hmm their install will fail.

I think the argument here is that only maintainers should generate the 
comments file and commit it to SVN, much in the same way that we 
pre-generate the flex and bison output and commit to SVN for people that 
can't generate it themselves.


ATB,

Mark.

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