Improves quantize help, Updates readme

Author: Ciro S. Costa

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2018 Ciro da Silva da Costa
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -10,42 +10,128 @@
   <img width="100%" src="/.github/asciinema-edit-overview.svg" alt="Illustration of how ASCIINEMA-EDIT works" />
 </p>
 
+Three transformations have been implemented so far:
 
+- [`quantize`](#quantize): Updates the cast delays following quantization ranges; and
+- [`cut`](#cut): Removes a certain range of time frames;
+- [`speed`](#speed): Updates the cast speed by a certain factor.
 
+### Quantize
+
+```sh
+NAME:
+   asciinema-edit quantize - Updates the cast delays following quantization ranges.
+
+   The command acts on the delays between the frames, reducing such
+   timings to the lowest value defined in a given range that they
+   lie in.
+
+   For instance, consider the following timestamps:
+
+      1  2  5  9 10 11
+
+   Assuming that we quantize over [2,6), we'd cut any delays between 2 and
+   6 seconds to 2 second:
+
+      1  2  4  6  7  8
+
+   This can be more easily visualized by looking at the delay quantization:
+
+      delta = 1.000000 | qdelta = 1.000000
+      delta = 3.000000 | qdelta = 2.000000
+      delta = 4.000000 | qdelta = 2.000000
+      delta = 1.000000 | qdelta = 1.000000
+      delta = 1.000000 | qdelta = 1.000000
+
+   If no file name is specified as a positional argument, a cast is
+   expected to be serverd via stdin.
+
+   Once the transformation has been performed, the resulting cast is
+   either written to a file specified in the '--out' flag or to stdout
+   (default).
+
+EXAMPLES:
+   Make the whole cast have a maximum delay of 1s:
+
+     asciinema-edit quantize --range 2 ./123.cast
+
+   Make the whole cast have time delays between 300ms and 1s cut to
+   300ms, delays between 1s and 2s cut to 1s and any delays bigger
+   than 2s, cut down to 2s:
+
+     asciinema-edit quantize \
+       --range 0.3,1 \
+       --range 1,2 \
+       --range 2 \
+       ./123.cast
+
+USAGE:
+   asciinema-edit quantize [command options] [filename]
+
+OPTIONS:
+   --range value  quantization ranges (comma delimited)
+   --out value    file to write the modified contents to
+   
+```
+
+### Speed
+
+```sh
 NAME:
-   asciinema-edit - edit recorded asciinema casts
+   asciinema-edit speed - Updates the cast speed by a certain factor.
+
+   If no file name is specified as a positional argument, a cast is
+   expected to be serverd via stdin.
+
+   If no range is specified (start=0, end=0), the whole event stream
+   is processed.
+
+   Once the transformation has been performed, the resulting cast is
+   either written to a file specified in the '--out' flag or to stdout
+   (default).
+
+EXAMPLES:
+   Make the whole cast ("123.cast") twice as fast:
 
-INSTALL
-   Using `go`, fetch the latest from `master`
+     asciinema-edit speed --factor 2 ./123.cast
 
-     go get -u -v github.com/cirocosta/asciinema-edit
+   Cut the speed in half:
 
-   Retrieving from GitHub releases
+     asciinema-edit speed --factor 0.5 ./123.cast
 
-     VERSION=0.0.1
-     curl -SOL https://github.com/cirocosta/asciinema-edit/releases/download/$VERSION/asciinema-edit_$VERSION_linux_amd64.tar.gz
+   Make only a certain part of the video twice as fast:
+
+     asciinema-edit speed \
+        --factor 2 \
+        --start 12.231 \
+        --factor 45.333 \
+        ./123.cast
 
 USAGE:
-   asciinema-edit [global options] command [command options] [arguments...]
+   asciinema-edit speed [command options] [filename]
+
+OPTIONS:
+   --factor value  number by which delays are multiplied by (default: 0)
+   --start value   initial frame timestamp (default: 0)
+   --end value     final frame timestamp (default: 0)
+   --out value     file to write the modified contents to
+```
 
-VERSION:
-   dev
 
-DESCRIPTION:
-   asciinema-edit provides missing features from the "asciinema" tool
-   when it comes to editing a cast that has already been recorded.
+### Cut
 
-COMMANDS:
-     cut  Removes a certain range of time frames.
+```sh
+NAME:
+   asciinema-edit cut - Removes a certain range of time frames.
 
-   If no file name is specified as a positional argument a cast is
+   If no file name is specified as a positional argument, a cast is
    expected to be served via stdin.
 
    Once the transformation has been performed, the resulting cast is
    either written to a file specified in the '--out' flag or to stdout
    (default).
 
-EXAMPLES
+EXAMPLES:
    Remove frames from 12.2s to 16.3s from the cast passed in the commands
    stdin.
 
@@ -59,8 +145,26 @@ EXAMPLES
      asciinema-edit cut \
        --from=12.2 --to=12.2 \
        1234.cast
-     help, h  Shows a list of commands or help for one command
 
-GLOBAL OPTIONS:
-   --help, -h     show help
-   --version, -v  print the version
+USAGE:
+   asciinema-edit cut [command options] [filename]
+
+OPTIONS:
+   --start value  initial frame timestamp (required) (default: 0)
+   --end value    final frame timestamp (required) (default: 0)
+   --out value    file to write the modified contents to
+```
+
+
+### Installation
+
+Being a Golang application, you can either build it yourself with `go get` or fetch a specific version from the [Releases page](https://github.com/cirocosta/asciinema-edit/releases):
+
+```sh
+#Using `go`, fetch the latest from `master`
+go get -u -v github.com/cirocosta/asciinema-edit
+
+#Retrieving from GitHub releases
+VERSION=0.0.3
+curl -SOL https://github.com/cirocosta/asciinema-edit/releases/download/$VERSION/asciinema-edit_$VERSION_linux_amd64.tar.gz
+```

commands/quantize.go

@@ -15,13 +15,30 @@ var Quantize = cli.Command{
 	Name: "quantize",
 	Usage: `Updates the cast delays following quantization ranges.
 
-   If no file name is specified as a positional argument, a cast is
-   expected to be serverd via stdin.
-
    The command acts on the delays between the frames, reducing such
    timings to the lowest value defined in a given range that they
    lie in.
 
+   For instance, consider the following timestamps:
+
+      1  2  5  9 10 11
+
+   Assuming that we quantize over [2,6), we'd cut any delays between 2 and
+   6 seconds to 2 second:
+
+      1  2  4  6  7  8
+
+   This can be more easily visualized by looking at the delay quantization:
+
+      delta = 1.000000 | qdelta = 1.000000
+      delta = 3.000000 | qdelta = 2.000000
+      delta = 4.000000 | qdelta = 2.000000
+      delta = 1.000000 | qdelta = 1.000000
+      delta = 1.000000 | qdelta = 1.000000
+
+   If no file name is specified as a positional argument, a cast is
+   expected to be serverd via stdin.
+
    Once the transformation has been performed, the resulting cast is
    either written to a file specified in the '--out' flag or to stdout
    (default).