From an interface document to a dictionary

An interface control document (ICD) defines the messages two systems exchange, usually as hundreds of pages of word-and-bit tables. A first-bite dictionary holds the same definitions as JSON the decoder loads. This guide is the way from one to the other: what to read out of the document, the conventions that make two people's transcriptions come out the same, the bite commands that catch mistakes, and how to keep the dictionary right when the document is revised.

The path from an interface control document to a dictionary, as nine steps in order, each with what it produces and the bite command that does or checks it. 1 Scope: document, revision and handling, bite new --repo. 2 Inventory: every interface and message, messages.csv. 3 Numbering: word size, bit 0 and first word, bite range. 4 Transcribe: one row per field, bite import-csv. 5 Check: bite fmt, check, lint and coverage. 6 Vectors: the document's examples as test vectors, bite vectors new and encode. 7 Review: a second reader with the checklist, in a pull request. 8 Version: a version number the changes justify, bite diff --check-version. 9 Maintain: the next revision of the document, bite diff.

The path

StepWhat you doCommandPage
1. ScopeFix the document, its revision and the interfaces to transcribe. Read its distribution statement; the dictionary inherits it. Start the repository.bite new <dir> --repoconventions
2. InventoryList every interface and every message the document names, with its identifier, whether or not you will define it.messages.csvreading an ICD
3. NumberingEstablish the word size, which end of a word is bit 0, and whether words count from 0 or 1. Test it on a field whose value you know.bite rangereading an ICD
4. TranscribeEnter one row per field, with the word and bits exactly as printed.bite import-csvworkflow
5. CheckRun the four gates until they pass.bite fmt, bite check --strict, bite lint, bite coverage --strictworkflow
6. VectorsTurn the document's example messages into test vectors, one per message at least.bite vectors new, bite vectors encodevectors
7. ReviewA second person reads every field against the document.pull requestchecklists
8. VersionGive the dictionary a version the changes justify.bite diff --check-versionconventions
9. MaintainWhen the document is revised, transcribe the changes and compare.bite diffmaintaining

The worked example goes through all nine on a synthetic 12-page document, and retrace.sh runs it end to end and compares the result with dictionaries/glasshouse byte for byte.

Pages

PageCovers
01 Reading an ICDwhat to extract and where documents put it; bit numbering with worked conversions; signed encodings; scaling; enumerations; what the format cannot express
02 Conventionsnames, units, labels, descriptions, sources, versions, repository layout, handling; every bite lint and bite coverage rule
03 Transcription workflowthe working loop; the four CSV tables column by column; errata and ambiguities
04 Vectors and validationwhere expected values come from; building payloads; what a capture can and cannot tell you
05 Maintaininga new revision of the document; bite diff; deprecation; the changelog
06 Worked examplea synthetic document, its tables, the dictionary and the output of every step
Checkliststranscription, review, release

What catches what

A transcription passes seven gates before it is released, each narrower than the last. bite fmt --check catches two spellings of one definition and a key written twice. bite check --strict catches inverted and overlapping bit ranges and messages named but not defined. bite lint catches names, units, labels and sources that depart from the conventions. bite coverage --strict catches bits no field claims and fields with no source, description or unit. The vectors, run by bite check, catch a field at the wrong bits or with the wrong scale or sign, against the document's own examples. A second reader catches a value copied wrong that still decodes. bite diff --check-version catches a breaking change released under a minor version.
MistakeCaught by
The same definition written two ways; a field name used twice in a messagebite fmt --check
A bit range with stop before start; a field wider than its type allowsbite check (error)
Two fields sharing bits; a message named and not definedbite check --strict
Bits that belong to no field; a field past the message's stated lengthbite coverage --strict
A field with no source, description or unit; a message with no vectorbite coverage --strict
A name, unit or label off the conventions; a label on a reserved valuebite lint
The word and bits typed for a field disagreeing with its start and stopbite import-csv
A field at the wrong bits, or with the wrong scale, sign or byte ordera vector from the document's examples, run by bite check
A payload in the document that the field values do not account forbite vectors encode --vector
A value copied wrong that still decodes to something plausiblethe second reader
A field that never changes, or values outside an enumeration, in real trafficbite stats
A change that breaks consumers, released as a minor versionbite diff --check-version

Status

PartStatus
bite new, range, import-csv, export-csv, fmt, coverage, lint, diff, vectors new, vectors encode, statsbuilt; tests in bite/tests/authoring.rs and bite/tests/cli.rs
Worked examplemeasured: retrace.out is the output of retrace.sh
Repository template, tools/dictionary-repo-templatebuilt; its workflow has not run on GitHub, because no first-bite release carries these commands yet
PDF table extraction, tools/icd-extractbuilt for tables laid out like the worked example's; measured on its PDF
Repeated groups, conditional layouts, sign-magnitude and BCD fields in the dictionary formatnot built; what to do meanwhile

The source of this page is a Markdown file in the repository.