TeXtidote

https://github.com/sylvainhalle/textidote
Admin
TeXtidote is a grammar and spelling checker for LaTeX documents and Markdown files that keeps track...
Tokens:13,420
Snippets:169
Trust Score:9.7
Update:5 months ago
Show doc for...
Tokens:
Raw
### Install TeXtidote on Debian Systems

Source: https://github.com/sylvainhalle/textidote/blob/master/Readme.md

Use this command to install TeXtidote via dpkg on Debian-based systems. The './' prefix is mandatory.

```bash
sudo apt-get install ./textidote_X.Y.Z_all.deb
```

--------------------------------

### Generate HTML Report with TeXtidote (Installed)

Source: https://github.com/sylvainhalle/textidote/blob/master/Readme.md

If TeXtidote is installed via apt-get, it can be called directly to generate an HTML report. Output is redirected to report.html.

```bash
textidote --output html example.tex > report.html
```

--------------------------------

### Mapping File Format Example

Source: https://github.com/sylvainhalle/textidote/blob/master/Readme.md

This is an example of the line format found in the mapping file generated by the --map option, showing correspondences between character ranges in the cleaned and original files.

```plaintext
L1C1-L1C24=L1C5-L128
L1C26-L1C28=L1C29-L1C31
L2C1-L2C10=L3C1-L3C10
...
```

--------------------------------

### Shell Auto-completion: Bash Setup

Source: https://context7.com/sylvainhalle/textidote/llms.txt

Adds TeXtidote shell auto-completion for Bash by sourcing the provided script in the user's .bashrc file.

```bash
# Bash: add to ~/.bashrc
source /opt/textidote/textidote.bash
# or if installed via apt-get, auto-completion is already active
```

--------------------------------

### TeXtidote Console Output Example

Source: https://github.com/sylvainhalle/textidote/blob/master/Readme.md

This is the typical console output when TeXtidote runs a basic verification. It indicates the version, copyright, number of warnings, and total analysis time.

```text
TeXtidote v0.8 - A linter for LaTeX documents
(C) 2018-2019 Sylvain Hallé - All rights reserved

Found 23 warnings(s)
Total analysis time: 2 second(s)
```

--------------------------------

### Shell Auto-completion: Zsh Setup

Source: https://context7.com/sylvainhalle/textidote/llms.txt

Configures TeXtidote shell auto-completion for Zsh by sourcing the provided script in the user's .zshrc file.

```bash
# Zsh: add to ~/.zshrc
source /opt/textidote/textidote.zsh
```

--------------------------------

### Find/Replace Patterns File

Source: https://github.com/sylvainhalle/textidote/blob/master/Readme.md

Format for the `replacements.txt` file. Lines starting with '#' are ignored. Patterns are separated by a tab. Supports regular expressions.

```plaintext
# Empty lines beginning with a pound sign are ignored
# Search and replace patterns are separated by a tab
find	replace
foo		bar
# Patterns can also be regular expressions
abc\d+[^x]		123
"---		---
"s		ß
\\myellipsis	\ldots
\[Bb]igm		\|
```

--------------------------------

### VS Code Task Configuration for TeXtidote

Source: https://context7.com/sylvainhalle/textidote/llms.txt

Configure VS Code's tasks.json to run TeXtidote as a shell command. This setup includes a problem matcher to parse TeXtidote's output and display errors within the editor.

```json
{
  "version": "2.0.0",
  "tasks": [{
    "label": "TeXtidote",
    "type": "shell",
    "command": "java -jar textidote.jar --output singleline --no-color ${file}",
    "problemMatcher": {
      "owner": "textidote",
      "fileLocation": ["relative", "${workspaceFolder}"],
      "pattern": {
        "regexp": "^(.+)\(L(\d+)C(\d+)-.*\):\s+(.*)$",
        "file": 1, "line": 2, "column": 3, "message": 4
      }
    }
  }]
}
```

--------------------------------

### Analyze Clipboard Content (Linux)

Source: https://github.com/sylvainhalle/textidote/blob/master/Readme.md

Use this command to analyze text copied to the clipboard on Linux systems without saving it to a file. Requires `xclip` to be installed.

```bash
xclip -o | textidote [options...]
```

--------------------------------

### TeXtidote Console Output with Local Aspell Dictionary

Source: https://github.com/sylvainhalle/textidote/blob/master/Readme.md

When TeXtidote starts, it automatically looks for and loads a local Aspell dictionary file named .aspell.XX.pws (where XX is the language code) if it exists in the current directory. A confirmation message is printed to the console.

```text
Found local Aspell dictionary
```

--------------------------------

### Ignore Specific Rule

Source: https://github.com/sylvainhalle/textidote/blob/master/Readme.md

Specify rule IDs to ignore using the `--ignore` parameter. This example ignores the rule with ID `sh:001`.

```java
java -jar textidote.jar --ignore sh:001 myfile.tex
```

--------------------------------

### Using a Configuration File

