Commits

abudden committed b5e1959

Removed old documentation

Comments (0)

Files changed (1)

doc/ctags_highlighting.txt

-*ctags_highlighting.txt*       Tag Highlighting
-
-Author:	    A. S. Budden <abuddenNOSPAM@NOSPAMgmail.com>
-	    Remove NOSPAM.
-
-## RevTag:: r461                                                           ##
-
-Copyright:  (c) 2009-2011 by A. S. Budden       *ctags_highlighting-copyright*
-	    The VIM LICENCE applies to ctags_highlighting.vim, mktypes.py and
-	    ctags_highlighting.txt (see |copyright|) except use
-	    "ctags_highlighting" instead of "Vim".
-	    NO WARRANTY, EXPRESS OR IMPLIED. USE AT-YOUR-OWN-RISK.
-
-==============================================================================
-1. Contents	    *ctags_highlighting* *ctags_highlighting-contents*    {{{1
-
-    1.    Contents	                     |ctags_highlighting-contents|
-    
-    2.    CTAGS Highlighting Manual	     |ctags_highlighting-manual|
-    2.1   Introduction                       |ctags_highlighting-intro|
-    2.2   Commands                           |ctags_highlighting-commands|
-    2.3   Colouring                          |ctags_highlighting-colours|
-    2.4   Configuration                      |ctags_highlighting-config|
-    2.5   Installation                       |ctags_highlighting-install|
-    
-    3.    CTAGS Highlighting Customisation   |ctags_highlighting-custom|
-    3.1   Adding More Languages              |ctags_highlighting-adding|
-    3.1.1 Example                            |ctags_highlighting-add-example|
-
-    4.    Troubleshooting                    |ctags_highlighting-troubleshooting|
-    
-    5.    Feature Wishlist                   |ctags_highlighting-wishlist|
-    
-    6.    CTAGS Highlighting History         |ctags_highlighting-history|
-
-==============================================================================
-2. CTAGS Highlighting Manual		 *ctags_highlighting-manual*      {{{1
-
-2.1 Introduction                         *ctags_highlighting-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++
-        * 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
-    |ctags_highlighting-adding|.
-    
-                                         *ctags_highlighting-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                             *ctags_highlighting-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
-	    |b:TypesFileRecurse|.
-
-	: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.
-
-2.3 Colouring                            *ctags_highlighting-colours*     {{{2
-
-    The ctags 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 |ctags_highlighting-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 ctags highlighter in
-    the first place!
-
-2.4 Configuration                        *ctags_highlighting-config*      {{{2
-
-    There are a number of options that allow customisation of the operation of
-    the highlighter.  These can be specified as buffer-local variables (using
-    a b: prefix) or global variables (using a g: prefix).  This is largely due
-    to the fact that I use the project plugin (|project.txt|).  This includes
-    the ability to customise buffer settings automatically using the "in="
-    part of the project configuration (see |project-syntax| if you have the
-    plugin installed).    
-
-        b:TypesFileRecurse               *b:TypesFileRecurse*
-    	
-	    If this variable is set to 1, |UpdateTypesFile| recurses into
-	    subdirectories even if the ! is not appended.
->
-		let b:TypesFileRecurse = 1
-<
-        b:TypesFileDoNotGenerateTags     *b:TypesFileDoNotGenerateTags*
-    
-	   If this variable is set to 1, running |UpdateTypesFile| is
-	   equivalent to running |UpdateTypesFileOnly|.
->
-		let b:TypesFileDoNotGenerateTags = 1
-<
-        b:TypesFileIncludeLocals         *b:TypesFileIncludeLocals*
-    	
-	   If this variable is set to 1, local variables are included in the
-	   syntax highlighting.  Note however that no scope is applied to
-	   these variables, so they will be highlighted even if they are used
-	   in the wrong function.
->
-		let b:TypesFileIncludeLocals = 1
-<
-        b:TypesFileIncludeSynMatches     *b:TypesFileIncludeSynMatches*
-    	
-	   If this variable is set to 1, more obscure matches are included in
-	   the syntax highlighter.  The standard highlighter only highlights
-	   tags that are made up of keyword characters (see |'iskeyword'|).
-	   If this option is enabled, other tags are highlighted using
-	   |:syn-match|.  Note however that this can seriously slow your Vim
-	   down if there are a lot of matches (|:syn-match| is much slower
-	   than |:syn-keyword|).
->
-               let b:TypesFileIncludeSynMatches = 1
-<
-
-	b:TypesFileSkipVimKeywords       *b:TypesFileSkipVimKeywords*
-
-	   If this variable is set to 1, the regular expression matchers used
-	   to highlight any keywords that match the keywords used in Vim's
-	   syntax definition language are disabled and these keywords won't
-	   be highlighted.
->
-               let b:TypesFileSkipVimKeywords = 1
-<
-    
-        b:TypesFileLanguages             *b:TypesFileLanguages*
-    
-	   This variable can be used to limit the number of languages searched
-	   for by the generation script.  This can speed up tag generation
-	   somewhat.  For example, if you are working on C/C++ source code,
-	   use:
->
-		let b:TypesFileLanguages = ['c']
-<
-	   If you're working on Ruby and Python code, use:
->
-		let b:TypesFileLanguages = ['ruby', 'python']
-<
-	b:TypesCTagsFile                 *b:TypesCTagsFile*
-
-	   Change the name of the tags file from the default, "tags". Affects
-	   both file reading and creation.
-
-	b:TypesPrefix                    *b:TypesPrefix*
-
-	   Change the prefix for the vim types files from the default, "types".
-	   Affects both file reading and creation.
-
-	b:TypesFileCtagsExecutable       *b:TypesFileCtagsExecutable*
-	   
-	   Change the name of the ctags executable.  By default, the script
-	   searches for a file called ctags or ctags.exe (depending on
-	   platform) in the path or in the vimfiles directory (if on Windows).
-	   If this is set to the name of an executable (e.g. etags), it will
-	   search for this executable in the path or vimfiles.  If it is set
-	   to a full path to an executable, the specified executable will be
-	   used.
-
-2.5 Installation                         *ctags_highlighting-install*     {{{2
-
-    The highlighter is distributed as a |vimball|.  To install, open it in Vim
-    and run: >
-	    source %
-<
-    Additional components are available on the |ctags_highlighting-website|.
-    These include a Windows binary version of the python component and a set
-    of pregenerated types files for wxWidgets, wxPython, Java, Android and Qt
-    4.  The Windows binary should be unzipped into your |vimfiles| directory.
-    The pregenerated types files are distributed as another |vimball|.
-
-==============================================================================
-3. CTAGS Highlighting Customisation      *ctags_highlighting-custom*      {{{1
-
-3.1 Adding More Languages                *ctags_highlighting-adding*      {{{2
-
-    1. Run ctags --list-languages and check that the required language is
-       present
-       
-    2. Add an entry to GetLanguageParameters() with the following components:
-    
-	   - lang:       The "friendly" name used to refer to the language in
-	                 the list of languages
-    
-	   - suffix:     The distinguishing name for the output file name,
-	                 e.g.  "py" for "types_py.vim"
-    
-	   - extensions: A regular expression describing the extensions for
-	                 relevant files (e.g. "p[lm]" for *.pl and *.pm)
-    
-	   - iskeyword:  What Vim thinks is a keyword for this file type: open
-			 a source file and enter ":echo &iskeyword" (not
-			 required for most languages: there is a sensible
-			 default).  See |'iskeyword'| for more information.
-    
-    3. Add the lang entry to the list of languages at the bottom of mktypes.py
-
-    4. Recompile the py2exe executable (if required).
-
-    5. Add the new language autocmd to ctags_highlighting.vim (the argument to
-       ReadTypes is the suffix)
-    6. Add the extension to the lookup table in ReadTypesAutoDetect in
-       ctags_highlighting.vim
-
-3.1.1 Example                            *ctags_highlighting-add-example* {{{3
-
-    When PHP support was added to the highlighter, the following lines were
-    added:
-    
-    To mktypes.py, in the GetLanguageParameters function, the following lines
-    were added: >
-
-	elif lang == 'php':
-		params['suffix'] = 'php'
-		params['extensions'] = r'php'
-<
-
-    In the main() function, the full_language_list was changed from: >
-
-	full_language_list = ['c', 'java', 'perl', 'python', 'ruby', 'vhdl']
-<
-    To: >
-
-	full_language_list = ['c', 'java', 'perl', 'python', 'ruby', 'vhdl', 'php']
-<
-    The following line was added to ctags_highlighting.vim: >
-
-	autocmd BufRead,BufNewFile *.php    call ReadTypes('php')
-<
-    Finally, the ReadTypesAutoDetect function in ctags_highlighting.vim was
-    modified so that the extensionLookup dictionary included the following
-    entry:
->
-				\     'php'          : "php",
-<
-
-==============================================================================
-4. Feature Wishlist                      *ctags_highlighting-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).
-    
-    - Move most of the functionality into an autoload script.
-    
-    - Tidy up the types files for wxWidgets, Qt, JDK, Android and wxPython.
-    
-    - More control over location of tags and types file.
-
-    - Make it work better when Vim is installed in a path with spaces.
-
-==============================================================================
-5. CTAGS Highlighting History            *ctags_highlighting-history*     {{{1
-
-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: