cleanup/improve usage and documentation

2 files changed, 30 insertions, 7 deletions

diff --git a/README.pod b/README.pod
index ee5a253..5e731cc 100644
--- a/README.pod
+++ b/README.pod
@@ -13,21 +13,25 @@ flexibility and aims to be used as a simple tool for other pacman based
 utilities which don't link against the library. It uses pacman.conf as a config
 file for locating and loading your local and sync databases.
 
-Targets are provided on the command line, and can be specified by simple name,
-or in repo/pkg format if the --sync option is used.
+Invoking expac consists of supplying a format string, which is generally
+described by one to many of the formatting tokens (see the B<FORMATTING>
+section), any relevant options and zero to many targets. The format string
+B<must> be the first non-option argument. Targets can be a simple package name,
+a query string (in the case of a search), or in repo/package syntax when the
+-sync option is supplied.
 
 =head1 OPTIONS
 
 =over 4
 
-=item B<-S, --sync>
-
-Search the sync databases for provided targets.
-
 =item B<-Q, --query>
 
 Search the local database for provided targets. This is the default behavior.
 
+=item B<-S, --sync>
+
+Search the sync databases for provided targets.
+
 =item B<-s, --search>
 
 Search for packages matching the strings specified by targets. This is a
@@ -152,6 +156,24 @@ output.
 
 Standard backslash escape sequences are supported, as per printf(1).
 
+=head1 EXAMPLES
+
+Emulate pacman's search function:
+
+=over 4
+
+  $ expac -Ss '%r/%n %v\n    %d' <search terms>
+
+=back
+
+List the oldest 10 installed packages (by build date):
+
+=over 4
+
+  $ expac --timefmt=%s '%b\t%n' | sort -n | head -10
+
+=back
+
 =head1 AUTHOR
 
 Dave Reisner E<lt>d@falconindy.comE<gt>
diff --git a/expac.c b/expac.c
index db64b9d..059a9d6 100644
--- a/expac.c
+++ b/expac.c
@@ -217,7 +217,8 @@ static void usage(void) {
       "  -p, --file                query local files instead of the DB\n"
       "  -t, --timefmt <fmt>       date format passed to strftime (default: \"%%c\")\n\n"
       "  -v, --verbose             be more verbose\n\n"
-      "  -h, --help                display this help and exit\n\n");
+      "  -h, --help                display this help and exit\n\n"
+      "For more details see expac(1).\n");
 }
 
 static int parse_options(int argc, char *argv[], alpm_handle_t *handle) {