[Fwd: Re: [postgis-devel] Issue 35 in postgis: Comments on Postgis Functions]
Obe, Regina
robe.dnd at cityofboston.gov
Tue Jul 8 00:36:27 PDT 2008
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.
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.
Thanks,
Regina
________________________________
From: Dane Springmeyer [mailto:blake at hailmail.net]
Sent: Tue 7/8/2008 2:12 AM
To: Kevin Neufeld
Cc: Obe, Regina
Subject: Re: [Fwd: Re: [postgis-devel] Issue 35 in postgis: Comments on Postgis Functions]
Kevin,
Sounds good. I have no outstanding changes. I'm looking forward to
digging into the split docbook and tracking the new changes...
Do either of you know what the story is on the lack of the use of trac
for postgis? As I get more interested in the work on documentation I
find myself wishing I could track the work though a trac system....
Dane
On Jul 7, 2008, at 7:59 PM, Kevin Neufeld wrote:
> The next step I would like to do is split the postgis.xml doc into
> separate files so it's more manageable - one for every chapter. If
> it's ok with you two, I'll make the change tonite.. making sure to
> checkout the latest commit so we don't lose any of Regina's useful
> commits in the process. :)
>
> Cheers,
> Kevin
>
> -------- Original Message --------
> Subject: Re: [postgis-devel] Issue 35 in postgis: Comments on
> Postgis Functions
> Date: Mon, 07 Jul 2008 19:56:36 -0700
> From: Kevin Neufeld <kneufeld at refractions.net>
> To: PostGIS Development Discussion <postgis-devel at postgis.refractions.net
> >
> References: <0016e64355defbe5a00451258f66 at google.com><53F9CF533E1AA14EA1F8C5C08ABC08D20197A0FD at ZDND.DND.boston.cob
> > <60A74853-AB5F-4B92-A46C-31C822ACDA07 at hailmail.net> <53F9CF533E1AA14EA1F8C5C08ABC08D20453F736 at ZDND.DND.boston.cob
> >
>
>
>
> Regina, Dane,
>
> Yes, I agree that we should keep the issue around a bit so it stays
> on our TODO list.
> In my spare time, I've been working on coming up with a template we
> could use for all the functions in the documentation. I still think
> that having every function as a refentry is the way to go instead of
> the current listitem we currently employ. I'm close ... just
> wrestling with DocBook, trying to make it jump though hoops as I try
> to customize the automatic generation of the TOC.
> Unlike the multiple term issue you were having, the refentry tag
> also permits having multiple function prototypes under the same
> refentry. So the same refpurpose tag could be applied as function
> comments for all overridden prototypes. The concept seems to work
> pretty well... it just the silly TOC that has me tied up in knots.
> Cheers,
> Kevin
>
> Obe, Regina wrote:
>> 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 <mailto:postgis-devel-bounces at postgis.refractions.net
>>> > on behalf of codesite-noreply at google.com <mailto:codesite-noreply at google.com
>>> >
>>> *Sent:* Thu 7/3/2008 5:47 PM
>>> *To:* postgis-devel at postgis.refractions.net <mailto: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 <mailto: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 <mailto: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
>>
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.osgeo.org/pipermail/postgis-devel/attachments/20080708/a1cb0645/attachment.html>
More information about the postgis-devel
mailing list