Doc: Turn "Semantic Highlighting" into how-to topics

And move the general information to the Overview (or the Code
view docs in the QDS Manual).

Task-number: QTCREATORBUG-29361
Change-Id: Ib1d13f3d81d707691c84aa4241ed28662e2bc8ee
Reviewed-by: Eike Ziller <eike.ziller@qt.io>

doc/qtcreator/src/cmake/creator-projects-cmake.qdoc

@@ -247,7 +247,7 @@
 
     \title Complete CMake code
 
-    \QC uses \l{Generic Highlighting}{generic highlighting} to provide
+    \QC uses \l{Download highlight definitions}{generic highlighting} to provide
     code completion specific arguments for the CMake commands. For
     example, only source file properties are suggested for the
     \l {CMake: set_source_files_properties command}, not the test or

doc/qtcreator/src/editors/creator-editors-options.qdoc

@@ -35,16 +35,16 @@
         \li Set the \l{Font & Colors}{font preferences and
             apply color schemes} for syntax highlighting in
             \uicontrol {Font & Colors}.
-        \li Specify \l{Generic Highlighting}
+        \li Specify \l{Download highlight definitions}
             {definition files for syntax highlighting} for other types of files
              than C++ or QML in \uicontrol {Generic Highlighter}.
 
         \li Set \l{Indent text or code}{tabs, indentation, the handling of
             whitespace, and mouse operations} in \uicontrol Behavior.
 
-        \li Set various display properties, such as \l{Highlighting Blocks}
+        \li Set various display properties, such as \l{Highlight code blocks}
-            {highlighting} or \l{Folding Blocks}{folding} blocks or text
+            {highlighting} or folding code blocks and text wrapping in
-            wrapping in \uicontrol Display.
+            \uicontrol Display.
 
         \li Add, modify, and remove \l{Snippets}{code snippets} in
             \uicontrol Snippets.

doc/qtcreator/src/editors/creator-editors-writing-code.qdoc

@@ -23,12 +23,6 @@
     in-line error indicators while you are typing.
 
     \list
-        \li \l{Semantic Highlighting}
-
-            \QC enables you to write well formatted code by highlighting
-            code elements and blocks. You can use syntax highlighting
-            also for other types of files than C++ or QML.
-
         \li \l{Checking Code Syntax}
 
             \QC checks for errors when you write code and displays inline

doc/qtcreator/src/editors/creator-semantic-highlighting.qdoc

