From e055120820bf3a18387599d2d4e19939255d2a81 Mon Sep 17 00:00:00 2001 From: Sze Howe Koh Date: Thu, 17 Nov 2022 22:46:25 +0800 Subject: Doc: Restructure Linguist examples for clarity The main goal is to show the qmake vs. CMake workflows side-by-side, for easier comparison. Previously, the entire CMake workflow was inserted into the middle of the qmake workflow. Other changes: * Updated the console snippets to work with all CMake generators, not just Makefiles. * Removed a suggestion to manually craft a Makefile. * Fixed a typo. Pick-to: 6.5 6.4 Change-Id: I3c5f3a56957160eddff2f0d6034e37c886966e62 Reviewed-by: Leena Miettinen --- .../doc/snippets/doc_src_examples_arrowpad.qdoc | 6 ++++- .../doc/snippets/doc_src_examples_hellotr.qdoc | 2 +- examples/linguist/doc/src/arrowpad.qdoc | 24 ++++++++++-------- examples/linguist/doc/src/hellotr.qdoc | 29 ++++++++++++---------- 4 files changed, 36 insertions(+), 25 deletions(-) (limited to 'examples') diff --git a/examples/linguist/doc/snippets/doc_src_examples_arrowpad.qdoc b/examples/linguist/doc/snippets/doc_src_examples_arrowpad.qdoc index 93bbd3acf..6effaf7a8 100644 --- a/examples/linguist/doc/snippets/doc_src_examples_arrowpad.qdoc +++ b/examples/linguist/doc/snippets/doc_src_examples_arrowpad.qdoc @@ -1,6 +1,10 @@ // Copyright (C) 2016 The Qt Company Ltd. // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause +//! [0] +lupdate arrowpad.pro +//! [0] + //! [1] lrelease arrowpad.pro //! [1] @@ -13,5 +17,5 @@ setenv LANG fr //! [4] -make update_translations +cmake --build . --target update_translations //! [4] diff --git a/examples/linguist/doc/snippets/doc_src_examples_hellotr.qdoc b/examples/linguist/doc/snippets/doc_src_examples_hellotr.qdoc index 4143849d0..9cbf847a6 100644 --- a/examples/linguist/doc/snippets/doc_src_examples_hellotr.qdoc +++ b/examples/linguist/doc/snippets/doc_src_examples_hellotr.qdoc @@ -34,5 +34,5 @@ linguist hellotr_la.ts //! [4] //! [5] -make update_translations +cmake --build . --target update_translations //! [5] diff --git a/examples/linguist/doc/src/arrowpad.qdoc b/examples/linguist/doc/src/arrowpad.qdoc index dd19695c5..b18cfa666 100644 --- a/examples/linguist/doc/src/arrowpad.qdoc +++ b/examples/linguist/doc/src/arrowpad.qdoc @@ -12,29 +12,33 @@ We will use two translations, French and Dutch, although there is no effective limit on the number of possible translations that can be used - with an application. The relevant lines of \c arrowpad.pro are + with an application. + + When using qmake, the relevant lines in \c arrowpad.pro are: \snippet arrowpad/arrowpad.pro 0 \codeline \snippet arrowpad/arrowpad.pro 1 - Run \c lupdate; it should produce two identical message files - \c arrowpad_fr.ts and \c arrowpad_nl.ts. These files will contain all the source - texts marked for translation with \c tr() calls and their contexts. - - It is also possible to produce translations using the - \l{cmake-commands-qtlinguisttools}{Qt6::LinguistTools CMake commands}. - The relevant lines in \c CMakeLists.txt are: + When using CMake, the relevant lines in \c CMakeLists.txt are: \snippet arrowpad/CMakeLists.txt 0 \codeline \snippet arrowpad/CMakeLists.txt 1 - After configuring and building, the translations are produced by running: + Run \c lupdate. It should produce two identical message files + \c arrowpad_fr.ts and \c arrowpad_nl.ts. These files will contain all the source + texts marked for translation with \c tr() calls and their contexts. + + When using qmake, \c lupdate must be run manually: + + \snippet doc/snippets/doc_src_examples_arrowpad.qdoc 0 + + When using CMake, build the \c update_translations target to run \c lupdate: \snippet doc/snippets/doc_src_examples_arrowpad.qdoc 4 See the \l{Qt Linguist Manual} for more information about - translating Qt application. + translating Qt applications. \section1 Line by Line Walkthrough diff --git a/examples/linguist/doc/src/hellotr.qdoc b/examples/linguist/doc/src/hellotr.qdoc index 21b5e922e..3ef24ab71 100644 --- a/examples/linguist/doc/src/hellotr.qdoc +++ b/examples/linguist/doc/src/hellotr.qdoc @@ -58,8 +58,10 @@ \section1 Creating a Latin Message File - The first step is to create a project file, \c hellotr.pro, that lists - all the source files for the project: + The first step is to create a project file that lists + all the source files for the project. + + When using qmake, the relevant lines in \c hellotr.pro are: \snippet hellotr/hellotr.pro 0 \snippet hellotr/hellotr.pro 1 @@ -68,17 +70,11 @@ maintain. In this example, we just maintain one set of translations, namely Latin. - It is also possible to produce translations using the - \l{cmake-commands-qtlinguisttools}{Qt6::LinguistTools CMake commands}. - One needs to add the following to the \c CMakeLists.txt: + When using CMake, the relevant lines in \c CMakeLists.txt are: \snippet hellotr/CMakeLists.txt 0 \codeline \snippet hellotr/CMakeLists.txt 1 - After configuring and building, the translations are produced by running: - - \snippet doc/snippets/doc_src_examples_hellotr.qdoc 5 - Note that the file extension is \c .ts, not \c .qm. The \c .ts translation source format is designed for use during the application's development. Programmers or release managers run @@ -105,15 +101,22 @@ \c lupdate is used to create and update the message files (\c hellotr_la.ts in this case) to keep them in sync with the source code. It is safe to run \c lupdate at any time, as \c lupdate does not remove any - information. For example, you can put it in the makefile, so the TS - files are updated whenever the source changes. + information. + + Try running \c lupdate right now. - Try running \c lupdate right now, like this: + When using qmake, \c lupdate must be run manually: \snippet doc/snippets/doc_src_examples_hellotr.qdoc 0 (The \c -verbose option instructs \c lupdate to display messages that - explain what it is doing.) You should now have a file \c hellotr_la.ts in + explain what it is doing.) + + When using CMake, build the \c update_translations target to run \c lupdate: + + \snippet doc/snippets/doc_src_examples_hellotr.qdoc 5 + + You should now have a file \c hellotr_la.ts in the current directory, containing this: \snippet doc/snippets/doc_src_examples_hellotr.qdoc 1 -- cgit v1.2.1