46d930c7d2f20a9ee50e965e2cbd3e2485668b53
[stack/conf/vim.git] / addons / TagHighlight / doc / TagHighlight.txt
1 *TagHighlight.txt*       Tag Highlighting
2
3 Author:     A. S. Budden <abuddenNOSPAM@NOSPAMgmail.com>
4                         Remove NOSPAM.
5
6 Copyright:  (c) 2009-2012 by A. S. Budden             *TagHighlight-copyright*
7             Permission is hereby granted to use and distribute this code,
8             with or without modifications, provided that this copyright
9             notice is copied with it. Like anything else that's free,
10             the TagHighlight plugin is provided *as is* and comes with no
11             warranty of any kind, either expressed or implied. By using
12             this plugin, you agree that in no event will the copyright
13             holder be liable for any damages resulting from the use
14             of this software.
15
16 ==============================================================================
17 1. Contents                   *TagHighlight* *TagHighlight-contents*          {{{1
18
19         1.    Contents                           |TagHighlight-contents|
20
21         2.    TagHighlight Manual                |TagHighlight-manual|
22         2.1   Introduction                       |TagHighlight-intro|
23         2.2   Commands                           |TagHighlight-commands|
24         2.3   Colouring                          |TagHighlight-colours|
25         2.4   Configuration                      |TagHighlight-config|
26         2.4.1 How to Set Options                 |TagHighlight-how-options|
27         2.4.2 Example Configurations             |TagHighlight-example-configs|
28         2.4.3 Option Summary                     |TagHighlight-option-list|
29         2.4.4 Option Details                     |TagHighlight-option-details|
30         2.5   Integration with Other Software    |TagHighlight-integration|
31         2.5.1 Tagbar Integration                 |TagHighlight-tagbar|
32         2.5.2 Git Integration                    |TagHighlight-git|
33         2.5.3 Bazaar Integration                 |TagHighlight-bazaar|
34         2.5.4 Mercurial Integration              |TagHighlight-mercurial|
35         2.5.5 Subversion Integration             |TagHighlight-subversion|
36         2.6   Installation                       |TagHighlight-install|
37         2.6.1 Requirements                       |TagHighlight-requirements|
38         2.6.2 Installation Guide                 |TagHighlight-install-guide|
39
40         3.    Standard Libraries                 |TagHighlight-standard-libraries|
41         3.1   Introduction                       |TagHighlight-stdlib-intro|
42         3.2   Adding More Standard Libraries     |TagHighlight-adding-libraries|
43
44         4.    TagHighlight Customisation         |TagHighlight-custom|
45         4.1   Adding More Languages              |TagHighlight-adding|
46         4.1.1 Example                            |TagHighlight-add-example|
47
48         5.    Contributing Changes               |TagHighlight-contributions|
49         5.1   Suggestions for Improvements       |TagHighlight-suggestions|
50         5.2   Patches                            |TagHighlight-patches|
51         5.3   Usage Examples                     |TagHighlight-usage-examples|
52
53         6.    Troubleshooting                    |TagHighlight-troubleshooting|
54
55         7.    Credits                            |TagHighlight-credits|
56
57         8.    TagHighlight History               |TagHighlight-history|
58
59 ==============================================================================
60 2. TagHighlight Manual           *TagHighlight-manual*                      {{{1
61
62 2.1 Introduction                         *TagHighlight-intro*               {{{2
63
64         TagHighlight is a plugin that highlights names of classes, variables,
65         types etc in source code in Vim.  This makes it quicker and easier to spot
66         errors in your code.  By using ctags and parsing the output, the typedefs,
67         #defines, enumerated names etc are all clearly highlighted in different
68         colours.
69
70         The idea was based on the comments in |tag-highlight|, but I wanted to
71         take it a little further.
72
73         This is achieved through a python script (also available as a compiled
74         executable if you don't have python: see |TagHighlight-requirements|) to
75         interact with ctags and to parse the result and a Vim script that makes
76         Vim read the resulting files.  Finally, a new command (|:UpdateTypesFile|)
77         is added (with optional ! for recursive operation) to keep the generated
78         files up to date.
79
80                                          *TagHighlight-languages*
81         At present, the highlighter supports the following languages:
82
83                 * C/C++
84                 * C#
85                 * Java
86                 * Javascript
87                 * Matlab (function names only; may require custom ctags)
88                 * Perl
89                 * PHP
90                 * Python
91                 * Ruby (largely untested)
92                 * Scala
93                 * Fortran
94                 * Go (if your version of ctags supports it)
95                 * VHDL (if your version of ctags supports it)
96
97         It should also work correctly with Charles Campbell's rainbow.vim bracket
98         highlighter.
99
100         The vast majority of the testing has been with C source code, so I'd be
101         very interested in any feedback on the use with C++ and the various other
102         languages.
103
104         Currently requires exuberant ctags or one of its derivatives.  Exuberant
105         ctags is available from:
106 >
107                 http://ctags.sourceforge.net
108 <
109         Adding more languages is extremely simple (as long as they're supported by
110         Exuberant ctags); see |TagHighlight-adding|.
111
112                                                              *TagHighlight-website*
113
114         Screenshots of the highlighter in operation are available at the website:
115 >
116                 http://www.cgtk.co.uk/taghighlight
117 <
118                                          *TagHighlight-source-code*
119
120         The plugin is distribute as source code (binaries of the python components
121         are also available for computers that do not have python installed) The
122         source code is managed using the Mercurial version control system and is
123         available on bitbucket at:
124 >
125                 https://bitbucket.org/abudden/taghighlight
126 <
127 ------------------------------------------------------------------------------
128
129 2.2 Commands                             *TagHighlight-commands*            {{{2
130
131         The following commands are provided by this plugin:
132
133         :UpdateTypesFile                 *:UpdateTypesFile*
134
135                 This command creates the syntax highlighting file used to show the
136                 extra colouring.  It then updates all of the open files automatically.
137                 By default, it scans recursively into subdirectories of the top level
138                 project source directory.  To find this, it looks for a file called
139                 "tags" or a file called "taghl_config.txt" in the directory containing
140                 the source code or any of its parents (all the way up to the root
141                 directory).  If it finds one of these files, it assumes that the
142                 directory containing the file also contains all of the source code.
143                 If it can't find either of the files, it will use the current
144                 directory.  This operation can be customised using the option
145                 |TagHL-DefaultDirModePriority|.
146
147                 NOTE: Recursion is now on by default.  To turn it off, set the option
148                 |TagHL-Recurse| to be 'False' or 0.  This can either be done globally
149                 in |g:TagHighlightSettings| or in a file named |taghl_config.txt| in
150                 the directory containing the source file.
151
152         :UpdateTypesFileOnly             *:UpdateTypesFileOnly*
153
154                 This command operates in the same manner as |UpdateTypesFile|, but
155                 it uses the current tags file rather than generating a new one
156                 (useful if you're generating tags files as part of your build
157                 process.
158
159         :ReadTypes                       *:ReadTypes*
160
161                 This command can be used to manually read in any types files to
162                 highlight keywords.  Generally not likely to be used as the
163                 built-in autocmds should load the types files when a file is
164                 loaded or the types files are updated.
165
166 ------------------------------------------------------------------------------
167
168 2.3 Colouring                            *TagHighlight-colours*             {{{2
169
170         The tag highlighter uses a number of additional highlighting groups to
171         differentiate between different types of tag.  These are not supported as
172         standard by many colour schemes.  You can either download the "bandit"
173         colour scheme from:
174 >
175                 http://www.cgtk.co.uk/bandit
176 <
177         (screenshots of C source code on the |TagHighlight-website|) or you
178         can configure the extra highlighting groups yourself.  The following
179         highlight groups should be defined (others may be needed for different
180         languages):
181
182                 Class           : Class
183                 DefinedName     : Define
184                 Enumerator      : Enumerator
185                 Function        : Function or method
186                 EnumerationName : Enumeration name
187                 Member          : Member (of structure or class)
188                 Structure       : Structure Name
189                 Type            : Typedef
190                 Union           : Union Name
191                 GlobalConstant  : Global Constant
192                 GlobalVariable  : Global Variable
193                 LocalVariable   : Local Variable
194
195                                               *TagHighlight-language-colours*
196
197         To see the full list of supported groups for a given language, open up
198         plugin/TagHighlight/data/kinds.txt and find your language.  The bit after
199         CTags is the name of the highlight group.  For example, for C++, there is
200         the entry:
201 >
202                 d:CTagsDefinedName
203 <
204         so for this language, the highlight group 'DefinedName' can be used to
205         highlight defined names.
206
207         The easiest way to add these new groups to an existing colour scheme is to
208         download my |EasyColour| plugin from:
209 >
210                 http://www.cgtk.co.uk/easycolour
211 <
212         If you want to edit an existing colour scheme manually, an example of how
213         to highlight one of these would be to include the following line in your
214         colour scheme (see |:highlight|):
215 >
216                 hi Enumerator guifg="c000c0"
217 <
218         You can, of course, also link the groups to another highlighting group
219         using something like:
220 >
221                 hi link Type Comment
222 <
223         All groups are linked to the 'Keyword' type by default.  However, this
224         loses a lot of the advantages of having the tag highlighter in the first
225         place - being able to distinguish between different types!
226
227 ------------------------------------------------------------------------------
228
229 2.4 Configuration                        *TagHighlight-config*              {{{2
230
231         There are a large number of configuration options that allow customisation
232         of the operation of the highlighter.  For simple use, none of these really
233         need to be set.  Options can be set globally, per project or per buffer;
234         see |TagHighlight-how-options| for more information.
235
236 2.4.1 How to Set Options                 *TagHighlight-how-options*         {{{3
237
238         Options can be set globally, per project or per buffer.  Global options
239         are overridden by project options, which in turn are overridden by
240         buffer-specific options.
241
242         Global Options                   *g:TagHighlightSettings*
243
244                 Global options are set in a global |Dictionary|.  The variable
245                 name is |g:TagHighlightSettings|.  The keys in the dictionary are
246                 the option names and the values are the option values.  The safest
247                 way to set a value in this dictionary is to use something like
248                 this:
249 >
250                         if ! exists('g:TagHighlightSettings')
251                                 let g:TagHighlightSettings = {}
252                         endif
253                         let g:TagHighlightSettings['TagFileName'] = 'tagfile'
254                         let g:TagHighlightSettings['CtagsExecutable'] = 'etags.exe'
255 <
256                 If you want to override any existing options (or you want to be
257                 lazy...) you can probably also do it this way:
258 >
259                         let g:TagHighlightSettings = {'TagFileName': 'tagfile', 'CtagsExecutable': 'etags.exe'}
260 <
261         Project Options                  *taghl_config.txt*
262
263                 Project options are set in a text file in the project directory.
264                 The location of this file can be specified using the options
265                 |TagHL-ProjectConfigDirModePriority| and (if an explicit location
266                 is needed) |TagHL-ProjectConfigFileDirectory|.  By default. the
267                 file name of the project config file is "taghl_config.txt".  If
268                 for any reason you need to change this, it can be customised using
269                 the option |TagHL-ProjectConfigFileName| (this probably needs to
270                 be a Global option set in |g:TagHighlightSettings|.
271
272                 The format of the project config file is a simple text file with
273                 colons used to delimit keys and values.  A simple example would
274                 look like this:
275 >
276                         SkipPatterns:Skip.*,AnotherPattern\d+
277                         IncludeLocals:1
278                         UserLibraryDir:c:/user_libraries
279                         PythonVariantPriority:
280                                 if_pyth
281                                 if_pyth3
282                                 python
283                                 compiled
284 <
285                 Most lines start with an option name (there is no leading
286                 whitespace on these lines).  The option name is everything up to
287                 the colon.  After the colon is the value.
288
289                 For boolean options (such as Recurse and IncludeLocals in the
290                 example above), any of True, 1, False or 0 are acceptable (note:
291                 True and False are case sensitive).
292
293                 For string entries (such as UserLibraryDir above), all of the text
294                 after the first colon is treated as the value.
295
296                 For list entries (such as SkipPatterns and PythonVariantPriority
297                 above), you can either put all the entries on one line with commas
298                 to separate them, or you can put one entry on each subsequeunt
299                 line with a tab character at the start of the line.
300
301         Buffer Options                   *b:TagHighlightSettings*
302
303                 Buffer specific options are set in a buffer-local |Dictionary| in
304                 the same way as the global options in |g:TagHighlightSettings|.
305                 The name of this |Dictionary| is |b:TagHighlightSettings|.  See
306                 the description for |g:TagHighlightSettings| for usage
307                 instructions.
308
309 2.4.2 Example Configurations             *TagHighlight-example-configs*     {{{3
310
311         Introduction                                                          {{{4
312
313                 This section contains a few examples of configurations that may be
314                 useful.  It is hoped that most users will be able to use TagHighlight
315                 without setting any options at all, but these give some examples of
316                 some more complex scenarios.  These examples are also all on the wiki:
317 >
318                         https://bitbucket.org/abudden/taghighlight/wiki/Home
319 <
320                 If you have any additional examples (e.g. how to use with different
321                 variants of ctags, specific libraries or other custom configurations),
322                 please add them to the wiki.
323
324         Trivial Configuration                                                 {{{4
325
326                 Use case: User has source code placed in multiple subdirectories and
327                           either has the current directory to be the project root or
328                           rarely deletes the tags file that is generated.
329
330                 Implementation:
331
332                         First time round, use |:cd| to get to the project root and run:
333 >
334                                 :UpdateTypesFile
335 <
336                         After the first run, you can open any source file in the project,
337                         with the current directory set anywhere you like; the existing
338                         tags file will be found and the location of that will be used as
339                         the project root.
340
341         Low Complexity                                                        {{{4
342
343                 Use case: User has source code all in one directory but has a lot of
344                           subdirectories that would take a long time to scan.  The
345                           user therefore wishes to disable recursive scanning.  User
346                                   project uses Qt4, so the user would like the classes etc
347                                   from Qt4 (e.g. QString) to be highlighted.
348
349                 Implementation:
350
351                         Make sure that you have installed the standard libraries (see 
352                         |TagHighlight-install-stdlib|).  The Qt4 library will be loaded
353                         automatically.  Create a file called taghl_config.txt in the
354                         source directory.  In that file, add the following line (with no
355                         leading whitespace).
356 >
357                                 Recurse:False
358 <
359                         No other configuration should be necessary; just run:
360 >
361                                 :UpdateTypesFile
362 <
363         Medium Complexity                                                     {{{4
364
365                 Use case: User has (C) source code in the current directory; project
366                                   uses an external library (stored elsewhere on the hard disk)
367                                   but user would like to highlight the keywords from the user
368                                   library as well as the keywords from the main project.  User
369                                   is running a version of Vim with dynamic support for BOTH
370                                   python2 and python3, but would like to use python 2 by
371                                   preference.  User would like to include local variables in
372                                   the highlighted keyword list.  Exuberant ctags is installed
373                                   in the system path with executable name 'etags'.
374
375                 Implementation:
376
377                         First of all, we'll set TagHighlight up to use python 2 via the
378                         python interface and to recognise the non-standard ctags
379                         executable name.  In vimrc, add the following lines:
380 >
381                                 if ! exists('g:TagHighlightSettings')
382                                         let g:TagHighlightSettings = {}
383                                 endif
384                                 let g:TagHighlightSettings['ForcedPythonVariant'] = 'if_pyth'
385                                 let g:TagHighlightSettings['CtagsExecutable'] = 'etags'
386 <
387                         Next, generate the types highlighter for the library.  Let's
388                         assume that the library is stored in /home/user/libraries/lib1.
389                         Open up a new Vim and type:
390 >
391                                 :cd /home/user/libraries/lib1
392                                 :UpdateTypesFile
393 <
394                         That should create a file called types_c.taghl in the library
395                         directory.
396
397                         Now, create a project config file in the project directory.  The
398                         file should be called taghl_config.txt.  In that file, add the
399                         following lines (no leading whitespace):
400 >
401                                 IncludeLocals:True
402                                 UserLibraries:/home/user/libraries/lib1/types_c.taghl
403 <
404                         Open any source file in the project and run:
405 >
406                                 :UpdateTypesFile
407 <
408
409 2.4.3 Option Summary                     *TagHighlight-option-list*         {{{3
410
411         There are a lot of options for TagHighlight.  They are mentioned in this
412         section, grouped by their purpose.  You can find an alphabetical list with
413         more details in |TagHighlight-option-details|.  Along side each option
414         name is a link, starting with TagHL- and then the option name (to avoid
415         namespace clashes with other plugins).  Use CTRL-] on the TagHL- prefixed
416         option name to jump to detailed help on it.
417
418         What files to scan:
419
420                 Languages                        Link:|TagHL-Languages|
421                         List of languages to scan when generating highlighter.
422
423                 ParsingSkipList                  Link:|TagHL-ParsingSkipList|
424                         List of files for which types highlighter should not be loaded.
425
426                 Recurse                          Link:|TagHL-Recurse|
427                         When generating tags, recurse into subdirectories.
428
429                 SourceDir                        Link:|TagHL-SourceDir|
430                         Explicit location of the source code that you want to scan.
431
432         When to read the generated types file
433
434                 LanguageDetectionMethods         Link:|TagHL-LanguageDetectionMethods|
435                         How to identify programming language and which |autocmd|s to run.
436
437                 ExtensionLanguageOverrides       Link:|TagHL-ExtensionLanguageOverrides|
438                         Force a particular file extension to match a chosen language.
439
440                 FileTypeLanguageOverrides        Link:|TagHL-FileTypeLanguageOverrides|
441                         Force a particular file type to match a chosen language.
442
443                 SyntaxLanguageOverrides          Link:|TagHL-SyntaxLanguageOverrides|
444                         Force a particular Vim syntax to match a chosen language.
445
446         What to include in the generated types file
447
448                 IncludeLocals                    Link:|TagHL-IncludeLocals|
449                         Include local variables (not context aware) in types highlighter.
450
451                 IncludeSynMatches                Link:|TagHL-IncludeSynMatches|
452                         Include syntax matches in highlighter (see warning in details).
453
454                 SkipPatterns                     Link:|TagHL-SkipPatterns|
455                         List of python REs for keywords that should be skipped.
456
457                 SkipVimKeywords                  Link:|TagHL-SkipVimKeywords|
458                         Don't include vim keywords in highlighter.
459
460         Customisation:
461
462                 PreReadHooks                     Link:|TagHL-PreReadHooks|
463                         List of functions to call before reading types.
464
465                 PostReadHooks                    Link:|TagHL-PostReadHooks|
466                         List of functions to call after reading types.
467
468                 PreUpdateHooks                   Link:|TagHL-PreUpdateHooks|
469                         List of functions to call before updating types.
470
471                 PostUpdateHooks                  Link:|TagHL-PostUpdateHooks|
472                         List of functions to call after updating types.
473
474         Disabling built-in functionality:
475
476                 DisableTypeParsing               Link:|TagHL-DisableTypeParsing|
477                         Don't read types highlighter (disable highlight functionality).
478
479                 DisableTagManager                Link: |TagHL-DisableTagManager|
480                         Don't automatically adjust the 'tags' option.
481
482                 DoNotGenerateTags                Link:|TagHL-DoNotGenerateTags|
483                         Don't generate tags (use an existing tags file).
484
485                 DoNotGenerateTagsIfPresent       Link:|TagHL-DoNotGenerateTagsIfPresent|
486                         Don't generate tags if a tags file is detected.
487
488                 OnlyGenerateTypesIfPresent      Link:|TagHL-OnlyGenerateTypesIfPresent|
489                         Only generate types or tags if a types file already exists.
490
491         How to Run Python and Ctags:
492
493                 ForcedPythonVariant              Link:|TagHL-ForcedPythonVariant|
494                         Specify specific python variant to use.
495
496                 PathToPython                     Link:|TagHL-PathToPython|
497                         Specify path to python executable.
498
499                 PythonVariantPriority            Link:|TagHL-PythonVariantPriority|
500                         Specify priority order of different python variants.
501
502                 CtagsExecutable                  Link:|TagHL-CtagsExecutable|
503                         Specify the name of (or full path to) exuberant ctags.
504
505                 CtagsVariant                     Link:|TagHL-CtagsVariant|
506                         Use a variant of ctags other than exuberant.
507
508                 CtagsArguments                   Link:|TagHL-CtagsArguments|
509                         Specify an explicit list of arguments to pass to ctags.
510
511                 CtagsExtraArguments              Link:|TagHL-CtagsExtraArguments|
512                         Specify a list of extra arguments to pass to ctags.
513
514         Locations of Files (normal):
515
516                 DefaultDirModeSearchWildcards    Link:|TagHL-DirModeSearchWildcards|
517                         What to search for when deciding which directory to use.
518
519                 DefaultDirModePriority           Link:|TagHL-DefaultDirModePriority|
520                         Which directories to search by default.
521
522                 MaxDirSearchLevels               Link:|TagHL-MaxDirSearchLevels|
523                         How far up the directory tree to search.
524
525         Location and name of Project Configuration File:
526
527                 ProjectConfigFileDirModePriority Link:|TagHL-ProjectConfigFileDirModePriority|
528                         Which directories to search for project config file.
529
530                 ProjectConfigFileDirectory       Link:|TagHL-ProjectConfigFileDirectory|
531                         Explicit location for project config file.
532
533                 ProjectConfigFileName            Link:|TagHL-ProjectConfigFileName|
534                         File name for project config file.
535
536                 ProjectConfigFileSearchWildcards Link:|TagHL-DirModeSearchWildcards|
537                         What to search for when deciding which directory to use.
538
539         Location and name of tag file:
540
541                 TagFileDirModePriority           Link:|TagHL-TagFileDirModePriority|
542                         Which directories to search for tag file.
543
544                 TagFileDirectory                 Link:|TagHL-TagFileDirectory|
545                         Explicit location for tag file.
546
547                 TagFileName                      Link:|TagHL-TagFileName|
548                         File name for tag file.
549
550                 TagFileSearchWildcards           Link:|TagHL-DirModeSearchWildcards|
551                         What to search for when deciding which directory to use.
552
553         Location and name of types file:
554
555                 TypesFileDirModePriority         Link:|TagHL-TypesFileDirModePriority|
556                         Which directories to search for types highlighter file.
557
558                 TypesFileDirectory               Link:|TagHL-TypesFileDirectory|
559                         Explicit location for types highlighter file.
560
561                 TypesFileExtension               Link:|TagHL-TypesFileExtension|
562                         File extension for types highlighter file.
563
564                 TypesFileNameForce               Link:|TagHL-TypesFileNameForce|
565                         Force an explicit file name for the types highlighter file.
566
567                 TypesFilePrefix                  Link:|TagHL-TypesFilePrefix|
568                         Prefix for the types highlighter file.
569
570                 TypesFileSearchWildcards         Link:|TagHL-DirModeSearchWildcards|
571                         What to search for when deciding which directory to use.
572
573         Libraries:
574
575                 DisableStandardLibraries         Link:|TagHL-DisableStandardLibraries|
576                         Don't try loading standard libraries.
577
578                 ForcedStandardLibraries          Link:|TagHL-ForcedStandardLibraries|
579                         Always load specified standard libraries.
580
581                 UserLibraries                    Link:|TagHL-UserLibraries|
582                         List of user libraries that should be loaded.
583
584                 UserLibraryDir                   Link:|TagHL-UserLibraryDir|
585                         Location of user libraries specified with relative path.
586
587         Debugging:
588
589                 DebugLevel                       Link:|TagHL-DebugLevel|
590                         How much debugging information should be printed.
591
592                 DebugFile                        Link:|TagHL-DebugFile|
593                         Write debug log to a file.
594
595                 DebugPrintTime                   Link:|TagHL-DebugPrintTime|
596                         When writing to file, include timestamps.
597
598         Internal Use Only:
599
600                 CtagsExeFull                     Link:|TagHL-CtagsExeFull|
601                         Internal use only.
602
603                 CtagsFileLocation                Link:|TagHL-CtagsFileLocation|
604                         Internal use only.
605
606                 TypesFileLocation                Link:|TagHL-TypesFileLocation|
607                         Internal use only.
608
609 2.4.4 Option Details                     *TagHighlight-option-details*      {{{3
610
611         CtagsArguments                       *TagHL-CtagsArguments*
612                 This option allows advanced users to specify an explicit list of
613                 arguments to pass to ctags.  In most cases, you won't want to use
614                 this, but if |TagHL-CtagsExecutable| is pointing to a non-recognised
615                 version of ctags, you may need to specify custom arguments in order to
616                 get it to work with |TagHighlight|.  Before using this, consider the
617                 option |TagHL-CtagsVariant|.  If you do use CtagsArguments, please get
618                 in touch and let me know why: I might be able to create a new
619                 CtagsVariant to do whatever you need.
620
621                 Note: this should not be used to add additional arguments to ctags.
622                 This explcitly sets ALL of the parameters that are passed to ctags,
623                 replacing all the ones that TagHighlight would usually use.  If you
624                 just want to add an option to ctags, see |TagHL-CtagsExtraArguments|.
625
626                 Option Type: List
627                 Default: [] (empty list)
628
629         CtagsExeFull                         *TagHL-CtagsExeFull*
630                 Used internally to tell the python part of the application where ctags
631                 is.  Do not use this option as it will be automatically overwritten.
632                 Instead, see |TagHL-CtagsExecutable|.
633
634         CtagsExecutable                      *TagHL-CtagsExecutable*
635                 This option allows you to specify which exuberant ctags executable to
636                 run.  You can either specify an absolute path (e.g. "/usr/bin/ctags")
637                 or the name of an executable in the system path (e.g. "etags" if your
638                 system names Exuberant ctags in that way).
639
640                 Option Type: String
641                 Default: "ctags"
642
643         CtagsExtraArguments                  *TagHL-CtagsExtraArguments*
644                 This can be used to add a list of extra arguments for ctags to the
645                 ones normally used by TagHighlight.  This should be used if you want
646                 to customise the operation of ctags in some way not supported by
647                 TagHighlight.  If you use this option, please let me know: I might be
648                 able to add a TagHighlight option specific for your use case.
649
650                 Option Type: List
651                 Default: [] (empty list)
652
653         CtagsFileLocation                    *TagHL-CtagsFileLocation*
654                 Used internally to handle the location of the tag file.  Do not use
655                 this option as it will be automatically overwritten.  Instead, see
656                 |TagHL-DefaultDirModePriority|, |TagHL-TagFileDirModePriority| and
657                 |TagHL-TagFileDirectory|.
658
659                 See also |TagHL-TagFileName|.
660
661         CtagsVariant                         *TagHL-CtagsVariant*
662                 Some variants of ctags expect different arguments to exuberant ctags.
663                 This option allows you to tell |TagHighlight| to provide the arguments
664                 in a different form.  Currently supported values for this option are
665                 "exuberant" for the standard implementation and "jsctags" for jsctags.
666                 Note that if you're using this option, you probably also want to set
667                 |TagHL-CtagsExecutable| to something other than "ctags".
668
669                 Option Type: String
670                 Default: "exuberant"
671
672         DebugFile                            *TagHL-DebugFile*
673                 If set to something other than "None" (the default), write debugging
674                 messages to a file.
675
676                 Option Type: String
677                 Default: "None"
678
679         DebugLevel                           *TagHL-DebugLevel*
680                 This is a string describing how much debugging information to print.
681                 By default, this is set to 'Error': only errors or critical problems
682                 are reported.  Possible values are: "None" (don't print anything),
683                 "Critical" (only print critical errors, i.e. those where the plugin is
684                 installed incorrectly or similar), "Error" (print errors and critical
685                 problems), "Warning" (warn of potential issues), "Status" (report most
686                 actions that are being carried out) or "Information" (report
687                 everything that's happening).
688
689                 Option Type: String
690                 Default: "Error"
691
692         DebugPrintTime                       *TagHL-DebugPrintTime*
693                 If True or 1, when writing debug information to a file (see the option
694                 |TagHL-DebugFile|, prefix each entry with a timestamp.  Only supported
695                 for messages generated in Vim, not by the python script.
696
697                 Option Type: Boolean
698                 Default: False
699
700         DefaultDirModePriority               *TagHL-DefaultDirModePriority*
701                 There are several 'DirModePriority' options in addition to this one.
702                 These are used to determine where to find or place the project
703                 configuration file, the tags file and the types file.  The options
704                 that configure each of these are |TagHL-ProjectConfigDirModePriority|,
705                 |TagHL-TagFileDirModePriority| and |TagHL-TypesFileDirModePriority|.
706
707                 By default, all three of these priority settings are set simply as
708                 ["Default"].  Where "Default" is found in the list, the value of
709                 |TagHL-DefaultDirModePriority| will be used.
710
711                 When determining which directory to use, the plugin will try each of
712                 the methods in order until it gets a match.  The available methods
713                 of searching are:
714
715                         Explicit:
716                                 If a directory has been explicitly set (using the option
717                                 |TagHL-ProjectConfigFileDirectory| for project configuration
718                                 files, the option |TagHL-TagFileDirectory| for tag files and
719                                 the option |TagHL-TypesFileDirectory| for types highlighter
720                                 files), this directory will be used if this dir mode is
721                                 encountered.
722
723                         UpFromFile:
724                                 The plugin will start in the directory containing the current
725                                 file and look for any file matching the wildcards specified in
726                                 the option |TagHL-DirModeSearchWildcards|.  If none of the
727                                 wildcards match, it will try the parent directory and then
728                                 keep trying one level higher until it either finds a match or
729                                 reaches the top level directory (at which point the next
730                                 dir mode will be tried if no match is found).  If you wish to
731                                 stop it searching all the way to the top level directory, you
732                                 can limit the number of levels with |TagHL-MaxDirSearchLevels|.
733
734                         UpFromCurrent:
735                                 This works in the same way as UpFromFile, except that it
736                                 starts in the current directory (see |:pwd| or |getcwd()|).
737
738                         CurrentDirectory:
739                                 This will use the current working directory (see |:pwd| or
740                                 |getcwd()|) explicitly (any dir modes following this one will
741                                 never be used).
742
743                         FileDirectory:
744                                 This will use the directory containing the currently open file
745                                 (any dir modes following this one will never be used).
746
747                 The default value is ["Explicit", "UpFromFile", "CurrentDirectory"].
748                 Using the project config file as an example, when deciding where this
749                 file should be, it will first check for the presence of the option
750                 |TagHL-ProjectConfigFileDirectory|.  If this option is set, it will
751                 use that directory.  If not, it will start in the directory containing
752                 the currently open file and keep going up a level until it finds any
753                 file matching one of the wildcards in |TagHL-DirModeSearchWildcards|.
754                 If it reaches the top level directory without finding a file, it will
755                 use Vim's current working directory.
756
757                 Option Type: List
758                 Default:
759                         If |TagHL-Recurse| is True (the default), the default is
760                         ["Explicit", "UpFromFile", "CurrentDirectory"].
761
762                         If |TagHL-Recurse| is False, the default is ["FileDirectory"].
763
764         DefaultDirModeSearchWildcards        *TagHL-DefaultDirModeSearchWildcards*
765                 This option contains the wildcards that should be checked for when
766                 trying to determine which directory to use (in either the UpFromFile
767                 or UpFromCurrent dir mode).  The default is to match when either a
768                 project configuration file is found or a tags file is found.
769
770                 Note that the wildcard will only match against readable files, not
771                 directories.
772
773                 Option Type: List
774                 Default: [value of TagFileName option, value of ProjectConfigFileName option]
775
776         DisableStandardLibraries             *TagHL-DisableStandardLibraries*
777                 If installed, the standard libraries will automatically be loaded if
778                 the conditions specified in their configuration file match.  Setting
779                 this option to True or 1 will disable the checks and the standard
780                 libraries will never be loaded.  For more information on standard
781                 libraries, see |TagHighlight-standard-libraries|.
782
783                 Option Type: Boolean
784                 Default: False
785
786         DisableTagManager                     *TagHL-DisableTagManager*
787                 The TagManager automatically sets up the 'tags' option to include the
788                 generated tags file along with any tags files for user libraries (see
789                 |TagHL-UserLibraries|).  This option can be used to disable the
790                 TagManager.
791         
792                 If the TagManager is enabled, the generated tags file will be added to
793                 the 'tags' option; this makes it much easier to work with complex
794                 directory structures while maintaining a common tags file.
795                 If user libraries are configured and there is a tags file in the same
796                 directory as the library .taghl file (with a filename that matches the
797                 |TagHL-TagFileName| option), the TagManager will add the library tags
798                 file to the 'tags' option to enable easy navigation to library source
799                 code.
800
801                 Option Type: Boolean
802                 Default: False
803
804         DisableTypeParsing                   *TagHL-DisableTypeParsing*
805                 This option disables loading of types highlighter files: no custom
806                 types will be highlighted.
807
808                 Option Type: Boolean
809                 Default: False
810
811         DoNotGenerateTags                    *TagHL-DoNotGenerateTags*
812                 If this option is set, calling |:UpdateTypesFile| will be functionally
813                 equivalent to calling |:UpdateTypesFileOnly|: it will be assumed that
814                 a tag file already exists and ctags will not be run.  This should be
815                 used if you NEVER want |TagHighlight| to generate a tags file.
816                 Otherwise, you probably want |TagHL-DoNotGenerateTagsIfPresent|.
817
818                 Option Type: Boolean
819                 Default: False (generate tags)
820
821         DoNotGenerateTagsIfPresent           *TagHL-DoNotGenerateTagsIfPresent*
822                 This option is similar to |TagHL-DoNotGenerateTags|.  However, it only
823                 applies if a tags file already exists.  If the tags file exists, it
824                 will not be regenerated but will be used as is.  If the tags file does
825                 not exist, it will be created.  If |TagHL-DoNotGenerateTags| is set,
826                 this option is ignored.
827
828                 Option Type: Boolean
829                 Default: False (always generate tags)
830
831         ExtensionLanguageOverrides           *TagHL-ExtensionLanguageOverrides*
832                 If there are any entries in this dictionary, they will be used to
833                 force a particular file extension to be treated as representing a
834                 particular programming language.  The dictionary key is a Vim regular
835                 expression that matches the file extension and the dictionary value is
836                 the "suffix" defined for that language (the bit in between "types_"
837                 and ".taghl" in the generated type highlighter file).
838
839                 For example, to make all .svn files be treated as C files by the
840                 highlighter (so that function names mentioned in your commit log are
841                 highlighted), you could use something like this:
842 >
843                         let g:TagHighlightSettings['ExtensionLanguageOverrides'] =
844                                         \ {'svn': 'c'}
845 <
846                 To disable an extension from matching against a language, set the
847                 dictionary value to an empty string ("").
848
849                 This override will only work if 'Extension' is in the list of
850                 |TagHL-LanguageDetectionMethods|.
851
852         FileTypeLanguageOverrides            *TagHL-FileTypeLanguageOverrides*
853                 If there are any entries in this dictionary, they will be used to
854                 force a particular file type to be treated as representing a
855                 particular programming language.  The dictionary key is a Vim file
856                 type (as reported by ":set ft?") and the dictionary value is the
857                 "suffix" defined for that language (the bit in between "types_"
858                 and ".taghl" in the generated type highlighter file).
859
860                 To disable a file type from matching against a language, set the
861                 dictionary value to an empty string ("").
862
863                 This override will only work if 'FileType' is in the list of
864                 |TagHL-LanguageDetectionMethods|.
865
866         ForcedPythonVariant                  *TagHL-ForcedPythonVariant*
867                 There are a number of different python variants that are supported for
868                 running the python part of the plugin.  If this option is set to one
869                 of the strings that are supported by |TagHL-PythonVariantPriority|,
870                 that variant will always be used (and the plugin will fail if that
871                 variant is not available).
872
873                 Option Type: String
874                 Default: None (unset)
875
876         ForcedStandardLibraries              *TagHL-ForcedStandardLibraries*
877                 Any standard library names that are listed in this option will be
878                 loaded unconditionally.  For example, if this option is set to
879                 ["Android SDK", "JDK"], the Android SDK highlight definitions and the
880                 Java Development Kit highlight definitions will be loaded (as long as
881                 the highlight libraries have been installed).  For more information,
882                 see |TagHighlight-standard-libraries|.
883
884                 Option Type: List
885                 Default: [] (empty list)
886
887         IncludeLocals                        *TagHL-IncludeLocals*
888                 If set to True or 1, local variables will be included in the types
889                 highlighter file.  Note that ctags provides no context for these
890                 local variables and (if support for Dr Chip's rainbow plugin is to be
891                 provided) it would be impossible to make the highlighting context
892                 sensitive anyway, so the names will be highlighted whereever they may
893                 appear in the file.  As far as I am aware, there is no way round this,
894                 but I'd be interested to hear from anyone who has a good suggestion.
895
896                 Option Type: Boolean
897                 Default: False
898
899         IncludeSynMatches                    *TagHL-IncludeSynMatches*
900                 If set to True or 1, tags that cannot be highlighted with the Vim
901                 command "syn keyword" will be highlighted using the Vim command
902                 "syn match".  While this allows highlighting of a lot more tags,
903                 it uses a regular expression matching engine and as the number of
904                 tags increases, Vim gets slower and slower.  Therefore, use with
905                 caution.
906
907                 Option Type: Boolean
908                 Default: False
909
910         LanguageDetectionMethods             *TagHL-LanguageDetectionMethods*
911                 This option can be used to configure which methods are used for
912                 detecting the language of a file in order to read the appropriate
913                 highlight definition file.  There are three methods that are
914                 available:
915
916                         Extension:  Look at the extension of the current file and check
917                                                 for matches with the VimExtensionMatcher in the
918                                                 language definition files.
919
920                         FileType: Look at the file type that has been selected by Vim and
921                                   check for matches with the VimFileTypes list in the
922                                   language definition files.
923
924                         Syntax: Look at syntax that has been selected by Vim and check for
925                                 matches with the VimSyntaxes list in the language
926                                 definition files.  In most cases, you probably want to use
927                                 FileType rather than Syntax.
928
929                 When calling the either of the core commands (|:ReadTypes| and
930                 |:UpdateTypesFile|), they are checked in the order specified in the
931                 option.  In addition, there are |autocommand|s defined that will load
932                 the definitions when reading or creating a new file (Extension match),
933                 setting the |'syntax'| (Syntax match) or setting the |'filetype'|
934                 (FileType match).  In each case, the |autocommand|s do nothing unless
935                 the match type is listed in this option.
936
937                 Option Type: List
938                 Default: ['Extension']
939
940         Languages                            *TagHL-Languages*
941                 By default, when |:UpdateTypesFile| is run, any files that ctags
942                 recognises will be scanned for tags and types highlighters will be
943                 generated for each language in the resulting tags file that is
944                 supported by |TagHighlight|.  This option can be used to restrict both
945                 the types and tags files to a limited set of languages.  For example,
946                 if you have a directory with C code, Python code, Perl code and Ruby
947                 code, but you only want to generated tags and types for C and Python,
948                 set this option to ["c","python"].
949
950                 Option Type: List
951                 Default: [] (check all supported languages)
952
953         MaxDirSearchLevels                   *TagHL-MaxDirSearchLevels*
954                 When searching for a directory in which to store or from which to read
955                 the project config, tags or types highlighter files, there are two
956                 modes (UpFromFile and UpFromCurrent) that can be used to start in a
957                 particular directory and try every directory above that one until the
958                 file is found.  If there is a need to limit the number of directories
959                 that will be tried (mainly likely if there is a deeply nested
960                 directory structure and Vim seems a little slow), this option can be
961                 used.  If set to 0 (the default), it will keep going until it reaches
962                 the root directory.  If the option is set to 1, it will only check the
963                 current directory; if 2 it will check the current directory and the
964                 parent directory etc.
965
966                 For more information, see |TagHL-DefaultDirModePriority|.
967
968                 Option Type: Integer
969                 Default: 0
970
971         OnlyGenerateTypesIfPresent           *TagHL-OnlyGenerateTypesIfPresent*
972                 If this option is set, then a new types highlighter file will only be
973                 generated if one already exists.  If working on relatively small
974                 projects, this can be useful as you can set up an autocmd to
975                 regenerate tags and types files when you save:
976 >
977                         let g:TagHighlightSettings['OnlyGenerateTypesIfPresent'] = 1
978                         autocmd BufWritePost * UpdateTypesFile
979 <
980                 Every time you save a file, |TagHighlight| will check whether a types
981                 file exists and if it does, it will regenerate it.  If it doesn't
982                 exist, it will do nothing.  For larger projects, this is currently
983                 probably not practical due to the time it takes ctags to process the
984                 code.
985
986                 Option Type: Boolean
987                 Default: False (always generate types file)
988
989         ParsingSkipList                      *TagHL-ParsingSkipList*
990                 If you're editing a lot of files and for most you want tag highlight
991                 to run but one or two you don't, put the filenames of the ones for
992                 which you don't want highlighting in this list and the types
993                 highlighter will not be loaded for those files.
994
995                 Option Type: List
996                 Default: [] (load types highlighter for all files)
997
998         PathToPython                         *TagHL-PathToPython*
999                 When using the python variant "python" but with python not in the
1000                 path, this option allows you to specify the path to the python
1001                 executable.  See |TagHL-PythonVariantPriority| for more information.
1002
1003                 Option Type: String
1004                 Default: None (look in path if required)
1005
1006         PreReadHooks                         *TagHL-PreReadHooks*
1007                 Any function names that are listed in this option will be called
1008                 immediately prior to reading the types highlighter file.  This can be
1009                 used to allow complex customisation of |TagHighlight| and is for
1010                 advanced users only.  If you find a use for this, or any of the other
1011                 hooks, please let me know as I'd be interested to hear your use case!
1012                 The function must accept two arguments: the first is the full path and
1013                 filename of the current source code file and the second is the
1014                 relevant language suffix specified in the corresponding language
1015                 definition file (see |TagHighlight-add-example|.
1016
1017                 Option Type: List
1018                 Default: [] (no hooks)
1019
1020         PostReadHooks                        *TagHL-PostReadHooks*
1021                 Any function names that are listed in this option will be called
1022                 immediately after reading the types highlighter file.  This can be
1023                 used to allow complex customisation of |TagHighlight| and is for
1024                 advanced users only.  If you find a use for this, or any of the other
1025                 hooks, please let me know as I'd be interested to hear your use case!
1026                 The function must accept two arguments: the first is the full path and
1027                 filename of the current source code file and the second is the
1028                 relevant language suffix specified in the corresponding language
1029                 definition file (see |TagHighlight-add-example|.
1030
1031                 Option Type: List
1032                 Default: [] (no hooks)
1033
1034         PreUpdateHooks                       *TagHL-PreUpdateHooks*
1035                 Any function names that are listed in this option will be called
1036                 immediately prior to generating a new types highlighter file.  This
1037                 can be used to allow complex customisation of |TagHighlight| and is
1038                 for advanced users only.  If you find a use for this, or any of the
1039                 other hooks, please let me know as I'd be interested to hear your use
1040                 case!  The function takes no arguments.
1041
1042                 Option Type: List
1043                 Default: [] (no hooks)
1044
1045         PostUpdateHooks                      *TagHL-PostUpdateHooks*
1046                 Any function names that are listed in this option will be called
1047                 immediately after generating a new types highlighter file.  This can
1048                 be used to allow complex customisation of |TagHighlight| and is for
1049                 advanced users only.  If you find a use for this, or any of the other
1050                 hooks, please let me know as I'd be interested to hear your use case!
1051                 The function takes no arguments.
1052
1053                 Option Type: List
1054                 Default: [] (no hooks)
1055
1056         ProjectConfigFileDirModePriority     *TagHL-ProjectConfigFileDirModePriority*
1057                 This option is used to determine which directories to look in for a
1058                 project configuration file.  See |TagHL-DefaultDirModePriority| for
1059                 details.
1060
1061                 Option Type: List
1062                 Default: ["Default"] (use DefaultDirModePriority value)
1063
1064         ProjectConfigFileDirectory           *TagHL-ProjectConfigFileDirectory*
1065                 If the dir mode priority for project config files (see the option
1066                 |TagHL-ProjectConfigFileDirModePriority|) contains the mode
1067                 "Explicit", the directory specified in this option will be used
1068                 unconditionally if the option has been set.
1069
1070                 Option Type: String
1071                 Default: None (no explicit directory)
1072
1073         ProjectConfigFileName                *TagHL-ProjectConfigFileName*
1074                 This option allows customisation of the file name for project
1075                 configuration files.  The default file name is taghl_config.txt.
1076
1077                 Option Type: String
1078                 Default: "taghl_config.txt"
1079
1080         PythonVariantPriority                *TagHL-PythonVariantPriority*
1081                 The python part of |TagHighlight| can be run in a number of ways,
1082                 depending on your system configuration.  For most users, this should
1083                 be handled completely automatically, but if you want to customise
1084                 things, this option is the best way to start.  There are currently
1085                 four supported python variants:
1086
1087                         if_pyth3: When using this variant, the python code will be run
1088                                   using the Python 3.x interface built into Vim.  If using
1089                                   a Vim that is compiled with +python/dyn and
1090                                   +python3/dyn, be aware that this may cause problems if
1091                                   you want to use the python 2.x interface.  See the
1092                                   details on case 4 under |:py3file|.
1093
1094                         if_pyth:  When using this variant, the python code will be run
1095                                   using the Python 2.x (at least version 2.6 required)
1096                                   interface built into Vim.  See the comments above
1097                                   regarding potential conflicts between the two python
1098                                   versions.
1099
1100                         python:   When using this variant. the python code will be run
1101                                   using the version of python that is in the path or
1102                                   specified with the option |TagHL-PathToPython|.
1103
1104                         compiled: When using this variant, the compiled executable version
1105                                   of the python part of the plugin will be used (so no
1106                                   system version of python is required).  Note that this
1107                                   requires the compiled version to be installed as it is
1108                                   not part of the main distribution.  See the installation
1109                                           guide for more information: |TagHighlight-install|.
1110
1111                 Option Type: List
1112                 Default: ["if_pyth3", "if_pyth", "python", "compiled"]
1113
1114         Recurse                              *TagHL-Recurse*
1115                 If this option is set to True or 1, any call to |:UpdateTypesFile|
1116                 will scan recursively: tag files (and therefore the types highlighter
1117                 file based on that tag file) will contain tags from source code in the
1118                 source directory and all subdirectories of that directory.  If this
1119                 option is not set, or set to False or 0, only source code in the
1120                 source directory will be scanned.
1121
1122                 Option Type: Boolean
1123                 Default: True (recurse)
1124
1125         SkipPatterns                         *TagHL-SkipPatterns*
1126                 Any (python) regular expressions listed in this option will be matched
1127                 against any keyword names found in the tags file.  If they match, the
1128                 keyword names will be omitted from the types highlighter file.  For
1129                 example, set this option to ['MyVar.*', 'Number[0-9]+'] to exclude the
1130                 variables MyVarOne, MyVar, MyVariable, Number0, Number10 etc.
1131
1132                 Option Type: List
1133                 Default: [] (no patterns)
1134
1135         SkipReservedKeywords                 *TagHL-SkipReservedKeywords*
1136                 This option stops TagHighlight from overriding keywords that are
1137                 reserved words in the programming language in which they are found.
1138                 There may be situations in which (for example) ctags includes "bool"
1139                 in its list of tags for some C++ source code and TagHighlight will
1140                 then overwrite the default highlighting of "bool" with whatever ctags
1141                 says that tag type is.  By default, any keywords that match those in
1142                 the language definition file will be ignored by TagHighlight.  If you
1143                 want TagHighlight to take over the highlighting of keywords (assuming
1144                 there is a custom definition somewhere that ctags can find it), set
1145                 this option to False or 0 and the reserved keywords will be included.
1146                 
1147                 If you find that reserved keywords aren't skipped with your chosen
1148                 programming language, it may be that TagHighlight doesn't know about
1149                 the reserved keywords for your language.  Please feel free to add them
1150                 to the language definition file and send me a patch (see the bit about
1151                 ReservedKeywords in |TagHighlight-adding|) or send me a list of the
1152                 keywords and I'll do this myself.
1153
1154                 Note that the same effect can be achieved somewhat more laboriously
1155                 using |TagHL-SkipPatterns| (useful if you only want to skip a subset
1156                 of the reserved keywords).
1157
1158                 Option Type: Boolean
1159                 Default: True (don't include reserved keywords)
1160
1161         SkipVimKeywords                      *TagHL-SkipVimKeywords*
1162                 As well as being unable to use "syn keyword" for tag names that
1163                 contain non-keyword characters, Vim also cannot use "syn keyword" to
1164                 match certain vim keywords (such as "contains").  There are very few
1165                 of these keywords, so if any exist in the tag file, they are matched
1166                 with a "syn match" command.  If you'd rather just omit them ("syn match"
1167                 highlighting is much slower than "syn keyword" highlighting), set this
1168                 option to True or 1.  See also |TagHL-IncludeSynMatches|.
1169
1170                 Option Type: Boolean
1171                 Default: False (include Vim keywords)
1172
1173         SourceDir                            *TagHL-SourceDir*
1174                 If this option is set to an explicit directory, that directory will be
1175                 scanned for source files when generating tags.  By default, if a
1176                 project config file is found, the directory containing that will be
1177                 used.  If it wasn't, but a tag file was found, the directory
1178                 containing that will be used.  If it wasn't, but a types highlighter
1179                 file was found, the directory containing that will be used.  Finally,
1180                 if all of the other checks fail, the current working directory will be
1181                 used.
1182
1183                 Option Type: String
1184                 Default: None (use normal scanning method)
1185
1186         SyntaxLanguageOverrides              *TagHL-SyntaxLanguageOverrides*
1187                 If there are any entries in this dictionary, they will be used to
1188                 force a particular file that is being highlighted with a specified
1189                 syntax to be treated as representing a particular programming
1190                 language.  The dictionary key is a Vim syntax name (as reported by
1191                 ":set syntax?") and the dictionary value is the "suffix" defined for
1192                 that language (the bit in between "types_" and ".taghl" in the
1193                 generated type highlighter file).  In most cases, you probably want to
1194                 use |TagHL-FileTypeLanguageOverrides|.
1195
1196                 To disable a syntax type from matching against a language, set the
1197                 dictionary value to an empty string ("").
1198
1199                 This override will only work if 'Syntax' is in the list of
1200                 |TagHL-LanguageDetectionMethods|.
1201
1202         TagFileDirModePriority               *TagHL-TagFileDirModePriority*
1203                 This option is used to determine which directories to look in for a
1204                 tag file or in which directory to place a tag file when generating new
1205                 tags.  See |TagHL-DefaultDirModePriority| for details.
1206
1207                 Option Type: List
1208                 Default: ["Default"] (use DefaultDirModePriority value)
1209
1210         TagFileDirectory                     *TagHL-TagFileDirectory*
1211                 If the dir mode priority for tag files (see the option
1212                 |TagHL-TagFileDirModePriority|) contains the mode "Explicit", the
1213                 directory specified in this option will be used unconditionally if the
1214                 option has been set.
1215
1216                 Option Type: String
1217                 Default: None (no explicit directory)
1218
1219         TagFileName                          *TagHL-TagFileName*
1220                 By default, the file generated by ctags containing the tags
1221                 definitions are stored in a file named "tags".  If you wish to change
1222                 this, adjust this option appropriately.
1223
1224                 Option Type: String
1225                 Default: "tags"
1226
1227         TypesFileDirModePriority             *TagHL-TypesFileDirModePriority*
1228                 This option is used to determine which directories to look in for a
1229                 types highlighter file or in which directory to place a types
1230                 highlighter file when generating a new types highlighter.  See
1231                 |TagHL-DefaultDirModePriority| for details.
1232
1233                 Option Type: List
1234                 Default: ["Default"] (use DefaultDirModePriority value)
1235
1236         TypesFileDirectory                   *TagHL-TypesFileDirectory*
1237                 If the dir mode priority for types highlighter files (see the option
1238                 |TagHL-TypesFileDirModePriority|) contains the mode "Explicit", the
1239                 directory specified in this option will be used unconditionally if the
1240                 option has been set.
1241
1242                 Option Type: String
1243                 Default: None (no explicit directory)
1244
1245         TypesFileExtension                   *TagHL-TypesFileExtension*
1246                 By default, types highlighter files have taghl as an extension.  With
1247                 all the default options, the types highlighter file for C source code
1248                 will be called types_c.taghl.  This is constructed out of several
1249                 parts:
1250
1251                         "types" - This part is set with |TagHL-TypesFilePrefix|.
1252                         "_" - This is hard coded (although see |TagHL-TypesFileNameForce|).
1253                         "c" - This is the suffix for the current language.
1254                         "."     - This is hard coded.
1255                         "taghl" - This part is set with |TagHL-TypesFileExtension|.
1256
1257                 If really necessary, |TagHL-TypesFileNameForce| can be used to specify
1258                 an explicit filename, but I would discourage this.
1259
1260                 Option Type: String
1261                 Default: "taghl"
1262
1263         TypesFileLocation                    *TagHL-TypesFileLocation*
1264                 Used internally to tell the python part of the application where the
1265                 types file should be stored.  Do not use this option as it will be
1266                 automatically overwritten.  Instead, see |TagHL-TypesFileDirectory|
1267                 and |TagHL-TypesFileDirModePriority|.
1268
1269         TypesFileNameForce                   *TagHL-TypesFileNameForce*
1270                 Use this if you REALLY need to force a specific file name for the
1271                 types highlighter file.  It is generally better to configure
1272                 |TagHL-TypesFilePrefix| and |TagHL-TypesFileExtension|.
1273
1274                 Option Type: String
1275                 Default: None (use normal rules for generating file name)
1276
1277         TypesFilePrefix                      *TagHL-TypesFilePrefix*
1278                 Use this to configure the prefix of the generated (and read) types
1279                 highlighter files.  See |TagHL-TypesFileExtension| for more
1280                 information.
1281
1282                 Option Type: String
1283                 Default: "types"
1284
1285         UserLibraries                        *TagHL-UserLibraries*
1286                 If you have some libraries that are used by your code, but which are
1287                 not kept with your code, it is possible to highlight keywords used in
1288                 those libraries when working on the main code.  To do this, generate a
1289                 types highlighter file for the library code and then add the path to
1290                 the library types highlighter file to this option.  The path can be an
1291                 absolute path to the file (e.g. ["c:/libraries/mylibrary.taghl"]) or it
1292                 can be relative to the directory specified in the configuration option
1293                 |TagHL-UserLibraryDir| (e.g. for the same file as specified above, if
1294                 the option |TagHL-UserLibraryDir| is set to "c:/libraries", you could
1295                 set this option to ["mylibrary.taghl"].
1296
1297                 Option Type: List
1298                 Default: [] (no user libraries)
1299
1300         UserLibraryDir                       *TagHL-UserLibraryDir*
1301                 Location of libraries specified with relative paths in the option
1302                 |TagHL-UserLibraries|.  See the help for |TagHL-UserLibraries| for
1303                 more information.
1304
1305                 Option Type: String
1306                 Default: "." (use current directory)
1307
1308 ------------------------------------------------------------------------------
1309
1310 2.4 Integration with Other Software      *TagHighlight-integration*         {{{2
1311
1312 2.5.1 Tagbar Integration                 *TagHighlight-tagbar*              {{{3
1313
1314         |TagHighlight| can be used to highlight the names of classes etc in the
1315         tagbar window (thanks to Alexey Radkov for reporting this).  Tagbar uses
1316         its own filetype, so you can configure this with something like:
1317 >
1318                 let g:TagHighlightSettings['LanguageDetectionMethods'] =
1319                         \ ['Extension', 'FileType']
1320                 let g:TagHighlightSettings['FileTypeLanguageOverrides'] =
1321                         \ {'tagbar': 'c'}
1322 <
1323         You'll obviously need to change the language preference according to the
1324         language in which you program.  In order to use it with different
1325         languages in different project, use a |taghl_config.txt| project options
1326         file, something like this (customise the language for each file as
1327         required):
1328 >
1329                 LanguageDetectionMethods:Extension,FileType
1330                 FileTypeLanguageOverrides:
1331                         tagbar:c
1332                 # vim:ff=unix,noet
1333 <
1334         This assumes that you are writing C code; customise as appropriate.
1335
1336 2.5.2 Git Integration                    *TagHighlight-git*                 {{{3
1337
1338         A similar method to that used with tagbar can be used to highlight git
1339         commit messages.  Use something like this in your |taghl_config.txt|
1340         project configuration file:
1341 >
1342                 LanguageDetectionMethods:
1343                         Extension,FileType
1344                 FileTypeLanguageOverrides:
1345                         gitcommit:python
1346                 # vim:ff=unix,noet
1347 <
1348         This assumes that you are writing python code; customise as required.
1349
1350 2.5.3 Bazaar Integration                 *TagHighlight-bazaar*              {{{3
1351
1352         Unfortunately, there is no easy way to highlight tags in Bazaar projects
1353         as the commit message is stored in a temporary directory rather than
1354         within the project.  If anyone has a suggestion of how to work round this,
1355         please let me know.
1356
1357 2.5.4 Mercurial Integration              *TagHighlight-mercurial*           {{{3
1358
1359         Unfortunately, there is no easy way to highlight tags in Mercurial projects
1360         as the commit message is stored in a temporary directory rather than
1361         within the project.  If anyone has a suggestion of how to work round this,
1362         please let me know.
1363
1364 2.5.5 Subversion Integration             *TagHighlight-subversion*          {{{3
1365
1366         A similar method to that used with tagbar can be used to highlight
1367         subversion commit messages (thanks to Alexey Radkov for reporting this).
1368         Use something like this in your |taghl_config.txt| project configuration
1369         file:
1370 >
1371                 LanguageDetectionMethods:
1372                         Extension,FileType
1373                 FileTypeLanguageOverrides:
1374                         svn:java
1375                 # vim:ff=unix,noet
1376 <
1377         This assumes that you are writing Java code; customise as required.
1378
1379 ------------------------------------------------------------------------------
1380
1381 2.6 Installation                         *TagHighlight-install*             {{{2
1382
1383 2.6.1 Requirements                       *TagHighlight-requirements*        {{{3
1384
1385         |TagHighlight| consists of some Vim scripts and some Python scripts.  The
1386         Vim scripts require a relatively recent Vim (at least version 7).  To use
1387         the python 3 interface, version 7.3 is required.
1388
1389         As described in |TagHL-PythonVariantPriority|, there are a number of
1390         different ways you can run the Python part of the application.  If your
1391         Vim has the python interface compiled in, with python version 2.6 or
1392         greater and it works, you can use that to run the python code (you'll need
1393         python installed on your system).  If you have the python3 interface, you
1394         can also use that.  Alternatively, if you have python 2.6 or above
1395         (including python 3), you can use that.  Finally, there is a (separately
1396         distributed) compiled version if you don't have python on your system.
1397
1398 2.6.2 Installation Guide                 *TagHighlight-install-guide*       {{{3
1399
1400         Uninstalling ctags_highlighter:      *TagHighlight-remove-old*          {{{4
1401
1402                 This plugin replaces the previous version, which was called
1403                 ctags_highlighter.  Please delete ctags_highlighter before using this
1404                 plugin.  The files you need to delete (if present) in your ~/.vim or
1405                 vimfiles directory are:
1406
1407                 * mktypes.py
1408                 * extra_source/mktypes (delete the entire folder)
1409                 * doc/ctags_highlighting.txt
1410                 * plugin/ctags_highlighting.vim
1411                 * types_qt4.vim (if you installed the GUI types addon)
1412                 * types_wx.vim (if you installed the GUI types addon)
1413                 * types_wxpy.vim (if you installed the GUI types addon)
1414                 * types_android.vim (if you installed the GUI types addon)
1415                 * types_jdk.vim (if you installed the GUI types addon)
1416
1417         Installing the main plugin:          *TagHighlight-install-main*        {{{4
1418
1419                 The TagHighlight plugin is distributed as a zip file.  If you are
1420                 using the pathogen plugin, create a directory called TagHighlight in
1421                 ~/.vim/bundle or vimfiles/bundle.  Unzip the zip file directly into
1422                 the new directory.  If you are not using the pathogen plugin, simply
1423                 unzip the zip file directly into your ~/.vim or vimfiles directory.
1424
1425                 For details of the pathogen plugin, see:
1426 >
1427                         https://github.com/tpope/vim-pathogen
1428 <
1429         Updating the help tags:              *TagHighlight-update-helptags*     {{{4
1430
1431                 If you use pathogen, run:
1432 >
1433                         :call pathogen#helptags()
1434 <
1435                 Otherwise, use:
1436 >
1437                         :helptags ~/.vim/doc
1438 <
1439                 or:
1440 >
1441                         :helptags path/to/vimfiles/doc
1442 <
1443                 as appropriate.
1444
1445         Installing the compiled version:     *TagHighlight-install-compiled*    {{{4
1446
1447                 If you want to use the compiled version of the plugin (if you do not
1448                 have python on your system), download the zip file for your chosen
1449                 platform (or both Windows and Linux if you use the same vim
1450                 configuration directory on both platforms) and unzip in the same
1451                 location as the main plugin (~/.vim or ~/.vim/bundle/TagHighlight
1452                 depending on whether you use pathogen).
1453
1454         Installing the standard libraries:   *TagHighlight-install-stdlib*      {{{4
1455
1456                 If you want support for highlighting of standard libraries (see
1457                 |TagHighlight-standard-libraries|), unzip that zip file in the same
1458                 place as the main plugin (~/.vim or ~/.vim/bundle/TagHighlight
1459                 depending on whether you use pathogen).
1460
1461         Uninstalling:                        *TagHighlight-uninstall*           {{{4
1462
1463                 If you use pathogen and have followed the pathogen install
1464                 instructions above, you should be able to simply delete
1465                 ~/.vim/bundle/TagHighlight.
1466
1467                 If you don't use pathogen, the files/directories to delete (all
1468                 relative to ~/.vim or vimfiles) are:
1469
1470                 * plugin/TagHighlight.vim
1471                 * plugin/TagHighlight (entire directory)
1472                 * autoload/TagHighlight (entire directory)
1473                 * doc/TagHighlight.txt
1474
1475 ==============================================================================
1476 3. Standard Libraries                    *TagHighlight-standard-libraries*  {{{1
1477
1478 3.1 Introduction                         *TagHighlight-stdlib-intro*        {{{2
1479
1480         |TagHighlight| supports two different methods for loading in tag definitions
1481         for highlighting of tags that are defined outside of the main source code.
1482
1483         For libraries that are specific to your project and not likely to be used
1484         widely, User Libraries can be defined.  For these, types highlighter files
1485         are generated for the library and then the project configuration links
1486         directly to those library files.  For more information on user libraries,
1487         see |TagHL-UserLibraries|.
1488
1489         For libraries that are common across a lot of projects (and probably a lot
1490         of people), standard libraries can be defined.  A number of these standard
1491         libraries are available on the |TagHighlight-website|.  For installation
1492         instructions, see |TagHighlight-install-stdlib|.  At the time of writing,
1493         the available standard libraries are:
1494
1495         * "Android SDK": Android Software Development Kit (Java)
1496         * "JDK": Java Development Kit (Java)
1497         * "PySide": PySide framework (Python; limited support)
1498         * "Qt4": Qt4 (C++)
1499         * "wxpython": wxPython (Python; limited support)
1500         * "wxWidgets": wxWidgets (C++)
1501
1502         If a source file is opened that looks like it might be part of one of
1503         these libraries, the standard library highlighter is automatically loaded.
1504         Forcing loading of a particular library can be achieved using the option
1505         |TagHL-ForcedStandardLibraries| (the library names are the bits in double
1506         quotes in the list above).  Disabling standard library parsing can be
1507         achieved either by deleting the standard libraries (or not installing them
1508         in the first place), or by setting |TagHL-DisableStandardLibraries| to
1509         True or 1.
1510
1511 ------------------------------------------------------------------------------
1512
1513 3.2 Adding More Standard Libraries       *TagHighlight-adding-libraries*    {{{2
1514
1515         Standard libraries are stored in the standard_libraries subdirectory of
1516         the main plugin area (plugin/TagHighlight).  Each standard library is held
1517         in its own subdirectory (the name is not important).  In that directory
1518         there should be a types highlighter file generated from the standard
1519         library: again the name is not important, but it shouldn't end with .vim
1520         as otherwise it will be automatically sourced by Vim on startup!).  As an
1521         example, the Android SDK highlighter file is called android_sdk.taghl.  In
1522         addition, there should be a file called library_types.txt giving the
1523         details of that library.
1524
1525         The format of library_types.txt is similar to that of the project
1526         configuration file (see |taghl_config.txt|) and all txt files used by
1527         TagHighlight.  The required fields are as follows:
1528
1529                 LibraryName - The "friendly" name of the library, e.g. Android SDK
1530
1531                 TypesFiles - A comma-separated list of types highlighter files to load
1532                              (usually only one).
1533
1534                 TypesSuffixes - Language suffixes to which this highlighter applies.
1535
1536                 CheckMode - One of the following methods for determining if a source
1537                             file should load this standard library:
1538
1539                         * Always - This standard library will be loaded for all files of
1540                                    the correct language (where TypesSuffixes matches).
1541
1542                         * MatchStart - Search for any one of a set of regular expressions
1543                                        (set with MatchREs) in the first MatchLines lines
1544                                        (default 30) in the file.
1545
1546                         * MatchEnd - Like MatchStart, but look in the last MatchLines lines
1547                                        in the file.
1548
1549                         * Custom - Call a custom function (name provided in
1550                                    CustomFunction) with the suffix as a parameter.  If it
1551                                    returns 'Load', load the library; if it returns 'Skip',
1552                                    do not load the library.  Any other return value is an
1553                                    error.
1554
1555         Other options that may be required depending on the CheckMode:
1556
1557                 MatchREs - list of Vim regular expressions to compare against the
1558                            first (if using MatchStart) or last (if using MatchEnd)
1559                            MatchLines lines in the file.  Required for MatchStart or
1560                            MatchEnd.
1561
1562                 MatchLines - If using MatchStart or MatchEnd, the number of lines to
1563                              scan when trying to match the regular expressions.  If
1564                              not provided, defaults to 30.
1565
1566                 CustomFunction - The name of the function used in the Custom
1567                                  CheckMode.  Required if using Custom.
1568
1569         See the existing standard libraries for examples.
1570
1571 ==============================================================================
1572 4. TagHighlight Customisation            *TagHighlight-custom*              {{{1
1573
1574 4.1 Adding More Languages                *TagHighlight-adding*              {{{2
1575
1576         1.  Run ctags --list-languages and check that the required language is
1577                 present.
1578
1579         2.  If you're using a custom version of ctags highlighter with extra
1580                 languages, you may need to add the details to the kind list in
1581                 plugin/TagHighlight/data/kinds.txt (for most standard languages, this
1582                 won't be necessary).  To do this, run:
1583 >
1584                         ctags --list-kinds=all
1585 <
1586                 and examine the entries for your language.
1587
1588         3.  Create a new file in plugin/TagHighlight/data/languages/ with a .txt
1589                 extension (the file name can be anything you want).  Set the fileformat
1590                 to be 'unix' for consistency and don't expand tabs in case you need to
1591                 add any multi-line lists:
1592 >
1593                         set ff=unix noet
1594 <
1595         4.  In that file, add the following fields in Key:Value format (one per
1596                 line):
1597
1598                 FriendlyName - Whatever you prefer to call the language.
1599
1600                 CTagsName - Whatever ctags refers to the language as.
1601
1602                 PythonExtensionMatcher -        A python regular expression that matches
1603                                                                         the extensions of files that are written
1604                                                                         in this language.
1605
1606                 VimExtensionMatcher -   The Vim regular expression version of
1607                                                                 PythonExtensionMatcher.
1608
1609                 VimFileTypes -  A list of Vim file types (the output of the Vim command
1610                                                 ":set ft?") that are relevant for this language.
1611
1612                 VimSyntaxes -   A list of Vim syntax names (the output of the Vim
1613                                                 command ":set syntax?") that are relevant for this
1614                                                 language.
1615
1616                 Suffix -        Whatever you would like the generated files to be named,
1617                                         e.g. for C code, the suffix is c and the generated files
1618                                         are by default called types_c.taghl.
1619
1620         5.  Optionally, add other fields as required:
1621
1622                 ReservedKeywords - This is a list of predefined keywords for a given
1623                                    language - those keywords that are typically
1624                                    designated 'reserved words' in the language
1625                                    documentation.  This is used when a user specifies
1626                                    the |TagHL-SkipReservedKeywords| option.  This
1627                                    option can either be specified as a list of
1628                                    comma-separated keywords on a single line, as a
1629                                    list of keywords one per line or (more
1630                                    conveniently) as a list of keywords with several
1631                                    per-line separated by spaces:
1632 >
1633                             # Example 1:
1634                                                         ReservedKeywords:bool,asm,break,case
1635                                                         # Example 2:
1636                                                         ReservedKeywords:
1637                                                                 bool
1638                                                                 asm
1639                                                                 break
1640                                                                 case
1641                                                         # Example 3:
1642                                                         ReservedKeywords:
1643                                                                 bool asm break
1644                                                                 case
1645 <
1646                                                    See the examples in the existing language
1647                                                    definitions for details.
1648
1649                 SkipList -  Any specific ctags "kinds" (single characters referring
1650                                         to types of tags) that you want to omit from the types
1651                                         file.  For example, for C code, function prototypes are
1652                                 omitted (function definitions are included) by setting
1653                                 SkipList to p.  To include multiple items, separate
1654                                 each item with a comma.  To see a list of kinds for a
1655                                 language, use:
1656 >
1657                                                 ctags --list-kinds
1658 <
1659                 SpecialSyntaxHandlers - This is for unusual cases where particular
1660                                                                 syntax commands are required for a given
1661                                                                 language.  Add any functions you want to
1662                                                                 call here.  As an example, for Java code,
1663                                                                 all syntax items must be added to the
1664                                                                 javaTop cluster; this is done in a special
1665                                                                 syntax handler.  For most languages this
1666                                                                 is unnecessary.
1667
1668                 Priority -  Where a tag name is used for multiple different types (e.g.
1669                                         as a defined name and as a typedef), it can only be
1670                                         highlighted as one or the other (Vim is not aware of the
1671                                 context of the keyword).  The priority defines whether it
1672                                 should (in this case) be highlighted as a defined name or
1673                                 as a typedef.  The default priority order is shown in
1674                                 plugin/TagHighlight/data/language_defaults.txt.  Entries
1675                                 not included in the priority list are treated in
1676                                 alphabetical order after the ones that are in the priority
1677                                         list.  If the default priority is not appropriate for the
1678                                         new language, it can be overridden in the language
1679                                         definition.
1680
1681                 IsKeyword - Most source files have Vim's |'iskeyword'| option set to
1682                                         @,48-57,_,192-255.  If that is incorrect for the language
1683                                         that you are defining, it can be changed in the new
1684                                         language definition.  Generally not really required.
1685
1686         6.  Add a modeline for consistency:
1687 >
1688                 # vim: ff=unix:noet
1689 <
1690         7.  Test your new language!
1691
1692         8.  Send me a copy for inclusion in the main distribution.  If you're
1693                 sending it to me as a bitbucket pull request, it would help enormously
1694                 if you could also also:
1695
1696                 * Update the list of languages (|TagHighlight-languages|) in this
1697                   file.
1698                 * Update the list of languages in README.md (shown on the bitbucket
1699                   front page).
1700                 * Add a note in the latest entry in the change log in this file
1701               (|TagHighlight-history|).  If there isn't an entry there for an
1702                   unreleased version, please add one: something like
1703 >
1704                         x.x.x: xxth Xxxxxxxx 2012  : Added support for LANGUAGE.
1705 <
1706                   (leave the x characters in: I'll change these when I release the
1707                   code).
1708
1709 4.1.1 Example                            *TagHighlight-add-example*         {{{3
1710
1711         It is worth looking at the existing language files for examples.  The C#
1712         language file is called csharp.txt and looks like this:
1713 >
1714                 FriendlyName:c#
1715                 CTagsName:c#
1716                 PythonExtensionMatcher:cs
1717                 VimExtensionMatcher:cs
1718                 Suffix:cs
1719
1720                 # vim: ff=unix:noet
1721 <
1722         The friendly name and CTagsName are both 'c#' (it is quite normal for
1723         these to be the same).  Only one file extension is supported (cs), so the
1724         extension matchers are trivial.  The selected suffix is cs (this is the
1725         bit that goes in the filename).
1726
1727         It really is that easy!
1728
1729 ==============================================================================
1730 5. Contributing Changes                  *TagHighlight-contributions*       {{{1
1731
1732         Contributions to TagHighlight are, of course, very welcome.  The bug
1733         tracker is currently private (due to it running on my home server behind a
1734         firewall) and this is unlikely to change in the near future.  However, the
1735         code is public and I am happy to accept, patches or suggestions for
1736         improvements and usage examples.
1737
1738 5.1 Suggestions for Improvements         *TagHighlight-suggestions*         {{{2
1739
1740         For suggestions for improvements, please send me an email to:
1741 >
1742                 abudden _AT_ gmail.com
1743 <
1744         Please include as much detail as possible.
1745
1746 5.2 Patches                              *TagHighlight-patches*             {{{2
1747
1748         If you've made an improvement to TagHighlight and would like your changes
1749         to be included in the main distribution, there are a number of ways of
1750         doing this.  The code is maintained in a Mercurial repository and
1751         published on bitbucket.  In rough order of preference, the ways you can
1752         send me a patch are:
1753
1754                 1. Bitbucket pull request (https://bitbucket.org/abudden/taghighlight)
1755
1756                 2. Mercurial bundle (see "hg help bundle") attached to an email.
1757
1758                 3. Mercurial patchbomb email (for details of the patchbomb extension,
1759                 please see http://mercurial.selenic.com/wiki/PatchbombExtension).
1760
1761         If sending a patch, please follow these guidelines:
1762
1763         * Could should conform to the same general coding standard as the existing
1764           source tree.  This isn't especially strict or well documented, but at
1765           the very least python code should be indented with four spaces and
1766           everything else should be indented with hard tabs but alignment should
1767           be with spaces.  As a general guide, '^\t\+' is good but either '\S\t'
1768           or '^\s\+' is bad (there are exceptions).
1769
1770         * Please help to maintain the documentation at the same time, including:
1771
1772                 - The history in |TagHighlight-history|: if there isn't an entry there
1773                   for an unreleased version, pease add one, something like:
1774 >
1775                         x.x.x: xxth Xxxxxxxx 2012  : Added support for LANGUAGE.
1776 <
1777                   (leave the x characters in, I'll change these when I release the
1778                   next version).
1779
1780                 - Any options that have been added: add these both to the categorised
1781                   |TagHighlight-option-list| and the alphabetic (and more detailed)
1782                   |TagHighlight-option-summary|.
1783
1784 5.3 Usage Examples                       *TagHighlight-usage-examples*      {{{2
1785
1786         There is a wiki available at:
1787 >
1788                 https://bitbucket.org/abudden/taghighlight/wiki/Home
1789 <
1790         Please feel free to add usage examples to this page.
1791
1792 ==============================================================================
1793 6. Troubleshooting                       *TagHighlight-troubleshooting*     {{{1
1794
1795         A debugging log can be generated by running the command:
1796 >
1797                 :UpdateTypesFileDebug /path/to/debug_log.txt
1798 <
1799         This will generate tags (recursively), create a types highlighter file and
1800         try to read the relevant types highlighter files for all open files.  All
1801         debugging information will be written to /path/to/debug_log.txt.
1802
1803         If you're having difficulties getting TagHighlight to work, please try
1804         running the above command and send a brief description of the symptoms
1805         along with a copy of the debug log to me at abudden _AT_ gmail _DOT_ com.
1806         I'll do my best to help you get it working as quickly as I can.
1807
1808         If you're having problems that are specific to the |:UpdateTypesFileOnly|
1809         command, please use the following commands, which work in much the same
1810         way as the commands above:
1811 >
1812                 :let g:TagHighlightSettings['DebugLevel'] = 'Information'
1813                 :let g:TagHighlightSettings['DebugFile'] = '/path/to/typesonly.log'
1814                 :UpdateTypesFileOnly
1815 <
1816 ==============================================================================
1817 7. Credits                             *TagHighlight-credits*               {{{1
1818
1819         Software:
1820
1821                 Al Budden - Lead Developer
1822
1823         Additional Languages:
1824
1825                 Aleksey Baibarin - C# Support (and suggestions for other improvements)
1826                 Ali Hamdi - Go Support (and suggestions for other improvements)
1827                 Lee Gauthier - Scala Support
1828                 Oleg Lebedev - Fortran Support
1829                 Piotr Yordanov - Javascript support (and other suggestions)
1830
1831         Suggestions for Improvement and Testing:
1832
1833                 Alan Warren - Suggestions for Improvement
1834                 Alexey Radkov - Suggestions for Improvement
1835                 Hong Xu - Suggestions for Improvement
1836                 Marcus Martin - Testing & Suggestions
1837                 Mishail - Testing & Suggestions
1838                 Prasun Ratn - Testing & Suggestions
1839                 Yongwei Wu - Testing & Suggestions
1840
1841         Additional credits from the predecessor (ctags_highlighting):
1842
1843                 Mikhail Stepura - better handling of paths with spaces
1844                 Sung Pae - customisation of tags file name
1845
1846 ==============================================================================
1847 8. TagHighlight History                *TagHighlight-history*               {{{1
1848
1849 x.x.x: xxth Xxxxxxxx 2012  : Fixed globpath to prevent use of wildignore
1850                              option (thanks to Vincent).  Added support for
1851                              Javascript (thanks to Piotr Yordanov).
1852                              Transferred source repository from git to
1853                                                          mercurial.  Added support for custom ctags
1854                                                          argument lists (option CtagsArguments) in order
1855                                                          to allow use with versions of ctags (like
1856                                                          jsctags) that don't accept the same arguments as
1857                                                          exuberant ctags (thanks to Piotr Yordanov for the
1858                                                          suggestion and help getting jsctags working).
1859                                                          Also added support for CtagsVariant arguments to
1860                                                          simplify this process for known variants.
1861                                                          Support for jsctags is still fairly flaky as
1862                                                          jsctags seems to fail very easily (and I've only
1863                                                          used it for generating tags for its own source
1864                                                          code!).  Added a reference (in the documentation)
1865                                                          to the new wiki.  Added initial version of a
1866                                                          manager for the 'tags' option to automatically
1867                                                          handle tag files for user libraries (thanks to
1868                                                          Alexey Radkov and Ali Hamdi).  Fixed a bug in the
1869                                                          ParsingSkipList option implementation.  Added
1870                                                          option to only generate the tags file if one is
1871                                                          not present or to only generate types file if one
1872                                                          IS present (thanks to Ali Hamdi for the
1873                                                          suggestion).  Added CtagsExtraArguments and
1874                                                          clarified what is meant by CtagsArguments (thanks
1875                                                          to Alan Warren for the suggestion).  Added
1876                                                          support for skipping reserved keywords for given
1877                                                          languages when generating types files.  Initially
1878                                                          the reserved keywords have been recorded for C++,
1879                                                          Python, Java and C#.  Thanks to Alexey Radkov and
1880                                                          Alan Warren for the suggestions.
1881
1882 2.1.5: 20th February 2012  : Added support for Scala (thanks to Lee Gauthier).
1883
1884 2.1.4: 15th December 2011  : Improved internal modeline to make addition of
1885                              languages more straightforward.  Added support
1886                              for Go Programming Language (thanks to Ali Hamdi).
1887
1888 2.1.3: 14th October 2011   : Minor typo correction in documentation.  Fix to
1889                              make TagHighlight with pre 7.3-288 versions of
1890                              Vim (bug in has() function).  Added support for
1891                              Fortran (thanks to Oleg Lebedev).
1892
1893 2.1.2:  30th August 2011   : Allow overriding the file-language relationship
1894                              without having to edit the language definitions.
1895                              Added support for Matlab (if your version of
1896                              ctags supports it).  Added support for .hh
1897                              extension for C/C++ headers.  Fixed bug with
1898                              highlight priority for non-specified types.
1899
1900 2.1.1:  23rd August 2011   : Addition of LanguageDetectionMethods option to
1901                              allow loading of types when FileType or Syntax
1902                              are set (thanks to Hong Xu for the suggestion).
1903                              This also involved addition of syntax and
1904                                                          filetype definitions to all languages.  Prevent
1905                                                          Vim from repeatedly loading autocmds in plugin
1906                                                          development mode.  Don't overwrite Cursor colour
1907                                                          definitions with SQL cursor colouring (thanks
1908                                                          again to Hong Xu for reporting this bug).
1909
1910 2.1.0:  22nd August 2011   : First public release of TagHighlight.  Many
1911                              thanks to Aleksey Baibarin, Marcus Martin,
1912                                                          Mishail, Prasun Ratn and Yongwei Wu for the help
1913                                                          with testing the various pre-release versions of
1914                                                          this plugin.
1915
1916 2.0.24: 12th August 2011   : Release script improvements to include packaging
1917                              of standard libraries.
1918
1919 2.0.23: 12th August 2011   : Improvements to variable passing when options
1920                              have been set to 'True' rather than 1.
1921
1922 2.0.22: 11th August 2011   : Website link update.  Comments on troubleshooting
1923                              issues with UpdateTypesFileOnly.  Fix for check
1924                              for existence of tag file (not looking in the
1925                              correct directory).
1926
1927 2.0.21: 10th August 2011   : Additional debug.
1928
1929 2.0.20: 9th August 2011    : Further improvements to build script.
1930
1931 2.0.19: 9th August 2011    : Minor tweaks to build script.
1932
1933 2.0.18: 9th August 2011    : Preparation for publishing code on github.
1934
1935 2.0.17: 9th August 2011    : (Internal change).  Separated TagHighlight
1936                              version control from vimfiles bzr repository into
1937                              separate git repository.  Revision number no
1938                              longer meaningful.
1939
1940 2.0.16: 8th August 2011    : Wildcard matches are for files only, not
1941                              directories (work-around for issue with tags file
1942                              having same name as svn tags directory).  Extra
1943                              debug regarding working directory etc.
1944                              Simplified commands by moving functionality into
1945                              a new function.  REMOVED non-recursive command!
1946
1947 2.0.15: 5th August 2011    : Debug output improvements.
1948
1949 2.0.14: 5th August 2011    : Bug fix for selection of source directory.  If
1950                              one of the explicit locations was set to 'None',
1951                              it was using 'None' as the source dir location.
1952                              Added version information printing to debug
1953                              output.
1954
1955 2.0.13: 4th August 2011    : Improvements to directory searching (mainly for
1956                              Cygwin).  Addition of option to include timestamp
1957                              in debug log (Vim debug output only at present).
1958
1959 2.0.12: 3rd August 2011    : Added option to limit number of directories to
1960                                                          search up through when looking for configuration
1961                                                          or existing tags file.
1962
1963 2.0.11: 2nd August 2011    : Added some example configurations to the
1964                              documentation.
1965
1966 2.0.10: 2nd August 2011    : Added extensive debug stuff.
1967
1968 2.0.9: 30th July 2011      : Attempt to work around python bug 3905 (issue
1969                              with subprocess when called from GUI
1970                              application).
1971
1972 2.0.8: 30th July 2011      : Fixed erroneous function call.
1973
1974 2.0.7: 30th July 2011      : Bug fix for exception handling.
1975
1976 2.0.6: 29th July 2011      : Included description of defaults in
1977                              documentation.  Improved python version checking:
1978                              don't use python if version is < 2.6 or cannot
1979                              import print_function.
1980
1981 2.0.5: 28th July 2011      : Bug fix in Java special handler.  Added
1982                              description of how to add languages not supported
1983                              by standard ctags.
1984
1985 2.0.4: 27th July 2011      : Fixed bug in python interface (old variable
1986                              name); renamed ctags interface python code to
1987                              avoid potential issues with other plugins
1988                              thinking that ctags.py is actually ctags.
1989                              Further improvements to handling paths with
1990                              spaces.
1991
1992 2.0.3: 26th July 2011      : Added missing documentation to zip file!
1993
1994 2.0.2: 26th July 2011      : Improved Linux compiled version support.
1995
1996 2.0.1: 25th July 2011      : Added provisional support for a Linux compiled
1997                              version.
1998
1999 2.0.0: 25th July 2011      : Significant refactor of all the code.  Reworked
2000                                                          the way options are set (can now be set globally,
2001                                                          per buffer or in a project configuration file).
2002                                                          All options now moved into dictionaries to
2003                                                          minimise the number of variables created by the
2004                                                          plugin.  Moved most of the functionality into
2005                                                          autoload to simplify operation.  Added support
2006                                                          for using the python interface (either 2.6+ or
2007                                                          3.0+), or using a system python (either 2.6+ or
2008                                                          3.0+) or using a compiled version on either
2009                                                          Windows.  Improved library implementation to
2010                                                          improve loading method and ease generation of
2011                                                          standard libraries.  Added support for user
2012                                                          libraries.  Improved language handlers (now
2013                                                          configured from a single text file).  Renamed
2014                                                          project from ctags_highlighter to TagHighlight.
2015                                                          New revision numbering scheme.  Changed default
2016                                                          types file extension.  Allow complete
2017                                                          customisation of location and name of types and
2018                                                          tags files.  Allow specific keywords to be
2019                                                          skipped when generating types files.  Added
2020                                                          support for pre-read, post-read, pre-update and
2021                                                          post-update hooks to allow further customisation.
2022
2023 r461 : 6th May 2011        : Allow explicit setting of ctags executable
2024                                                          name.  Added troubleshooting section to the
2025                                                          manual.
2026
2027 r458 : 7th March 2011      : Inclusion of vim keywords (display, contained
2028                                                          etc) controlled by separate option.
2029
2030 r456 : 6th March 2011      : Fixed accidental file-type change.
2031
2032 r452 : 6th March 2011      : Better handling of unknown ctags tag kinds.
2033
2034 r443 : 19th February 2011  : Allow customisation of the filenames used
2035                                                          for tags and types files (thanks to Sung Pae).
2036
2037 r442 : 16th February 2011  : Improved prioritisation of object-oriented
2038                                                          language types (thanks to Aleksey Baibarin).
2039
2040 r440 : 16th February 2011  : More explicit choice of C/C++ file extensions to
2041                                                          avoid conflicts with C# (thanks to Aleksey
2042                                                          Baibarin).
2043
2044 r439 : 10th February 2011  : Kill any cscope connections prior to running 
2045                                                          script in order to prevent cscope from locking
2046                                                          the cscope.out file.
2047
2048 r435 : 11th January 2011   : Changed default to not include syntax matches
2049                                                          unless either g:TypesFileIncludeSynMatches or
2050                                                          b:TypesFileIncludeSynMatches is set to 1 (this
2051                                                          makes the highlighting much faster for large
2052                                                          projects).
2053
2054 r431 : 2nd December 2010   : Add support for local variables in non-C
2055                                                          languages.
2056
2057 r429 : 2nd December 2010   : Improvements to cope with spaces in paths.
2058
2059 r425 : 16th November 2010  : Added support for Java and Android SDKs.
2060
2061 r410 : 9th September 2010  : Improved option configuration implementation.
2062
2063 r409 : 9th September 2010  : Allow cscope configuration options to be local
2064                                                          rather than buffer specific.
2065
2066 r398 : 29th March 2010     : Added support for python import in the listing.
2067
2068 r396 : 29th March 2010     : Factored out old ctags_[a-z] types to improve
2069                                                          language support.
2070
2071 r394 : 26th March 2010     : Fix for python use.
2072
2073 r391 : 2nd March 2010      : Fix for ctags names.
2074
2075 r390 : 2nd March 2010      : Attempted improvements to code including support
2076                                                          for C# (thanks to Aleksey Baibarin).
2077
2078 r387 : 20th February 2010  : Fixed VIMFILESDIR typo.
2079
2080 r384 : 19th February 2010  : Improvements to VIMFILESDIR identification.
2081                                                          Re-architecture of type definitions to make
2082                                                          them more sensitive to different ctags "kinds"
2083                                                          for different languages.  Note that Enumerator
2084                                                          has been renamed to EnumerationValue: the latest
2085                                                          Bandit Colour Scheme supports this.
2086
2087 r382 : 13th February 2010  : Fixed escaping of paths and operation of
2088                                                          ReadTypes when not in an autocommand.
2089
2090 r340 : 2nd November 2009   : Added missing winrestview().
2091
2092 r330 : 16th September 2009 : Minor Documentation update.
2093
2094 r329 : 16th September 2009 : Added revision output to mktypes.
2095
2096 r328 : 16th September 2009 : Fix for bug with path finding on Windows where
2097                                                          directories in the path end in a backslash.
2098
2099 r326 : 15th September 2009 : Added revision number to debug output.
2100
2101 r324 : 14th September 2009 : Fixed Linux bugs with new implementation.
2102
2103 r321 : 14th September 2009 : Fixed bug with returning to the correct window
2104                                                          after use, added debugging statements and moved
2105                                                          executable search to a separate function.  Also
2106                                                          added preliminary work towards more explicit
2107                                                          type names.
2108
2109 r309 : 17th August 2009    : Added documentation.
2110
2111 r302 : 10th August 2009    : Added experimental PHP support.
2112
2113 r301 : 7th August 2009     : Made GUI tags and types files optional and added
2114                                                          shellescape to protect paths (thanks to Mikhail
2115                                                          Stepura again). The gui_tags_and_types.vba file
2116                                                          contains the tags and highlighting definitions
2117                                                          for Qt, wxWidgets and wxPython (used to be
2118                                                          included in the main distribution).
2119
2120 r292 : 3rd August 2009     : Fixed bug with cscope option.
2121
2122 r285 : 27th July 2009      : Added support for ctags being stored in a path
2123                                                          with spaces and other odd characters (thanks to
2124                                                          Mikhail Stepura).
2125
2126 r261 : 23rd May 2009       : Changed some of the defaults to the python script
2127                                                          (so fewer options need to be passed by
2128                                                          UpdateTypesFile).  It should now be possible to
2129                                                          generate the types file simply by running
2130                                                          "mktypes.py" or "mktypes.py -r" in the project
2131                                                          directory.  Of course, UpdateTypesFile works too.
2132                                                          Added UpdateTypesFileOnly command for projects in
2133                                                          which the tags file is updated externally (e.g.
2134                                                          the Linux kernel source).  Removed regular
2135                                                          expression matches by default: this is much
2136                                                          quicker for large projects.
2137
2138 r252 : 21st May 2009       : Added (optional) support for highlighting of
2139                                                          local variables (not scope-specific: just
2140                                                          recognises names).  Tidied up tag generation.
2141
2142 r173 : 17th November 2008  : Added automatic reloading of types file whenever
2143                                                          :UpdateTypesFile is run.  Also runs cscope (in
2144                                                          the background) if cscope.files is present in the
2145                                                          current working directory.
2146
2147 r132 : 17th September 2008 : Updated to support limiting the languages checked
2148                                                          for (intended to be used with the project plugin
2149                                                          and it's in= option) in order to speed it up a
2150                                                          bit. Also added project option for recursion (so
2151                                                          you don't have to bother with the exclamation
2152                                                          mark) and parsing of local enumerations.
2153                                                          Finally, added sorting of tags file such that
2154                                                          function implementations come before function
2155                                                          declarations, regardless of the alphabetic order
2156                                                          of the file names in which they are stored.
2157                                                          Finally, added zipfile version in case of
2158                                                          problems with vba.
2159
2160 r129 : 9th September 2008  : Updated to only add to the various rainbow.vim
2161                                                          related groups if b:hlrainbow is set.
2162
2163 r126 : 5th September 2008  : This has now been updated to run considerably
2164                                                          quicker (with only one pass by ctags and
2165                                                          excluding directories named "docs" to avoid
2166                                                          spending a long time searching through all the
2167                                                          files that doxygen creates).  On the project I
2168                                                          used to benchmark it, the running time reduced
2169                                                          from about two minutes to about seven seconds!
2170
2171 ==============================================================================
2172 Modelines: {{{1
2173  vim:tw=78:ts=4:ft=help:fdm=marker: