Doc: update cs2cs and also C API regarding area of use (fixes #1186)

3 files changed, 104 insertions, 26 deletions

diff --git a/docs/source/apps/cs2cs.rst b/docs/source/apps/cs2cs.rst
index 29ea5b42..bfab6d48 100644
--- a/docs/source/apps/cs2cs.rst
+++ b/docs/source/apps/cs2cs.rst
@@ -6,19 +6,35 @@ cs2cs
 
 .. only:: html
 
-    Cartographic coordinate system filter.
+    Filter for transformations between two coordinate reference systems.
 
 Synopsis
 ********
 
     **cs2cs** [ **-eEfIlrstvwW** [ args ] ] [ *+opts[=arg]* ] [ +to [*+opts[=arg]*] ] file[s]
 
+or
+
+    **cs2cs** [ **-eEfIlrstvwW** [ args ] ] {source_crs} +to {target_crs} file[s]
+
+    where {source_crs} or {target_crs} is a PROJ string, a WKT string or a AUTHORITY:CODE
+    (where AUTHORITY is the name of a CRS authority and CODE the code of a CRS
+    found in the proj.db database), expressing a coordinate reference system.
+
+.. versionadded:: 6.0.0
+
+or
+
+    **cs2cs** [ **-eEfIlrstvwW** [ args ] ] {source_crs} {target_crs}
+
+.. versionadded:: 6.0.0
+
 Description
 ***********
 
 :program:`cs2cs` performs transformation between the source and destination
-cartographic coordinate system on a set of input points. The coordinate
-system transformation can include translation between projected and
+cartographic coordinate reference system on a set of input points. The coordinate
+reference system transformation can include translation between projected and
 geographic coordinates as well as the application of datum shifts.
 
 The following control parameters can appear in any order:
@@ -125,22 +141,21 @@ The following control parameters can appear in any order:
     parameters. Usage varies with projection and for a complete description
     consult the :ref:`projection pages <projections>`.
 
-The :program:`cs2cs` program requires two coordinate system definitions. The first (or
+The :program:`cs2cs` program requires two coordinate reference system (CRS) definitions. The first (or
 primary is defined based on all projection parameters not appearing after the
 *+to* argument. All projection parameters appearing after the *+to* argument
-are considered the definition of the second coordinate system. If there is no
-second coordinate system defined, a geographic coordinate system based on the
-datum and ellipsoid of the source coordinate system is assumed. Note that the
-source and destination coordinate system can both be projections, both be
-geographic, or one of each and may have the same or different datums.
-
-Additional projection control parameters may be contained in two auxiliary
-control files: the first is optionally referenced with the
-*+init=file:id* and the second is always processed after the name of the
-projection has been established from either the run-line or the contents of
-*+init* file. The environment parameter :envvar:`PROJ_LIB` establishes the default
-directory for a file reference without an absolute path. This is also used
-for supporting files like datum shift files.
+are considered the definition of the second CRS. If there is no
+second CRS defined, a geographic CRS based on the
+datum and ellipsoid of the source CRS is assumed. Note that the
+source and destination CRS can both of same or different nature (geographic,
+projected, compound CRS), or one of each and may have the same or different datums.
+
+When using a WKT definition or a AUTHORITY:CODE, the axis order of the CRS will
+be enforced. So for example if using EPSG:4326, the first value expected (or
+returned) will be a latitude.
+
+The environment parameter :envvar:`PROJ_LIB` establishes the
+directory for resource files (database, datum shift grids, etc.)
 
 One or more files (processed in left to right order) specify the source of
 data to be transformed. A ``-`` will specify the location of processing standard
@@ -157,8 +172,11 @@ places), while projected (cartesian) coordinates will be in linear
 (meter, feet) units.
 
 
-Example
-*******
+Examples
+********
+
+Using PROJ strings
+------------------
 
 The following script
 
@@ -179,6 +197,24 @@ The x-y output data will appear as three lines of:
 
     1402285.98  5076292.42 -0.00
 
+
+Using EPSG codes
+----------------
+
+Transforming from WGS 84 latitude/longitude (in that order) to UTM Zone 31N/WGS 84
+
+::
+
+    cs2cs EPSG:4326 EPSG:32631 <<EOF
+    45N 2E
+    EOF
+
+outputs
+
+::
+
+    421184.70   4983436.77 0.00
+
 .. only:: man
 
     See also
diff --git a/docs/source/development/reference/datatypes.rst b/docs/source/development/reference/datatypes.rst
index 25e7ffd2..18bd7efd 100644
--- a/docs/source/development/reference/datatypes.rst
+++ b/docs/source/development/reference/datatypes.rst
@@ -60,11 +60,12 @@ Transformation objects
 
 .. c:type:: PJ_AREA
 
+    .. versionadded:: 6.0.0
+
     Opaque object describing an area in which a transformation is performed.
 
-    .. note:: This object is not fully implemented yet. It is to be used with
-              :c:func:`proj_create_crs_to_crs` to select the best transformation
-              between the two input coordinate reference systems.
+    It is used with :c:func:`proj_create_crs_to_crs` to select the best transformation
+    between the two input coordinate reference systems.
 
 2 dimensional coordinates
 --------------------------------------------------------------------------------
diff --git a/docs/source/development/reference/functions.rst b/docs/source/development/reference/functions.rst
index aa548664..87271117 100644
--- a/docs/source/development/reference/functions.rst
+++ b/docs/source/development/reference/functions.rst
@@ -127,10 +127,10 @@ paragraph for more details.
     The returned :c:type:`PJ`-pointer should be deallocated with :c:func:`proj_destroy`.
 
     :param PJ_CONTEXT* ctx: Threading context.
-    :param `srid_from`: Source SRID.
-    :type `srid_from`: const char*
-    :param `srid_to`: Destination SRID.
-    :type `srid_to`: const char*
+    :param `source_crs`: Source CRS.
+    :type `source_crs`: const char*
+    :param `target_crs`: Destination SRS.
+    :type `target_crs`: const char*
     :param `area`: Descriptor of the desired area for the transformation.
     :type `area`: PJ_AREA
     :returns: :c:type:`PJ*`
@@ -142,6 +142,45 @@ paragraph for more details.
     :param PJ* P:
     :returns: :c:type:`PJ*`
 
+Area of interest
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+.. versionadded:: 6.0.0
+
+
+.. c:function:: PJ_AREA* proj_area_create(void)
+
+    Create an area of use.
+
+    Such an area of use is to be passed to :c:func:`proj_create_crs_to_crs` to
+    specify the area of use for the choice of relevant coordinate operations.
+
+    :returns: :c:type:`PJ_AREA*` to be deallocated with :c:func:`proj_area_destroy`
+
+
+.. c:function:: void proj_area_set_bbox(PJ_AREA *area, double west_lon_degree, double south_lat_degree, double east_lon_degree, double north_lat_degree)
+
+    Set the bounding box of the area of use
+
+    Such an area of use is to be passed to :c:func:`proj_create_crs_to_crs` to
+    specify the area of use for the choice of relevant coordinate operations.
+
+    In the case of an area of use crossing the antimeridian (longitude +/- 180 degrees),
+    `west_lon_degree` will be greater than `east_lon_degree`.
+
+    :param `area`: Pointer to an object returned by :c:func:`proj_area_create`.
+    :param `west_lon_degree`: West longitude, in degrees. In [-180,180] range.
+    :param `south_lat_degree`: South latitude, in degrees. In [-90,90] range.
+    :param `east_lon_degree`: East longitude, in degrees. In [-180,180] range.
+    :param `north_lat_degree`: North latitude, in degrees. In [-90,90] range.
+
+.. c:function:: void proj_area_destroy(PJ_AREA* area)
+
+    Deallocate a :c:type:`PJ_AREA` object.
+
+    :param PJ_AREA* area
+
+
 .. _coord_trans_functions:
 
 Coordinate transformation
@@ -604,6 +643,8 @@ Various
 C API for ISO-19111 functionality
 +++++++++++++++++++++++++++++++++
 
+.. versionadded:: 6.0.0
+
 The PJ* objects returned by :c:func:`proj_create_from_wkt`,
 :c:func:`proj_create_from_database` and other functions in that section
 will have generally minimal interaction with the functions declared in the