Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Doc Reference enhancements #380

Closed
wants to merge 6 commits into from

Conversation

@dr-jts
Copy link
Contributor

commented Mar 9, 2019

This PR is a start on implementing improvements to the documentation suggested in ticket 4332.

The commits show the various improvements being suggested.

dr-jts added 4 commits Mar 8, 2019
Create Table Management and Version sections
Move admin sections to bottom

Signed-off-by: Martin Davis <mtnclimb@gmail.com>
Rename Exceptional to Troubleshooting Functions
Add abstract


Signed-off-by: Martin Davis <mtnclimb@gmail.com>
Simplify some section titles
Improve data type section

Signed-off-by: Martin Davis <mtnclimb@gmail.com>
Improve spatial datatype descriptions
Signed-off-by: Martin Davis <mtnclimb@gmail.com>
@@ -2,10 +2,11 @@
<sect1 id="PostGIS_GUC">
<sect1info>
<abstract>
<para>This section lists custom PostGIS Grand Unified Custom Variables(GUC). These can be set globally, by database, by session or by transaction. Best set at global or database level.</para>
<para>This section lists custom PostGIS Grand Unified Custom Variables(GUC).

This comment has been minimized.

Copy link
@Komzpa

Komzpa Mar 11, 2019

Member
Suggested change
<para>This section lists custom PostGIS Grand Unified Custom Variables(GUC).
<para>This section lists custom PostGIS Grand Unified Custom Variables (GUC).

<para><emphasis>At least as of PostgreSQL 8.3</emphasis> - Everything can be CAST to text (presumably because of the magical unknown type), so no defined CASTS for that need to be present for you to CAST an object to text.</para>
<para><emphasis>(At least as of PostgreSQL 8.3)</emphasis> Everything can be CAST to <varname>text</varname>, so CASTs to text do not need to be specified.</para>

This comment has been minimized.

Copy link
@Komzpa

Komzpa Mar 11, 2019

Member

Postgres 8.3 is dead since 2013.

Suggested change
<para><emphasis>(At least as of PostgreSQL 8.3)</emphasis> Everything can be CAST to <varname>text</varname>, so CASTs to text do not need to be specified.</para>
<para>Everything can be CAST to <varname>text</varname>, so CASTs to text do not need to be specified.</para>
</abstract>
</sect1info>
<title>PostgreSQL PostGIS Geometry/Geography/Box Types</title>
<title>Geometry/Geography/Box Data Types</title>

This comment has been minimized.

Copy link
@Komzpa

Komzpa Mar 11, 2019

Member
Suggested change
<title>Geometry/Geography/Box Data Types</title>
<title>PostGIS Geometry/Geography/Box Data Types</title>

PostGIS box != Postgres box

This comment has been minimized.

Copy link
@dr-jts

dr-jts Mar 11, 2019

Author Contributor

Good call.

<para>box2d is a spatial data type used to represent the enclosing box of a geometry or set of geometries. ST_Extent in earlier versions prior to PostGIS 1.4 would return a box2d.</para>
<para><varname>box2d</varname> is a spatial data type used to represent
the two-dimensional enclosing box of a geometry or collection of geometries.
For example, the <varname>ST_Extent</varname> aggregate function returns a <varname>box2d</varname> object.</para>

This comment has been minimized.

Copy link
@Komzpa

Komzpa Mar 11, 2019

Member

instead of wrapping into varname these can be links:

Suggested change
For example, the <varname>ST_Extent</varname> aggregate function returns a <varname>box2d</varname> object.</para>
For example, the <xref linkend="ST_Extent" /> aggregate function returns a <varname>box2d</varname> object.</para>

This comment has been minimized.

Copy link
@dr-jts

dr-jts Mar 11, 2019

Author Contributor

Nice, definitely better. My opinion is that everything should be linked if possible, to allow easy traversal through the docs.

<para>box3d is a postgis spatial data type used to represent the enclosing box of a geometry or set of geometries. ST_3DExtent returns a box3d object.</para>
<para><varname>box3d</varname> is a postgis spatial data type used to represent
the three-dimensional enclosing box of a geometry or collection of geometries.
For example, the <varname>ST_3DExtent</varname> aggregate function returns a <varname>box3d</varname> object.

This comment has been minimized.

Copy link
@Komzpa

Komzpa Mar 11, 2019

Member
Suggested change
For example, the <varname>ST_3DExtent</varname> aggregate function returns a <varname>box3d</varname> object.
For example, the <xref linkend="ST_3DExtent" /> aggregate function returns a <varname>box3d</varname> object.

<refpurpose>
Packages and upgrades postgis extensions (e.g. postgis_sfcgal,
postgis_topology, postgis_sfcgal) to latest available version.

This comment has been minimized.

Copy link
@Komzpa

Komzpa Mar 11, 2019

Member
Suggested change
postgis_topology, postgis_sfcgal) to latest available version.
postgis_topology, postgis_sfcgal, postgis_raster) to latest available version.
@Komzpa

This comment has been minimized.

Copy link
Member

commented Mar 11, 2019

I like this. @dr-jts wave when you feel it's ready for (intermediate) commit.

dr-jts added 2 commits Mar 11, 2019
Make suggested improvements
Signed-off-by: Martin Davis <mtnclimb@gmail.com>
Wording changes, simplify type to-level description
Signed-off-by: Martin Davis <mtnclimb@gmail.com>
@dr-jts

This comment has been minimized.

Copy link
Contributor Author

commented Mar 11, 2019

Thanks for the detailed review, @Komzpa, and for the thumbs-up.

I've made a few more small changes - hopefully they look good too. And now I'll stop until this is committed.

@strk strk closed this in da4041a Mar 11, 2019

@Komzpa

This comment has been minimized.

Copy link
Member

commented Mar 11, 2019

@dr-jts merged, please continue :D

@dr-jts dr-jts deleted the dr-jts:doc-reference-enhancements branch Mar 11, 2019

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
2 participants
You can’t perform that action at this time.