Add better "Usage" doc page

app/views/docs/_docs_topics.html.slim

@@ -4,6 +4,6 @@ h2 Docs
   = categories.link_to 'How it works', docs_path('how-it-works'), :'how-it-works'
   = categories.link_to 'Getting started', docs_path('getting-started'), :'getting-started'
   = categories.link_to 'Installation', docs_path(:installation), :installation
-  = categories.link_to 'Recorder options', docs_path(:options), :options
+  = categories.link_to 'Usage', docs_path(:usage), :usage
   = categories.link_to 'Embedding', docs_path(:embedding), :embedding
   = categories.link_to 'FAQ', docs_path(:faq), :faq

app/views/docs/getting-started.html.slim

@@ -11,18 +11,20 @@ markdown:
 
   Go to your terminal and run the following command:
 
-      $ asciinema rec
+      asciinema rec
 
   New shell will be spawned and everything you do in it will get recorded.
   When you're finished simply exit the shell either by typing `exit`
   or hitting `<C-d>`.
 
+  See [usage instructions](#{docs_path(:usage)}) to learn about all commands and options.
+
   ## 3. Create your profile (optional)
 
   If you want your recordings to be assigned to your asciinema profile run the
   following command:
 
-      $ asciinema auth
+      asciinema auth
 
   If you skip this step now, you can run the above command later and all
   previously recorded asciicasts will automatically get assigned to your
@@ -30,5 +32,3 @@ markdown:
 
   NOTE: To be able to edit/delete your recordings you have to assign them to
   your profile.
-
-  Btw, see <a href="/~sickill">sickill's profile</a>.

app/views/docs/options.html.slim

@@ -1,23 +0,0 @@
-- content_for(:title, 'Recorder options')
-
-markdown:
-
-  # Recorder options
-
-  See the list of available options with:
-
-      $ asciinema -h
-      usage: asciinema [-h] [-y] [-c <command>] [-t <title>] [action]
-
-      Asciicast recorder+uploader.
-
-      Actions:
-      rec              record asciicast (this is the default when no action given)
-      auth             authenticate and/or claim recorded asciicasts
-
-      Optional arguments:
-      -c command       run specified command instead of shell ($SHELL)
-      -t title         specify title of recorded asciicast
-      -y               don't prompt for confirmation
-      -h, --help       show this help message and exit
-      -v, --version    show version information

app/views/docs/usage.html.slim

@@ -0,0 +1,61 @@
+- content_for(:title, 'Usage')
+
+markdown:
+
+  # Usage
+
+  asciinema cli is composed of multiple (sub)commands, similar to `git`,
+  `rails` or `brew`.
+
+  If you run `asciinema` with no arguments, help will be displayed showing all
+  available commands.
+
+  In addition to this, you can run any asciinema command with the `-h` switch
+  to display help about that specific command. For example, try running
+  `asciinema rec -h`. This will display a list of all of the options `rec`
+  command accepts, with their defaults.
+
+  ## `rec`
+
+  __Record terminal session and upload it to asciinema.org site.__
+
+  This is the single most important command in asciinema, since it is how you
+  utilize this tool's main job.
+
+  By running `asciinema rec` you start a new recording session. The command
+  (process) that is recorded can be specified with `-c` option (see below), and
+  defaults to `$SHELL` which is what you want in most cases.
+
+  Recording finishes when you exit the shell (hit <kbd>Ctrl+D</kbd> or type
+  `exit`). If the recorded process is not a shell than recording finishes when
+  the process exits.
+
+  `ASCIINEMA_REC=1` is added to recorded process environment variables. This
+  can be used by your shell's config file (`.bashrc`, `.zshrc`) to alter the
+  prompt or play a sound when shell is being recorded.
+
+  Available options:
+
+  * `-c` - command to record (if none given a new shell instance is recorded)
+  * `--max-wait` - reduce recorded terminal inactivity to maximum of <max-wait> seconds (0 turns off)
+  * `-t` - set asciicast title (can be also set later, on the site)
+  * `-y` - upload immediately after shell exits, without asking for confirmation
+
+  ## `auth`
+
+  __Assign local API token to asciinema.org account.__
+
+  Every machine you install asciinema recorder on you get a new unique API
+  token. This command is used to connect this local API token with your
+  asciinema.org account.
+
+  This command displays the URL you should open in your web browser. If you
+  never logged in to asciinema.org then your account will be automatically
+  created when opening the URL.
+
+  NOTE: it is __necessary__ to do this if you want to __edit or delete__ your
+  recordings on asciinema.org.
+
+  You can synchronize your `~/.asciinema/config` file (which keeps the API
+  token) across the machines but that's not necessary. You can assign new
+  tokens to your account from as many machines as you want.