Improve documentation

diff --git a/README b/README
index 5595369d2d4eb8e55a390ab95f38bc9315961ba2..dfe68b4c6667830551fc177bf6e6bcc2b60a58ee 100644 (file)
--- a/README
+++ b/README
@@ -1,7 +1,16 @@
 WWW-Offliberty version 0.002
 ============================
 
-WWW::Offliberty is a simple interface to the offliberty.com download service.
+Offliberty is a service that takes a URL to some media (for example a
+YouTube video, a Vimeo video, a SoundCloud song) and returns one or
+more download links.
+
+WWW::Offliberty is a simple interface to this service. The dist also
+includes a command-line script called "off" that has the same
+functionality as the module.
+
+See http://offliberty.com and the documentation of WWW::Offliberty for
+more information.
 
 INSTALLATION
 
@@ -17,11 +26,11 @@ DEPENDENCIES
 This module requires these other modules and libraries:
 
  * HTML::TreeBuilder
- * LWP::UserAgent
+ * HTTP::Tiny
 
 COPYRIGHT AND LICENCE
 
-Copyright (C) 2013 by Marius Gavrilescu
+Copyright (C) 2013-2015 by Marius Gavrilescu
 
 This library is free software; you can redistribute it and/or modify
 it under the same terms as Perl itself, either Perl version 5.18.1 or,

diff --git a/lib/WWW/Offliberty.pm b/lib/WWW/Offliberty.pm
index f89e0d6a2ed63d22f63dec8c41c973591b9c8aa4..d7a407af2e281ab1aba1cadd2f5a57378d7af52c 100644 (file)
--- a/lib/WWW/Offliberty.pm
+++ b/lib/WWW/Offliberty.pm
@@ -38,9 +38,20 @@ WWW::Offliberty - interface to offliberty.com download service
 
 WWW::Offliberty is a simple interface to the offliberty.com download service.
 
-It exports a single function: B<off>(I<url>, [I<argument> => value...]).
-This function  that returns a list of download links,
-as returned by the service.
+The module exports (on request) a single function, B<off>(I<url>,
+[I<parameter> => value, ...]). It takes a URL and an optional list of
+parameters (key/value pairs). It returns a list of download links. An
+empty list is returned if the Offliberty service returns no URLs (for
+example if Offliberty encounters an error or the URL is invalid). Dies
+if unable to contact Offliberty (for example if there is no internet
+connection or a firewall blocks the connection).
+
+The supported services and parameters are undocumented. From empirical
+testing, when requesting a YouTube URL the service will return an
+audio-only URL when called with no parameters, and two URLs
+(audio-only and audio/video) when called with the parameter
+B<video_file> set to B<1>. In contrast, Vimeo URLs with no parameters
+return both audio-only and audio/video variants.
 
 =head1 SEE ALSO
 
@@ -52,7 +63,7 @@ Marius Gavrilescu, E<lt>marius@ieval.roE<gt>
 
 =head1 COPYRIGHT AND LICENSE
 
-Copyright (C) 2013 by Marius Gavrilescu
+Copyright (C) 2013-2015 by Marius Gavrilescu
 
 This library is free software; you can redistribute it and/or modify
 it under the same terms as Perl itself, either Perl version 5.18.1 or,

diff --git a/off b/off
index c4183c0f4b6d617aec86d2965ffeb0a1cff5b515..4633a3a35dd40968a14e4c88ec3cf43719237555 100755 (executable)
--- a/off
+++ b/off
@@ -25,7 +25,11 @@ off - Offliberate this
 
 =head1 DESCRIPTION
 
-off is a command-line interface to the offliberty.com download service. It prints a list of download URLs for a given resource (e.g. a youtube video). You can also send parameters using the C<--param> argument.
+off is a command-line interface to the offliberty.com download
+service. It prints a list of download URLs for a given resource (e.g.
+a youtube video). You can also send parameters using the C<--param>
+argument. See the L<WWW::Offliberty> documentation for more
+information about parameters.
 
 =head1 SEE ALSO
 
@@ -37,7 +41,7 @@ Marius Gavrilescu, E<lt>marius@ieval.roE<gt>
 
 =head1 COPYRIGHT AND LICENSE
 
-Copyright (C) 2013 by Marius Gavrilescu
+Copyright (C) 2013-2015 by Marius Gavrilescu
 
 This library is free software; you can redistribute it and/or modify
 it under the same terms as Perl itself, either Perl version 5.18.1 or,