<html><body style="word-wrap: break-word; -webkit-nbsp-mode: space; -webkit-line-break: after-white-space; "><div>Hi Regina,</div><div><br></div><div><div><div>On Jul 7, 2008, at 12:29 PM, Obe, Regina wrote:</div><br class="Apple-interchange-newline"><blockquote type="cite"> <div style="WORD-WRAP: break-word; -webkit-nbsp-mode: space; -webkit-line-break: after-white-space"> <div dir="ltr" align="left"><span class="874062219-07072008"><font face="Arial" color="#0000ff" size="2">Dane,</font></span></div> <div dir="ltr" align="left"><span class="874062219-07072008"><font face="Arial" color="#0000ff" size="2"></font></span> </div> <div dir="ltr" align="left"><span class="874062219-07072008"><font face="Arial" color="#0000ff" size="2">Thanks. That would help. I've started to fix these as I go along adding examples. </font></span></div> <div dir="ltr" align="left"><span class="874062219-07072008"><font face="Arial" color="#0000ff" size="2"></font></span> </div> <div dir="ltr" align="left"><span class="874062219-07072008"><font face="Arial" color="#0000ff" size="2">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.</font></span></div> <div dir="ltr" align="left"><span class="874062219-07072008"><font face="Arial" color="#0000ff" size="2"></font></span> </div></div></blockquote><div><br></div>Okay, sounds good.</div><div><br><blockquote type="cite"><div style="WORD-WRAP: break-word; -webkit-nbsp-mode: space; -webkit-line-break: after-white-space"> <div dir="ltr" align="left"><span class="874062219-07072008"><font face="Arial" color="#0000ff" size="2">Is there an issue with having more than one <term> in the varlistentry.</font></span></div></div></blockquote><div><br></div><div>No, not at all. I was commenting on multiple <term>'s used in situations where the same <listitem> documentation info logically applies to different functions.</div><div><br></div><div>For example, with the ST_Rotate* functions:</div><div><div><div> <term>ST_RotateZ(geometry, float8)</term></div><div> <term>ST_RotateX(geometry, float8)</term></div><div> <term>ST_RotateY(geometry, float8)</term></div><div><br></div><div>Parsing this required slightly different logic, so I was concerned that this might be an anomaly and the functions should be given their own full <varlistentry>. But, this seems reasonable and I'm sure any parsing logic could accommodate this.</div><div><br></div><div>The main place that might need attention in terms of multiple <term>'s are these entries: </div><div><br></div><div><div><term>ST_xmin(box3d) ymin(box3d) zmin(box3d)</term></div><div><br></div><div><term>ST_xmax(box3d) ymax(box3d) zmax(box3d)</term></div><div><br></div><div>I noticed in your updates to trunk you've added the ST_prefix. Should they also be treated like the ST_Rotate functions?</div></div><div><br></div><div>Ultimately, your use below seems perfectly appropriate, because the same documentation (and eventually function comments) will necessary need to be applied to those multiple function records in the database.</div><div><br></div><div><div><br></div></div></div></div><blockquote type="cite"><div style="WORD-WRAP: break-word; -webkit-nbsp-mode: space; -webkit-line-break: after-white-space"><div dir="ltr" align="left"><span class="874062219-07072008"><font face="Arial" color="#0000ff" size="2"> The html xsl parse just seems to put in a , when forming the html so I assume its okay to do that.</font></span></div> <div dir="ltr" align="left"><span class="874062219-07072008"><font face="Arial" color="#0000ff" size="2"></font></span> </div> <div dir="ltr" align="left"><span class="874062219-07072008"><font face="Arial" color="#0000ff" size="2">E.g. I changed Add Point entry to:</font></span></div> <div dir="ltr" align="left"><span class="874062219-07072008"><font face="Arial" color="#0000ff" size="2"></font></span> </div> <div dir="ltr" align="left"><span class="874062219-07072008"><font face="Arial" color="#0000ff" size="2"> <varlistentry><br> <term>ST_AddPoint(linestring geometry, point geometry)</term><br> <term>ST_AddPoint(linestring geometry, point geometry, position integer)</term></font></span></div> <div> </div></div></blockquote><div><br></div>This looks excellent. Having the geometry type listed beside the data type will be very helpful for beginners. When I comes to parsing the docbook to add comments do you imagine we'll just strip the added text (in this case 'linestring') based on its position? I noticed the entry for ST_BdPolyFromText was one of the only functions within the docbook (before you commenced work) that listed more explicit types, but it uses the opposite order:</div><div><br></div><div><term>ST_BdPolyFromText(text WKT, integer SRID)</term></div><div><br></div><div><br><blockquote type="cite"><div style="WORD-WRAP: break-word; -webkit-nbsp-mode: space; -webkit-line-break: after-white-space"> <div dir="ltr" align="left"><span class="874062219-07072008"><font face="Arial" color="#0000ff" size="2"> <listitem><br> <para>Adds a point to a LineString before point <position><br> (0-based index). Third parameter can be omitted or set 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 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></font></span></div></div></blockquote><div><br></div><div>Having examples like this is going to be extremely useful. I wonder if we could develop a simple set of 'official' sample data that they could be run upon? Obviously the documentation could instruct the user to create some simple sample data themselves and name the table 'sometable' so a quick copy and paste could give them example results. But I wonder whether actually using table names, field names, etc. in the documentation that referred to sample data would work the time investment? What do you think?</div><div><br></div><div><br></div><div>Cheers,</div><div><br></div><div>Dane</div><div><br></div><div><br></div><div><br></div><div><div><br></div><div><br></div><div><br></div><div><br></div></div><blockquote type="cite"><div style="WORD-WRAP: break-word; -webkit-nbsp-mode: space; -webkit-line-break: after-white-space"> <div class="OutlookMessageHeader" lang="en-us" dir="ltr" align="left"> <hr tabindex="-1"> <font face="Tahoma" size="2"><b>From:</b> postgis-devel-bounces@postgis.refractions.net [<a href="mailto:postgis-devel-bounces@postgis.refractions.net">mailto:postgis-devel-bounces@postgis.refractions.net</a>] <b>On Behalf Of </b>Dane Springmeyer<br><b>Sent:</b> Monday, July 07, 2008 1:59 PM<br><b>To:</b> PostGIS Development Discussion<br><b>Subject:</b> Re: [postgis-devel] Issue 35 in postgis: Comments on Postgis Functions<br></font><br></div> <div></div>Regina and Paul, <div><br></div> <div> <div> <div>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.</div> <div><br></div> <div>I propose we close this issue 35 as invalid and cook up another one based on Regina's sweet plan. How does that sound?</div> <div><br></div> <div>More comments below...</div> <div><br></div> <div><br></div> <div>On Jul 6, 2008, at 1:57 AM, Obe, Regina wrote:</div><br class="Apple-interchange-newline"> <blockquote type="cite"> <div> <div id="idOWAReplyText16337" dir="ltr"> <div dir="ltr"><font face="Arial" color="#000000" size="2">Paul,</font></div> <div dir="ltr"><font face="Arial" color="#000000" size="2">You must have been reading my mind when you selectively picked this one and the proj one to not comment about.</font></div> <div dir="ltr"><font face="Arial" size="2"></font> </div> <div dir="ltr"><font face="Arial" size="2">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.</font></div></div></div></blockquote> <div><br></div>Yes, it requires Python and the Psycopg2 driver as well as an existing db to match function names against (due to variable argument syntax).</div> <div><br> <blockquote type="cite"> <div> <div id="idOWAReplyText16337" dir="ltr"> <div dir="ltr"><font face="Arial" size="2"></font> </div> <div dir="ltr"><font face="Arial" size="2">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.</font></div></div></div></blockquote> <div><br></div> <div>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.</div> <br> <blockquote type="cite"> <div> <div id="idOWAReplyText16337" dir="ltr"> <div dir="ltr"><font face="Arial" size="2"></font> </div> <div dir="ltr"><font face="Arial" size="2">In many cases they do or almost do. But we have cases like</font></div> <div dir="ltr"><font face="Arial" size="2"></font> </div> <div dir="ltr"><span class="term">ST_MakePolygon(linestring, [linestring[]])</span></div> <div dir="ltr"><span class="term"></span> </div> <div dir="ltr"><span class="term">which if we changed to</span></div> <div dir="ltr"><span class="term"></span> </div> <div dir="ltr"><span class="term">ST_MakePolygon(linestring geometry, linestrings geometry[])</span></div> <div dir="ltr"><span class="term"><span class="term"><span class="term">ST_MakePolygon(linestring)</span></span></span></div> <div dir="ltr"><span class="term"></span> </div> <div dir="ltr"><span class="term">would work.</span></div> <div dir="ltr"><span class="term"></span> </div></div></div></blockquote> <blockquote type="cite"> <div> <div id="idOWAReplyText16337" dir="ltr"> <div dir="ltr"><span class="term">the only issue I can think of are these functions with multi-signatures</span></div> <div dir="ltr"><span class="term"><span class="term">ST_AddPoint(linestring, point, [<position>])</span></span></div> <div dir="ltr"><span class="term"><span class="term"></span></span> </div> <div dir="ltr"><span class="term"><span class="term">I personally would prefer see it listed twice as</span></span></div> <div dir="ltr"><span class="term"><span class="term"><span class="term">ST_AddPoint(linestring geometry, point geometry)</span></span></span></div> <div dir="ltr"><span class="term"><span class="term"><span class="term"></span></span></span> </div> <div dir="ltr"><span class="term"><span class="term"><span class="term"><span class="term">ST_AddPoint(linestring geometry, point geometry, position integer)</span></span></span></span></div> <div dir="ltr"><span class="term"><span class="term"><span class="term"><span class="term"></span></span></span></span> </div> <div dir="ltr"><span class="term"><span class="term"><span class="term"><span class="term">since I'm not convinced non-programmers don't find that nomenclature confusing.</span></span></span></span></div> <div dir="ltr"><span class="term"></span> </div> <div dir="ltr"><span class="term">then I'm thinking we can generate the postgis_comments.sql.in from a simple</span></div> <div dir="ltr"><span class="term"></span> </div> <div dir="ltr"><span class="term">postgis_comments.xsl file that parses the postgis.xml thus not needing another dependency.</span></div> <div dir="ltr"><span class="term"></span> </div> <div dir="ltr"><span class="term">Although I could very well be trivializing the simplicity of this.</span></div> <div dir="ltr"><span class="term"></span> </div> <div dir="ltr"><span class="term">Does anyone have issues with me changing the doc accordingly. </span></div> <div dir="ltr"><span class="term"></span> </div></div></div></blockquote> <div><br></div> <div>This sounds excellent. I'd be happy to help with this renaming if it is needed.</div> <div><br></div> <div><br></div> <div>Cheers,</div> <div><br></div> <div>Dane</div> <div><br></div> <div><br></div> <div><br></div><br> <blockquote type="cite"> <div> <div id="idOWAReplyText16337" dir="ltr"> <div dir="ltr"><span class="term">Thanks,</span></div> <div dir="ltr"><span class="term">Regina</span></div> <div dir="ltr"><span class="term"></span> </div> <div dir="ltr"><span class="term"></span> </div></div> <div dir="ltr"><br> <hr tabindex="-1"> <font face="Tahoma" size="2"><b>From:</b> <a href="mailto:postgis-devel-bounces@postgis.refractions.net">postgis-devel-bounces@postgis.refractions.net</a> on behalf of <a href="mailto:codesite-noreply@google.com">codesite-noreply@google.com</a><br><b>Sent:</b> Thu 7/3/2008 5:47 PM<br><b>To:</b> <a href="mailto:postgis-devel@postgis.refractions.net">postgis-devel@postgis.refractions.net</a><br><b>Subject:</b> [postgis-devel] Issue 35 in postgis: Comments on Postgis Functions<br></font><br></div> <div><p><font size="2">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><a href="mailto:postgis-devel@postgis.refractions.net">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></font></p></div></div> <div> <div><br class="webkit-block-placeholder"></div> <hr size="1"> <div><br class="webkit-block-placeholder"></div><p><strong>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. </strong></p></div> <div><br class="webkit-block-placeholder"></div> <hr size="1"> <div><br class="webkit-block-placeholder"></div><p><strong><font color="#339900" size="2">Help make the earth a greener place. If at all possible resist printing this email and join us in saving paper. </font></strong></p><strong><font color="#339900" size="2"></font></strong><p><strong><font color="#339900" size="2"></font></strong></p>_______________________________________________<br>postgis-devel mailing list<br><a href="mailto:postgis-devel@postgis.refractions.net">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></blockquote></div><br></div></div> <div><div><br class="webkit-block-placeholder"></div><hr size="1"><div><br class="webkit-block-placeholder"></div><p><strong> 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. </strong></p></div><div><br class="webkit-block-placeholder"></div><hr size="1"><div><br class="webkit-block-placeholder"></div><p><strong><font size="2" color="339900"> Help make the earth a greener place. If at all possible resist printing this email and join us in saving paper. </font></strong></p><strong><font size="2" color="339900"> </font></strong><p><strong><font size="2" color="339900"> </font></strong></p> _______________________________________________<br>postgis-devel mailing list<br><a href="mailto:postgis-devel@postgis.refractions.net">postgis-devel@postgis.refractions.net</a><br>http://postgis.refractions.net/mailman/listinfo/postgis-devel<br></blockquote></div><br></div></body></html>