Next: no title Up: část II Expert's Guide Previous: kapitola 18 Contributing to the RichDoc Framework

Kapitola 19
Styles

This chapter describes in more detail the style languages that are used to customize the RichDoc framework.

19.1 Visual Styles

Visual style language defines the rules that affect the process of visualization of a RichDoc document. It is quite similar to HTML Cascading Style Sheet system. The visual styles are organized into a cascade of style files. The anatomy of a style file is shown in obr. 19.1.

[picture]
Style File
Styles “display”
Style “title”
Style Value
“foreColor”
Styles “print”
Style “table”
Styles “html”
Styles “pdf”
Style
File
Style
File
[end of picture]

Obr. 19.1 Anatomy of Style File

Each style file contains visual rules, organized into structures of several levels:

Styles Level: The Styles structure groups rules applicable for different context of rendering, such as display, printing, exporting to PDF, etc. You may also create intermediate Styles structures containing general rules and inherit these from more specific Styles structures.
Style Level: The Style structure groups rules to be applicable to one element of the document, such as paragraph, table, word etc. Style structures have names that are used to match the structures with the object, see sekce 19.1.1. Like with styles structures, Style structures may inherit data from other Style structures.
Style Value Level: The Style Value represents single visual property to be applied to an object, such as foreground color, font size etc.

19.1.1 Matching and Inheriting Style Structures

The ultimate goal of the style mechanism is to assign to each document element, such as paragraph or table, a set of style values, such as foreground color or font size. When this assignment is done, we can use the style values to render the document element. Although we may do the assignment explicitly for each element, like in traditional word processors, we do it more systematically using external matching mechanism, see obr. 19.2.

[picture]
Document
section
title
section
section
title
p
p
table
table
p
matching styles to elements
inheriting values in document
inheriting values in style
[end of picture]

Obr. 19.2 Matching Elements to Styles

First, for each document element, we find the best matching Style structure. Since Style structures are actually containers of style values, this assignment effectively assigns the document element a group of style values. If we need a style value for particular element, we first ask its associated Style structure. If the value is not found, we attempt to inherit it from elsewhere.

If the Style structure has a parent Style structure (such as the “title” style in our example is derived from the “p” style), we first try to inherit the value from here. This kind of inheritance we call inheritance in style. If this fails, we attempt to inherit the value from the containing element (such as the “table” element in our example inherits from its containing “section” elements). This process we call inheritance in document.

Note that not all style values may be inherited in document. For instance, the margins of elements are not inherited, because that would add to the margin for each new level of containment in the document. The colors, on the other hand, are inherited in document: if we say that a section has specific foreground color, all its children inherit that color unless they override it.

Finally, we need to explain how we match Style structures to document elements. Each document has a tag name, and optional class name. Tag names of various types of elements are described in Section 17.2. They roughly correspond to HTML tag names. From the tag name and class name, we construct element name, which is either tagName or tagName#class. The element path is dot-separated list of element names of all parent elements of given element from the document root towards the element, including the final element. For instance, the element path of the table in obr. 19.2 is section.section.table. A partial element path is element path with some parts omitted. We may omit any number of dot-separated items from the beginning of the path, and/or any number of class qualifiers. For instance, the partial element paths of the path section#appendix.p#note are: p, p#note, section.p, section.p#note, and section#appendix.p. The element path or any of element partial paths are said to match the element. We say that p₁ is stronger match than p₂ if (a) p₁ is longer than p₂ in terms of the number of the dot-separated elements, or (b), if the paths have the same length, but p₁ has class qualifier sooner than p₂. The partial paths of our example path are listed in order of their strength, from the weakest one to the strongest one.

After these complicated definitions, we come to a simple conclusion: we match document element with that style whose name has best match with the element's path. For instance, we have style s₁ with name section#appendix.p and s₂ with name section.p#note. They both match our example element, but we match it with s₁, because it has stronger match. That is, we ignore the note class of the paragraph in favor of obeying the appendix class of the containing section.

19.2 Document Styles

Document style language defines various document classes (for books, articles, etc), and for each class defines rules how document material is named and numbered.

19.3 Bibliography Styles

Bibliography style language defines types of bibliographical references (see tabulka 6.1), and for each reference, how the linear textual representation, that is displayed in the Bibliography section of a document, is constructed from the database fields.

Bibliography style is defined in a XML file style.xml. The file has structure shown in obr. 19.3. The root element is styles, having style element for each type of publication. The type attribute of the style element corresponds to one of the publication type from tabulka 6.1. Its value is the English name of the publication type in Java convention, e.g. “technicalReport”.

<styles>
  	<style type="type">markup	</style>
   
  	<style type="type">markup	</style>
</styles>

Obr. 19.3 Structure of a Bibliography Style File

The markup contains the actual XML markup that generates the citation text. It may contain ordinary paragraph markup (see Section 17.2), plus the following special elements:

<dbField [b="text"] [a="text"] [from="record"] />

element that inserts one field from the record being rendered. dbField is the name of the field to be inserted, i.e. one of fields listed in tabulka 6.2. Again, the field name is formed from the field's English name in Java style, e.g. <howPublished />. The b attribute may be used to insert text (e.g. punctuation) before the field text, if the field text is not empty. Likewise, the value of the a attribute is conditionally inserted after the field text. The from attribute may be used for qualification of record associated with the record being rendered. For instance, if we render In Proceedings record, the title element refers to the in proceedings title. If we want to refer to the title of the containing proceedings, we should use <title from="pd" /> .

If the field contains multiple values (such as the author field), all values are inserted with appropriate punctuation used to separate the values.

<name type="type" />

Inserts the localized name of the publication type. For instance, <name type="phdThesis" /> inserts the phrase “PhD Thesis” in an appropriate language.

<s value="key" />

Inserts the localized string of any kind. The key identifies the string to be added. For instance, <s value="and" /> inserts the conjunction “and” in an appropriate language.