Rebuild README.markdown from POD

1 files changed, 137 insertions, 11 deletions

diff --git a/README.markdown b/README.markdown
index 9f35802..f7e5662 100644
--- a/README.markdown
+++ b/README.markdown
@@ -1,31 +1,152 @@
 # NAME
 
-Music::Lyrics::LRC - Manipulate LRC karaoke lyrics files
+Music::Lyrics::LRC - Manipulate LRC karaoke timed lyrics files
 
 # VERSION
 
-Version 0.01
-
-# SYNOPSIS
-
-This section to be completed.
+Version 0.02
 
 # DESCRIPTION
 
 Read, write, and do simple manipulations of the LRC lyrics files used for some
 karaoke devices.
 
+For details on the LRC file format, please see Wikipedia:
+
+[https://en.wikipedia.org/wiki/LRC\_(file\_format)](https://en.wikipedia.org/wiki/LRC_\(file_format\))
+
+# SYNOPSIS
+
+    use Music::Lyrics::LRC;
+    ...
+    my $lrc = Music::Lyrics::LRC->new();
+    open my $rfh, '<', 'mylyrics.lrc';
+    ...
+    my $lyrics = $lrc->lyrics();  # arrayref of hashrefs: time (msec), text
+    my $tags = $lrc->tags();  # hashref, name => value
+    ...
+    $rfh->add_lyric(5500, q(Now I'm singin' at exactly 5.5 seconds...));
+    $rfh->add_tag('author', 'Justin A. Perlhacker');
+    ...
+    open my $wfh, '>', 'savelyrics.lrc';
+    $lrc->save($wfh);
+
 # SUBROUTINES/METHODS
 
-This section to be completed.
+## `new()`
+
+Constructor; no arguments.
+
+## `lyrics()`
+
+Retrieve an arrayref of hashrefs representing lyric lines, sorted by time
+ascending. Each one has `time` and `text` keys. The time is in milliseconds.
+
+    {
+        time => 5500,
+        text => 'Now I\'m singin\' at exactly 5.5 seconds...',
+    },
+    {
+        time => 6001,
+        text => 'And now a moment after the sixth...',
+    },
+    ...
+
+## `tags()`
+
+Retrieve a hashref of tag names to tag values for this lyrics file.
+
+    {
+        ar => 'Justin A. Perlhacker',
+        ti => 'Perl timekeeping blues',
+        ...
+    }
+
+## `add_lyric($time, $text)`
+
+Add a lyric at the given non-negative time in millseconds and with the given
+text. The text must not include newlines or carriage returns.
+
+## `set_tag($name, $value)`
+
+Set a tag with the given name and value. The name must be at least one
+character and cannot have colons. Neither the name nor the value can include
+newlines or carriage returns.
+
+## `unset_tag($name)`
+
+Clear a tag with the given name. Raises a warning if the tag has not been set.
+
+## `load($fh)`
+
+Load lyrics from the given readable filehandle.
+
+## `save($fh)`
+
+Save lyrics to the given writeable filehandle.
+
+## `ts_to_msec(\%ts)`
+
+Convert the internal LRC timestamp hash structure to milliseconds. You are
+probably not interested in this.
+
+## `msec_to_ts($msec)`
+
+Convert milliseconds to the internal LRC timestamp hash structure. You are
+probably not interested in this, either.
 
 # DIAGNOSTICS
 
-This section to be completed.
+- `Bad lyric time`
+
+    A lyric could not be added with the given time. It may have been negative.
+
+- `Bad lyric line`
+
+    The line you tried to add had illegal characters in it, probably a carriage
+    return or a newline.
+
+- `Bad tag name`
+
+    The tag you tried to set had an illegal name. It needs to be at least one
+    character, and can't include colons or whitespace.
+
+- `Bad tag value`
+
+    You tried to set a tag to an illegal value. The value probably had a carriage
+    return or a newline in it.
+
+- `Tag not set`
+
+    You tried to clear a tag that had not already been set.
+
+- `Unknown format for line %s`
+
+    The parser ran across a line in the LRC file that it could not understand. It
+    tolerates blank lines, tags, and lyric lines, and doesn't know anything else.
+
+- `Failed file read: %s`
+
+    The file read failed with the given system error.
+
+- `Not a filehandle`
+
+    You passed `load()` or `save()` something that wasn't a filehandle.
+
+- `Failed tag write: %s`
+
+    An attempt to write a tag to the output filehandle in `save()` failed with the
+    given system error.
+
+- `Failed lyric write: %s`
+
+    An attempt to write a lyric timestamp and line to the output filehandle in
+    `save()` failed with the given system error.
 
 # CONFIGURATION AND ENVIRONMENT
 
-None to speak of.
+You'll need to make sure that you're passing in a filehandle with the
+appropriate I/O layers you want, especially encoding.
 
 # DEPENDENCIES
 
@@ -35,11 +156,16 @@ None to speak of.
 
 # INCOMPATIBILITIES
 
-Probably.
+This module does not support any "extended" or "enhanced" LRC format; in
+particular, at the time of writing it can't handle per-word times syntax. This
+may change in future revisions.
 
 # BUGS AND LIMITATIONS
 
-Yes.
+The format accepted here is very liberal, and needs to be tested with lots of
+different LRC files from the wild.
+
+The test suite is skeletal, and needs a lot of fleshing out.
 
 # AUTHOR