Doc: improve cs2cs doc by mentionning possibility to use EPSG CRS names (#2290)

3 files changed, 46 insertions, 7 deletions

diff --git a/docs/source/apps/cs2cs.rst b/docs/source/apps/cs2cs.rst
index ef3ee7b1..b90ff5d3 100644
--- a/docs/source/apps/cs2cs.rst
+++ b/docs/source/apps/cs2cs.rst
@@ -17,9 +17,26 @@ or
 
     **cs2cs** [**-eEfIlrstvwW** [args]] {source_crs} {target_crs} file ...
 
-    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.
+    where {source_crs} or {target_crs} is one of the possibilities accepted
+    by :c:func:`proj_create`, provided it expresses a CRS
+
+    - a proj-string,
+    - a WKT string,
+    - an object code (like "EPSG:4326", "urn:ogc:def:crs:EPSG::4326",
+      "urn:ogc:def:coordinateOperation:EPSG::1671"),
+    - an Object name. e.g "WGS 84", "WGS 84 / UTM zone 31N". In that case as
+      uniqueness is not guaranteed, heuristics are applied to determine the appropriate best match.
+    - a OGC URN combining references for compound coordinate reference systems
+      (e.g "urn:ogc:def:crs,crs:EPSG::2393,crs:EPSG::5717" or custom abbreviated
+      syntax "EPSG:2393+5717"),
+    - a OGC URN combining references for references for projected or derived CRSs
+      e.g. for Projected 3D CRS "UTM zone 31N / WGS 84 (3D)":
+      "urn:ogc:def:crs,crs:EPSG::4979,cs:PROJ::ENh,coordinateOperation:EPSG::16031"
+      (*added in 6.2*)
+    - a OGC URN combining references for concatenated operations
+      (e.g. "urn:ogc:def:coordinateOperation,coordinateOperation:EPSG::3895,coordinateOperation:EPSG::1618")
+    - a PROJJSON string. The jsonschema is at https://proj.org/schemas/v0.2/projjson.schema.json (*added in 6.2*)
+    - a compound CRS made from two object names separated with " + ". e.g. "WGS 84 + EGM96 height" (*added in 7.1*)
 
     .. versionadded:: 6.0.0
 
@@ -210,8 +227,8 @@ The x-y output data will appear as three lines of:
     1402293.44  5076292.68 0.00
 
 
-Using EPSG codes
-----------------
+Using EPSG CRS codes
+--------------------
 
 Transforming from WGS 84 latitude/longitude (in that order) to UTM Zone 31N/WGS 84
 
@@ -227,6 +244,23 @@ outputs
 
     421184.70   4983436.77 0.00
 
+Using EPSG CRS names
+--------------------
+
+Transforming from WGS 84 latitude/longitude (in that order) with EGM96 height to
+UTM Zone 31N/WGS 84 with WGS84 ellipsoidal height
+
+::
+
+    echo 45 2 0 | cs2cs "WGS 84 + EGM96 height" "WGS 84 / UTM zone 31N"
+
+outputs
+
+::
+
+    421184.70   4983436.77 50.69
+
+
 .. only:: man
 
     See also
diff --git a/docs/source/apps/projinfo.rst b/docs/source/apps/projinfo.rst
index 99adbd50..13e2231f 100644
--- a/docs/source/apps/projinfo.rst
+++ b/docs/source/apps/projinfo.rst
@@ -31,7 +31,8 @@ Synopsis
     |    {object_reference} | (-s {srs_def} -t {srs_def})
     |
 
-    where {object_definition} or {srs_def} is
+    where {object_definition} or {srs_def} is one of the possibilities accepted
+    by :c:func:`proj_create`
 
     - a proj-string,
     - a WKT string,
@@ -48,7 +49,7 @@ Synopsis
       (*added in 6.2*)
     - a OGC URN combining references for concatenated operations
       (e.g. "urn:ogc:def:coordinateOperation,coordinateOperation:EPSG::3895,coordinateOperation:EPSG::1618")
-    - a PROJJSON string. The jsonschema is at https://proj.org/schemas/v0.1/projjson.schema.json (*added in 6.2*)
+    - a PROJJSON string. The jsonschema is at https://proj.org/schemas/v0.2/projjson.schema.json (*added in 6.2*)
     - a compound CRS made from two object names separated with " + ". e.g. "WGS 84 + EGM96 height" (*added in 7.1*)
 
     {object_reference} is a filename preceded by the '@' character.  The
diff --git a/docs/source/development/reference/functions.rst b/docs/source/development/reference/functions.rst
index e092c4a0..770fb8ec 100644
--- a/docs/source/development/reference/functions.rst
+++ b/docs/source/development/reference/functions.rst
@@ -37,11 +37,15 @@ paragraph for more details.
     - a WKT string,
     - an object code (like "EPSG:4326", "urn:ogc:def:crs:EPSG::4326",
       "urn:ogc:def:coordinateOperation:EPSG::1671"),
+    - an Object name. e.g "WGS 84", "WGS 84 / UTM zone 31N". In that case as
+      uniqueness is not guaranteed, heuristics are applied to determine the appropriate best match.
     - a OGC URN combining references for compound coordinate reference systems
       (e.g "urn:ogc:def:crs,crs:EPSG::2393,crs:EPSG::5717" or custom abbreviated
       syntax "EPSG:2393+5717"),
     - a OGC URN combining references for concatenated operations
       (e.g. "urn:ogc:def:coordinateOperation,coordinateOperation:EPSG::3895,coordinateOperation:EPSG::1618")
+    - a PROJJSON string. The jsonschema is at https://proj.org/schemas/v0.2/projjson.schema.json (*added in 6.2*)
+    - a compound CRS made from two object names separated with " + ". e.g. "WGS 84 + EGM96 height" (*added in 7.1*)
 
     Example call: