[Fwd: Re: [postgis-devel] Issue 35 in postgis: Comments on Postgis Functions]
Obe, Regina
robe.dnd at cityofboston.gov
Tue Jul 8 00:31:46 PDT 2008
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.
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.
Thanks,
Regina
________________________________
From: Kevin Neufeld [mailto:kneufeld at refractions.net]
Sent: Tue 7/8/2008 1:29 AM
To: Obe, Regina
Cc: Dane Springmeyer
Subject: Re: [Fwd: Re: [postgis-devel] Issue 35 in postgis: Comments on Postgis Functions]
That's a good question. Are patches usually back-ported to earlier
versions? Version 1.4 will likely have new methods in addition to new
docs. Are we going to have to back-port all the new functionality as
well? I'm tempted to leave 1.3 as a static version, but I think it's a
question you should push to devel. Maybe Mark or Paul will have other
thoughts.
Cheers,
Kevin
Obe, Regina wrote:
> Sure that works for me. Only question I have I hadn't moved the
> changes I made in trunk to branch 1.3 even though they are relevant
> for branch 1.3. Do we not care and are splitting off from branch 1.3
> at this point.
>
> Thanks,
> Regina
>
> ------------------------------------------------------------------------
> *From:* Kevin Neufeld [mailto:kneufeld at refractions.net]
> *Sent:* Mon 7/7/2008 10:59 PM
> *To:* Obe, Regina; Dane Springmeyer
> *Subject:* [Fwd: Re: [postgis-devel] Issue 35 in postgis: Comments on
> Postgis Functions]
>
> 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/2b2e2be4/attachment.html>
More information about the postgis-devel
mailing list