From f8c212bcd297bb19864b8d1276001017ab7929a7 Mon Sep 17 00:00:00 2001 From: hedy Date: Sat, 18 Nov 2023 22:24:34 +0800 Subject: [PATCH] docs: Document new options, commands, API functions --- CHANGELOG.md | 4 ++ README.md | 99 +++++++++++++++++++++++++++++++++++--------- lua/outline/init.lua | 6 +-- 3 files changed, 86 insertions(+), 23 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 39ebbd0..f49f935 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -52,6 +52,10 @@ cursorline is enabled only when focus is in outline. This lessens the visual changes due to `auto_set_cursor`, when focus is in code. - Floating windows are now used for `show_help` keymap and `:OutlineStatus` command. +- New command `:OutlineRefresh` and corresponding lua API function + `refresh_outline()` triggers re-requesting of symbols from provider and + updating the outline. +- New lua API function `is_focus_in_outline()` ### Fixes diff --git a/README.md b/README.md index 5b5f15c..448bce6 100644 --- a/README.md +++ b/README.md @@ -58,6 +58,9 @@ Table of contents * [Custom icons](#custom-icons) * [Disable icons](#disable-icons) * [TODO](#todo) +* [Limitations](#limitations) + * [Preview window](#preview-window-1) + * [Many outlines](#many-outlines) * [Related plugins](#related-plugins) @@ -138,8 +141,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. @@ -182,7 +186,7 @@ Pass a table to the setup call with your configuration options. -- 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 @@ -190,13 +194,14 @@ Pass a table to the setup call with your configuration options. 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. @@ -219,8 +224,6 @@ Pass a table to the setup call with your configuration options. }, 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 @@ -228,6 +231,25 @@ Pass a table to the setup call with your configuration options. -- 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 @@ -296,7 +318,6 @@ Pass a table to the setup call with your configuration options. 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 @@ -494,6 +515,19 @@ A fallback is always used if the previous candidate returned a falsey value. 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 @@ -625,6 +659,20 @@ require'outline' 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 @@ -854,20 +902,31 @@ Key: buffer is closed. Maybe it should continue working, so that pressing enter can open a split to - the correct location, and pressing `q` can properly close the buffer. - -- Preview / Hover - - ✅ Configurable winhighlight options for preview window (like nvim-cmp) - (simrat39/symbols-outline.nvim#128) - - ✅ Configurable width and height of preview window (simrat39/symbols-outline.nvim#130) - -- View - - ✅ Outline window customizations (simrat39/symbols-outline.nvim#137) - - ✅ Option to show line number next to symbols (simrat39/symbols-outline.nvim#212) - - ✅ Option to hide cursor in outline window if cursorline enabled + the correct location like `NvimTree` does, and pressing `q` can properly + close the buffer. +## 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](https://github.com/hedyhli/outline.nvim/issues/26), and for now you +can use a single outline sidebar and have it auto-update whenever you switch +buffers. + ## Related plugins - Aerial.nvim diff --git a/lua/outline/init.lua b/lua/outline/init.lua index 9a84242..a292624 100644 --- a/lua/outline/init.lua +++ b/lua/outline/init.lua @@ -610,7 +610,7 @@ function M.is_open() return M.view:is_open() end -function M.is_active() +function M.is_focus_in_outline() local winid = vim.fn.win_getid() if M.view:is_open() and winid == M.view.winnr then return true @@ -621,7 +621,7 @@ end ---Whether there is currently an available provider. ---@return boolean has_provider function M.has_provider() - if M.is_active() then + if M.is_focus_in_outline() then return _G._outline_current_provider ~= nil end return providers.has_provider() @@ -631,7 +631,7 @@ function M.show_status() ---@type outline.StatusContext local ctx = {} local p = _G._outline_current_provider - if not M.is_active() then + if not M.is_focus_in_outline() then p = providers.find_provider() end