LanguageTool.txt

*LanguageTool.txt*  A grammar checker in Vim for English, French, German, etc.
*LanguageTool*

Author:      Dominique Pellé <dominique.pelle@gmail.com>
Last Change: 23 Jan 2021

For Vim version 7.0 and above

============================================================================

1.  Overview                                      |languagetool-overview|
2.  Screenshots & Demo                            |languagetool-screenshots|
3.  Download                                      |languagetool-download|
4.  Installation                                  |languagetool-installation|
5.  Configuration                                 |languagetool-configuration|
6.  Features                                      |languagetool-features|
7.  Bugs                                          |languagetool-bugs|
8.  License                                       |languagetool-license|

============================================================================

1. Overview                                           *languagetool-overview*

This plugin integrates LanguageTool into Vim. LanguageTool is an Open Source
style and grammar checker for English, French, German, etc. See
http://www.languagetool.org/languages/ for a complete list of supported
languages.

LanguageTool detects grammar mistakes that a spelling checker cannot detect
such as "it work" instead of "it works". Since version 1.8, LanguageTool
can also detect spelling mistakes using Hunspell dictionaries bundled with
LanguageTool for several languages or using morfologik for other languages.
Vim builtin spelling checker can also of course be used along with
LanguageTool. One advantage of the spelling checker of LanguageTool over
Vim spelling checker, is that it uses the native Hunspell dictionary directly,
so it works even with the latest Hunspell dictionaries containing features
not supported by Vim. For example, the latest French Hunspell dictionaries
from http://www.dicollecte.org are not supported by Vim but they work well
with LanguageTool. On the other hand, the Vim native spelling checker is
faster and better integrated with Vim.

See http://www.languagetool.org/ for more information about LanguageTool.

============================================================================

2. Screenshots                                     *languagetool-screenshots*

If you don't have time to read help files, these screenshots will give you
an idea of what the LanguageTool plugin does:

  http://dominique.pelle.free.fr/pic/LanguageToolVimPlugin_en.png
  http://dominique.pelle.free.fr/pic/LanguageToolVimPlugin_fr.png

============================================================================

3. Download                                           *languagetool-download*

LanguageTool can be downloaded from:

  http://www.languagetool.org/

============================================================================

4. Installation                                   *languagetool-installation*

4.1 Installing the plugin~

Preferably install the vim-LanguageTool plugin using a plugin
manager such as vim-plug or Vundle.

With vim-plug, you can install the plugin by adding this line to your
~/.vimrc file: >

  Plug 'dpelle/vim-LanguageTool'

Then run: >

  :PlugInstall

Alternatively, if you don't use a Vim plugin manager, copy the following
3 files from /~https://github.com/dpelle/vim-LanguageTool into: >

  ~/.vim/autoload/languagetool.vim
  ~/.vim/plugin/LanguageTool.vim
  ~/.vim/doc/LanguageTool.txt

Then index the documentation: >

  $ vim -c 'helptags ~/.vim/doc'

You have to enable plugins by adding these two lines in your |.vimrc| file: >

  :set nocompatible
  :filetype plugin on

4.2 Installing LanguageTool~

To use this plugin, you need to install the Java LanguageTool program.
Recent versions of LanguageTool require Java-8.

4.2.1 Download the stand-alone version of LanguageTool~

Download the latest stable stand-alone version of LanguageTool
(file LanguageTool-*.zip) from http://www.languagetool.org/download/ >

  $ wget https://languagetool.org/download/LanguageTool-5.2.zip
  $ unzip LanguageTool-5.2.zip

This should extract the file LanguageTool-5.2/languagetool-commandline.jar
among several other files.

A more recent version may be available by the time you read this.

Alternatively, you can choose to download the latest daily snapshot
(file LanguageTool-*-snapshot.zip). This is a more recent version of
LanguageTool than the stable version, but it is less tested: >

  $ wget https://languagetool.org/download/snapshots/LanguageTool-20210123-snapshot.zip
  $ unzip LanguageTool-20210123-snapshot.zip

4.2.2 Build LanguageTool from sources in git~

If you prefer to build LanguageTool yourself from sources, you first need
to install the prerequisite packages. On Ubuntu, you need to install the
following packages: >

  $ sudo apt-get install openjdk-8-jdk maven git

