Doc: clarify that -if does not relax potential restrictions on file e…

…xtensions (fixes #8590)
OSGeo · Dec 10, 2023 · d086421 · d086421
1 parent beb8f49
commit d086421
Show file tree

Hide file tree

Showing 4 changed files with 11 additions and 3 deletions.
diff --git a/doc/source/programs/ogr2ogr.rst b/doc/source/programs/ogr2ogr.rst
@@ -22,7 +22,7 @@ Synopsis
             [-preserve_fid] [-fid <FID>] [-limit <nb_features>]
             [-spat <xmin> <ymin> <xmax> <ymax>] [-spat_srs <srs_def>] [-geomfield <field>]
             [-a_srs <srs_def>] [-t_srs <srs_def>] [-s_srs <srs_def>] [-ct <string>]
-            [-f <format_name>] [-overwrite] [-dsco <NAME>=<VALUE>]...
+            [-if <input_drv_name>] [-f <format_name>] [-overwrite] [-dsco <NAME>=<VALUE>]...
             [-lco <NAME>=<VALUE>]... [-nln <name>]
             [-nlt <type>|PROMOTE_TO_MULTI|CONVERT_TO_LINEAR|CONVERT_TO_CURVE]
             [-dim XY|XYZ|XYM|XYZM|<layer_dim>]
@@ -67,6 +67,8 @@ output coordinate system or even reprojecting the features during translation.
 
 .. include:: options/help_and_help_general.rst
 
+.. include:: options/if.rst
+
 .. option:: -f <format_name>
 
     Output file format name, e.g. ``ESRI Shapefile``, ``MapInfo File``,

diff --git a/doc/source/programs/options/formats_raster.rst b/doc/source/programs/options/formats_raster.rst
@@ -14,6 +14,8 @@
     which determines the order in which they are successively probed when opening
     a dataset. Most of the time, this order does not matter, but in some situations,
     several drivers may recognize the same file. The ``-if`` option of some utilities
-    can be specified to ask to use a particular driver to open the dataset.
+    can be specified to restrict opening the dataset with a subset of drivers (generally one).
+    Note that it does not force those drivers to open the dataset. In particular,
+    some drivers have requirements on file extensions.
     Alternatively, the :config:`GDAL_SKIP` configuration option can also be used
     to exclude one or several drivers.
diff --git a/doc/source/programs/options/formats_vector.rst b/doc/source/programs/options/formats_vector.rst
@@ -13,6 +13,8 @@
     which determines the order in which they are successively probed when opening
     a dataset. Most of the time, this order does not matter, but in some situations,
     several drivers may recognize the same file. The ``-if`` option of some utilities
-    can be specified to ask to use a particular driver to open the dataset.
+    can be specified to restrict opening the dataset with a subset of drivers (generally one).
+    Note that it does not force those drivers to open the dataset. In particular,
+    some drivers have requirements on file extensions.
     Alternatively, the :config:`GDAL_SKIP` configuration option can also be used
     to exclude one or several drivers.
diff --git a/doc/source/programs/options/if.rst b/doc/source/programs/options/if.rst
@@ -4,5 +4,7 @@
     not necessary to specify it, but it can be used to skip automatic driver
     detection, when it fails to select the appropriate driver.
     This option can be repeated several times to specify several candidate drivers.
+    Note that it does not force those drivers to open the dataset. In particular,
+    some drivers have requirements on file extensions.
 
     .. versionadded:: 3.2