diff options
Diffstat (limited to 'start/indent-blankline-2.20.4/doc/indent_blankline.txt')
| -rw-r--r-- | start/indent-blankline-2.20.4/doc/indent_blankline.txt | 784 |
1 files changed, 784 insertions, 0 deletions
diff --git a/start/indent-blankline-2.20.4/doc/indent_blankline.txt b/start/indent-blankline-2.20.4/doc/indent_blankline.txt new file mode 100644 index 0000000..d3975e8 --- /dev/null +++ b/start/indent-blankline-2.20.4/doc/indent_blankline.txt @@ -0,0 +1,784 @@ +*indent_blankline.txt* Show vertical lines for indent on empty lines + + +Author: Lukas Reineke <lukas.reineke@protonmail.com> +Version: 2.20.4 + +============================================================================== +CONTENTS *indent-blankline* + + 1. Introduction |indent-blankline-introduction| + 2. Highlights |indent-blankline-highlights| + 3. Setup |indent-blankline-setup| + 4. Variables |indent-blankline-variables| + 5. Commands |indent-blankline-commands| + 6. License |indent-blankline-license| + +============================================================================== + 1. INTRODUCTION *indent-blankline-introduction* + +This plugin adds indentation guides to all lines (including empty lines). + +It uses Neovim's virtual text feature and **no conceal** + +This plugin requires Neovim 0.5 or higher. It makes use of Neovim only +features so it will not work in Vim. +There is a legacy version of the plugin that supports Neovim 0.4 under the +branch `version-1` + +============================================================================== + 2. HIGHLIGHTS *indent-blankline-highlights* + +To change the highlighting of either the indent character, or the whitespace +between indent characters, define or update these highlight groups. + +------------------------------------------------------------------------------ +IndentBlanklineChar *hl-IndentBlanklineChar* + + Highlight of indent character. + + Default: takes guifg color from 'Whitespace' ~ + + Example: > + + highlight IndentBlanklineChar guifg=#00FF00 gui=nocombine + +------------------------------------------------------------------------------ +IndentBlanklineSpaceChar *hl-IndentBlanklineSpaceChar* + + Highlight of space character. + + Default: takes guifg color from 'Whitespace' ~ + + Example: > + + highlight IndentBlanklineSpaceChar guifg=#00FF00 gui=nocombine + +------------------------------------------------------------------------------ +IndentBlanklineSpaceCharBlankline *hl-IndentBlanklineSpaceCharBlankline* + + Highlight of space character on blank lines. + + Default: takes guifg color from 'Whitespace' ~ + + Example: > + + highlight IndentBlanklineSpaceCharBlankline guifg=#00FF00 gui=nocombine + +------------------------------------------------------------------------------ +IndentBlanklineContextChar *hl-IndentBlanklineContextChar* + + Highlight of indent character when base of current context. + Only used when |g:indent_blankline_show_current_context| is active + + Default: takes guifg color from 'Label' ~ + + Example: > + + highlight IndentBlanklineContextChar guifg=#00FF00 gui=nocombine + +------------------------------------------------------------------------------ +IndentBlanklineContextSpaceChar *hl-IndentBlanklineContextSpaceChar* + + Highlight of space characters one indent level of the current context. + Only used when |g:indent_blankline_show_current_context| is active + + Default: takes guifg color from 'Label' ~ + + Example: > + + highlight IndentBlanklineContextSpaceChar guifg=#00FF00 gui=nocombine + +------------------------------------------------------------------------------ +IndentBlanklineContextStart *hl-IndentBlanklineContextStart* + + Highlight of the first line of the current context. + Only used when |g:indent_blankline_show_current_context_start| is active + + Default: takes guifg color from 'Label' as guisp and adds underline ~ + + Note: You need to have set |gui-colors| for the default to work. + + Example: > + + highlight IndentBlanklineContextStart guisp=#00FF00 gui=underline + +------------------------------------------------------------------------------ + +Note: Define your highlight group after setting colorscheme or your colorscheme will clear your highlight group + +When defining the highlight group, it is important to set |nocombine| as a +gui option. This is to make sure the character does not inherit gui options +from the underlying text, like italic or bold. + +Highlight groups get reset on |ColorScheme| autocommand, if both fg and bg +are empty. + +The set more than one highlight group that changes based on indentation level, +see: +|g:indent_blankline_char_highlight_list| +|g:indent_blankline_space_char_highlight_list| +|g:indent_blankline_space_char_blankline_highlight_list| + +============================================================================== + 3. SETUP *indent-blankline-setup* + +To configure indent-blankline, either run the setup function, or set variables +manually. +The setup function has a single table as argument, keys of the table match the +|indent-blankline-variables| without the `indent_blankline_` part. + +Example: > + + require("indent_blankline").setup { + -- for example, context is off by default, use this to turn it on + show_current_context = true, + show_current_context_start = true, + } + +============================================================================== + 4. VARIABLES *indent-blankline-variables* + +All variables can be set globally |g:var|, per tab |t:var|, or per buffer |b:var| + +------------------------------------------------------------------------------ +g:indent_blankline_char *g:indent_blankline_char* + + Specifies the character to be used as indent line. + Not used if |g:indent_blankline_char_list| is not empty. + + When set explicitly to empty string (""), no indentation character is + displayed at all, even when |g:indent_blankline_char_list| is not empty. + This can be useful in combination with + |g:indent_blankline_space_char_highlight_list| to only rely on different + highlighting of different indentation levels without needing to show a + special character. + + Also set by |g:indentLine_char| + + Default: '│' ~ + + Example: > + + let g:indent_blankline_char = '|' + +------------------------------------------------------------------------------ +g:indent_blankline_char_blankline *g:indent_blankline_char_blankline* + + Specifies the character to be used as indent line for blanklines. + Not used if |g:indent_blankline_char_list_blankline| is not empty. + + Default: '' ~ + + Example: > + + let g:indent_blankline_char_blankline = '┆' + +------------------------------------------------------------------------------ +g:indent_blankline_char_list *g:indent_blankline_char_list* + + Specifies a list of characters to be used as indent line for + each indentation level. + Ignored if the value is an empty list. + + Also set by |g:indentLine_char_list| + + Default: [] ~ + + Example: > + + let g:indent_blankline_char_list = ['|', '¦', '┆', '┊'] + +------------------------------------------------------------------------------ +g:indent_blankline_char_list_blankline *g:indent_blankline_char_list_blankline* + + Specifies a list of characters to be used as indent line for + each indentation level on blanklines. + Ignored if the value is an empty list. + + Default: [] ~ + + Example: > + + let g:indent_blankline_char_list_blankline = ['|', '¦', '┆', '┊'] + +------------------------------------------------------------------------------ + +g:indent_blankline_char_highlight_list *g:indent_blankline_char_highlight_list* + + Specifies the list of character highlights for each indentation level. + Ignored if the value is an empty list. + + Default: [] ~ + + Example: > + + let g:indent_blankline_char_highlight_list = ['Error', 'Function'] + +------------------------------------------------------------------------------ +g:indent_blankline_space_char_blankline *g:indent_blankline_space_char_blankline* + + Specifies the character to be used as the space value in between indent + lines when the line is blank. + + Default: An empty space character ~ + + Example: > + + let g:indent_blankline_space_char_blankline = ' ' + +------------------------------------------------------------------------------ + +g:indent_blankline_space_char_highlight_list *g:indent_blankline_space_char_highlight_list* + + Specifies the list of space character highlights for each indentation + level. + Ignored if the value is an empty list. + + Default: [] ~ + + Example: > + + let g:indent_blankline_space_char_highlight_list = ['Error', 'Function'] + +------------------------------------------------------------------------------ + +g:indent_blankline_space_char_blankline_highlight_list *g:indent_blankline_space_char_blankline_highlight_list* + + Specifies the list of space character highlights for each indentation + level when the line is empty. + Ignored if the value is an empty list. + + Also set by |g:indent_blankline_space_char_highlight_list| + + Default: [] ~ + + Example: > + + let g:indent_blankline_space_char_blankline_highlight_list = ['Error', 'Function'] + +------------------------------------------------------------------------------ +g:indent_blankline_use_treesitter *g:indent_blankline_use_treesitter* + + Use treesitter to calculate indentation when possible. + Requires treesitter + + Default: false ~ + + Example: > + + let g:indent_blankline_use_treesitter = v:true + +------------------------------------------------------------------------------ +g:indent_blankline_indent_level *g:indent_blankline_indent_level* + + Specifies the maximum indent level to display. + + Also set by |g:indentLine_indentLevel| + + Default: 10 ~ + + Example: > + + let g:indent_blankline_indent_level = 4 + +------------------------------------------------------------------------------ +g:indent_blankline_max_indent_increase *g:indent_blankline_max_indent_increase* + + The maximum indent level increase from line to line. + Set this option to 1 to make aligned trailing multiline comments not + create indentation. + + Default: g:indent_blankline_indent_level ~ + + Example: > + + let g:indent_blankline_max_indent_increase = 1 + +------------------------------------------------------------------------------ +g:indent_blankline_show_first_indent_level *g:indent_blankline_show_first_indent_level* + + Displays indentation in the first column. + + Default: v:true ~ + + Example: > + + let g:indent_blankline_show_first_indent_level = v:false + +------------------------------------------------------------------------------ +g:indent_blankline_show_trailing_blankline_indent *g:indent_blankline_show_trailing_blankline_indent* + + Displays a trailing indentation guide on blank lines, to match the + indentation of surrounding code. + Turn this off if you want to use background highlighting instead of chars. + + Default: v:true ~ + + Example: > + + let g:indent_blankline_show_trailing_blankline_indent = v:false + +------------------------------------------------------------------------------ +g:indent_blankline_show_end_of_line *g:indent_blankline_show_end_of_line* + + Displays the end of line character set by |listchars| instead of the + indent guide on line returns. + + Default: v:false ~ + + Example: > + + let g:indent_blankline_show_end_of_line = v:true + +------------------------------------------------------------------------------ +g:indent_blankline_show_foldtext *g:indent_blankline_show_foldtext* + + Displays the full fold text instead of the indent guide on folded lines. + + Note: there is no autocommand to subscribe to changes in folding. This + might lead to unexpected results. A possible solution for this is to + remap folding bindings to also call |IndentBlanklineRefresh| + + Default: v:true ~ + + Example: > + + let g:indent_blankline_show_foldtext = v:false + +------------------------------------------------------------------------------ +g:indent_blankline_enabled *g:indent_blankline_enabled* + + Turns this plugin on or off. + + Also set by |g:indentLine_enabled| + + Note: the buffer version of this variable overwrites all other + enabled/disabled checks. + + Default: v:true ~ + + Example: > + + let g:indent_blankline_enabled = v:false + +------------------------------------------------------------------------------ +g:indent_blankline_disable_with_nolist *g:indent_blankline_disable_with_nolist* + + When true, automatically turns this plugin off when |nolist| is set. + When false, setting |nolist| will keep displaying indentation guides but + removes whitespace characters set by |listchars|. + + Default: v:false ~ + + Example: > + + let g:indent_blankline_disable_with_nolist = v:true + +------------------------------------------------------------------------------ +g:indent_blankline_filetype *g:indent_blankline_filetype* + + Specifies a list of |filetype| values for which this plugin is enabled. + All |filetypes| are enabled if the value is an empty list. + + Also set by |g:indentLine_fileType| + + Default: [] ~ + + Example: > + + let g:indent_blankline_filetype = ['vim'] + +------------------------------------------------------------------------------ +g:indent_blankline_filetype_exclude *g:indent_blankline_filetype_exclude* + + Specifies a list of |filetype| values for which this plugin is not enabled. + Ignored if the value is an empty list. + + Also set by |g:indentLine_fileTypeExclude| + + Default: [ ~ + "lspinfo", ~ + "packer", ~ + "checkhealth", ~ + "help", ~ + "man", ~ + "", ~ + ] ~ + + Example: > + + let g:indent_blankline_filetype_exclude = ['help'] + +------------------------------------------------------------------------------ +g:indent_blankline_buftype_exclude *g:indent_blankline_buftype_exclude* + + Specifies a list of |buftype| values for which this plugin is not enabled. + Ignored if the value is an empty list. + + Also set by |g:indentLine_bufTypeExclude| + + Default: [ ~ + "terminal", ~ + "nofile", ~ + "quickfix", ~ + "prompt", ~ + ] ~ + + Example: > + + let g:indent_blankline_buftype_exclude = ['terminal'] + +------------------------------------------------------------------------------ +g:indent_blankline_bufname_exclude *g:indent_blankline_bufname_exclude* + + Specifies a list of buffer names (file name with full path) for which + this plugin is not enabled. + A name can be regular expression as well. + + Also set by |g:indentLine_bufNameExclude| + + Default: [] ~ + + Example: > + + let g:indent_blankline_bufname_exclude = ['README.md', '.*\.py'] + +------------------------------------------------------------------------------ +g:indent_blankline_strict_tabs *g:indent_blankline_strict_tabs* + + When on, if there is a single tab in a line, only tabs are used to + calculate the indentation level. + When off, both spaces and tabs are used to calculate the indentation + level. + Only makes a difference if a line has a mix of tabs and spaces for + indentation. + + Default: v:false ~ + + Example: > + + let g:indent_blankline_strict_tabs = v:true + +------------------------------------------------------------------------------ +g:indent_blankline_show_current_context *g:indent_blankline_show_current_context* + + When on, use treesitter to determine the current context. Then show the + indent character in a different highlight. + + Note: Requires https://github.com/nvim-treesitter/nvim-treesitter to be + installed + + Note: With this option enabled, the plugin refreshes on |CursorMoved|, + which might be slower + + Default: v:false ~ + + Example: > + + let g:indent_blankline_show_current_context = v:true + +------------------------------------------------------------------------------ +g:indent_blankline_show_current_context_start *g:indent_blankline_show_current_context_start* + + Applies the |hl-IndentBlanklineContextStart| highlight group to the first + line of the current context. + By default this will underline. + + Note: Requires https://github.com/nvim-treesitter/nvim-treesitter to be + installed + + Note: You need to have set |gui-colors| and it depends on your terminal + emulator if this works as expected. + If you are using kitty and tmux, take a look at this article to + make it work + http://evantravers.com/articles/2021/02/05/curly-underlines-in-kitty-tmux-neovim/ + + Default: v:false ~ + + Example: > + + let g:indent_blankline_show_current_context_start = v:true + +------------------------------------------------------------------------------ +g:indent_blankline_show_current_context_start_on_current_line *g:indent_blankline_show_current_context_start_on_current_line* + + Shows |g:indent_blankline_show_current_context_start| even when the cursor + is on the same line + + Default: v:true ~ + + Example: > + + let g:indent_blankline_show_current_context_start_on_current_line = v:false + +------------------------------------------------------------------------------ +g:indent_blankline_context_char *g:indent_blankline_context_char* + + Specifies the character to be used for the current context indent line. + Not used if |g:indent_blankline_context_char_list| is not empty. + + Useful to have a greater distinction between the current context indent + line and others. + + Also useful in combination with |g:indent_blankline_char| set to empty string + (""), as this allows only the current context indent line to be shown. + + Default: g:indent_blankline_char ~ + + Example: > + + let g:indent_blankline_context_char = '┃' + +------------------------------------------------------------------------------ +g:indent_blankline_context_char_blankline *g:indent_blankline_context_char_blankline* + + Equivalent of |g:indent_blankline_char_blankline| for + |g:indent_blankline_context_char|. + + Default: '' ~ + + Example: > + + let g:indent_blankline_context_char_blankline = '┆' + +------------------------------------------------------------------------------ +g:indent_blankline_context_char_list *g:indent_blankline_context_char_list* + + Equivalent of |g:indent_blankline_char_list| for + |g:indent_blankline_context_char|. + + Default: [] ~ + + Example: > + + let g:indent_blankline_context_char_list = ['┃', '║', '╬', '█'] + +------------------------------------------------------------------------------ +g:indent_blankline_context_char_list_blankline *g:indent_blankline_context_char_list_blankline* + + Equivalent of |g:indent_blankline_char_list_blankline| for + |g:indent_blankline_context_char_blankline|. + + Default: [] ~ + + Example: > + + let g:indent_blankline_context_char_list_blankline = ['┃', '║', '╬', '█'] + +------------------------------------------------------------------------------ +g:indent_blankline_context_highlight_list *g:indent_blankline_context_highlight_list* + + Specifies the list of character highlights for the current context at + each indentation level. + Ignored if the value is an empty list. + + Only used when |g:indent_blankline_show_current_context| is active + + Default: [] ~ + + Example: > + + let g:indent_blankline_context_highlight_list = ['Error', 'Warning'] + +------------------------------------------------------------------------------ +g:indent_blankline_char_priority *g:indent_blankline_char_priority* + + Specifies the |extmarks| priority for chars. + + Default: 1 ~ + + Example: > + + let g:indent_blankline_char_priority = 50 + +------------------------------------------------------------------------------ +g:indent_blankline_context_start_priority *g:indent_blankline_context_start_priority* + + Specifies the |extmarks| priority for the context start. + + Default: 10000 ~ + + Example: > + + let g:indent_blankline_context_start_priority = 50 + +------------------------------------------------------------------------------ +g:indent_blankline_context_patterns *g:indent_blankline_context_patterns* + + Specifies a list of lua patterns that are used to match against the + treesitter |tsnode:type()| at the cursor position to find the current + context. + + To learn more about how lua pattern work, see here: + https://www.lua.org/manual/5.1/manual.html#5.4.1 + + Only used when |g:indent_blankline_show_current_context| is active + + Default: [ ~ + "class", ~ + "^func", ~ + "method", ~ + "^if", ~ + "while", ~ + "for", ~ + "with", ~ + "try", ~ + "except", ~ + "arguments", ~ + "argument_list", ~ + "object", ~ + "dictionary", ~ + "element", ~ + "table", ~ + "tuple", ~ + "do_block", ~ + ] ~ + + Example: > + + let g:indent_blankline_context_patterns = ['^if'] + +------------------------------------------------------------------------------ +g:indent_blankline_use_treesitter_scope *g:indent_blankline_use_treesitter_scope* + + Instead of using |g:indent_blankline_context_patterns|, use the current + scope defined by nvim-treesitter as the context. + + Default: false ~ + + Example: > + + let g:indent_blankline_use_treesitter_scope = true + +------------------------------------------------------------------------------ +g:indent_blankline_context_pattern_highlight *g:indent_blankline_context_pattern_highlight* + + Specifies a map of patterns set in + |g:indent_blankline_context_patterns| to highlight groups. + When the current matching context pattern is in the map, the context + will be highlighted with the corresponding highlight group. + + Only used when |g:indent_blankline_show_current_context| is active + + Default: {} ~ + + Example: > + + let g:indent_blankline_context_pattern_highlight = {'function': 'Function'} + +------------------------------------------------------------------------------ +g:indent_blankline_viewport_buffer *g:indent_blankline_viewport_buffer* + + Sets the buffer of extra lines before and after the current viewport that + are considered when generating indentation and the context. + + Default: 10 ~ + + Example: > + + let g:indent_blankline_viewport_buffer = 20 + +------------------------------------------------------------------------------ +g:indent_blankline_disable_warning_message *g:indent_blankline_disable_warning_message* + + Turns deprecation warning messages off. + + Default: v:false ~ + + Example: > + + let g:indent_blankline_disable_warning_message = v:true + +============================================================================== + 5. COMMANDS *indent-blankline-commands* + +------------------------------------------------------------------------------ +:IndentBlanklineRefresh[!] *IndentBlanklineRefresh* + + Refreshes the indent guides for the current buffer. + Run this with |autocmd| when the file changes. For example after a plugin + formats the file. + + With bang (IndentBlanklineRefresh!) refreshes the indent guides globally. + + By default it is run for: + 1. |FileChangedShellPost| * + 2. |TextChanged| * + 3. |TextChangedI| * + 4. |CompleteChanged| * + 5. |BufWinEnter| * + 6. |Filetype| * + 7. |OptionSet| list,listchars,shiftwidth,tabstop,expandtab + + Example: > + + autocmd User ALEFixPost IndentBlanklineRefresh + +------------------------------------------------------------------------------ +:IndentBlanklineRefreshScroll[!] *IndentBlanklineRefreshScroll* + + Refreshes the indent guides for the current buffer. But tries to reuse as + indent guides that already exist. Only used if we are sure the buffer + content did not change. + + With bang (IndentBlanklineRefresh!) refreshes the indent guides globally. + + By default it is run for: + 1. |WinScrolled| * + + Example: > + + autocmd WinScrolled * IndentBlanklineRefreshScroll + +------------------------------------------------------------------------------ +:IndentBlanklineEnable[!] *IndentBlanklineEnable* + + Enables this plugin for the current buffer. + This overwrites any include/exclude rules. + + With bang (IndentBlanklineEnable!) enables this plugin globally + +------------------------------------------------------------------------------ +:IndentBlanklineDisable[!] *IndentBlanklineDisable* + + Disables this plugin for the current buffer. + This overwrites any include/exclude rules. + + With bang (IndentBlanklineDisable!) disables this plugin globally + +------------------------------------------------------------------------------ +:IndentBlanklineToggle[!] *IndentBlanklineToggle* + + Toggles between |IndentBlanklineEnable| and |IndentBlanklineDisable|. + + With bang (IndentBlanklineToggle!) toggles globally + +============================================================================== + 6. LICENSE *indent-blankline-license* + +The MIT Licence +http://www.opensource.org/licenses/mit-license.php + +Copyright (c) 2023 Lukas Reineke + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in +all copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN +THE SOFTWARE. + +============================================================================== +vim:tw=78:ts=8:ft=help:norl |