[postgis-devel] postgis_comments.sql

[Regina Obe]

Added users to cc list to get more input.

I have mixed feeling about this.  I see the value of not including it in extensions but would like to keep the make target.

 

1)      If you build from tar ball it’s already included built so you don’t need docbook to build extensions from tar ball.  But I guess if you build from git you do need dockbook. Given the craziness of our dependencies and the fact that most people don’t build their own PostGIS – the pain seems pretty minimal.

2)      Building the comments has on occasion prevented us from documenting things that aren’t so.  For example if you said in the docs the function signature is

 

Foo(geometry, integer)

 

And it was defined in the code as foo(geometry, integer[])

 

Then the build would error out because the code doesn’t agree with the docs  – which I think is a nice feature.

 

 

But that is the only really nice to have I can think of.  I suppose we could achieve the same by keeping the make target, but just don’t include it in extensions

and have it as part of the ci steps to install the comments to confirm they install.

 

 

From: postgis-devel [mailto:postgis-devel-bounces at lists.osgeo.org] On Behalf Of Bruce Rindahl
Sent: Monday, March 2, 2020 5:43 PM
To: PostGIS Development Discussion <postgis-devel at lists.osgeo.org>
Subject: Re: [postgis-devel] postgis_comments.sql

 

This:



then this:

 



??

vs this:

https://postgis.net/docs/DropGeometryColumn.html 

 

I say it is a no brainer.  Especially since the function above is really not needed in PostGIS v3.0 

 

 

 

On Mon, Mar 2, 2020 at 2:34 PM Paul Ramsey <pramsey at cleverelephant.ca <mailto:pramsey at cleverelephant.ca> > wrote:

I have long had an animus for the comments.sql file, because it results in a couple bad couplings:

extension depends on comments depends on docbook, so you cannot build extension without having docbook/xslt tools installed
extension depends on commetns depends on docbook, so you cannot change documentation format

All this maybe would be worth choking down if the SQL comments provided any great value, but it’s not at all clear to me that they do. People lookup functions on postgis.net <http://postgis.net> , on the google, but not in their SQL terminal monitors or object browsers.

If we can find it without ourselves to not have SQL comments anymore, we can back out some of these weird dependencies.

Taking the temperature, who would set themselves on fire to save SQL comments?

P
_______________________________________________
postgis-devel mailing list
postgis-devel at lists.osgeo.org <mailto:postgis-devel at lists.osgeo.org> 
https://lists.osgeo.org/mailman/listinfo/postgis-devel

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.osgeo.org/pipermail/postgis-devel/attachments/20200302/718f2e4d/attachment-0001.html>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: image001.png
Type: image/png
Size: 9448 bytes
Desc: not available
URL: <http://lists.osgeo.org/pipermail/postgis-devel/attachments/20200302/718f2e4d/attachment-0002.png>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: image003.png
Type: image/png
Size: 29611 bytes
Desc: not available
URL: <http://lists.osgeo.org/pipermail/postgis-devel/attachments/20200302/718f2e4d/attachment-0003.png>