Source: https://github.com/sylvainhalle/textidote/blob/master/Readme.md

Configure TeXtidote by placing arguments in a .textidote file in the current directory. This allows for complex configurations without long command lines.

```plaintext
--output html --read-all
--replace replacements.txt
--dict mydict.txt
--ignore sh:001,sh:d:001
--check en mytext.tex
```

--------------------------------

### Run TeXtidote with Configuration File

Source: https://github.com/sylvainhalle/textidote/blob/master/Readme.md

Execute TeXtidote using arguments defined in the .textidote configuration file. The output is redirected to an HTML report.

```bash
textidote > report.html
```

--------------------------------

### Default CLI Configuration File

Source: https://context7.com/sylvainhalle/textidote/llms.txt

Place a .textidote file in the project root to set default command-line arguments. Use --no-config to bypass.

```bash
# .textidote  (placed in project root)
--output html
--read-all
--replace replacements.txt
--dict mydict.txt
--ignore sh:001,sh:001
--check en mytext.tex
```

```bash
# Run with config file active (arguments are merged)
textidote > report.html
```

```bash
# Ignore the config file for this run
textidote --no-config --output plain paper.tex
```

--------------------------------

### Initialize and Use Textidote Linter in Java

Source: https://context7.com/sylvainhalle/textidote/llms.txt

Demonstrates setting up a cleaner pipeline, creating a Linter instance, adding various types of rules (raw and cleaned text), blacklisting rules, and evaluating a source file. This is the primary way to use the Textidote library programmatically.

```java
import ca.uqac.lif.textidote.Linter;
import ca.uqac.lif.textidote.Advice;
import ca.uqac.lif.textidote.as.AnnotatedString;
import ca.uqac.lif.textidote.cleaning.CompositeCleaner;
import ca.uqac.lif.textidote.cleaning.latex.LatexCleaner;
import ca.uqac.lif.textidote.rules.CheckNoBreak;
import ca.uqac.lif.textidote.rules.RegexRule;

import java.util.Scanner;
import java.util.List;

// 1. Build a cleaner pipeline
LatexCleaner latexCleaner = new LatexCleaner();
latexCleaner.setIgnoreBeforeDocument(true); // skip preamble
CompositeCleaner cleaner = new CompositeCleaner();
cleaner.add(latexCleaner);

// 2. Create the linter
Linter linter = new Linter(cleaner);

// 3. Add rules applied to the raw (comment-stripped) source
linter.add(new CheckNoBreak());
linter.add(new RegexRule("sh:001",
    "\\(sub)*section\\{\\s*[a-z].*?\}",
    "A section title should start with a capital letter."));

// 4. Add rules applied to the cleaned plain text
linter.addCleaned(new RegexRule("sh:d:001", ",[A-Za-z]",
    "There should be a space after a comma."));

// 5. Ignore specific rules
linter.addToBlacklist(List.of("sh:001", "sh:d:*"));

// 6. Read input and evaluate
Scanner sc = new Scanner(new File("paper.tex"), "utf-8");
AnnotatedString source = AnnotatedString.read(sc);
source.setResourceName("paper.tex");
sc.close();

List<Advice> adviceList = linter.evaluateAll(source);
for (Advice a : adviceList) {
    System.out.println(a.getPositionRange() + ": " + a.getMessage()
        + " [" + a.getRule().getName() + "]");
}
// Output example:
// L25C1-L25C25: A section title should start with a capital letter. [sh:001]
```

--------------------------------

### Compile TeXtidote Project

Source: https://github.com/sylvainhalle/textidote/blob/master/Readme.md

Use the Ant build tool to compile the TeXtidote sources. This will generate the `textidote.jar` file.

```bash
ant
```

--------------------------------

### Create Linux Command Line Shortcut for TeXtidote

Source: https://github.com/sylvainhalle/textidote/blob/master/Readme.md

This bash script creates a command-line executable for TeXtidote, assuming the 'textidote.jar' file is located in '/opt/textidote'. Make the script executable after creation.

```bash
#! /bin/bash
java -jar /opt/textidote/textidote.jar "$@"
```

--------------------------------

### Download TeXtidote Dependencies

Source: https://github.com/sylvainhalle/textidote/blob/master/Readme.md

Use the Ant build tool to download the necessary dependencies for compiling TeXtidote.

```bash
ant download-deps
```

--------------------------------

### Docker: Run HTML Report Generation

Source: https://context7.com/sylvainhalle/textidote/llms.txt

Executes the TeXtidote Docker container to generate an HTML report. Mounts the current directory as /doc and sets it as the working directory.

```bash
# Run HTML report (mount current dir as /doc)
docker run --rm -v "$(pwd):/doc" -w /doc textidote \
  --output html paper.tex > report.html
```

--------------------------------

### Docker: Check Markdown File

Source: https://context7.com/sylvainhalle/textidote/llms.txt

Runs TeXtidote via Docker to check a Markdown file for grammar and style. Mounts the current directory and sets it as the working directory.

