#+BEGIN_HTML
<p align="center">
  <img
    src="https://user-images.githubusercontent.com/30298743/151288287-82b50b4e-aab6-40e6-9bae-fd55161c72ba.svg"
    alt="languagetool.el logo" />
</p>
<h1 align="center">languagetool.el</h1>
<p align="center">
  <img
    src="https://user-images.githubusercontent.com/30298743/151289330-d298348c-5052-446f-9098-c888df631b51.png"
    alt="languagetool.el in action" />
</p>
<hr />
<p align="center">
  <a href="https://melpa.org/#/languagetool">
    <img
      src="https://melpa.org/packages/languagetool-badge.svg"
      alt="MELPA Version" />
  </a>
  <a href="https://stable.melpa.org/#/languagetool">
    <img
      src="https://stable.melpa.org/packages/languagetool-badge.svg"
      alt="MELPA Stable Version" />
  </a>
  <a href="https://github.com/PillFall/Emacs-LanguageTool.el/actions/workflows/byte-compile.yml">
    <img
      src="https://github.com/PillFall/Emacs-LanguageTool.el/workflows/build/badge.svg"
      alt="CI Status" />
  </a>
</p>
#+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.