Vim-Spell documentation

# VIM: let g:VS_language = 'american' 

*VS_help.txt*	For Vim version 5.7.+	Last change: 27th jan 2002

		VIM Spell Plugin MANUAL	by Luc Hermitte
			VIM-Spell version 0.2


------------------------------------------------------------------------------

								*Presentation*
Presentation: 

VIM-Spell is a spell checker plugin for VIM. Actually it wraps external tools
that use the |IA-spell| pipe protocol.

Contents 
|Features|	The features of the VIM-Spell Plugin.
|Install|	Installation notes.
|Options|	Options to customize it.
|Future|	Known problems & TODO list.
|References|	References to related programs and plugins.


------------------------------------------------------------------------------

								*Features*
Plugin features:

As its name suggests, the main feature of this plugin is to add spell-checking
functionalities to VIM. 

VIM-Spell defines two operating modes ; each one being associate to a buffer.
The first mode is associated to the buffer of the text spell-checked. The
second one is a view that suggests alternatives to a misspelling. See for
instance :
	http://hermitte.free.fr/vim/ressources/VS-capture.gif



  							*main-buffer-mode*
  Main-buffer Mode:
    From this mode we can :
      * |Parse| the buffer for misspellings,
      * |Highlight| the misspellings,
      * |Jump| from one misspelling to the next/previous,
      * |Exit|,
      * |Swap| the value of the current language,
      * Ask for |Alternatives|.


  							*corrector-mode*
  Corrector Mode: 
    In this mode, a set of alternatives are suggested to replace the word
    which is under the cursor in the parsed buffer. From this list, we can : 
      * |Choose| an alternative,
      * |Correct| the misspelled word and replace it by the chosen alternative,
      * |Replace-all| Replace every occurrence of the misspelled word by the
	chosen alternative,
      * |Replace-buf| Replace every occurrence of the misspelled word in every
	opened buffer by the chosen alternative,
      * |Ignore| the fact that the word is misspelled,
      * |Add| the word to the personal dictionary,
      * |Undo/redo| the last action,
      * |Jump| from one misspellings to the next/previous.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 
Details about the features:
  

*Parse*		Parse the buffer for misspellings -- key binding (KB) : <M-s>r
  Main mode.

  This action issues two calls to |IA-spell|. It first updates the list of
  misspelled words within the edited document, and then |cache| their
  possible alternatives. It also |Highlight|s the misspellings.
  Note: The current buffer must have been saved before calling |IA-spell|.
  This must be done at least once before using the other features of this
  plugin. 



*Highlight*	Highlight the misspellings -- <M-s>s ; not yet automatic
  Main mode.

  Switches in the Error-Syntax style all the misspelled words.



*Jump*		Jump from one misspelling to the next/previous -- <M-n>, <M-p>
  Both modes.

  Puts the cursor under the the next/previous misspelling.
  In corrector-mode, it also actuates the alternatives proposed to match the
  new current misspelling.



*Exit*		Exit -- <M-s>E
  Both modes.

  Closes the corrector window (if opened) and un-highlight the misspellings.



*Swap*		Swap the value of the current language -- <M-s>L
  Main mode.

  Changes the value of the option |g:VS_language| in order to be turn after
  turn : "American" or "French". You will certainly want to change this, do it
  within VS_map.vim. BTW, this mapping requires you have installed my
  |triggering| plugin.


*Alternatives*  Ask for alternatives -- <M-s>a
  Main mode.

  Opens (if not) the corrector window and suggests alternatives to the current
  word (i.e. under the cursor) if misspelled.
  This switches to the corrector mode.


   - - - - - - - - - -

*Choose*      Choose an alternative -- cursors, <tab>, <s-tab>
  Corrector mode

  An alternative is considered chosen if the cursor (in the corrector window)
  is on the line of the alternative.
  <tab> and <s-tab> have also been mapped to jump from one alternative to the
  next/previous.



*Correct*	Correct the misspelled word -- <cr>, <2-click>, number
  Corrector mode :: correction

  The current misspelled word is replaced by the chosen alternative.

  The alternative can also be chosen by directly typing its number.

  If the current word within the main buffer differs from the misspelling
  considered within the corrector-buffer, nothing is done.

      

*Replace-all*	Replace every occurrence of the misspelled word -- A
  Corrector mode :: correction

  Every occurrence, in the main buffer, of the misspelling is replaced by the
  chosen alternative.



*Replace-buf*	Replace every occurrence of the misspelling in every buffer -- B
  Corrector mode :: correction

  Every occurrence, in every opened buffer, of the misspelling is replaced by
  the chosen alternative.



*Ignore*	Ignore the fact that the word is misspelled -- i
  Corrector mode :: dictionary management

  This is a temporary measure. The word is once again highlighted when
  |Highlight| is required.



