From 559bfd0bbd49b78041a61c1bb1608a83ecdae7b2 Mon Sep 17 00:00:00 2001
From: Peter Kokot <peterkokot@gmail.com>
Date: Sun, 12 Oct 2025 03:27:00 +0200
Subject: [PATCH] CPackIFWConfigureFile: Update documentation

- Extended command description.
- Added basic "Examples" section.
- Added "See Also" section.
---
 Modules/CPackIFWConfigureFile.cmake | 91 +++++++++++++++++++++++++++--
 1 file changed, 85 insertions(+), 6 deletions(-)

diff --git a/Modules/CPackIFWConfigureFile.cmake b/Modules/CPackIFWConfigureFile.cmake
index f92fc108d2..bed78f9930 100644
--- a/Modules/CPackIFWConfigureFile.cmake
+++ b/Modules/CPackIFWConfigureFile.cmake
@@ -7,8 +7,8 @@ CPackIFWConfigureFile
 
 .. versionadded:: 3.8
 
-This module defines :command:`configure_file` similar command to
-configure file templates prepared in QtIFW/SDK/Creator style.
+This module provides a command similar to :command:`configure_file` for
+configuring file templates prepared in QtIFW/SDK/Creator style.
 
 Load this module in a CMake project with:
 
@@ -19,21 +19,100 @@ Load this module in a CMake project with:
 Commands
 ^^^^^^^^
 
-The module defines the following commands:
+This module provides the following command:
 
 .. command:: cpack_ifw_configure_file
 
-  Copy a file to another location and modify its contents.
+  Copies a file template to output file and substitutes variable values
+  referenced as ``%{VAR}`` or ``%VAR%`` from the input file template
+  content:
 
   .. code-block:: cmake
 
     cpack_ifw_configure_file(<input> <output>)
 
-  Copies an ``<input>`` file to an ``<output>`` file and substitutes variable
-  values referenced as ``%{VAR}`` or ``%VAR%`` in the input file content.
+  ``<input>``
+    Input file template.  If given as a relative path, it is interpreted as
+    relative to the current source directory
+    (:variable:`CMAKE_CURRENT_SOURCE_DIR`).
+
+  ``<output>``
+    Output file.  If given as a relative path, it is interpreted as relative
+    to the current binary directory (:variable:`CMAKE_CURRENT_BINARY_DIR`).
+
+  Qt Installer Framework (QtIFW) uses ``@`` characters for embedding
+  predefined variables (``TargetDir``, ``StartMenuDir``, etc.) in Qt
+  installer scripts:
+
+  .. code-block:: javascript
+    :caption: ``example.qs``
+
+    component.addOperation(
+      "CreateShortcut",
+      "@TargetDir@/example.com.html",
+      "@StartMenuDir@/Example Web Site.lnk"
+    );
+
+  The purpose of this command is to preserve the QtIFW predefined variables
+  containing the ``@`` characters (``@VAR@``), and instead use the ``%``
+  characters for template placeholders (``%VAR%``, ``%{VAR}``) in
+  Qt/IFW/SDK/Creator templates.  The :command:`configure_file` command
+  would otherwise replace all variable references containing the ``@``
+  characters.
+
   Each variable reference will be replaced with the current value of the
   variable, or the empty string if the variable is not defined.
 
+Examples
+^^^^^^^^
+
+In the following example this module is used to create an IFW component
+script from a given template file ``qt.tools.foo.qs.in``, where
+``%FOO_DOC_DIR%`` variable reference will be replaced by the values of
+the ``FOO_DOC_DIR`` CMake variable.
+
+.. code-block:: cmake
+  :caption: ``CMakeLists.txt``
+
+  cmake_minimum_required(VERSION 3.8)
+
+  project(Foo)
+
+  # ...
+
+  include(CPackIFWConfigureFile)
+
+  set(FOO_DOC_DIR "doc/foo")
+
+  cpack_ifw_configure_file(qt.tools.foo.qs.in qt.tools.foo.qs)
+
+.. code-block:: javascript
+  :caption: ``qt.tools.foo.qs.in``
+
+  function Component()
+  {
+  }
+
+  Component.prototype.createOperations = function()
+  {
+    if (installer.value("os") === "win") {
+      component.addOperation(
+        "CreateShortcut",
+        "@TargetDir@/%FOO_DOC_DIR%/example.com.html",
+        "@StartMenuDir@/Example Web Site.lnk"
+      );
+    }
+
+    component.createOperations();
+  }
+
+  // ...
+
+See Also
+^^^^^^^^
+
+* The :cpack_gen:`CPack IFW Generator`.
+* The :module:`CPackIFW` module.
 #]=======================================================================]
 
 if(NOT DEFINED CPackIFWConfigureFile_CMake_INCLUDED)