Configuration

Muttprint -- User's guide
Prev |  | Next

# 3. Configuration

## 3.1. The configuration file

Some things could be configured in Muttprint. This is permanently done in the configuration files `$HOME/.muttprintrc` (only for the current user) or `/etc/Muttprintrc` (global for all users). User settings override global settings.

You can also specify an additional configuration file with the `-r `filename`` option. This file is read finally and overwrites command line settings, too. This additional configuration file is useful for using more than one configurations and you can combine it with some Hooks of Mutt.

The configuration file is structured in a way that values are assigned to different variables -- this is different from `.muttrc`. The name of the variable stands first and is case sensitive; take over them exactly. Then follows a equal sign (`=`) without any whitespaces. At last, there's the value. Quotes (`'` or `"`) are optional.

An example for a configuration file is distributed with Muttprint (`sample-muttprintrc`). If you've installed a RPM or Debian package, you'll find it in `/usr/share/doc/packages/muttprint/`.

An example for a correct assignment:

    VARIABLE=value

Normally the script works without any adapts. But it is recommended to inform about the possibilities you have.

### 3.1.1. Printer

If Muttprint should not print on the default printer, you can change this by setting `PRINTER` to the correct value.

To print in a file, you could use following syntax, the name (and location) of the file is freely chooseable:

    PRINTER="TO_FILE:/foo/bar/test.ps"

If duplex printing is enabled, Muttprint creates a second file with the prefix `2`, e. g. `test2.ps`.

If this variable is not set, Muttprint evaluates the environment variable `PRINTER` and uses its value to get the printer. Normally it is set to the default printer. If you use CDE (which is common on commercial Unix systems) its configuration file is read to get the default printer.

As of version 0.70 Muttprint offers direct support of the new printing system CUPS. It will be turned on by setting `PRINT_COMMAND` to `CUPS`. Alternatively it is possible to set it to an arbitrary command which contains the string `$CUPS_OPTIONS` which is substituted by the CUPS printing options.

| You could use the setting `gv -` to have a print preview. This is useful if you test different settings.

### 3.1.2. Printing command

Muttprint uses lpr to print in its default setting. If you would like to use another printing command, set `PRINT_COMMAND` to the program you would like to use. The string `$PRINTER` is replaced by the chosen printer. The default is `lpr -P$PRINTER`.

| You could use the setting `gv -` to have a print preview. This is useful if you test different settings.

### 3.1.3. Penguin

As a default setting it is printed a little penguin on the right top of the page. If there should be another picture or if the penguin has another location as Muttprint assumes, you can configure this by setting the `PENGUIN` variable to the right value. The picture must be in Encapsulated PostScript (you could use convert from the Image Magick package for converting your favourite picture into EPS) and it is scaled to a height of 2 cm (5.08 in). The logo must not have a higher width than height.

If `PENGUIN=on`, Muttprint tries to find out the location of the penguin file. (Read the source code to find out, where Muttprint searches.) This is the default setting.

Additionally, Muttprint comes with some example pictures that are already converted into the EPS format. After the installation, you'll find this in `/usr/share/muttprint`.

If the printing of the graphic should turned off, set `PENGUIN` to the value `off`.

### 3.1.4. Printing of X-Faces

X-Faces are black and white pictures with a size of 48 x 48 pixels, that could be included as mail header (the `X-Face:` header) in each message. This is no "official" standard but it is spread especially in news articles.

Muttprint supports the printing of this picture instead of the image specified with the `PENGUIN` variable. To do this, set `XFACE` to `on`. If there's no such header, the `PENGUIN` picture (or nothing) is printed.

To work right, following two programs are required:

- convert from the Image Magick package

- uncompface

Both programs should be part of common Linux distributions and can simply be installed.

In any case you must make sure that this header is really dumped to Muttprint. If you use Mutt, see Section 2.3.1 for a correct configuration. Otherwise read the documentation of your mail software.

### 3.1.5. Duplex printing

Muttprint allows manual duplex printing. It prints odd pages at first, waits a while and prints then even pages.

Muttprint needs the speed of your printer to calculate the time when the printing of even pages will start, see Section 3.1.9.

