Improve config file documentation

README.md

@@ -218,11 +218,11 @@ Playing from IPFS:
 Available options:
 
 * `-i, --idle-time-limit=<sec>` - Limit replayed terminal inactivity to max `<sec>` seconds
-* `-s, --speed=<factor>` - Playback speedup (can be fractional)
+* `-s, --speed=<factor>` - Playback speed (can be fractional)
 
-NOTE: it is recommended to run `asciinema play` in a terminal of dimensions not
+> For the best playback experience it is recommended to run `asciinema play` in
-smaller than the one used for recording as there's no "transcoding" of control
+> a terminal of dimensions not smaller than the one used for recording, as
-sequences for new terminal size.
+> there's no "transcoding" of control sequences for new terminal size.
 
 ### `cat <filename>`
 
@@ -291,41 +291,66 @@ saved in the file (unless the file already exists or you have set
 
 The auto-generated, minimal config file looks like this:
 
-    [api]
+```ini
-    token = <your-api-token-here>
+[api]
+token = <your-api-token-here>
+```
 
 There are several options you can set in this file. Here's a config with all
 available options set:
 
-    [api]
+```ini
-    token = <your-api-token-here>
+[api]
-    url = https://asciinema.example.com
 
-    [record]
+; API server URL, default: https://asciinema.org
-    command = /bin/bash -l
+url = https://asciinema.example.com
-    stdin = no
-    env = SHELL,TERM,USER
-    idle_time_limit = 2
-    yes = true
-    quiet = true
 
-    [play]
+; API token, autogenerated when uploading a recording for the first time
-    idle_time_limit = 1
+token = <your-api-token-here>
+
+[record]
+
+; command to record, default: $SHELL
+command = /bin/bash -l
+
+; enable stdin (keyboard) recording, default: no
+stdin = yes
+
+; list of environment variables to capture, default: SHELL,TERM
+env = SHELL,TERM,USER
+
+; limit recorded terminal inactivity to max n seconds, default: off
+idle_time_limit = 2
+
+; answer "yes" to all interactive prompts, default: no
+yes = true
+
+; be quiet, suppress all notices/warnings, default: no
+quiet = true
+
+[play]
+
+; playback speed (can be fractional), default: 1
+speed = 2
+
+; limit replayed terminal inactivity to max n seconds, default: off
+idle_time_limit = 1
+```
 
 The options in `[api]` section are related to API location and authentication.
-To tell asciinema recorder to use your own asciinema site instance rather than
+To tell asciinema recorder to use your own asciinema server instance rather than
 the default one (asciinema.org), you can set `url` option. API URL can also be
-passed via `ASCIINEMA_API_URL` environment variable, as well as API token, via
+passed via `ASCIINEMA_API_URL` environment variable, and API token via
 `ASCIINEMA_API_TOKEN` environment variable.
 
 The options in `[record]` and `[play]` sections have the same meaning as the
 options you pass to `asciinema rec`/`asciinema play` command. If you happen to
-often use either `-c`, `-w` or `-y` with these commands then consider saving it
+often use either `-c`, `-i` or `-y` with these commands then consider saving it
 as a default in the config file.
 
-*NOTE: If you want to publish your asciinema config file (in public dotfiles
+> If you want to publish your asciinema config file (in public dotfiles
-repository) you __should__ remove `token = ...` line from the file and use
+> repository) you __should__ remove `token = ...` line from the file and use
-`ASCIINEMA_API_TOKEN` environment variable instead.*
+> `ASCIINEMA_API_TOKEN` environment variable instead.
 
 ### Configuration file locations