diff --git a/gdal/doc/source/user/configoptions.rst b/gdal/doc/source/user/configoptions.rst
new file mode 100644
index 000000000000..2719637937d6
--- /dev/null
+++ b/gdal/doc/source/user/configoptions.rst
@@ -0,0 +1,64 @@
+.. configoptions:
+
+================================================================================
+Configuration options
+================================================================================
+
+This page discussed runtime configuration options for GDAL, and is distinct from
+options to the build-time configure script. Runtime configuration options apply
+on all platforms, and are evaluated at runtime. They can be set programmatically,
+by commandline switches or in the environment by the user.
+
+Configuration optoins are normally used to alter the default behavior of GDAL/OGR
+drivers and in some cases the GDAL/OGR core. They are essentially global
+variables the user can set.
+
+How to set configuration options ?
+----------------------------------
+
+One example of a config option is the GDAL_CACHEMAX option. It controls the size
+of the GDAL block cache, in megabytes. It can be set in the environment on Unix
+(bash/bourne) shell like this:
+
+::
+
+    export GDAL_CACHEMAX=64
+
+In a DOS/Windows command shell it is done like this:
+
+::
+
+    set GDAL_CACHEMAX=64
+
+It can also be set on the commandline for most GDAL and OGR utilities with the
+``--config`` switch, though in a few cases these switches are not evaluated in
+time to affect behavior.
+
+::
+
+    gdal_translate --config GDAL_CACHEMAX 64 in.tif out.tif
+
+In C/C++ configuration switches can be set programmatically with
+:cpp:func:`CPLSetConfigOption`:
+
+.. code-block:: c
+
+    #include "cpl_conv.h"
+    ...
+        CPLSetConfigOption( "GDAL_CACHEMAX", "64" );
+
+Normally a configuration option applies to all threads active in a program, but
+they can be limited to only the current thread with
+:cpp:func:`CPLSetThreadLocalConfigOption`
+
+.. code-block:: c
+
+    CPLSetThreadLocalConfigOption( "GTIFF_DIRECT_IO", "YES" );
+
+For boolean options, the values YES, TRUE or ON can be used to turn the option on;
+NO, FALSE or OFF to turn it off.
+
+List of configuration options and where they apply
+--------------------------------------------------
+
+.. include:: configoptions_index_generated.rst
diff --git a/gdal/doc/source/user/configoptions_index.rst b/gdal/doc/source/user/configoptions_index.rst
deleted file mode 100644
index 6e20c9638d06..000000000000
--- a/gdal/doc/source/user/configoptions_index.rst
+++ /dev/null
@@ -1,9 +0,0 @@
-.. configoptions_index:
-
-================================================================================
-Index of configuration options
-================================================================================
-
-List of configuration options and where they apply:
-
-.. include:: configoptions_index_generated.rst
diff --git a/gdal/doc/source/user/index.rst b/gdal/doc/source/user/index.rst
index 6692675b21c8..de7c977073eb 100644
--- a/gdal/doc/source/user/index.rst
+++ b/gdal/doc/source/user/index.rst
@@ -14,4 +14,4 @@ User oriented documentation
    ogr_sql_sqlite_dialect
    GDAL Virtual File Systems <virtual_file_systems>
    ogr_feature_style
-   configoptions_index
+   configoptions