```bash
# Check Markdown file
docker run --rm -v "$(pwd):/doc" -w /doc textidote \
  --check en --type md README.md
```

--------------------------------

### Sub-file Handling and Root Document with TeXtidote

Source: https://context7.com/sylvainhalle/textidote/llms.txt

TeXtidote automatically follows `\input` and `\include` directives. Use `--read-all` for sub-files lacking `\begin{document}`, and `--root` to explicitly set the project root.

```bash
# Check a multi-file document starting from main.tex
java -jar textidote.jar --check en main.tex
```

```bash
# Force reading all content (no \begin{document} in sub-file)
java -jar textidote.jar --read-all --check en chapter1.tex
```

```bash
# Specify document root manually (supports %!TEX root directive too)
java -jar textidote.jar --root main.tex chapter1.tex
```

--------------------------------

### Run TeXtidote with Plain Report

Source: https://github.com/sylvainhalle/textidote/blob/master/Readme.md

Omit the --output html option to display results directly in the console. The plain report format shows warnings with line and column numbers, a description, and an excerpt marked with '^'.

```bash
java -jar textidote.jar example.tex
```

--------------------------------

### Docker: Build TeXtidote Image

Source: https://context7.com/sylvainhalle/textidote/llms.txt

Builds the official TeXtidote Docker image from the provided Dockerfile. This image is based on OpenJDK 8.

```bash
# Build the image
docker build -t textidote .
```

--------------------------------

### Docker: Run Grammar Check

Source: https://context7.com/sylvainhalle/textidote/llms.txt

Uses the TeXtidote Docker container to perform a grammar check on a LaTeX file. Mounts the current directory and sets it as the working directory.

```bash
# Run grammar check
docker run --rm -v "$(pwd):/doc" -w /doc textidote \
  --check en --output singleline paper.tex
```

--------------------------------

### TeXtidote Desktop Entry Configuration

Source: https://github.com/sylvainhalle/textidote/blob/master/Readme.md

This INI file defines a desktop entry for TeXtidote, allowing it to be launched from the desktop environment by dropping files onto its icon. Ensure the Exec and Icon paths are correct.

```ini
[Desktop Entry]
Version=1.0
Type=Application
Name=TeXtidote
Comment=Check text with TeXtidote
Exec=/opt/textidote/textidote-desktop.sh %F
Icon=/opt/textidote/textidote-icon.svg
Path=
Terminal=false
StartupNotify=false
```

--------------------------------

### Enable Bash Auto-completion for TeXtidote

Source: https://github.com/sylvainhalle/textidote/blob/master/Completions/Readme.md

Add this line to your .bashrc file to enable Bash auto-completion for TeXtidote. Ensure you replace `/path/to/` with the actual path to the `textidote.bash` script.

```bash
source /path/to/textidote.bash
```

--------------------------------

### Create Linux Desktop Shortcut Script for TeXtidote

Source: https://github.com/sylvainhalle/textidote/blob/master/Readme.md

This bash script generates an HTML report of TeXtidote analysis and opens it in the default browser. It includes error handling and uses 'notify-send' if available.

```bash
#!/bin/bash
if [ -x /usr/bin/notify-send ]; then
  err() { notify-send -a TeXtidote -i /opt/textidote/textidote-icon.svg "$*"; }
else
  err() { printf "%s\n" "$*" >&2; }
fi

[ $# -lt 1 ] && err "At least one file should be provided as input" && exit
dir=$(dirname "$1")

pushd "$dir" || err "$dir does not exist" && exit
java -jar /opt/textidote/textidote.jar --check en --output html "$@" > /tmp/textidote.html
popd || exit

xdg-open /tmp/textidote.html &
```

--------------------------------

### Read All File Content

Source: https://github.com/sylvainhalle/textidote/blob/master/Readme.md

Use the `--read-all` option when analyzing files that do not contain `\begin{document}` to ensure the entire file is processed.

```java
java -jar textidote.jar --read-all myfile.tex
```

--------------------------------

### Clone TeXtidote Repository

Source: https://github.com/sylvainhalle/textidote/blob/master/Readme.md

Clone the TeXtidote project from GitHub using the provided Git command.

```bash
git clone git@github.com:sylvainhalle/textidote.git
```

--------------------------------

### Ignore \input with Comments

Source: https://context7.com/sylvainhalle/textidote/llms.txt

Wrap \input commands with \% textidote: ignore begin and \% textidote: ignore end comments to exclude them from analysis.

```latex
% textidote: ignore begin
\input{generated-content}
% textidote: ignore end
```

--------------------------------

### Basic lint with HTML report

Source: https://context7.com/sylvainhalle/textidote/llms.txt

Generates an interactive HTML report for a LaTeX file. Use this for a visual review of issues in a web browser. The output is redirected to an HTML file.

```bash
java -jar textidote.jar --output html paper.tex > report.html
```

