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 INI1 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.

Note

In the future, rinohtype will be able to generate an empty INI style sheet, listing all styles defined in the matcher with the supported style attributes along with the default values as comments. This generated style sheet can serve as a good starting point for developing a custom style sheet from scratch.

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 INI1 format with the .rtt extension. Here is an example configuration for the article template:

[TEMPLATE_CONFIGURATION]
name = my article configuration
template = article

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

[SectionTitles]
contents = 'Contents'

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

[VARIABLES]
paper_size = A5

[title]
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 three parts: title, front_matter and contents. The order of these parts can be changed (although that makes little sense for the article template), and individual parts can optionally be hidden by setting the parts configuration option. The configuration above hides the front matter part (commented out using a semicolon), for example.

The template configuration also specifies which style sheet is used for styling document elements. The DocumentTemplate.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. It determines which language is used for standard document strings such as section and admonition titles.

The Article template defines two custom template options. The abstract_location option determines where the (optional) article abstract is placed, on the title page or in the front matter part. table_of_contents allows hiding the table of contents section. Empty document parts will not be included in the document. When the table of contents section is suppressed and there is no abstract in the input document or abstract_location is set to title, the front matter document part will not appear in the PDF.

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 (although indirectly through the page base page template).

For document part templates, page_number_format determines how page numbers are formatted. When a document part uses the same page number format as the preceding part, the numbering is continued.

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 set the rinoh_template 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_article.rtt')

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

The TemplateConfigurationFile.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 Article documentation to discover all of the options accepted by it and the document part and page templates.

1(1,2)

see Supported INI File Structure in configparser