LanguageTool can then be downloaded and built with Maven as follows: >

  $ git clone /~https://github.com/languagetool-org/languagetool.git
  $ cd languagetool
  $ mvn clean package

After the build, the command line version of LanguageTool can be found in: >

  languaetool/languagetool-standalone/target/LanguageTool-5.3-SNAPSHOT/LanguageTool-5.3-SNAPSHOT/languagetool-commandline.jar

4.3 Configuring the location of the jar file~

After installing LanguageTool, you must specify the location of the file
languagetool-commandline.jar in your $HOME/.vimrc file. Example: >

  :let g:languagetool_jar='$HOME/languagetool/languagetool-standalone/target/LanguageTool-5.3-SNAPSHOT/LanguageTool-5.3-SNAPSHOT/languagetool-commandline.jar'

See section |languagetool-configuration| for more optional settings.

============================================================================

5. Configuration                                 *languagetool-configuration*

LanguageTool plugin uses character encoding from the 'fenc' option or from
the 'enc' option if 'fenc' is empty.

Several global variables can be set in your |vimrc| to configure the behavior
of the LanguageTool plugin.

g:languagetool_jar                                       *g:languagetool_jar*

  This variable specifies the location of the LanguageTool java grammar
  checker program. Default is empty.

  Example: >

  :let g:languagetool_jar='$HOME/languagetool/languagetool-standalone/target/LanguageTool-5.0-SNAPSHOT/LanguageTool-5.0-SNAPSHOT/languagetool-commandline.jar'

g:languagetool_cmd                                       *g:languagetool_cmd*

  Conversely, you could use this variable to specify by yourself the
  command call. This variable takes priority over g:languagetool_jar.
  This is useful for system package management installs like for
  archlinux.

  Example: >

  :let g:languagetool_cmd='/usr/bin/languagetool'
  :let g:languagetool_cmd='java -jar $HOME/languagetool/languagetool-standalone/target/LanguageTool-4.3-SNAPSHOT/LanguageTool-4.3-SNAPSHOT/languagetool-commandline.jar'

g:languagetool_lang                                      *g:languagetool_lang*

  The language code to use for the language tool checker. If undefined,
  plugin tries to guess the language of the Vim spelling checker
  'spelllang' or v:lang. If neither work, plugin defaults to
  English US (en-US). Starting with LanguageTool-1.8, regional variants
  of some languages can be specified. For languages with variants,
  it is necessary to specify the variant in order for LanguageTool
  to signal spelling errors. In other words, with  :set spelllang=en
  LanguageTool only signals grammar mistakes whereas with
  :set spelllang=en_us LanguageTool signals spelling mistakes and
  grammar mistakes. The valid language codes are: >

    ar     Arabic
    ast    Asturian
    be     Belarusian
    br     Breton
    ca     Catalan
    cs     Czech
    da     Danish
    de     German
    de-AT  German  (Austria)
    de-CH  German  (Switzerland)
    de-DE  German  (Germany)
    el     Greek
    en     English
    en-AU  English (Australia)
    en-CA  English (Canada)
    en-GB  English (Great Britain)
    en-NZ  English (New Zealand)
    en-US  English (US)
    en-ZA  English (South Africa)
    eo     Esperanto
    es     Spanish
    fa     Persian
    fr     French
    ga     Irish
    gl     Galician
    it     Italian
    ja     Japanese
    km     Khmer
    nl     Dutch
    pl     Polish
    pt     Portuguese
    pt-BR  Portuguese (Brazil)
    pt-MZ  Portuguese (Mozambique)
    pt-PT  Portuguese (Portugal)
    ro     Romanian
    ru     Russian
    sk     Slovak
    sl     Slovenian
    sr     Serbian
    sr-BA  Serbian (Bosnia and Herzegovina)
    sr-HR  Serbian (Croatia)
    sr-ME  Serbian (Montenegro)
    sr-RS  Serbian (Serbia)
    sv     Swedish
    ta     Tamil
    tl     Tagalog
    uk     Ukrainian
    zh     Chinese

g:languagetool_disable_rules                   *g:languagetool_disable_rules*

  This variable specifies checker rules to disable. The set of disabled rule
  must be comma separated.
  Default value set by plugin is: WHITESPACE_RULE,EN_QUOTES

  Example: >

  :let g:languagetool_disable_rules='ENGLISH_WORD_REPEAT_BEGINNING_RULE,WHITESPACE_RULE,EN_QUOTES,FRENCH_WHITESPACE,UPPERCASE_SENTENCE_START,APOS'

