From 226249db062618b6594c2f82dce018813127c84e Mon Sep 17 00:00:00 2001
From: Marcin Kulik <m@ku1ik.com>
Date: Sun, 19 Nov 2017 18:29:50 +0100
Subject: [PATCH] Improve config file documentation

---
 README.md | 73 +++++++++++++++++++++++++++++++++++++------------------
 1 file changed, 49 insertions(+), 24 deletions(-)

diff --git a/README.md b/README.md
index 59ff3e8..f869bcd 100644
--- a/README.md
+++ b/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
-smaller than the one used for recording as there's no "transcoding" of control
-sequences for new terminal size.
+> For the best playback experience it is recommended to run `asciinema play` in
+> a terminal of dimensions not smaller than the one used for recording, as
+> 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]
-    token = <your-api-token-here>
+```ini
+[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]
-    token = <your-api-token-here>
-    url = https://asciinema.example.com
+```ini
+[api]
 
-    [record]
-    command = /bin/bash -l
-    stdin = no
-    env = SHELL,TERM,USER
-    idle_time_limit = 2
-    yes = true
-    quiet = true
+; API server URL, default: https://asciinema.org
+url = https://asciinema.example.com
 
-    [play]
-    idle_time_limit = 1
+; API token, autogenerated when uploading a recording for the first time
+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
-repository) you __should__ remove `token = ...` line from the file and use
-`ASCIINEMA_API_TOKEN` environment variable instead.*
+> If you want to publish your asciinema config file (in public dotfiles
+> repository) you __should__ remove `token = ...` line from the file and use
+> `ASCIINEMA_API_TOKEN` environment variable instead.
 
 ### Configuration file locations