Better structure of v2 doc

doc/asciicast-v2.md

@@ -4,78 +4,89 @@ asciicast v2 file
 is [NDJSON (newline delimited JSON)](https://github.com/ndjson/ndjson-spec) file
 where:
 
-* __first line__ contains meta-data (duration, terminal size etc), encoded as JSON
+* __first line__ contains meta-data (duration, initial terminal size, etc),
-  object,
+  encoded as JSON object,
-* __all subsequent lines__ contain stream data, _each line_ representing single stream
+* __all subsequent lines__ form an event stream, _each line_ representing a
-  element (event), encoded as JSON array.
+  separate event stream item.
 
 ## Meta-data
 
-Every asciicast v2 includes the following meta-data:
+The following meta-data is **required** in asciicast v2:
 
 * `version` - set to 2,
-* `width` - terminal width (number of columns),
+* `width` - initial terminal width (number of columns),
-* `height` - terminal height (number of rows),
+* `height` - initial terminal height (number of rows).
-* `duration` - total duration of asciicast as floating point number,
+
-* `command` - command that was recorded, as given via `-c` option to `rec`,
+The following meta-data is **optional** in asciicast v2:
-* `title` - title of the asciicast, as given via `-t` option to `rec`,
+
+* `command` - command that was recorded, as given via `-c` option to `asciinema rec`,
+* `title` - title of the asciicast, as given via `-t` option to `asciinema rec`,
 * `env` - map of environment variables useful for debugging playback problems.
 
 Example meta-data line:
 
-    { "version": 2, "width": 80, "height": 24, "duration": 1.515658, "command": "/bin/zsh", "title": null, "env": { "TERM": "xterm-256color", "SHELL": "/bin/zsh" } }
+    { "version": 2, "width": 80, "height": 24, "command": "/bin/zsh", "title": null, "env": { "TERM": "xterm-256color", "SHELL": "/bin/zsh" } }
 
-## Stream data
+## Event stream
 
-Every stream element is a 3-tuple encoded as JSON array:
+Each element of the event stream is a 3-tuple encoded as JSON array:
 
     [ time, event-type, event-data ]
 
 Where:
 
-* `time` (number) - relative time (in seconds) since the previous event (or
+* `time` (number) - relative time (in seconds) since the previous event occured
-  since the beginning of the recording session when it's the first event in the
+  (or since the beginning of the recording session for the first event in the
-  stream)
+  stream),
-* `event-type` (string) - one of: "o", "i", "size"
+* `event-type` (string) - one of: `"o"`, `"i"`, `"size"`,
 * `event-data` (any) - event specific data, described separately for each event
-  type
+  type.
 
 For example, let's look at the following line:
 
     [ 1.001376, "o", "Hello world" ]
 
-It represents an event of printing text "Hello world" to stdout ("o" event type,
+It represents the event which:
-see below), which happened 1.001376 sec after a previous event in the stream.
 
-### Supported (planned) event types
+* happened 1.001376 sec after a previous event in the stream,
+* is of type `"o"` (print to stdout, see below),
+* has data `"Hello world"`.
+
+### Supported event types
+
+This section describes the event types supported in asciicast v2 format.
+
+The list is open to extension, and new event types may be added in both the
+current and future versions of the format. For example, we may add new event
+type for text overlay (subtitles display).
+
+A tool which interprets the event stream (web/cli player, post-processor) should
+ignore event types it doesn't understand or doesn't care about. However, it
+should honor the amount of time specified by such stream item (by pausing for
+this amount of time when playing back) in order to keep the subsequent events on
+the timeline.
 
 #### "o" - output, printing to stdout
 
-TODO: change this section to reflect new structure
+Event of type `"o"` represents printing new data to terminal's stdout.
 
-Frame represents an event of printing new data to terminal's stdout. It is a 2
+`event-data` is a string containing the data that was printed to a terminal. It
-element array containing **delay** and **data**.
+has to be valid, UTF-8 encoded JSON string as described
-
+in [JSON RFC section 2.5](http://www.ietf.org/rfc/rfc4627.txt), with all
-**Delay** is the number of seconds that elapsed since the previous frame (or
-since the beginning of the recording in case of the 1st frame) represented as
-a floating point number, with microsecond precision.
-
-**Data** is a string containing the data that was printed to a terminal in a
-given frame. It has to be valid, UTF-8 encoded JSON string as described in
-[JSON RFC section 2.5](http://www.ietf.org/rfc/rfc4627.txt), with all
 non-printable Unicode codepoints encoded as `\uXXXX`.
 
-For example, frame `[5.4321, "foo\rbar\u0007..."]` means there was 5 seconds of
+#### "i" - input, from keyboard (planned?)
-inactivity between previous printing and printing of `foo\rbar\u0007...`.
-
-#### "i" - input, from keyboard
 
 TODO
 
-#### "size" - terminal resize
+not supported by current versions of the recorder and players
+
+#### "size" - terminal resize (planned?)
 
 TODO
 
+not supported by current versions of the recorder and players
+
 ## Complete asciicast v2 example
 
 A very short asciicast v2 file looks like this:
@@ -85,3 +96,6 @@ A very short asciicast v2 file looks like this:
     [ 1.001376, "o", "This is overwritten\rThis is better." ]
     [ 0.143733, "o", " " ]
     [ 0.541828, "o", "Bye!" ]
+
+The final `"Bye!"` was printed to a terminal after 1.935785 sec (0.248848 +
+1.001376 + 0.143733 + 0.541828).