1 files changed, 46 insertions, 0 deletions
diff --git a/README b/README
new file mode 100644
index 0000000..5ad7225
--- /dev/null
+++ b/README
@@ -0,0 +1,46 @@
+vp is a powerful UNIX tool for interactively building shell commands.
+For more information, read the vp.1 manual.
+
+Below are some examples of how I've successfully used vp to perform
+advanced ad-hoc text processing in my everyday life.
+
+= Sort paragraphs alphabetically =
+
+I once found myself wanting to sort function definitions alphabetically.
+Luckily, the solution was simplified by the fact that functions
+didn't contain any blank lines.  Here's how I did it.
+
+ 1. Open the file in vi.
+
+ 2. Cut the function definitions to the clipboard:
+
+	!xsel -i
+
+ 3. Launch vp:
+
+	:!vp
+
+ 4. Write something along the following lines:
+
+	xsel -o | perl -00 -ne '
+	push @d, $_;
+	END { print for sort @d }' 
+
+ 5. When you've found a command that works, press q to keep
+    the output.
+
+ 6. Copy the buffer:
+
+	:%!xsel -i
+
+ 7. Quit vp, return to the original vi session and paste the
+    sorted function definitions.
+
+For a more general solution, which supports blank lines within
+definitions, I came up with the following command:
+
+	xsel -o | perl -ne '
+	@d[$i] .= $_;
+	$i++ if /^}/;
+	END { print for sort @d }
+	'