cs2cs / proj_create_crs_to_crs_from_pj(): add a --authority switch to control where coordinate operations are looked for (fixes #2442)

2 files changed, 35 insertions, 12 deletions

diff --git a/docs/source/apps/cs2cs.rst b/docs/source/apps/cs2cs.rst
index 7fe570d9..7df8890f 100644
--- a/docs/source/apps/cs2cs.rst
+++ b/docs/source/apps/cs2cs.rst
@@ -11,15 +11,11 @@ cs2cs
 Synopsis
 ********
 
-    **cs2cs** [**-eEfIlrstvwW** [args]]
-              [[--area name_or_code] | [--bbox west_long,south_lat,east_long,north_lat]]
-              [*+opt[=arg]* ...] [+to *+opt[=arg]* ...] file ...
-
-or
-
-    **cs2cs** [**-eEfIlrstvwW** [args]] [--area name_or_code]
-              [[--area name_or_code] | [--bbox west_long,south_lat,east_long,north_lat]]
-              {source_crs} {target_crs} file ...
+    | **cs2cs** [**-eEfIlrstvwW** [args]]
+    |           [[--area <name_or_code>] | [--bbox <west_long,south_lat,east_long,north_lat>]]
+    |           [--authority <name>]
+    |           ([*+opt[=arg]* ...] [+to *+opt[=arg]* ...] | {source_crs} {target_crs})
+    |           file ...
 
     where {source_crs} or {target_crs} is one of the possibilities accepted
     by :c:func:`proj_create`, provided it expresses a CRS
@@ -148,7 +144,7 @@ The following control parameters can appear in any order:
     Causes a listing of cartographic control parameters tested for and used by
     the program to be printed prior to input data.
 
-.. option:: --area name_or_code
+.. option:: --area <name_or_code>
 
     .. versionadded:: 8.0.0
 
@@ -158,7 +154,7 @@ The following control parameters can appear in any order:
 
     This option is mutually exclusive with :option:`--bbox`.
 
-.. option:: --bbox west_long,south_lat,east_long,north_lat
+.. option:: --bbox <west_long,south_lat,east_long,north_lat>
 
     .. versionadded:: 8.0.0
 
@@ -170,6 +166,21 @@ The following control parameters can appear in any order:
     `south_lat` and `north_lat` in the [-90,90]. `west_long` is generally lower than
     `east_long`, except in the case where the area of interest crosses the antimeridian.
 
+.. option:: --authority <name>
+
+    .. versionadded:: 8.0.0
+
+    This option can be used to restrict the authority of coordinate operations
+    looked up in the database. When not specified, coordinate
+    operations from any authority will be searched, with the restrictions set
+    in the ``authority_to_authority_preference`` database table related to the authority
+    of the source/target CRS themselves.
+    If authority is set to ``any``, then coordinate operations from any authority will be searched
+    If authority is a non-empty string different of ``any``, then coordinate operations
+    will be searched only in that authority namespace (e.g ``EPSG``).
+
+    This option is mutually exclusive with :option:`--bbox`.
+
 .. only:: man
 
     The *+opt* run-line arguments are associated with cartographic
diff --git a/docs/source/development/reference/functions.rst b/docs/source/development/reference/functions.rst
index cc29743c..32902916 100644
--- a/docs/source/development/reference/functions.rst
+++ b/docs/source/development/reference/functions.rst
@@ -182,7 +182,19 @@ paragraph for more details.
     This is the same as :c:func:`proj_create_crs_to_crs` except that the source and
     target CRS are passed as PJ* objects which must of the CRS variety.
 
-    :param `options`: should be set to NULL currently.
+    :param `options`: a list of NUL terminated options, or NULL.
+
+    The list of supported options is:
+
+    - AUTHORITY=name: to restrict the authority of coordinate operations
+      looked up in the database. When not specified, coordinate
+      ``operations from any authority`` will be searched, with the restrictions set
+      in the authority_to_authority_preference database table related to the authority
+      of the source/target CRS themselves.
+      If authority is set to "any", then coordinate operations from any authority will be searched
+      If authority is a non-empty string different of ``any``, then coordinate operations
+      will be searched only in that authority namespace (e.g ``EPSG``).
+
 
 .. doxygenfunction:: proj_normalize_for_visualization
    :project: doxygen_api