Skip to content

Commit

Permalink
Document BufWritePost example, improve documentation structure (issue #…
Browse files Browse the repository at this point in the history 
…46)

Issue #46 on GitHub:
  #46
  • Loading branch information
@xolox
xolox committed May 19, 2013
1 parent 384ebf4 commit cad39a9
Show file tree
Hide file tree
Showing 2 changed files with 71 additions and 36 deletions.
30 changes: 21 additions & 9 deletions README.md
View file
Expand Up @@ -193,19 +193,23 @@ If this is set and not false, it will suppress the warning on startup if ctags i

This variable is a string of comma separated names of syntax groups in which dynamic highlighting is not applied. It defaults to `.*String.*,.*Comment.*,cIncluded`.

## Faster syntax highlighting using Python
## Customizing the easytags plug-in

The Vim script implementation of dynamic syntax highlighting is quite slow on large tags files. When the Python Interface to Vim is enabled the easytags plug-in will therefor automatically use a Python script that performs dynamic syntax highlighting about twice as fast as the Vim script implementation. The following options are available to change the default configuration.
Advanced users may wish to customize how the easytags plug-in works beyond the point of changing configuration defaults. This section contains some hints about this. If you have suggestions, please feel free to submit them.

### The `g:easytags_python_enabled` option
### Passing custom command line arguments to Exuberant Ctags

To disable the Python implementation of dynamic syntax highlighting you can set this option to false (0).
You may want to run Exuberant Ctags with specific command line options, for example the [code_complete] [code_complete] plug-in requires the signature field to be present. To do this you can create a configuration file for Exuberant Ctags, e.g. `~/.ctags` on UNIX or `%USERPROFILE%\ctags.cnf` on Windows. The file should contain one command line option per line. See the [Exuberant Ctags manual] [ctags_cfg] for details.

### The `g:easytags_python_script` option
### Update & highlight tags immediately after save

This option defines the pathname of the script that contains the Python implementation of dynamic syntax highlighting.
By default the easytags plug-in automatically updates & highlights tags for the current file after several seconds of inactivity. This is done to prevent the easytags plug-in from interrupting your workflow.

If you want the easytags plug-in to automatically update & highlight tags for the current file right after you save the file, you can add the following line to your [vimrc script] [vimrc]:

## How to customize the highlighting colors?
:autocmd BufWritePost * call xolox#easytags#autoload('BufWritePost')

### How to customize the highlighting colors?

The easytags plug-in defines new highlighting groups for dynamically highlighted tags. These groups are linked to Vim's default groups so that they're colored out of the box, but if you want you can change the styles. To do so use a `highlight` command such as the ones given a few paragraphs back. Of course you'll need to change the group name. Here are the group names used by the easytags plug-in:

Expand All @@ -223,9 +227,17 @@ The easytags plug-in defines new highlighting groups for dynamically highlighted

As you can see each of these names ends in `Tag` to avoid conflicts with the syntax modes shipped with Vim. And about the singular/plural confusion: I've tried to match the existing highlighting groups defined by popular syntax modes (except of course for the `Tag` suffix).

## Passing custom command line arguments to Exuberant Ctags
## Faster syntax highlighting using Python

The Vim script implementation of dynamic syntax highlighting is quite slow on large tags files. When the Python Interface to Vim is enabled the easytags plug-in will therefor automatically use a Python script that performs dynamic syntax highlighting about twice as fast as the Vim script implementation. The following options are available to change the default configuration.

You may want to run Exuberant Ctags with specific command line options, for example the [code_complete] [code_complete] plug-in requires the signature field to be present. To do this you can create a configuration file for Exuberant Ctags, e.g. `~/.ctags` on UNIX or `%USERPROFILE%\ctags.cnf` on Windows. The file should contain one command line option per line. See the [Exuberant Ctags manual] [ctags_cfg] for details.
### The `g:easytags_python_enabled` option

To disable the Python implementation of dynamic syntax highlighting you can set this option to false (0).

### The `g:easytags_python_script` option

This option defines the pathname of the script that contains the Python implementation of dynamic syntax highlighting.

## Troubleshooting

