<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=idOWAReplyText726 dir=ltr>
<DIV dir=ltr><FONT face=Arial color=#000000 size=2>I think we had trac or something like it way back when. I forget what happened to it. I think the google bug tracker thing was meant to be a stop gap measure, but ended up being more than that as often stop gap measure have a way of doing.</FONT></DIV>
<DIV dir=ltr><FONT face=Arial size=2></FONT> </DIV>
<DIV dir=ltr><FONT face=Arial size=2>Personally I don't really care either way. I'm pretty minimalist when it comes to things like that and have a simple task list to keep track of what I need to do and trac (from my vague memory of it) is a bit too tracky for my liking.</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> Dane Springmeyer [mailto:blake@hailmail.net]<BR><B>Sent:</B> Tue 7/8/2008 2:12 AM<BR><B>To:</B> Kevin Neufeld<BR><B>Cc:</B> Obe, Regina<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>Kevin,<BR><BR>Sounds good. I have no outstanding changes. I'm looking forward to <BR>digging into the split docbook and tracking the new changes...<BR><BR>Do either of you know what the story is on the lack of the use of trac <BR>for postgis? As I get more interested in the work on documentation I <BR>find myself wishing I could track the work though a trac system....<BR><BR>Dane<BR><BR><BR>On Jul 7, 2008, at 7:59 PM, Kevin Neufeld wrote:<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 <BR>> it's ok with you two, I'll make the change tonite.. making sure to <BR>> checkout the latest commit so we don't lose any of Regina's useful <BR>> commits in the process. :)<BR>><BR>> Cheers,<BR>> Kevin<BR>><BR>> -------- Original Message --------<BR>> Subject: Re: [postgis-devel] Issue 35 in postgis: Comments on <BR>> Postgis Functions<BR>> Date: Mon, 07 Jul 2008 19:56:36 -0700<BR>> From: Kevin Neufeld <kneufeld@refractions.net><BR>> To: PostGIS Development Discussion <postgis-devel@postgis.refractions.net<BR>> ><BR>> References: <0016e64355defbe5a00451258f66@google.com><53F9CF533E1AA14EA1F8C5C08ABC08D20197A0FD@ZDND.DND.boston.cob<BR>> > <60A74853-AB5F-4B92-A46C-31C822ACDA07@hailmail.net> <53F9CF533E1AA14EA1F8C5C08ABC08D20453F736@ZDND.DND.boston.cob<BR>> ><BR>><BR>><BR>><BR>> Regina, Dane,<BR>><BR>> Yes, I agree that we should keep the issue around a bit so it stays <BR>> on our TODO list.<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 <BR>> the current listitem we currently employ. I'm close ... just <BR>> wrestling with DocBook, trying to make it jump though hoops as I try <BR>> to customize the automatic generation of the TOC.<BR>> Unlike the multiple term issue you were having, the refentry tag <BR>> also permits having multiple function prototypes under the same <BR>> refentry. So the same refpurpose tag could be applied as function <BR>> comments for all overridden prototypes. The concept seems to work <BR>> pretty well... it just the silly TOC that has me tied up in knots.<BR>> Cheers,<BR>> Kevin<BR>><BR>> Obe, Regina wrote:<BR>>> Dane,<BR>>> Thanks. That would help. I've started to fix these as I go along <BR>>> adding examples. I don't know if we should get rid of issue 35 <BR>>> though. I think the intent is still the same its just the actual <BR>>> implementation may be different and I was looking at your python <BR>>> and your comments as guidelines of what is wrong with the <BR>>> documentation.<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>>> E.g. I changed Add Point entry to:<BR>>> <varlistentry><BR>>> <term>ST_AddPoint(linestring geometry, point geometry)</term><BR>>> <term>ST_AddPoint(linestring geometry, point geometry, position <BR>>> integer)</term><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 <BR>>> line 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>>> I was next going to attempt to write a postgis_comments.xsl <BR>>> (finally I have a use for this xslt pocket book I have lying <BR>>> around :)) . I haven't done that yet though and not sure I'm the <BR>>> best person to attempt that.<BR>>> Thanks,<BR>>> Regina<BR>>><BR>>> ------------------------------------------------------------------------<BR>>> *From:* postgis-devel-bounces@postgis.refractions.net [<A href="mailto:postgis-devel-bounces@postgis.refractions.net">mailto:postgis-devel-bounces@postgis.refractions.net</A><BR>>> ] *On Behalf Of *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, <BR>>> and I'm in no way committed to the idea. It was simply an easy way <BR>>> for me 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 <BR>>>> this one and the proj one to not comment about.<BR>>>> Regarding this I have been looking at Dane's submission and as <BR>>>> Paul mentioned, off list, its not good to add any more <BR>>>> dependencies than we need to. This would require adding Python <BR>>>> and Python's pgsql library to use his source.<BR>>><BR>>> Yes, it requires Python and the Psycopg2 driver as well as an <BR>>> existing db to match function names against (due to variable <BR>>> argument syntax).<BR>>><BR>>>> My main gripe with it is that it requires a postgis_template db to <BR>>>> be loaded to build the comments. It seems the main reason for <BR>>>> that is to look up the arg signature in the procname which would <BR>>>> seem to be unnecessary if our argument list in the documents could <BR>>>> be mapped to the postgresql function signature.<BR>>><BR>>> Exactly. It could easily be modified to match against an xml file <BR>>> (or internal python data type) that stores the exact function names <BR>>> and arguments, but having the docs more closely match the actual <BR>>> function definitions would be ideal.<BR>>><BR>>>> In many cases they do or almost do. But we have cases like<BR>>>> ST_MakePolygon(linestring, [linestring[]])<BR>>>> which if we changed to<BR>>>> ST_MakePolygon(linestring geometry, linestrings geometry[])<BR>>>> ST_MakePolygon(linestring)<BR>>>> would work.<BR>>>> the only issue I can think of are these functions with multi-<BR>>>> signatures<BR>>>> ST_AddPoint(linestring, point, [<position>])<BR>>>> I personally would prefer see it listed twice as<BR>>>> ST_AddPoint(linestring geometry, point geometry)<BR>>>> ST_AddPoint(linestring geometry, point geometry, position integer)<BR>>>> since I'm not convinced non-programmers don't find that <BR>>>> nomenclature confusing.<BR>>>> then I'm thinking we can generate the postgis_comments.sql.in from <BR>>>> a simple<BR>>>> postgis_comments.xsl file that parses the postgis.xml thus not <BR>>>> needing another dependency.<BR>>>> Although I could very well be trivializing the simplicity of this.<BR>>>> Does anyone have issues with me changing the doc accordingly.<BR>>><BR>>> This sounds excellent. I'd be happy to help with this renaming if <BR>>> it is needed.<BR>>><BR>>><BR>>> Cheers,<BR>>><BR>>> Dane<BR>>><BR>>><BR>>><BR>>><BR>>>> Thanks,<BR>>>> Regina<BR>>>><BR>>>> ------------------------------------------------------------------------<BR>>>> *From:* postgis-devel-bounces@postgis.refractions.net <mailto:postgis-devel-bounces@postgis.refractions.net <BR>>>> > on behalf of codesite-noreply@google.com <mailto:codesite-noreply@google.com <BR>>>> ><BR>>>> *Sent:* Thu 7/3/2008 5:47 PM<BR>>>> *To:* postgis-devel@postgis.refractions.net <mailto:postgis-devel@postgis.refractions.net <BR>>>> ><BR>>>> *Subject:* [postgis-devel] Issue 35 in postgis: Comments on <BR>>>> Postgis 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 <mailto:postgis-devel@postgis.refractions.net <BR>>>> ><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>>>> *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 <BR>>>> sender and delete the material from any computer. *<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 <mailto:postgis-devel@postgis.refractions.net <BR>>>> ><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><BR></FONT></P></DIV></BODY></HTML>