diff options
Diffstat (limited to 'vim/doc/tagbar.txt')
| -rw-r--r-- | vim/doc/tagbar.txt | 1016 |
1 files changed, 0 insertions, 1016 deletions
diff --git a/vim/doc/tagbar.txt b/vim/doc/tagbar.txt deleted file mode 100644 index cb9a3e3..0000000 --- a/vim/doc/tagbar.txt +++ /dev/null @@ -1,1016 +0,0 @@ -*tagbar.txt* Display tags of a file in their correct scope - -Author: Jan Larres <jan@majutsushi.net> -Licence: Vim licence, see |license| -Homepage: http://majutsushi.github.com/tagbar/ -Version: 2.3 - -============================================================================== -Contents *tagbar* *tagbar-contents* - - 1. Intro ........................... |tagbar-intro| - Pseudo-tags ................... |tagbar-pseudotags| - Supported features ............ |tagbar-features| - Other ctags-compatible programs |tagbar-other| - 2. Requirements .................... |tagbar-requirements| - 3. Installation .................... |tagbar-installation| - 4. Usage ........................... |tagbar-usage| - Commands ...................... |tagbar-commands| - Key mappings .................. |tagbar-keys| - 5. Configuration ................... |tagbar-configuration| - Highlight colours ............. |tagbar-highlight| - Automatically opening Tagbar .. |tagbar-autoopen| - 6. Extending Tagbar ................ |tagbar-extend| - 7. Troubleshooting & Known issues .. |tagbar-issues| - 8. History ......................... |tagbar-history| - 9. Todo ............................ |tagbar-todo| - 10. Credits ......................... |tagbar-credits| - -============================================================================== -1. Intro *tagbar-intro* - -Tagbar is a plugin for browsing the tags of source code files. It provides a -sidebar that displays the ctags-generated tags of the current file, ordered by -their scope. This means that for example methods in C++ are displayed under -the class they are defined in. - -Let's say we have the following code inside of a C++ file: -> - namespace { - char a; - - class Foo - { - public: - Foo(); - ~Foo(); - private: - int var; - }; - }; -< -Then Tagbar would display the tag information like so: -> - __anon1* : namespace - Foo : class - +Foo() - +~Foo() - -var - a -< -This example shows several important points. First, the tags are listed -indented below the scope they are defined in. Second, the type of a scope is -listed after its name and a colon. Third, tags for which the access/visibility -information is known are prefixed with a symbol indicating that. - ------------------------------------------------------------------------------- -PSEUDO-TAGS *tagbar-pseudotags* - -The example also introduces the concept of "pseudo-tags". Pseudo-tags are tags -that are not explicitly defined in the file but have children in it. In this -example the namespace doesn't have a name and thus ctags doesn't generate a -tag for it, but since it has children it still needs to be displayed using an -auto-generated name. - -Another case where pseudo-tags appear is in C++ implementation files. Since -classes are usually defined in a header file but the member methods and -variables in the implementation file the class itself won't generate a tag -in that file. - -Since pseudo-tags don't really exist they cannot be jumped to from the Tagbar -window. - -Pseudo-tags are denoted with an asterisk ('*') at the end of their name. - ------------------------------------------------------------------------------- -SUPPORTED FEATURES *tagbar-features* - -The following features are supported by Tagbar: - - - Display tags under their correct scope. - - Automatically update the tags when switching between buffers and editing - files. - - Display visibility information of tags if available. - - Highlight the tag near the cursor while editing files. - - Jump to a tag from the Tagbar window. - - Display the complete prototype of a tag. - - Tags can be sorted either by name or order of appearance in the file. - - Scopes can be folded to hide uninteresting information. - - Supports all of the languages that ctags does, i.e. Ant, Assembler, ASP, - Awk, Basic, BETA, C, C++, C#, COBOL, DosBatch, Eiffel, Erlang, Flex, - Fortran, HTML, Java, JavaScript, Lisp, Lua, Make, MatLab, OCaml, Pascal, - Perl, PHP, Python, REXX, Ruby, Scheme, Shell script, SLang, SML, SQL, Tcl, - Tex, Vera, Verilog, VHDL, Vim and YACC. - - Can be extended to support arbitrary new types. - ------------------------------------------------------------------------------- -OTHER CTAGS-COMPATIBLE PROGRAMS *tagbar-other* - -Tagbar theoretically also supports filetype-specific programs that can output -tag information that is compatible with ctags. However due to potential -incompatibilities this may not always completely work. Tagbar has been tested -with doctorjs/jsctags and will use that if present, other programs require -some configuration (see |tagbar-extend|). If a program does not work even with -correct configuration please contact me. - -Note: Please check |tagbar-issues| for some possible issues with jsctags. - -============================================================================== -2. Requirements *tagbar-requirements* - -The following requirements have to be met in order to be able to use tagbar: - - - Vim 7.0 or higher. Older versions will not work since Tagbar uses data - structures that were only introduced in Vim 7. - - Exuberant ctags 5.5 or higher. Ctags is the program that generates the - tag information that Tagbar uses. It is shipped with most Linux - distributions, otherwise it can be downloaded from the following - website: - - http://ctags.sourceforge.net/ - - Tagbar will work on any platform that ctags runs on -- this includes - UNIX derivatives, Mac OS X and Windows. Note that other versions like - GNU ctags will not work. - Tagbar generates the tag information by itself and doesn't need (or use) - already existing tag files. - - File type detection must be turned on in vim. This can be done with the - following command in your vimrc: -> - filetype on -< - See |filetype| for more information. - - Tagbar will not work in |restricted-mode| or with 'compatible' set. - -============================================================================== -3. Installation *tagbar-installation* - -Use the normal Vimball install method for installing tagbar.vba: -> - vim tagbar.vba - :so % - :q -< -Alternatively you can clone the git repository and then add the path to -'runtimepath' or use the pathogen plugin. Don't forget to run |:helptags| if -you're not using pathogen. - -If the ctags executable is not installed in one of the directories in your -$PATH environment variable you have to set the g:tagbar_ctags_bin variable, -see |g:tagbar_ctags_bin|. - -============================================================================== -4. Usage *tagbar-usage* - -There are essentially two ways to use Tagbar: - - 1. Have it running all the time in a window on the side of the screen. In - this case Tagbar will update its contents whenever the source file is - changed and highlight the tag the cursor is currently on in the file. If - a tag is selected in Tagbar the file window will jump to the tag and the - Tagbar window will stay open. |g:tagbar_autoclose| has to be unset for - this mode. - 2. Only open Tagbar when you want to jump to a specific tag and have it - close automatically once you have selected one. This can be useful for - example for small screens where a permanent window would take up too much - space. You have to set the option |g:tagbar_autoclose| in this case. The - cursor will also automatically jump to the Tagbar window when opening it. - -Opening and closing the Tagbar window~ -Use |:TagbarOpen| or |:TagbarToggle| to open the Tagbar window if it is -closed. By default the window is opened on the right side, set the option -|g:tagbar_left| to open it on the left instead. If the window is already open, -|:TagbarOpen| will jump to it and |:TagbarToggle| will close it again. -|:TagbarClose| will simply close the window if it is open. - -It is probably a good idea to assign a key to these commands. For example, put -this in your |vimrc|: -> - nnoremap <silent> <F9> :TagbarToggle<CR> -< -You can then open and close Tagbar by simply pressing the <F9> key. - -You can also use |:TagbarOpenAutoClose| to open the Tagbar window, jump to it -and have it close automatically on tag selection regardless of the -|g:tagbar_autoclose| setting. - -Jumping to tags~ -When you're inside the Tagbar window you can jump to the definition of a tag -by moving the cursor to a tag and pressing <Enter> or double-clicking on it -with the mouse. The source file will then move to the definition and put the -cursor in the corresponding line. This won't work for pseudo-tags. - -Sorting~ -You can sort the tags in the Tagbar window in two ways: by name or by file -order. Sorting them by name simply displays the tags in their alphabetical -order under their corresponding scope. Sorting by file order means that the -tags keep the order they have in the source file, but are still associated -with the correct scope. You can change the sort order by pressing the "s" key -in the Tagbar window. The current sort order is displayed in the statusbar of -the Tagbar window. - -Folding~ -The displayed scopes (and unscoped types) can be folded to hide uninteresting -information. Mappings similar to Vim's built-in ones are provided. Folds can -also be opened and closed by clicking on the fold icon with the mouse. - -Displaying the prototype of a tag~ -Tagbar can display the prototype of a tag. More precisely it can display the -line in which the tag is defined. This can be done by either pressing <Space> -when on a tag or hovering over a tag with the mouse. In the former case the -prototype will be displayed in the command line |Command-line|, in the latter -case it will be displayed in a pop-up window. The prototype will also be -displayed when the cursor stays on a tag for 'updatetime' milliseconds. - ------------------------------------------------------------------------------- -COMMANDS *tagbar-commands* - -:TagbarOpen [{flags}] - Open the Tagbar window if it is closed. - - Additional behaviour can be specified with the optional {flags} argument. - It is a string which can contain these character flags: - 'f' Jump to Tagbar window when opening (just as if |g:tagbar_autofocus| - were set to 1) - 'j' Jump to Tagbar window if already open - 'c' Close Tagbar on tag selection (just as if |g:tagbar_autoclose| were - set to 1, but doesn't imply 'f') - - For example, the following command would always jump to the Tagbar window, - opening it first if necessary, but keep it open after selecting a tag - (unless |g:tagbar_autoclose| is set): > - :TagbarOpen fj -< -:TagbarClose - Close the Tagbar window if it is open. - -:TagbarToggle - Open the Tagbar window if it is closed or close it if it is open. - -:TagbarOpenAutoClose - Open the Tagbar window, jump to it and close it on tag selection. This is - an alias for ":TagbarOpen fc". - -:TagbarSetFoldlevel {number} - Set the foldlevel of the tags of the current file to {number}. The - foldlevel of tags in other files remains unaffected. Works in the same way - as 'foldlevel'. - -:TagbarShowTag - Open the parent folds of the current tag in the file window as much as - needed for the tag to be visible in the Tagbar window. - -:TagbarDebug [logfile] - Start debug mode. This will write debug messages to file [logfile] while - using Tagbar. If no argument is given "tagbardebug.log" in the current - directory is used. Note: an existing file will be overwritten! - -:TagbarDebugEnd - End debug mode, debug messages will no longer be written to the logfile. - ------------------------------------------------------------------------------- -KEY MAPPINGS *tagbar-keys* - -The following mappings are valid in the Tagbar window: - -<F1> Display key mapping help. -<CR>/<Enter> Jump to the tag under the cursor. Doesn't work for pseudo-tags - or generic headers. -p Jump to the tag under the cursor, but stay in the Tagbar window. -<LeftMouse> When on a fold icon, open or close the fold depending on the - current state. -<2-LeftMouse> Same as <CR>. See |g:tagbar_singleclick| if you want to use a - single- instead of a double-click. -<Space> Display the prototype of the current tag (i.e. the line defining - it) in the command line. -+/zo Open the fold under the cursor. --/zc Close the fold under the cursor or the current one if there is - no fold under the cursor. -o/za Toggle the fold under the cursor or the current one if there is - no fold under the cursor. -*/zR Open all folds by setting foldlevel to 99. -=/zM Close all folds by setting foldlevel to 0. -<C-N> Go to the next top-level tag. -<C-P> Go to the previous top-level tag. -s Toggle sort order between name and file order. -x Toggle zooming the window. -q Close the Tagbar window. - -============================================================================== -5. Configuration *tagbar-configuration* - - *g:tagbar_ctags_bin* -g:tagbar_ctags_bin~ -Default: empty - -Use this option to specify the location of your ctags executable. Only needed -if it is not in one of the directories in your $PATH environment variable. - -Example: -> - let g:tagbar_ctags_bin = 'C:\Ctags5.8\ctags.exe' -< - - *g:tagbar_left* -g:tagbar_left~ -Default: 0 - -By default the Tagbar window will be opened on the right-hand side of vim. Set -this option to open it on the left instead. - -Example: -> - let g:tagbar_left = 1 -< - - *g:tagbar_width* -g:tagbar_width~ -Default: 40 - -Width of the Tagbar window in characters. - -Example: -> - let g:tagbar_width = 30 -< - - *g:tagbar_autoclose* -g:tagbar_autoclose~ -Default: 0 - -If you set this option the Tagbar window will automatically close when you -jump to a tag. This implies |g:tagbar_autofocus|. - -Example: -> - let g:tagbar_autoclose = 1 -< - - *g:tagbar_autofocus* -g:tagbar_autofocus~ -Default: 0 - -If you set this option the cursor will move to the Tagbar window when it is -opened. - -Example: -> - let g:tagbar_autofocus = 1 -< - - *g:tagbar_sort* -g:tagbar_sort~ -Default: 1 - -If this option is set the tags are sorted according to their name. If it is -unset they are sorted according to their order in the source file. Note that -in the second case Pseudo-tags are always sorted before normal tags of the -same kind since they don't have a real position in the file. - -Example: -> - let g:tagbar_sort = 0 -< - - *g:tagbar_compact* -g:tagbar_compact~ -Default: 0 - -Setting this option will result in Tagbar omitting the short help at the -top of the window and the blank lines in between top-level scopes in order to -save screen real estate. - -Example: -> - let g:tagbar_compact = 1 -< - - *g:tagbar_expand* -g:tagbar_expand~ -Default: 0 - -If this option is set the Vim window will be expanded by the width of the -Tagbar window if using a GUI version of Vim. - -Example: -> - let g:tagbar_expand = 1 -< - - *g:tagbar_singleclick* -g:tagbar_singleclick~ -Default: 0 - -If this option is set then a single- instead of a double-click is used to jump -to the tag definition. - -Example: -> - let g:tagbar_singleclick = 1 -< - - *g:tagbar_foldlevel* -g:tagbar_foldlevel~ -Default: 99 - -The initial foldlevel for folds in the Tagbar window. Fold with a level higher -than this number will be closed. - -Example: -> - let g:tagbar_foldlevel = 2 -< - - *g:tagbar_iconchars* -g:tagbar_iconchars~ - -Since the display of the icons used to indicate open or closed folds depends -on the actual font used, different characters may be optimal for different -fonts. With this variable you can set the icons to characters of your liking. -The first character in the list specifies the icon to use for a closed fold, -and the second one for an open fold. - -Examples (don't worry if some the characters aren't displayed correctly, just -choose other characters in that case): -> - let g:tagbar_iconchars = ['▶', '▼'] (default on Linux and Mac OS X) - let g:tagbar_iconchars = ['▾', '▸'] - let g:tagbar_iconchars = ['▷', '◢'] - let g:tagbar_iconchars = ['+', '-'] (default on Windows) -< - - *g:tagbar_autoshowtag* -g:tagbar_autoshowtag~ -Default: 0 - -If this variable is set and the current tag is inside of a closed fold then -the folds will be opened as much as needed for the tag to be visible so it can -be highlighted. If it is not set then the folds won't be opened and the parent -tag will be highlighted instead. You can use the TagbarShowTag command to open -the folds manually. - -Example: -> - let g:tagbar_autoshowtag = 1 -< - - *g:tagbar_updateonsave_maxlines* -g:tagbar_updateonsave_maxlines~ -Default: 5000 - -If the current file has fewer lines than the value of this variable, Tagbar -will update immediately after saving the file. If it is longer then the update -will only happen on the |CursorHold| event and when switching buffers (or -windows). This is to prevent the time it takes to save a large file from -becoming annoying in case you have a slow computer. If you have a fast -computer you can set it to a higher value. - -Example: -> - let g:tagbar_updateonsave_maxlines = 10000 -< - - *g:tagbar_systemenc* -g:tagbar_systemenc~ -Default: value of 'encoding' - -This variable is for cases where the character encoding of your operating -system is different from the one set in Vim, i.e. the 'encoding' option. For -example, if you use a Simplified Chinese Windows version that has a system -encoding of "cp936", and you have set 'encoding' to "utf-8", then you would -have to set this variable to "cp936". - -Example: -> - let g:tagbar_systemenc = 'cp936' -< - ------------------------------------------------------------------------------- -HIGHLIGHT COLOURS *tagbar-highlight* - -All of the colours used by Tagbar can be customized. Here is a list of the -highlight groups that are defined by Tagbar: - -TagbarComment - The help at the top of the buffer. - -TagbarKind - The header of generic "kinds" like "functions" and "variables". - -TagbarNestedKind - The "kind" headers in square brackets inside of scopes. - -TagbarScope - Tags that define a scope like classes, structs etc. - -TagbarType - The type of a tag or scope if available. - -TagbarSignature - Function signatures. - -TagbarPseudoID - The asterisk (*) that signifies a pseudo-tag. - -TagbarFoldIcon - The fold icon on the left of foldable tags. - -TagbarHighlight - The colour that is used for automatically highlighting the current tag. - -TagbarAccessPublic - The "public" visibility/access symbol. - -TagbarAccessProtected - The "protected" visibility/access symbol. - -TagbarAccessPrivate - The "private" visibility/access symbol. - -If you want to change any of those colours put a line like the following in -your vimrc: -> - highlight TagbarScope guifg=Green ctermfg=Green -< -See |:highlight| for more information. - ------------------------------------------------------------------------------- -AUTOMATICALLY OPENING TAGBAR *tagbar-autoopen* - -Since there are several different situations in which you might want to open -Tagbar automatically there is no single option to enable automatic opening. -Instead, autocommands can be used together with a convenience function that -opens Tagbar only if a supported file is open(ed). - -If you want to open Tagbar automatically on Vim startup no matter what put -this into your vimrc: -> - autocmd VimEnter * nested :TagbarOpen -< -If you want to open it only if you're opening Vim with a supported file/files -use this instead: -> - autocmd VimEnter * nested :call tagbar#autoopen() -< -For opening Tagbar also if you open a supported file in an already running -Vim: -> - autocmd FileType * nested :call tagbar#autoopen() -< -And if you only want to open Tagbar only for specific filetypes, not for all -of the supported ones: -> - autocmd FileType c,cpp nested :TagbarOpen -< -Check out |autocmd.txt| if you want it to open automatically in more -complicated cases. - -============================================================================== -6. Extending Tagbar *tagbar-extend* - -Tagbar has a flexible mechanism for extending the existing file type (i.e. -language) definitions. This can be used both to change the settings of the -existing types and to add completely new types. A complete configuration -consists of a type definition for Tagbar in your |vimrc| and optionally a -language definition for ctags in case you want to add a new language. - -Before writing your own extension have a look at the wiki -(https://github.com/majutsushi/tagbar/wiki/Support-for-additional-filetypes) -or try googling for existing ones. If you do end up creating your own -extension please consider adding it to the wiki so that others will be able to -use it, too. - -Every type definition in Tagbar is a dictionary with the following keys: - -ctagstype: The name of the language as recognized by ctags. Use the command > - ctags --list-languages -< to get a list of the languages ctags supports. The case doesn't - matter. -kinds: A list of the "language kinds" that should be listed in Tagbar, - ordered by the order they should appear in in the Tagbar window. - Use the command > - ctags --list-kinds={language name} -< to get a list of the kinds ctags supports for a given language. An - entry in this list is a string with two or three parts separated - by a colon: the first part is the one-character abbreviation that - ctags uses, and the second part is an arbitrary string that will - be used in Tagbar as the header for the tags of this kind that are - not listed under a specific scope. The optional third part - determines whether tags of this kind should be folded by default, - with 1 meaning they should be folded and 0 they should not. If - this part is omitted the tags will not be folded by default. For - example, the string > - "f:functions:1" -< would list all the function definitions in a file under the header - "functions" and fold them. -sro: The scope resolution operator. For example, in C++ it is "::" and - in Java it is ".". If in doubt run ctags as shown below and check - the output. -kind2scope: A dictionary describing the mapping of tag kinds (in their - one-character representation) to the scopes their children will - appear in, for example classes, structs etc. - Unfortunately there is no ctags option to list the scopes, you - have to look at the tags ctags generates manually. For example, - let's say we have a C++ file "test.cpp" with the following - contents: > - class Foo - { - public: - Foo(); - ~Foo(); - private: - int var; - }; -< We then run ctags in the following way: > - ctags -f - --format=2 --excmd=pattern --extra= --fields=nksaSmt test.cpp -< Then the output for the variable "var" would look like this: > - var tmp.cpp /^ int var;$/;" kind:m line:11 class:Foo access:private -< This shows that the scope name for an entry in a C++ class is - simply "class". So this would be the word that the "kind" - character of a class has to be mapped to. -scope2kind: The opposite of the above, mapping scopes to the kinds of their - parents. Most of the time it is the exact inverse of the above, - but in some cases it can be different, for example when more than - one kind maps to the same scope. If it is the exact inverse for - your language you only need to specify one of the two keys. -replace: If you set this entry to 1 your definition will completely replace -{optional} an existing default definition. This is useful if you want to - disable scopes for a file type for some reason. Note that in this - case you have to provide all the needed entries yourself! -sort: This entry can be used to override the global sort setting for -{optional} this specific file type. The meaning of the value is the same as - with the global setting, that is if you want to sort tags by name - set it to 1 and if you want to sort them according to their order - in the file set it to 0. -deffile: The path to a file with additional ctags definitions (see the -{optional} section below on adding a new definition for what exactly that - means). This is especially useful for ftplugins since they can - provide a complete type definition with ctags and Tagbar - configurations without requiring user intervention. - Let's say you have an ftplugin that adds support for the language - "mylang", and your directory structure looks like this: > - ctags/mylang.cnf - ftplugin/mylang.vim -< Then the "deffile" entry would look like this to allow for the - plugin to be installed in an arbitray location (for example - with pathogen): > - - 'deffile' : expand('<sfile>:p:h:h') . '/ctags/mylang.cnf' -< -ctagsbin: The path to a filetype-specific ctags-compatible program like -{optional} jsctags. Set it in the same way as |g:tagbar_ctags_bin|. jsctags is - used automatically if found in your $PATH and does not have to be - set in that case. If it is not in your path you have to set this - key, the rest of the configuration should not be necessary (unless - you want to change something, of course). -ctagsargs: The arguments to be passed to the filetype-specific ctags program -{optional} (without the filename). Make sure you set an option that makes the - program output its data on stdout. Not used for the normal ctags - program. - - -You then have to assign this dictionary to a variable in your vimrc with the -name -> - g:tagbar_type_{vim filetype} -< -For example, for C++ the name would be "g:tagbar_type_cpp". If you don't know -the vim file type then run the following command: -> - :set filetype? -< -and vim will display the file type of the current buffer. - -Example: C++~ -Here is a complete example that shows the default configuration for C++ as -used in Tagbar. This is just for illustration purposes since user -configurations will usually be less complicated. -> - let g:tagbar_type_cpp = { - \ 'ctagstype' : 'c++', - \ 'kinds' : [ - \ 'd:macros:1', - \ 'p:prototypes:1', - \ 'g:enums', - \ 'e:enumerators', - \ 't:typedefs', - \ 'n:namespaces', - \ 'c:classes', - \ 's:structs', - \ 'u:unions', - \ 'f:functions', - \ 'm:members', - \ 'v:variables' - \ ], - \ 'sro' : '::', - \ 'kind2scope' : { - \ 'g' : 'enum', - \ 'n' : 'namespace', - \ 'c' : 'class', - \ 's' : 'struct', - \ 'u' : 'union' - \ }, - \ 'scope2kind' : { - \ 'enum' : 'g', - \ 'namespace' : 'n', - \ 'class' : 'c', - \ 'struct' : 's', - \ 'union' : 'u' - \ } - \ } -< - -Which of the keys you have to specify depends on what you want to do. - -Changing an existing definition~ -If you want to change an existing definition you only need to specify the -parts that you want to change. It probably only makes sense to change "kinds" -and/or "scopes", which would be the case if you wanted to exclude certain -kinds from appearing in Tagbar or if you want to change their order. As an -example, if you didn't want Tagbar to show prototypes for C++ files and switch -the order of enums and typedefs, you would do it like this: -> - let g:tagbar_type_cpp = { - \ 'kinds' : [ - \ 'd:macros:1', - \ 'g:enums', - \ 't:typedefs', - \ 'e:enumerators', - \ 'n:namespaces', - \ 'c:classes', - \ 's:structs', - \ 'u:unions', - \ 'f:functions', - \ 'm:members', - \ 'v:variables' - \ ] - \ } -< -Compare with the complete example above to see the difference. - -Adding a definition for a new language/file type~ -In order to be able to add a new language to Tagbar you first have to create a -configuration for ctags that it can use to parse the files. This can be done -in two ways: - - 1. Use the --regex argument for specifying regular expressions that are used - to parse the files. An example of this is given below. A disadvantage of - this approach is that you can't specify scopes. - 2. Write a parser plugin in C for ctags. This approach is much more powerful - than the regex approach since you can make use of all of ctags' - functionality but it also requires much more work. Read the ctags - documentation for more information about how to do this. - -For the first approach the only keys that are needed in the Tagbar definition -are "ctagstype" and "kinds". A definition that supports scopes has to define -those two and in addition "scopes", "sro" and at least one of "kind2scope" and -"scope2kind". - -Let's assume we want to add support for LaTeX to Tagbar using the regex -approach. First we put the following text into ~/.ctags or a file pointed to -by the "deffile" definition entry: -> - --langdef=latex - --langmap=latex:.tex - --regex-latex=/^\\tableofcontents/TABLE OF CONTENTS/s,toc/ - --regex-latex=/^\\frontmatter/FRONTMATTER/s,frontmatter/ - --regex-latex=/^\\mainmatter/MAINMATTER/s,mainmatter/ - --regex-latex=/^\\backmatter/BACKMATTER/s,backmatter/ - --regex-latex=/^\\bibliography\{/BIBLIOGRAPHY/s,bibliography/ - --regex-latex=/^\\part[[:space:]]*(\[[^]]*\])?[[:space:]]*\{([^}]+)\}/PART \2/s,part/ - --regex-latex=/^\\part[[:space:]]*\*[[:space:]]*\{([^}]+)\}/PART \1/s,part/ - --regex-latex=/^\\chapter[[:space:]]*(\[[^]]*\])?[[:space:]]*\{([^}]+)\}/CHAP \2/s,chapter/ - --regex-latex=/^\\chapter[[:space:]]*\*[[:space:]]*\{([^}]+)\}/CHAP \1/s,chapter/ - --regex-latex=/^\\section[[:space:]]*(\[[^]]*\])?[[:space:]]*\{([^}]+)\}/\. \2/s,section/ - --regex-latex=/^\\section[[:space:]]*\*[[:space:]]*\{([^}]+)\}/\. \1/s,section/ - --regex-latex=/^\\subsection[[:space:]]*(\[[^]]*\])?[[:space:]]*\{([^}]+)\}/\.\. \2/s,subsection/ - --regex-latex=/^\\subsection[[:space:]]*\*[[:space:]]*\{([^}]+)\}/\.\. \1/s,subsection/ - --regex-latex=/^\\subsubsection[[:space:]]*(\[[^]]*\])?[[:space:]]*\{([^}]+)\}/\.\.\. \2/s,subsubsection/ - --regex-latex=/^\\subsubsection[[:space:]]*\*[[:space:]]*\{([^}]+)\}/\.\.\. \1/s,subsubsection/ - --regex-latex=/^\\includegraphics[[:space:]]*(\[[^]]*\])?[[:space:]]*(\[[^]]*\])?[[:space:]]*\{([^}]+)\}/\3/g,graphic+listing/ - --regex-latex=/^\\lstinputlisting[[:space:]]*(\[[^]]*\])?[[:space:]]*(\[[^]]*\])?[[:space:]]*\{([^}]+)\}/\3/g,graphic+listing/ - --regex-latex=/\\label[[:space:]]*\{([^}]+)\}/\1/l,label/ - --regex-latex=/\\ref[[:space:]]*\{([^}]+)\}/\1/r,ref/ - --regex-latex=/\\pageref[[:space:]]*\{([^}]+)\}/\1/p,pageref/ -< -This will create a new language definition with the name "latex" and associate -it with files with the extension ".tex". It will also define the kinds "s" for -sections, chapters and the like, "g" for included graphics, "l" for labels, -"r" for references and "p" for page references. See the ctags documentation -for more information about the exact syntax. - -Now we have to create the Tagbar language definition in our vimrc: -> - let g:tagbar_type_tex = { - \ 'ctagstype' : 'latex', - \ 'kinds' : [ - \ 's:sections', - \ 'g:graphics', - \ 'l:labels', - \ 'r:refs:1', - \ 'p:pagerefs:1' - \ ], - \ 'sort' : 0, - \ 'deffile' : expand('<sfile>:p:h:h') . '/ctags/latex.cnf' - \ } -< -The "deffile" field is of course only needed if the ctags definition actually -is in that file and not in ~/.ctags. - -Sort has been disabled for LaTeX so that the sections appear in their correct -order. They unfortunately can't be shown nested with their correct scopes -since as already mentioned the regular expression approach doesn't support -that. - -Tagbar should now be able to show the sections and other tags from LaTeX -files. - -============================================================================== -7. Troubleshooting & Known issues *tagbar-issues* - -As a general rule, if the tag information displayed by Tagbar is wrong (for -example, a method doesn't show up or is in the wrong place) you should first -try running ctags manually to see whether ctags reports the wrong information -or whether that information is correct and Tagbar does something wrong. To run -ctags manually execute the following command in a terminal: -> - ctags -f - --format=2 --excmd=pattern --extra= --fields=nksaSmt myfile -< -If you set the |g:tagbar_ctags_bin| variable you probably have to use the same -value here instead of simply "ctags". - -If Tagbar doesn't seem to work at all, but you don't get any error messages, -you can use Tagbar's debug mode to try to find the source of the problem (see -|tagbar-commands| on how to invoke it). In that case you should especially pay -attention to the reported file type and the ctags command line in the log -file. - - - - jsctags has to be newer than 2011-01-06 since it needs the "-f" option to - work. Also, the output of jsctags seems to be a bit unreliable at the - moment (especially regarding line numbers), so if you notice some strange - behaviour with it please run it manually in a terminal to check whether - the bug is in jsctags or Tagbar. - - - Nested pseudo-tags cannot be properly parsed since only the direct parent - scope of a tag gets assigned a type, the type of the grandparents is not - reported by ctags (assuming the grandparents don't have direct, real - children). - - For example, if we have a C++ file with the following content: -> - foo::Bar::init() - { - // ... - } - foo::Baz::method() - { - // ... - } -< - In this case the type of "foo" is not known. Is it a namespace? A class? - For this reason the methods are displayed in Tagbar like this: -> - foo::Bar* : class - init() - foo::Baz* : class - method() -< - - Scope-defining tags at the top level that have the same name but a - different kind/scope type can lead to an incorrect display. For example, - the following Python code will incorrectly insert a pseudo-tag "Inner2" - into the "test" class: -> - class test: - class Inner: - def foo(self): - pass - - def test(): - class Inner2: - def bar(self): - pass -< - I haven't found a clean way around this yet, but it shouldn't be much of a - problem in practice anyway. Tags with the same name at any other level are - no problem, though. - -============================================================================== -8. History *tagbar-history* - -2.3 (2011-12-24) - - Add a convenience function that allows more flexible ways to - automatically open Tagbar. - - Replace option tagbar_usearrows with tagbar_iconchars to allow custom - characters to be specified. This helps with fonts that don't display the - default characters properly. - - Remove the need to provide the complete jsctags configuration if jsctags - is not found in $PATH, now only the concrete path has to be specified. - - Add debugging functionality. - -2.2 (2011-11-26) - - Small incompatible change: TagbarOpen now doesn't jump to the Tagbar - window anymore if it is already open. Use "TagbarOpen j" instead or see - its documentation for more options. - - Tags inside of scopes now have a header displaying their "kind". - - The Tagbar contents are now immediately updated on save for files - smaller than a configurable size. - - Tagbar can now be configured to jump to a tag with only a single-click - instead of a double-click. - - Most of the script has been moved to the |autoload| directory, so Vim - startup should be faster (thanks to Kien N). - - Jumping to tags should work most of the time even if the file has been - modified and not saved. - - If Ctags has been installed into the default location using Homebrew or - MacPorts it should now be found automatically. - - Several bugfixes. - -2.1 (2011-05-29) - - Make Tagbar work in (hopefully) all cases under Windows - - Handle cases where 'encoding' is different from system encoding, for - example on a Chinese Windows with 'encoding' set to "utf-8" (see manual - for details in case it doesn't work out-of-the-box) - - Fixed a bug with the handling of subtypes like "python.django" - - If a session got saved with Tagbar open it now gets restored properly - - Locally reset foldmethod/foldexpr in case foldexpr got set to something - expensive globally - - Tagbar now tries hard to go to the correct window when jumping to a tag - - Explain some possible issues with the current jsctags version in the - manual - - Explicitly check for some possible configuration problems to be able to - give better feedback - - A few other small fixes - -2.0.1 (2011-04-26) - - Fix sorting bug when 'ignorecase' is set - -2.0 (2011-04-26) - - Folding now works correctly. Folds will be preserved when leaving the - Tagbar window and when switching between files. Also tag types can be - configured to be folded by default, which is useful for things like - includes and imports. - - DoctorJS/jsctags and other compatible programs are now supported. - - All of the highlight groups can now be overridden. - - Added keybinding to quickly jump to next/previous top-level tag. - - Added Taglist's "p" keybinding for jumping to a tag without leaving the - Tagbar window. - - Several bugfixes and other small improvements. - -1.5 (2011-03-06) - - Type definitions can now include a path to a file with the ctags - definition. This is especially useful for ftplugins that can now ship - with a complete ctags and Tagbar configuration without requiring user - intervention. Thanks to Jan Christoph Ebersbach for the suggestion. - - Added autofocus setting by Taybin Rutkin. This will put the cursor in - the Tagbar window when it is opened. - - The "scopes" field is no longer needed in type definitions, the - information is already there in "scope2kind". Existing definitions will - be ignored. - - Some fixes and improvements related to redrawing and window switching. - -1.2 (2011-02-28) - - Fix typo in Ruby definition - -1.1 (2011-02-26) - - Don't lose syntax highlighting when ':syntax enable' is called - - Allow expanding the Vim window when Tagbar is opened - -1.0 (2011-02-23) - - Initial release - -============================================================================== -9. Todo *tagbar-todo* - - - Allow filtering the Tagbar content by some criteria like tag name, - visibility, kind ... - - Integrate Tagbar with the FSwitch plugin to provide header file - information in C/C++. - - Allow jumping to a tag in the preview window, a split window or a new tab. - -============================================================================== -10. Credits *tagbar-credits* - -Tagbar was written by Jan Larres and is released under the Vim licence, see -|license|. It was heavily inspired by the Taglist plugin by Yegappan -Lakshmanan and uses a small amount of code from it. - -Original taglist copyright notice: -Permission is hereby granted to use and distribute this code, with or without -modifications, provided that this copyright notice is copied with it. Like -anything else that's free, taglist.vim is provided *as is* and comes with no -warranty of any kind, either expressed or implied. In no event will the -copyright holder be liable for any damamges resulting from the use of this -software. - -The folding technique was inspired by NERDTree by Martin Grenfell. - -Thanks to the following people for code contributions, feature suggestions etc: -Jan Christoph Ebersbach -Leandro Freitas -Seth Milliken -Kien N -pielgrzym -Taybin Rutkin - -============================================================================== - vim: tw=78 ts=8 sw=8 sts=8 noet ft=help |