document new QTPLUGIN magic

Change-Id: Ia12f55a3e6bd670cb95c21c8f896b0451dd63693
Reviewed-by: Fawzi Mohamed <fawzi.mohamed@digia.com>
Reviewed-by: Leena Miettinen <riitta-leena.miettinen@digia.com>
Reviewed-by: Oswald Buddenhagen <oswald.buddenhagen@digia.com>

qmake/doc/src/qmake-manual.qdoc

@@ -2133,6 +2133,16 @@
     linked with an application so that they are available as built-in
     resources.
 
+    qmake automatically adds the plugins that are typically needed
+    by the used Qt modules (see \c QT).
+    The defaults are tuned towards an optimal out-of-the-box experience.
+    See \l{Static Plugins} for a list of available plugins, and ways
+    to override the automatic linking.
+
+    This variable currently has no effect when linking against a
+    shared/dynamic build of Qt, or when linking libraries.
+    It may be used for deployment of dynamic plugins at a later time.
+
     \target QT_VERSION_variable
     \section1 QT_VERSION
 

src/corelib/doc/snippets/code/doc_src_plugins-howto.pro

@@ -43,7 +43,7 @@ CONFIG += release
 #! [3]
 
 #! [4]
-CONFIG += qpa_minimal_plugin
+QTPLUGIN.platforms = qminimal
 #! [4]
 
 #! [5]
@@ -53,7 +53,7 @@ QTPLUGIN     += qjpeg \
 #! [5]
 
 #! [6]
-CONFIG -= import_qpa_plugin
+QTPLUGIN.platforms = -
 #! [6]
 
 #! [7]

src/corelib/doc/src/plugins-howto.qdoc

@@ -266,20 +266,46 @@
 
     To link those plugins statically, you need to add
     the required plugins to your build using \c QTPLUGIN.
-    Q_IMPORT_PLUGIN() macros are also needed in application code,
-    but those are automatically generated by qmake and added to
-    your application project.
 
     In the \c .pro file for your application, you need the following
     entry:
 
     \snippet code/doc_src_plugins-howto.pro 5
 
+    qmake automatically adds the plugins to QTPLUGIN that are typically
+    needed by the used Qt modules (see \c QT), while more specialized
+    plugins need to be added manually.
+    The default list of automatically added plugins can be overridden
+    per type.
+    For example, to link the minimal plugin instead of the default Qt
+    platform adaptation plugin, use:
+
+    \snippet code/doc_src_plugins-howto.pro 4
+
+    If you want neither the default nor the minimal QPA plugin to be
+    linked automatically, use:
+
+    \snippet code/doc_src_plugins-howto.pro 6
+
+    The defaults are tuned towards an optimal out-of-the-box experience,
+    but may unnecessarily bloat the application.
+    It is recommended to inspect the linker command line built by qmake
+    and eliminate unnecessary plugins.
+
+    \section2 Details of Linking Static Plugins
+
+    To cause static plugins actually being linked and instantiated,
+    Q_IMPORT_PLUGIN() macros are also needed in application code,
+    but those are automatically generated by qmake and added to
+    your application project.
+
     If you do not want all plugins added to QTPLUGIN to be automatically
     linked, remove \c import_plugins from the \c CONFIG variable:
 
     \snippet code/doc_src_plugins-howto.pro 7
 
+    \section2 Creating Static Plugins
+
     It is also possible to create your own static plugins, by
     following these steps:
 
@@ -298,17 +324,6 @@
     to make sure that the \c{QT_STATICPLUGIN} preprocessor macro is
     defined.
 
-    The default Qt platform adaptation plugin is automatically added to QTPLUGIN
-    in static builds. If you want to add the minimal plugin instead, add \c qpa_minimal_plugin
-    to \c CONFIG:
-
-    \snippet code/doc_src_plugins-howto.pro 4
-
-    If you want neither the default nor the minimal QPA plugin to be linked automatically,
-    remove \c import_qpa_plugin from \c CONFIG:
-
-    \snippet code/doc_src_plugins-howto.pro 6
-
     \section1 Deploying and Debugging Plugins
 
     The \l{Deploying Plugins} document covers the process of deploying