g:languagetool_enable_rules                     *g:languagetool_enable_rules*

  Some LanguageTool rules are disabled by default (rules that contain
  default="off" in grammar.xml) because they might be stylistic, nitpicky
  or give frequent positive.

  Those rules can be enabled by setting the g:languagetool_enable_rules
  variable. Example: >

  :let g:languagetool_enable_rules=PASSIVE_VOICE

g:languagetool_disable_categories         *g:languagetool_disable_categories*

  This variable specifies checker rule-categories which are disabled.

g:languagetool_enable_categories           *g:languagetool_enable_categories*

  This variable specifies checker rule-categories which are enabled.

g:languagetool_win_height                         *g:languagetool_win_height*

  This variable specifies the height of the scratch window which contains
  all grammatical mistakes with some explanations. You can use a negative
  value to disable opening the scratch window. You can also make it empty ''
  to let Vim pick a default size.
  Default is: 14

You can also customize the following syntax highlighting groups: >

  LanguageToolCmd
  LanguageToolErrorCount
  LanguageToolLabel
  LanguageToolUrl
  LanguageToolGrammarError
  LanguageToolSpellingError

For example, to highlight grammar errors in blue, and spelling errors in
red, with a curly underline in vim GUIs that support it, add this into your
colorscheme: >

  :hi LanguageToolGrammarError  guisp=blue gui=undercurl guifg=NONE guibg=NONE ctermfg=white ctermbg=blue term=underline cterm=none
  :hi LanguageToolSpellingError guisp=red  gui=undercurl guifg=NONE guibg=NONE ctermfg=white ctermbg=red  term=underline cterm=none

============================================================================

6. Features                                           *languagetool-features*

The LanguageTool plugin defines 2 commands |:LanguageToolCheck| and
|:LanguageToolClear|.

:LanguageToolCheck                                       *:LanguageToolCheck*

Use the |:LanguageToolCheck| command to check the grammar in the current
buffer. This will highlight errors in the buffer. It will also open a new
scratch window with the list of grammar mistakes with further explanations
for each error. It also populates the location-list for the window.

The |:LanguageToolCheck| command accepts a range. You can for example check
grammar between lines 100 and 200 in buffer with :100,200LanguageToolCheck,
check grammar in the visual selection with :<',>'LanguageToolCheck, etc.
The default range is 1,$ (whole buffer).

:LanguageToolClear                                       *:LanguageToolClear*

Use the |:LanguageToolClear| command to clear highlighting of grammar
mistakes, close the scratch window containing the list of errors, clear
and close the location-list.

The two commands are also available from the menu in gvim: >

  Plugin -> LanguageTool -> Check
                         -> Clear

Using the error scratch window~

Pressing <Enter> on an error in the error scratch buffer will jump to that
error.

Using the Location-list~

The |location-list| is populated when running |:LanguageToolCheck|. So you can
use location-list Vim commands such as |:lopen| to open the location-list
window, |:lne| to jump to the next error, etc.

The error scratch window may seem redundant with the location-list, but the
scratch window is more flexible to present errors in a nice way. If you do
not wish to popup the error scratch window, but use the location-list only,
you can disable it by setting |g:languagetool_win_height| to a negative value.

============================================================================

7. Bugs                                                   *languagetool-bugs*

Please report bugs or suggestions to <dominique.pelle@gmail.com>.
Alternatively, you can also discuss improvements to this plugin in Wiki
by clicking on the "Vim wiki" link at the top of the script page:

  http://www.vim.org/scripts/script.php?script_id=3223

============================================================================

8. Other plugin for grammar checking

Grammalecte is another grammar checker for French.  A plugin for Vim is
available at:

  /~https://github.com/dpelle/vim-Grammalecte

Checking text with Grammalecte or LanguageTool can find different errors,
Installing both plugins is thus recommended.

============================================================================

9. License                                             *languagetool-license*

The VIM LICENSE applies to the LanguageTool.vim plugin (see |copyright|
except use "LanguageTool.vim" instead of "Vim").

LanguageTool is freely available under LGPL.

============================================================================
vim:tw=78:fo=tcq2:isk=!-~,^*,^\|,^\":ts=8:ft=help:norl: