Next: Chapter 15  Acknowledgments Up: Part I  User's Guide Previous: Chapter 13  The ScratchPad Application

Chapter 14
Troubleshooting

The RichDoc framework is an experimental project that is under rapid development. This means that the framework may contain bugs, many features are not finished, and some features and file formats may be changed without notice. If you still decide to use it on a production level, you should be very careful, save and backup your files regularly, and be prepared to face frequent problems. Namely, the framework has the following limitations:

• There is no undo/redo support. What you do to the document cannot be easily reversed. You should thus save your document frequently, so that you can revert to previously saved version if your document gets damaged, either due to your mistake, or due to the failure of the framework. If your document gets damaged during saving, you may attempt to recover it from emergency backup file, as described in Section 14.2.

14.1 Platform-specific problems

Although the RichDoc framework is implemented using technology supporting all major operating systems, there are some known problems with certain platforms. This section discusses some of them.

• On certain systems, it is difficult to set up input facilities to support national (non-ASCII) characters. For this purpose, the BookEditor application contains a user-level feature that maps keys on a keyboard to other, non-English letters. With this feature, you may type text in non-English language as if the underlying system supported it. The character map is currently provided only for the Czech language. You can switch between English and Czech keyboard by clicking the language button in the bottom-right corner of the main frame.
• The framework relies on the underlying window system to send notification when the main application window is deactivated. For instance, the main toolbar should be hidden upon deactivation. However, some systems fail to send such notification. For instance, if you use the cygwin X-server under MS Windows to display a RichDoc application running on UNIX system, deactivating the RichDoc application displayed in X-windows frame, by activating other window that itself is not an X-windows, does not cause the deactivated window to be notified. This causes the main toolbar window to remain visible, obscuring the newly activated window. This problem can be fixed only by configuring the RichDoc framework to display the main toolbar as a lightweight window. In lightweight mode, the toolbar is not a real window, but just a rectangular area painted into the host window, namely the RichDoc main frame. This solves the problem, but prevents the main toolbar to be dragged off the main frame of the RichDoc application.
• Some systems, namely cygwin X-server running under MS Windows, may not support drag & drop operations. There is again a possibility of enabling a lightweight drag & drop, which handles mouse events and simulates drag & drop operation on application level. This effectively enables the drag & drop, albeit with limited functionality.

14.2 File Backup and Recovery

Each time you save a document, the book editor creates an incremental backup of the file before it is rewritten with the new version. The word incremental refers to the fact that only files that are going to be modified are backed up. This keeps the size of backup files small. The backup files are ZIP files containing original content of modified ZIP files. The emergency file has the path $TEMP/ksmsa/richDoc/backup/$FILE-$ID/$DATE.zip, where $TEMP is the path to your system's temporary directory (usually c:\Documents and Settings\$USERNAME\Local Settings\Temp under Windows), $FILE is the short name of the file being saved, $ID is the global identifier of the file main section, and $DATE is the date of backup.

Note that this feature is intended for emergency purposes only, you should not rely on it as a kind of version management system. A better, more user friendly version management system is under construction.

Next: Chapter 15  Acknowledgments Up: Part I  User's Guide Previous: Chapter 13  The ScratchPad Application