```bash
textidote --output html paper.tex > report.html
```

```bash
# Open the generated report
xdg-open report.html   # Linux
open report.html       # macOS
```

--------------------------------

### Create MacOS Shortcut Script for TeXtidote

Source: https://github.com/sylvainhalle/textidote/blob/master/Readme.md

This shell script is designed for MacOS Automator. It analyzes LaTeX files using TeXtidote, generates an HTML report, and opens it in the default web browser. Remember to update the path to 'textidote.jar'.

```bash
[ $# -lt 1 ] && echo "At least one file should be provided as input" 1>&2 && exit 1
dir=$(dirname "$1")

cd "$dir" || (echo "$dir does not exist" 1>&2 && exit 1)
java -jar /path/to/textidote.jar --check en --output html "$@" > /tmp/textidote.html || true

open /tmp/textidote.html
```

--------------------------------

### Enable Zsh Auto-completion for TeXtidote

Source: https://github.com/sylvainhalle/textidote/blob/master/Completions/Readme.md

Add this line to your .zshrc file to enable Zsh auto-completion for TeXtidote. Replace `/path/to/` with the actual path to the `textidote.zsh` script.

```zsh
source /path/to/textidote.zsh
```

--------------------------------

### Run TeXtidote with Single Line Report

Source: https://github.com/sylvainhalle/textidote/blob/master/Readme.md

Use the --output singleline option to display results in a parseable single-line format. Each line includes the filename, position, warning message, and the problematic excerpt in quotes.

```bash
java -jar textidote.jar --output singleline example.tex
```

--------------------------------

### Find/Replace Preprocessing with TeXtidote --replace

Source: https://context7.com/sylvainhalle/textidote/llms.txt

Apply regex find/replace rules before cleaning or linting using the `--replace` option. This is useful for substituting custom macros with their textual equivalents.

```bash
java -jar textidote.jar --replace replacements.txt paper.tex
```

```text
# Expand abbreviation macros
\myabbr	abbreviation
# Replace custom ellipsis with LaTeX standard
\myellipsis	\ldots
# Regex replacement: expand \Bigm to |
\[Bb]igm	\|
# Replace typographic quotes
"---	---
```

--------------------------------

### Apply Find/Replace Operations

Source: https://github.com/sylvainhalle/textidote/blob/master/Readme.md

Use the `--replace` parameter with a file containing find/replace patterns to pre-process the text before analysis.

```java
$ java -jar textidote.jar --replace replacements.txt
```

--------------------------------

### Generate Mapping with --clean --map

Source: https://github.com/sylvainhalle/textidote/blob/master/Readme.md

Combine --clean and --map options to generate a mapping file that correlates character ranges between the cleaned and original LaTeX files. The cleaned output is redirected to a file.

```bash
java -jar textidote.jar --clean --map map.txt example.tex > clean.txt
```

--------------------------------

### Generate HTML Report with TeXtidote

Source: https://github.com/sylvainhalle/textidote/blob/master/Readme.md

Run TeXtidote using Java to generate an HTML report from a LaTeX file. Output is redirected to report.html. This command can also be used with standard input by omitting the filename or using '--'.

```bash
java -jar textidote.jar --output html example.tex > report.html
```

--------------------------------

### Specify Root Document

Source: https://github.com/sylvainhalle/textidote/blob/master/Readme.md

Use the `--root` argument to specify the root document when TeXtidote needs to follow sub-files, especially when the `%!TEX root = ...` directive is not used or needs overriding.

```java
java -jar textidote.jar --root main.tex myfile.tex
```

--------------------------------

### Clickable report (--output clickable)

Source: https://context7.com/sylvainhalle/textidote/llms.txt

Produces diagnostics prefixed with `file:line:column:`, which are directly parsable by many editors like VS Code and Emacs flycheck for navigation. Use `--no-color` for cleaner output.

```bash
java -jar textidote.jar --output clickable --no-color paper.tex
```

--------------------------------

### Analyze Clipboard Content (MacOS X)

Source: https://github.com/sylvainhalle/textidote/blob/master/Readme.md

Use this command to analyze text copied to the clipboard on MacOS X without saving it to a file. Requires `pbpaste` utility.

```bash
pbpaste | textidote [options...]
```

--------------------------------

### Use N-gram Language Model

Source: https://context7.com/sylvainhalle/textidote/llms.txt

Activate LanguageTool's n-gram model for improved accuracy in detecting word confusion errors. Requires a pre-downloaded index.

```bash
java -jar textidote.jar --check en --languagemodel /path/to/ngram-data paper.tex
```

--------------------------------

### Generate JSON Report with TeXtidote

Source: https://context7.com/sylvainhalle/textidote/llms.txt

Use the `--output json` flag to generate LanguageTool-compatible JSON reports. This is useful for programmatic post-processing or integration with other tools.

```bash
java -jar textidote.jar --check en --output json paper.tex > results.json
```

