 | Level: Intermediate Andrew Blais, Unindicted co-conspirators, Gnosis Software, Inc.
David Mertz (mertz@gnosis.cx), Unindicted co-conspirators, Gnosis Software, Inc.
01 Jun 2001 The Pyrite Project has created several related tools to allow Python programmers to access and control PalmOS handheld devices. Pyrite communicates with and manages the data help on Palm devices, while Pyrite Publisher creates and distributes Doc format e-books to Palm devices. This article discusses our experience working with Pyrite tools, the underlying architecture, and tips for effectively using the Pyrite tools.
We suppose you're like us in some ways: 1) You have a brand new PalmOS handheld that promises to do all sorts of neat things; 2) Your OS of choice is Linux; and 3) You want to transform documents from your Linux environment into documents that you can access with your PalmOS handheld. Maybe you even wish to programmatically manipulate the record database on your Palm. The Pyrite Project provides this set of tools; we will focus on the portion dubbed Pyrite Publisher that deals with document conversions. While the Pyrite Project has potential and addresses some important
needs, it still has a lot of rough edges. This article walks you
through some of the problems you might encounter. Prerequisites for installing Pyrite Publisher
Pyrite Publisher is written in Python and depends on some code provided by another pair of packages called Pilot-Link and Pyrite. Consequently, you will need the following things:
- Python 1.5.2, or greater
- The development headers for Python
- A C compiler -- gcc worked for us
- The pilot-link library, 0.8.11 or greater
- The header files from pilot-link
- The development headers from pyrite
We assume that you don't need help getting (1), (2), and (3). There are two
ways to get the remaining header files and libraries. The first method employs RPM. Go to the RPM database on RPMFind.net (see Resources) and download the RPMs for pilot-link and pilot-link-devel. The second method is to download the pilot-link source (see Resources) and install it by hand. Use the standard procedures to install, namely:
Listing 1. bash session for installing pilot-link source
$ tar zxvf pilot-link.0.9.3.tar.gz
$ cd pilot-link.0.9.3
$ ./configure
$ make
$ make install
|
To get the development headers from Pyrite, download the source (see Resources). Then do the following:
Listing 2. bash session for installing Pyrite source
$ tar zxvf pyrite-0.9.3.tar.gz
$ cd pyrite-0.9.3
$ ./configure
$ make
|
One of the Makefiles has an error, so use your favorite editor to open 'i18n/Makefile. On line 26, change:
Listing 3. Required fix for Makefile error
# mkdir -p $(DESTDIR)$(LOCALEDIR) ;
mkdir -p $(DESTDIR)$(LOCALEDIR) ;
|
Otherwise, you will get the following error message:
Listing 4. Error message
make[1]: Entering directory
`/root/PAPERS/palm-stuff/pyrite-0.9.3/i18n'
if [ "yes" = "yes" ]; then \
mkdir -p /usr/share/locale ;
/bin/sh: -c: line 2: syntax error: unexpected end of file
make[1]: *** [install] Error 2
make[1]: Leaving directory `/root/PAPERS/palm-stuff/pyrite-0.9.3/i18n'
make: *** [install] Error 2
|
Finally, run make install. You now have all the header files and libraries that you need to install Pyrite Publisher.
Other installation issues (Slackware, Mandrake)
We encountered several problems installing the Pyrite libraries and headers on our Mandrake 7.1 system. These issues are not directly Pyrite's fault, but you might have to install a few dependencies on your system. First, configure complained that it couldn't find the python config makefile. We readily downloaded a suitable python-dev RPM, which installed with no trouble (see Resources). Next, configure complained that it couldn't find the pilot-link library. We knew that pilot-link was installed, and that we had /usr/lib/libpisock.so.3 and
/usr/lib/libpisock.so.3.0.1. But, we didn't have a generic libpisock. We resolved this by creating the following link in /usr/lib:
Listing 5. Creating an non-numbered libpisock.so link
$ ln -s libpisock.so.3.0.1 libpisock.so
|
Subsequently, configure complained that it couldn't find the pilot-link library. So, we searched rpmfind for the appropriate pilot-link-devel-*.rpm. However, we encountered the infamous "only packages with major numbers <= 3 are supported by this version of RPM". So, we used the force: we got the source (see Resources). Then, we did the following:
Listing 6. bash session for installing pilot-link headers
$ tar zxvf pilot-link-0.9.3.tar.gz
$ cd pilot-link/include
$ cp * /usr/local/include
|
Finally, configure was happy. And make ran fine. We thought that we were on our way, but make install died because of the already mentioned typographical error in pyrite-0.9.3/i18n/Makefile. We made the change described above, and even make install worked. On our Slackware 7.1 system, python-dev was installed by default, but
pilot-link was not. Pilot-link needed to be configured with the
--without-cpp option. Our glibc and gcc had been upgraded from the 7.1 default, which may or may not have led to this option being required.
Installing Pyrite Publisher
Of course, begin by downloading the source (see Resources). Then, do the following:
Listing 7. bash session for installing Pyrite Publisher
$ tar zxvf pyrite-publisher-1.99.0.tar.gz
$ cd pyrite-publisher-1.99.0
$ python setup.py install
|
Unfortunately, you're not done yet. There are several more problems with Pyrite Publisher. Here is how we resolved them. Some more fixes
Again, Pyrite Publisher promises to transform documents into files that can be uploaded to and read on a PalmOS handheld. Unfortunately, Pyrite Publisher doesn't do what it is supposed to do right out of the box. We found that we needed to make several fixes before we could get it working. For someone with no knowledge of Python, this is really a big problem. The following code changes will allow you to fix Pyrite Publisher just enough to transform a document such as an HTML document into a form that can be uploaded to a PalmOS handheld for convenient access on a train or in a cafe. Several changes are needed to PyritePublisher/plugin_HTML.py. In
Plugin.eof(), on line 79, change:
Listing 8. Required fix for plugin_HTML.py (1)
# self.fmt.add_flowing_data(p.anchorlist[x])
self.fmt.add_flowing_data(self.parser.anchorlist[x])
|
Listing 9. Required fix for plugin_HTML.py (2)
# from DocToolkit.entitydefs import entitydefs
from PyritePublisher.entitydefs import entitydefs
|
The next fix is to PyritePublisher/plugin_TealDoc.py. On line 32, change:
Listing 10. Required fix for plugin_TealDoc.py
# from DocToolkit import metrics
from PyritePublisher import metrics
|
The next fix is to PyritePublisher/doc_database.py. In
DocWriteStream.close(), on line 135, change:
Listing 11. Required fix for doc_database.py
# db.setRecord(0x40, uid, 0, bookmark_pack(t,p))
db.setRecord(0x40, uid, 0, 'THIS IS A TEST STRING')
|
This last fix is undoubtedly an ugly hack, but our goal here is not to beautify code. Our fix has the strange side effect of inserting odd looking bookmarks into our pdb files, which appear as a series of y's with umlauts. Apparently, the function bookmark_pack() is intended to create Palm-style bookmarks, but the function is missing, and we are not sure of the exact format. With this hack you can transform documents on your Linux machine into documents that you can read on your PalmOS handheld. Hopefully the authors will create or restore the needed function.
Using Pyrite Publisher
Using Pyrite Publisher is relatively simple. In
pyrite-publisher-1.99.0/PyritePublisher, you will find
pyrpub. If the document that you want to transform into PalmOS readable form is, for instance, file.html, the command is simply:
Listing 12. Converting an HTML file to PalmDoc
You will find a file named file.pdb, which can be read by a Palm. The next step is getting file.pdb on your PalmOS handheld. You can use a nifty program that comes with pilot-link called
pilot-xfer. Assuming that you have connected your Palm to
/dev/cua1, issue the following command:
Listing 13. Transferring the PalmDoc file to the Palm
$ pilot-xfer /dev/cua1 -i file.pdb
|
|
Writing Python code to communicate with a PalmOS device
Pyrite-0.9.3 provides a library that can be used to write Python code that will communicate with a PalmOS device.
One valuable source of information is to be found in
pyrite-0.9.3/doc/prg/html/book1.html, which is the root of the Pyrite Programmers Guide. Pyrite depends on another library called Sulfur, and there is helpful documentation in
pyrite-0.9.3/Sulfur/doc/html/book1.html, which is the root of the Sulfur Programmers Guide. The relationship between Pyrite and Sulfur can be better understood by noting that as Rob Tillotson developed Pyrite, he found that he had also been developing code that was useful outside the context of PalmOS applications. This code became Sulfur.
In or under pyrite-0.9.3, you will find the following five Python modules
with their various classes.
-
Blocks.py: Block, Record, AppBlock,
CategoryAppBlock, SortBlock, Resource, and PrefBlock
-
Database.py: Database, Slice, and CategoryIterator
-
Store/Store.py: BaseStore and Store
-
Application/Application.py: Application,
PyriteState, and PyriteCLIAppContext
-
Conduit/Conduit.py: Conduit
Blocks and Database are imported along with Pyrite, but Store, Application, and Conduit are not. There are also additional modules, classes, and methods, but the listed ones received more attention in the documentation. In this context, we will only summarize these modules and some of their methods.
Block objects represent and transform data to and from PalmOS and Python readable states. For example, Python stores the time in a tuple, and a Palm stores the time in the form of two packed bytes. Suppose we want the time 10 hours, 30 minutes, and 0 seconds. Then the following:
Python code for creating a Palm date
from Pyrite
import Blocks
time_tuple = (10, 30, 0)
palm_time = Blocks.tuple_to_palm_date(time_tuple)
|
will put 4032 in palm_time, which is the way that a Palm
internally represents the time.
A Database object is an accessible database with an .append() method, a .new_record() method, a .delete() method, and a .next_record() method. This is all quite interesting stuff, but it also goes quite beyond our aim here. See the resources listed above.
|
|
Then, press your hot-button on your cradle. Actually, you will be instructed to do this on the command line. Then, you will find file.pdb on your Palm. A limitation of Pyrite Publisher is that it doesn't directly convert PDF or Postscript files to pdb files. Luckily, there is a simple workaround for this. The utility pstotext can transform a Postscript file into a text file. To generate a pdb file, first transform the ps file into a text file, and then use Pyrite Publisher to convert the text file into a pdb file. If the file that you want to transform into a pdb file is a PDF file, first use pdf2pdf to transform the PDF file into a postscript file, and then proceed as described above. Unfortunately, this isn't a foolproof method, since
pstotext and pdf2ps aren't entirely reliable, but when they work, you will be able to generate pdb files.
Related packages
To find packages related to the Pyrite libraries and Pyrite Publisher, try searching Freshmeat. We think that you might want to look at some of the following packages (for links, see Resources):
- KVM (the K Virtual machine) and the Connected Limited Device Configuration (CLDC) let you write Palm applications that can be run on X11.
- Kpilot makes it possible for your Palm to exchange data with your Linux box. Kpilot uses plugins to exchange data between your Palm and other applications like KOrganizer or POP3/SMTP mail servers. Using Kpilot, you can read and edit documents and install new programs on your Palm.
- Jan Schaumann has done some interesting things with the Palm within the context of the Linux OS.
- Plucker also enables the Linux user to read HTML documents
offline. Plucker claims to support clickable images, italics, multiple
databases, configurable display parameters and stylus options, compression, and Python conduits and parsers.
- DataViz Documents To Go is a sophisticated
document conversion package, but only for Win32 and MacOS. If you happen to use these platforms, you can convert document formats such as MS-Word, MS-Excel, WordPerfect, PDF, and others. You can even edit documents in many of these formats on your Palm. Of course, you have to pay $50 for it.
 |
Summary
We like the concept behind the Pyrite Project, but we find that it doesn't live up to its promises. Pyrite Publisher works only if you know enough Python and system administration to fix it. After investing a lot of time in getting some work out of Pyrite Publisher, it still has a large collection of weird bugs. Also, Pyrite Publisher doesn't directly convert Postscript and PDF files. We are not totally negative, however, since it seems to be on the cusp of fulfilling its aim. We hope that Rob Tillotson and company continue with the Pyrite Project. Linux-using Palm owners could certainly use it.
Resources
About the authors | | | Andrew Blais divides his time between home-schooling his son, writing for Gnosis, and teaching philosophy and religion at Anna Maria College. He can be reached at onlymice@gnosis.cx. |
| | | David Mertz worries that if the density of transistors doubles every eighteen months, then he may lose his next computer in a haystack. David may be reached at mertz@gnosis.cx; his life pored over at http://gnosis.cx/dW/. Suggestions and
recommendations on this, past, or future columns are welcome. |
Rate this page
| |
