The engine <introduction-layers-engine>
is configured through the configuration-ipc
and the configuration-iif
it includes. These files supply a set of keywords associated with values. There are two types of keywords: keywords-system
and keywords-user
.
Contents
System keywords configure the behavior of the engine <introduction-layers-engine>
and plugins <introduction-layers-plugins>
. System keywords are conventionally identified by the lowercase_with_underscore naming scheme.
Most system keywords are optional, with sensible defaults used in case they are omitted. There are a few mandatory keywords that will result in an error if they are not supplied:
keywords-system-data_config
Required for all documents that useplugins <plugin_api>
.keywords-system-input_xml
keywords-system-output_docx
The following is a complete listing of known system keywords. Custom tags and plugins may define additional keywords (or use existing ones for their own purposes).
The number of elements to include in the caption of a generated figure, table or heading reference before the object number. For example, say we have a figure that is the second figure under heading 1.2.3. Let's also say that it is the fifth figure under heading 1.2 and the 10th in the first section. In that case, the following table shows the resulting reference captions for different values of this keyword:
caption_counter_depth | caption |
---|---|
|
|
|
|
|
|
|
|
|
|
This keyword is optional. It defaults to 1.
The name of the configuration-idc
that configures the entire introduction-layers-plugins
.
This keyword is mandatory if the configuration-xml
specifies content generated by plugins, and completely ignored otherwise.
This keyword has no special meaning. However, it is implicitly set to the result of :pydatetime.datetime.now
when headers and footers are processed, if not set explicitly to something else. This makes it simpler to include information about the time of generation into the configuration-docx-headers-footers
. The implicitly-defined value is not available at any point besides the final keyword replacement step for configuration-docx-headers-footers
.
This keyword is optional.
The minimum cutoff level to dump to the file. To dump everything to the file use logging.NOTSET
, 0
, or 1
. The value can be a (case insensitive) string level name, a number or one of the constants in the :pylogging
module.
If keywords-system-log_file
is missing, this level will be ignored and nothing will be written to a file.
This keyword is optional. It defaults to logging.NOTSET
.
Logging Configuration <logging-configuration>
A sequence of include file <configuration-iif>
names. Include files can only add new keywords to the existing configuration. They do not overwrite any keywords that are already set. It is therefore important that include files are loaded in breadth-first order in the order that they appear in the sequence.
This keyword is optional.
The name of the configuration-docx
to use as a style and formatting template in the introduction-layers-template
. All the styles referenced explicitly by the configuration-xml
and implicitly in the future-work-user-defaults
must be present in this file. This file must also contain all the required formatting for configuration-docx-headers-footers
.
This keyword is optional. The default is the empty document provided by python-docx.
The name of the configuration-xml
file to use a content and layout template in the introduction-layers-template
. This template must follow the specification laid out in xml_spec
. It may contain additional tags, loaded through the keywords-system-tags
mapping.
This keyword is mandatory.
The name of the output file to write to. All messages with level greater than or equal to keywords-system-file_level
will be written to the named file.
If boolean :pyTrue
, a file with the same name as keywords-system-output_docx
, but with a .log
extension will be created.
This keyword is optional. If omitted, a log file will not be written, and keywords-system-file_level
is ignored.
Logging Configuration <logging-configuration>
A string that determines the contents of each line of the log file. The format of this string is the same as for the fmt attribute of a :pylogging.Formatter
. It uses %
interpolation syntax, with all the :pylogging.LogRecord
attributes as valid keyword replacements.
This keyword is optional. If omitted, the log message will be formatted according to '%(asctime)s - %(name)s - %(levelname)s - %(message)s'
.
Logging Configuration <logging-configuration>
Whether or not to log images in separate files, in addition to inserting them into the document. Evaluated as a boolean, regardless of the actual type of the value. It is up to individual tag handlers to respect this setting. This setting is independent of the other logger settings.
This keyword is optional. If omitted, it normally defaults to falsy, but custom tags may chose to interpret it differently.
Image Logging <logging-images>
Whether or not to print log output to the standard error stream. Evaluated as a boolean, regardless of the actual type of the value. If truthy, all messages with level greater than or equal to keywords-system-stderr_level
are written to standard error.
This keyword is optional. If omitted, it defaults to falsy, and keywords-system-stderr_level
is ignored.
Logging Configuration <logging-configuration>
Whether or not to print log output to the standard output stream. Evaluated as a boolean, regardless of the actual type of the value. If truthy, all messages with level greater than or equal to keywords-system-stdout_level
are written to standard error.
If falsy, keywords-system-stdout_level
is ignored.
If keywords-system-log_stderr
is set to truthy along with this keyword, then messages with a logging level greater than or equal to keywords-system-stderr_level
will not be sent to standard output.
This keyword is optional. It defaults to truthy.
Logging Configuration <logging-configuration>
The name of the generated document. If a file with the same name already exists, the program's behavior is determined by the keywords-system-overwrite_output
keyword.
This keyword is mandatory.
Determines how to handle the case where the file named by keywords-system-output_docx
already exists. The following options are recognized:
'raise'
Raise an error and abort.
'rename'
Keep prompting the user for a new file name until they select one that does not already exist. A default suggestion is generated, which can be selected automatically.
'silent'
Overwrite the existing file without further comment.
'warn'
Overwrite the existing file, but with a warning.
Any other value will trigger a fatal error
.
This keyword is optional. It defaults to 'raise'
.
The minimum threshold for messages that go to the standard error stream. This acts as an (exclusive) upper threshold for messages sent to the standard output stream as well. This level does not affect the level being logged to the file. The value can be a (case insensitive) string level name, a number or one of the constants in the :pylogging
module.
If keywords-system-log_stderr
is missing or falsy, this level will be ignored.
This keyword is optional. It defaults to logging.ERROR
.
Logging Configuration <logging-configuration>
The minimum threshold for messages that go to the standard output stream. This level does not affect the level being logged to the file. The value can be a (case insensitive) string level name, a number or one of the constants in the :pylogging
module.
If keywords-system-log_stderr
is truthy, keywords-system-stderr_level
provides the exclusive upper threshold for messages sent to standard output.
If keywords-system-log_stdout
is falsy, this level will be ignored.
This keyword is optional. It defaults to logging.WARNING
.
Logging Configuration <logging-configuration>
Sets up user-defined tags for the configuration-xml
. This is a mapping of tag names to user-defined tag-api-descriptors
. Values may be strings containing the fully-qualified names of the object to import, or the objects themselves. Both of the values in the following example are valid:
import my.custom.module
tags = {
'tag1': my.cusom.module.descriptor,
'tag2': 'my.custom.module.descriptor',
}
This keyword is optional.
User-defined keywords provide the data used to perform keyword replacements for the xml-spec-tags-kwd
tags in the configuration-xml
. They provide the per-report configuration of the basic content. User-defined keywords are conventionally identified by a CamelCase naming scheme. While the naming is not strictly a requirement, any lowercase_and_underscore name is automatically reserved for use as a system keyword <keywords-system>
.
In addition to direct definition in the configuration-ipc
/ configuration-iif
and insertion via the xml-spec-tags-kwd
tag, keywords can be computed through the xml-spec-tags-expr
tag in the configuration-xml
. The namespace in which an xml-spec-tags-expr
tag is evaluated is the existing mapping of keywords defined up to that point. The result is a new user-defined keyword. System keywords placed in an xml-spec-tags-expr
tag are not guaranteed to work correctly. This form of computation is provided to de-clutter the configuration-ipc
, and avoid information redundancy in the frequently edited file.