diff --git a/doc/outline.txt b/doc/outline.txt index 8ad741d..2c22c02 100644 --- a/doc/outline.txt +++ b/doc/outline.txt @@ -13,6 +13,7 @@ Table of Contents *outline-table-of-contents* - Lua API |outline-lua-api| - Tips |outline-tips| - Recipes |outline-recipes| + - Limitations |outline-limitations| - Related plugins |outline-related-plugins| PREREQUISITES *outline-prerequisites* @@ -95,8 +96,9 @@ configuration. - **Node**: An item in the outline view - **Fold**: Collapse a collapsible node - **Location**: Where in the source file a node is from -- **Preview**: Show the location of a node in code using a floating window -- **Peek**: Go to corresponding location in code without leaving outline window +- **Preview**: Show the location of a node in code using a floating window. + Syntax highlighting is provided if treesitter is installed. +- **Jump/Peek**: Go to corresponding location in code without leaving outline window - **Hover**: Cursor currently on the line of a node - **Hover symbol**: Displaying a floating window to show symbol information provided by provider. @@ -140,7 +142,7 @@ Show defaults ~ -- when jumping. false to disable. jump_highlight_duration = 300, -- Whether to center the cursor line vertically in the screen when - -- jumping/focusing. Runs zz. + -- jumping/focusing. Executes zz. center_on_jump = true, -- Vim options for the outline window @@ -148,13 +150,14 @@ Show defaults ~ show_relative_numbers = false, wrap = false, + -- true/false/'focus_in_outline'/'focus_in_code'. + -- The last two means only show cursorline when the focus is in outline/code. + -- 'focus_in_outline' can be used if the outline_items.auto_set_cursor + -- operations are too distracting due to visual contrast caused by cursorline. show_cursorline = true, -- Enable this only if you enabled cursorline so your cursor color can -- blend with the cursorline, in effect, as if your cursor is hidden -- in the outline window. - -- This is useful because with cursorline, there isn't really a need - -- to know the vertical column position of the cursor and it may even - -- be distracting, rendering lineno/guides/icons unreadable. -- This makes your line of cursor have the same color as if the cursor -- wasn't focused on the outline window. -- This feature is experimental. @@ -177,8 +180,6 @@ Show defaults ~ }, outline_items = { - -- Whether to highlight the currently hovered symbol and all direct parents - highlight_hovered_item = true, -- Show extra details with the symbols (lsp dependent) as virtual next show_symbol_details = true, -- Show corresponding line numbers of each symbol on the left column as @@ -186,6 +187,25 @@ Show defaults ~ -- Why? See this comment: -- https://github.com/simrat39/symbols-outline.nvim/issues/212#issuecomment-1793503563 show_symbol_lineno = false, + -- Whether to highlight the currently hovered symbol and all direct parents + highlight_hovered_item = true, + -- Whether to automatically set cursor location in outline to match + -- location in code when focus is in code. If disabled you can use + -- `:OutlineFollow[!]` from any window or `` from outline window to + -- trigger this manually. + auto_set_cursor = true, + -- Autocmd events to automatically trigger these operations. + auto_update_events = { + -- Includes both setting of cursor and highlighting of hovered item. + -- The above two options are respected. + -- This can be triggered manually through `follow_cursor` lua API, + -- :OutlineFollow command, or . + follow = { 'CursorMoved' }, + -- Re-request symbols from the provider. + -- This can be triggered manually through `refresh_outline` lua API, or + -- :OutlineRefresh command. + items = { 'InsertLeave', 'WinEnter', 'BufEnter', 'BufWinEnter', 'TabEnter', 'BufWritePost' }, + }, }, -- Options for outline guides which help show tree hierarchy of symbols @@ -254,7 +274,6 @@ Show defaults ~ hover_symbol = '', -- Preview location code of the symbol under cursor toggle_preview = 'K', - -- Symbol actions rename_symbol = 'r', code_actions = 'a', -- These fold actions are collapsing tree nodes, not code folding @@ -427,8 +446,8 @@ COMMANDS *outline-commands* - **:OutlineFocus**: Toggle focus between outline and code/source window - **:OutlineFocusOutline**: Focus on outline - **:OutlineFocusCode**: Focus on source window -- **:OutlineStatus**: Display current provider and outline window status in the - messages area +- **:OutlineStatus**: Display provider and outline window status in a floating + window, similar to `:LspInfo` - **:OutlineFollow[!]** (✓ bang × mods) Go to corresponding node in outline based on cursor position in code, and focus on the outline window. @@ -438,12 +457,23 @@ COMMANDS *outline-commands* whereas this command sets position in outline window to the cursor position of code window. With bang, it can be understood as the converse of `peek_location`. + This is automatically triggered on events + `config.outline_items.auto_update_events.follow`. + You can also trigger this manually using the `restore_location` keymap (default + ``) from the outline window. +- **:OutlineRefresh** + Trigger refresh of symbols from provider and update outline items. + This is automatically triggered on events + `config.outline_items.auto_update_events.refresh`. DEFAULT KEYMAPS *outline-default-keymaps* These mappings are active only for the outline window. +You can open a floating window showing the following list of keymaps using the +`?` key by default from the outline window. + Key Action ------------- ---------------------------------------------------- Esc / q Close outline @@ -464,7 +494,7 @@ These mappings are active only for the outline window. R Reset all folding Ctrl+k Go up and peek location Ctrl+j Go down and peek location - ? Show current keymaps as a vim message + ? Show current keymaps in a floating window HIGHLIGHTS *outline-highlights* @@ -549,13 +579,21 @@ Outline.nvim provides the following public API for use in lua. - **is_open()** Return whether the outline window is open. - **show_status()** - Display current provider and outline window status in the messages area. + Display provider and outline window status in a floating window. - **has_provider()** Returns whether a provider is available for current window. - **follow_cursor(opts)** Go to corresponding node in outline based on cursor position in code, and focus on the outline window. With `opts.focus_outline=false`, cursor focus will remain on code window. + This is automatically called on events + `config.outline_items.auto_update_events.follow`. +- **is_focus_in_outline()** + Return whether outline is open and current focus is in outline. +- **refresh_outline()** + Re-request symbols from provider and update outline items. + This is automatically called on events + `config.outline_items.auto_update_events.refresh`. TIPS *outline-tips* @@ -749,6 +787,28 @@ Disable icons for specific kinds, and for others use lspkind: +LIMITATIONS *outline-limitations* + + +PREVIEW WINDOW ~ + +Sometimes the preview window could be slow in loading. This could be due to the +code buffer being large. As of now there are no good solutions in circumventing +this problem — currently the entire code buffer is read, and then put into +the preview buffer. If only the required portion to preview is read and set +instead, there would be highlighting issues (say the calculated starting line +was within a markdown code block, so what was previously not supposed to be +code is now highlighted as code). + + +MANY OUTLINES ~ + +Outline.nvim does not support having multiple outlines attached to different +buffers as of now. However, this feature is planned +, and for now you can use a +single outline sidebar and have it auto-update whenever you switch buffers. + + RELATED PLUGINS *outline-related-plugins* - Aerial.nvim