Imprint Configuration Files¶
This page contains a summary of the different files that users must provide to have imprint operate properly. Most of the files have their own reference pages and tutorial sections.
The different types of files are normally referred to by their extension. However, since internally files are always referenced to by their full name, none of the extensions listed here are actually mandatory. They are a default choice made for clarity and aesthetics, not functionality.
Contents
IPC File¶
The Imprint Program Configuration (IPC) file is the main script for a given output of imprint. It contains a set of Keywords mapped to values. Some of the keywords reference the other configuration files and configure the Engine Layer; others provide the user-defined data for content generation. The former are referred to as System Keywords, while the latter are User-Defined Keywords.
The file is written using Python syntax. Keywords are normal Python names. All
the restrictions that apply to Python variable names apply to keyword names.
Traditionally, System Keywords which direct the operation of the
Engine Layer start with lowercase letters, while
User-Defined Keywords containing per-document data start with uppercase letters.
Any keyword starting with a dunder (double underscore / __) is for internal
use by the configuration file, and will not be exposed to the core at all.
Modules imported into the configuration will not be exposed either.
Paths¶
Relative paths are resolved from the directory containing the IPC File, not the current directory. This makes it easy to copy entire configurations to different locations, and have them work out of the box. It also allows a user to generate multiple documents correctly without changing directories, and generally removes any dependence on the current directory.
In particular, this applies to the following system keywords, which are expected to contain a path or paths:
IDC File¶
A Imprint Data Configuration (IDC) file complements the core configuration of the IPC File by supplying the data configuration mappings for the Plugins Layer. The data configuration is referenced by the data_config keyword.
Like the IPC File, the IDC File uses Python
syntax. It follows a similar loading convention of removing any names starting
with a dunder (double underscore / __) from the loaded namespace. Unlike
IPC File, recursive includes are not allowed.
Each name in the global namespace of the IDC File corresponds to a plugin configuration. Normally, all the visible names in the file are Python dictionaries, but other mapping types are allowed.
The builtin <figure>, <table> and <string> tags support plugins. The plugins are structured so that unnecessary keys are silently ignored, making it possile to share data configuration across multiple tags. For example, a figure and a table generated from the same data set can share a data configuration, and therefore avoid the redundancy of repeated data source specs.
Configuration Names¶
Plugin tags in the XML Template are mapped to their configuration
objects by a special attribute, usually id. The name of the attribute is
set for each plugin’s descriptor.
A missing configuration aborts the generation of its particular content, but does not necessarily constitute a fatal error.
IIF Files¶
Imprint Include Files (IIF) have the exact same format as the main IPC File. Their purpose is to share content between multiple document configurations, using the includes keyword.
Include files are intended to supplement the main configuration file. The main configuration automatically overrides any duplicate keys that are found in the includes.
Includes may be done recursively. Since the engine does not check for infinite loops, use this feature carefully.
XML Template¶
The XML template defines the structure and content of the document. A full specification of the XML structure is given in XML Template Specification. Additional features can be added through the XML Tag API. The template is referenced by the input_xml keyword.
DOCX Stub¶
The DOCX stub is an empty template document that defines all of the styles and formatting. All the styles referenced explicitly in the XML Template, as well as the implicit default styles must exist in the stub. The stub is also responsible for setting up the page numbering, headers and footers. The stub is referenced by the input_docx keyword.