+BEGIN_HTML

languagetool.el

+END_HTML

** Introduction

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).

** Installation

*** Obtaining the prerequisites

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 [[https://languagetool.org/download/][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.

*** Obtaining the package

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:

+BEGIN_SRC elisp

(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"))

+END_SRC

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.

*** Configuring the package

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:

+BEGIN_SRC elisp

(setq languagetool-java-arguments '("-Dfile.encoding=UTF-8"))

+END_SRC

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:

+BEGIN_SRC elisp

(setq languagetool-console-command "~/.languagetool/languagetool-commandline.jar" languagetool-server-command "~/.languagetool/languagetool-server.jar")

+END_SRC

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:

+BEGIN_SRC elisp

(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")

+END_SRC

If you pay for [[https://languagetool.org/proofreading-api][LanguageTool Proofreading API]] features, you can add the keys for the LanguageTool API as follows:

+BEGIN_SRC elisp

(setq languagetool-api-key "xxxxxxxxxxxx" languagetool-username "johndoe@example.com")

+END_SRC

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 [[https://www.gnu.org/software/emacs/manual/html_node/emacs/Specifying-File-Variables.html][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.

+BEGIN_SRC org

LocalWords: seplling

+END_SRC

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 [[https://www.gnu.org/software/emacs/manual/html_node/emacs/Specifying-File-Variables.html][local file variable]] ~languagetool-suggestion-level~ to the value desired, in lowercase.

** Quick Usage

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.

*** ~console~ Mode :PROPERTIES: :CUSTOM_ID: console-mode :END:

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.

*** ~server~ Mode

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][~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.