Improve Doc Reference section #383

dr-jts · 2019-03-12T20:50:03Z

Some more doc improvements. See commits for details.

Signed-off-by: Martin Davis <mtnclimb@gmail.com>

Komzpa · 2019-03-13T10:45:30Z

doc/Makefile.in

 	reference_operator.xml \
 	reference_output.xml \
 	reference_processing.xml \
 	reference_raster.xml \
-	reference_temporal.xml \


This is a historic thing. ST_ initially is SpatioTemporal, but by time to design the spec for temporal writers got tired and just said "ok let it be SpaTial". @estebanzimanyi you know the terminology about time, can you advise here?

The only functions under Temporal were ones dealing with Trajectories, so it seems better to give them a section by that name. That highlights the ability to work with trajectories.

As for the ST_ naming, maybe that reflected grand ambitions at one time. But AFAIK the specs haven't really fulfilled these dreams, so now it is just a (nice?) way to namespace spatial functions.

Komzpa · 2019-03-13T10:49:21Z

doc/reference_bbox.xml

+	  <refsynopsisdiv>
+		<funcsynopsis>
+		  <funcprototype>
+			<funcdef>geometry <function>ST_Expand</function></funcdef>


but but but ST_Expand returns rectangular geometry and not a box, if fed with geometry. This minor distinction drove me nuts when I tried to normalize "what the function gets you from which input" graph, after which I decided that boxes are kind of rectangular areas. Also, ST_OrientedEnvelope - it's not a box?

Yes, wasn't sure what was best to do with this. Ideally it would appear under both Geometry and Bounding Box. Too bad the name is overloaded, but there it is.

In the end I decided this was more of a bounding box kind of thing. But can change it back if that's better.

And as for ST_OrientedEnvelope, I also find that name confusing. Perhaps it should be called ST_OrientedRectangle? But it's definitely not a box.

My take on naming practice is that the support of box* types is indicated by using the word "Box" in names. Other names like Rectangle and Envelope indicate that a geometry type is used. The use of the term Envelope at all is perhaps unfortunate, since in PG that function is provided by the box types. But that's what the Simple Features spec uses, so we should use it in a limited way.

doc/reference_bbox.xml

Komzpa · 2019-03-13T10:51:38Z

doc/reference_management.xml

+		<para>Returns the integer SRID of the
+			specified geometry column by searching through the GEOMETRY_COLUMNS table.
+			If the geometry column has not been properly added (e.g. with the
+			<xref linkend="AddGeometryColumn" /> function), this function will not work.</para>


AddGeometryColumn is not a good way to add columns since PostGIS 2?

That's my understanding too. So this description should indicate this more strongly. But will need to research how to phrase this.

doc/reference_measure.xml

Komzpa · 2019-03-13T10:54:45Z

doc/reference_processing.xml

+	  <refnamediv>
+		<refname>ST_Accum</refname>
+
+		<refpurpose>An aggregate function to construct an array of geometries.</refpurpose>


ST_Accum is effectively array_agg. I understand it was added when array_agg wasn't available, but how about removing it now that there is no supported Postgres versions without array_agg?

Sounds good to me. Can we get a third vote of +1?

doc/reference_sfcgal.xml

Komzpa · 2019-03-13T11:00:14Z

doc/Makefile.in

@@ -122,19 +122,19 @@ XML_SOURCES = \
 	performance_tips.xml \
 	postgis.xml \
 	reference_accessor.xml \
+	reference_bbox.xml \


ST_Envelope, ST_OrientedEnvelope I'd expect nearby. Naming needs tweaking then - how about calling section with something like "rectangle functions" so box / geometry-with-rect-angles distinction is not there?

This may also consume operator section since these are defined on boxes?

See previous comment. The Bounding Box section does not contain either "Envelope" function, so I think this is ok? When I reorg the Accessors and Processing sections we can think about where they should go.

My opinion is that they belong in different sections, even though they are unfortunately named similarly. One is just a simple accessor, but the OrientedEnvelope requires a full-blown spatial algorithm to compute. I think it should be called OrientedRectangle or something like that. It should not mention Envelope, because that implies an axis-oriented rectangle.

I think the operator section should remain distinct, since it's long already. And operators are clearly different things to functions.