*Add*		Add the word to the personal dictionary -- * or & 
  Corrector mode :: dictionary management

  The word is added to the personal dictionary dependent of the current
  language. Typing '&' adds the word in lower case.

  This issues a call to |IA-spell|.

  When using |Aspell|, if the word to add is accentuated (or contains non
  alphanumeric characters), this function will propose to directly insert the
  word into the dictionary as if |g:VS_aspell_add_directly_to_dict| was set to
  true. Hence, all the corresponding warnings apply.
  This way of proceding comes from the fact I wasn't able to add accentuated
  words to the personal dictionary through the pipe protocol with Aspell .33.5
  alpha compiled with MinGW and used under Windows NT. Any hint/comment on
  this point is welcome.

  Deleting a word from the dictionary is out of topic here but quite easy
  indeed with Aspell. I have identified for instance with the version .33.5
  alpha the files fr.pws (for French) and english.pws. Deleting the line of
  the word no longer desired and reducing the last number on the first line
  should do the trick.
  


*Undo/redo*	Undo/redo the last action -- u / <C-R>
  Corrector mode :: dictionary management

  Undo/redo the last action that has occurred in the main buffer. This is
  helpful to undo a change without (because we haven't click on the right line
  for instance) leaving the corrector window.


- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 
  Internal considerations

							*cache*
As the calls to Aspell are quite slow -- due to the need to load the
dictionary each time it is run --, I decided to cache all the calls to Aspell.

Though, a file named ./.spell/errors-list is maintained for every folder
containing files checked with this plugin. Every time a file is parsed, all
the new misspellings detected are added (at the end of the file) with the list
of their suggested alternatives.

Hence, all in all |IA-spell| is called only twice : a first time to detect new
misspellings, and a second one to retrieve the suggested alternatives of all
the new misspellings. Once the file is parsed, the improvement is noticeable :
looking for the alternatives of a misspelling is an instantaneous operation.

All the current misspellings are remembered. It may not be useful in the long
run except for recurrent misspellings. But, the replacing feature will make
this behavior useless and hence we will be able to delete the cache-file
between two sessions.  cf. |todo-replace|

Regarding the highlighting policy, every word is considered OK except those
detected misspelled by the |IA-spell| tool. This is the opposite approach of
the one taken in |engspchk|. If the cached file is localized (to folder) and
often erased, this will enable to manage smaller lists of words.


------------------------------------------------------------------------------

								*Install*
Installation notes: 

  Files of the plugin: 
    The plugin is composed of 6 files plus this file and its HTML version :
      - VS-all.vim	: the file to be sourced, it sources the others ;
      - VS_fm-fun.vim	: file management functions ;
      - VS_gui.vim	: functions relatives to the corrector GUI ;
      - VS_int-fun.vim	: internal function wrapping the calls to |IA-spell| ;
      - VS_map.vim	: mappings defined in the main buffer ;
      - VS_gui-map.vim	: mappings defined in the corrector buffer. 

    They could be downloaded as a tarball archive at :
	http://hermitte.free.fr/vim/ressources/vim-spell.tar.gz

    I think that the best thing to do is to extract them in a dedicated folder
    with for instance : gzip -cd VS.tar.gz | tar xf -
    Personnaly, I extract it within $VIM/macros/ which creates a new folder.
    I choose not to put it in my plugins folder, and source VS-all.vim only
    with specific filetypes (like tex and html,php,...) thanks to their
    respective ftplugins.

    Note by the way that you will also require the |alternate| plugin and my
    |help| plugin in order to use VIM-Spell. They are in $VIM/plugin/ on my
    systems.

  VIM 5.xx
    The VIM version I use is the 5.7. Hence all the features from this plugin
    do work fine under these old releases.
    But. There is a 'but'. The mappings for the corrector-buffer imply they
    are unloaded out of the buffer. Indeed, I remap things like <cr>, a, i,
    <tab>, 0, 1, ..., 9, and so on. I wouldn't have done so if there didn't
    exist a way to implement buffer-relative mappings with these old versions
    of VIM. So, to make it straight, download |buffoption| and copy it
    into your $VIMRUNTIME/macros folder. I also suggest you take a look on a
    my page about "File-type plugin emulation on VIM 5.xx" for more
    explanations.
	http://hermitte.free.fr/vim-beta/ftplugin.php3 : still, but will move to
	http://hermitte.free.fr/vim/ftplugin.php3

  VIM 6.0
    As I have just said, the "maps local to a buffer" mechanism is required by
    VIM-Spell to work correctly. It is directly supported under VIM 6.0,
    without any other plugin required. Hence, as |buffoption| is not used,
    menus are no longer local to buffers.


  Customizing the mappings:
    I decided to bind all the features to sequences beginning by <M-s> because:
      - 's' is like spell ;
      - <C-S> is already mapped (in my configuration) to :w<cr> for when I
	come back from Ms-Windows products that I used over a long period ;
      - 'ó' is not a letter I use in French, Ms-Windows Spanish users may
	want to change it ; note: you will (quite) never see my mappings
	starting with <M-i> : 'é' probably the accentuated letter the most
	used in French.
    BTW, notice that <M-s> and <M-S> are two different key strokes.

    So, if you want to change the default mappings, just edit the files with
    "map" within -- e.g. gvim VS_*map.vim -- and make your customizations.

  Last thing:
    I'm aware that this plugin is quite complex. It is the price for all its
    features. It depends on external plugins and even external (but common for
    VIM users I guess) tools. For maintenance aspects, it is composed on
    several inter-dependant files. And for compatibility reasons, I've chosen
    to use as few new VIM 6.0 features as possible.

    Regarding my choices of folders between $VIM and $VIMRUNTIME, they are
    guided from the fact I've installed VIM 5.7 and VIM 6.0 on my Windows NT
    system.  All the common and compatible (ft)plugins are in $VIM/(ft)plugin
    while specific stuff is in the respective $VIMRUNTIME folders. If your
    installation is simple, I suggest you use $VIMRUNTIME everywhere.
    Sometimes, I will write a note about this cohabitation topic.