@@ -4,125 +4,138 @@
 /*!
     \page creator-highlighting.html
     \if defined(qtdesignstudio)
-    \previouspage creator-editor-functions.html
+    \previouspage qtquick-text-editor.html
     \else
-    \previouspage creator-coding-navigating.html
+    \previouspage creator-how-tos.html
     \endif
-    \nextpage creator-checking-code-syntax.html
 
-    \title Semantic Highlighting
+    \ingroup creator-how-to-edit
 
-    \QC understands the C++, QML, and JavaScript languages as code, not as plain
+    \title Download highlight definitions
-    text. It reads the source code, analyzes it, and highlights it based on the
-    semantic checks that it does for the following code elements:
 
-    \list
+    \QC uses the \l{https://api.kde.org/frameworks/syntax-highlighting/html/index.html}
-        \li Types (such as classes, structs, and type definitions)
+    {KSyntaxHighlighting} syntax highlighting engine with Kate syntax definitions.
-        \li Local variables
+    It comes with most of the commonly used Kate definitions, and you can download
-        \li Class fields
+    more definitions. For more information about the definition files, see
-        \li Virtual functions
+    \l{https://docs.kde.org/stable5/en/kate/katepart/highlight.html}
-    \endlist
-
-    To specify the color scheme to use for semantic highlighting, select
-    \preferences > \uicontrol {Text Editor} > \uicontrol {Font & Colors}.
-
-    \QC supports syntax highlighting also for other types of files than C++,
-    QML, or JavaScript.
-
-    \section1 Generic Highlighting
-
-    \QC uses
-    \l{https://api.kde.org/frameworks/syntax-highlighting/html/index.html}
-    {KSyntaxHighlighting}, which is the syntax highlighting engine for Kate
-    syntax definitions. \QC comes with most of the commonly used syntax files,
-    and you can download additional files. For more information about the
-    definition files, see
-    \l{https://docs.kde.org/trunk5/en/kate/katepart/highlight.html}
     {Working with Syntax Highlighting}.
 
     Font attributes that a syntax definition file explicitly specifies, such as
     bold, italic, underline, or strike through, are applied. Colors are applied
     if they are readable with \QC themes.
 
+    \section2 Remember preferred definitions
+
     If more than one highlight definition is available for the file that you
-    open for editing, the editor asks you to select the one to use. To save
+    open for editing, the editor asks you to select the one to use.
-    the selection, select \uicontrol {Remember My Choice}. To reset the
+
-    remembered definitions, select \preferences >
+    To save the selection, select \uicontrol {Remember My Choice}.
-    \uicontrol {Text Editor} > \uicontrol {Generic Highlighter} >
+
+    To reset the remembered definitions, go to \preferences >
+    \uicontrol {Text Editor} > \uicontrol {Generic Highlighter} and select
     \uicontrol {Reset Remembered Definitions}.
 
+    \image qtcreator-syntax-highlighter.png {Generic Highlighter preferences}
+
+    \section2 Download definitions
+
     If the editor cannot find the highlight definition for a file that you open
     for editing, it prompts you to download additional highlight definition
     files. Select \uicontrol {Download Definitions} to download the files.
+
     To view information about the downloaded files, open the \l{View output}
     {General Messages} view.
 
-    To suppress the message for a particular file pattern, select \preferences >
+    \section2 Ignore file patterns
+
+    To suppress the message for a particular file pattern, go to \preferences >
     \uicontrol {Text Editor} > \uicontrol {Generic Highlighter} and add the
-    pattern to the \uicontrol {Ignored file patterns} field.
+    pattern to \uicontrol {Ignored file patterns}.
 
-    \image qtcreator-syntax-highlighter.png "Generic Highlighter preferences"
+    \section2 Add your own definitions
 
-    If you have written your own syntax definition files, you
+    If you have written your own syntax definition files, add a definition search
-    can add a definition search path in the
+    path in \uicontrol {User Highlight Definition Files}.
-    \uicontrol {User Highlight Definition Files} field. To
+
-    apply the changes you make to the definition files, select
+    To apply the changes you make to the definition files, select
     \uicontrol {Reload Definitions}.
 
-    \section1 Highlighting Blocks
+    \if defined(qtdesignstudio)
+    \sa Code
+    \else
+    \sa {Edit Code}{How To: Edit Code}, {Edit Mode}
+    \endif
+*/
 
