NAME

Palm::Doc - Handler for Palm Doc books

SYNOPSIS

use Palm::Doc;

DESCRIPTION

Helper for reading and writing Palm Doc books. The interface is based on Palm::ZText since it just makes sense. However, because of the nature of these databases, record-level processing is just a Bad Idea. Use the text and textfile calls rather than do direct access of the @records array.

EXAMPLES

Convert a text file to a .pdb:

        use Palm::Doc;
        my $doc = new Palm::Doc;
        $doc->textfile( $ARGV[0] );
        $doc->Write( $ARGV[0] . ".pdb" );

Convert an HTML file to a .prc:

        use HTML::TreeBuilder;
        use HTML::FormatText;
        use Palm::Doc;

        my $tree = HTML::TreeBuilder->new_from_file( $ARGV[0] );
        my $formatter = HTML::FormatText->new( leftmargin => 0, rightmargin => 80 );
        my $doc = new Palm::Doc;
        $doc->{attributes}{resource} = 1;
        $doc->text( $formatter->format( $tree ) );
        $doc->Write( $ARGV[0] . ".prc" );

new

        $doc = new Palm::Doc;

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.

text

        $text = $doc->text;

Return the contents of the Doc database.

        $text = $doc->text( @text );

Set the contents of the Doc book to the specified arguments. All the list arguments will simply be concatenated together.

textfile

        $doc->textfile( "README.txt" );

Set the contents of the Doc to the contents of the file and sets the name of the PDB to the specified filename.

BUGS

Bookmarks are unsupported. I've never had any use for them.

Output databases are always compressed and there's no option to disable compression. I consider this a feature, to be honest.

Note On Character Sets

Palm::Doc doesn't do anything with character sets. This might be a bug, depending on how you feel about this kind of thing, but the reality is that we're generally converting between text and Doc files, neither of which are real great at telling us what encoding we're supposed to use.

My understanding of PalmOS character sets is that Doc books should be encoded in either Windows Code Page 1252 or, for Japanese, 932. Actually, the PalmOS encoding is a small variation on those. In practice, ISO 8859-1 works okay for western languages which is real nice because Encode doesn't know about the PalmOS stuff.

This gist of all this is that when you're creating a Palm::Doc, you may need to do something along the lines of:

        use Encode 'from_to';

        my $text = read_my_text();
        from_to( $text, $charset, 'iso-8859-1' ) unless $charset =~ /8859-1$/;
        my $doc = new Palm::Doc();
        $doc->text( $text );

And when you're reading a Palm::Doc and you care about the character set, you're pretty much going to have to guess the encoding and act appropriately:

        use Encode 'decode';
        my $doc = new Palm::PDB;
        $doc->Load( $pdbname );
        my $text = decode("iso-8859-1", $doc->text());

AUTHOR

Christophe Beauregard <cpb@cpan.org>

SEE ALSO

Palm::PDB

Palm::ZText

makedoc

http://www.pyrite.org/doc_format.html

http://patb.dyndns.org/Programming/PilotDoc.htm

Palm::PalmDoc is another CPAN module for handling Doc databases, but doesn't use Palm::PDB and doesn't handle reading Docs.

http://www.df.lth.se/~triad/krad/recode/palm.html for details on PalmOS text encoding

cpanm EBook::MOBI

perl -MCPAN -e shell
install EBook::MOBI