Doc: add generic config option description from Trac [skip travis] [s…

…kip appveyor]

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

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