Advanced Usage

Magic Comments

Magic comments are special comments which contents are interpreted by LT_EX+ and which can be used to change some LT_EX+ settings in the middle of the document. The accepted syntax depends on the language and is shown in the following list. Except when otherwise noted, magic comments have to be on their own line, and they can be surrounded by whitespace.

BibT_EX: Same as L^AT_EX
L^AT_EX: % LTeX: SETTINGS
Markdown: One of the following:
- 
- [comment]: <> "LTeX: SETTINGS"
Org: # LTeX: SETTINGS
reStructuredText: .. LTeX: SETTINGS
R Sweave: Same as L^AT_EX
XHTML: Starting from LT_EX 15.2.0: 
Programming languages: LTeX: SETTINGS inside a line comment or a single-line block comment

Magic comments are case-insensitive (except for the setting values), and the spaces in the magic comment line can be any amount of whitespace, even no amount at all.

Magic commands trigger a reinitialization of LT_EX+ due to potentially changed parameters. This causes the text section to be split at the position of the magic command, resulting in two requests being made to the language server. By using multiple trivial magic commands (e.g., % LTeX: for L^AT_EX), you can split a large file into smaller chunks, which are then sent for checking. Although this may slightly alter the output, it can be useful for avoiding API limits of the premium API (see ltex.languageToolHttpServerUri).

SETTINGS has to be replaced with a whitespace-separated list of KEY=VALUE pairs. Neither KEY nor VALUE are enclosed in quotation marks. The following settings are supported:

enabled: One of true or false. Makes it possible to disable LT_EX+ for the rest of the document, or to enable it again.

Example: enabled=false
language: Changes the value of ltex.language for the rest of the document.

Example: language=de-DE

Multilingual L^AT_EX Documents with the babel Package

While magic comments can be used to switch languages in a L^AT_EX document, this only makes sense for long parts of text. If you just want to use few words from another language, using magic comments can be cumbersome.

The preferred way of having multiple languages in one L^AT_EX document is using the babel package. This statement even holds if you don’t use LT_EX+, as otherwise hyphenation and other language-specific aspects will be wrong in your typeset document. For instance, some words that exist in both English and German are hyphenated differently, depending on which language is used (example: ham·burg·er vs. Ham·bur·ger).

LT_EX+ supports automatically switching its ltex.language setting for a number of basic babel commands and environments. These are:

\usepackage[LANGUAGE]{babel}: Switches the language for the rest of the document.
\selectlanguage{LANGUAGE}: Switches the language for the rest of the document.
\foreignlanguage{LANGUAGE}{TEXT}: Switches the language for the contents TEXT of the last argument.
\begin{otherlanguage}{LANGUAGE}TEXT\end{otherlanguage}: Switches the language for the contents TEXT of the environment.

Here, LANGUAGE is one of babel’s language names like english, american, ngerman, etc. Refer to the babel manual for a list of possible language names. Keep in mind that not all languages supported by LT_EX+ are supported by babel, and vice versa.

For the first point of the list, multiple comma-separated babel package options are allowed instead of just one LANGUAGE. If you specify multiple languages in the package options, e.g., \usepackage[american,ngerman]{babel} (since your document is multilingual), then babel and LT_EX+ will default to the language that is mentioned last.

In addition, as the commands and environments given above are quite long, LT_EX+ supports the following shortcuts:

\textLANGUAGETAG{TEXT}: Short version of \foreignlanguage{LANGUAGE}{TEXT}.
\begin{LANGUAGETAG}TEXT\end{LANGUAGETAG}: Short version of \begin{otherlanguage}{LANGUAGE}TEXT\end{otherlanguage}.

LANGUAGETAG can be any of the following:

A language name like english, american, ngerman.
A language short code like en-US or de-DE (see ltex.language).
A language short code with dashes removed. \textLANGUAGETAG only works without dashes (\textenUS).

