Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
EBook::Tools::PalmDoc(User Contributed Perl DocumentatEBook::Tools::PalmDoc(3)

NAME
       EBook::Tools::PalmDoc - Palm::PDB handler for manipulating the
       PalmDoc/PilotDoc/AportisDoc format

SYNOPSIS
	use EBook::Tools::PalmDoc qw(uncompress_palmdoc);
	use Palm::PDB;

	my $pdb	= Palm::PDB->new();

       or

	use EBook::Tools::PalmDoc qw(:all);

	my $pdb	= EBook::Tools::PalmDoc->new();
	$pdb->set_text($text);
	$pdb->Write('textfile.pdb');

	my $pdb2 = EBook::Tools::PalmDoc->new();
	$pdb2->{attributes}{resource} =	1;
	$pdb->import_textfile('textfile.txt');
	$pdb->Write('textfile.prc');

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.

CONSTRUCTOR
   "new()"
       Instantiates a new Ebook::Tools::PalmDoc	object.	 To create a Palm
       Resource	file instead of	a Palm Database	file, set
       "$self->{attributes}{resource}" to be true immediately after
       construction.

       Create a	new Doc	object.	By default, it's not a resource	database.
       Setting "$self->{attributes}{resource}" to 1 before any manipulations
       will cause it to	become a resource database.

ACCESSOR METHODS
   "bookmarks()"
       Returns a hash of bookmarks, where the keys are the bookmark offsets
       and the values are the bookmark names.

   "text()"
       Returns the text	of the file

   "html()"
       Returns the text	of the file converted to HTML via HTML::TextToHTML.

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.

   "ParseRecord(%record)"
       Parses PDB records, updating the	object attributes.  This method	is
       called automatically on every database record (in .pdb files) during
       "Load()".

   "ParseResource(%resource)"
       Parses PDB resources, updating object attributes.  This is called
       automatically on	every database resource	(in .prc files)	during
       "Load()".

   "ParseRecordBookmark($data,$currentrecord)"
       Parses bookmark records/resources, updating object attributes, most
       notably "$self->{bookmarks}".

       The $currentrecord argument is optional,	but without it the debugging
       information may be less useful.	This is	called automatically by
       ParseRecord() and ParseResource() as needed.

   "ParseRecordText($data)"
       Parses text records, updating object attributes,	most notably appending
       text to "$self->{text}".

       This is called automatically by "ParseRecord()" and "ParseResource()"
       as needed.

   "set_text(@text)"
       Uses the	contents of @text (concatenated) as the	text of	the PDB.

   import_textfile($filename)
       Set the contents	of the Doc to the contents of the file and sets	the
       name of the PDB to the basename of the file.

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

   "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.

       See "uncompress_palmdoc()" for more details on the algorithm.

       This procedure was taken	from Palm::Doc with some minor changes.

   "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.

       See:

       http://wiki.mobileread.com/wiki/DOC#PalmDOC

       and

       http://wiki.mobileread.com/wiki/MOBI

       keys

       The returned hashref will have the following keys:

       o   "compression"

	   Possible values:

	   1 - no compression
	   2 - PalmDoc compression
	   128 - iSilo3?
	   17480 (the characters 'DH') - Mobipocket 'Dictionary	Huffman'
	   compression (aka HuffDic aka	Huff/CDIC)

	   A warning will be carped if an unknown value	is found.

       o   "textlength"

	   Uncompressed	length of book text in bytes

       o   "textrecords"

	   Number of PDB records used for book text

       o   "recordsize"

	   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.

       o   "spare"

	   Two bytes that should always	be zero.  A warning will be carped if
	   they	aren't.

       o   "unknown12"

	   32 bits of unknown data, generally zero.  This key may be changed
	   later if more information is	discovered.  Use with caution.

       Note that the current position component	of the header is discarded.

   "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.

       If an error is encountered during uncompression outputs a debug message
       and returns undef.

       Arguments

       "uncompress_palmdoc" takes one optional named argument:

       "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.

       Algorithm

       The decoding mechanism is as follows:

       Start by	reading	a byte from the	compressed stream.  If the byte	is:

       o   0x00: copy unmodified

       o   0x01	to 0x08: "Type A" command

	   This	specifies that the next	1-8 bytes are to be copied unmodified.

       o   0x09	to 0x7f: copy unmodified

       o   0x80	to 0xbf: "Type B" command

	   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).

       o   0xc0	to 0xff: "Type C" command

	   This	compresses spaces with the next	character, with	the value of
	   that	character being	XORed with 0x80.

BUGS
       o   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:

	   <http://www.df.lth.se/~triad/krad/recode/palm.html>

	   for details.

       o   PalmDoc files in resource (.prc) form are almost entirely untested.
	   Use at your own risk	(but feel free to file bug reports).

       o   Although bookmarks can be extracted,	they cannot be added to	a new
	   file.

       o   Unit	tests are unwritten.

AUTHOR
       Zed Pobre <zed@debian.org>

COPYRIGHT
       Copyright 2008 Zed Pobre

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

SEE ALSO
       o   EBook::Tools

       o   Palm::PDB

       o   Palm::Doc

	   Palm::Doc was the inspiration for this component, but it has	been
	   completely redesigned and the only code remaining from it is	in
	   "compress_palmdoc()".

perl v5.24.1			  2017-07-08	      EBook::Tools::PalmDoc(3)

NAME | SYNOPSIS | DESCRIPTION | CONSTRUCTOR | ACCESSOR METHODS | MODIFIER METHODS | PROCEDURES | BUGS | AUTHOR | COPYRIGHT | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=EBook::Tools::PalmDoc&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help