------------------------------------------------------------------------------

								*Options*
Options: 

The options are global. Making them buffer relative caused me a lot of
troubles when I wanted to |Parse| several buffers.


*g:VS_language*	string (...)
  This option defines the language/dictionary used. cf. the --master option of
  |IA-spell|.

  BTW, you may want to customize the |Swap| languages.


*g:VS_spell_prog* string ('ispell'/'aspell')
  This option must be used to set which |IA-spell| tool is used : Ispell or
  Aspell -- or any upcoming clone.


*g:VS_strip_accents* boolean (0/1)
  Directly passed to |IA-spell| if defined.


*g:VS_aspell_add_directly_to_dict* boolean (0/1)
  This trick enable to quicken the insertion of words into the personal
  dictionary. I guess it will only work with |Aspell|. I've tested this
  approach with Aspell .33.5 alpha ; I can't guarantee that it always work
  with future versions of Aspell. By default, this option is set to false (ie.
  0).
  If you want to use it, please check :
  - You are using Aspell or at least the format of your personal dictionary
    looks like : "xxxx <number_of_entries>" on the first line, while the
    following lines are made of «personal» words.
  - The personal dictionary names are correctly set within VS_personal_dict()
    regarding your |g:VS_language|.
  - $ASPELL points to the folder where your personal dictionaries are stored.
    I think that the name of this env. variable is very badly chosen.
  Any feedback is welcome regarding this option (and the rest as well) :
  format of personal dictionaries and its everlastingness, their names
  regarding the language used, etc.


------------------------------------------------------------------------------

								*Future*
Known problems & TODO List: 


							*Known* *problems*
  Known problems:
    Setting the file-type will cancel the highlighting of misspellings ; So,
    try to avoid to reset it every time the buffer is reloaded -- this could
    be observed with the affectation of &filetype within modelines like with
    this file.  

    The current |Ignore| feature lasts until the next call to VS_show_errors()
    hence until a |Highlight| of misspellings, a |Parse|, etc.

    When we hit '*' in the Corrector mode, a space must be hit in order to
    activate the associated mapping.

  

							*TODO*
  TODO list:

    * Manage replacement list ;				*todo-replace*
      i.e. list of words to be systematically replaced by a predefined word.
      Aspell seems to use *.prepl files for this purpose. But how to manage
      them through pipes (-a option) ?
      Two possible ways (option ?) to execute the replacements:
      - can be executed on user's request
      - can be executed automatically => map every characters -- possibility
	to study ; cf. Word_in_ment() in fr-abbrs.vim
    * Ignore some contextual word like "\oe uvre" -- with TeX
      and other expressions like for instance the labels of figure the
      parameters to \rnode{}{}{}, and so on.
    * Locally and permanently Ignore words ; e.g. Luc & Hermitte can be
      ignored safely in a document, but are not wanted in the dictionary.
    * Cache the dictionary management requests ; delay and merge the calls to
      |IA-spell| that add words to the dictionary as long as possible.
    * Secondary dictionary.
    * Delete words from the dictionary ; Aspell does not seem to permit it
      through a piped call, while it is quite easy to perform. But is it safe
      in regard of its future versions ? Will be supported if the option
      |g:VS_aspell_add_directly_to_dict| is set to true.
    * Add the possibility to retract/expand the help for the Corrector-Mode.
    * Dedicate a sub-menu for the different options.

    * Extension to other file types : extend the file-type2mode recognition
      function ; only TeX, ML-like and None/url are recognized for now.
      Actually, I do support only the formats supported by Aspell.
    * Wrap other functions exclusives to Aspell (e.g. sounds-like words and
      lists of words, phonemes, score between words)
    * Add g:VS_language to the names of cached files.
    * Being able to ask for alternatives on the fly ; i.e. not only for
      cached misspellings.

    * Better handling of the splitted window for a more ergonomic plugin.
    * Option for vertical splitting of window with vim6 ; could be nicest.
    * Option for displaying suggested alternatives in a popup-menu ; why not.
    * Delete unneeded code
    * Silent execution under VIM 6 to be improved
    * VIM 6 local menus ; works fine with VIM 5.7 + buffoption.vim