-    Use block highlighting to visually separate parts of the code that belong
+/*!
-    together. For example, when you place the cursor within the braces, the code
+    \page creator-how-to-use-code-blocks.html
+
+    \if defined(qtdesignstudio)
+    \previouspage qtquick-text-editor.html
+    \else
+    \previouspage creator-how-tos.html
+    \endif
+
+    \ingroup creator-how-to-edit
+
+    \title Highlight code blocks
+
+    Block highlighting visually separates parts of the code that belong together.
+    For example, when you place the cursor within a set of braces, the code
     enclosed in braces is highlighted.
 
-    \image qtcreator-blockhighlighting.png
+    \image qtcreator-blockhighlighting.png {A code block highlighted in the editor}
 
-    To enable block highlighting, select \preferences > \uicontrol {Text Editor}
+    To enable block highlighting, go to \preferences > \uicontrol {Text Editor}
-    > \uicontrol Display > \uicontrol {Highlight blocks}.
+    > \uicontrol Display and select \uicontrol {Highlight blocks}.
 
-    \section1 Folding Blocks
+    \section1 Fold code blocks
 
-    Use the folding markers to collapse and expand blocks of code within braces.
+    Select the folding markers to collapse and expand blocks of code within braces.
-    Click the folding marker to collapse or expand a block. In the figure above,
+    In the image above, the folding markers are located between the line number
-    the folding markers are located between the line number and the text pane.
+    and the text pane.
 
-    To show the folding markers, select \preferences >
+    To show the folding markers, go to \preferences >
-    \uicontrol {Text Editor} > \uicontrol Display >
+    \uicontrol {Text Editor} > \uicontrol Display and select
     \uicontrol {Display folding markers}. This option is enabled by default.
 
-    \image qtcreator-options-text-editor-display.png "Text Editor Display preferences"
+    \image qtcreator-options-text-editor-display.png {Text Editor Display preferences}
 
-    \section2 Folding All Comment Blocks
+    \if defined(qtcreator)
+    \section1 Fold all comment blocks
 
-    To fold all comment blocks, select \uicontrol Tools > \uicontrol C++ >
+    To fold all comment blocks, go to \uicontrol Tools > \uicontrol C++ >
-    \uicontrol {Fold All Comment Blocks}. To unfold all comment blocks, select
+    \uicontrol {Fold All Comment Blocks}.
-    \uicontrol {Unfold All Comment Blocks}.
 
-    \section1 Animating Matching Braces
+    To unfold all comment blocks, select \uicontrol {Unfold All Comment Blocks}.
+    \endif
+
+    \section1 Animate matching braces
 
     When the cursor is on a brace, the matching brace is animated by default.
 
-    To turn off the animation and just highlight the block and the braces, select
+    To turn off the animation and just highlight the block and the braces, go to
-    \preferences > \uicontrol {Text Editor} > \uicontrol Display and deselect
+    \preferences > \uicontrol {Text Editor} > \uicontrol Display and clear
     \uicontrol {Animate matching parentheses}.
 
-    \section1 Moving Between Blocks
+    \if defined(qtcreator)
+    \section1 Move between code blocks
 
-    You can use keyboard shortcuts to move within and between blocks. To go to
+    Use keyboard shortcuts to move within and between code blocks:
-    block end, press \key {Ctrl+]} and to go to block start, press
+
-    \key {Ctrl+[}. To also select the lines from the cursor position to the end
+    \list
+        \li To go to block end, press \key {Ctrl+]}.
+        \li To go to block start, press \key {Ctrl+[}.
+    \endlist
+
+    To also select the lines from the cursor position to the end
     or beginning of the block, press \key {Ctrl+Shift+]} and
     \key {Ctrl+Shift+[}, respectively.
+    \endif
 
-    \section1 Selecting the Current Block
+    \if defined(qtdesignstudio)
-
+    \sa Code
-    To select the current block, press \key Ctrl+U. A second key press extends
+    \else
-    the selection to the parent block. To undo the last selection, press
+    \sa {Edit Code}{How To: Edit Code}, {Edit Mode}
-    \key {Ctrl+Alt+Shift+U}.
+    \endif
-
-    To enable smart block selection, select \preferences
-    > \uicontrol {Text Editor} > \uicontrol Behavior >
-    \uicontrol {Enable smart selection changing}.
-
-    \image qtcreator-preferences-texteditor-behavior.webp "Text Editor Behavior preferences"
 */

doc/qtcreator/src/howto/creator-only/creator-how-tos.qdoc

@@ -55,10 +55,16 @@
 
     \section1 Edit Code
 
+    The code editor offers useful features, such as semantic highlighting,
+    checking code syntax, code completion, and refactoring actions.
+
     \generatelist creator-how-to-edit
 
     \section2 Configure Editors
 
+    Configure the code and text editor to suit your specific needs by
+    changing the fonts, colors, highlighting, and indentation.
+
     \generatelist creator-how-to-configure-editors
 
     \section2 Manage Language Servers
@@ -449,9 +455,22 @@
 
     \ingroup creator-how-to-edit
 
-    \title Select the enclosing block in C++
+    \title Select the current code block
 
-    Press \key {Ctrl+U}.
+    To select the current block of C++ code in the code editor, press
+    \key Ctrl+U.
+
+    Press \key Ctrl+U a second time to extend the selection to the parent block.
+
+    To undo the last selection, press \key {Ctrl+Alt+Shift+U}.
+
+    \section1 Turn on smart block selection
+
+    To turn on smart block selection, go to \preferences
+    > \uicontrol {Text Editor} > \uicontrol Behavior and select
+    \uicontrol {Enable smart selection changing}.
+
+    \image qtcreator-preferences-texteditor-behavior.webp {Text Editor Behavior preferences}
 
     \sa {Edit Code}{How To: Edit Code}, {Edit Mode}
 */

doc/qtcreator/src/overview/creator-only/creator-configuring.qdoc

