oat-tools 1.1.3
OAT Tools is a CLI for managing Oppimispäiväkirja Markdown files.
Requires Python: >=3.13

## OAT Tools

OAT Tools is a CLI tool written in Python. It is installed as executable `oat` using `uv tool install` or as one-off run using `uvx`. The tool has been designed to help you manage Markdown files written to learning diary written using OAT Spec (as described in [Oppimispäiväkirja 101](https://sourander.github.io/oat)).

The idea is to keep the tool minimalistic and simple. It will handle the following tasks:

* Detect unused references (Footnotes in Vancouver style)
* Order references by first appearance
* Remove unused references
* Count words in Markdown files, excluding code blocks, footnotes and urls.

## Installation

You can install OAT Tools using `uv`:

```bash
uv tool install oat-tools
```

The output will some something like this:

```
Resolved 3 packages in 1ms
Installed 3 packages in 3ms
 + click==8.2.1
 + oat-tools==1.0.0
 + tabulate==0.9.0
Installed 1 executable: oat
```

From now on, you can use the `oat` command in your terminal to run the tool.

### Update

You can update the tool using `uv`:

```bash
uv tool update oat-tools
```

## Usage

### Autocompletion

OAT Tools supports shell autocompletion for `bash`, `zsh` and `fish`, as this support is provided by the underlying `click` library. To enable autocompletion, run the following command for your shell, or add it to your shell configuration file:

```bash
# For zsh (or add to ~/.zshrc)
eval "$(_OAT_COMPLETE=zsh_source oat)"

# For bash (or add to ~/.bashrc)
eval "$(_OAT_COMPLETE=bash_source oat)"
```

### References

To detect unused references, order them by first appearance, and remove unused references, you can use the following command:

```bash
# Abstract
oat references [check|fix] <FILE...>

# Concrete example (check diary, another and all Markdown files in docs directory)
oat references check diary.md another.md docs/**/*.md

# Concrete example (fix the same files)
oat references fix diary.md another.md docs/**/*.md
```

Where `<FILE...>` is any number or Markdown files you want to process. You can use wildcards since your shell will expand them. Note that the `--fix` option will modify the files in place, so use it with caution. It is recommended to run the command without `--fix` first to see what changes will be made. Any unused references will be REMOVED, which is a destructive operation. It is recommended to run these commands after a Git commit, so you can easily revert the changes if needed, and can also review the changes using various diff tools.

Terminology used in this tool:

* **appearance**: Means that the `[^ref]` is used in the body text.
* **reference**: Means that the `[^ref]:` is defined in the footnotes section.
* **unused**: The `[^ref]:` is defined in the footnotes section, but has no appearance in the body text.
* **orphan**: Opposite situation. The `[^ref]` is used in the body text without a corresponding `[^ref]:`.

### Word Count

To count words in Markdown files, excluding code blocks, footnotes, and URLs, you can use the following command:

```bash
# Abstract
oat wordcount <FILE...>

# Concrete example
oat wordcount diary.md another.md docs/**/*.md
```

Where `<FILE...>` is any number of Markdown files you want to process. Again, you can use wildcards.

### Captions

To check and fix caption numbering in Markdown files, you can use the following command:

```bash
# Abstract
oat captions [check|fix] <FILE...>

# Concrete example (check captions in all Markdown files in docs directory)
oat captions check docs/**/*.md

# Concrete example (fix caption numbering in the same files)
oat captions fix docs/**/*.md
```

Where `<FILE...>` is any number of Markdown files you want to process. You can use wildcards since your shell will expand them.

The captions feature ensures that image captions are numbered sequentially starting from 1. Captions must follow this exact format:

```plaintext
**Kuva #:** Caption text goes here as a one-liner.
```

The `check` command will report any captions that are not in the correct numerical order, showing which files need attention. The `fix` command will renumber all captions sequentially, starting from 1, in the order they appear in the file. It will also report a common caption formatting issue where the colon is placed outside the bolding, e.g., `**Kuva 1**: Caption text...`. Example outputs:

```bash-console
$ oat captions check TESTER.md
⚠️  WARNING: Malformed captions detected (colon outside bolding):
file_path:line    content
----------------  ----------------------------------------
TESTER.md:3       **Kuva 2**: Colon on wrong side of bold.


⚠️  WARNING: Caption numbering issues:
file_path:line      current  caption
----------------  ---------  -----------------------------------------------------
TESTER.md:5               3  I am wrong because 2 is malformed. Also, the trunc...
TESTER.md:11              4  Duplicate part B.
TESTER.md:13             42  Off-by-thirtysomething index
```

**Note**: The `fix` option will modify the files in place, so use it with caution. It is recommended to run the `check` command first to see what changes will be made. As with other commands, it's best to run these after a Git commit so you can easily review and revert changes if needed.