```json
{
  "software": {
    "name": "TeXtidote",
    "version": "0.9",
    "buildDate": "2019-08-03 10:08",
    "apiVersion": 1
  },
  "warnings": {},
  "language": { "name": "English", "code": "en" },
  "matches": [
    {
      "message": "A section title should start with a capital letter.",
      "shortMessage": "TeXtidote rule",
      "replacements": [],
      "offset": 120,
      "length": 25,
      "context": { "text": "...", "offset": 0, "length": 25 },
      "rule": { "id": "sh:001", "description": "Regex check on the text" }
    }
  ]
}
```

--------------------------------

### Perform Grammar and Style Checks

Source: https://github.com/sylvainhalle/textidote/blob/master/Readme.md

Use the --check option followed by a two-letter language code to perform spelling, grammar, and style checks. Language Tool is used for these checks.

```bash
java -jar textidote.jar --check en example.tex
```

--------------------------------

### CI Integration with --ci Flag

Source: https://context7.com/sylvainhalle/textidote/llms.txt

Use the --ci flag to ensure TeXtidote returns an exit code of 0, preventing CI pipelines from failing due to warnings. Alternatively, use 'continue-on-error: true' or 'allow_failure: true'.

```yaml
# GitHub Actions
- name: Lint LaTeX
  run: java -jar textidote.jar --check en --output singleline paper.tex
  continue-on-error: true
```

```yaml
# Or use --ci flag
- name: Lint LaTeX
  run: java -jar textidote.jar --check en --ci paper.tex
```

```yaml
lint:
  script: java -jar textidote.jar --check en paper.tex
  allow_failure: true
```

--------------------------------

### Strip Markup with TeXtidote --clean

Source: https://context7.com/sylvainhalle/textidote/llms.txt

Use the `--clean` flag to remove all LaTeX markup and print only the plain text to stdout. The `--map` option can generate a character-range mapping file for correlating clean-text positions back to the original source.

```bash
# Print cleaned text to stdout
java -jar textidote.jar --clean paper.tex
```

```bash
# Save cleaned text and position map
java -jar textidote.jar --clean --map map.txt paper.tex > clean.txt
```

```bash
# Clean a Markdown file
java -jar textidote.jar --clean --type md README.md
```

```text
L1C1-L1C24=L1C5-L1C28
L1C26-L1C28=L1C29-L1C31
L2C1-L2C10=L3C1-L3C10
```

--------------------------------

### Single-line report (--output singleline)

Source: https://context7.com/sylvainhalle/textidote/llms.txt

Generates a compact report with one warning per line, formatted as `file(LxxCyy-LzzCww): message "excerpt"`. This is ideal for parsing by scripts, CI pipelines, or editor integrations. Use `--no-color` for cleaner output.

```bash
java -jar textidote.jar --output singleline --no-color paper.tex
```

--------------------------------

### Save Cleaned Output to File

Source: https://github.com/sylvainhalle/textidote/blob/master/Readme.md

Redirect the output of the --clean command to a file to save the cleaned text.

```bash
java -jar textidote.jar --clean example.tex > clean.txt
```

--------------------------------

### Use Custom Dictionary with TeXtidote --dict

Source: https://context7.com/sylvainhalle/textidote/llms.txt

Provide a plain-text word list using the `--dict` option to prevent TeXtidote from flagging specific words as spelling errors. Aspell local dictionaries are automatically detected.

```bash
# Explicit dictionary file
java -jar textidote.jar --check en --dict mywords.txt paper.tex
```

```bash
# Aspell local dictionary is loaded automatically if present:
# .aspell.en.pws  ->  auto-loaded when --check en is used
```

```text
Kleene
LTL
LTLf
co-NP
```

--------------------------------

### Use a Custom Dictionary for Spelling Checks

Source: https://github.com/sylvainhalle/textidote/blob/master/Readme.md

Specify a custom dictionary file using the --dict parameter to ignore specific words during spelling checks. The dictionary file should contain one word per line.

```bash
java -jar textidote.jar --check en --dict dico.txt example.tex
```

--------------------------------

### Enable Zsh Tab Completion for TeXtidote

Source: https://github.com/sylvainhalle/textidote/blob/master/Readme.md

Add this line to your ~/.zshrc file to enable command-line tab completion for TeXtidote in Zsh. Restart your shell after adding the line.

```zsh
source /opt/textidote/textidote.zsh
```

--------------------------------

### Specify Markdown Input Type

Source: https://github.com/sylvainhalle/textidote/blob/master/Readme.md

When providing input via standard input, use the --type md parameter to explicitly tell TeXtidote that the input is in Markdown format, as it defaults to LaTeX.

```bash
--type md
```

--------------------------------

### Remove Environments and Macros with TeXtidote

Source: https://context7.com/sylvainhalle/textidote/llms.txt

Instruct TeXtidote to treat specified LaTeX environments or macro calls as comments using `--remove` and `--remove-macros`. This makes their content invisible to all rules.