estebanzimanyi · 2019-03-13T11:32:08Z

A quick answer, I can dig more if needed. I think we cannot deviate from ST_* which, as Darafei rightfully pointed out, was meant SpatioTemporal at the beginning. Since it took years (more precisely decades) to begin addressing the spatiotemporal aspects, the meaning of the ST_ prefix became SpaTial. FYI, the current (draft) standards for spatiotemporal aspects can be found here https://www.opengeospatial.org/standards/movingfeatures It may be the case that the prefix for those functions at the SQL level would be MF_ but according to my understanding this has still to be decided Esteban

…

On Wed, Mar 13, 2019 at 12:00 PM Darafei Praliaskouski < ***@***.***> wrote: ***@***.**** commented on this pull request. ------------------------------ In doc/Makefile.in <#383 (comment)>: > @@ -122,19 +122,19 @@ XML_SOURCES = \ performance_tips.xml \ postgis.xml \ reference_accessor.xml \ + reference_bbox.xml \ ST_Envelope, ST_OrientedEnvelope I'd expect nearby. Naming needs tweaking then - how about calling section with something like "rectangle functions" so box / geometry-with-rect-angles distinction is not there? This may also consume operator section since these are defined on boxes? — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#383 (review)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AZp2BoDI-buBFamIehtgqR8PLM8U-5wJks5vWNpKgaJpZM4br2nE> .

-- ------------------------------------------------------------ Prof. Esteban Zimanyi Department of Computer & Decision Engineering (CoDE) CP 165/15 Universite Libre de Bruxelles Avenue F. D. Roosevelt 50 B-1050 Brussels, Belgium fax: + 32.2.650.47.13 tel: + 32.2.650.31.85 e-mail: ezimanyi@ulb.ac.be Internet: http://code.ulb.ac.be/ ------------------------------------------------------------

Signed-off-by: Martin Davis <mtnclimb@gmail.com>

dr-jts · 2019-03-13T17:13:35Z

@estebanzimanyi @Komzpa Agreed, there's definitely no mandate to use a prefix other than ST_ right now.

I see now where the word Temporal comes from. However, "Temporal" has a much more general meaning in the database world. So it needs to be qualified in the PG context. Perhaps this section should be called Temporal Trajectory Functions? That would tie in with the OGC spec (which I wasn't aware of, and is nice to see). Although are there really any other kind of trajectories?

I note however that the PG functions do not seem to follow the OGC naming?

It might be nice to "namespace" the Trajectory functions. Maybe by using the prefix "ST_TrajectoryXXX"?

dr-jts · 2019-03-13T19:00:09Z

@Komzpa once again thanks for the detailed and thought-provoking review.

Can we make this PR just about reorganizing the reference section, and defer the issues of removing/improving docs to another issue? That will let this get committed and I can work on further improvements.

dr-jts · 2019-03-19T04:43:28Z

To summarize: apart from the reorganization which is the focus of this PR, for reference the other changes suggested are:

Possibly drop AddGeometryColumn doc, or make clear it is no longer needed?
Remove or deprecate ST_Accum
Possibly call section Temporal Trajectory Support ?

dr-jts · 2019-03-19T04:43:56Z

Is it possible to merge this PR? @strk @Komzpa

Komzpa · 2019-03-19T05:31:42Z

@dr-jts merged. a ticket linkr mentioned somewhere on the PR would be really helpful for composing a Closes: / References: section of merge svn commit message :)

Komzpa · 2019-03-19T05:36:25Z

Possibly drop AddGeometryColumn doc, or make clear it is no longer needed?

De-emphasize it. Go through docs and make sure we only mention it on its own page.

Remove or deprecate ST_Accum

I've raised it on mailing list.

Possibly call section Temporal Trajectory Support ?

My dream is to take @estebanzimanyi's work and make it part of PostGIS.

estebanzimanyi · 2019-03-19T07:00:38Z

It is my dream also. Working hard toward this. This weekend I transformed documentation from LaTeX to docbook format to be compatible with PostGIS. Still have to finalize selectivity functions for the operators. But we are little by little reaching a first release. Le mar. 19 mars 2019 à 06:36, Darafei Praliaskouski < notifications@github.com> a écrit :

…