------------------------------------------------------------------------------

								*References*
References:

  Links to external programs 


    The VIM editor					*VIM*
     Do I really need to present you this wonderful text editor ?
     Just in case, the plugin presented here has been written for VIM --
	http://vim.sourceforge.net/
    

    [IA]spell						*IA-spell*
     I use [IA]spell to refer to either |Ispell| or |Aspell|. Indeed, these
     tools accept a same and important set of parameters. Therefore, this
     plugin rely on this common set and can be used with either spell-checker
     ; see |g:VS_spell_prog|. Of course one or the other is needed by the
     plugin.
    

    Ispell						*Ispell*
     Ispell is the widely distributed spell-checker I use as reference for
     this plugin. 
     Ispell hasn't been tested but should be OK with this plugin.
	http://fmg-www.cs.ucla.edu/geoff/ispell.html
    

    Aspell						*Aspell*
     "Aspell is an Open Source spell checker designed to eventually replace
     Ispell.  Its main feature is that it does a much better job of coming up
     with possible suggestions than Ispell does. In fact recent tests shows
     that it even does better than Microsoft Word 97's spell checker in some
     cases."
    				 © Kevin Atkinson, from Aspell's introduction.
     It takes into account the sonority of words.
	http://aspell.sourceforge.net/
    

    Text tools						*cat* *echo*
     The text tools and more precisely cat is required on your system. Make
     sure it is accessible from your ${PATH}.
     Rem.: I use |cat| instead of |echo| because |echo| looses accents and
     cuts word when they occur on my Windows NT system.
    
  Dependencies 
    This plugin rely on some other plugins like :
    

    a.vim						*alternate*
     Defines some functions to go to specific windows/buffers.
     Critical.
	http://vim.sf.net/scripts/script.php?script_id=31
    

    help.vim						*help*
     Very little plugin of my own that I use to define help strings.
     Not rely critical.
	http://hermitte.free.fr/vim/ressources/help.vim


    Triggers.vim					*triggering*
     Big piece of script. It permits to execute one action or an other on a
     trigger. 
     Used to swap languages.
	http://hermitte.free.fr/vim-beta/general.php3#Triggers_vim
    

    buffoption.vim					*buffoption*
     This file is used to define buffer relative mappings with versions of VIM
     prior to the 6 series -- critical in that case. As, I write my mappings
     as "noremap"s, you should retrieve my patch from
	http://hermitte.free.fr/vim-beta/ftplugin.php3#buffoptions2_vim you
     will also need : buffoptions_map2.vim and fileuptodate.vim. 
     With the VIM 6 series, this file is no more required.
    
  
  Other related VIM's plugins 
   

    Claudio Fleiner's vimspell.vim. 			*vimspell*
     This plugins is the one that inspired me at first.  It generates the list
     of misspelled words through a call to |IA-spell|, then highlights them in
     the Error syntax style. It permits to : - jump from a misspelled word to
     the next one, - add them to the |IA-spell|'s dictionary, - ignore them, 
     - and see a list of alternative words.
	http://www.fleiner.com/vim/spell.html
    

    Dr. Charles E. Campbell, Jr.'s engspchk.vim.	*engspchk*
     A really big piece of plugin! It needs no external tool. The dictionary
     is part of the plugin ; hence, it has to be extended and ported to other
     languages. It highlights misspelled words, enables to jump from one to
     another, and manages the dictionary. With VIM v6.0+, it can compute
     alternative words.
     I've stolen my jumping functions, and TeX highlighting rules from this
     plugin.  
	http://www.erols.com/astronaut/vim/index.html#Spelling


    Matthias Veit's spellcheck.vim for VIM 6 (only ?)	*spellcheck*
     Late addition to sourceforge. Require Aspell and ruby => I haven't tested
     it.  It seems that I permit much more things.
	http://vim.sf.net/scripts/script.php?script_id=131


    Johannes Zellner's Aspell.vim for VIM 6.0		*JZ*
     Another spellchecking plugin wrapping Aspell.
     <htpp://www.zellner.org/vim/autoload/Aspell.vim>


------------------------------------------------------------------------------
 © Luc Hermitte, 2001-2002	http://hermitte.free.fr/vim
top