Basic Document Styling¶

rinohtype allows for fine-grained control over the style of its output. Most aspects of a document’s style can be controlled by style sheet files and template configuration files which are being introduced in this chapter. These files are plain text files that are easy to create, read and modify.

Style Sheets¶

A style sheet defines the look of each element in a document. For each type of document element, the style sheet assign values to the style properties available for that element. Style sheets are stored in plain text files using the Windows INI[1] format with the .rts extension. Below is an excerpt from the Sphinx style sheet included with rinohtype.

[STYLESHEET]
name=Sphinx
description=Mostly a copy of the LaTeX style included with Sphinx
pygments_style=friendly

[VARIABLES]
mono_typeface=TeX Gyre Cursor
serif_typeface=TeX Gyre Pagella
sans_typeface=Tex Gyre Heros
fallback_typeface=DejaVu Serif
thin_black_stroke=0.5pt,#000
blue=#20435c

[default:Paragraph]
typeface=$(serif_typeface)
font_weight=REGULAR
font_size=10pt
line_spacing=fixed(12pt, leading(0))
indent_first=0
space_above=0
space_below=0
text_align=JUSTIFY
kerning=True
ligatures=True
hyphen_lang=en_US
hyphen_chars=4

[fallback]
typeface=$(fallback_typeface)

[body]
base=default
space_above=5pt
space_below=0
text_align=justify

[emphasis]
font_slant=italic

[strong]
font_weight=BOLD

[literal emphasis]
base=emphasis
typeface=$(mono_typeface)
hyphenate=False
ligatures=False

[literal strong]
base=strong
typeface=$(mono_typeface)
hyphenate=False
ligatures=False

[inline math]
base=monospaced

[quote]
font_slant=italic

Except for [STYLESHEET] and [VARIABLES], each configuration section in a style sheet determines the style of a particular type of document element. The emphasis style, for example, determines the look of emphasized text, which is displayed in an italic font. This is similar to how HTML’s cascading style sheets work. In rinohtype however, document elements are identified by means of a descriptive label (such as emphasis) instead of a cryptic selector. rinohtype also makes use of selectors, but these are collected in a matcher which maps them to descriptive names to be used by many style sheets. Unless you are using rinohtype as a PDF library to create custom documents, the default matcher should cover your needs.

The following two subsections illustrate how to extend an existing style sheet and how to create a new, independent style sheet. For more in-depth information on style sheets, please refer to Element Styling.

Extending an Existing Style Sheet¶

Starting from an existing style sheet, it is easy to make small changes to the style of individual document elements. The following style sheet file is based on the Sphinx stylesheet included with rinohtype.

[STYLESHEET]
name=My Style Sheet
description=Small tweaks made to the Sphinx style sheet
base=sphinx

[VARIABLES]
mono_typeface=Courier

[emphasis]
font_color=#00a

[strong]
base=DEFAULT_STYLE
font_color=#a00

