Improve manpage introduction, add examples to manpage.

Closes #19

2 files changed, 17 insertions, 0 deletions

diff --git a/docs/Rakefile b/docs/Rakefile
index da2d4cf4..375ce408 100644
--- a/docs/Rakefile
+++ b/docs/Rakefile
@@ -81,6 +81,12 @@ task :manpage do
         f.puts "### #{entry['title']}\n"
         f.puts entry['body']
         f.puts ""
+        (entry['examples'] || []).each do |example|
+          f.puts "    jq '#{example['program']}'"
+          f.puts "       #{example['input']}"
+          f.puts "    => #{example['output'].join(", ")}"
+          f.puts
+        end
       end
       f.puts ""
     end
diff --git a/docs/content/3.manual/manual.yml b/docs/content/3.manual/manual.yml
index f0cedf4f..6e8065c6 100644
--- a/docs/content/3.manual/manual.yml
+++ b/docs/content/3.manual/manual.yml
@@ -35,6 +35,17 @@ manpage_intro: |
 
   `jq` [<options>...] <filter>
 
+  `jq` can transform JSON in various ways, by selecting, iterating,
+  reducing and otherwise mangling JSON documents. For instance,
+  running the command `jq 'map(.price) | add'` will take an array of
+  JSON objects as input and return the sum of their "price" fields.
+  
+  The <options> are described in the [INVOKING JQ] section, they
+  mostly concern input and output formatting. The <filter> is written
+  in the jq language and specifies how to transform the input
+  document.
+
+  ## FILTERS
   
 sections:
   - title: Invoking jq