Doc: Add overview page to LinguistTools

Provide a landing page for LinguistTools macros, making it easier
to navigate between them in the breadcrumb menu. Also add details on
where the respective command is found.

Task-number: QTBUG-96239
Pick-to: 6.2 6.4
Change-Id: Ib74c6cab2215900e1b43ea26fce293ea74d154f0
Reviewed-by: Jörg Bornemann <joerg.bornemann@qt.io>

3 files changed, 36 insertions, 6 deletions

diff --git a/src/linguist/linguist/doc/cmake-macros.qdoc b/src/linguist/linguist/doc/cmake-macros.qdoc
index c23cd9e63..432667696 100644
--- a/src/linguist/linguist/doc/cmake-macros.qdoc
+++ b/src/linguist/linguist/doc/cmake-macros.qdoc
@@ -2,14 +2,30 @@
 // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
 
 /*!
+\group cmake-commands-qtlinguisttools
+\title CMake Commands in Qt6 LinguistTools
+
+The following CMake commands are defined when Qt6::LinguistTools is loaded, for instance
+with
+
+\code
+find_package(Qt6 REQUIRED COMPONENTS LinguistTools)
+\endcode
+
+\sa{CMake Command Reference}
+*/
+
+/*!
 \page qtlinguist-cmake-qt-add-translation.html
-\ingroup cmake-macros-qtlinguisttools
+\ingroup cmake-commands-qtlinguisttools
 
 \title qt_add_translation
 \target qt6_add_translation
 
 \summary {Compiles Qt Linguist .ts files into .qm files.}
 
+\include cmake-find-package-linguisttools.qdocinc
+
 \warning This function is deprecated. Consider using the target-based
 functions \l{qt6_add_lrelease} or \l{qt6_add_translations} instead.
 
@@ -56,13 +72,15 @@ sub-directory:
 
 /*!
 \page qtlinguist-cmake-qt-create-translation.html
-\ingroup cmake-macros-qtlinguisttools
+\ingroup cmake-commands-qtlinguisttools
 
 \title qt_create_translation
 \target qt6_create_translation
 
 \summary {Sets up the Qt Linguist translation toolchain.}
 
+\include cmake-find-package-linguisttools.qdocinc
+
 \warning This function is deprecated. Consider using the target-based
 functions \l{qt6_add_lupdate} or \l{qt6_add_translations} instead.
 
@@ -108,13 +126,15 @@ files in the build directory:
 
 /*!
 \page qtlinguist-cmake-qt-add-lupdate.html
-\ingroup cmake-macros-qtlinguisttools
+\ingroup cmake-commands-qtlinguisttools
 
 \title qt_add_lupdate
 \target qt6_add_lupdate
 
 \summary {Add targets to generate or update Qt Linguist .ts files.}
 
+\include cmake-find-package-linguisttools.qdocinc
+
 \cmakecommandsince 6.2
 
 \section1 Synopsis
@@ -182,13 +202,15 @@ Add the targets \c{myapp_lupdate} and \c{update_translations} for updating the
 
 /*!
 \page qtlinguist-cmake-qt-add-lrelease.html
-\ingroup cmake-macros-qtlinguisttools
+\ingroup cmake-commands-qtlinguisttools
 
 \title qt_add_lrelease
 \target qt6_add_lrelease
 
 \summary {Add targets to transform Qt Linguist .ts files into .qm files.}
 
+\include cmake-find-package-linguisttools.qdocinc
+
 \cmakecommandsince 6.2
 
 \section1 Synopsis
@@ -268,13 +290,15 @@ files.
 
 /*!
 \page qtlinguist-cmake-qt-add-translations.html
-\ingroup cmake-macros-qtlinguisttools
+\ingroup cmake-commands-qtlinguisttools
 
 \title qt_add_translations
 \target qt6_add_translations
 
 \summary {Add targets to update and transform Qt Linguist .ts files into .qm files.}
 
+\include cmake-find-package-linguisttools.qdocinc
+
 \cmakecommandsince 6.2
 
 \section1 Synopsis
diff --git a/src/linguist/linguist/doc/includes/cmake-find-package-linguisttools.qdocinc b/src/linguist/linguist/doc/includes/cmake-find-package-linguisttools.qdocinc
new file mode 100644
index 000000000..25e98107b
--- /dev/null
+++ b/src/linguist/linguist/doc/includes/cmake-find-package-linguisttools.qdocinc
@@ -0,0 +1,6 @@
+The command is defined in the \c LinguistTools component of the \c Qt6 package.
+Load the package with:
+
+\code
+find_package(Qt6 REQUIRED COMPONENTS LinguistTools)
+\endcode
diff --git a/src/linguist/linguist/doc/src/linguist-manual.qdoc b/src/linguist/linguist/doc/src/linguist-manual.qdoc
index d73dad166..4511e9225 100644
--- a/src/linguist/linguist/doc/src/linguist-manual.qdoc
+++ b/src/linguist/linguist/doc/src/linguist-manual.qdoc
@@ -44,7 +44,7 @@
     \li \l{Qt Linguist Manual: Developers}{Developers}
     \li \l{Qt Linguist Manual: TS File Format}{TS File Format}
     \li \l{Qt Linguist Manual: Text ID Based Translations}{Text ID Based Translations}
-    \li \l{cmake-macros-qtlinguisttools}{CMake Commands}
+    \li \l{CMake Commands in Qt6 LinguistTools}{CMake Commands}
     \endlist
 
 */