```bash
# Remove a single environment
java -jar textidote.jar --remove itemize paper.tex
```

```bash
# Remove multiple environments
java -jar textidote.jar --remove itemize,lstlisting,verbatim paper.tex
```

```bash
# Remove a custom macro (\foo, \foo{bar}, \foo[x=y]{bar})
java -jar textidote.jar --remove-macros foo paper.tex
```

```bash
# Combine both
java -jar textidote.jar --remove lstlisting --remove-macros myabbrev paper.tex
```

--------------------------------

### Configure GitHub CI to Continue on Error

Source: https://github.com/sylvainhalle/textidote/blob/master/Readme.md

Use `continue-on-error: true` in your GitHub Actions workflow to prevent pipeline failure when TeXtidote returns a non-zero exit code.

```yaml
continue-on-error: true
```

--------------------------------

### AnnotatedString Class: Transformations and Provenance

Source: https://context7.com/sylvainhalle/textidote/llms.txt

Demonstrates creating, transforming, and querying an AnnotatedString, including mapping current indices/positions/ranges back to the original source text.

```java
import ca.uqac.lif.textidote.as.AnnotatedString;
import ca.uqac.lif.textidote.as.Position;
import ca.uqac.lif.petitpoucet.function.strings.Range;

// Create from raw text
AnnotatedString s = new AnnotatedString("Hello world foo bar baz.");

// Apply transformations (mutations; each returns 'this')
s.replaceAll("foo", "abcde")           // "Hello world abcde bar baz."
 .substring(6, s.lastIndexOf("baz"));  // "world abcde bar "

// Query current content
System.out.println(s);           // "world abcde bar "
System.out.println(s.length());  // 16
System.out.println(s.lineCount()); // 1

// Map a current index back to original source index
int origIndex = s.findOriginalIndex(1); // index of 'o' in "world"
// → points to position 7 in the original string

// Map a current position (line/col) back to original
Position currentPos = new Position(0, 6);  // column 6 in cleaned text
Position origPos = s.findOriginalPosition(currentPos);
System.out.println(origPos);  // line 0, column 12 in original

// Map a range in current text to original range
Range origRange = s.findOriginalRange(0, 4); // "world" in cleaned text
System.out.println(origRange); // [6,10] in original string

// Get line/column position from linear index
Position p = s.getPosition(3);
System.out.println("line=" + p.getLine() + " col=" + p.getColumn());

// Export the full mapping for external use
java.util.Map<Range, Range> map = s.getMap();
```

--------------------------------

### Plain (console) report

Source: https://context7.com/sylvainhalle/textidote/llms.txt

Outputs a human-readable report directly to the terminal. This format includes line/column references and a `^^^^` underline to highlight problematic ranges in the original source.

```bash
java -jar textidote.jar paper.tex
# or explicitly
java -jar textidote.jar --output plain paper.tex
```

--------------------------------

### Analyze Clipboard Content (Windows PowerShell)

Source: https://github.com/sylvainhalle/textidote/blob/master/Readme.md

Use this command to analyze text copied to the clipboard on Windows using PowerShell. Requires `GetClipboard` cmdlet.

```powershell
GetClipboard | textidote [options...]
```

--------------------------------

### Perform Checks with First Language Option

Source: https://github.com/sylvainhalle/textidote/blob/master/Readme.md

Use --firstlang option to specify your primary language for Language Tool, useful for detecting false friends. This is used in conjunction with the --check option.

```bash
java -jar textidote.jar --check en --firstlang de example.tex
```

--------------------------------

### Emacs Flycheck Checker for TeXtidote

Source: https://github.com/sylvainhalle/textidote/blob/master/Readme.md

Define a custom Flycheck checker in your Emacs init.el or .emacs file to use TeXtidote for LaTeX grammar and spelling checks. Ensure you replace '~/PATH/TO/textidote.jar' with the actual path to your textidote.jar file.

```emacs-lisp
(flycheck-define-checker tex-textidote
  "A LaTeX grammar/spelling checker using textidote.

  See https://github.com/sylvainhalle/textidote"
  :modes (latex-mode plain-tex-mode)
  :command ("java" "-jar" (eval (expand-file-name("~/PATH/TO/textidote.jar")))
            "--read-all"
            "--output" "singleline"
            "--no-color"
            "--check"   (eval (if ispell-current-dictionary (substring ispell-current-dictionary 0 2) "en"))
            ;; Try to honor local aspell dictionary and replacements if they exist
            "--dict"    (eval (expand-file-name "~/.aspell.en.pws"))
            "--replace" (eval (expand-file-name "~/.aspell.en.prepl"))
            ;; Using source ensures that a single temporary file in a different dir is created
            ;; such that textidote won't process other files. This serves as a hacky workaround for
            ;; https://github.com/sylvainhalle/textidote/issues/200.
            source)
  :error-patterns ((warning line-start (file-name)
                            "(L" line "C" column "-" (or (seq "L" end-line "C" end-column) "?"): "
                            (message (one-or-more (not "")))(one-or-more not-newline) line-end)))
(add-to-list 'flycheck-checkers 'tex-textidote)
```

