Adding qmake doc details for generating rc files

The qmake documentation was missing details about when rc files
are autogenerated under Windows.

A new section about windows rc files is added in
"Platform Notes".

Some hints are added in section VERSION.
Link to new "Platform Notes" section is added.
The VERSION example is extended, too.

Link to new "Platform Notes" section is added to RC_ICONS as
this is a rc file generator trigger, too.

The section "Building an Application" gets a link to the
"Platform Notes" and the system variable list was shortened
by all entries relevant to windows only rc files.

Many links to VERSION were not resolved by qdoc. Adds
explicit linkage.

Change-Id: Iacbc34d53a6bafa6e7658aaee8c751f32e978177
Reviewed-by: Leena Miettinen <riitta-leena.miettinen@theqtcompany.com>
Reviewed-by: Oswald Buddenhagen <oswald.buddenhagen@theqtcompany.com>

2 files changed, 90 insertions, 33 deletions

diff --git a/qmake/doc/snippets/code/doc_src_qmake-manual.pro b/qmake/doc/snippets/code/doc_src_qmake-manual.pro
index be5f979e39..335fa6f97e 100644
--- a/qmake/doc/snippets/code/doc_src_qmake-manual.pro
+++ b/qmake/doc/snippets/code/doc_src_qmake-manual.pro
@@ -333,7 +333,8 @@ win32:UI_DIR = c:/myproject/ui
 
 
 #! [57]
-VERSION = 1.2.3
+win32:VERSION = 1.2.3.4 # major.minor.patch.build
+else:VERSION = 1.2.3    # major.minor.patch
 #! [57]
 
 
diff --git a/qmake/doc/src/qmake-manual.qdoc b/qmake/doc/src/qmake-manual.qdoc
index 8c3dc46015..56d9dd35ae 100644
--- a/qmake/doc/src/qmake-manual.qdoc
+++ b/qmake/doc/src/qmake-manual.qdoc
@@ -763,9 +763,55 @@
 
     \section1 Windows
 
-    Features specific to this platform include support for creating Visual
-    Studio project files and handling manifest files when deploying Qt
-    applications developed using Visual Studio 2005, or later.
+    Features specific to this platform include support for Windows resource
+    files (provided or auto-generated), creating Visual Studio project files,
+    and handling manifest files when deploying Qt applications developed
+    using Visual Studio 2005, or later.
+
+    \section2 Adding Windows Resource Files
+
+    This section describes how to handle a Windows resource file with
+    qmake to have it linked to an application executable (EXE) or dynamic
+    link library (DLL). qmake can optionally auto-generate a suitably
+    filled Windows resource file.
+
+    A linked Windows resource file may contain many elements that can
+    be accessed by its EXE or DLL. However, the
+    \l{The Qt Resource System}{Qt resource system} should be used for
+    accessing linked-in resources in a platform-independent way. But
+    some standard elements of the linked Windows resource file are
+    accessed by Windows itself. For example, in Windows explorer the
+    version tab of the file properties is filled by resource elements.
+    In addition, the program icon of the EXE is read from these elements.
+    So it is good practice for a Qt created Windows EXE or DLL to use
+    both techniques at the same time: link platform-independent resources
+    via the \l{The Qt Resource System}{Qt resource system} and add Windows
+    specific resources via a Windows resource file.
+
+    Typically, a resource-definition script (.rc file) is compiled to a
+    Windows resource file. Within the Microsoft toolchain, the RC tool
+    generates a .res file, which can be linked with the Microsoft linker
+    to an EXE or DLL. The MinGW toolchain uses the windres tool to generate
+    an .o file that can be linked with the MinGW linker to an EXE or DLL.
+
+    The optional auto-generation of a suitably filled .rc file by qmake is
+    triggered by setting at least one of the system variables \l{VERSION}
+    and \l{RC_ICONS}. The generated .rc file is automatically compiled and
+    linked. Elements that are added to the .rc file are defined by the system
+    variables \l{QMAKE_TARGET_COMPANY}, \l{QMAKE_TARGET_DESCRIPTION},
+    \l{QMAKE_TARGET_COPYRIGHT}, \l{QMAKE_TARGET_PRODUCT}, \l{RC_CODEPAGE},
+    \l{RC_ICONS}, \l{RC_LANG},and \l{VERSION}.
+
+    If these elements are not sufficient, qmake has the two system variables
+    \l{RC_FILE} and \l{RES_FILE} that point directly to an externally created
+    .rc or .res file. By setting one of these variables, the specified file
+    is linked to the EXE or DLL.
+
+    \note The generation of the .rc file by qmake is blocked, if \l{RC_FILE}
+    or \l{RES_FILE} is set. In this case, no further changes are made to the
+    given .rc file or the .res or .o file by qmake; the variables pertaining
+    to .rc file generation have no effect.
+
 
     \section2 Creating Visual Studio Project Files
 
@@ -2132,34 +2178,35 @@
     \target QMAKE_TARGET_COMPANY
     \section1 QMAKE_TARGET_COMPANY
 
