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 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
[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
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
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:
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 (
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.
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
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
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 (although indirectly through the
page base page template).
For document part templates,
determines how page numbers are formatted. When a document part uses the same
page number format as the preceding part, the numbering is continued.
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.
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
To render a document using this template configuration programatically, load
the template file using
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 config = TemplateConfigurationFile('my_article.rtt') # render the document to 'my_document.pdf' document = config.document(document_tree) document.render('my_document')
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
Refer to the
Article documentation to discover all of the options
accepted by it and the document part and page templates.