Auto-commit on 6d1dbe8495b5fafbc5f50d80268d0ca5b7b097be

1 files changed, 65 insertions, 4 deletions

diff --git a/readme.rst b/readme.rst
index b9e788b..6f14284 100644
--- a/readme.rst
+++ b/readme.rst
@@ -1,9 +1,70 @@
 Simple Text Queue
-=================
+#################
+
+Why and what it is
+==================
+
+`teaqueue` is a command able to process sequentially items such as files from
+a list of filenames in a text files by calling a given command for each of
+them.
+
+It can be used to:
+
+- transcode a batch of video files such as your preferred technical
+  presentations to a format accepted by your mobile phone,
+
+- retrieve a bunch of URLs or other remote operation,
+
+- sequential operation on anything that can be encoded on a single line (json
+  data, base64 data, etc).
+
+It is really useful for operations taking a lot of time when you want to be
+able to stop processing items in the queue and resume it, optionally changing
+order of items or adding/removing items from it before.
 
 Why `tea` ???
+-------------
+
+Because I love tea.
+
+Usage
+=====
+
+Usage is linked directly to manipulation of simple text files. You use text
+files to make the queue, to add or remove items from it, to change priority of
+items. *UNIX is the way*.
+
+I give some examples in this section. Take into account `teaqueue` takes
+`queue.txt` in the current directory by default as queue file modifying it
+when interrupted to remove processed items. By default, processed items goes
+to `done.txt`. This files serves to remove processed items from `queue.txt`
+when the queue is interrupted and serves as a log file for processed items.
+
+Video batch transcoding
+-----------------------
+
+Firstly list filenames in the queue::
+
+    find -type f -iname '*.webm' > queue.txt
+
+Then ask `teaqueue` to process each files with a transcoding command::
+
+    teaqueue transcode_my_file.sh
+
+This is all if you just want to process each file and do not interrupt it. If
+you want to interrupt processing of the queue, modify it and resume it, first
+press `Ctrl-C` and modify `queue.txt` accordingly::
+
+    find ../another_dir -type '*.webm' >> queue.txt
+
+Or reorder some items::
+
+    vim queue.txt
+
+Then run again `teaqueue`::
+
+    teaqueue transcode_my_file.sh
 
-- Because I love tea.
 
 History
 =======
@@ -17,5 +78,5 @@ processed, you could write something like this::
     comm -23 queue.txt done.txt > remaining_queue.txt
 
 But if this is something you want to do again and again, it might be
-convenient to write a little wrapper to do it for us. This is how teaqueue is
-born.
+convenient to write a little wrapper to do it for us. This is how `teaqueue`
+was born.