# tjot

A colorize [djot](https://djot.net) terminal pager.

[![Build status](https://builds.sr.ht/~ser/tjot/.build.yml.svg)](https://builds.sr.ht/~ser/tjot/.build.yml?)
★ [Releases](https://downloads.ser1.net/software/tjot/)
★ ![Latest release](https://downloads.ser1.net/software/tjot/badges/latest_release.svg)  
[![License](https://downloads.ser1.net/software/tjot/badges/license.svg)](https://hg.sr.ht/~ser/tjot/raw/LICENSE?rev=tip)
★ [Changelog](https://hg.sr.ht/~ser/tjot/browse/CHANGELOG.md?rev=tip)
★ [Software metrics](https://downloads.ser1.net/software/tjot/badges/METRICS.md)
★ [Issues](https://todo.sr.ht/~ser/tjot)
★ [Mailing List](https://lists.sr.ht/~ser/tjot)
★ [Credits](https://hg.sr.ht/~ser/tjot/browse/CREDITS.md?rev=tip)  
[![Go Report Card](https://goreportcard.com/badge/ser1.net/tjot)](https://goreportcard.com/report/ser1.net/tjot)
★ ![Code linting](https://downloads.ser1.net/software/tjot/badges/linting.svg)
★ ![Code security](https://downloads.ser1.net/software/tjot/badges/vulnerabilities.svg)
★ ![Markdown linting](https://downloads.ser1.net/software/tjot/badges/doc_linting.svg)
★ ![Unit tests](https://downloads.ser1.net/software/tjot/badges/unit_tests.svg)  
![Code coverage](https://downloads.ser1.net/software/tjot/badges/coverage.svg)
★ ![Code complexity](https://downloads.ser1.net/software/tjot/badges/complexity.svg)
★ ![ABC metrics](https://downloads.ser1.net/software/tjot/badges/abc_score.svg)
★ ![Lines of code](https://downloads.ser1.net/software/tjot/badges/loc.svg)

A terminal pager for djot documents. The project is considered alpha-quality:
there are known bugs and many missing features. See the end of the
[changelog](https://hg.sr.ht/~ser/tjot/browse/CHANGELOG.md?rev=tip) for a list.

- [Features](#features)
- [Usage](#usage)
- [Install](#install)
- [To-do & known bugs](https://hg.sr.ht/~ser/tjot/browse/CHANGELOG.md#todo?rev=tip)
- [Other solutions](#other-solutions)

## Features

![](https://hg.sr.ht/~ser/tjot/raw/screen.png?rev=tip)

- Covers 100% of the Djot spec
- Reasonably fast:

  - `pandoc -f djot -t ansi`: 10 runs, milliseconds: [266, σ 270, 274]
  - `tjot`: 105 runs, [24, σ 26, 28]

- ANSI glyphs & escape codes for nice tables, task lists, and coloring
- Renders images, including SVGs
- Detects the terminal size (usually) for accurate wrapping
- Langage-sensitive highlighting for code blocks, and language detection

### Limitations & Caveats

It's not really a pager yet; you have to dump the output to less.

There's no configuration yet. Eventually you'll be able to disable image
fetching, image rendering, image rastering methods, and swap colors around, but
this is TBI.

There's only so much magic you can do in a terminal. Super and subscripts are
supported iff the terminal supports UTF-8 characters and is using a font with
those code points. Even so, Unicode does not support all characters as offset
scripts, so the things you can do with these are limited. To print a list of
supported super and subscripts, run `tjot -s`. Add `-v` to see the glyphs in
your terminal, and check that they're mapped correctly. If they aren't, there's
not much you can do about it except change your terminal font or skip the wrong
ones.

Because there are no pages, footnotes are rendered as endnotes.

See the end of the [changelog](CHANGELOG.md) for other known bugs and
limitations.

If tjot seems slow at times, check if your document contains embedded, remote
images. tjot tries to fetch and render these; for example, the top table in
`tests/README.dj` pauses at the start because it's downloading 11 badges. tjot
does no image caching (yet), and so this image fetching happens every time you
run tjot.

## Usage

`tjot -h` will give you usage.

Either provide a file path to the program, or pipe the content to it.

```sh
$ tjot my_document.dj
$ <my_document.dj tjot
```

For now, you'll probably want to pipe the result to a pager.

## Install

1. Download one of the pre-built binaries from the
   [releases](https://downloads.ser1.net/software/tjot/) page.
2. If you have Go installed, run `go install ser1.net/tjot@latest`. Make sure
   you have `$(go env GOPATH)/bin` in your `${PATH}`.
3. Clone the repository, build it, and copy the binary into your `${PATH}`

   ```sh
   $ hg clone hg.sr.ht/~ser/tjot
   $ cd tjot
   $ go build .
   $ cp tjot /usr/local/bin
   ```

tjot needs changes to the godjot library which have not yet been merged
upstream. For now there's a `replace` directive in the `go.mod`.

## Other solutions

```sh
pandoc -f djot -t ansi <file>.dj
```
