Doc improvements regarding recomandation not to alter official registries and use auxiliary databases

2 files changed, 33 insertions, 0 deletions

diff --git a/docs/source/apps/projinfo.rst b/docs/source/apps/projinfo.rst
index bb4f831d..6c090494 100644
--- a/docs/source/apps/projinfo.rst
+++ b/docs/source/apps/projinfo.rst
@@ -302,6 +302,20 @@ The following control parameters can appear in any order:
 
     Identifier to assign to the object (for SQL output).
 
+    It is strongly recommended that new objects should not be added in common
+    registries, such as ``EPSG``, ``ESRI``, ``IAU``, etc.
+    Users should use a custom authority name instead. If a new object should be
+    added to the official EPSG registry, users are invited to follow the
+    procedure explained at https://epsg.org/dataset-change-requests.html.
+
+    Combined with :option:`--dump-db-structure`, users can create
+    auxiliary databases, instead of directly modifying the main proj.db database.
+    See the :ref:`example how to export to an auxiliary database <projinfo_aux_db_example>`.
+
+    Those auxiliary databases can be specified through
+    :cpp:func:`proj_context_set_database_path` or the :envvar:`PROJ_AUX_DB`
+    environment variable.
+
 .. option:: --c-ify
 
     For developers only. Modify the string output of the utility so that it
@@ -473,6 +487,8 @@ Output:
         }
     }
 
+.. _projinfo_aux_db_example:
+
 4. Exporting the SQL statements to insert a new CRS in an auxiliary database.
 
 .. code-block:: console
diff --git a/src/iso19111/c_api.cpp b/src/iso19111/c_api.cpp
index 2a655e51..1462dd31 100644
--- a/src/iso19111/c_api.cpp
+++ b/src/iso19111/c_api.cpp
@@ -310,6 +310,12 @@ void proj_context_set_autoclose_database(PJ_CONTEXT *ctx, int autoclose) {
  * definition database ("proj.db"), and potentially auxiliary databases with
  * same structure.
  *
+ * Starting with PROJ 8.1, if the auxDbPaths parameter is an empty array,
+ * the PROJ_AUX_DB environment variable will be used, if set.
+ * It must contain one or several paths. If several paths are
+ * provided, they must be separated by the colon (:) character on Unix, and
+ * on Windows, by the semi-colon (;) character.
+ *
  * @param ctx PROJ context, or NULL for default context
  * @param dbPath Path to main database, or NULL for default.
  * @param auxDbPaths NULL-terminated list of auxiliary database filenames, or
@@ -8899,6 +8905,17 @@ void proj_string_destroy(char *str) { free(str); }
  *
  * proj_insert_object_session_create() may have been called previously.
  *
+ * It is strongly recommended that new objects should not be added in common
+ * registries, such as "EPSG", "ESRI", "IAU", etc. Users should use a custom
+ * authority name instead. If a new object should be
+ * added to the official EPSG registry, users are invited to follow the
+ * procedure explainted at https://epsg.org/dataset-change-requests.html.
+ *
+ * Combined with proj_context_get_database_structure(), users can create
+ * auxiliary databases, instead of directly modifying the main proj.db database.
+ * Those auxiliary databases can be specified through proj_context_set_database_path()
+ * or the PROJ_AUX_DB environment variable.
+ *
  * @param ctx PROJ context, or NULL for default context
  * @param session The insertion session. May be NULL if a single object must be
  *                inserted.