To activate the duplex printing, set `DUPLEX` to `on`.

If you own a real Postscript printer and if this printer has duplex capabilities, you should set `DUPLEX` to `printer`. This changes the Postscript code in a way that tells your printer to enable automatic duplex printing; for CUPS a corresponding option is used.

### 3.1.6. Paper save mode

It's possible to print two pages on one page in landscape. This allows you to save paper and ink and increases the printing speed. This makes only with the paper format DIN A4 sense because two reduced pages fit exactly to one sheet.

To enable this mode, set `PAPERSAVE` to `on`.

If you only want to activate the papersave mode if more than one page is printed, set `PAPERSAVE` to `optional`.

### 3.1.7. Date

The `DATE` option allows two settings: `original` and `local`. If set to `original`, Muttprint print the date unchanged as it is in the mail header, i. e. in English and in the sender's time zone.

If you set this option to `local`, Muttprint converts the time zone in the time zone of the system and prints the date in the local language [1].

The format of the date could be specified with the `DATE_FORMAT` variable. The argument is a format string, e. g. `"%A, %d. %B %Y %H:%M:%S"`. The quotation marks are necessary because the string contains spaces. The strftime(3) manpage contains details about it.

### 3.1.8. Format of printed mail addresses

There are different ways of writing mail address and realname together in the mail header. Here are some examples:

- `Bernhard Walle <Bernhard.Walle@gmx.de>`

- `"Bernhard Walle <Bernhard.Walle@gmx.de>`

- `Bernhard.Walle@gmx.de (Bernhard Walle)`

The used format depends of the mail program of the sender; all three are correct. If the variable `ADDRESSFORMAT` is set to the value `original`, the addresses are printed unchanged.

If you would like uniform mail headers, you can assign a format string to this variable. The default setting is `"%r <%a>,\n"`. You can use all characters as format string, `%r` is substituted by the name ("real name"), `%a` by the mail address and `\n` prints a newline. The paling quotes are necessary because of the spaces. A newline at the end means that every address is printed in a separate line if more than one address is given. Muttprint removes newlines and commas after the last address automatically.

Additionally, particular parts could be printed bold or italic. If a part is embedded in stars (`*`), the text is bold; slashes (`/`) means italic printing; nesting is possible.

Here is just another example for a format string (this is the one that I use): `"/%r/ (%a),"`.

### 3.1.9. Printing speed

As mentioned above, Muttprint requires the duration which your printer needs to print one page. This setting is done by setting the variable `SPEED` to the value in seconds (only integers are allowed). Default is 30 seconds (`SPEED=30`).

### 3.1.10. Font

You could use different fonts for the printing. The correspondent variable is names `FONT`. `Latex` (standard steting) means the standard LaTeX font of the EC family. `Latex-bright` uses Computer Modern Bright. This font is not available on many systems because of its license[2]. Another choice is `Latin-modern` for the lmodern fonts (not available on most systems).

There are several Postscript fonts which are possible here: `Times`, `Palatino`, `Utopia`, `Charter` `Bookman`, `CentSchool` (New Century Schoolbook), `Chancery` (Zapf Chancery), `Helvetica` or `AvantGarde`.

Of course the fonts has to be installed on your system. As the LaTeX distribution teTeX is standard on Linux systems, this should be no problem.

### 3.1.11. Font size

You can control the font size with the variable `FONTSIZE`. Only the values `10pt`, `11pt` and `12pt` are possible.

### 3.1.12. Formatting of the mail body

The mail body is split into two parts: text and signature. If there is a signature and it should not be removed (see Section 3.1.18), this two parts can be formatted separately.

Muttprint uses the LaTeX package `fancyvrb.sty` to print the body, which offers lots of formatting options. The options which are passed to the `Verbatim` environment could be set with the variable `VERBATIMNORMAL` (for the normal text) and `VERBATIMSIG` (for the signature).

You'll find the exact syntax in the documentation of `fancyvrb.sty`, which could be viewed with the command texdoc fancyvrb. Normally, the signature is printed in Italics. You can print borders, too.

If you don't want a separate formatting of mail body and signature, just set `VERBATIMSIG` to `raw`. If so, the signature is treated as normal mail text and is printed like this (including the signature separator).

Here're some examples:

- `fontshape=it,frame=topline`: italic font, border above the block

- `fontfamily=helvetica,fontseries=b`: Helvetica font, bold

- `numbers=left,stepnumber=5`: Line numbering each fifth line

### 3.1.13. Margin settings

The margins could be set by modifying following variables: `TOPMARGIN` (top margin), `BOTTOMMARGIN` (bottom margin), `LEFTMARGIN` (left margin) and `RIGHTMARGIN` (right margin).

This variables should be set to a integer, which specifies the margin in millimeters (mm). Other measuring units are not possible; 25.4 mm are 1 inch.

### 3.1.14. Wrapping long lines

The length of the longest line is specified with the `WRAPMARGIN` variable. Longer lines are wrapped automatically but shorter lines are not joined.

### 3.1.15. Rules under/over head- and footline

There could be printed a rule under the headline resp. over the footline. They are turned off as default.

Set the variables `HEADRULE` resp. `FOOTRULE` to `on` or `off`.

### 3.1.16. Design of the first pages

There exists different possibilities to highlight the mail headers on the first page. Here is a listing of them:

Style | Description
--- | ---
`plain` | no rules
`border` | rule after the headers (default setting)
`Border` | thick rule after the headers
`fbox` | simple box around the mailheaders
`shadowbox` | shadowbox around the header
`ovalbox` | box with rounded corners around the header (thin lines)
`Ovalbox` | same as `ovalbox` but thicker lines
`doublebox` | box with double lines around the header
`grey` | grey background behind the headers
`greybox` | same as `grey` but with a additional black box

Set the variable `FRONTSTYLE` to a value from the table above.

### 3.1.17. Paper format

To set the paper format, set `PAPER` to the right value. Possible are only `A4` and `letter`.

If there exists a file `/etc/papersize` as usually on Debian systems, it is evaluated, too. Own settings overwrite this system settings.

### 3.1.18. Cut signature