-    Windows only. Specifies the company for the project target, this is used where
-    applicable for putting the company name in the application's properties. This is
-    only utilized if the VERSION or RC_ICONS variable is set and the RC_FILE and RES_FILE
-    variables are not set.
+    Windows only. Specifies the company for the project target; this is
+    used where applicable for putting the company name in the application's
+    properties. This is only utilized if the \l{VERSION} or \l{RC_ICONS}
+    variable is set and the \l{RC_FILE} and \l{RES_FILE} variables are not set.
 
     \target QMAKE_TARGET_DESCRIPTION
     \section1 QMAKE_TARGET_DESCRIPTION
 
-    Windows only. Specifies the description for the project target, this is used where
-    applicable for putting the description in the application's properties. This is only
-    utilized if the VERSION or RC_ICONS variable is set and the RC_FILE and RES_FILE variables
-    are not set.
+    Windows only. Specifies the description for the project target; this is
+    used where applicable for putting the description in the application's
+    properties. This is only utilized if the \l{VERSION} or \l{RC_ICONS}
+    variable is set and the \l{RC_FILE} and \l{RES_FILE} variables are not set.
 
     \target QMAKE_TARGET_COPYRIGHT
     \section1 QMAKE_TARGET_COPYRIGHT
 
-    Windows only. Specifies the copyright information for the project target, this is used where
-    applicable for putting the copyright information in the application's properties. This is only
-    utilized if the VERSION or RC_ICONS variable is set and the RC_FILE and RES_FILE variables
+    Windows only. Specifies the copyright information for the project target;
+    this is used where applicable for putting the copyright information in the
+    application's properties. This is only utilized if the \l{VERSION} or
+    \l{RC_ICONS} variable is set and the \l{RC_FILE} and \l{RES_FILE} variables
     are not set.
 
     \target QMAKE_TARGET_PRODUCT
     \section1 QMAKE_TARGET_PRODUCT
 
-    Windows only. Specifies the product for the project target, this is used where
-    applicable for putting the product in the application's properties. This is only utilized if
-    the VERSION or RC_ICONS variable is set and the RC_FILE and RES_FILE variables
-    are not set.
+    Windows only. Specifies the product for the project target; this is used
+    where applicable for putting the product in the application's properties.
+    This is only utilized if the \l{VERSION} or \l{RC_ICONS} variable is set
+    and the \l{RC_FILE} and \l{RES_FILE} variables are not set.
 
     \section1 QT
 
@@ -2263,22 +2310,24 @@
     \target RC_CODEPAGE
     \section1 RC_CODEPAGE
 
-    Windows only. Specifies the codepage that should be specified in a generated rc file. This is
-    only utilized if the VERSION or RC_ICONS variable is set and the RC_FILE and RES_FILE variables
-    are not set.
+    Windows only. Specifies the codepage that should be specified in a generated
+    .rc file. This is only utilized if the \l{VERSION} or \l{RC_ICONS} variable
+    is set and the \l{RC_FILE} and \l{RES_FILE} variables are not set.
 
     \target RC_ICONS
     \section1 RC_ICONS
 
-    Windows only. Specifies the icons that should be included into a generated rc file, this
-    is only utilized if the RC_FILE and RES_FILE variable are not set.
+    Windows only. Specifies the icons that should be included into a generated
+    .rc file. This is only utilized if the \l{RC_FILE} and \l{RES_FILE} variable
+    are not set. More details about the generation of .rc files can be found in
+    the \l{Platform Notes}.
 
     \target RC_LANG
     \section1 RC_LANG
 
-    Windows only. Specifies the language that should be specified in a generated rc file. This is
-    only utilized if the VERSION or RC_ICONS variable is set and the RC_FILE and RES_FILE variables
-    are not set.
+    Windows only. Specifies the language that should be specified in a generated
+    .rc file. This is only utilized if the \l{VERSION} or \l{RC_ICONS} variable
+    is set and the \l{RC_FILE} and \l{RES_FILE} variables are not set.
 
     \section1 RC_INCLUDEPATH
 
@@ -2477,8 +2526,16 @@
     \target VERSION
     \section1 VERSION
 
-    Specifies the version number of the application if the \c app \l{#TEMPLATE}{template} is
-    specified or the version number of the library if the \c lib template is specified.
+    Specifies the version number of the application if the \c app
+    \l{#TEMPLATE}{template} is specified or the version number of
+    the library if the \c lib template is specified.
+
+    On Windows, triggers auto-generation of an .rc file if the \l{RC_FILE}
+    and \l{RES_FILE} variables are not set. The generated .rc file will have
+    the FILEVERSION and PRODUCTVERSION entries filled with major, minor, patch
+    level, and build number. Each number must be in the range from 0 to 65535.
+    More details about the generation of .rc files can be found in the
+    \l{Platform Notes}.
 
     For example:
 
@@ -4648,7 +4705,9 @@
 
     When using this template, the following qmake
     system variables are recognized. You should use these in your .pro file to
-    specify information about your application.
+    specify information about your application. For additional
+    platform-dependent system variables, you could have a look at the
+    \l{Platform Notes}.
 
     \list
     \li \l{HEADERS} - A list of header files for the application.
@@ -4670,9 +4729,6 @@
     \li \l{VPATH} - The search path to find supplied files.
     \li \l{DEF_FILE} - Windows only: A .def file to be linked against for the
         application.
-    \li \l{RC_FILE} - Windows only: A resource file for the application.
-    \li \l{RES_FILE} - Windows only: A resource file to be linked against for
-        the application.
     \endlist
 
     You only need to use the system variables that you have values for. For