<HTML dir=ltr><HEAD><TITLE>Re: [Fwd: Re: [postgis-devel] Issue 35 in postgis: Comments on Postgis Functions]</TITLE>
<META http-equiv=Content-Type content="text/html; charset=unicode">
<META content="MSHTML 6.00.6000.16674" name=GENERATOR></HEAD>
<BODY>
<DIV id=idOWAReplyText41548 dir=ltr>
<DIV dir=ltr><FONT face=Arial color=#000000 size=2>Well I was back-porting per Paul's request so relevant changes would appear in the upcoming 1.3.4, but now that we are making so many changes, I guess its best to just cut the chord.</FONT></DIV>
<DIV dir=ltr><FONT face=Arial size=2></FONT> </DIV>
<DIV dir=ltr><FONT face=Arial size=2>I don't think the documentation as it stands has any new functions listed that will not be available in the 1.3.4 though. So on the one hand it does seem a shame to cut off a not yet released version in our efforts.</FONT></DIV>
<DIV dir=ltr><FONT face=Arial size=2></FONT> </DIV>
<DIV dir=ltr><FONT face=Arial size=2>Thanks,</FONT></DIV>
<DIV dir=ltr><FONT face=Arial size=2>Regina</FONT></DIV></DIV>
<DIV dir=ltr><BR>
<HR tabIndex=-1>
<FONT face=Tahoma size=2><B>From:</B> Kevin Neufeld [mailto:kneufeld@refractions.net]<BR><B>Sent:</B> Tue 7/8/2008 1:29 AM<BR><B>To:</B> Obe, Regina<BR><B>Cc:</B> Dane Springmeyer<BR><B>Subject:</B> Re: [Fwd: Re: [postgis-devel] Issue 35 in postgis: Comments on Postgis Functions]<BR></FONT><BR></DIV>
<DIV>
<P><FONT size=2>That's a good question. Are patches usually back-ported to earlier<BR>versions? Version 1.4 will likely have new methods in addition to new<BR>docs. Are we going to have to back-port all the new functionality as<BR>well? I'm tempted to leave 1.3 as a static version, but I think it's a<BR>question you should push to devel. Maybe Mark or Paul will have other<BR>thoughts.<BR><BR>Cheers,<BR>Kevin<BR><BR>Obe, Regina wrote:<BR>> Sure that works for me. Only question I have I hadn't moved the<BR>> changes I made in trunk to branch 1.3 even though they are relevant<BR>> for branch 1.3. Do we not care and are splitting off from branch 1.3<BR>> at this point.<BR>> <BR>> Thanks,<BR>> Regina<BR>><BR>> ------------------------------------------------------------------------<BR>> *From:* Kevin Neufeld [<A href="mailto:kneufeld@refractions.net">mailto:kneufeld@refractions.net</A>]<BR>> *Sent:* Mon 7/7/2008 10:59 PM<BR>> *To:* Obe, Regina; Dane Springmeyer<BR>> *Subject:* [Fwd: Re: [postgis-devel] Issue 35 in postgis: Comments on<BR>> Postgis Functions]<BR>><BR>> The next step I would like to do is split the postgis.xml doc into<BR>> separate files so it's more manageable - one for every chapter. If it's<BR>> ok with you two, I'll make the change tonite.. making sure to checkout<BR>> the latest commit so we don't lose any of Regina's useful commits in the<BR>> process. :)<BR>><BR>> Cheers,<BR>> Kevin<BR>><BR>> -------- Original Message --------<BR>> Subject: Re: [postgis-devel] Issue 35 in postgis: Comments on<BR>> Postgis<BR>> Functions<BR>> Date: Mon, 07 Jul 2008 19:56:36 -0700<BR>> From: Kevin Neufeld <kneufeld@refractions.net><BR>> To: PostGIS Development Discussion<BR>> <postgis-devel@postgis.refractions.net><BR>> References:<BR>> <0016e64355defbe5a00451258f66@google.com><53F9CF533E1AA14EA1F8C5C08ABC08D20197A0FD@ZDND.DND.boston.cob><BR>> <60A74853-AB5F-4B92-A46C-31C822ACDA07@hailmail.net><BR>> <53F9CF533E1AA14EA1F8C5C08ABC08D20453F736@ZDND.DND.boston.cob><BR>><BR>><BR>><BR>> Regina, Dane,<BR>><BR>> Yes, I agree that we should keep the issue around a bit so it stays on<BR>> our TODO list.<BR>><BR>> In my spare time, I've been working on coming up with a template we<BR>> could use for all the functions in the documentation. I still think<BR>> that having every function as a refentry is the way to go instead of the<BR>> current listitem we currently employ. I'm close ... just wrestling with<BR>> DocBook, trying to make it jump though hoops as I try to customize the<BR>> automatic generation of the TOC.<BR>><BR>> Unlike the multiple term issue you were having, the refentry tag also<BR>> permits having multiple function prototypes under the same refentry. So<BR>> the same refpurpose tag could be applied as function comments for all<BR>> overridden prototypes. The concept seems to work pretty well... it just<BR>> the silly TOC that has me tied up in knots.<BR>><BR>> Cheers,<BR>> Kevin<BR>><BR>> Obe, Regina wrote:<BR>> > Dane,<BR>> ><BR>> > Thanks. That would help. I've started to fix these as I go along<BR>> > adding examples.<BR>> ><BR>> > I don't know if we should get rid of issue 35 though. I think the<BR>> > intent is still the same its just the actual implementation may be<BR>> > different and I was looking at your python and your comments as<BR>> > guidelines of what is wrong with the documentation.<BR>> ><BR>> > Is there an issue with having more than one <term> in the<BR>> > varlistentry. The html xsl parse just seems to put in a , when<BR>> > forming the html so I assume its okay to do that.<BR>> ><BR>> > E.g. I changed Add Point entry to:<BR>> ><BR>> > <varlistentry><BR>> > <term>ST_AddPoint(linestring geometry, point geometry)</term><BR>> > <term>ST_AddPoint(linestring geometry, point geometry, position<BR>> > integer)</term><BR>> ><BR>> > <listitem><BR>> > <para>Adds a point to a LineString before point<BR>> > <position><BR>> > (0-based index). Third parameter can be omitted or set<BR>> > to -1 for<BR>> > appending.</para><BR>> > <programlisting><BR>> > --guarantee all linestrings in a table are closed<BR>> > --by adding the start point of each linestring to the end of the line<BR>> > string<BR>> > --only for those that are not closed<BR>> > UPDATE sometable<BR>> > SET the_geom = ST_AddPoint(the_geom, ST_StartPoint(the_geom))<BR>> > FROM sometable<BR>> > WHERE ST_IsClosed(the_geom) = false;<BR>> > </programlisting><BR>> > </listitem><BR>> > </varlistentry><BR>> ><BR>> > I was next going to attempt to write a postgis_comments.xsl (finally I<BR>> > have a use for this xslt pocket book I have lying around :)) . I<BR>> > haven't done that yet though and not sure I'm the best person<BR>> > to attempt that.<BR>> ><BR>> > Thanks,<BR>> > Regina<BR>> ><BR>> > ------------------------------------------------------------------------<BR>> > *From:* postgis-devel-bounces@postgis.refractions.net<BR>> > [<A href="mailto:postgis-devel-bounces@postgis.refractions.net">mailto:postgis-devel-bounces@postgis.refractions.net</A>] *On Behalf Of<BR>> > *Dane Springmeyer<BR>> > *Sent:* Monday, July 07, 2008 1:59 PM<BR>> > *To:* PostGIS Development Discussion<BR>> > *Subject:* Re: [postgis-devel] Issue 35 in postgis: Comments on<BR>> > Postgis Functions<BR>> ><BR>> > Regina and Paul,<BR>> ><BR>> > I agree that a python script dependency for this step isn't ideal, and<BR>> > I'm in no way committed to the idea. It was simply an easy way for me<BR>> > to start working on the task, and I was not anticipating its<BR>> > consideration as a dependency.<BR>> ><BR>> > I propose we close this issue 35 as invalid and cook up another one<BR>> > based on Regina's sweet plan. How does that sound?<BR>> ><BR>> > More comments below...<BR>> ><BR>> ><BR>> > On Jul 6, 2008, at 1:57 AM, Obe, Regina wrote:<BR>> ><BR>> >> Paul,<BR>> >> You must have been reading my mind when you selectively picked this<BR>> >> one and the proj one to not comment about.<BR>> >><BR>> >> Regarding this I have been looking at Dane's submission and as Paul<BR>> >> mentioned, off list, its not good to add any more dependencies than<BR>> >> we need to. This would require adding Python and Python's pgsql<BR>> >> library to use his source.<BR>> ><BR>> > Yes, it requires Python and the Psycopg2 driver as well as an existing<BR>> > db to match function names against (due to variable argument syntax).<BR>> ><BR>> >><BR>> >> My main gripe with it is that it requires a postgis_template db to be<BR>> >> loaded to build the comments. It seems the main reason for that is<BR>> >> to look up the arg signature in the procname which would seem to be<BR>> >> unnecessary if our argument list in the documents could be mapped to<BR>> >> the postgresql function signature.<BR>> ><BR>> > Exactly. It could easily be modified to match against an xml file (or<BR>> > internal python data type) that stores the exact function names and<BR>> > arguments, but having the docs more closely match the actual function<BR>> > definitions would be ideal.<BR>> ><BR>> >><BR>> >> In many cases they do or almost do. But we have cases like<BR>> >><BR>> >> ST_MakePolygon(linestring, [linestring[]])<BR>> >><BR>> >> which if we changed to<BR>> >><BR>> >> ST_MakePolygon(linestring geometry, linestrings geometry[])<BR>> >> ST_MakePolygon(linestring)<BR>> >><BR>> >> would work.<BR>> >><BR>> >> the only issue I can think of are these functions with multi-signatures<BR>> >> ST_AddPoint(linestring, point, [<position>])<BR>> >><BR>> >> I personally would prefer see it listed twice as<BR>> >> ST_AddPoint(linestring geometry, point geometry)<BR>> >><BR>> >> ST_AddPoint(linestring geometry, point geometry, position integer)<BR>> >><BR>> >> since I'm not convinced non-programmers don't find that nomenclature<BR>> >> confusing.<BR>> >><BR>> >> then I'm thinking we can generate the postgis_comments.sql.in from a<BR>> >> simple<BR>> >><BR>> >> postgis_comments.xsl file that parses the postgis.xml thus not<BR>> >> needing another dependency.<BR>> >><BR>> >> Although I could very well be trivializing the simplicity of this.<BR>> >><BR>> >> Does anyone have issues with me changing the doc accordingly.<BR>> >><BR>> ><BR>> > This sounds excellent. I'd be happy to help with this renaming if it<BR>> > is needed.<BR>> ><BR>> ><BR>> > Cheers,<BR>> ><BR>> > Dane<BR>> ><BR>> ><BR>> ><BR>> ><BR>> >> Thanks,<BR>> >> Regina<BR>> >><BR>> >><BR>> >><BR>> >><BR>> ------------------------------------------------------------------------<BR>> >> *From:* postgis-devel-bounces@postgis.refractions.net<BR>> >> <<A href="mailto:postgis-devel-bounces@postgis.refractions.net">mailto:postgis-devel-bounces@postgis.refractions.net</A>> on behalf of<BR>> >> codesite-noreply@google.com <<A href="mailto:codesite-noreply@google.com">mailto:codesite-noreply@google.com</A>><BR>> >> *Sent:* Thu 7/3/2008 5:47 PM<BR>> >> *To:* postgis-devel@postgis.refractions.net<BR>> >> <<A href="mailto:postgis-devel@postgis.refractions.net">mailto:postgis-devel@postgis.refractions.net</A>><BR>> >> *Subject:* [postgis-devel] Issue 35 in postgis: Comments on Postgis<BR>> >> Functions<BR>> >><BR>> >> Issue 35: Comments on Postgis Functions<BR>> >> <A href="http://code.google.com/p/postgis/issues/detail?id=35">http://code.google.com/p/postgis/issues/detail?id=35</A><BR>> >><BR>> >> Comment #2 by pwramsey3:<BR>> >> (No comment was entered for this change.)<BR>> >><BR>> >><BR>> >> Issue attribute updates:<BR>> >> Labels: -Type-Defect Type-Enhancement<BR>> >><BR>> >> --<BR>> >> You received this message because you are listed in the owner<BR>> >> or CC fields of this issue, or because you starred this issue.<BR>> >> You may adjust your issue notification preferences at:<BR>> >> <A href="http://code.google.com/hosting/settings">http://code.google.com/hosting/settings</A><BR>> >> _______________________________________________<BR>> >> postgis-devel mailing list<BR>> >> postgis-devel@postgis.refractions.net<BR>> >> <<A href="mailto:postgis-devel@postgis.refractions.net">mailto:postgis-devel@postgis.refractions.net</A>><BR>> >> <A href="http://postgis.refractions.net/mailman/listinfo/postgis-devel">http://postgis.refractions.net/mailman/listinfo/postgis-devel</A><BR>> >><BR>> >><BR>> >><BR>> ------------------------------------------------------------------------<BR>> >><BR>> >> *The substance of this message, including any attachments, may be<BR>> >> confidential, legally privileged and/or exempt from disclosure<BR>> >> pursuant to Massachusetts law. It is intended solely for the<BR>> >> addressee. If you received this in error, please contact the sender<BR>> >> and delete the material from any computer. *<BR>> >><BR>> >><BR>> >><BR>> ------------------------------------------------------------------------<BR>> >><BR>> >> *Help make the earth a greener place. If at all possible resist<BR>> >> printing this email and join us in saving paper. *<BR>> >><BR>> >> **<BR>> >><BR>> >> **<BR>> >><BR>> >> _______________________________________________<BR>> >> postgis-devel mailing list<BR>> >> postgis-devel@postgis.refractions.net<BR>> >> <<A href="mailto:postgis-devel@postgis.refractions.net">mailto:postgis-devel@postgis.refractions.net</A>><BR>> >> <A href="http://postgis.refractions.net/mailman/listinfo/postgis-devel">http://postgis.refractions.net/mailman/listinfo/postgis-devel</A><BR>> ><BR>> > ------------------------------------------------------------------------<BR>> ><BR>> > *The substance of this message, including any attachments, may be<BR>> > confidential, legally privileged and/or exempt from disclosure<BR>> > pursuant to Massachusetts law. It is intended solely for the<BR>> > addressee. If you received this in error, please contact the sender<BR>> > and delete the material from any computer. *<BR>> ><BR>> > ------------------------------------------------------------------------<BR>> ><BR>> > * Help make the earth a greener place. If at all possible resist<BR>> > printing this email and join us in saving paper. *<BR>> ><BR>> > * *<BR>> ><BR>> > * *<BR>> ><BR>> > ------------------------------------------------------------------------<BR>> ><BR>> > _______________________________________________<BR>> > postgis-devel mailing list<BR>> > postgis-devel@postgis.refractions.net<BR>> > <A href="http://postgis.refractions.net/mailman/listinfo/postgis-devel">http://postgis.refractions.net/mailman/listinfo/postgis-devel</A><BR>> > <BR>><BR>><BR></FONT></P></DIV></BODY></HTML>