LanguageTool is a free and open-source multilingual grammar, style, and spell checker with support for more than 30 languages. So, why not use it as your Emacs grammar and spell check tool. That is what this package is for.
languagetool.el is a tool written for Emacs keeping in mind integrity and display. In a way that you can see all the issues which LanguageTool generates for your text and which kind of issue is, by following a colour key.
LanguageTool standalone version comes with tree different executables written in Java:
- The first is the GUI, to use LanguageTool directly.
- The other is the Command Line Interface, to check text in this way.
- And the final one is the Server, to create an HTTP server to check text via requests.
languagetool.el creates a wrapper for two of these three tools, the CLI
(console module) and the Server (server module).
As LanguageTool is code in Java, you need to install that on your system. LanguageTool requires Java 8 or later to work.
You’ll need (obviously) LanguageTool itself, you can download it in this link or, if available, with your package manager.
If you download LanguageTool Zip file, extract the contents in a folder you
want; for example /home/pillfall/.languagetool/, if you use LanguageTool with
other tools could be a great option.
In case you use your package manager, find out if it download the class files or
the standalone executable and where it put them, this is useful for later
configuration. For example ArchLinux download the class files and puts them in
the /usr/share/languagetool and /usr/share/java/languagetool directories.
You can install the package using the MELPA repository or via use-package.
In case you use the latter and get the LanguageTool Zip, one default configuration, enabling all current features, would be:
(use-package languagetool
:ensure t
:defer t
:commands (languagetool-check
languagetool-clear-suggestions
languagetool-correct-at-point
languagetool-correct-buffer
languagetool-set-language
languagetool-server-mode
languagetool-server-start
languagetool-server-stop)
:config
(setq languagetool-java-arguments '("-Dfile.encoding=UTF-8")
languagetool-console-command "~/.languagetool/languagetool-commandline.jar"
languagetool-server-command "~/.languagetool/languagetool-server.jar"))If you want to install it from source, you can clone this repository and do all
the configuration manually (create a package.el, generate autoloads.el,
etc.). Right now, there are no installation steps following this approach, so
you’ll need to know what you are doing, but there is a handy makefile which byte
compiles all the elisp files.
To get this package to work, you’ll need to configure some variables.
First you must configure Java to accept files in UTF-8, for that purpose, set
languagetool-java-arguments using customize interface or with elisp like
follows:
(setq languagetool-java-arguments '("-Dfile.encoding=UTF-8"))Then you need to tell the package how do you plan to call LanguageTool.
If you download, extracted and plan to use the LanguageTool Zip, set
languagetool-console-command and languagetool-server-command using
customize interface or with elisp like follows:
(setq languagetool-console-command "~/.languagetool/languagetool-commandline.jar"
languagetool-server-command "~/.languagetool/languagetool-server.jar")If you are going to use a package manager, and it download the class files, you
will call LanguageTool from its class, so set languagetool-java-arguments,
languagetool-console-command and languagetool-server-command using
customize interface or with elisp like follows:
(setq languagetool-java-arguments '("-Dfile.encoding=UTF-8"
"-cp" "/usr/share/languagetool:/usr/share/java/languagetool/*")
languagetool-console-command "org.languagetool.commandline.Main"
languagetool-server-command "org.languagetool.server.HTTPServer")If you pay for LanguageTool Proofreading API features, you can add the keys for the LanguageTool API as follows:
(setq languagetool-api-key "xxxxxxxxxxxx"
languagetool-username "johndoe@example.com")By default, the correction language is auto and it is buffer local, meaning
that you could check in different languages different files, if you want to
change the language, you could use local file variables to define the language
to use in that buffer, setting the variable languagetool-correction-language,
or call languagetool-set-language.
If you want to know more customization options you can find those at the customize interface.
When you decide to ignore a word, this package will add a comment like
following ispell conventions. So, after the ignore you’ll get a comment like
this at the end of your file.
# LocalWords: seplling
You can select between the default or the “picky” level when checking the
buffer. When using the “picky” level, additional rules will activate, i.e. rules
that you might only find useful when checking formal text. To change the level
you can set your local file variable languagetool-suggestion-level to the
value desired, in lowercase.
When you end customizing the packages (faces, languages, etc.). You can now
start checking your text. So, you can use either console mode or server
mode.
In this mode, when you start checking, the first thing you need to do is call
languagetool-check. This will invoke LanguageTool in the current region, if
any, and then highlight all the suggestions made by the tool. If there is no
region, the whole available portion of the buffer will check.
This function is synchronous. Therefore, it blocks Emacs until LanguageTool done with your text. This is the right behaviour, as LanguageTool is a bit slow checking text in this mode, so it prevents you from changing the text while checking.
After LanguageTool highlights all its suggestions, now you can correct your
text, then put your cursor on the underlined word and call
languagetool-correct-at-point, this will pop up
a transient minibuffer with all the suggestions, choose the one fits your needs,
and you are ready to go. There is also a buffer wide correction function, called
languagetool-correct-buffer, you can call it if you want to check all the
buffer, suggestion by suggestion.
If you finish, and don’t want to see any more suggestions, call
languagetool-clear-suggestions and all the highlighting will disappear.
In this mode, you first start having a running the server. To initialize it, you
can call languagetool-server-start, then you’ll have a running server attached
to Emacs (If you close Emacs, it’s over). This server starts to listen in port
8081 by default. You can change it by setting languagetool-server-port to
another value.
If you are going to use a server with another configuration, like servers not
located in your localhost, you must set languagetool-server-url and
languagetool-server-port to whatever adjust your needs. These variables play
in the communication to the LanguageTool HTTP API.
After your server is running, you can toggle on the languagetool-server-mode.
LanguageTool then starts to highlight all its suggestions in the available
portion of the buffer. You use the same method as in ~console~ mode to correct
your text.
If you finish, just toggle off the languagetool-server-mode, it will take all
the LanguageTool suggestions with itself.