Merge branch 'master' of github.com:hedyhli/symbols-outline.nvim

doc/symbols-outline.txt

@@ -19,6 +19,8 @@ Table of Contents                          *symbols-outline-table-of-contents*
   - Commands                   |symbols-outline-symbols-outline.nvim-commands|
   - Default keymaps     |symbols-outline-symbols-outline.nvim-default-keymaps|
   - Highlights               |symbols-outline-symbols-outline.nvim-highlights|
+  - Lua API                     |symbols-outline-symbols-outline.nvim-lua-api|
+  - Tips                           |symbols-outline-symbols-outline.nvim-tips|
   - Recipes                     |symbols-outline-symbols-outline.nvim-recipes|
 
 ==============================================================================
@@ -84,10 +86,34 @@ FIXES                                      *symbols-outline-fork-status-fixes*
 This section may be relevant to you if your existing config uses the mentioned
 features:
 
+- **Config**: Configuration options have been significantly restructured to
+    provide better consistency and understandability. Please see the
+    |symbols-outline-default-config| for an example of the full list.
+    - Options that control the looks
+        and behaviour of outline window is now moved to `outline_window` table;
+    - Options that control the items that show up are now in `outline_items`
+    - Options for the preview window is in `preview_window`.
+    - Symbol icons are now in `symbols.icons`, symbol blacklists are in
+        `symbols.blacklist`
+    - Lsp blacklists are now in `providers.lsp.blacklist_clients`.
+    - Fold options are now in `symbol_folding` with `fold_markers` being
+        `symbol_folding.markers`, consistent to `guides.markers`.
+    The reasoning for the above is simple. When you see 'border' under
+    `preview_window` you can directly infer it controls the border for the preview
+    window. Previously, for example, when you see `winblend` or `wrap`: is it for
+    the outline window or the preview window? Furthermore, this change also aids
+    extensibility to the configuration, and avoids cluttering the root setup opts
+    namespace.
+    If you disagree with this decision, you are always free to switch back to the
+    original symbols-outline.nvim, or you could pin a commit in this fork if you
+    still want to use the features and fixes from here.
 - **Config**: `keymaps.focus_location` RENAMED to `keymaps.peek_location` to
     avoid confusion with focus window commands.
 - **Config**: Marker icons used for guides can now be customized. `show_guides`
     REMOVED in favor of `guides.enabled`.
+    You can set `guides = false` to disable guides altogether, or set `guides =
+    true` to enable it but use default configuration for the guides. Otherwise,
+    please use `guides.enabled` if your configuration for `guides` is a table.
 - **Behaviour**: Removed hover floating window from `toggle_preview`.
     - Instead, you can set `open_hover_on_preview=true` (true by default) so that
         the `hover_symbol` action can be triggered when `toggle_preview`is
@@ -129,7 +155,8 @@ Features/Changes:
 - Cursorline option for the outline window.
 - Added function and command to show provider and outline window status, somewhat
     like `:LspInfo`.
-- Move down/up by one line and peek_location immediately.
+- Move down/up by one line and peek_location immediately, default bindings are
+    `<C-j>` and `<C-k>` just like Aerial.
 - Flash highlight when using goto/peek location.
 - Auto jump config option (see config `auto_goto`)
     (simrat39/symbols-outline.nvim#229, simrat39/symbols-outline.nvim#228).
@@ -137,7 +164,8 @@ Features/Changes:
 - New restore location keymap option to go back to corresponding outline location
     synced with code (see config `restore_location`).
 
-Screen recordings of some of the features is shown at the bottom of the readme.
+Screen recordings of some of the features is shown at the
+|symbols-outline-bottom-of-the-readme|.
 
 
 PRS                                          *symbols-outline-fork-status-prs*
@@ -239,11 +267,12 @@ Table of contents
 - |symbols-outline-setup|
 - |symbols-outline-configuration|
     - |symbols-outline-terminology|
-    - |symbols-outline-options|
+    - |symbols-outline-default-options|
 - |symbols-outline-commands|
-    - |symbols-outline-lua-api|
 - |symbols-outline-default-keymaps|
 - |symbols-outline-highlights|
+- |symbols-outline-lua-api|
+- |symbols-outline-tips|
 - |symbols-outline-recipes|
 
 
@@ -255,19 +284,17 @@ PREREQUISITES             *symbols-outline-symbols-outline.nvim-prerequisites*
 
 INSTALLATION               *symbols-outline-symbols-outline.nvim-installation*
 
-Use `hedyhli/symbols-outline.nvim` if you wish to use this fork.
-
 Packer:
 
 >lua
-    use 'simrat39/symbols-outline.nvim'
+    use 'hedyhli/symbols-outline.nvim'
 <
 
 Lazy:
 
 >lua
     {
-      "simrat39/symbols-outline.nvim",
+      "hedyhli/symbols-outline.nvim",
       config = function()
         -- Example mapping to toggle outline
         vim.keymap.set("n", "<leader>tt", "<cmd>SymbolsOutline<CR>",
@@ -284,11 +311,11 @@ Lazy with lazy-loading:
 
 >lua
     {
-      "simrat39/symbols-outline.nvim",
+      "hedyhli/symbols-outline.nvim",
       cmd = { "SymbolsOutline", "SymbolsOutlineOpen" },
       keys = {
         -- Example mapping to toggle outline
-        { "<leader>tt", "<cmd>SymbolsOutline<CR>", desc = "Toggle outline window" },
+        { "<leader>tt", "<cmd>SymbolsOutline<CR>", desc = "Toggle outline" },
       },
       opts = {
         -- Your setup opts here
@@ -314,9 +341,15 @@ Note that a call to `.setup()` is _required_ for this plugin to work
 
 CONFIGURATION             *symbols-outline-symbols-outline.nvim-configuration*
 
+The configuration structure has been heavily improved and refactored in this
+plugin. For details and reasoning, see |symbols-outline-breaking-changes|.
+
 
 TERMINOLOGY ~
 
+Check this list if you there’s any confusion with the terms used in the
+configuration.
+
 - **Provider**: Source of the items in the outline view. Could be LSP, CoC, etc.
 - **Node**: An item in the outline view
 - **Fold**: Collapse a collapsible node
@@ -329,46 +362,22 @@ TERMINOLOGY ~
 - **Focus**: Which window the cursor is in
 
 
-OPTIONS ~
+DEFAULT OPTIONS ~
 
 Pass a table to the setup call with your configuration options.
 
 Default values are shown:
 
 >lua
-    local opts = {
+    {
+      outline_window = {
         -- Where to open the split window: right/left
         position = 'right',
-      -- Whether width is relative to existing windows
-      relative_width = true,
         -- Percentage or integer of columns
         width = 25,
+        -- Whether width is relative to existing windows
+        relative_width = true,
     
-      -- Whether to highlight the currently hovered symbol (high cpu usage)
-      highlight_hovered_item = true,
-      -- Options for outline guides.
-      -- Only in this fork
-      guides = {
-        enabled = true,
-        markers = {
-          bottom = '└',
-          middle = '├',
-          vertical = '│',
-          horizontal = '─',
-        },
-      },
-      -- Automatically open preview of code on hover
-      auto_preview = false,
-      -- Automatically open hover_symbol when opening toggle_preview (see keymaps).
-      -- If you disable this you can still open hover_symbol using your keymap
-      -- below.
-      -- Only in this fork
-      open_hover_on_preview = true,
-      -- Border option for floating preview window.
-      -- Options include: single/double/rounded/solid/shadow or an array of border
-      -- characters.
-      -- See :help nvim_open_win() and search for "border" option.
-      border = 'single',
         -- Behaviour changed in this fork:
         -- Auto close the outline window if goto_location is triggered and not for
         -- peek_location
@@ -381,6 +390,19 @@ Default values are shown:
         show_numbers = false,
         show_relative_numbers = false,
         show_cursorline = true,  -- Only in this fork
+    
+        -- Whether to wrap long lines, or let them flow off the window
+        wrap = false,
+        -- Only in this fork:
+        -- Whether to focus on the outline window when it is opened.
+        -- Set to false to remain focus on your previous buffer when opening
+        -- symbols-outline.
+        focus_on_open = true,
+      },
+    
+      outline_items = {
+        -- Whether to highlight the currently hovered symbol (high cpu usage)
+        highlight_hovered_item = true,
         -- Show extra details with the symbols (lsp dependent)
         show_symbol_details = true,
         -- Only in this fork.
@@ -388,23 +410,48 @@ Default values are shown:
         -- Why? See this comment:
         -- https://github.com/simrat39/symbols-outline.nvim/issues/212#issuecomment-1793503563
         show_symbol_lineno = false,
-      -- Highlight group for the preview background
+      },
-      preview_bg_highlight = 'Pmenu',
+    
+      -- Options for outline guides.
+      -- Only in this fork
+      guides = {
+        enabled = true,
+        markers = {
+          bottom = '└',
+          middle = '├',
+          vertical = '│',
+          horizontal = '─',
+        },
+      },
+    
+      symbol_folding = {
         -- Depth past which nodes will be folded by default
         autofold_depth = nil,
         -- Automatically unfold hovered symbol
         auto_unfold_hover = true,
-      fold_markers = { '', '' },
+        markers = { '', '' },
-      -- Whether to wrap long lines, or let them flow off the window
+      },
-      wrap = false,
     
-      -- Only in this fork:
+      preview_window = {
-      -- Whether to focus on the outline window when it is opened.
+        -- Automatically open preview of code location when navigating outline window
-      -- Set to false to remain focus on your previous buffer when opening
+        auto_preview = false,
-      -- symbols-outline.
+        -- Automatically open hover_symbol when opening preview (see keymaps for
-      focus_on_open = true,
+        -- hover_symbol).
+        -- If you disable this you can still open hover_symbol using your keymap
+        -- below.
+        -- Only in this fork
+        open_hover_on_preview = true,
+        -- Border option for floating preview window.
+        -- Options include: single/double/rounded/solid/shadow or an array of border
+        -- characters.
+        -- See :help nvim_open_win() and search for "border" option.
+        border = 'single',
+        border_hl = 'Pmenu',
+        -- Highlight group for the preview background
+        bg_hl = 'Pmenu',
         -- Pseudo-transparency of the preview window
         winblend = 0
+      },
     
       -- These keymaps can be a string or a table for multiple keys
       keymaps = { 
@@ -445,14 +492,19 @@ Default values are shown:
         up_and_goto = '<C-k>',
       },
     
-      -- Lsp clients to ignore
+      providers = {
-      lsp_blacklist = {},
+        lsp = {
-      -- Symbols to ignore.
+          -- Lsp client names to ignore
-      -- Possible values: lua/symbols-outline/symbols.lua
+          blacklist_clients = {},
-      symbol_blacklist = {},
+        },
+      },
     
       symbols = {
-        -- Changed in this fork
+        -- Symbols to ignore.
+        -- Possible values are the Keys in the icons table below.
+        blacklist = {},
+        -- Changed in this fork to fix deprecated icons not showing.
+        icons = {
           File = { icon = "󰈔", hl = "@text.uri" },
           Module = { icon = "󰆧", hl = "@namespace" },
           Namespace = { icon = "󰅪", hl = "@namespace" },
@@ -481,16 +533,17 @@ Default values are shown:
           TypeParameter = { icon = "𝙏", hl = "@parameter" },
           Component = { icon = "󰅴", hl = "@function" },
           Fragment = { icon = "󰅴", hl = "@constant" },
-        -- ccls
+          -- Added ccls symbols in this fork
           TypeAlias =  { icon = ' ', hl = '@type' },
           Parameter = { icon = ' ', hl = '@parameter' },
           StaticMethod = { icon = ' ', hl = '@function' },
           Macro = { icon = ' ', hl = '@macro' },
         },
+      },
     }
 <
 
-To find out exactly what some of the options do, check out the
+To find out exactly what some of the options do, please see the
 |symbols-outline-recipes| section of the readme at the bottom for
 screen-recordings.
 
@@ -526,39 +579,6 @@ COMMANDS                       *symbols-outline-symbols-outline.nvim-commands*
     With bang, it can be understood as the converse of `focus_location`.
 
 
-LUA API ~
-
->lua
-    require'symbols-outline'
-<
-
-- setup(opts)
-- **toggle_outline(opts)**
-    Toggle opening/closing of outline window.
-    If `opts.focus_outline=false`, keep focus on previous window.
-- **open_outline(opts)**
-    Open the outline window.
-    If `opts.focus_outline=false`, keep focus on previous window.
-- **close_outline()**
-    Close the outline window.
-- **focus_toggle()**
-    Toggle cursor focus between code and outline window.
-- **focus_outline()**
-    Focus cursor on the outline window.
-- **focus_code()**
-    Focus cursor on the window which the outline is derived from.
-- **is_open()**
-    Return whether the outline window is open.
-- **show_status()**
-    Display current provider and outline window status in the messages area.
-- **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.
-
-
 DEFAULT KEYMAPS         *symbols-outline-symbols-outline.nvim-default-keymaps*
 
 These mappings are active for the outline window.
@@ -592,38 +612,96 @@ HIGHLIGHTS                   *symbols-outline-symbols-outline.nvim-highlights*
   Pmenu                     Highlight of the preview popup windows
   SymbolsOutlineConnector   Highlight of the table connectors
   Comment                   Highlight of the info virtual text
+Note that some highlights are configurable such as the preview window border
+and background. Please see |symbols-outline-configuration-options|.
+
+
+LUA API                         *symbols-outline-symbols-outline.nvim-lua-api*
+
+Symbols-outline provides the following public API for use in lua.
+
+>lua
+    require'symbols-outline'
+<
+
+- setup(opts)
+- **toggle_outline(opts)**
+    Toggle opening/closing of outline window.
+    If `opts.focus_outline=false`, keep focus on previous window.
+- **open_outline(opts)**
+    Open the outline window.
+    If `opts.focus_outline=false`, keep focus on previous window.
+- **close_outline()**
+    Close the outline window.
+- **focus_toggle()**
+    Toggle cursor focus between code and outline window.
+- **focus_outline()**
+    Focus cursor on the outline window.
+- **focus_code()**
+    Focus cursor on the window which the outline is derived from.
+- **is_open()**
+    Return whether the outline window is open.
+- **show_status()**
+    Display current provider and outline window status in the messages area.
+- **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.
+
+
+TIPS                               *symbols-outline-symbols-outline.nvim-tips*
+
+- To open the outline but don’t focus on it, you can use `:SymbolsOutline!` or
+    `:SymbolsOutlineOpen`.
+    This is useful in autocmds, say you have a filetype that, whenever a buffer
+    with that filetype is opened you want to open the outline.
+- After navigating around in the outline window, you can use `<C-g>` (default
+    mapping for `restore_location`) to go back to the corresponding outline
+    location based on the code location.
+
 
 RECIPES                         *symbols-outline-symbols-outline.nvim-recipes*
 
 Behaviour you may want to achieve and the combination of configuration options
 to achieve it.
 
+Code snippets in this section are to be placed in `.setup({ <HERE> })` directly
+unless specified otherwise.
+
 **Unfold all others except currently hovered item**
 
 >lua
+    symbol_folding = {
       autofold_depth = 1,
       auto_unfold_hover = true,
+    },
 <
 
 
 
-Any other recipes you think others may also find useful? Feel free to open a
-PR.
-
 **Use outline window as a quick-jump window**
 
 >lua
+    preview_window = {
       auto_preview = true,
+    },
 <
 
 
 https://github.com/hedyhli/symbols-outline.nvim/assets/50042066/a473d791-d1b9-48e9-917f-b816b564a645
 
+Note that in the recording I have `preview_window.open_hover_on_preview =
+false`.
+
 Alternatively, if you want to automatically navigate to the corresponding code
-location and not use the preview window:
+location directly and not use the preview window:
 
 >lua
+    outline_window = {
       auto_goto = true,
+    },
 <
 
 This feature was added by @stickperson in an upstream PR 🙌
@@ -634,22 +712,34 @@ https://github.com/hedyhli/symbols-outline.nvim/assets/50042066/3d06e342-97ac-40
 Or, you can use keys `<C-j>` and `<C-k>` to achieve the same effect, whilst not
 having `auto_goto` on by default.
 
+This feature is newly added in this fork.
+
 **Hide the extra details after each symbol name**
 
 >lua
+    outline_items = {
       show_symbol_details = false,
+    },
 <
 
 **Show line numbers next to each symbol to jump to that symbol quickly**
 
+This feature is newly added in this fork.
+
 >lua
-    show_symbol_lineno = true,
+    outline_items = {
+      show_symbol_lineno = false,
+    },
 <
 
-The default highlight group is `LineNr`.
+The default highlight group for the line numbers is `LineNr`.
 
 
 
+------------------------------------------------------------------------------
+Any other recipes you think others may also find useful? Feel free to open a
+PR.
+
 ==============================================================================
 3. Links                                               *symbols-outline-links*