[docgen] Update doc/orgmode.txt

Author: github-actions

doc/orgmode.txt

@@ -86,7 +86,7 @@ CONTENTS                                                        *orgmode-content
             1.3.3.2. org_capture_refile...............|orgmode-org_capture_refile|
             1.3.3.3. org_capture_kill...................|orgmode-org_capture_kill|
             1.3.3.4. org_capture_show_help.........|orgmode-org_capture_show_help|
-        1.3.4. Closing note mappings...............|orgmode-closing_note_mappings|
+        1.3.4. Note mappings...............................|orgmode-note_mappings|
             1.3.4.1. org_note_finalize.................|orgmode-org_note_finalize|
             1.3.4.2. org_note_kill.........................|orgmode-org_note_kill|
             1.3.4.3. org_note_show_help...............|orgmode-org_note_show_help|
@@ -157,8 +157,10 @@ CONTENTS                                                        *orgmode-content
     1.7. Autocompletion...................................|orgmode-autocompletion|
     1.8. Abbreviations.....................................|orgmode-abbreviations|
     1.9. Formatting...........................................|orgmode-formatting|
-    1.10. Colors..................................................|orgmode-colors|
-        1.10.1. Highlight Groups........................|orgmode-highlight_groups|
+    1.10. User interface..................................|orgmode-user_interface|
+        1.10.1. Colors............................................|orgmode-colors|
+            1.10.1.1. Highlight Groups..................|orgmode-highlight_groups|
+        1.10.2. Menu................................................|orgmode-menu|
     1.11. Advanced search................................|orgmode-advanced_search|
     1.12. Notifications (experimental)......|orgmode-notifications_(experimental)|
         1.12.1. Cron................................................|orgmode-cron|
@@ -199,7 +201,9 @@ TABLE OF CONTENT                                        *orgmode-table_of_conten
 7.  Autocompletion (#autocompletion)
 8.  Abbreviations (#abbreviations)
 9.  Formatting (#formatting)
-10. Colors (#colors)
+10. User interface (#user-interface)
+    1.  Colors (#colors)
+    2.  Menu (#menu)
 11. Advanced search (#advanced-search)
 12. Notifications (experimental) (#notifications-experimental)
 13. Clocking (#clocking)
@@ -1021,7 +1025,7 @@ These mappings live under `mappings.capture`, and can be changed like this:
     })
 <
 
-CLOSING NOTE MAPPINGS                              *orgmode-closing_note_mappings*
+NOTE MAPPINGS                                              *orgmode-note_mappings*
 
 Mappings used in closing note window.
 
@@ -1528,6 +1532,8 @@ Currently, these things are formatted:
 *   Clock entries total time is recalculated (see Recalculating totals (#recalculating-totals) in Clocking (#Clocking) section)
 
 --------------------------------------------------------------------------------
+USER INTERFACE                                            *orgmode-user_interface*
+
 COLORS                                                            *orgmode-colors*
 
 Colors used for todo keywords and agenda states (deadline, schedule ok, schedule warning)
@@ -1585,6 +1591,73 @@ HIGHLIGHT GROUPS                                        *orgmode-highlight_group
     *   `OrgAgendaScheduled`: A scheduled item in the agenda view
     *   `OrgAgendaScheduledPast`: A item past its scheduled date in the agenda view
 
+MENU                                                                *orgmode-menu*
+
+The menu is used when selecting further actions in `agenda`, `capture` and `export`. Here is an example of the menu you see when opening `agenda`:
+>
+    Press key for an agenda command
+    -------------------------------
+    a Agenda for current week or day
+    t List of all TODO entries
+    m Match a TAGS/PROP/TODO query
+    M Like m, but only for TODO entries
+    s Search for keywords
+    q Quit
+<
+
+Users have the option to change the appearance of this menu. To do this, you need to add a handler in the UI configuration section:
+>
+    require("orgmode").setup({
+      ui = {
+        menu = {
+          handler = function(data)
+            -- your handler here, for example:
+            local options = {}
+            local options_by_label = {}
+            for _, item in ipairs(data.items) do
+              -- Only MenuOption has `key`
+              -- Also we don't need `Quit` option because we can close the menu with ESC
+              if item.key and item.label:lower() ~= "quit" then
+                table.insert(options, item.label)
+                options_by_label[item.label] = item
+              end
+            end
+            local handler = function(choice)
+              if not choice then
+                return
+              end
+              local option = options_by_label[choice]
+              if option.action then
+                option.action()
+              end
+            end
+            vim.ui.select(options, {
+              propmt = data.propmt,
+            }, handler)
+          end,
+        },
+      },
+    })
+<
+
+When the menu is called, the handler receives a table `data` with the following fields as input:
+* `title` (`string`) — menu title
+* `items` (`table`) — array containing `MenuItem` (see below)
+* `prompt` (`string`) — prompt text used to prompt a keystroke
+
+Each menu item `MenuItem` is one of two types: `MenuOption` and `MenuSeparator`.
+
+`MenuOption` is a table containing the following fields:
+* `label` (`string`) — description of the action
+* `key` (`string`) — key that will be processed when the keys are pressed in the menu
+* `action` (`function` optional) — handler that will be called when the `key` is pressed in the menu.
+
+`MenuSeparator` is a table containing the following fields:
+* `icon` (`string` optional) — character used as separator. The default character is `-`
+* `length` (`number` optional) — number of repetitions of the separator character. The default length is 80
+
+In order for the menu to work as expected, the handler must call `action` from `MenuItem`.
+
 --------------------------------------------------------------------------------
 ADVANCED SEARCH                                          *orgmode-advanced_search*