--------------------------------

### Remove LaTeX Markup with --clean

Source: https://github.com/sylvainhalle/textidote/blob/master/Readme.md

Use the --clean option to remove LaTeX markup and obtain a plain text version of your document. The output is printed to the console by default.

```bash
java -jar textidote.jar --clean example.tex
```

--------------------------------

### Configure GitLab CI to Allow Failure

Source: https://github.com/sylvainhalle/textidote/blob/master/Readme.md

Use `allow_failure: true` in your GitLab CI configuration to allow jobs to fail without stopping the entire pipeline, useful when TeXtidote returns a non-zero exit code.

```yaml
allow_failure: true
```

--------------------------------

### Inline Ignore Comments in LaTeX

Source: https://context7.com/sylvainhalle/textidote/llms.txt

Use % textidote: ignore begin and % textidote: ignore end comments to skip specific regions in LaTeX source during analysis.

```latex
% LaTeX: ignore a region
% textidote: ignore begin
Some weird LaTeX markup that TeXtidote does not understand...
\customWeirdMacro{strange}{args}
% textidote: ignore end
```

--------------------------------

### Set Encoding and File Type

Source: https://context7.com/sylvainhalle/textidote/llms.txt

Override default file encoding or force input type when auto-detection fails, such as when reading from stdin.

```bash
# Windows cp1252 encoded file
java -jar textidote.jar --encoding cp1252 paper.tex
```

```bash
# Read Markdown from stdin (pipe)
cat README.md | java -jar textidote.jar --type md --check en
```

```bash
# Read LaTeX from clipboard (Linux)
xclip -o | textidote --type tex --check en
```

```bash
# Read LaTeX from clipboard (macOS)
pbpaste | textidote --type tex --check en
```

```bash
# Read LaTeX from clipboard (Windows PowerShell)
Get-Clipboard | textidote --type tex --check en
```

--------------------------------

### Ignore LaTeX Markup with TeXtidote

Source: https://github.com/sylvainhalle/textidote/blob/master/Readme.md

Use these comments to tell TeXtidote to ignore specific regions of LaTeX markup that it may not understand, preventing garbled output or nonsensical warnings.

```latex
% textidote: ignore begin
Some weird LaTeX markup that TeXtidote does not
understand...
% textidote: ignore end
```

--------------------------------

### Grammar and spelling check with --check

Source: https://context7.com/sylvainhalle/textidote/llms.txt

Performs a deep language check using LanguageTool on the cleaned text. Specify the two-letter language code (BCP 47) for the check. Supports variant locales and first-language detection.

```bash
# Check English grammar and spelling
java -jar textidote.jar --check en paper.tex
```

```bash
# Check French
java -jar textidote.jar --check fr rapport.tex
```

```bash
# Check with a variant locale
java -jar textidote.jar --check en_UK thesis.tex
```

```bash
# Check with first-language false-friend detection (author's L1 is German)
java -jar textidote.jar --check en --firstlang de paper.tex
```

--------------------------------

### Disable Sub-file Following

Source: https://context7.com/sylvainhalle/textidote/llms.txt

Use the --single-file option to prevent TeXtidote from following \input commands.

```bash
java -jar textidote.jar --single-file paper.tex
```

--------------------------------

### ReplacementCleaner Class: Regex Find/Replace with Provenance

Source: https://context7.com/sylvainhalle/textidote/llms.txt

Applies regex find/replace rules loaded from a text source to an AnnotatedString, preserving provenance. Useful for custom macro expansions or text normalization.

```java
import ca.uqac.lif.textidote.cleaning.ReplacementCleaner;
import ca.uqac.lif.textidote.as.AnnotatedString;

import java.util.Scanner;
import java.io.StringReader;

// Load from a formatted text source (tab-separated find → replace)
String rules =
    "# Custom macro expansions
" +
    "\\myname\tAlice
" +
    "\\Bigm\t|\n" +
    ""---	---
";

Scanner sc = new Scanner(new StringReader(rules));
ReplacementCleaner rc = ReplacementCleaner.create(sc);
sc.close();

// Apply to source
AnnotatedString s = new AnnotatedString("Hello \\myname, the result is \\Bigm{} cool.");
AnnotatedString result = rc.clean(s);
System.out.println(result);
// Output: "Hello Alice, the result is | cool."
```

--------------------------------

### Specify Character Encoding

Source: https://github.com/sylvainhalle/textidote/blob/master/Readme.md

Override the default OS encoding for reading files using the --encoding option, specifying the desired encoding such as 'cp1252'.

```bash
java -jar textidote.jar --encoding cp1252 example.tex
```

--------------------------------

### Inline Ignore Comments in Markdown

Source: https://context7.com/sylvainhalle/textidote/llms.txt

