ser1.net/tjot

tjot

A colorize djot terminal pager.

|----------------------|----------------------|----------------------|----------------------| | | | Releases | | | | Changelog | Credits | Mailing List | | | Issues | | Software metrics | | | | | | | | | | |

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 for a list.

• Features
• Usage
• Install
• To-do & known bugs are at the end of the Changelog
• Other solutions

Features

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

$ tjot my_document.dj
$ <my_document.dj tjot

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

Install

• Download one of the pre-built binaries from the Releases page.

• If you have Go installed, run go install ser1.net/tjot@latest. Make sure you have $(go env GOPATH)/bin in your ${PATH}.

• Clone the repository, build it, and copy the binary into your ${PATH}

  $ hg clone ser1.net/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

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

Benchmark history

• goos: linux
• goarch: amd64
• pkg: ser1.net/tjot/term
• cpu: AMD Ryzen 7 5800H with Radeon Graphics

: v0.0.5:

BenchmarkRenderer-16                1114           1087711 ns/op