[postgis-devel] Issue 35 in postgis: Comments on Postgis Functions

Mon Jul 7 12:29:57 PDT 2008

Dane,

Thanks.  That would help.  I've started to fix these as I go along
adding examples.  

I don't know if we should get rid of issue 35 though.  I think the
intent is still the same its just the actual implementation may be
different and I was looking at your python and your comments as
guidelines of what is wrong with the documentation.

Is there an issue with having more than one <term> in the varlistentry.
The html xsl parse just seems to put in a , when forming the html so I
assume its okay to do that.

E.g. I changed Add Point entry to:

 <varlistentry>
     <term>ST_AddPoint(linestring geometry, point geometry)</term>
     <term>ST_AddPoint(linestring geometry, point geometry, position
integer)</term>

            <listitem>
              <para>Adds a point to a LineString before point
<position>
              (0-based index). Third parameter can be omitted or set to
-1 for
              appending.</para>
     <programlisting>
--guarantee all linestrings in a table are closed
--by adding the start point of each linestring to the end of the line
string 
--only for those that are not closed
UPDATE sometable
 SET the_geom = ST_AddPoint(the_geom, ST_StartPoint(the_geom))
 FROM sometable
 WHERE ST_IsClosed(the_geom) = false;
     </programlisting>
            </listitem>
          </varlistentry>

I was next going to attempt to write a postgis_comments.xsl (finally I
have a use for this xslt pocket book I have lying around :)) .  I
haven't done that yet though and not sure I'm the best person to attempt
that.

Thanks,
Regina

________________________________

From: postgis-devel-bounces at postgis.refractions.net
[mailto:postgis-devel-bounces at postgis.refractions.net] On Behalf Of Dane
Springmeyer
Sent: Monday, July 07, 2008 1:59 PM
To: PostGIS Development Discussion
Subject: Re: [postgis-devel] Issue 35 in postgis: Comments on Postgis
Functions

Regina and Paul, 

I agree that a python script dependency for this step isn't ideal, and
I'm in no way committed to the idea. It was simply an easy way for me to
start working on the task, and I was not anticipating its consideration
as a dependency.

I propose we close this issue 35 as invalid and cook up another one
based on Regina's sweet plan. How does that sound?

More comments below...

On Jul 6, 2008, at 1:57 AM, Obe, Regina wrote:

	Paul,
	You must have been reading my mind when you selectively picked
this one and the proj one to not comment about.

	Regarding this I have been looking at Dane's submission and as
Paul mentioned, off list, its not good to add any more dependencies than
we need to.  This would require adding Python and Python's pgsql library
to use his source.

Yes, it requires Python and the Psycopg2 driver as well as an existing
db to match function names against (due to variable argument syntax).

	My main gripe with it is that it requires a postgis_template db
to be loaded to build the comments.  It seems the main reason for that
is to look up the arg signature in the procname which would seem to be
unnecessary if our argument list in the documents could be mapped to the
postgresql function signature.

Exactly. It could easily be modified to match against an xml file (or
internal python data type) that stores the exact function names and
arguments, but having the docs more closely match the actual function
definitions would be ideal.

	In many cases they do or almost do.  But we have cases like

	ST_MakePolygon(linestring, [linestring[]])

	which if we changed to

	ST_MakePolygon(linestring geometry, linestrings geometry[])
	ST_MakePolygon(linestring)

	would work.

	the only issue I can think of are these functions with
multi-signatures
	ST_AddPoint(linestring, point, [<position>])

	I personally would prefer see it listed twice as
	ST_AddPoint(linestring geometry, point geometry)

	ST_AddPoint(linestring geometry, point geometry, position
integer)

	since I'm not convinced non-programmers don't find that
nomenclature confusing.

	then I'm thinking we can generate the postgis_comments.sql.in
from a simple

	postgis_comments.xsl  file that parses the postgis.xml thus not
needing another dependency.

	Although I could very well be trivializing the simplicity of
this.

	Does anyone have issues with me changing the doc accordingly.  

This sounds excellent. I'd be happy to help with this renaming if it is
needed.

Cheers,

Dane

	Thanks,
	Regina

________________________________

	From: postgis-devel-bounces at postgis.refractions.net on behalf of
codesite-noreply at google.com
	Sent: Thu 7/3/2008 5:47 PM
	To: postgis-devel at postgis.refractions.net
	Subject: [postgis-devel] Issue 35 in postgis: Comments on
Postgis Functions

	Issue 35: Comments on Postgis Functions
	http://code.google.com/p/postgis/issues/detail?id=35

	Comment #2 by pwramsey3:
	(No comment was entered for this change.)

	Issue attribute updates:
	        Labels: -Type-Defect Type-Enhancement

	--
	You received this message because you are listed in the owner
	or CC fields of this issue, or because you starred this issue.
	You may adjust your issue notification preferences at:
	http://code.google.com/hosting/settings
	_______________________________________________
	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. 

________________________________

	Help make the earth a greener place. If at all possible resist
printing this email and join us in saving paper. 

	_______________________________________________
	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.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.osgeo.org/pipermail/postgis-devel/attachments/20080707/a2a28b28/attachment.html>