Possibly drop AddGeometryColumn doc, or make clear it is no longer needed? De-emphasize it. Go through docs and make sure we only mention it on its own page. Remove or deprecate ST_Accum I've raised it on mailing list. Possibly call section Temporal Trajectory Support ? My dream is to take @estebanzimanyi <https://github.com/estebanzimanyi>'s work and make it part of PostGIS. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#383 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AZp2BtvZ0LSx6NQ_B8YW2bltiPEul1FXks5vYHddgaJpZM4br2nE> .

dr-jts added 11 commits March 11, 2019 22:19

Improve trajectory function section

0dab129

Signed-off-by: Martin Davis <mtnclimb@gmail.com>

Improve Long Transaction reference section

4d937f8

Signed-off-by: Martin Davis <mtnclimb@gmail.com>

Add doc Reference Bounding Box functions section

51a0f1b

Signed-off-by: Martin Davis <mtnclimb@gmail.com>

Move doc Reference SFCGAL section

ca89cb3

Signed-off-by: Martin Davis <mtnclimb@gmail.com>

Move doc Reference Misc function Find_SRID

5ba91e2

Signed-off-by: Martin Davis <mtnclimb@gmail.com>

Move doc Ref ST_PointInsideCircle function

daf0850

Signed-off-by: Martin Davis <mtnclimb@gmail.com>

Move doc Ref ST_MemSize function

46b728c

Signed-off-by: Martin Davis <mtnclimb@gmail.com>

Move doc Ref function ST_Accum to Processing functions

3df5c96

Signed-off-by: Martin Davis <mtnclimb@gmail.com>

Disable doc Ref Misc Functions section

25f165f

Signed-off-by: Martin Davis <mtnclimb@gmail.com>

Fix doc Ref section XML DTD error

cb110b1

Signed-off-by: Martin Davis <mtnclimb@gmail.com>

REALLY fix the doc Ref section DTD error

5f763bf

Signed-off-by: Martin Davis <mtnclimb@gmail.com>

Komzpa reviewed Mar 13, 2019

View reviewed changes

dr-jts added 3 commits March 13, 2019 09:26

Use 3D instead of 3d in doc Ref bbox section

d31ca2b

Signed-off-by: Martin Davis <mtnclimb@gmail.com>

Fix doc link for ST_PointInsideCircle

bc9b307

Signed-off-by: Martin Davis <mtnclimb@gmail.com>

Fix doc SFCGAL link formatting.

b78e75d

Signed-off-by: Martin Davis <mtnclimb@gmail.com>

strk closed this in 7db2b4c Mar 19, 2019

dr-jts deleted the doc-improve-ref branch March 21, 2019 23:04

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Improve Doc Reference section #383

Improve Doc Reference section #383

dr-jts commented Mar 12, 2019

Komzpa Mar 13, 2019

dr-jts Mar 13, 2019

dr-jts Mar 13, 2019

Komzpa Mar 13, 2019

dr-jts Mar 13, 2019

dr-jts Mar 13, 2019

Komzpa Mar 13, 2019

dr-jts Mar 13, 2019 •

edited

Komzpa Mar 13, 2019

dr-jts Mar 13, 2019

Komzpa Mar 13, 2019

dr-jts Mar 13, 2019

dr-jts Mar 13, 2019

estebanzimanyi commented Mar 13, 2019 via email

dr-jts commented Mar 13, 2019 •

edited

dr-jts commented Mar 13, 2019

dr-jts commented Mar 19, 2019

dr-jts commented Mar 19, 2019

Komzpa commented Mar 19, 2019

Komzpa commented Mar 19, 2019

estebanzimanyi commented Mar 19, 2019 via email

Navigation Menu

Improve Doc Reference section #383

Improve Doc Reference section #383

Conversation

dr-jts commented Mar 12, 2019

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

dr-jts Mar 13, 2019 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

estebanzimanyi commented Mar 13, 2019 via email

dr-jts commented Mar 13, 2019 • edited

dr-jts commented Mar 13, 2019

dr-jts commented Mar 19, 2019

dr-jts commented Mar 19, 2019

Komzpa commented Mar 19, 2019

Komzpa commented Mar 19, 2019

estebanzimanyi commented Mar 19, 2019 via email

dr-jts Mar 13, 2019 •

edited

dr-jts commented Mar 13, 2019 •

edited