1 files changed, 45 insertions, 19 deletions
diff --git a/doc/qtcreator/src/editors/creator-only/creator-text-editing-macros.qdoc b/doc/qtcreator/src/editors/creator-only/creator-text-editing-macros.qdoc
index fd4b4a8b70..796931f328 100644
--- a/doc/qtcreator/src/editors/creator-only/creator-text-editing-macros.qdoc
+++ b/doc/qtcreator/src/editors/creator-only/creator-text-editing-macros.qdoc
@@ -1,35 +1,61 @@
-// Copyright (C) 2023 The Qt Company Ltd.
+// Copyright (C) 2024 The Qt Company Ltd.
 // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
 
 /*!
     \previouspage creator-editor-codepasting.html
     \page creator-macros.html
-    \nextpage creator-diff-editor.html
+    \previouspage creator-how-tos.html
 
-    \title Using Text Editing Macros
+    \ingroup creator-how-to-edit
 
-    To record a text editing macro, select \uicontrol Tools >
-    \uicontrol {Text Editing Macros} > \uicontrol {Record Macro}
-    or press \key {Alt+[}. To stop recording, select \uicontrol Tools >
-    \uicontrol {Text Editing Macros} > \uicontrol {Stop Recording Macro} or
-    press \key {Alt+]}.
+    \title Record text editing macros
+
+    When you have a file open in the code editor, you can record a
+    keyboard sequence as a macro. You can then play the macro to
+    repeat the sequence. You can save the latest macro and assign a
+    keyboard shortcut for running it or run it from the locator.
+
+    \section1 Record macros
+
+    To record a text editing macro:
+
+    \list 1
+        \li Go to \uicontrol Tools > \uicontrol {Text Editing Macros} >
+            \uicontrol {Record Macro} or press \key {Alt+[}.
+        \li Press keyboard keys.
+        \li To stop recording, go to \uicontrol Tools >
+            \uicontrol {Text Editing Macros} > \uicontrol {Stop Recording Macro}
+            or press \key {Alt+]}.
+    \endlist
 
     \note The macro recorder does not support code completion.
 
-    To play the last macro, select \uicontrol Tools >
-    \uicontrol {Text Editing Macros} > \uicontrol {Play Last Macro} or
-    press \key {Alt+R}.
+    \section1 Play macros
 
-    To save the last macro, select \uicontrol Tools >
-    \uicontrol {Text Editing Macros} > \uicontrol {Save Last Macro}.
+    To play the last macro:
 
-    To assign a keyboard shortcut to a text editing macro, select
-    \preferences > \uicontrol Environment >
-    \uicontrol Keyboard. For more information, see \l{Assign keyboard shortcuts}.
+    \list
+        \li Go to \uicontrol Tools > \uicontrol {Text Editing Macros} >
+            \uicontrol {Play Last Macro}.
+        \li Press \key {Alt+R}.
+        \li Enter \c rm in the locator.
+    \endlist
 
-    You can also use the \c rm locator filter to run a macro. For more
-    information, see \l{Navigate with locator}.
+    \section1 Save macros
 
-    To view and remove saved macros, select \preferences >
+    To save the last macro, go to \uicontrol Tools >
+    \uicontrol {Text Editing Macros} > \uicontrol {Save Last Macro}.
+
+    To view and remove saved macros, go to \preferences >
     \uicontrol {Text Editor} > \uicontrol Macros.
+
+    \image qtcreator-preferences-texteditor-macros.webp {Macros tab in Text Editor Preferences}
+
+    \section1 Assign keyboard shortcuts to macros
+
+    To assign a keyboard shortcut to a text editing macro, go to
+    \preferences > \uicontrol Environment > \uicontrol Keyboard.
+
+    \sa {Assign keyboard shortcuts}, {Edit Code}{How To: Edit Code},
+    {Navigate with locator}
 */