oat-tools 1.1.3

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).

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:

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:

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:

# 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:

# 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:

# 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:

# 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:

**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:

$ 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.