[0.1 draft] [guide 15 · spec 15 pages]

guide

Text Tables — the guide

Plain text tables that describe themselves. These pages are for anyone who works with tables — analysts, data engineers, anyone who opens a .csv and wishes it came with a note explaining what's inside. They cover what you can put in a file, what it means, and why it's worth it.

Topic What it gives you
Introduction The idea in two minutes: context that travels with the data
File structure How a file is laid out: first line, blocks, tables; choosing a prefix
First line The one line that names the format and the dialect
System lines A map of every keyword so you know what you're looking at
Tables One table or several; data inline, in a CSV next door, or column by column
Metadata (meta-*) Source, author, grain, as-of date, license
Columns (column) Types, units and money, allowed values, roles, relations, computed columns
Aggregates (agg-*) Totals and counts that ride along — trustworthy without scanning
SQL (sql-*) Ship the CREATE TABLE, the keys and the query with the data
Notes and links Leave a remark on a cell, row, column or file; turn values into links
Charts (chart) Suggest a bar, line or pie over columns you've described
Archives (.txtab.zip) Zip it, preview the schema without unzipping, store wide tables by column
Full example One file showing most features at once
Prior art Where the ideas come from, and how Text Tables compares

Building a tool, parser or validator? The precise rules — required fields, edge cases, the error-code registry — are in ../spec/. This guide leaves them out so it stays readable; the spec wins when the two differ.

guide/README.md on GitHub