tessella 0.3.0

data/doc/README.md

@@ -0,0 +1,74 @@
+# tessella documentation
+
+tessella draws text figures on a monospace grid, in Unicode or pure
+ASCII: charts, trees, tables, bit-field, timing and sequence
+diagrams, and pictures, all of which compose into one figure. Its
+output is meant for documents first: no trailing blank, no escape
+code unless asked, ASCII from the first byte when asked.
+
+```text
+$ ruby datasheet.rb
+           CTRL (0x04)
+
+ 0                   1
+ 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5
++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+| MODE  |      DIV      |  EN   |
++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+
+─────────────────────────────────────
+
+     ──┐ ┌─┐ ┌─┐ ┌─┐ ┌─┐ ┌─┐ ┌─┐ ┌─┐
+sclk   └─┘ └─┘ └─┘ └─┘ └─┘ └─┘ └─┘ └─
+
+     ────┐                       ┌───
+cs       └───────────────────────┘
+
+     ▒▒▒▒╳       ╳       ╳       ▒▒▒▒
+mosi ▒▒▒▒╳──CMD──╳─ADDR──╳─DATA──▒▒▒▒
+```
+
+## Guide
+
+1. [Getting started](getting-started.md): install, a first chart, a
+   first diagram, the library.
+2. [Charts](charts.md): line, scatter, stairs, density, bar,
+   histogram, box, stem, heatmap, candlestick and pie; input formats,
+   options, canvases, colour, ASCII.
+3. [Composition](composition.md): blocks; frame, beside, stack, grid,
+   indent, caption, shadow, fill.
+4. Diagrams: [trees](tree.md), [tables](table.md),
+   [bit fields](bitfield.md), [timing diagrams](wave.md),
+   [sequence diagrams](seq.md).
+5. [Pictures](images.md): images as text.
+6. One-liners: [sparklines](sparkline.md), charts one line high;
+   [meters](meter.md), progress bars and gauges;
+   [rules](rule.md), dividers; [text styles](text.md), Unicode's
+   styled alphabets.
+7. [Linting](lint.md): checking a figure, drawn or hand-made, for
+   what breaks it on someone else's screen.
+8. [Glyph sets](glyphs.md): width classes, the named glyph sets, and
+   checking a set of one's own.
+9. [Width targets](targets.md): drawing for a Western terminal, a CJK
+   one, or a browser.
+
+## Reference
+
+- [The `tessella` command](cli.md): every command and option, exit
+  statuses, pipelines.
+- [The library](library.md): every factory, `Block`, `Raster`,
+  `Width`, errors, the output rules, vendoring.
+- [DESIGN.md](../DESIGN.md): the internal interfaces, and why the
+  project is shaped as it is.
+
+## Examples
+
+Every figure in these pages is real output. The input files and the
+Ruby scripts are in [examples/](../examples/); each `$` command runs
+in that directory. `doc/check.rb` re-runs every one of them and
+compares the output byte for byte:
+
+```sh
+ruby doc/check.rb            # report any figure that changed
+ruby doc/check.rb --update   # rewrite the pages from what runs now
+```

data/doc/bitfield.md

@@ -0,0 +1,123 @@
+# Bit fields
+
+`bitfield` draws a packet header or a register as RFC 2360 draws one:
+a bit ruler, `+-+` ticks, one row per word, each field's name centred
+in its cell. It is always ASCII, as the genre is.
+
+```ruby
+Tessella.bitfield(fields, word: 32, octets: false, ruler: true,
+                  abbrev: false)                       # => Block
+```
+
+```text
+tessella bitfield [--word N] [--octets] [--no-ruler] [--abbrev]
+                  [--max-width N] [file]
+```
+
+## Input
+
+One field per line, `name:bits`, in order from the most significant
+bit; or, in Ruby, an Array of `[name, bits]` pairs.
+
+```text
+$ cat ipv4.txt
+Version:4
+IHL:4
+DSCP:6
+ECN:2
+Total Length:16
+Identification:16
+Flags:3
+Fragment Offset:13
+TTL:8
+Protocol:8
+Header Checksum:16
+Source Address:32
+```
+
+```text
+$ tessella bitfield ipv4.txt
+ 0                   1                   2                   3
+ 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+|Version|  IHL  |   DSCP    |ECN|         Total Length          |
++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+|        Identification         |Flags|     Fragment Offset     |
++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+|      TTL      |   Protocol    |        Header Checksum        |
++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+|                        Source Address                         |
++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+```
+
+A field longer than what is left of its row continues on the next,
+as an Ethernet header's addresses do:
+
+```text
+$ tessella bitfield ethernet.txt
+ 0                   1                   2                   3
+ 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+|                        Destination MAC                        |
++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+|        Destination MAC        |          Source MAC           |
++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+|                          Source MAC                           |
++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+|           EtherType           |
++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+```
+
+## Options
+
+- `--word N` (`word:`): bits per row, 8, 16, 32 (the default) or 64.
+- `--octets`: byte-oriented, one tick per octet instead of per bit,
+  and no bit ruler.
+- `--no-ruler` (`ruler: false`): drop the two ruler rows.
+- `--abbrev`: truncate a name too wide for its cell, instead of
+  refusing it.
+- `--ascii` is accepted and changes nothing.
+
+```text
+$ tessella bitfield --word 16 --octets icmp.txt
++---------------+---------------+
+|     Type      |     Code      |
++---------------+---------------+
+|           Checksum            |
++---------------+---------------+
+```
+
+```text
+$ tessella bitfield --no-ruler icmp.txt
++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+|     Type      |     Code      |           Checksum            |
++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+```
+
+A bit is two columns wide, so a 1-bit field has room for one
+character and a 4-bit field for seven:
+
+```text
+$ printf 'Destination:4\nx:4\n' | tessella bitfield --word 8
+tessella bitfield: name "Destination" needs 11 columns, this cell only has 7
+```
+
+```text
+$ printf 'Destination:4\nx:4\n' | tessella bitfield --word 8 --abbrev
+ 0
+ 0 1 2 3 4 5 6 7
++-+-+-+-+-+-+-+-+
+|Destin.|   x   |
++-+-+-+-+-+-+-+-+
+```
+
+## Errors
+
+A line that is not `name:bits`, a field of zero bits, a name too wide
+without `--abbrev`, a name that is not ASCII, or an output wider than `--max-width` exits 1,
+naming the line. An unsupported `--word` exits 2.
+
+```text
+$ printf 'Type:8\nCode\n' | tessella bitfield
+tessella bitfield: line 2: "Code" not name:bits
+```