@@ -111,7 +111,7 @@
     To download and use highlight definition files, select \preferences >
     \uicontrol {Text Editor} > \uicontrol {Generic Highlighter}.
 
-    For more information, see \l{Generic Highlighting}.
+    For more information, see \l{Download highlight definitions}.
 
     \section1 Adding Your Own Code Snippets
 

doc/qtcreator/src/overview/creator-only/creator-overview.qdoc

@@ -116,6 +116,30 @@
     such as Python, for which a \e {language server} is available that provides
     information about the code to IDEs.
 
+    \section2 Semantic Highlighting
+
+    To help you write well formatted code, \QC highlights code elements and
+    blocks. It understands the C++, QML, and JavaScript languages as code, not
+    as plain text, so it reads the source code, analyzes it, and highlights it
+    based on the semantic checks that it does for code elements, such as:
+
+    \list
+        \li Types (such as classes, structs, and type definitions)
+        \li Local variables
+        \li Class fields
+        \li Virtual functions
+    \endlist
+
+    You can select the color scheme to use for semantic highlighting in the text
+    editor preferences.
+
+    \QC supports syntax highlighting also for other types of files than C++,
+    QML, or JavaScript. It uses the
+    \l{https://api.kde.org/frameworks/syntax-highlighting/html/index.html}
+    {KSyntaxHighlighting} syntax highlighting engine with Kate syntax
+    definitions. It comes with most of the commonly used Kate definitions,
+    and you can download more definitions in the text editor preferences.
+
     \section2 Finding
 
     Use the incremental and advanced search to search in currently open projects
@@ -145,7 +169,8 @@
     If you are used to the Vim editor, run the main editor in the
     \l {FakeVim Modes and Commands}{FakeVim mode}.
 
-    For more information, see \l{Edit Code}{How To: Edit Code} and \l{Editors}.
+    For more information, see \l{Edit Code}{How To: Edit Code}, \l{Editors},
+    and \l{Text Editor}.
 
     \section1 Building, Deploying, and Running Applications
 

doc/qtcreator/src/qtcreator-toc.qdoc

@@ -29,7 +29,6 @@
         \list
         \li \l{Writing Code}
             \list
-                \li \l{Semantic Highlighting}
                 \li \l{Checking Code Syntax}
             \endlist
             \li \l{Configuring the Editor}

doc/qtcreatordev/src/qtcreator-dev.qdoc

@@ -98,7 +98,7 @@
 
     \list
         \li \l{https://doc.qt.io/qtcreator/creator-highlighting.html#generic-highlighting}
-            {Generic Highlighting}
+            {Download highlight definitions}
         \li \l{https://docs.kde.org/stable5/en/applications/katepart/highlight.html}
             {Working with Syntax Highlighting}
     \endlist

doc/qtdesignstudio/src/qtdesignstudio-toc.qdoc

@@ -201,7 +201,6 @@
                     \list
                         \li \l{Writing Code}
                             \list
-                                \li \l{Semantic Highlighting}
                                 \li \l{Checking Code Syntax}
                                 \li \l{Indent text or code}
                                 \li \l{Behavior}

doc/qtdesignstudio/src/views/qtquick-text-editor.qdoc

@@ -20,13 +20,21 @@
     The view offers the following features:
 
     \list
-        \li \l{Semantic Highlighting}
         \li \l{Checking Code Syntax}
         \li \l{Complete code}
         \li \l{Indent text or code}
         \li \l{Edit properties of QML types}
     \endlist
 
+    \section1 Semantic Highlighting
+
+    To help you write well formatted code, the \uicontrol Code view highlights
+    code elements and blocks. \QDS reads the source code, analyzes it, and
+    highlights it based on semantic checks.
+
+    To select the color scheme for semantic highlighting, go to
+    \preferences > \uicontrol {Text Editor} > \uicontrol {Font & Colors}.
+
     \section1 Refactoring Code
 
     Code refactoring is the process of improving and simplifying code without
@@ -44,5 +52,6 @@
         \li Select \key Ctrl + \key {F} (or \key Cmd + \key F on \macos).
     \endlist
 
-    \sa {Finding}, {Apply quick fixes}, {QML Quick Fixes}
+    \sa {Finding}, {Apply quick fixes}, {Download highlight definitions},
+    {Highlight code blocks}, {QML Quick Fixes}
 */