tbls/doc/Tutorial.md

Tutorial

At its most basic, tbls selects a random element from a table.

Suppose you have a few tables:

:: suit
Hearts
Bells
Whistles
Cups
Knives
Shovels

:: card
Ace
One
Two
...
Ten
Eleven
Twelve
Thief
Queen
King
Beast

tbls might return "Whistles" from suit. Or "Twelve" from card.

But wait there's more. tbls will also expand macros found in table entries.

Let's add another table:

:: draw
[card] of [suit]

When you place the name of a table in [squarebrackets], then tbls views that as a placeholder for a random item from that table. And it will expand the text. So this might end up being "Thief of Shovels" or "Twelve or Cups".