Commit da4041a3 authored by Darafei Praliaskouski's avatar Darafei Praliaskouski

Doc layout improvements.

Patch by Martin Davis.

References #4332
Closes https://github.com/postgis/postgis/pull/380


git-svn-id: http://svn.osgeo.org/postgis/trunk@17335 b70326c6-7e19-0410-871a-916f4a2858ee
parent bf1c0826
Pipeline #51313806 passed with stage
in 22 minutes and 55 seconds
......@@ -124,7 +124,6 @@ XML_SOURCES = \
reference_accessor.xml \
reference_constructor.xml \
reference_editor.xml \
reference_exception.xml \
reference_guc.xml \
reference_lrs.xml \
reference_management.xml \
......@@ -137,7 +136,9 @@ XML_SOURCES = \
reference_raster.xml \
reference_temporal.xml \
reference_transaction.xml \
reference_troubleshooting.xml \
reference_type.xml \
reference_version.xml \
reference.xml \
release_notes.xml \
reporting.xml \
......
......@@ -41,7 +41,8 @@
<!ENTITY reference_temporal SYSTEM "reference_temporal.xml">
<!ENTITY reference_transaction SYSTEM "reference_transaction.xml">
<!ENTITY reference_misc SYSTEM "reference_misc.xml">
<!ENTITY reference_exception SYSTEM "reference_exception.xml">
<!ENTITY reference_troubleshooting SYSTEM "reference_troubleshooting.xml">
<!ENTITY reference_version SYSTEM "reference_version.xml">
<!ENTITY reference_raster SYSTEM "reference_raster.xml">
<!ENTITY faq_raster SYSTEM "faq_raster.xml">
<!ENTITY extras SYSTEM "extras.xml">
......
......@@ -17,7 +17,6 @@
</note>
&reference_type;
&reference_guc;
&reference_management;
&reference_constructor;
&reference_accessor;
......@@ -31,6 +30,8 @@
&reference_temporal;
&reference_transaction;
&reference_misc;
&reference_exception;
&reference_version;
&reference_guc;
&reference_troubleshooting;
</chapter>
......@@ -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).
These can be set globally, by database, by session or by transaction. Best set at global or database level.</para>
</abstract>
</sect1info>
<title>PostGIS Grand Unified Custom Variables (GUCs)</title>
<title>Grand Unified Custom Variables (GUCs)</title>
<refentry id="postgis_backend">
<refnamediv>
......
This diff is collapsed.
<?xml version="1.0" encoding="UTF-8"?>
<sect1 id="Troubleshooting_Functions">
<sect1info>
<abstract>
<para>These functions are utilities for troubleshooting and repairing geometry data.
They are only needed if the geometry data is corrupted in some way,
which should never happen under normal circumstances.</para>
</abstract>
</sect1info>
<title>Troubleshooting Functions</title>
<refentry id="PostGIS_AddBBox">
<refnamediv>
<refname>PostGIS_AddBBox</refname>
<refpurpose>Add bounding box to the geometry.</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcprototype>
<funcdef>geometry <function>PostGIS_AddBBox</function></funcdef>
<paramdef><type>geometry </type> <parameter>geomA</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsection>
<title>Description</title>
<para>Add bounding box to the geometry. This would make bounding
box based queries faster, but will increase the size of the
geometry.</para>
<note>
<para>Bounding boxes are automatically added to geometries so in general this is not needed
unless the generated bounding box somehow becomes corrupted or you have an old install that is lacking bounding boxes. Then you need to drop the old and readd.</para>
</note>
<para>&curve_support;</para>
</refsection>
<refsection>
<title>Examples</title>
<programlisting>UPDATE sometable
SET the_geom = PostGIS_AddBBox(the_geom)
WHERE PostGIS_HasBBox(the_geom) = false;</programlisting>
</refsection>
<!-- Optionally add a "See Also" section -->
<refsection>
<title>See Also</title>
<para><xref linkend="PostGIS_DropBBox" />, <xref linkend="PostGIS_HasBBox" /></para>
</refsection>
</refentry>
<refentry id="PostGIS_DropBBox">
<refnamediv>
<refname>PostGIS_DropBBox</refname>
<refpurpose>Drop the bounding box cache from the geometry.</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcprototype>
<funcdef>geometry <function>PostGIS_DropBBox</function></funcdef>
<paramdef><type>geometry </type> <parameter>geomA</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsection>
<title>Description</title>
<para>Drop the bounding box cache from the geometry. This reduces
geometry size, but makes bounding-box based queries slower. It is also used to drop a corrupt bounding box. A tale-tell sign of a corrupt cached bounding box
is when your ST_Intersects and other relation queries leave out geometries that rightfully should return true.</para>
<note>
<para>Bounding boxes are automatically added to geometries and improve speed of queries so in general this is not needed
unless the generated bounding box somehow becomes corrupted or you have an old install that is lacking bounding boxes.
Then you need to drop the old and readd. This kind of corruption has been observed in 8.3-8.3.6 series whereby cached bboxes were not always recalculated when a geometry changed and upgrading to a newer version without a dump reload will not
correct already corrupted boxes. So one can manually correct using below and readd the bbox or do a dump reload.</para>
</note>
<para>&curve_support;</para>
</refsection>
<refsection>
<title>Examples</title>
<programlisting>--This example drops bounding boxes where the cached box is not correct
--The force to ST_AsBinary before applying Box2D forces a recalculation of the box, and Box2D applied to the table geometry always
-- returns the cached bounding box.
UPDATE sometable
SET the_geom = PostGIS_DropBBox(the_geom)
WHERE Not (Box2D(ST_AsBinary(the_geom)) = Box2D(the_geom));
UPDATE sometable
SET the_geom = PostGIS_AddBBox(the_geom)
WHERE Not PostGIS_HasBBOX(the_geom);
</programlisting>
</refsection>
<!-- Optionally add a "See Also" section -->
<refsection>
<title>See Also</title>
<para><xref linkend="PostGIS_AddBBox" />, <xref linkend="PostGIS_HasBBox" />, <xref linkend="Box2D" /></para>
</refsection>
</refentry>
<refentry id="PostGIS_HasBBox">
<refnamediv>
<refname>PostGIS_HasBBox</refname>
<refpurpose>Returns TRUE if the bbox of this geometry is cached, FALSE otherwise.</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcprototype>
<funcdef>boolean <function>PostGIS_HasBBox</function></funcdef>
<paramdef><type>geometry </type> <parameter>geomA</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsection>
<title>Description</title>
<para>Returns TRUE if the bbox of this geometry is cached, FALSE
otherwise. Use <xref linkend="PostGIS_AddBBox" /> and <xref linkend="PostGIS_DropBBox" /> to control caching.</para>
<para>&curve_support;</para>
</refsection>
<refsection>
<title>Examples</title>
<programlisting>SELECT the_geom
FROM sometable WHERE PostGIS_HasBBox(the_geom) = false;</programlisting>
</refsection>
<!-- Optionally add a "See Also" section -->
<refsection>
<title>See Also</title>
<para><xref linkend="PostGIS_AddBBox" />, <xref linkend="PostGIS_DropBBox" /></para>
</refsection>
</refentry>
</sect1>
......@@ -2,43 +2,65 @@
<sect1 id="PostGIS_Types">
<sect1info>
<abstract>
<para>This section lists the PostgreSQL data types installed by PostGIS. Note we describe the casting behavior of these which is very
important especially when designing your own functions.
<para>This section lists the custom PostgreSQL
data types installed by PostGIS to represent spatial data.
</para>
<para>A Cast is when one type is coerced into another type. PostgreSQL
is unique from most databases in that it allows you to define casting behavior for custom types and the functions used for casting.
A cast can be specified as automatic in which case, you do not have to do a CAST(myfoo As otherfootype) or myfoo::otherfootype
if you are feeding it to a function that only works with otherfootype and there is an automatic cast in place for it.
</para>
<para>The danger of relying on automatic cast behavior is when you have an overloaded function say one that takes a box2d and one that takes a box3d
but no geometry. What happens is that both functions are equally good to use with geometry since geometry has an autocast for both
-- so you end up with an ambiguous function error. To force PostgreSQL to choose, you do a CAST(mygeom As box3d) or mygeom::box3d.</para>
<para>Each data type describes its type casting behaviour.
A <ulink url="https://www.postgresql.org/docs/current/sql-expressions.html#SQL-SYNTAX-TYPE-CASTS">type cast</ulink> converts values of one data type into another type.
PostgreSQL allows defining casting behavior for custom types, along with the functions used to convert type values.
Casts can be defined as <emphasis role="bold">automatic</emphasis>.
This allows PostgreSQL to automatically convert a function argument to a type supported by the function.
Casts can also be specified <emphasis role="bold">explicitly</emphasis>,
using the syntax <varname>CAST(myval As sometype)</varname> or <varname>myval::sometype</varname>.
This allows avoiding an issue that can occur when using an overloaded function which does not support a given type
(for example, one that accepts a box2d or a box3d, but not a geometry.)
Since geometry has an automatic cast to both box types, this will produce an "ambiguous function" error.
To prevent the error use an explicit cast to the desired box type.</para>
<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>All data types can be CAST to <varname>text</varname>, so these do not need to be specified explicitly.</para>
</abstract>
</sect1info>
<title>PostgreSQL PostGIS Geometry/Geography/Box Types</title>
<title>PostGIS Geometry/Geography/Box Data Types</title>
<refentry id="box2d_type">
<refnamediv>
<refname>box2d</refname>
<refpurpose>A box composed of x min, ymin, xmax, ymax. Often used to return the 2d enclosing box of a geometry. </refpurpose>
<refpurpose>A 2-dimensional bounding box.
Often used to describe the 2D extent of a geometry or collection of geometries. </refpurpose>
</refnamediv>
<refsection>
<title>Description</title>
<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 <xref linkend="ST_Extent" /> aggregate function returns a <varname>box2d</varname> object.</para>
<para>The representation contains the values <varname>xmin, ymin, xmax, ymax</varname>.
These are the minimum and maxium values of the X and Y extents.
</para>
</refsection>
<refsection>
<title>See Also</title>
<para><xref linkend="PostGIS_BoxFunctions" /></para>
</refsection>
</refentry>
<refentry id="box3d_type">
<refnamediv>
<refname>box3d</refname>
<refpurpose>A box composed of x min, ymin, zmin, xmax, ymax, zmax. Often used to return the 3d extent of a geometry or collection of geometries. </refpurpose>
<refpurpose>A 3-dimensional bounding box.
Often used to describe the 3D extent of a geometry or collection of geometries. </refpurpose>
</refnamediv>
<refsection>
<title>Description</title>
<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 <xref linkend="ST_3DExtent" /> aggregate function returns a <varname>box3d</varname> object.
</para>
<para>The representation contains the values <varname>xmin, ymin, zmin, xmax, ymax, zmax</varname>.
These are the minimum and maxium values of the X, Y and Z extents.
</para>
</refsection>
<refsection>
......@@ -67,18 +89,24 @@
</tgroup>
</informaltable>
</refsection>
<refsection>
<title>See Also</title>
<para><xref linkend="PostGIS_BoxFunctions" /></para>
</refsection>
</refentry>
<refentry id="geometry">
<refnamediv>
<refname>geometry</refname>
<refpurpose>Planar spatial data type.</refpurpose>
<refpurpose>The type representing spatial features with planar coordinate systems.</refpurpose>
</refnamediv>
<refsection>
<title>Description</title>
<para>geometry is a fundamental PostGIS spatial data type used to represent a feature in the Euclidean coordinate system.</para>
<para>All spatial operations on geometry are using units of the Spatial Reference System the geomtry is in.</para>
<para><varname>geometry</varname> is a fundamental PostGIS spatial data type used to represent a feature in planar (Euclidean) coordinate systems.</para>
<para>All spatial operations on geometry use the units of the Spatial Reference System the geometry is in.</para>
</refsection>
<refsection>
......@@ -122,23 +150,34 @@
<refsection>
<title>See Also</title>
<para><xref linkend="RefObject" /></para>
<para><xref linkend="RefObject" />, <xref linkend="PostGIS_SQLMM_Functions" /></para>
</refsection>
</refentry>
<refentry id="geometry_dump">
<refnamediv>
<refname>geometry_dump</refname>
<refpurpose>A spatial datatype with two fields - geom (holding a geometry object)
and path[] (a 1-d array holding the position of the geometry within the dumped object.)</refpurpose>
<refpurpose>A composite type used to describe the parts of complex geometry.</refpurpose>
</refnamediv>
<refsection>
<title>Description</title>
<para>geometry_dump is a compound data type consisting of a geometry object referenced by the .geom field
and path[] a 1-dimensional integer array (starting at 1 e.g. path[1] to get first element) array that defines the navigation path within the dumped geometry to find this element.
It is used by the ST_Dump* family of functions as an output type to explode a more complex geometry into its
constituent parts and location of parts.</para>
<para><varname>geometry_dump</varname> is a
<ulink url="https://www.postgresql.org/docs/current/rowtypes.html">composite data type</ulink>
containing the fields:</para>
<itemizedlist>
<listitem>
<para><varname>geom</varname> - a references to a component geometry</para>
</listitem>
<listitem>
<para><varname>path[]</varname> - a 1-dimensional integer array
that defines the navigation path within the dumped geometry to the <varname>geom</varname> component.
The path array starts at 1 (e.g. <varname>path[1]</varname> is the first element.)</para>
</listitem>
</itemizedlist>
<para>
It is used by the <varname>ST_Dump*</varname> family of functions as an output type to explode a complex geometry into its
constituent parts.</para>
</refsection>
<refsection>
<title>See Also</title>
......@@ -149,12 +188,18 @@
<refentry id="geography">
<refnamediv>
<refname>geography</refname>
<refpurpose>Ellipsoidal spatial data type.</refpurpose>
<refpurpose>The type representing spatial features with geodetic (ellipsoidal) coordinate systems.</refpurpose>
</refnamediv>
<refsection>
<title>Description</title>
<para>geography is a spatial data type used to represent a feature in the round-earth coordinate system.</para>
<para><varname>geography</varname> is a spatial data type used to represent a feature in geodetic coordinate systems.
Geodetic coordinate systems model the earth using an ellipsoid.
</para>
<para>
Spatial operations on the geography type provide more accurate results
by taking the ellipsoidal model into account.
</para>
</refsection>
<refsection>
......@@ -178,7 +223,7 @@
<refsection>
<title>See Also</title>
<para><xref linkend="PostGIS_GeographyFunctions" />, <xref linkend="PostGIS_Geography" /></para>
<para><xref linkend="PostGIS_Geography" />, <xref linkend="PostGIS_GeographyFunctions" /></para>
</refsection>
</refentry>
</sect1>
This diff is collapsed.
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment