Latest version: 1.4.6

README.listtexts

List texts in Mlmmj

List texts are stored in listdir/text and subdirectories of prefix/share/mlmmj/text.skel. They specify the content of various automatic emails that Mlmmj sends. They are provided in a number of different languages. The language to use for a list is chosen when you run the mlmmj-make-ml script and the appropriate files are copied into your listdir/text directory.

This file documents the following aspects of list texts:

Naming scheme

List texts are named following a scheme of:

purpose-action-reason-type

Mlmmj will look for the full four-part name first, then for files with shorter names obtained by dropping parts off the end, and finally for a file with a compatibility filename. It will use the first one it finds. (Note that use of the compatibility filename is DEPRECATED and will be removed in a future release.)

So, the complete search order is:

When using shortened names, the %ifaction%, %ifreason%, %iftype% and related conditionals can be used to customise the list text according to the values of the missing parts.

Mlmmj checks these three paths for each candidate filename, and then moves on to the next candidate filename:

The second path does not exist by default, but can be created by copying or symlinking the language of your choice to that path.

Note that this search order means that if there is a more specific list text in a system directory, it will override a less-specific or compatibility list text in the listdir. This may be surprising, and may change in a future version, so should not be relied upon. Best practice is to ensure each list has its own copy of all textx present in system directories, or none of them.

Supported list texts

The following list texts are supported. The compatibility filename (DEPRECATED) is given in brackets. Those with asterisks (*) are not yet used.

Format

List texts have the following format:

They are expected to be in UTF-8 encoding and have Unix line endings.

The headers should be formatted as they should appear in the mail message. They will begin the mail message. Header continuation via lines beginning with linear whitespace is supported.

Following the headers found in the list text, Mlmmj will output the following default headers, unless the same header is already provided in the list text.

The Subject: header is treated specially: it may include UTF-8 characters, which will automatically be escaped using the =?utf-8?q?…?= quoting mechanism.

(NOTE: the ‘digest’ list text is a bit different. See its description above.)

Both headers and bodies of list texts may include conditionals, formatting directives and substitutions. These are explained in the following sections.

Conditionals

Conditionals allow text in list texts to be included or omitted based on conditions. The following are available:

The text after the %if…% directive is only included if the condition is satisfied, until an %else% or %endif% is encountered. These behave as you would expect. The %else% is optional.

If a line with any of these conditional directives (%if…%, %else% or %endif%), after processing, contains only whitespace, the line does not appear at all in the output (the newline and any whitespace is omitted).

Furthermore, if the preceding processed output ends with a blank line, when an unsatisfied conditional is encountered which has no %else% part, that preceding blank line is removed (unless it is the blank line that ends the headers).

On the whole, this is what you would want and expect, so you probably don’t need to worry about it.

Note that when multiple parameters can be given for the directives, these have ‘or’ behaviour; to get ‘and’ behaviour, nest conditionals.

Wrapping

There are various directives available to assist with wrapping and formatting. Wrapping needs to be enabled for each paragraph with:

To turn off wrapping before the end of a paragraph, use:

To cater for various languages, there are a number of different wrapping modes that can be set. These can be set either before or after wrapping is specified, and can even be changed part way through a paragraph if desired. The following directives control them:

If a line with any of the directives in this section, after processing, contains only whitespace, the line does not appear at all in the output (the newline and any whitespace is omitted).

Formatting and comments

The following directives are available to assist with formatting and readability:

If a line with any of these directives, after processing, contains only whitespace, the line does not appear at all in the output (the newline and any whitespace is omitted).

Formatted substitutions

These formatted substitutions work with multiple lines, so are generally not appropriate for use in headers. They are:

Directives which include a list of items have the behaviour that each item is preceded and followed by the same text as preceded and followed the directive on its line; only one such directive is supported per line. Those which include a block of text have the behaviour that second and later lines are preceded with as many spaces as there were bytes preceding the directive; any text following such directives on the same line is omitted.

If a line with any of these directives, after processing, contains only whitespace, the line does not appear at all in the output (the newline and any whitespace is omitted).

Unformatted substitutions

Unformatted substitutions that are available are:

Escapes

These allow you to avoid special meanings of characters used for other purposes in list texts, as well as control the construction of the texts at a fairly low level.