Tildefy

Tildefy is a command-line tool designed to automatically insert non-breaking spaces (tildes ~) into LaTeX (.tex) documents to prevent unwanted line breaks.

It is especially useful for languages with strict formatting regarding single-letter prepositions, academic titles, numbers and units, and citations (such as Czech).

⚠️ Disclaimer: Tildefy simply automates the insertion of tildes. While it successfully handles most common situations, it might not work in 100% of cases. Please be cautious and always double-check the applied changes (e.g., using the --diff flag) before compiling your final document.

How It Works

Tildefy doesn't just blindly replace text using regular expressions. It is a smart LaTeX processor that operates in three steps:

1. Segmentation: The input document is parsed and segmented into "SAFE" and "UNSAFE" blocks. Unsafe blocks, such as math environments ($, \begin{equation}), code listings (\begin{lstlisting}), and comments (%), are protected and completely ignored during processing.
2. Rule Loading: A designated YAML ruleset is loaded. Rules are sorted by a priority value to ensure specific rules are applied before more general fallback rules.
3. Application: The rules (which can be standard Regex replacements or custom specific processors) are applied exclusively to the "SAFE" segments of the document.

Installation

1. Clone the repository:

   git clone https://github.com/JanPrindis/Tildefy.git
   cd tildefy

2. Create and activate a virtual environment (highly recommended):

   python -m venv .venv
   # On Windows: .venv\Scripts\activate
   # On macOS/Linux: source .venv/bin/activate

3. Install the package and its dependencies:

   pip install .

   (For development, use pip install -e ".[dev]" instead).

Usage & Examples

Tildefy provides a colorful and user-friendly CLI powered by the rich library. You can process single files or entire directories.

Basic Usage

Print the processed output of a single file to the console:

tildefy path/to/document.tex

See What Will Change (Dry Run)

You can view a beautifully highlighted character-level diff without modifying your actual files. This is perfect for reviewing changes:

tildefy path/to/document.tex --diff

Process and Save in Place

To apply the changes and overwrite the original files, use the --inplace flag. By default, Tildefy creates a .bak backup of your file before overwriting it.

tildefy path/to/document.tex --inplace

Process an Entire Directory

You can pass a directory instead of a single file. Tildefy will recursively find all .tex files (or a custom extension using --ext) and process them:

tildefy ./my_thesis_folder/ --inplace

Disable Backups

If you are using Git and don't need .bak files cluttering your directory, you can disable backups:

tildefy ./my_thesis_folder/ --inplace --no-backup

Use Custom Rules

By default, Tildefy uses the Czech typography ruleset. You can easily pass your own YAML ruleset:

tildefy ./document.tex --inplace --rules ./rules/my_custom_rules.yaml

Testing

The project includes a robust, data-driven test suite built on top of pytest.

To learn how the tests work, how to run them, and how to add support for a new language or custom ruleset, please see the Testing Documentation.

License

This project is licensed under the MIT License.