[postgis-devel] SQL comment generation

[Mark Cave-Ayland]

Obe, Regina wrote:
> Mark,
> 
> I created a new xsl folder and committed the postgis_comments.sql.xsl I
> created to that.
> 
> I also made some enhancements to it to include the arg names in the
> comments.  Sample generated sql file is attached and seems to work just
> fine with xsltproc.
> 
> To test I ran the command
> 
> xsltproc -o postgis_comments.sql xsl/postgis_comments.sql.xsl
> reference_new.xml
> 
> Though I guess that is not exactly the best place to put it.
> 
> In the process I discovered there is really no
> ST_BdPolyFromText(text),  ST_BdMPolyFromText(text)
> 
> or
> 
> ST_WktToSQL(text,srid)
> even in the 1.4
> 
> These seem counter-intuitive to me since we have such constructs for
> ST_GeomFromText, ST_GeometryFromText.
> 
> Anyrate if this all looks okay to you, can you integrate in the build
> and figure out where the postgis_comments.sql should go.
> 
> As I mentioned I was eventually planning to create similar xsl files
> that will comb out aggregate, mm and 3d compatible functions and
> generate an additional toc doc .xml file from those that will then be
> processed by our docbook generation step and simply provide an index
> listing of said functions.
> 
> Can I chain these together like that? - xsl to generate docbox xml, then
> docbook to build document?
> 
> Thanks,
> Regina

Regina, apologies for the delay on this one - I've been busy trying to 
unbreak the memory management in SVN trunk :)

I agree with the other people on this thread that I'm not so keen having 
xsltproc as part of the main build as it is quite tricky to set up 
(along with the stylesheets) for someone who just wants to "build and 
go". And even then once we generate the output, how on earth would we go 
about integrating it back into lwpostgis.sql? I think that putting it in 
a separate file would be a waste of a good feature since it wouldn't get 
used if it wasn't part of the main file.

I'm thinking at the moment that maybe the best course of action would be 
to go through lwpostgis.sql manually adding the comments generated from 
your XSLT and then one the initial grunt work has been done then we just 
leave it to the developers' common sense to keep the entries updated. So 
in other words, if someone adds a function they simply re-run your XSLT 
and paste the output into the correct place in lwpostgis.sql.

Otherwise I can see the time required to integrate everything into the 
build system, the extra build dependency, and the work arounds needed 
for the corner cases would be quite time consuming. But then at least 
with the XSLT we can begin to make developers' lives easier who continue 
to work on new functionality.


ATB,

Mark.

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