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.
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 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
[VARIABLES], each configuration section
in a style sheet determines the style of a particular type of document element.
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
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
It is also possible to completely override a style definition. This can be done
by setting the
base of a style definition to
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.
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.
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 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
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 (
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.
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
The standard document strings configured by the
language option described above can be overridden by
user-defined strings in the
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
followed by document part and page template sections. Similar to style sheets,
the variables can be referenced in the template configuration sections. Here,
paper_size variable is set, which is being referenced by by all page
Article indirectly through the
base page template.
For document part templates,
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
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
_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.
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
To render a document using this template configuration programatically, load
the template file using
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).resolve() config = TemplateConfigurationFile(script_path / 'my_book.rtt') # render the document to 'my_document.pdf' document = config.document(document_tree) document.render('my_document')
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
Refer to the Standard Document Templates to discover all of the options accepted by the templates and the document part and page templates.