Writing the specification document

The table is normative; the picture is not

A state diagram is the best way to understand a protocol and the worst way to specify one. It is easy to draw an arrow you never implement, and easy to forget an arrow you do. A transition table cannot hide either mistake, because it has a row per (state, event) pair and an empty cell is visibly empty.

So write the table first and treat it as normative — the sentence 'where this document and the diagram disagree, the table governs' belongs in your specification. Then draw the diagram from the table, mechanically, one arrow per row. If the drawing needs an arrow the table does not have, the table was incomplete; fix the table, not the picture.

One row per (state, event) — including the rows you did not want

Enumerate the events that can reach each state, not the ones you hope for. In a state that accepts three legal inputs you owe four rows: the three, plus the catch-all. The full event vocabulary for a line-based protocol is small and always the same:

• a line that satisfies the grammar,
• a line that is syntactically wrong (not a number, empty),
• a line that is syntactically right but semantically wrong (a number outside the range),
• end-of-stream, because the client closed or dropped,
• the idle timeout expiring.

The last two are the ones that get forgotten, and they are the two a marker can trigger by accident. Give every one of them a row, an action, and a next state. If the answer is 'do nothing and close', write that down — 'nothing' is a specified action; an empty cell is not.

The sections around the table

The table is the core, but a marker needs to find the rest. A workable outline, in order:

1. Scope and purpose — one paragraph. What the protocol is for, who talks first.
2. Transport and port — TCP, the port number, and a note that it is unregistered.
3. Framing and encoding — CRLF terminated, US-ASCII, maximum line length.
4. Message grammar — per direction, in a notation, not prose.
5. State model — the state list with one sentence each, then the transition table, then the diagram.
6. Error catalogue — every error line the server can emit, with its trigger.
7. Example session — a complete, literal transcript, CRLFs shown.
8. Versioning — how a future version announces itself, even if the answer is 'this version does not'.

Worked example — the PoD transition table

Seven rows cover the whole protocol. CONNECTED has one event and one exit. LISTED has four rows because it is the only state that waits for input: the good line, the out-of-range number, the non-number, and the dropped connection. SENT and REJECTED each have one immediate transition to CLOSED — no event required, which the table records as (immediate) rather than leaving blank.

Count the rows against the diagram in the previous lesson and you get five arrows plus two disconnect rows. That arithmetic — table rows in, diagram arrows out, differences explained — is the check a marker runs, and it is the check you should run on yourself before you submit.