Commits

abudden committed 01b33dd

Initial work towards (#19) documentation updates.

Comments (0)

Files changed (1)

doc/TagHighlight.txt

+*TagHighlight.txt*       Tag Highlighting
+
+Author:	    A. S. Budden <abuddenNOSPAM@NOSPAMgmail.com>
+	    Remove NOSPAM.
+
+Copyright:  (c) 2009-2011 by A. S. Budden             *TagHighlight-copyright*
+	    The VIM LICENCE applies to all files that constitute the
+	    TagHighlight distribution.  See |copyright| except use
+	    TagHighlight instead of "Vim".
+	    NO WARRANTY, EXPRESS OR IMPLIED. USE AT-YOUR-OWN-RISK.
+
+==============================================================================
+1. Contents	              *TagHighlight* *TagHighlight-contents*          {{{1
+
+    1.    Contents	                     |TagHighlight-contents|
+    
+    2.    TagHighlight Manual	   	     |TagHighlight-manual|
+    2.1   Introduction                       |TagHighlight-intro|
+    2.2   Commands                           |TagHighlight-commands|
+    2.3   Colouring                          |TagHighlight-colours|
+    2.4   Configuration                      |TagHighlight-config|
+    2.4.1 How to Set Options                 |TagHighlight-how-options|
+    2.4.2 Option Summary	             |TagHighlight-option-list|
+    2.4.3 Option Details	             |TagHighlight-option-details|
+    2.5   Installation                       |TagHighlight-install|
+    
+    3.    TagHighlight Customisation	     |TagHighlight-custom|
+    3.1   Adding More Languages              |TagHighlight-adding|
+    3.1.1 Example                            |TagHighlight-add-example|
+
+    4.    Troubleshooting                    |TagHighlight-troubleshooting|
+    
+    5.    Feature Wishlist                   |TagHighlight-wishlist|
+    
+    6.    TagHighlight History		     |TagHighlight-history|
+
+==============================================================================
+2. TagHighlight Manual		 *TagHighlight-manual*                      {{{1
+
+2.1 Introduction                         *TagHighlight-intro*               {{{2
+
+    This set of scripts is designed to increase the number of highlighting
+    groups used by Vim.  This makes it quicker and easier to spot errors in
+    your code.  By using ctags and parsing the output, the typedefs, #defines,
+    enumerated names etc are all clearly highlighted in different colours.
+    
+    The idea was based on the comments in |tag-highlight|, but I wanted to
+    take it a little further.
+    
+    This is achieved through a little python script to interact with ctags and
+    to parse the result and a small Vim script that makes Vim read the
+    resulting files.  Finally, a new command (:UpdateTypesFile) is added (with
+    optional !  for recursive operation) to keep the generated files up to
+    date.
+    
+    At present, the highlighter supports the following languages:
+    
+        * C/C++
+        * C#
+        * Java
+        * Perl
+        * PHP
+        * Python
+        * Ruby (largely untested)
+        * VHDL (if your version of ctags supports it)
+    
+    It should also work correctly with Charles Campbell's rainbow.vim bracket
+    highlighter.
+    
+    The vast majority of the testing has been with C source code, so I'd be
+    very interested in any feedback on the use with C++ and the various other
+    languages.
+
+    Currently requires exuberant ctags or one of its derivatives.  Exuberant
+    ctags is available from:
+>
+    http://ctags.sourceforge.net
+<
+    Adding more languages is extremely simple, see
+    |TagHighlight-adding|.
+    
+                                         *TagHighlight-website*
+    
+    Screenshots of the highlighter in operation are available at the website:
+>
+    http://sites.google.com/site/abudden/contents/Vim-Scripts/ctags-highlighting
+<
+
+2.2 Commands                             *TagHighlight-commands*            {{{2
+
+    The following commands are provided by this plugin:
+
+	:UpdateTypesFile                 *UpdateTypesFile*
+
+	    This command creates the syntax highlighting file used to show the
+	    extra colouring.  It then updates all of the open files
+	    automatically.  By default, it only looks for source files in the
+	    current directory.  However, see |UpdateTypesFile!| and
+	    |TagHL-Recurse|.
+
+	:UpdateTypesFile!                *UpdateTypesFile!*
+    
+	    This command operates in the same way as |UpdateTypesFile| except
+	    that it looks for source files recursively into subdirectories.
+	    It automatically excludes directories named either "docs" or
+	    "Documentation".  See also |b:TypesFileRecurse|.
+
+	:UpdateTypesFileOnly             *UpdateTypesFileOnly*
+
+	    This command operates in the same manner as |UpdateTypesFile|, but
+	    it uses the current tags file rather than generating a new one
+	    (useful if you're generating tags files as part of your build
+	    process.
+
+	:ReadTypes			 *ReadTypes*
+
+	    This comment can be used to manually read in any types files to
+	    highlight keywords.  Generally not likely to be used as the
+	    built-in autocmds should load the types files when a file is
+	    loaded or the types files are updated.
+
+2.3 Colouring                            *TagHighlight-colours*             {{{2
+
+    The tag highlighter uses a number of additional highlighting groups to
+    differentiate between different types of tag.  These are not supported as
+    standard by many colour schemes.  You can either download the "bandit"
+    colour scheme from:
+>
+    http://sites.google.com/site/abudden/contents/Vim-Scripts/bandit-colour-scheme
+<
+    (screenshots of C source code on the |TagHighlight-website|) or you
+    can configure the extra highlighting groups yourself.  The following
+    highlight groups should be defined:
+
+	ClassName       : Class
+    	DefinedName     : Define
+    	Enumerator      : Enumerator
+    	Function        : Function or method
+    	EnumerationName : Enumeration name
+    	Member          : Member (of structure or class)
+    	Structure       : Structure Name
+    	Type            : Typedef
+    	Union           : Union Name
+    	GlobalConstant  : Global Constant
+    	GlobalVariable  : Global Variable
+    	LocalVariable   : Local Variable
+
+    An example of how to highlight one of these would be to include the
+    following line in your colour scheme (see |:highlight|):
+>
+	hi Enumerator guifg="c000c0"
+<
+    You can, of course, also link the groups to another highlighting group
+    using something like:
+>
+        hi link Type Keyword
+<
+    However, this probably defies the point of having the tag highlighter in
+    the first place!
+
+2.4 Configuration                        *TagHighlight-config*              {{{2
+
+    There are a large number of configuration options that allow customisation
+    of the operation of the highlighter.  For simple use, none of these really
+    need to be set.  Options can be set globally, per project or per buffer;
+    see |TagHighlight-how-options| for more information.
+
+2.4.1 How to Set Options                 *TagHighlight-how-options*         {{{3
+
+    Options can be set globally, per project or per buffer.  Global options
+    are overridden by project options, which in turn are overridden by
+    buffer-specific options.
+
+	Global Options			 *g:TagHighlightSettings*
+
+	    Global options are set in a global |Dictionary|.  The variable
+	    name is |g:TagHighlightSettings|.  The keys in the dictionary are
+	    the option names and the values are the option values.  The safest
+	    way to set a value in this dictionary is to use something like
+	    this:
+>
+		if ! exists('g:TagHighlightSettings')
+		    let g:TagHighlightSettings = {}
+		endif
+		let g:TagHighlightSettings['Recurse'] = 1
+		let g:TagHighlightSettings['CtagsExecutable'] = 'etags.exe'
+<
+	    If you want to override any existing options (or you want to be
+	    lazy...) you can probably also do it this way:
+>
+		let g:TagHighlightSettings = {'Recurse': 1, 'CtagsExecutable': 'etags.exe'}
+<
+	Project Options                  *taghl_config.txt*
+
+	Buffer Options                   *b:TagHighlightSettings*
+	
+	    ...
+
+2.4.2 Option Summary                     *TagHighlight-option-list*         {{{3
+
+2.4.3 Option Details                     *TagHighlight-option-details*      {{{3
+
+2.5 Installation                         *TagHighlight-install*             {{{2
+
+==============================================================================
+3. TagHighlight Customisation            *TagHighlight-custom*              {{{1
+
+3.1 Adding More Languages                *TagHighlight-adding*              {{{2
+
+    1. Run ctags --list-languages and check that the required language is
+       present.
+
+    2. Create a new file in plugin/TagHighlight/data/languages/ with a .txt
+       extension (the file name can be anything you want).  Set the fileformat
+       to be 'unix' for consistency and don't expand tabs in case you need to
+       add any multi-line lists:
+>
+	    set ff=unix noet
+<
+    3. In that file, add the following fields in Key:Value format (one per
+       line):
+
+	    FriendlyName - Whatever you prefer to call the language
+
+	    CTagsName - Whatever ctags refers to the language as
+
+	    PythonExtensionMatcher - A python regular expression that matches
+				     the extensions of files that are written
+				     in this language.
+
+	    VimExtensionMatcher - The Vim regular expression version of
+				  PythonExtensionMatcher.
+
+	    Suffix - Whatever you would like the generated files to be named,
+		     e.g. for C code, the suffix is c and the generated files
+		     are by default called types_c.taghl
+
+    4. Optionally, add other fields as required:
+
+	    SkipList - Any specific ctags "kinds" (single characters referring
+		       to types of tags) that you want to omit from the types
+		       file.  For example, for C code, function prototypes are
+		       omitted (function definitions are included) by setting
+		       SkipList to p.  To include multiple items, separate
+		       each item with a comma.  To see a list of kinds for a
+		       language, use:
+>
+			    ctags --list-kinds
+<
+	    SpecialSyntaxHandlers - This is for unusual cases where particular
+				    syntax commands are required for a given
+				    language.  Add any functions you want to
+				    call here.  As an example, for Java code,
+				    all syntax items must be added to the
+				    javaTop cluster; this is done in a special
+				    syntax handler.  For most languages this
+				    is unnecessary.
+
+    5. Add a modeline for consistency:
+>
+	# vim: ff=unix:noet
+<
+    5. Test your new language!
+
+    6. Send me a copy for inclusion in the main distribution.
+
+3.1.1 Example                            *TagHighlight-add-example*         {{{3
+
+    It is worth looking at the existing language files for examples.  The C#
+    language file is called csharp.txt and looks like this:
+>
+	FriendlyName:c#
+	CTagsName:c#
+	PythonExtensionMatcher:cs
+	VimExtensionMatcher:cs
+	Suffix:cs
+	
+	# vim: ff=unix:noet
+<
+    The friendly name and CTagsName are both 'c#' (it is quite normal for
+    these to be the same).  Only one file extension is supported (cs), so the
+    extension matchers are trivial.  The selected suffix is cs (this is the
+    bit that goes in the filename).
+
+    It really is that easy!
+
+==============================================================================
+4. Troubleshooting                       *TagHighlight-troubleshooting*     {{{1
+
+==============================================================================
+5. Feature Wishlist                      *TagHighlight-wishlist*            {{{1
+
+    - Highlighting of local variables (could be useful for checking your
+      variable is defined in the correct function)?  Not currently possible as
+      "ctags --c-kinds=+l" doesn't provide the scope of the local variable, so
+      a lot of complicated parsing of the source would be required.
+    
+    - Option to update the types files whenever :make is run.
+    
+    - Option to update the types files whenever specific files are written
+      (would need to make :UpdateTypesFile! much faster for this to be
+      practical).
+    
+    - Make it work better with paths containing spaces.
+
+==============================================================================
+6. TagHighlight History                *TagHighlight-history*               {{{1
+
+rXXX : Xth XXX 2011        : Significant refactor of all the code.  Reworked
+			     the way options are set (can now be set globally,
+			     per buffer or in a project configuration file).
+			     All options now moved into dictionaries to
+			     minimise the number of variables created by the
+			     plugin.  Moved most of the functionality into
+			     autoload to simplify operation.  Added support
+			     for using the python interface (either 2.6+ or
+			     3.0+), or using a system python (either 2.6+ or
+			     3.0+) or using a compiled version on either
+			     Windows or Linux.  Improved library
+			     implementation to improve loading method and ease
+			     generation of standard libraries.  Added support
+			     for user libraries.  Improved language handlers
+			     (now configured from a single text file).
+			     Renamed project from ctags_highlighter to
+			     TagHighlight.  New revision numbering scheme.
+			     Changed default types file extension.  Allow
+			     complete customisation of location and name of
+			     types and tags files.  Allow specific keywords to
+			     be skipped when generating types files.  Added
+			     support for pre-read, post-read, pre-update and
+			     post-update hooks to allow further customisation.
+
+r461 : 6th May 2011        : Allow explicit setting of ctags executable
+                             name.  Added troubleshooting section to the
+                             manual.
+
+r458 : 7th March 2011      : Inclusion of vim keywords (display, contained
+                             etc) controlled by separate option.
+
+r456 : 6th March 2011      : Fixed accidental file-type change.
+
+r452 : 6th March 2011      : Better handling of unknown ctags tag kinds.
+
+r443 : 19th February 2011  : Allow customisation of the filenames used
+                             for tags and types files (thanks to Sung Pae).
+
+r442 : 16th February 2011  : Improved prioritisation of object-oriented
+                             language types (thanks to Aleksey Baibarin).
+
+r440 : 16th February 2011  : More explicit choice of C/C++ file extensions to
+			     avoid conflicts with C# (thanks to Aleksey
+			     Baibarin).
+
+r439 : 10th February 2011  : Kill any cscope connections prior to running 
+                             script in order to prevent cscope from locking
+                             the cscope.out file.
+
+r435 : 11th January 2011   : Changed default to not include syntax matches
+                             unless either g:TypesFileIncludeSynMatches or
+                             b:TypesFileIncludeSynMatches is set to 1 (this
+                             makes the highlighting much faster for large
+                             projects).
+
+r431 : 2nd December 2010   : Add support for local variables in non-C
+                             languages.
+
+r429 : 2nd December 2010   : Improvements to cope with spaces in paths.
+
+r425 : 16th November 2010  : Added support for Java and Android SDKs.
+
+r410 : 9th September 2010  : Improved option configuration implementation.
+
+r409 : 9th September 2010  : Allow cscope configuration options to be local
+                             rather than buffer specific.
+
+r398 : 29th March 2010     : Added support for python import in the listing.
+
+r396 : 29th March 2010     : Factored out old ctags_[a-z] types to improve
+                             language support.
+
+r394 : 26th March 2010     : Fix for python use.
+
+r391 : 2nd March 2010      : Fix for ctags names.
+
+r390 : 2nd March 2010      : Attempted improvements to code including support
+                             for C# (thanks to Aleksey Baibarin).
+
+r387 : 20th February 2010  : Fixed VIMFILESDIR typo.
+
+r384 : 19th February 2010  : Improvements to VIMFILESDIR identification.
+                             Re-architecture of type definitions to make
+                             them more sensitive to different ctags "kinds"
+                             for different languages.  Note that Enumerator
+                             has been renamed to EnumerationValue: the latest
+                             Bandit Colour Scheme supports this.
+
+r382 : 13th February 2010  : Fixed escaping of paths and operation of
+                             ReadTypes when not in an autocommand.
+
+r340 : 2nd November 2009   : Added missing winrestview().
+
+r330 : 16th September 2009 : Minor Documentation update.
+
+r329 : 16th September 2009 : Added revision output to mktypes.
+
+r328 : 16th September 2009 : Fix for bug with path finding on Windows where
+                             directories in the path end in a backslash.
+
+r326 : 15th September 2009 : Added revision number to debug output.
+
+r324 : 14th September 2009 : Fixed Linux bugs with new implementation.
+
+r321 : 14th September 2009 : Fixed bug with returning to the correct window
+			     after use, added debugging statements and moved
+			     executable search to a separate function.  Also
+			     added preliminary work towards more explicit
+			     type names.
+
+r309 : 17th August 2009    : Added documentation.
+
+r302 : 10th August 2009    : Added experimental PHP support.
+
+r301 : 7th August 2009     : Made GUI tags and types files optional and added
+			     shellescape to protect paths (thanks to Mikhail
+			     Stepura again). The gui_tags_and_types.vba file
+			     contains the tags and highlighting definitions
+			     for Qt, wxWidgets and wxPython (used to be
+			     included in the main distribution).
+
+r292 : 3rd August 2009     : Fixed bug with cscope option.
+
+r285 : 27th July 2009      : Added support for ctags being stored in a path
+			     with spaces and other odd characters (thanks to
+			     Mikhail Stepura).
+
+r261 : 23rd May 2009       : Changed some of the defaults to the python script
+			     (so fewer options need to be passed by
+			     UpdateTypesFile).  It should now be possible to
+			     generate the types file simply by running
+			     "mktypes.py" or "mktypes.py -r" in the project
+			     directory.  Of course, UpdateTypesFile works too.
+			     Added UpdateTypesFileOnly command for projects in
+			     which the tags file is updated externally (e.g.
+			     the Linux kernel source).  Removed regular
+			     expression matches by default: this is much
+			     quicker for large projects.
+
+r252 : 21st May 2009       : Added (optional) support for highlighting of
+			     local variables (not scope-specific: just
+			     recognises names).  Tidied up tag generation.
+
+r173 : 17th November 2008  : Added automatic reloading of types file whenever
+			     :UpdateTypesFile is run.  Also runs cscope (in
+			     the background) if cscope.files is present in the
+			     current working directory.
+
+r132 : 17th September 2008 : Updated to support limiting the languages checked
+			     for (intended to be used with the project plugin
+			     and it's in= option) in order to speed it up a
+			     bit. Also added project option for recursion (so
+			     you don't have to bother with the exclamation
+			     mark) and parsing of local enumerations.
+			     Finally, added sorting of tags file such that
+			     function implementations come before function
+			     declarations, regardless of the alphabetic order
+			     of the file names in which they are stored.
+			     Finally, added zipfile version in case of
+			     problems with vba.
+
+r129 : 9th September 2008  : Updated to only add to the various rainbow.vim
+			     related groups if b:hlrainbow is set.
+
+r126 : 5th September 2008  : This has now been updated to run considerably
+			     quicker (with only one pass by ctags and
+			     excluding directories named "docs" to avoid
+			     spending a long time searching through all the
+			     files that doxygen creates).  On the project I
+			     used to benchmark it, the running time reduced
+			     from about two minutes to about seven seconds!
+
+==============================================================================
+Modelines: {{{1
+ vim:tw=78:ts=8:ft=help:fdm=marker: