Version 2.4

doc/tagbar.txt

@@ -1,33 +1,34 @@
-*tagbar.txt*	Display tags of a file in their correct scope
+*tagbar.txt*    Display tags of a file ordered by scope
 
-Author:		Jan Larres <jan@majutsushi.net>
-Licence:	Vim licence, see |license|
-Homepage:	http://majutsushi.github.com/tagbar/
-Version:	2.3
+Author:         Jan Larres <jan@majutsushi.net>
+Licence:        Vim licence, see |license|
+Homepage:       http://majutsushi.github.com/tagbar/
+Version:        2.4
 
 ==============================================================================
-Contents					*tagbar* *tagbar-contents*
+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|
+              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|
+              Show current tag in statusline  |tagbar-statusline|
+         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*
+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
@@ -36,27 +37,27 @@ the class they are defined in.
 
 Let's say we have the following code inside of a C++ file:
 >
-    namespace {
-        char a;
+        namespace {
+            char a;
 
-        class Foo
-        {
-        public:
-            Foo();
-            ~Foo();
-        private:
-            int var;
+            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
+        __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
@@ -64,7 +65,7 @@ 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*
+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
@@ -83,7 +84,7 @@ window.
 Pseudo-tags are denoted with an asterisk ('*') at the end of their name.
 
 ------------------------------------------------------------------------------
-SUPPORTED FEATURES					*tagbar-features*
+SUPPORTED FEATURES                                           *tagbar-features*
 
 The following features are supported by Tagbar:
 
@@ -104,7 +105,7 @@ The following features are supported by Tagbar:
   - Can be extended to support arbitrary new types.
 
 ------------------------------------------------------------------------------
-OTHER CTAGS-COMPATIBLE PROGRAMS				*tagbar-other*
+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
@@ -116,7 +117,7 @@ correct configuration please contact me.
 Note: Please check |tagbar-issues| for some possible issues with jsctags.
 
 ==============================================================================
-2. Requirements						*tagbar-requirements*
+2. Requirements                                          *tagbar-requirements*
 
 The following requirements have to be met in order to be able to use tagbar:
 
@@ -143,24 +144,23 @@ The following requirements have to be met in order to be able to use tagbar:
   - Tagbar will not work in |restricted-mode| or with 'compatible' set.
 
 ==============================================================================
-3. Installation						*tagbar-installation*
+3. Installation                                          *tagbar-installation*
 
 Use the normal Vimball install method for installing tagbar.vba:
 >
-	vim tagbar.vba
-	:so %
-	:q
+        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.
+'runtimepath' or use the pathogen plugin. Don't forget to run |:helptags|.
 
 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*
+4. Usage                                                        *tagbar-usage*
 
 There are essentially two ways to use Tagbar:
 
@@ -184,9 +184,9 @@ closed. By default the window is opened on the right side, set the option
 |: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|:
+this into your |vimrc|:
 >
-	nnoremap <silent> <F9> :TagbarToggle<CR>
+        nnoremap <silent> <F9> :TagbarToggle<CR>
 <
 You can then open and close Tagbar by simply pressing the <F9> key.
 
@@ -206,7 +206,7 @@ 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
+in the Tagbar window. The current sort order is displayed in the statusline of
 the Tagbar window.
 
 Folding~
@@ -214,6 +214,13 @@ 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.
 
+Highlighting the current tag~
+When the Tagbar window is open the current tag will automatically be
+highlighted in it after a short pause if the cursor is not moving. The length
+of this pause is determined by the 'updatetime' option. If you want to make
+that pause shorter you can change the option, but don't set it too low or
+strange things will happen. This is unfortunately unavoidable.
+
 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>
@@ -223,9 +230,9 @@ 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*
+COMMANDS                                                     *tagbar-commands*
 
-:TagbarOpen [{flags}]
+:TagbarOpen [{flags}]                                            *:TagbarOpen*
     Open the Tagbar window if it is closed.
 
     Additional behaviour can be specified with the optional {flags} argument.
@@ -241,35 +248,45 @@ COMMANDS						*tagbar-commands*
     (unless |g:tagbar_autoclose| is set): >
         :TagbarOpen fj
 <
-:TagbarClose
+:TagbarClose                                                    *:TagbarClose*
     Close the Tagbar window if it is open.
 
-:TagbarToggle
+:TagbarToggle                                                  *:TagbarToggle*
     Open the Tagbar window if it is closed or close it if it is open.
 
-:TagbarOpenAutoClose
+:TagbarOpenAutoClose                                    *:TagbarOpenAutoClose*
     Open the Tagbar window, jump to it and close it on tag selection. This is
     an alias for ":TagbarOpen fc".
 
-:TagbarSetFoldlevel {number}
+:TagbarSetFoldlevel[!] {number}                          *:TagbarSetFoldlevel*
     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'.
+    as 'foldlevel'. Folds that are specified to be closed by default in the
+    type configuration will not be opened, use a "!" to force applying the new
+    foldlevel to those folds as well.
 
-:TagbarShowTag
+:TagbarShowTag                                                *: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]
+:TagbarGetTypeConfig {filetype}                         *:TagbarGetTypeConfig*
+    Paste the Tagbar configuration of the vim filetype {filetype} at the
+    current cursor position (provided that filetype is supported by Tagbar)
+    for easy customization. The configuration will be ready to use as is but
+    will only contain the "kinds" entry as that is the only one that really
+    makes sense to customize. See |tagbar-extend| for more information about
+    type configurations.
+
+:TagbarDebug [logfile]                                          *:TagbarDebug*
     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
+:TagbarDebugEnd                                              *:TagbarDebugEnd*
     End debug mode, debug messages will no longer be written to the logfile.
 
 ------------------------------------------------------------------------------
-KEY MAPPINGS						*tagbar-keys*
+KEY MAPPINGS                                                     *tagbar-keys*
 
 The following mappings are valid in the Tagbar window:
 
@@ -297,9 +314,9 @@ x             Toggle zooming the window.
 q             Close the Tagbar window.
 
 ==============================================================================
-5. Configuration					*tagbar-configuration*
+5. Configuration                                        *tagbar-configuration*
 
-							*g:tagbar_ctags_bin*
+                                                          *g:tagbar_ctags_bin*
 g:tagbar_ctags_bin~
 Default: empty
 
@@ -308,10 +325,10 @@ 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'
+        let g:tagbar_ctags_bin = 'C:\Ctags5.8\ctags.exe'
 <
 
-							*g:tagbar_left*
+                                                               *g:tagbar_left*
 g:tagbar_left~
 Default: 0
 
@@ -320,10 +337,10 @@ this option to open it on the left instead.
 
 Example:
 >
-	let g:tagbar_left = 1
+        let g:tagbar_left = 1
 <
 
-							*g:tagbar_width*
+                                                              *g:tagbar_width*
 g:tagbar_width~
 Default: 40
 
@@ -331,10 +348,10 @@ Width of the Tagbar window in characters.
 
 Example:
 >
-	let g:tagbar_width = 30
+        let g:tagbar_width = 30
 <
 
-							*g:tagbar_autoclose*
+                                                          *g:tagbar_autoclose*
 g:tagbar_autoclose~
 Default: 0
 
@@ -343,10 +360,10 @@ jump to a tag. This implies |g:tagbar_autofocus|.
 
 Example:
 >
-	let g:tagbar_autoclose = 1
+        let g:tagbar_autoclose = 1
 <
 
-							*g:tagbar_autofocus*
+                                                          *g:tagbar_autofocus*
 g:tagbar_autofocus~
 Default: 0
 
@@ -355,10 +372,10 @@ opened.
 
 Example:
 >
-	let g:tagbar_autofocus = 1
+        let g:tagbar_autofocus = 1
 <
 
-							*g:tagbar_sort*
+                                                               *g:tagbar_sort*
 g:tagbar_sort~
 Default: 1
 
@@ -369,10 +386,10 @@ same kind since they don't have a real position in the file.
 
 Example:
 >
-	let g:tagbar_sort = 0
+        let g:tagbar_sort = 0
 <
 
-							*g:tagbar_compact*
+                                                            *g:tagbar_compact*
 g:tagbar_compact~
 Default: 0
 
@@ -382,10 +399,10 @@ save screen real estate.
 
 Example:
 >
-	let g:tagbar_compact = 1
+        let g:tagbar_compact = 1
 <
 
-							*g:tagbar_expand*
+                                                             *g:tagbar_expand*
 g:tagbar_expand~
 Default: 0
 
@@ -394,10 +411,10 @@ Tagbar window if using a GUI version of Vim.
 
 Example:
 >
-	let g:tagbar_expand = 1
+        let g:tagbar_expand = 1
 <
 
-							*g:tagbar_singleclick*
+                                                        *g:tagbar_singleclick*
 g:tagbar_singleclick~
 Default: 0
 
@@ -406,22 +423,22 @@ to the tag definition.
 
 Example:
 >
-	let g:tagbar_singleclick = 1
+        let g:tagbar_singleclick = 1
 <
 
-							*g:tagbar_foldlevel*
+                                                          *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.
+The initial foldlevel for folds in the Tagbar window. Folds with a level
+higher than this number will be closed.
 
 Example:
 >
-	let g:tagbar_foldlevel = 2
+        let g:tagbar_foldlevel = 2
 <
 
-							*g:tagbar_iconchars*
+                                                          *g:tagbar_iconchars*
 g:tagbar_iconchars~
 
 Since the display of the icons used to indicate open or closed folds depends
@@ -430,31 +447,31 @@ 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):
+Examples (don't worry if some of 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)
+        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*
 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.
+tag will be highlighted instead. You can use the |:TagbarShowTag| command to
+open the folds manually.
 
 Example:
 >
-	let g:tagbar_autoshowtag = 1
+        let g:tagbar_autoshowtag = 1
 <
 
-						*g:tagbar_updateonsave_maxlines*
+                                              *g:tagbar_updateonsave_maxlines*
 g:tagbar_updateonsave_maxlines~
 Default: 5000
 
@@ -467,10 +484,10 @@ computer you can set it to a higher value.
 
 Example:
 >
-	let g:tagbar_updateonsave_maxlines = 10000
+        let g:tagbar_updateonsave_maxlines = 10000
 <
 
-							*g:tagbar_systemenc*
+                                                          *g:tagbar_systemenc*
 g:tagbar_systemenc~
 Default: value of 'encoding'
 
@@ -482,11 +499,11 @@ have to set this variable to "cp936".
 
 Example:
 >
-	let g:tagbar_systemenc = 'cp936'
+        let g:tagbar_systemenc = 'cp936'
 <
 
 ------------------------------------------------------------------------------
-HIGHLIGHT COLOURS					*tagbar-highlight*
+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:
@@ -530,49 +547,108 @@ TagbarAccessPrivate
 If you want to change any of those colours put a line like the following in
 your vimrc:
 >
-	highlight TagbarScope guifg=Green ctermfg=Green
+        highlight TagbarScope guifg=Green ctermfg=Green
 <
 See |:highlight| for more information.
 
 ------------------------------------------------------------------------------
-AUTOMATICALLY OPENING TAGBAR				*tagbar-autoopen*
+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).
+opens Tagbar only if a supported file is open(ed). It has a boolean parameter
+that specifies whether Tagbar should be opened if any loaded buffer is
+supported (in case the parameter is set to true) or only if a supported
+file/buffer is currently being shown in a window. This can be useful if you
+use multiple tabs and don't edit supported files in all of them.
 
 If you want to open Tagbar automatically on Vim startup no matter what put
 this into your vimrc:
 >
-    autocmd VimEnter * nested :TagbarOpen
+        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()
+        autocmd VimEnter * nested :call tagbar#autoopen(1)
 <
+The above is exactly what the Taglist plugin does if you set the
+Tlist_Auto_Open option, in case you want to emulate this behaviour.
+
 For opening Tagbar also if you open a supported file in an already running
 Vim:
 >
-    autocmd FileType * nested :call tagbar#autoopen()
+        autocmd FileType * nested :call tagbar#autoopen(0)
 <
-And if you only want to open Tagbar only for specific filetypes, not for all
-of the supported ones:
+If you use multiple tabs and want Tagbar to also open in the current tab when
+you switch to an already loaded, supported buffer:
 >
-    autocmd FileType c,cpp nested :TagbarOpen
+        autocmd BufEnter * nested :call tagbar#autoopen(0)
+<
+And if you 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.
 
+------------------------------------------------------------------------------
+SHOWING THE CURRENT TAG IN THE STATUSLINE                  *tagbar-statusline*
+
+You can show the current tag in the 'statusline', or in any other place that
+you want to, by calling the tagbar#currenttag() function. The current tag is
+exactly the same as would be highlighted in the Tagbar window if it is open.
+It is defined as the nearest tag upwards in the file starting from the cursor
+position. This means that for example in a function it should usually be the
+name of the function.
+
+The function has the following signature:
+
+tagbar#currenttag({format}, {default} [, {flags}])
+    {format} is a |printf()|-compatible format string where "%s" will be
+    replaced by the name of the tag. {default} will be displayed instead of
+    the format string if no tag can be found.
+
+    The optional {flags} argument specifies some additional properties of the
+    displayed tags. It is a string which can contain these character flags:
+    'f'   Display the full hierarchy of the tag, not just the tag itself.
+    's'   If the tag is a function, the complete signature will be shown,
+          otherwise just "()" will be appended to distinguish functions from
+          other tags.
+
+    For example, if you put the following into your statusline: >
+        %{tagbar#currenttag('[%s] ', '')}
+<   then the function "myfunc" will be show as "[myfunc()] ".
+
 ==============================================================================
-6. Extending Tagbar					*tagbar-extend*
+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.
+existing types and to add completely new types. For Tagbar to support a
+filetype two things are needed: a program that generates the tag information,
+usually Exuberant Ctags, and a Tagbar type definition in your |vimrc| or an
+|ftplugin| that tells Tagbar how to interpret the generated tags.
+
+Note: if you only want to customize an existing definition (like changing the
+order in which tag kinds are displayed) see "Changing an existing definition"
+below.
+
+There are two ways to generate the tag information for new filetypes: add a
+definition to Exuberant Ctags or create a specialized program for your
+language that generates ctags-compatible tag information (see
+|tags-file-format| for information about how a "tags" file is structured). The
+former allows simple regular expression-based parsing that is easy to get
+started with, but doesn't support scopes unless you instead want to write a
+C-based parser module for Exuberant Ctags. The regex approach is described in
+more detail below.
+Writing your own program is the approach used by for example jsctags and can
+be useful if your language can best be parsed by a program written in the
+language itself, or if you want to provide the program as part of a complete
+support package for the language. Some tips on how to write such a program are
+given at the end of this section.
 
 Before writing your own extension have a look at the wiki
 (https://github.com/majutsushi/tagbar/wiki/Support-for-additional-filetypes)
@@ -591,18 +667,26 @@ kinds:      A list of the "language kinds" that should be listed in Tagbar,
             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 >
+            entry in this list is a colon-separated string with the following
+            syntax: >
+                {short}:{long}[:{fold}[:{stl}]]
+<           {short} is the one-character abbreviation that ctags uses, and
+            {long} is an arbitrary string that will be used in Tagbar as the
+            header for the the tags of this kind that are not listed under a
+            specific scope. {fold} 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. {stl} is used by the tagbar#currenttag()
+            function (see |tagbar-statusline|) to decide whether tags of this
+            kind should be shown in the statusline or not, with 1 meaning they
+            will be shown and 0 meaning they will be ignored. Omitting this
+            part means that the tags will be shown. Note that you have to
+            specify {fold} too if you want to specify {stl}.
+            For example, the string >
                 "f:functions:1"
 <           would list all the function definitions in a file under the header
-            "functions" and fold them.
+            "functions", fold them, and implicitly show them in the statusline
+            if tagbar#currenttag() is used.
 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.
@@ -662,7 +746,8 @@ ctagsbin:  The path to a filetype-specific ctags-compatible program like
            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).
+           you want to change something, of course). Note: if you use this
+           then the "ctagstype" key is not needed.
 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
@@ -672,12 +757,12 @@ ctagsargs: The arguments to be passed to the filetype-specific ctags program
 You then have to assign this dictionary to a variable in your vimrc with the
 name
 >
-	g:tagbar_type_{vim filetype}
+        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?
+        :set filetype?
 <
 and vim will display the file type of the current buffer.
 
@@ -686,65 +771,71 @@ 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'
-	    \ }
-	\ }
+        let g:tagbar_type_cpp = {
+            \ 'ctagstype' : 'c++',
+            \ 'kinds'     : [
+                \ 'd:macros:1:0',
+                \ 'p:prototypes:1:0',
+                \ 'g:enums',
+                \ 'e:enumerators:0:0',
+                \ 't:typedefs:0:0',
+                \ 'n:namespaces',
+                \ 'c:classes',
+                \ 's:structs',
+                \ 'u:unions',
+                \ 'f:functions',
+                \ 'm:members:0:0',
+                \ 'v:variables:0:0'
+            \ ],
+            \ '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:
+parts that you want to change. It probably only makes sense to change "kinds",
+which would be the case if you wanted to for example change the order of
+certain kinds, change their default fold state or exclude them from appearing
+in Tagbar. The easiest way to do that is to use the |:TagbarGetTypeConfig|
+command, which will paste a ready-to-use configuration with the "kinds" entry
+for the specified type at the current cursor position.
+
+As an example, if you didn't want Tagbar to show prototypes for C++ files,
+switch the order of enums and typedefs, and show macros in the statusline, you
+would first run ":TagbarGetTypeConfig cpp" in your vimrc and then change the
+definition 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'
-	    \ ]
-	\ }
+        let g:tagbar_type_cpp = {
+            \ 'kinds' : [
+                \ 'd:macros:1',
+                \ 'g:enums',
+                \ 't:typedefs:0:0',
+                \ 'e:enumerators:0:0',
+                \ 'n:namespaces',
+                \ 'c:classes',
+                \ 's:structs',
+                \ 'u:unions',
+                \ 'f:functions',
+                \ 'm:members:0:0',
+                \ 'v:variables:0:0'
+            \ ]
+        \ }
 <
 Compare with the complete example above to see the difference.
 
@@ -770,28 +861,28 @@ 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/
+        --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
@@ -801,18 +892,18 @@ 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'
-	\ }
+        let g:tagbar_type_tex = {
+            \ 'ctagstype' : 'latex',
+            \ 'kinds'     : [
+                \ 's:sections',
+                \ 'g:graphics:0:0',
+                \ 'l:labels',
+                \ 'r:refs:1:0',
+                \ 'p:pagerefs:1:0'
+            \ ],
+            \ '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.
@@ -825,8 +916,37 @@ that.
 Tagbar should now be able to show the sections and other tags from LaTeX
 files.
 
+Writing your own tag-generating program~
+If you want to write your own program for generating tags then here are some
+imporant tips to get it to integrate well with Tagbar:
+
+  - Tagbar supports the same tag format as Vim itself. The format is described
+    in |tags-file-format|, the third format mentioned there is the relevant
+    one. Note that the {tagaddress} part should be a search pattern since the
+    line number can be specified in a field (see below).
+  - Tagbar reads the tag information from a program's standard output
+    (stdout), it doesn't generate files and reads them in after that. So make
+    sure that your program has an option to output the tags on stdout.
+  - Some fields are supported for providing additional information about a
+    tag. One field is required: the "kind" field as a single letter without
+    a "kind:" fieldname. This field has to be the first one in the list. All
+    other fields need to have a fieldname in order to determine what they are.
+    The following fields are supported for all filetypes:
+
+        * line:      The line number of the tag
+        * column:    The column number of the tag
+        * signature: The signature of a function
+        * access:    Visibility/access information of a tag; the values
+                     "public", "protected" and "private" will be denoted with
+                     a special symbol in Tagbar
+
+    In addition fields that describe the surrounding scope of the tag are
+    supported if they are specified in the type configuration as explained at
+    the beginning of this section. For example, for a tag in class "Foo" this
+    could look like "class:Foo".
+
 ==============================================================================
-7. Troubleshooting & Known issues			*tagbar-issues*
+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
@@ -834,7 +954,7 @@ 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
+        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".
@@ -891,12 +1011,22 @@ file.
                 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.
+    I haven't found a proper 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*
+8. History                                                    *tagbar-history*
+
+2.4 (2012-06-17)
+    - New function tagbar#currenttag() that reports the current tag, for
+      example for putting it into the statusline.
+    - New command TagbarGetTypeConfig for easy customization of an existing
+      type.
+    - Type definitions now can be loaded from ftplugins.
+    - The autoopen() function is now a bit more flexible.
+    - Vala is now supported if Anjuta is installed.
+    - Various other small improvements and bugfixes.
 
 2.3 (2011-12-24)
     - Add a convenience function that allows more flexible ways to
@@ -979,7 +1109,7 @@ file.
     - Initial release
 
 ==============================================================================
-9. Todo							*tagbar-todo*
+9. Todo                                                          *tagbar-todo*
 
   - Allow filtering the Tagbar content by some criteria like tag name,
     visibility, kind ...
@@ -988,7 +1118,7 @@ file.
   - Allow jumping to a tag in the preview window, a split window or a new tab.
 
 ==============================================================================
-10. Credits						*tagbar-credits*
+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
@@ -1006,11 +1136,13 @@ The folding technique was inspired by NERDTree by Martin Grenfell.
 
 Thanks to the following people for code contributions, feature suggestions etc:
 Jan Christoph Ebersbach
+Vadim Fint
 Leandro Freitas
 Seth Milliken
 Kien N
 pielgrzym
 Taybin Rutkin
+Ville Valkonen
 
 ==============================================================================
- vim: tw=78 ts=8 sw=8 sts=8 noet ft=help
+ vim: tw=78 ts=8 sw=4 sts=4 et ft=help

plugin/tagbar.vim

@@ -4,7 +4,7 @@
 " Author:      Jan Larres <jan@majutsushi.net>
 " Licence:     Vim licence
 " Website:     http://majutsushi.github.com/tagbar/
-" Version:     2.3
+" Version:     2.4
 " Note:        This plugin was heavily inspired by the 'Taglist' plugin by
 "              Yegappan Lakshmanan and uses a small amount of code from it.
 "
@@ -109,8 +109,9 @@ command! -nargs=0 TagbarToggle        call tagbar#ToggleWindow()
 command! -nargs=? TagbarOpen          call tagbar#OpenWindow(<f-args>)
 command! -nargs=0 TagbarOpenAutoClose call tagbar#OpenWindow('fc')
 command! -nargs=0 TagbarClose         call tagbar#CloseWindow()
-command! -nargs=1 TagbarSetFoldlevel  call tagbar#SetFoldLevel(<args>)
+command! -nargs=1 -bang TagbarSetFoldlevel  call tagbar#SetFoldLevel(<args>, <bang>0)
 command! -nargs=0 TagbarShowTag       call tagbar#OpenParents()
+command! -nargs=1 TagbarGetTypeConfig call tagbar#gettypeconfig(<f-args>)
 command! -nargs=? TagbarDebug         call tagbar#StartDebug(<f-args>)
 command! -nargs=0 TagbarDebugEnd      call tagbar#StopDebug()
 

syntax/tagbar.vim

@@ -3,7 +3,7 @@
 " Author:      Jan Larres <jan@majutsushi.net>
 " Licence:     Vim licence
 " Website:     http://majutsushi.github.com/tagbar/
-" Version:     2.3
+" Version:     2.4
 
 scriptencoding utf-8