.\" Automatically generated by Pod::Man 4.07 (Pod::Simple 3.32)
.\"
.\" 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
..
.if !\nF .nr F 0
.if \nF>0 \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    if !\nF==2 \{\
.        nr % 0
.        nr F 2
.    \}
.\}
.\"
.\" 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::PalmDoc 3pm"
.TH EBook::Tools::PalmDoc 3pm "2017-05-22" "perl v5.24.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::PalmDoc \- Palm::PDB handler for manipulating the PalmDoc/PilotDoc/AportisDoc format
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\& use EBook::Tools::PalmDoc qw(uncompress_palmdoc);
\& use Palm::PDB;
\&
\& my $pdb = Palm::PDB\->new();
.Ve
.PP
or
.PP
.Vb 1
\& use EBook::Tools::PalmDoc qw(:all);
\&
\& my $pdb = EBook::Tools::PalmDoc\->new();
\& $pdb\->set_text($text);
\& $pdb\->Write(\*(Aqtextfile.pdb\*(Aq);
\&
\& my $pdb2 = EBook::Tools::PalmDoc\->new();
\& $pdb2\->{attributes}{resource} = 1;
\& $pdb\->import_textfile(\*(Aqtextfile.txt\*(Aq);
\& $pdb\->Write(\*(Aqtextfile.prc\*(Aq);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module contains a Palm::PDB handler (subclassed from
Palm::Raw) and some associated general procedures for dealing with
PalmDoc books.  This handles PalmDoc and only PalmDoc.  For
Mobipocket, eReader, or other .pdb/.prc formats, see the module
specific to the format.
.SH "CONSTRUCTOR"
.IX Header "CONSTRUCTOR"
.ie n .SS """new()"""
.el .SS "\f(CWnew()\fP"
.IX Subsection "new()"
Instantiates a new Ebook::Tools::PalmDoc object.  To create a Palm
Resource file instead of a Palm Database file, set
\&\f(CW\*(C`$self\->{attributes}{resource}\*(C'\fR to be true immediately after
construction.
.PP
Create a new Doc object. By default, it's not a resource database. Setting
\&\f(CW\*(C`$self\->{attributes}{resource}\*(C'\fR to \f(CW1\fR before any manipulations will
cause it to become a resource database.
.SH "ACCESSOR METHODS"
.IX Header "ACCESSOR METHODS"
.ie n .SS """bookmarks()"""
.el .SS "\f(CWbookmarks()\fP"
.IX Subsection "bookmarks()"
Returns a hash of bookmarks, where the keys are the bookmark offsets
and the values are the bookmark names.
.ie n .SS """text()"""
.el .SS "\f(CWtext()\fP"
.IX Subsection "text()"
Returns the text of the file
.ie n .SS """html()"""
.el .SS "\f(CWhtml()\fP"
.IX Subsection "html()"
Returns the text of the file converted to \s-1HTML\s0 via HTML::TextToHTML.
.SH "MODIFIER METHODS"
.IX Header "MODIFIER METHODS"
These methods have two naming/capitalization schemes \*(-- methods
directly related to the subclassing of Palm::PDB use its
MethodName capitalization style.  Any other methods are
lowercase_with_underscores for consistency with the rest of
EBook::Tools.
.ie n .SS """ParseRecord(%record)"""
.el .SS "\f(CWParseRecord(%record)\fP"
.IX Subsection "ParseRecord(%record)"
Parses \s-1PDB\s0 records, updating the object attributes.  This method is
called automatically on every database record (in .pdb files) during
\&\f(CW\*(C`Load()\*(C'\fR.
.ie n .SS """ParseResource(%resource)"""
.el .SS "\f(CWParseResource(%resource)\fP"
.IX Subsection "ParseResource(%resource)"
Parses \s-1PDB\s0 resources, updating object attributes.  This is called
automatically on every database resource (in .prc files) during
\&\f(CW\*(C`Load()\*(C'\fR.
.ie n .SS """ParseRecordBookmark($data,$currentrecord)"""
.el .SS "\f(CWParseRecordBookmark($data,$currentrecord)\fP"
.IX Subsection "ParseRecordBookmark($data,$currentrecord)"
Parses bookmark records/resources, updating object attributes, most
notably \f(CW\*(C`$self\->{bookmarks}\*(C'\fR.
.PP
The \f(CW$currentrecord\fR argument is optional, but without it the
debugging information may be less useful.  This is called
automatically by \fIParseRecord()\fR and \fIParseResource()\fR as needed.
.ie n .SS """ParseRecordText($data)"""
.el .SS "\f(CWParseRecordText($data)\fP"
.IX Subsection "ParseRecordText($data)"
Parses text records, updating object attributes, most notably
appending text to \f(CW\*(C`$self\->{text}\*(C'\fR.
.PP
This is called automatically by \*(L"\fIParseRecord()\fR\*(R" and
\&\*(L"\fIParseResource()\fR\*(R" as needed.
.ie n .SS """set_text(@text)"""
.el .SS "\f(CWset_text(@text)\fP"
.IX Subsection "set_text(@text)"
Uses the contents of \f(CW@text\fR (concatenated) as the text of the \s-1PDB.\s0
.SS "import_textfile($filename)"
.IX Subsection "import_textfile($filename)"
Set the contents of the Doc to the contents of the file and sets the
name of the \s-1PDB\s0 to the basename of the file.
.SH "PROCEDURES"
.IX Header "PROCEDURES"
All procedures are exportable, but none are exported by default.
.ie n .SS """compress_palmdoc($text)"""
.el .SS "\f(CWcompress_palmdoc($text)\fP"
.IX Subsection "compress_palmdoc($text)"
Compresses input text using the simplified Lempel-Ziv 77 encoding used
by PalmDoc and some other formats and returns the compressed string.
.PP
See \*(L"\fIuncompress_palmdoc()\fR\*(R" for more details on the algorithm.
.PP
This procedure was taken from Palm::Doc with some minor changes.
.ie n .SS """parse_palmdoc_header($data)"""
.el .SS "\f(CWparse_palmdoc_header($data)\fP"
.IX Subsection "parse_palmdoc_header($data)"
Takes as an argument a scalar containing the 16 bytes of the PalmDoc
header (also used by Mobipocket).  Returns a hashref containing those
values keyed to recognizable names.
.PP
See:
.PP
http://wiki.mobileread.com/wiki/DOC#PalmDOC
.PP
and
.PP
http://wiki.mobileread.com/wiki/MOBI
.PP
\fIkeys\fR
.IX Subsection "keys"
.PP
The returned hashref will have the following keys:
.IP "\(bu" 4
\&\f(CW\*(C`compression\*(C'\fR
.Sp
Possible values:
.RS 4
.IP "1 \- no compression" 4
.IX Item "1 - no compression"
.PD 0
.IP "2 \- PalmDoc compression" 4
.IX Item "2 - PalmDoc compression"
.IP "128 \- iSilo3?" 4
.IX Item "128 - iSilo3?"
.IP "17480 (the characters '\s-1DH\s0') \- Mobipocket 'Dictionary Huffman' compression (aka HuffDic aka Huff/CDIC)" 4
.IX Item "17480 (the characters 'DH') - Mobipocket 'Dictionary Huffman' compression (aka HuffDic aka Huff/CDIC)"
.RE
.RS 4
.PD
.Sp
A warning will be carped if an unknown value is found.
.RE
.IP "\(bu" 4
\&\f(CW\*(C`textlength\*(C'\fR
.Sp
Uncompressed length of book text in bytes
.IP "\(bu" 4
\&\f(CW\*(C`textrecords\*(C'\fR
.Sp
Number of \s-1PDB\s0 records used for book text
.IP "\(bu" 4
\&\f(CW\*(C`recordsize\*(C'\fR
.Sp
Maximum size of each record containing book text. This should always
be 2048 (for some Mobipocket files) or 4096 (for everything else).  A
warning will be carped if it isn't.
.IP "\(bu" 4
\&\f(CW\*(C`spare\*(C'\fR
.Sp
Two bytes that should always be zero.  A warning will be carped if
they aren't.
.IP "\(bu" 4
\&\f(CW\*(C`unknown12\*(C'\fR
.Sp
32 bits of unknown data, generally zero.  This key may be changed
later if more information is discovered.  Use with caution.
.PP
Note that the current position component of the header is discarded.
.ie n .SS """uncompress_palmdoc($data,%args)"""
.el .SS "\f(CWuncompress_palmdoc($data,%args)\fP"
.IX Subsection "uncompress_palmdoc($data,%args)"
Uncompresses data compressed using the simplified Lempel-Ziv 77 scheme
used by PalmDoc and some other formats, and returns the uncompressed
string.
.PP
If an error is encountered during uncompression outputs a debug
message and returns undef.
.PP
\fIArguments\fR
.IX Subsection "Arguments"
.PP
\&\f(CW\*(C`uncompress_palmdoc\*(C'\fR takes one optional named argument:
.ie n .IP """trailing""" 4
.el .IP "\f(CWtrailing\fR" 4
.IX Item "trailing"
This specifies the number of trailing bytes to ignore on each record
during decompression.  Extra data such as this is sometimes found on
version 6 Mobipocket records.
.PP
\fIAlgorithm\fR
.IX Subsection "Algorithm"
.PP
The decoding mechanism is as follows:
.PP
Start by reading a byte from the compressed stream.  If the byte is:
.IP "\(bu" 4
0x00: copy unmodified
.IP "\(bu" 4
0x01 to 0x08: \*(L"Type A\*(R" command
.Sp
This specifies that the next 1\-8 bytes are to be copied unmodified.
.IP "\(bu" 4
0x09 to 0x7f: copy unmodified
.IP "\(bu" 4
0x80 to 0xbf: \*(L"Type B\*(R" command
.Sp
This specifies that the 16 bits (two characters) starting at that
point represent a length-offset pair.  Of the 16 bits that make up
these two bytes, the two leftmost bits (which should be '10') are
simply an identifier and are discarded.  The next 11 bits encode the
offset backwards from the end of uncompressed text, and the last three
encode the length of text to copy from that point (copying n+3 bytes).
.IP "\(bu" 4
0xc0 to 0xff: \*(L"Type C\*(R" command
.Sp
This compresses spaces with the next character, with the value of that
character being XORed with 0x80.
.SH "BUGS"
.IX Header "BUGS"
.IP "\(bu" 4
There isn't really any good way to detect the encoding from a
PalmDoc file, and I haven't even tried.  You may have some luck with
Encode::Detect.  On top of this, the encodings aren't entirely
conformant with what you might expect, and vary by version of PalmOS.
See:
.Sp
<http://www.df.lth.se/~triad/krad/recode/palm.html>
.Sp
for details.
.IP "\(bu" 4
PalmDoc files in resource (.prc) form are almost entirely
untested.  Use at your own risk (but feel free to file bug reports).
.IP "\(bu" 4
Although bookmarks can be extracted, they cannot be added to a
new file.
.IP "\(bu" 4
Unit tests are unwritten.
.SH "AUTHOR"
.IX Header "AUTHOR"
Zed Pobre <zed@debian.org>
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2008 Zed Pobre
.PP
Licensed to the public under the terms of the \s-1GNU GPL,\s0 version 2
.SH "SEE ALSO"
.IX Header "SEE ALSO"
.IP "\(bu" 4
EBook::Tools
.IP "\(bu" 4
Palm::PDB
.IP "\(bu" 4
Palm::Doc
.Sp
Palm::Doc was the inspiration for this component, but it has been
completely redesigned and the only code remaining from it is in
\&\*(L"\fIcompress_palmdoc()\fR\*(R".