Often the signature contains useless information or advertising and should therefore not be printed. Muttprint is able to cut the signature, if it was separated from the mail by using "`––` " -- take a look at the whitespace (some mail clients don't generate a correct separator).

To do this you've to set `REM_SIG` (this means "remove signature" to the value `on`.

If Muttprint should recognize other separators to indicate the beginning of a signature, you can set `SIG_REGEXP` to a regular expression in Perl syntax. The default setting is `^-- $`. If you don't know what this notation means, just don't change the default.

### 3.1.19. Omit quoting

Often the author of the mail does not quote sensibly but attaches the whole mail so that the printing becomes very long and confusing.

If `REM_QUOTE` is set to `on`, the quoting will not be printed. Muttprint detects the quoting by using the same regular expression that Mutt does in its standard configuration. So the text which is color emphasized from Mutt should omitted in the printing. This corresponds to the toggle quote function (Shift-t) on screen.

### 3.1.20. Printed headers

Normally only the interesting headers are printed. You could change this settings with the variable `PRINTED_HEADERS`. Specify each header separated with a underline (`_`).

The order is important for the printing. The evaluation is case-insensitive. Headers that doesn't exist are ignored. For bold printing embed the name of the header in stars (`*`), for italic printing do the same with slashes (`/`).

The default setting is:

    PRINTED_HEADERS="Date_To_From_CC_Newsgroups_*Subject*"

One more example for a sensible setting:

    PRINTED_HEADERS="/Date/_To_From_*Subject*_X-Mailer"

### 3.1.21. Own LaTeX code

The variable `LATEXCODE` is for people who are very familiar with LaTeX and would like to customize the printing without changing the source code of Muttprint. For example, it is useful to use own fonts.

Besides `LATEXCODE` there are five additional variables (`LATEXCODE1` till `LATEXCODE5`) to split your LaTeX code nicely. This variables are integrated in the code in this order.

| You could print the mail text in a proportional font (instead of typewriter font) with following setting:
    LATEXCODE="\renewcommand{\ttdefault}{\rmdefault}"

### 3.1.22. Printing in the background

Normally Muttprint runs in the foreground and terminates after the print procedure is finished successfully. This simplifies the output of error messages. On modern computers, the printing of normal mails takes only a few seconds. (An exception could be the first run of Muttprint because LaTeX has to create lots of font files.)

Sometimes it could be useful to put Muttprint in the background immediately. So you can use the your mail client instantly after you started the print job. This is only recommended if you already tested Muttprint to make sure that there must be printed no error messages.

For this, you can assign the variable `BACKGROUND` the value `on`. In the debug mode (see Section 3.1.23) this option has no effect.

### 3.1.23. Error messages

The output of latex and dvips are not displayed. If there are any problems, it would be helpful to read this output. Therefore you should set `DEBUG` to `1` in your `.muttprintrc`. Now Muttprint creates a log file named `/tmp/muttprint.log` in the next run so that you can watch the error messages. This could be helpful for all bug reports, too.

## 3.2. Command line options

Most configuration settings could be made by command line options as well. The advantage is a easier integration in the mail client (e. g. with own macros).

You find a detailed description of all options with muttprint `-h` or or in the muttprint(1) manpage.

The effects of this options are the same as in the configuration file but command line settings override all other settings.

## 3.3. Different languages

### 3.3.1. Overview

The script supports different languages. In contrast to old versions the configuration is done not with the configuration file but with the locale environment of your operating system.

Under Unix environment variables are used to control the locale settings. There are different variables which control different aspects of localization. For example a user might English text messages but he wants to work with German texts (and the Western European character set).

For Muttprint the variables `LC_ALL`, `LANG`, `LC_MESSAGES`, `LC_CTYPE` and `LC_TIME` are important. `LC_CTYPE` specifies the encoding used for input and output. Muttprint expects its input (especially the mail that should be printed) in this charset and prints all messages in this charset. `LC_MESSAGES` specifies the language for messages and the printing and `LC_TIME` is responsible for date and time information. The date in the footer is generated by LaTeX and so it's in the language specified by `LC_MESSAGES`. `LC_ALL` overwrites all other `LC_` variables, so if it's set, the other have no meaning anymore. `LANG` is a fallback: If, for example, `LC_MESSAGES` is not defined `LANG` is used to determine the language for messages. Normally you only set the `LANG` variable.

In the first place the language adaptions affect some words in the printing, which means the labels of the mail header and the date.

Also the encoding is determined by the locale environment of your system. There's no way to do this manual as in older versions of Muttprint anymore. The number of supported charsets is limited because of the usage of LaTeX. Following encodings are supported: ISO-8859-1 (Western European languages), ISO-8859-2 (Eastern European languages), ISO-8859-3 (South-Eastern European and other languages), ISO-8859-4 (Scandinavian and Baltic languages), ISO-8859-9 (Turkish), ISO-8859-15 (ISO-8859-1 with some modifications, especially the Euro sign), KOI8-R (languages with Cyrillic characters, e. g. Russian) and UTF-8.

The support of UTF-8 is not complete. LaTeX itself uses 8-bit character sets. This means that it could be only this subset of characters used, which are usual in the current locale environment. So Cyrillic letters could only be printed in a Russian environment. Maybe this changes in future but the main problem is LaTeX.

### 3.3.2. Translation file

The Muttprint translation files are located in the `share` directory and have the name `translation-`language`.pl`. You could add new files in this directory without any changes on the Muttprint script. Not only the headers mentioned above but also the help message are translated here.

For new translations take any file as template, copy it and translate it. If you would like to provide your translation to other users, just send me the new file with a e-mail and I'll add it in the next release.

Important: The encoding of this file must be (independent of the current locale environment) UTF-8. Read the file `README` which is in the `translation/` directory of Muttprint (the source code distribution).

### Notes

[1] | This works independent from the translation file by using the functions of the operating system.
[2] | You can download this font and install it on your computer from the CTAN. You find the fonts in CTAN:/tex-archive/nonfree/fonts/cmbright/ (CTAN = Comprehensive TeX Archive Network consists of a network of several servers. The CTAN server in Germany is ftp://ftp.dante.de, in the United Kingdom ftp://cam.ctan.org and in the United States ftp://tug.ctan.org).

Prev | Home | Next
Installation |  | Known Bugs