By default, styles defined in a style sheet extend the corresponding style from the base style sheet. In this example, emphasized text will be set in an italic font (as configured in the base style sheet) and colored blue (#00a).

It is also possible to completely override a style definition. This can be done by setting the base of a style definition to DEFAULT_STYLE as illustrated by the strong style. This causes strongly emphasised text to be displayed in red (#a00) but not in a bold font as was defined in the base style sheet (the default for font_weight is Medium; see TextStyle). Refer to Default Matcher to find out which style attributes are accepted by each style (by following the hyperlink to the style class’s documentation).

The style sheet also redefines the mono_typeface variable. This variable is used in the base style sheet in all style definitions where a monospaced font is desired. Redefining the variable in the derived style sheet affects all of these style definitions.

Starting from Scratch¶

If you don’t specify a base style sheet in the [STYLESHEET] section, you create an independent style sheet. You should do this if you want to create a document style that is not based on an existing style sheet. If the style definition for a particular document element is not included in the style sheet, the default values for its style properties are used.

Document Templates¶

As with style sheets, you can choose to make use of a template provided by rinohtype and optionally customize it or you can create a custom template from scratch. This section discusses how you can configure an existing template. See Document Templates on how to create a custom template.

Configuring a Template¶

rinohtype provides a number of Standard Document Templates. These can be customized by means of a template configuration file; a plain text file in the INI[1] format with the .rtt extension. Here is an example configuration for the Book template:

[TEMPLATE_CONFIGURATION]
name = my book configuration
template = book

parts =
    title
    ;front_matter
    contents
    ;back_matter
stylesheet = sphinx_base14
language = fr

[SectionTitles]
contents = 'Contents'

[AdmonitionTitles]
caution = 'Careful!'
warning = 'Please be warned'

[VARIABLES]
paper_size = A5

[front_matter]
page_number_format = lowercase roman
end_at_page = left

[contents]
page_number_format = number

[title_page]
top_margin = 2cm

The TEMPLATE_CONFIGURATION sections collects global template options. Set name to provide a short label for your template configuration. template identifies the document template to configure.

All document templates consist of a number of document parts. The Article template defines only a single part (contents) where the Book template defines four. The order of the parts can be changed, and individual parts can optionally be hidden by overriding the parts configuration option. The configuration above hides the front and back matter parts (commented out using a semicolon), for example. Note that empty document parts will not be included in the document. For example, when there are no index entries and the index is thus empty, the back matter part is omitted.

The template configuration also specifies which style sheet is used for styling document elements. The stylesheet option takes the name of an installed style sheet (see rinoh --list-stylesheets) or the filename of a stylesheet file (.rts).

The language option sets the default language for the document, which determines which language is used for standard document strings such as section and admonition titles.

The Article template defines an additional template option, abstract_location which determines where the (optional) article abstract is placed; in the title box or as part of the body text. This distinction is only visible when using multiple columns for the page contents (see columns).

The standard document strings configured by the language option described above can be overridden by user-defined strings in the SectionTitles and AdmonitionTitles sections of the configuration file. For example, the default title for the table of contents section (Table of Contents) is replaced with Contents. The configuration also sets custom titles for the caution and warning admonitions.

The others sections in the configuration file are the VARIABLES section, followed by document part and page template sections. Similar to style sheets, the variables can be referenced in the template configuration sections. Here, the paper_size variable is set, which is being referenced by by all page templates in Article indirectly through the page base page template.

For document part templates, page_number_format determines how page numbers are formatted. To prevent restarting the page numbering for a document part, set this to continue to use the same page numbering format at the preceding document part and continue with the next number.

The DocumentPartTemplate.end_at_page option controls at which page the document part ends. This is set to left for the title part in the example configuration to make the contents part start on a right page.

Each document part finds page templates by name. They will first look for specific left/right page templates by appending _left_page or _right_page to the document part name. If these page templates have not been defined in the template, it will look for the more general <document part name>_page template. Note that, if left and right page templates have been defined by the template (such as the book template), the configuration will need to override these, as they will have priority over the general page template defined in the configuration.

The example configuration only adjusts the top margin for the TitlePageTemplate, but many more aspects of the page templates are configurable. Refer to Standard Document Templates for details.

Using a Template Configuration File¶

A template configuration file can be specified when rendering using the command-line rinoh tool by passing it to the --template command-line option. When using the Sphinx Builder, you can specify the template in the rinoh_documents option in conf.py.

To render a document using this template configuration programatically, load the template file using TemplateConfigurationFile:

import sys
from pathlib import Path

from rinoh.frontend.rst import ReStructuredTextReader
from rinoh.template import TemplateConfigurationFile

# the parser builds a rinohtype document tree
parser = ReStructuredTextReader()
with open('my_document.rst') as file:
    document_tree = parser.parse(file)

# load the article template configuration file
script_path = Path(sys.path[0]).resolve()
config = TemplateConfigurationFile(script_path / 'my_book.rtt')

# render the document to 'my_document.pdf'
document = config.document(document_tree)
document.render('my_document')

The TemplateConfiguration.document() method creates a document instance with the template configuration applied. So if you want to render your document using a different template configuration, it suffices to load the new configuration file.

Refer to the Standard Document Templates to discover all of the options accepted by the templates and the document part and page templates.