Expand Down
77 changes: 50 additions & 27 deletions doc/easytags.txt
View file
Expand Up @@ -27,19 +27,21 @@ Contents ~
14. The |g:easytags_resolve_links| option
15. The |g:easytags_suppress_ctags_warning| option
16. The |g:easytags_ignored_syntax_groups| option
5. Faster syntax highlighting using Python |easytags-faster-syntax-highlighting-using-python|
5. Customizing the easytags plug-in |customizing-easytags-plug-in|
1. Passing custom command line arguments to Exuberant Ctags
2. Update & highlight tags immediately after save
3. How to customize the highlighting colors?
6. Faster syntax highlighting using Python |easytags-faster-syntax-highlighting-using-python|
1. The |g:easytags_python_enabled| option
2. The |g:easytags_python_script| option
6. How to customize the highlighting colors?
7. Passing custom command line arguments to Exuberant Ctags
8. Troubleshooting |easytags-troubleshooting|
7. Troubleshooting |easytags-troubleshooting|
1. |:HighlightTags| only works for the tags file created by |:UpdateTags|
2. The plug-in complains that Exuberant Ctags isn't installed
3. Vim locks up while the plug-in is running
4. Failed to highlight tags because pattern is too big!
5. The plug-in doesn't seem to work in Cygwin
9. Contact |easytags-contact|
10. License |easytags-license|
8. Contact |easytags-contact|
9. License |easytags-license|

===============================================================================
*easytags-introduction*
Expand Down Expand Up @@ -423,28 +425,37 @@ This variable is a string of comma separated names of syntax groups in which
dynamic highlighting is not applied. It defaults to '.*String.*,.*Comment.*,cIncluded'.

===============================================================================
*easytags-faster-syntax-highlighting-using-python*
Faster syntax highlighting using Python ~
*customizing-easytags-plug-in*
Customizing the easytags plug-in ~

The Vim script implementation of dynamic syntax highlighting is quite slow on
large tags files. When the Python Interface to Vim is enabled the easytags
plug-in will therefor automatically use a Python script that performs dynamic
syntax highlighting about twice as fast as the Vim script implementation. The
following options are available to change the default configuration.
Advanced users may wish to customize how the easytags plug-in works beyond the
point of changing configuration defaults. This section contains some hints
about this. If you have suggestions, please feel free to submit them.

-------------------------------------------------------------------------------
The *g:easytags_python_enabled* option
Passing custom command line arguments to Exuberant Ctags ~

To disable the Python implementation of dynamic syntax highlighting you can
set this option to false (0).
You may want to run Exuberant Ctags with specific command line options, for
example the code_complete [13] plug-in requires the signature field to be
present. To do this you can create a configuration file for Exuberant Ctags,
e.g. '~/.ctags' on UNIX or '%USERPROFILE%\ctags.cnf' on Windows. The file
should contain one command line option per line. See the Exuberant Ctags
manual [14] for details.

-------------------------------------------------------------------------------
The *g:easytags_python_script* option
Update & highlight tags immediately after save ~

This option defines the pathname of the script that contains the Python
implementation of dynamic syntax highlighting.
By default the easytags plug-in automatically updates & highlights tags for
the current file after several seconds of inactivity. This is done to prevent
the easytags plug-in from interrupting your workflow.

===============================================================================
If you want the easytags plug-in to automatically update & highlight tags for
the current file right after you save the file, you can add the following line
to your |vimrc| script:
>
:autocmd BufWritePost * call xolox#easytags#autoload('BufWritePost')
-------------------------------------------------------------------------------
How to customize the highlighting colors? ~

The easytags plug-in defines new highlighting groups for dynamically
Expand Down Expand Up @@ -484,14 +495,26 @@ tried to match the existing highlighting groups defined by popular syntax
modes (except of course for the 'Tag' suffix).

===============================================================================
Passing custom command line arguments to Exuberant Ctags ~
*easytags-faster-syntax-highlighting-using-python*
Faster syntax highlighting using Python ~

You may want to run Exuberant Ctags with specific command line options, for
example the code_complete [13] plug-in requires the signature field to be
present. To do this you can create a configuration file for Exuberant Ctags,
e.g. '~/.ctags' on UNIX or '%USERPROFILE%\ctags.cnf' on Windows. The file
should contain one command line option per line. See the Exuberant Ctags
manual [14] for details.
The Vim script implementation of dynamic syntax highlighting is quite slow on
large tags files. When the Python Interface to Vim is enabled the easytags
plug-in will therefor automatically use a Python script that performs dynamic
syntax highlighting about twice as fast as the Vim script implementation. The
following options are available to change the default configuration.

-------------------------------------------------------------------------------
The *g:easytags_python_enabled* option

To disable the Python implementation of dynamic syntax highlighting you can
set this option to false (0).

-------------------------------------------------------------------------------
The *g:easytags_python_script* option

This option defines the pathname of the script that contains the Python
implementation of dynamic syntax highlighting.

===============================================================================
*easytags-troubleshooting*
Expand Down

0 comments on commit cad39a9

Please sign in to comment.