Jarnal - Troubleshooting

Release Notes

Known Problems and Limitations:
  • Memory usage and crashes
  • Pdf backgrounds do not work properly in applets.
  • If you save a pdf file overwriting a pdf file you are currently annotating, Jarnal will crash.
  • When you paste text from an external app (via clipboard), the doc 'jumps' to the top of page.
  • If you zoom in too much you will run out of memory.
  • If you modify jarnalshell.conf while jarnal is open, it will overwrite your changes when it exits.
  • IRS pdf tax forms have a strange "non-printing" segment at the top. This appears when you open the pdf, but disappears when you print to pdf, causing whatever annotations you made to be improperly aligned with the form. There is a work-around. Open the form in Jarnal; print it to pdf without annotating. This removes the "non-printing" segment. If you now annotate the new pdf you created everything will work normally.
  • You may need to install the JAI for additional image support. You will need to do this to view TIFF files or to use pdftoppm as an external renderer.  

    Sun provides the JAI addon with support for additional graphical formats including multi-page tiff for faxes and ppm files used with xpdf for pdf support on unix systems. For Linux and Windows go to http://java.sun.com/products/java-media/jai/ and download and install JAI for your platform. For the Mac go to http://www.apple.com/downloads/macosx/apple/java3dandjavaadvancedimagingupdate.html. Note: there seem to be two JAI's to install - the connection between them is not clear to me. Make sure to install the "JAI Image I/O API" along with the JAI itself.

  • Java 1.5/1.6 are broken when used with the composition managers in Linux (compiz or beryl). You will just get grey boxes. Turn them off (sometimes called "desktop effects") or download a test version of 1.6 that fixes the problem. It is nearly impossible to find - but it is at http://download.java.net/jdk6/6u1. I also have a report (I have not tested it personally) that setting the AWT_TOOLKIT variable thusly injarnal.sh prior to running jarnal: export AWT_TOOLKIT=MToolkit resolves the problem.
  • Sun Java build 1.5.0-b64 is broken and issues a mouse-click at the end of each stroke, leading to blobby looking strokes. To fix, upgrade to a more recent version of Sun Java. Build 1.5.0_04-b05 works fine, for example. To check your version run java -version at the command line.
  • Loading fonts can crash some Sun VMs causing you to lose all your work. This is a Java error over which I have no control. I have tested all the fonts on my machine with the most recent 1.4.2 and none cause a crash, so it appears to be fixed. You should regardless upgrade for security reasons.
  • Html cut and paste does not work prior to Java 1.5.
  • Java support for additional image formats (bmp, png, pnm and tif) will not work with an unsigned applet loaded with a browser due to security restrictions. The solution is to convert image formats to .jbg (zipfile of jpg images) on the server. Here is source code for an (untested) java class with a single static method that reads an inputstream on an arbitrary java supported image file, and writes the corresponding jbg file on an outputstream. 

Jarnal screenshot

Memory Usage and Crashes

If Java runs out of memory Jarnal will crash and lose all your work. Since there is no way to trap this type of error to save your work it is importnat you allocate enough memory to Jarnal that it won't crash. As a guide on the bottom of the Jarnal window the information bar reports the current memory usage. If that number is near 100% - and in particular if it is red - save your work, close Jarnal, and allocate it more memory. Here are some guidelines.
1. Until Java 5 the default amount of memory allocated a Java virtual machine was 64M. This is not nearly enough.
2. The amount of memory can be increases on the command line that starts Java. The scripts that come in the Jarnal installation package use 192M. This is set on the command line by the command line switch -Xms192m. This should be enough for most purposes, but you can increase it if necessary.
3. As of Java 5 some machines are classed as "servers". If you run java -h from a command line and see The default VM is server, because you are running on a server-class machine mixed in with the information it prints out then the default amount of memory is not 64M, it is 1/4 the total amount of physical memory on your machine up to a maximum of 1G. For example, on one machine I have 4G memory; it is a server class machine. If I run Java without setting the memory - deleting the switch  -Xms192m from the command line script - then Java runs with 1G of memory, quite a lot more than 192M.
4. If you want to use very large files (100+ page pdf documents) 192M is not enough memory. If you have a modern machine with 2-4G of physical memory, try setting the memory to 1-2G. I got very good performance on large documents with -Xms1920m, 10 times the usual setting.

Thanks to Marco Poletti for helping figure this out.