Plucker FAQ
From Plucker Documentation
Introduction
What is Plucker?
Plucker is a suite of programs which provide an off-line web browser for Palm OS systems (see below for compatibility). It's free software under the conditions of the Free Software Foundation's General Public License, so you can copy, change, or even sell this program without giving anyone any money, as long as you make the source code (and your changes, if any) publicly available.
We would, of course, be interested to see any changes you might make and possibly include them in a future release of Plucker. There's lots of things that could be done better!
In many ways, the ideas of Plucker are similar to the proprietary AvantGo software, though we believe that the implementation of Plucker is utterly different from AvantGo. According to their web page, AvantGo implements an HTML parser on the Palm device; Plucker implements the majority of the parser on the PC/server/desktop machine. There are probably situations where AvantGo would be far more appropriate than Plucker (online browsing, for example), however, you need an SDK to work with AvantGo.
In what way is Plucker different from AvantGo and iSilo?
The programs differ in many ways.
Most importantly (to us, at least), Plucker is Free software, distributed under the FSF's General Public License. This means that if you are using Plucker, you are entitled to the source code, and you can change it to make it do whatever you want (as long as you make the changes publicly available).
For a longer comparison of features look at the AvantGo vs. Plucker vs. iSilo comparison page.
Where can I get Plucker?
You can visit the Plucker home page to get Plucker for your device and operating system.
The development versions ("the latest snapshot") are usually very stable themselves, so if you want access to all the latest features (and have the development tools installed) you can safely go with these versions. As always, remember to backup any unsaved data before you start playing with the development version.
Is there a mailing list for Plucker?
Yes.
The list for Plucker users, plucker-list, is a fairly low traffic list. The developers list, plucker-dev, is intended for focused development discussion amongst the core Plucker development team. Of course, anyone is welcome to read.
The Plucker Announce list is where new releases are announced. If you are only concerned with releases, this is the list for you.
To join: visit http://lists.plkr.org/ and select the list(s) you want to subscribe to.
Archives for plucker-list and plucker-dev can be found at the following URLs:
http://www.mail-archive.com/plucker-list%40rubberchicken.org http://www.mail-archive.com/plucker-dev%40rubberchicken.org http://lists.plkr.org
Is there an anonymous cvs server?
Yes there is. To check out the code from cvs, simply do the following:
cvs -d :pserver:anonymous:@cvs.plkr.org:/cvs/plucker -z3 co plucker
What is the status of Plucker?
Plucker is always in a beta state. While you're more than welcome to take Plucker for a spin, it might not work for you. It works well for us, but we don't know what you've got installed on your machines that may be different from that installed on ours. You might lose all the data on your Palm, you might need to reboot your machine, it might never be the same again.
Beware!
Where can I send bug reports?
If you have access to the Web, you can use our online bugtracker to file, comment upon and track bugs you've reported, or bugs reported by others.
If you do not have access to the Web, fill out the file BUGREPORT contained in the Plucker distribution and send it to plucker-bugs@plkr.org (really), and we'll do our best to fix them as soon as we can!
How can I contact the Plucker team?
Send a message to plucker-team@plkr.org. Unlike the mailing list, you don't have to be a subscriber to post to this address. However, general questions about Plucker should still be sent to the mailing lists.
Installation
What platforms does Plucker run on?
The viewer should run on any Palm OS device utilizing version 2.0.4 or higher of Palm OS, while the desktop tools are supported on Linux, Windows, Mac OS X, and OS/2.
The desktop tools will probably work on any Unix system with Python installed, but your mileage may vary, so don't get angry if they don't work. If you are able to get it running on a system not listed in REQUIREMENTS then please let us know so that it can be added to the list of supported systems.
Usage
How does Plucker work?
Plucker consists of four parts: the desktop, the parser/distiller, the conduit, and the viewer. The parser and the conduit have been merged into one complete Python version and development has been done towards the creation of a Perl parser. The standalone conduit is written in Perl and there is also a conduit written in Delphi for the Windows users.
The Plucker desktop runs on your main computer, i.e.the one with the HotSync cradle, IR port, or Bluetooth adapter physically attached to it, or on a networked machine which allows you to connect to it via Network Hotsync. It allows you to specify which pages to download in a user-friendly fashion and generates appropriate information that the parser can use during the conversion process later. The desktop can also call the parser directly and create Plucker databases at that time. Use of a desktop isn't required, but it makes creation and maintenance of database much easier for many users.
The parser or distiller also runs on your main computer. It gathers the web pages you specify and follows the links on those pages to a certain depth specified by you. If you're not using the Plucker Desktop, you specify the web pages you want to gather by creating a "home.html" file, which also becomes your home page. The links on "home.html" are followed to a depth specified by the optional "MAXDEPTH" attribute which you can include in the <a href="..."> tag in the home.html file. The parser finds new links to retrieve and also converts the pages to a format that the viewer can read.
The conduit takes the converted HTML files from a directory or from your computer's system memory (RAM; using a parser) and places them in a database on your Palm device. Alternatively, it may create a .PDB file on your desktop, which you can sync to your emulator or your "real" Palm device at a later time.
The viewer runs on your Palm device and displays the converted HTML files on your screen. It allows you to use the stylus to tap on links which will then display the target page. It has a page history, so you can move backwards and forwards through the pages just as you would with your desktop browser. It also has a library view where you can select from any of the Plucker databases you have installed and do other management tasks.
Rendering is done in part by the parser (which works out things like which styles to use) and in part by the viewer (which works out line and document lengths, and renders <a>nchors).
There also exists a third-party desktop, parser, and conduit written in Java called JPluck. While the original developer has moved on, it is still available at SourceForge.net/projects/jpluck. JPluck uses an XML format (called JXL) for specifying what its parser downloads, but the databases it generates are compatible with the Plucker viewer. Other developers have offered to take over development and there will be a replacement called Opusculus available at Opusculus.org.
Why can't I see any images on my Palm device?
Most likely, the answer is that the settings for the particular database are for images not to be included in the generated database. If you're using a Plucker Desktop program, make sure the "include images" check-box is checked for that particular channel.
If the parser throws errors when converting the images, try setting (supposing have imagemagick 5.4.4 or later):
image_parser = imagemagick2
If no images are plucked, check if you put MAXDEPTH=0. When 0, no images are downloaded. When 1, images are downloaded, but linked pages aren't (they require 2 or more).
It is also possible you have an ancient version of Plucker (image support was added in version 0.03) or you haven't installed all necessary tools. The Palm device uses a format called Tbmp (Tiny Bitmap) for its images, and the parser in Plucker needs (among others) a special tool called ppmtoTbmp to be able to convert images to the Palm OS bitmap format (depending on your version of Plucker, you may no longer need to use the ppmtoTbmp tool. It has recently been replaced by the netpbm2 package). Check out the REQUIREMENTS file in the main source archive for a list of necessary tools and where to find them.
It's set to include images and I have all the necessary tools, but I still can't see any!
Make sure that you don't set a too high value for MAXWIDTH. Anything above 150 pixels (default value) for embedded images will give the result that no images are shown on a low-resolution device. That value is roughly 310 pixels on a high-resolution device (subtract 10 pixels on all sides for the scrollbar)
Why do pages with images show 'img 4bpp' instead of images?
When you generate 2 or 4 bpp images you have to change the bit depth of the screen to view them. The default depth is 1 (Black/White), so when the viewer finds images of a higher bit depth it will display [img Nbpp] instead (N = bit depth for the image). You change the bit depth in the Preference dialog.
The protocol is missing when the parser attempts to download a page?
Even if you don't tell us what OS you are running we would be very surprised if it's not Red Hat 7.0, 7.1, or 7.2.
There is a bug in the python version (1.5.2) include with Red Hat 7.0, 7.1, and 7.2.
A solution provided by Joe A. can be found here and a more detailed discussion of the problem can be found here.
How do I pluck a password-protected site?
We suggest using Sitescooper together with Plucker to pluck various hard-to-get-at sites. Sitescooper has many features for pulling over pages that will be slow to appear as features in Plucker.
For more information on Sitescooper, see the Sitescooper homepage.
Another alternative is to use a program like wget or curl to download the content to a local directory or web server, and then point the parser at the local copy.
Is there any way to protect a Plucker document from theft?
Many people want to use Plucker for (books, reports, etc.) which they intend to sell, and they want to protect those books from theft.
Plucker documents can be built with an 'owner-id', which must correspond to the HotSync ID on a Palm for the document to be opened on that Palm. This is similar to the document-locking schemes used by many commercial sites. Use the --owner-id switch on the parser to do this.
Configuration
How do I configure the parser to create ZLib compressed databases?
By setting the compression key in the configuration file (.pluckerrc for Unix/Linux, plucker.ini for Windows and OS/2) to zlib the parser will use ZLib instead of DOC compression for the databases. You can always change this behavior at run-time by using the --zlib-compression or the --doc-compression options to the commandline distiller.
Development
Why does make only build the viewer application but never the ZLib library?
You didn't read the README in the viewer dir, did you? The zlib package must be downloaded separately and put in viewer/ZLIb *before* attempting to configure Plucker.
Where can I get zlib?
You can download zlib from its home page. Put the package in viewer/ZLib before you run configure.
Where can I get prc-tools?
prc-tools 2.x can be downloaded at: http://prc-tools.sourceforge.net/
Why is 'module X' so messy?
Well, the old legacy parser (a bunch of awk scripts) was only a temporary solution and have been replaced with a Python-based parser. That should make it easier to comprehend what it actually does! We believe that the rendering of documents for the Palm device should be specialized, so we intend to continue to render the documents in the parser/viewer.
If you haven't looked at the viewer since 0.02 then you would probably be surprised. The single source file of version 0.02 has been split up in several files and the viewer is approaching being optimal, but there are some issues, particularly with implied structure coupling, and lack of documentation, both of which we wish to address.
The conduit is not clever. It will upload pages to the database even if they already exist and have not changed. This should obviously be fixed so that a full 360 degree synchronization process can be achieved.
Miscellaneous Questions
Can you suggest some good web pages for Plucker?
In the appendix of the User's Guide you'll find a collection of links to some good web pages for Plucker.
What are some of the features of Plucker?
- Plucker is designed for off-line browsing on a small screen. It doesn't attempt to make HTML pages look like they appear on a monitor; instead, it tries to make them readable and useful.
- The history buttons always work, even from the home page.
- You can scroll nicely with the scroll buttons or the pen.
- On-screen indication of visited links.
- Image support
- Named anchors (such as <a href="#here">)
- Very impressive compression of records to save space on the device.
- Support for multiple databases and multiple versions of the same content.
- Search function for current page and all pages in a database
- Bookmarks
- Possible to copy URLs to a memo
- E-mail support/support for mailto links
- There are dozens more features not listed here, go ahead and give Plucker a go, and try them all out for yourself.
What features does Plucker not implement?
The following is a (non-exhaustive) list of unimplemented features. Apart from frames, we intend to include this functionality in the future:
- Frames (it might be possible to implement this in a links kind of way by rendering and converting the frames to tables, much like the Links browser).
- Document titles are not currently uploaded to the Palm device.
- Various HTML tags (e.g. <font>, <sup>, etc) are not supported.
- Javascript, DHTML, Java, CSS.
What other features are planned for the future?
Here is a list of other ideas for Plucker. No promises! A TODO list sorted both by category and by date can be found on the Plucker developer's page.
- We intend to integrate Plucker with the popular free desktop managers (namely, KDE and the Gnome). In these environments it would be great if you could Drag-'n'-Drop a URL into the Palm device for off-line viewing.
- The ability to modify parameters, such as the maximum link depth, from the Palm device, so that the next HotSync will retrieve more/less data.
- The ability to "send" a web page from the Palm device to an internet mail address.
- Cron-based gathering of HTML pages, prior to a HotSync (to significantly reduce HotSync time).
- Parallel gathering/parsing/conduit (to reduce HotSync time).
- Smart gathering/conduit; only update a document if it's actually changed. (Reduce hotsync time).
- Compatibility with AvantGo's .subs files, and the .site files that a similar product SiteScooper reads.
Of course, if you want to help add these (or other) features, feel free to implement them.
Where can I find Plucker eBooks?
Apart from the samples you can find at the Plucker web site, there are other sites that have eBooks as well.
Memoware has a growing collection of Plucker eBooks submitted by contributors and users of Plucker:
You can also find several Plucker eBooks at Byron Collins' site:
http://home.clarksville.com/~bcollins/index.htm
Curt 'n' Dave's Plucker-book Repository:
Nick Vargish's Bandersnatch Unpress:
http://unpress.bandersnatch.org/
The "Linux Documentation Project" (LDP) now releases all its HOWTOs and mini-HOWTOs in Plucker format. They are located under the 'Additional HOWTO-related items' at the following url:
http://www.tldp.org/docs.html#howto
or
