vim

Fork of vim, an acceptable text editor
git clone git://git.laack.co/vim.git
Log | Files | Refs | README | LICENSE

helptoc.txt (15664B)


      1 *helptoc.txt*   For Vim version 9.1.  Last change:  2025 Aug 10
      2 
      3 
      4 			  VIM REFERENCE MANUAL
      5 
      6 Interactive table of contents for help buffers and several other filetypes
      7 ==============================================================================
      8 
      9 
     10 1. OVERVIEW						*HelpToc-overview*
     11 
     12 The helptoc.vim plugin provides one command, :HelpToc, which generates a
     13 hierarchical table of contents in a popup window, which is based on the
     14 structure of a Vim buffer.  See |Helptoc-mappings| for a list of supported key
     15 mappings in the popup window.
     16 
     17 It was designed initially for help buffers, but it also works with buffers of
     18 the following types:
     19 	- asciidoc
     20 	- html
     21 	- man
     22 	- markdown
     23 	- terminal
     24 	- tex
     25 	- vim		Note: only with numbered fold markers, e.g. {{{1
     26 	- xhtml
     27 
     28 1.1 The :HelpToc command				*HelpToc-:HelpToc*
     29 
     30 The :HelpToc command takes no arguments and it cannot be executed from an
     31 unsupported filetype.  Also, it cannot be used to generate a table of contents
     32 for an inactive buffer.
     33 
     34 For most buffers of the supported types, :HelpToc may be entered directly
     35 in Vim's |Command-line-mode|.  How to use it from Vim's |Terminal-Job| mode is
     36 explained in |HelpToc-terminal-buftype|.
     37 
     38 You may choose to map :HelpToc to keys making it easier to use.  These are
     39 examples of what could be used: >
     40 
     41 	nnoremap <Leader>ht <Cmd>HelpToc<CR>
     42 	tnoremap <C-t><C-t> <Cmd>HelpToc<CR>
     43 <
     44 
     45 2. DETAILS						*HelpToc-details*
     46 
     47 When the :HelpToc command is executed from an active buffer of a supported
     48 type, a popup window is produced.  The window contains a hierarchical and
     49 interactive table of contents.  The entries are based on the "headings" in
     50 the buffer.
     51 
     52 Jumping to an entry's position in the buffer can be achieved by pressing
     53 enter on the applicable entry.  Navigation, and other commands applicable to
     54 the popup window, such as expanding and contracting levels, fuzzy searching,
     55 and jumping to the previous or next entry (leaving the table of contents
     56 itself displayed, using J and K), is provided at |help-TOC|, so that is not
     57 reproduced in this help file.
     58 
     59 
     60 3. TYPES						*HelpToc-types*
     61 
     62 Some filetypes have more predictable structures than others.  For example,
     63 markdown and asciidoc make the identification of headings (aside from edge
     64 cases, such as when in quotes) straightforward.  Some filetypes do not have
     65 such obvious or reliable headings/levels (particularly help buffers).
     66 Further, in some instances, how to enter the :HelpToc command is not
     67 necessarily obvious, e.g., when in a Vim |terminal-window|.  So, the following
     68 headings address specific details regarding the in-scope types.
     69 
     70 3.1 asciidoc					*HelpToc-asciidoc-filetype*
     71 
     72 The heading levels in asciidoc are typically identified by lines starting
     73 with a "=" (up to six, one per level), one or more blank characters, and the
     74 heading text.  :HelpToc will generate a table of contents based on either
     75 that form of heading type or, because asciidoc also allows for ATX heading
     76 level syntax (i.e., using the "#" character), headings using that format too.
     77 
     78 As asciidoc is very structured, its table of contents entries are presented
     79 in a standardized form - see |HelpToc-standardized-toc|.  So, the initial
     80 "=" or "#" characters and the following space from the related heading are
     81 not included in the table of contents' entries.
     82 
     83 3.2 html					*HelpToc-html-filetype*
     84 
     85 HTML provides for six levels of headings, <h1> to <h6>, which may be either
     86 upper or lower case and preceded by all sorts of content like <!--comments-->.
     87 :HelpToc will produce a table of contents based on the six heading levels.
     88 
     89 As HTML is very structured, its table of contents entries are presented
     90 in a standardized form - see |HelpToc-standardized-toc|.  So, the <h1> to <h6>
     91 tags, any preceding content, and any trailing content after the heading text,
     92 is not included in the table of contents' entries.
     93 
     94 3.3 man pages					*HelpToc-man-filetype*
     95 
     96 Retrieving man pages is typically performed in the terminal.  To use :HelpToc
     97 to generate a table of contents, the |man.vim| filetype plugin is a
     98 prerequisite.  It is provided with Vim, and may be sourced with: >
     99 
    100 	:runtime ftplugin/man.vim
    101 <
    102 Once sourced, the |:Man| command will open the applicable man page in a new
    103 buffer (of "man" filetype).  For example: >
    104 
    105 	:Man pwd
    106 <
    107 Once in the man buffer, entering :HelpToc opens the table of contents popup,
    108 with level 1 containing section names like NAME, SYNOPSIS, etc.  Levels
    109 below 1 include subsections and options, with the level depending on the
    110 number of spaces preceding the content.
    111 
    112 The table of contents for a man buffer's popup window has the same syntax
    113 highlighting as man pages.  This reflects that its content is reproduced
    114 as-is, i.e., no preceding tags, level-indicating data, etc., need be omitted
    115 for optimal presentation.
    116 
    117 3.4 markdown					*HelpToc-markdown-filetype*
    118 
    119 The headings and levels in markdown typically are ATX formatted headings
    120 (lines starting with up to three spaces, one to six "#", then (optionally)
    121 one or blank characters and the heading text).  The alternate form,
    122 setext, uses up to three spaces, the heading 1 text, followed by a
    123 line of one or more "=".  The setext heading 2 is similar, but for one or
    124 more "-" instead of "=".  There is no heading 3+ in setext.  ATX and setext
    125 headings are supported.
    126 
    127 As markdown is very structured, its table of contents entries are presented
    128 in a standardized form - see |HelpToc-standardized-toc|.  So, they do not
    129 include any leading spaces, any initial "#" characters and the following blank
    130 character(s) in the table of contents' entries.
    131 
    132 3.5 terminal					*HelpToc-terminal-buftype*
    133 
    134 There are no explicit "headings" for a terminal buffer.  However, :HelpToc
    135 displays the history of executed shell commands.  Those may be specified
    136 by changing the pattern used to match the Vim terminal's prompt.
    137 See |HelpToc-configuration| for examples.
    138 
    139 To access the terminal's table of contents, from the Vim's |Terminal-Job| mode
    140 enter CTRL-W N to go to |Terminal-Normal| mode.  From there, enter :HelpToc to
    141 generate the table of contents.  If you use the terminal's table of contents
    142 a lot, an appropriate mapping may make it easier than using CTRL-W N - e.g.: >
    143 
    144           tnoremap <C-t><C-t> <Cmd>HelpToc<CR>
    145 <
    146 As the terminal has only "level 1", the table of contents is presented in a
    147 standardized form - see |HelpToc-standardized-toc| - including only the history
    148 list of commands.  The prompt itself is also omitted since it adds no value
    149 repeating it for every entry.
    150 
    151 3.6 tex						*HelpToc-tex-filetype*
    152 
    153 In LaTeX, a document may be structured hierarchically using part, chapter,
    154 and sectioning commands.  Document structure levels are:
    155 	\part{}
    156 	\chapter{}
    157 	\section{}
    158 	\subsection{}
    159 	\subsubsection{}
    160 
    161 To keep things simpler, \part{} is supported, though treated as being at
    162 the same level as chapter.  Consequently, there are four levels displayed
    163 for a tex filetype's table of contents, regardless of the \documentclass{},
    164 i.e., part and chapter (at level 1), section (level 2), subsection (level 3),
    165 and subsubsection (level 4).
    166 
    167 Also supported are:
    168 	- The "*" used to produce unnumbered headings, which are not intended
    169 	  for reproduction in a table of contents: >
    170 		\section*{Unnumbered section heading not produced in the TOC}
    171 <	- Manual toc entries using \addcontentsline, for example: >
    172 		\addcontentsline{toc}{section}{entry in the TOC only!}
    173 <
    174 The table of contents for a tex filetype is in a standardized form -
    175 see |HelpToc-standardized-toc|.  Omitted are: the "\", the part, chapter,
    176 *section, or addcontentsline, and the left and right curly
    177 brackets preceding and following each heading's text.
    178 
    179 3.7 vim						*HelpToc-vim-filetype*
    180 
    181 Vim script and Vim9 script do not have headings or levels inherently like
    182 markup languages.  However, Vim provides for |folds| defined by markers (|{{{|),
    183 which themselves may be succeeded by a number explicitly indicating the fold
    184 level.  This is the structure recognized and supported by helptoc.vim.
    185 So, for example, the following would produce three table of contents entries: >
    186 
    187 	vim9script
    188 	# Variables {{{1
    189 	var b: bool = true
    190 	var s: string = $"Fold markers are great?  {b}!"
    191 	# Functions {{{1
    192 	def MyFunction(): void #{{{2
    193 	  echo s
    194 	enddef
    195 	MyFunction()
    196 <
    197 The table of contents for that script would appear like this:
    198 	Variables
    199 	Functions
    200 	| MyFunction(): void
    201 
    202 Note: The numbered |{{{| marker structure is the only one supported by
    203       helptoc.vim for the vim filetype.
    204 
    205 As the {{{1 to {{{6 markers make the "headings" explicit, the table of
    206 contents is in a standardized form - see |HelpToc-standardized-toc|.
    207 It does not include any leading comment markers (i.e., either # or ") and
    208 omits the markers themselves.
    209 
    210 3.8 xhtml					*HelpToc-xhtml-filetype*
    211 
    212 Although XHTML, being XML, is more strictly structured than HTML/HTML5,
    213 there is no practical difference in treatment required for the xhtml filetype
    214 because, at the heading level, the tags that matter are very similar.
    215 See |HelpToc-html-filetype| for how an xhtml filetype's table of contents is
    216 supported.
    217 
    218 
    219 4. STANDARDIZED TOC				*HelpToc-standardized-toc*
    220 
    221 The table of contents for a help buffer, terminal, or man page, make sense
    222 being presented in the form they appear, minus trailing content (such as tags).
    223 
    224 The table of contents for a markdown, asciidoc, [x]html, terminal, or tex
    225 buffer have superfluous content if the entire line was to be returned.
    226 For example:
    227 - Markdown has "#" characters before headings when using ATX heading notation.
    228 - Asciidoc will have either those or, more often, "=" characters before its
    229   headings.
    230 - HTML, aside from the "<h" headings, may have additional tags, comments,
    231   and whitespace before its headings.
    232 - The Vim terminal has the shell prompt, which adds nothing if repeated for
    233   every heading (and may be very long).
    234 - LaTeX has "\" level indicators like "\section{" and a trailing "}".
    235 Consequently, standardising these filetypes' tables of contents, removing
    236 the "noise", and indicating the contents level of each entry, makes sense.
    237 
    238 HelpToc standardizes the markdown, asciidoc, [x]html, terminal and tex tables
    239 of contents by removing extraneous characters, markup indicators, and tags.
    240 It also applies simple, unobtrusive syntax highlighting to the text and level
    241 indicators.  By default, it will appear like the following example (though
    242 any level indicators will be less prominent, using |NonText| highlight group).
    243 
    244 	Level 1
    245 	| Level 2
    246 	| | Level 3
    247 	| | | Level 4
    248 	| | | | Level 5
    249 	| | | | | Level 6
    250 
    251 Note: The "| " level indicator may be changed - see |HelpToc-configuration|.
    252 
    253 
    254 5. CONFIGURATION				*HelpToc-configuration*
    255 
    256 All configuration is achieved utilizing the g:helptoc dictionary.  Any of the
    257 following may be adjusted to meet your needs or preferences:
    258 
    259 g:helptoc key	 what it controls
    260 -------------	 ----------------
    261 shell_prompt	 The terminal prompt, used for creating a table of contents
    262 		 for the terminal (history list).  The default is,
    263 		 '^\w\+@\w\+:\f\+\$\s', which should match many users' bash
    264 		 prompt.  To change it, either interactively or in your .vimrc,
    265 		 use (for example for a bare Bourne shell "$ " prompt): >
    266 			vim9 g:helptoc.shell_prompt = '^\$\s'
    267 
    268 <level_indicator  This key's value controls the level indicator used in
    269 		 standardized tables of contents.  The default is '| '
    270 		 (i.e., a vertical bar and a space), but may be changed to
    271 		 whatever you want.  For example, for a broken bar and space: >
    272 			vim9 g:helptoc.level_indicator = '¦ '
    273 <
    274 popup_border	 By default, the table of contents border will appear above,
    275 		 right, below, and left of the popup window.  If you prefer
    276 		 not to have the border on the right and left (for example
    277 		 only), you can achieve that with: >
    278 			vim9 g:helptoc.popup_border = [1, 0, 1, 0]
    279 <popup_borderchars
    280 		 The default border characters for the table of contents popup
    281 		 window is the list ['─', '│', '─', '│', '┌', '┐', '┘', '└'].
    282 		 There's nothing wrong with those box drawing characters,
    283 		 though, for example, if you wanted a border that only uses
    284 		 ASCII characters, you could make the border spaces only: >
    285 			vim9 g:helptoc.popup_borderchars = [' ']
    286 <popup_borderhighlight
    287 		 The default border highlight group is Normal.  You can change
    288 		 that, perhaps in combination with popup_borderchars, above,
    289 		 to create a very clearly prominent border.  For example, if
    290 		 the popup_borderchars are made [' '], like above, the border
    291 		 could be made a solid colour different to the background
    292 		 with: >
    293 			vim9 g:helptoc.popup_borderhighlight = ['Cursor']
    294 
    295 <			  Note: Choosing a highlight group that persists when
    296 				colorschemes change may be a good idea if you
    297 				do choose to customize this.
    298 
    299 popup_drag	By default, table of contents popup windows may be dragged
    300 		with a mouse.  If you want to prevent that from happening,
    301 		for whatever reason, you may deactivate it with: >
    302 			vim9 g:helptoc.popup_drag = false
    303 <
    304 popup_close	Table of contents popups have "none" as the default setting
    305 		for this option.  If you use a mouse, you may want either
    306 		to have the option to close popup windows by clicking on them
    307 		or to have a clickable "X" in the top right corner.  For the
    308 		former, use "click", and for the latter, use "button", e.g.: >
    309 			vim9 g:helptoc.popup_close = "button"
    310 <popup_scrollbar
    311 		No scrollbar is provided on helptoc popups by default.  If you
    312 		do want scrollbars (which may be useful as an indicator of how
    313 		far through the table of contents you are, not just for using
    314 		with a mouse) you may choose to have them with: >
    315 			vim9 g:helptoc.popup_scrollbar = true
    316 <
    317 NOTE: Information about the "popup_*" options, above, relate to popup options,
    318 which are explained at the 'second argument' part of |popup_create-arguments|.
    319 
    320 
    321 6. LIMITATIONS					*HelpToc-limitations*
    322 
    323 - The help filetype may have edge case formatting patterns.  Those may result
    324   in some "headings" not being identified and/or may impact the heading levels
    325   of entries in the table of contents itself.
    326 - Terminal window table of contents may not be active (insofar as jumping to
    327   entries going to the Vim terminal's related command line).  For example, if
    328   Vim's terminal is set to Windows PowerShell Core, the table of contents will
    329   display successfully, though the entries go nowhere when Enter, J, or K are
    330   entered on them.
    331 - The tex filetype may have variable sectioning commands depending on the
    332   document class.  Consequently, some compromises are made, though they should
    333   have minimal impact.  Specifically:
    334   * In instances where \part{} and \chapter{} appear in the same buffer, they
    335     will both present at the top level in the table of contents.  This should
    336     be a minor matter because, in many instances, chapters will be in a
    337     separate document using \include{}.
    338   * An article or beamer \documentclass without a \part{} (or any document
    339     with neither any \part{} nor any \chapter{} command) will have no content
    340     at level 1.  Consequently, its table of contents entries will all appear
    341     preceded by at least one "| " (by default) because its headings start at
    342     level 2 (presuming \section{} is present).
    343 - The vim filetype is only supported where numbered fold markers are applied.
    344   This is intentional (including not handling unnumbered markers, which, when
    345   used in combination with numbered ones, may be used for folding comments).
    346   helptoc.vim itself provides an exemplar of how to use numbered fold markers,
    347   not only for folds, but to support generating a useful table of contents
    348   using :HelpToc.
    349 
    350 ==============================================================================
    351 vim:tw=78:ts=8:fo=tcq2:ft=help: