Document breakpoints

README.md

@@ -296,6 +296,7 @@ Available options:
 - `-i, --idle-time-limit=<sec>` - Limit replayed terminal inactivity to max `<sec>` seconds
 - `-s, --speed=<factor>` - Playback speed (can be fractional)
 - `-l, --loop` - Play in a loop
+- `-b, --breakpoints` - Automatically pause on [breakpoints](#breakpoints)
 - `--stream=<stream>` - Select stream to play (see below)
 - `--out-fmt=<format>` - Select output format (see below)
 
@@ -361,6 +362,29 @@ happen in any order.
 > asciinema versions prior to 2.0 confusingly referred to install ID as "API
 > token".
 
+## Breakpoints
+
+Breakpoints are markers that you can set in a recording to pause the playback at
+a specific point.
+
+When a breakpoint is reached, the playback automatically pauses and can be
+resumed by pressing space bar key. The playback continues until next breakpoint
+is encountered.
+
+To enable auto-pause-on-breakpoint behaviour when replaying with `asciinema
+play` use `-b`/`--breakpoints` option. It's off by default.
+
+Breakpoints can be added to a recording in several ways:
+
+- during recording session, by pressing a configured hotkey, see
+  [add_breakpoint_key config option](#configuration-file)
+- for existing recording, by inserting breakpoint events (`"b"`) in the
+  asciicast file, see [breakpoint event](doc/asciicast-v2.md#b---breakpoint)
+
+Breakpoints can be useful in e.g. live demos: you can create a recording with
+breakpoints, then play it back during presentation, and have it stop wherever
+you want to explain terminal contents in more detail.
+
 ## Hosting the recordings on the web
 
 As mentioned in the `Usage > rec` section above, if the `filename` argument to
@@ -419,7 +443,7 @@ quiet = true
 ; default: C-\ (control + backslash)
 pause_key = C-p
 
-; Define hotkey for adding a breakpoint, default: None
+; Define hotkey for adding a breakpoint, default: none
 add_breakpoint_key = C-b
 
 ; Define hotkey prefix key - when defined other recording hotkeys must