Use <!-- textidote: ignore begin --> and <!-- textidote: ignore end --> comments to skip specific regions in Markdown source during analysis.

```markdown
<!-- Markdown: ignore a region -->
<!-- textidote: ignore begin -->
This should be ignored by TeXtidote.
<!-- textidote: ignore end -->
```

--------------------------------

### Ignore Rules with TeXtidote --ignore

Source: https://context7.com/sylvainhalle/textidote/llms.txt

Suppress specific rule IDs or groups of rules using the `--ignore` flag. Rule IDs are shown in brackets in report formats. Wildcards (`*`) can be used to suppress entire rule categories.

```bash
# Ignore a single rule
java -jar textidote.jar --ignore sh:001 paper.tex
```

```bash
# Ignore multiple rules
java -jar textidote.jar --ignore sh:001,sh:002,sh:d:001 paper.tex
```

```bash
# Ignore all citation rules using wildcard
java -jar textidote.jar --ignore "sh:c:*" paper.tex
```

--------------------------------

### Emacs Flycheck Checker for TeXtidote

Source: https://context7.com/sylvainhalle/textidote/llms.txt

Define a custom checker for Emacs' Flycheck mode to use TeXtidote for LaTeX files. This configuration specifies the command, error patterns, and integrates with existing spell-checking dictionaries.

```emacs-lisp
(flycheck-define-checker tex-textidote
  "LaTeX grammar/spelling checker using TeXtidote."
  :modes (latex-mode plain-tex-mode)
  :command ("java" "-jar" "/opt/textidote/textidote.jar"
            "--read-all" "--output" "singleline" "--no-color"
            "--check" (eval (if ispell-current-dictionary
                               (substring ispell-current-dictionary 0 2) "en"))
            "--dict"    (eval (expand-file-name "~/.aspell.en.pws"))
            "--replace" (eval (expand-file-name "~/.aspell.en.prepl"))
            source)
  :error-patterns
  ((warning line-start (file-name)
            "(L" line "C" column "-" (or (seq "L" end-line "C" end-column) "?") "): "
            (message (one-or-more (not "")))
            (one-or-more not-newline) line-end)))
(add-to-list 'flycheck-checkers 'tex-textidote)
```

--------------------------------

### Ignore Multiple Rules

Source: https://github.com/sylvainhalle/textidote/blob/master/Readme.md

To ignore multiple rules, separate their IDs with a comma and no spaces.

```java
java -jar textidote.jar --ignore rule1,rule2,rule3 myfile.tex
```

--------------------------------

### Remove Specific Environment

Source: https://github.com/sylvainhalle/textidote/blob/master/Readme.md

Use the `--remove` parameter to instruct TeXtidote to ignore content within specified environments, such as `itemize`.

```java
$ java -jar textidote.jar --remove itemize myfile.tex
```

--------------------------------

### LatexCleaner Class: Cleaning LaTeX with Provenance

Source: https://context7.com/sylvainhalle/textidote/llms.txt

Configures and applies LatexCleaner to remove LaTeX markup from an AnnotatedString while preserving character provenance. It can ignore specific environments and macros.

```java
import ca.uqac.lif.textidote.cleaning.latex.LatexCleaner;
import ca.uqac.lif.textidote.as.AnnotatedString;

import java.util.Arrays;

// Create cleaner with root directory (for resolving \input sub-files)
LatexCleaner cleaner = new LatexCleaner("/path/to/project");

// Configuration
cleaner.setIgnoreBeforeDocument(true);  // skip preamble (default: true)
cleaner.ignoreEnvironments(Arrays.asList("lstlisting", "verbatim", "itemize"));
cleaner.ignoreMacros(Arrays.asList("myabbrev", "todo"));

// Apply to source string
AnnotatedString source = new AnnotatedString(
    "\\begin{document}
" +
    "This is \\textbf{important} text.
" +
    "\\begin{lstlisting}
code block
\\end{lstlisting}
" +
    "More text.
" +
    "\\end{document}");

AnnotatedString cleaned = cleaner.clean(source);
System.out.println(cleaned);
// Output:
// This is important text.
// More text.

// After cleaning, get list of \input sub-files found in the document
java.util.List<String> subFiles = cleaner.getInnerFiles();
// e.g. ["chapter1.tex", "chapter2.tex"]
```

--------------------------------

### Ignore Markdown Sections with TeXtidote

Source: https://github.com/sylvainhalle/textidote/blob/master/Readme.md

When working with Markdown, use these HTML-style comments to selectively ignore parts of the document from TeXtidote's analysis.

```markdown
<!-- textidote: ignore begin -->
This should be ignored
<!-- textidote: ignore end -->
```

--------------------------------

### Remove Macros

Source: https://github.com/sylvainhalle/textidote/blob/master/Readme.md

Use the `--remove-macros` parameter to remove occurrences of user-defined macros.

```java
$ java -jar textidote.jar --remove-macros foo myfile.tex
```
Tokens:
Raw