.\" Automatically generated by Pod::Man 4.10 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "EBook::Tools::MSReader 3pm"
.TH EBook::Tools::MSReader 3pm "2019-08-08" "perl v5.28.1" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
EBook::Tools::MSReader \- Helper code for working with Microsoft Reader (.lit) e\-books.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 4
\& use EBook::Tools::MSReader qw(find_convertlit find_convertlit_keys
\&                               system_convertlit);
\& $EBook::Tools::MSReader::convertlit_cmd = \*(Aq/opt/convertlit/clit\*(Aq;
\& $EBook::Tools::MSReader::convertlit_keys = \*(Aq/opt/convertlit/keys.txt\*(Aq;
\&
\& my $convertlit = find_convertlit();
\& my $keyfile = find_convertlit_keys();
\& system_convertlit(infile => \*(Aqmyfile.lit\*(Aq,
\&                   dir => \*(Aqmyfile\-unpacked\*(Aq);
.Ve
.SH "PROCEDURES"
.IX Header "PROCEDURES"
All procedures are exportable, but none are exported by default.
.ie n .SS """find_convertlit()"""
.el .SS "\f(CWfind_convertlit()\fP"
.IX Subsection "find_convertlit()"
Attempts to locate the convertlit executable by making a test
execution on predicted locations (including just checking \s-1PATH\s0) and
looking in the EBook::Tools user configuration directory (see
\&\*(L"\fBuserconfigdir()\fR\*(R" in EBook::Tools.
.PP
Returns the system command used for a successful invocation, or undef
if nothing worked.
.PP
This will use package variable \f(CW$convertlit_cmd\fR as its first guess,
and set that variable to the return value as well.
.ie n .SS """find_convertlit_keys($filename)"""
.el .SS "\f(CWfind_convertlit_keys($filename)\fP"
.IX Subsection "find_convertlit_keys($filename)"
Attempts to locate the convertlit \f(CW\*(C`keys.txt\*(C'\fR file by checking
predicted filenames, both in the current working directory and in the
EBook::Tools user configuration directory (see
\&\*(L"\fBuserconfigdir()\fR\*(R" in EBook::Tools.
.PP
If \f(CW$filename\fR is provided, the file \f(CW\*(C`basename\-keys.txt\*(C'\fR will also
be checked in both locations.
.PP
Returns the name of the first file found, or undef if nothing was found.
.PP
This will use package variable \f(CW$convertlit_keys\fR as its first guess,
and set that variable to the return value as well.
.ie n .SS """system_convertlit(%args)"""
.el .SS "\f(CWsystem_convertlit(%args)\fP"
.IX Subsection "system_convertlit(%args)"
Runs \f(CW\*(C`convertlit\*(C'\fR to extract or downconvert a \s-1MS\s0 Reader .lit file.
The procedures \fBfind_convertlit()\fR and \fBfind_convertlit_keys()\fR are
both called to locate necessary helper files.
.PP
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.
.PP
\fIArguments\fR
.IX Subsection "Arguments"
.IP "\(bu" 4
\&\f(CW\*(C`infile\*(C'\fR
.Sp
The input filename.  If not specified or invalid, the procedure croaks.
.IP "\(bu" 4
\&\f(CW\*(C`outfile\*(C'\fR
.Sp
The output filename.  If this is specified convertlit will perform a
downconversion.
.IP "\(bu" 4
\&\f(CW\*(C`dir\*(C'\fR
.Sp
The output directory.  If this is specified, and \f(CW\*(C`outfile\*(C'\fR is not,
convertlit will perform an extraction.  If both this and \f(CW\*(C`outfile\*(C'\fR
are specified, convertlit will downconvert and place the downconverted
file into the specified directory.
.IP "\(bu" 4
\&\f(CW\*(C`keyfile\*(C'\fR
.Sp
The location of the \f(CW\*(C`keys.txt\*(C'\fR file containing the encryption keys,
if available.  This is only required if the \f(CW\*(C`.lit\*(C'\fR file is
DRM-protected and package variable \f(CW$convertlit_keys\fR does not point
to the correct file.
.SH "BUGS AND LIMITATIONS"
.IX Header "BUGS AND LIMITATIONS"
.IP "\(bu" 4
All handling happens through ConvertLIT as an external helper.
Native Perl code may eventually be written to handle non-DRMed
extraction.
.IP "\(bu" 4
Unit tests are unwritten
.SH "AUTHOR"
.IX Header "AUTHOR"
Zed Pobre <zed@debian.org>
.SH "LICENSE AND COPYRIGHT"
.IX Header "LICENSE AND COPYRIGHT"
Copyright 2008 Zed Pobre
.PP
Licensed to the public under the terms of the \s-1GNU GPL,\s0 version 2.
.PP
ConvertLIT (not included) is copyright 2002, 2003 Dan A. Jackson, and
licensed under the terms of the \s-1GNU GPL,\s0 version 2 or later.