In order for babel to recognize the shortcuts, you have to use the \babeltags command in the form \babeltags{LANGUAGETAG1=LANGUAGE1, LANGUAGETAG2=LANGUAGE2, ...} (e.g., \babeltags{enUS=american, de-DE=ngerman, french=french}). The \babeltags command should be in your preamble, and it’s not required that it’s in the same document as the text to be checked.

As it (Italian) and sl (Slovene) would lead to \textit and \textsl, which are already taken by L^AT_EX, these two language short codes are not supported. In this case, you have to resort to using the language names italian and slovene.

Please note the following caveat: Similarly to magic comments, LT_EX+ only switches languages for the rest of the file that contains the babel commands. There is no inheritance for files that are included, e.g., via \input or \include. This is because LT_EX+ is a file-based checker and has no notion of “L^AT_EX projects” that comprise multiple T_EX files. In particular, \usepackage[LANGUAGE]{babel} will not switch languages if your preamble is in a different file than your text. In this case, use one of the other supported babel commands.

Set Language in Markdown with YAML Front Matter

In Markdown, LT_EX+ supports setting its ltex.language setting with Pandoc’s language variable lang in YAML front matter.

To use this, start your Markdown document with YAML front matter and include a variable named lang:

---
lang: LANGUAGE
---

LANGUAGE is a language short code supported by ltex.language.

Hiding False Positives with Regular Expressions

It’s possible to use ltex.hiddenFalsePositives to make LT_EX+ hide false positives based on regular expressions.

The recommended way of using ltex.hiddenFalsePositives is via the Hide false positive quick fix. This will add a JSON string containing the ID of the LanguageTool rule and the “sentence” to ltex.hiddenFalsePositives. LanguageTool internally splits every document into “sentences,” based on language-dependent rules (usually punctuation).

If you want to hide sentences based on a general pattern, you can add JSON strings with rule/sentence pairs yourself to ltex.hiddenFalsePositives. The format of the JSON string is documented in the description of the setting.

The sentence in the JSON string is a Java-compatible regular expression. Note that you have to replace all backslashes \ in the regular expression with four backslashes \\\\ as the JSON string will be parsed twice, once by the editor to read the JSON settings and once by LT_EX+ to parse the JSON string itself.

In addition, note that if you wanted to match a literal backslash \ in your regular expression, without the JSON escaping, you would have to use two backslashes \\ due to the regular expression parser. Therefore, together with the JSON escaping, you actually have to use eight backslashes \\\\\\\\ in total in your settings.json if you want to match a literal backslash. (In contrast, four backslashes are used, for instance, if you want to match the newline character \n as the backslash in there is not a literal backslash.)

Hiding false positives with ltex.hiddenFalsePositives has the following caveats:

Checking whether a match returned by LanguageTool is a false positive happens after the document has been converted from L^AT_EX, Markdown, etc. to plain text by LT_EX+. LanguageTool only returns the plain text sentence, but not the corresponding sentence in the original code. Therefore, the regular expression is matched against the plain text, not the original code. For instance, it’s not possible to have a regular expression that matches all sentences that contain a specific L^AT_EX command.
Checking whether a match returned by LanguageTool is a false positive happens after the document has been split into sentences. Therefore, it’s not possible to have regular expressions that span multiple sentences.

LanguageTool HTTP Servers

Although LT_EX+ ships with its own version of LanguageTool (LT), it’s possible to run LT independently of LT_EX+ and have LT_EX+ communicate with LT via HTTP. There are multiple scenarios in which this might be useful:

You want to run your own LT HTTP server, usually on localhost. This might be because the version of LT that comes with LT_EX+ does not work, because you want to use an older or newer version of LT than LT_EX+’s LT, or because you use other programs that use LT as well and you only want one instance of LT running.
You want to use LanguageTool Plus, the paid version of LT. In this case, you need a Developer API plan, since the Premium plan does not include API access.