Next: Chapter 7  Version Management and Localization Up: Part I  User's Guide Previous: Chapter 5  Managing Visual Styles

Chapter 6
Index, Glossary and Bibliography

This chapter describes how to add index and glossary to your books, and how to manage database of bibliographical references.

6.1 Creating Index and Glossary

Quality printed books have index and/or glossary sections in their end. The BookEditor framework supports authoring the index and glossary, and generates the corresponding sections automatically. The index section usually contains alphabetically sorted list of concepts, with references to pages where concepts are mentioned or defined. The glossary section contains a list of concepts, each accompanied with short definition.

To create an index, you should define the list of concepts, and associate them with elements in the document body. We shall call a definition of single concept an index entry. An index entry is associated with one or more elements in the document body, see Figure 6.1. An index entry may also provide a glossary definition. To define index entries, select the Index... command from the popup menu. An Index Editor window pops up, see Figure 6.2.

Figure 6.1 The Index Structures

Figure 6.2 Index Editor Window

The window contains four panes; the Index Entries pane contains a list of all index entries in the index. The Selected Entry pane contains an editor where you can edit the components of the selected entry. The Glossary Definition pane provides a space for optional glossary definition corresponding to the selected entry. The Associations pane displays a list of elements in the document that are associated with the selected entry.

As we can see in the figure, the entries may be split into several components, specified from the most important, to the less important ones, such as graph—connected. Some entries may share some of the first component(s), and differ only by the less significant components (e.g. search—breadth-first, search—depth-first). Such component sharing affects the final visual appearance of the index section in usual way; the common component(s) appear only once, and the secondary components are listed for the common primary component. In the index editor, however, all components must be explicitly specified. Also note that index entries may have several alternative names. The second entry in our example has two names: graph—connected, and connected graph. The entry thus appears twice in the generated index section. The final appearance of the index section in our example is shown in Figure 6.3.

Figure 6.3 Final Appearance of the Index Section

To add new entry to the index, press the Add button, and update the entry text in the Selected Entry pane. To create alternative names, just put each name on a separate line. To create names with two or more components, put the secondary component below the primary one, and use the hyphen (‘-’) character to indent the secondary component. To define a third-level component, put it below the second-level component, and use two hyphens to indent it, etc. You may use as many levels as you need, but it is recommended not to use more than three levels.

Our example also shows that you may use not only plain text, but also formatting (italic, bold, etc.), inline equations, inline graphic, etc. In fact, each component of an index entry name is a full-featured paragraph.

When index entries are defined, we want to associate them with the objects of the document content. We may associate entries with existing objects, such as sections and paragraphs, but more frequently, we want to associate them with parts of paragraphs corresponding to phrases. To associate an index entry with document element, select the index entry in the list, and place the cursor in the document editor area to the desired element, or select a desired phrase. Then press the Associate button. If some text is selected, it is associated with the selected index entry. If no text is selected, a menu pops up, offering various options of which element may be associated with the entry. After selecting particular object from the menu, the association is established.

It is also possible to define index entries the other way round: first to locate a phrase in the document, and then to define an index entry, associated with that phrase. This can be done using the toolbar button from the formatting group of buttons (under the button). For example, after selecting the “data structures” phrase in the editor and pressing the , an Index Editor pops up as shown in Figure 6.4. We see that index entry identical to the selected phrase is added to the index, and is associated with the phrase occurrence in the document content. If the phrase is not appropriate for the index entry name, we may easily modify the name of the index entry, but the association is preserved.

Figure 6.4 Creating Index Entry for a Phrase

If you later decide to merge two or more index entries into a single index entry, you may select them in the Entries pane (use arrows with Shift key, or click entries while holding the Ctrl key), and then press the Merge button. The list of occurrences associated with original index entries is merged into a single list, as well as the names of the selected index entries.

You may cancel association of index entry with document element, by selecting the association in the Associations pane, and pressing the Delete key. You may also delete the whole index entry and all its associations, by selecting the entry in the list and pressing the Delete key.

6.2 Creating Bibliographical References

For scientific documents, you often want to attach a list of bibliographical references to the end of the document, and refer to the list from within the document text. This process is separated into several independent tasks:

1. Create an inter-document database of bibliographical references.
2. Create a list of references to be associated with concrete document, to be printed in the Bibliography section.
3. Put references to the list created in step 2. into the document text.

6.2.1 Managing the Database of Bibliographical References

To add bibliographical references to your document, you must first prepare the database of such references. To manage the database, select the Bibliography... command from the popup menu, and press Database button. A Bibliography Database window shows up, see Figure 6.5.

Figure 6.5 The Bibliography Database Window

The top part of the window displays a hierarchical list of bibliographical references. You may organize the references into groups. To create a new group, press the New Group button. To add new record to the selected group, press the New Item button. When you select a record in the list, the list in the bottom part of the window is populated with details of the selected record.

Firstly, you should select the type of the bibliographical reference. The possible types of bibliographical references are summarized in Table 6.1. When you select a type, a list below the type box is filled with fields corresponding to the selected type. Fields that are printed in bold are mandatory; if they are omitted, the field name is printed in red color to draw your attention. Fields that are not printed in bold are optional and may be omitted. List of all fields is summarized in table Table 6.2. The bold items correspond to mandatory fields.

Each record must have explicitly specified language. The language of the record should always correspond to the language of the publication. If you need to use a record in language different from the publication language, you may translate some fields to the required language. For instance, if you want to cite a Czech book from an English publication, you should create the bibliographical record of the book in the Czech language, and then translate some fields (e.g. the title) to English. The framework then uses the English title if you reference the record from an English context.

The Author and Editor fields may have multiple values, if the publication has more than one author or editor. If you want to provide more than one author or editor, you may either click the Author or Editor field and drag down, or just press comma (‘,’) while editing the field. Extra fields may be deleted by selecting appropriate row(s) in the table, and pressing Delete. You should not put more than one name to a single field!

Information about single reference may be distributed into more than one record. For example, information about an article published in conference proceedings is distributed into two records: In Proceedings, describing details of the article (title, authors, etc.), and Proceedings, describing the proceedings itself (editors, publisher, year of publication). In BibTeX, this information is mixed into a single record. If you create a new In Proceedings record, for instance, the window provides rows for each value of the record, the last row being value named ‘In’. If you click the value, two options show up. New..., which creates new Proceedings record and associates it with In Proceedings record, and Browse..., which lets you browse for existing Proceedings records. When you choose any of the two options, the fields from the selected record are appended to the list, see Figure 6.6.

Figure 6.6 Chaining Records of Bibliographical References

6.2.2 BibTeX Compatibility

As you might have noticed, the BookEditor bibliography management system is similar to BibTeX. BookEditor contains a facility for importing BibTeX (.bib) files into RichDoc bibliographical database. The facility automatically performs necessary transformations, such as splitting multi-value fields (Author and Editor) into separate fields, and splitting compound records (Article, In Collection, In Proceedings and In Book) into multiple associated records. Please note that this facility may not support all BibTeX features, namely string macros.

6.2.3 About the Bibliographical Database

The bibliographical database being edited by the Bibliography Database window is intended for personal use. It is stored in a file ~/ksmsa/bibliography/.database, where ~ denotes the home directory, under Windows can be usually found at c:\Documents and Settings\username. If you want to use the database on several computers, you should copy the database file accordingly. A system of inter-personal management of bibliographical references is not yet implemented.

Please note that the binary database format may not be compatible across different versions of the RichDoc framework. If you want to upgrade the framework, you should first dump the database to XML file, and import it from that file after upgrading.

6.2.4 Referencing Bibliography from the Document

When the database is prepared, you may create a list of references to be associated with particular document. To insert references to a list of document references, select them in the Bibliography References window, and press the Add Item button. The Bibliography Database window closes, and the selected references are added to the list of document references, see Figure 6.7.

Figure 6.7 List of References Associated with a Document

Now you may put references to the list defined in the Bibliography window, into the document. To insert the reference, select it in the list, and press the Add Reference button, or just double-click the item in the list. A text containing the ordinal number of the reference, such as “[10]”, is inserted into document. The text is permanently associated with the reference, and the number is updated automatically when necessary.

Next: Chapter 7  Version Management and Localization Up: Part I  User's Guide Previous: Chapter 5  Managing Visual Styles