Next: Chapter 2 Editing Basics Up: Part I User's Guide Previous: Part I User's Guide

Chapter 1
Introduction

The RichDoc Framework is a comprehensive system that can be used for authoring, managing, exchanging and presenting documents, with emphasis on scientific documents. It is an experimental system developed within the KSMSA project. Its main goal is to validate the experimental results of Michal Ševčenko's dissertation project “Knowledge Support for Modeling and Simulation”, but it is published under the GNU license in the hope it will be useful for other users, too. Please refer to Chapter 14 for list of current limitations of the system. Users are also encouraged to contribute to the system, see Chapter 18.

1.1 Basic Philosophy of the RichDoc Framework

What is the difference between RichDoc framework and similar document management systems? There are two main groups of document management systems. The first type of systems, also called word processors, are based on the WYSIWYG (What You See Is What You Get) idea. That is, what you see on a computer screen during authoring a document is very similar, if not equal, to what you get when you print the document. This implies that word processors are presentation-oriented – they encourage the user to focus on visual rather than structural aspects of the document being edited. On the other hand, word processors have intuitive user interface, and are thus easy to use even by unexperienced users.

At the other side, there are markup systems, based on some markup language, such as LaTeX or HTML. You do not prepare the document visually, but using a text editor, where you enter the document text mixed with processing instructions (markup) needed to define structural and visual aspects of the document. Documents prepared with such systems usually are usually much more structure-oriented – the document data primarily represents the structure of the document, and the visual aspects (font size, style, margins etc) is inferred from this structure automatically using mechanism that is external to the document. This separation enables using the same document in very different contexts. For example, you may generate from the same document output in both HTML and PDF formats. However, using such systems is less comfortable and requires the knowledge of usually complex markup language.

We have tried to combine these approaches, and created a system that is semi-WYSIWYG. It is WYSIWYG in a sense that you are authoring the document visually, using graphical user interface. On the other hand, what you see on the screen primarily represents the structure of the document, not its final visual appearance. The fine visual aspects of the document may be modified later without modifying the actual document content. The content structure is thus much more similar to the traditional markup systems. In fact, there is a markup language behind the user interface of the system, but is designed to thoroughly support the visual nature of editing. Another design feature of our system, that makes it similar to markup language, is the “document consistency principle”. The principle rules that the document representation contains only those properties that the user actually explicitly specified. Properties that have not been specified explicitly get some reasonable default values, changeable without modification of the document. This clean structure is then propagated to output formats that can be generated by the framework, such as HTML.

One particularly useful feature of the RichDoc framework is that it forms a compact, portable software component that can be easily embedded into other software systems. The framework can not only create stand-alone documents, but also small documentation chunks that may be embedded to some superordinate function units, such as calendar entries, engineering files, or any other units for which it is useful to attach documentation to. All this with advanced features like tables, graphics or mathematics.

1.2 What RichDoc Framework is Not

The RichDoc Framework may be successfully used in situations when you need to create structurally rich documents with simple, consistent mapping between the document structure and its final visual appearance. If you need, for instance, to frequently change visual properties of document elements in an ad-hoc manner, you may find the RichDoc framework too cumbersome for accomplishing such task. The recommended best practice is to define for certain document elements, such as paragraphs or tables, a small number of classes (see Chapter 5), and merely assign that classes to existing elements. If this scenario does not fit to you, you may consider using more visually oriented text processors, such as Microsoft Word.

1.3 Requirements and Installation

The RichDoc Framework is pure Java application. It means that it runs on any platform that supports Java technology, including Microsoft Windows, many versions of the Unix operating system, and others. It has been tested on Microsoft Windows XP and RedHat Linux 9.1, but it is expected to run on other Java-enabled platforms as well.

Prior installation of the RichDoc Framework, you need to install the Java Runtime Environment (JRE) from Sun. Just visit http://www.java.com and download the JRE. If you have a JRE installed already, make sure that it is version 1.5 or later. If not, you should install the latest version.

Second step is to download and install a binary distribution of the RichDoc Framework. Two binary distributions are provided: Windows Installer to be installed on Windows, and compressed archive to be installed under UNIX. Installation under Windows is quite straightforward: just run the installer, and follow the instructions. After installation, the start menu is populated with appropriate shortcuts to run RichDoc applications. To install under UNIX, you need to unpack the distribution archive to an appropriate directory, and add the bin subdirectory to your PATH. Also make sure you have set the JAVA_HOME environment variable to the directory of your JRE installation. Then you can run any of the RichDoc programs by typing either bookEditor, scratchPad, or ioTool.

1.4 RichDoc Applications

Figure 1.1 Two RichDoc applications: (a) BookEditor, (b) ScratchPad

There are two basic applications based on the RichDoc framework. BookEditor, a program intended for authoring compact, standalone, scientific documents like books and articles, and ScratchPad, a handy tool for making personal notes. The two applications differ in a way they organize documents and their content, but the general content development procedures are the same. The rest of this document deals mostly with the BookEditor program. The ScratchPad program is then described in Chapter 13.

1.5 Getting Started

To start with the BookEditor, you must first create new document. To do this, use the File–New command from the pull-down menu. A New Document Wizard pops up, see Figure 1.2.

Figure 1.2 New Document Wizard

In the first step, you should specify the document class of the document, which represents its overall character. It may be either a Book, a Book with Parts, Article or Note. Setting the document class affects many aspects of the document, including its visual style, or the way the BookEditor numbers document sections. If you want to create your own document class or modify existing class, see Document Classes in the Programmer's Guide.

In the second step of the wizard, you specify the document title, language, and file. The document language specifies the primary language of the document. You may either select the language from the list, or press the Other button and select a language from the list of all languages. Note that although arbitrary language may be selected, most languages may have limited or no support, in which case English language rules apply to the document. To learn more about language support of the BookEditor, see Chapter 9.

1.6 Managing the Structure of the Document

The BookEditor frame shows the document content in the right part of the main window. The left part shows the document structure, see Figure 1.3.

[picture]
Editor Pane
Document Global Structure
Document Local Structure
[end of picture]

Figure 1.3 The BookEditor Frame

Note that in this manual, we call any structural part of the document, i.e. Part, Chapter, Section etc., with a generic name document section. The upper-left part of the main window shows the Document Global Structure pane, displaying overall document structure, i.e. all its sections, in a hierarchical way. You may use this pane to navigate to a section, or to change the document structure. To add new document section, right-click the parent section, and invoke Create Section from the popup menu, where Section stands for one of Part, Chapter, etc. To delete existing sections, select them with mouse, and press the Delete key. To move sections, drag them with mouse.

The Editor Pane in the right part of the main frame displays a part of the document selected in the Document Global Structure Pane. Note that the BookEditor always splits documents into editable parts at the level of chapters, that is, the Editor Pane displays one chapter at a time, if the document being edited is a book, or the whole document, if the document being edited is an article.

The Document Local Structure pane, shown in the bottom-left part of the main frame, displays the structure of the selected chapter in more detail. You may select the detail of the view using a toolbar at the top of the pane. Press to display the structure on section level, to display the structure on paragraph level, or to display the structure on the word level. This pane can also be used to change the document structure – you may drag nodes with mouse to move them around, drag them while holding the Ctrl key to copy them, or delete them by pressing the Delete key.