NAME

       EBook::Tools::MSReader - Helper code for working with Microsoft Reader (.lit) e-books.

SYNOPSIS

        use EBook::Tools::MSReader qw(find_convertlit find_convertlit_keys
                                      system_convertlit);
        $EBook::Tools::MSReader::convertlit_cmd = '/opt/convertlit/clit';
        $EBook::Tools::MSReader::convertlit_keys = '/opt/convertlit/keys.txt';

        my $convertlit = find_convertlit();
        my $keyfile = find_convertlit_keys();
        system_convertlit(infile => 'myfile.lit',
                          dir => 'myfile-unpacked');

PROCEDURES

       All procedures are exportable, but none are exported by default.

   "find_convertlit()"
       Attempts to locate the convertlit executable by making a test execution on predicted locations (including
       just checking PATH) and looking in the EBook::Tools user configuration directory (see "userconfigdir()"
       in EBook::Tools.

       Returns the system command used for a successful invocation, or undef if nothing worked.

       This will use package variable $convertlit_cmd as its first guess, and set that variable to the return
       value as well.

   "find_convertlit_keys($filename)"
       Attempts to locate the convertlit "keys.txt" file by checking predicted filenames, both in the current
       working directory and in the EBook::Tools user configuration directory (see "userconfigdir()" in
       EBook::Tools.

       If $filename is provided, the file "basename-keys.txt" will also be checked in both locations.

       Returns the name of the first file found, or undef if nothing was found.

       This will use package variable $convertlit_keys as its first guess, and set that variable to the return
       value as well.

   "system_convertlit(%args)"
       Runs "convertlit" to extract or downconvert a MS Reader .lit file.  The procedures find_convertlit() and
       find_convertlit_keys() are both called to locate necessary helper files.

       Returns the return value from convertlit, or undef if convertlit or the input file could not be found, or
       neither output file nor directory is specified.

       Arguments

       •   "infile"

           The input filename.  If not specified or invalid, the procedure croaks.

       •   "outfile"

           The output filename.  If this is specified convertlit will perform a downconversion.

       •   "dir"

           The  output  directory.   If  this  is  specified,  and  "outfile" is not, convertlit will perform an
           extraction.  If both this and "outfile" are specified, convertlit  will  downconvert  and  place  the
           downconverted file into the specified directory.

       •   "keyfile"

           The  location  of  the  "keys.txt"  file  containing the encryption keys, if available.  This is only
           required if the ".lit" file is DRM-protected and package variable $convertlit_keys does not point  to
           the correct file.

BUGS AND LIMITATIONS

       •   All  handling  happens  through ConvertLIT as an external helper.  Native Perl code may eventually be
           written to handle non-DRMed extraction.

       •   Unit tests are unwritten

AUTHOR

       Zed Pobre <zed@debian.org>

LICENSE AND COPYRIGHT

       Copyright 2008 Zed Pobre

       Licensed to the public under the terms of the GNU GPL, version 2.

       ConvertLIT (not included) is copyright 2002, 2003 Dan A. Jackson, and licensed under the terms of the GNU
       GPL, version 2 or later.

perl v5.24.1                                       2017-05-22                        EBook::Tools::MSReader(3pm)