Muttprint -- User's guide

2.2.1. Manual installation

At first, you have to unpack the archive. This could be done by the command

$ tar xvfz muttprint-Version.tar.gz

Change in the directory which was created:

$ cd muttprint-Version

There is distributed a suitable Makefile with Muttprint. To adjust the locations on your system, edit the Makefile with your favourite editor.

As mentioned above, there must be a small C program compiled. If you use Perl 5.8 and/or Linux, you could skip this step. For this, just execute

$ make

You need Root permissions to install the program. After you have changed with the su command to the superuser, perform the installation with

# make install

The script should work now.

If you would like to uninstall Muttprint later and all files are still on the same location, execute simply

# make uninstall

as root.

2.2.2. Installation of the packages

If your distribution uses a package management system such as RPM or DPKG, it is a good idea to use the correlatively packages. The greatest advantage is the simple uninstallation.

Most Linux distributions use the RPM package management system. The easiest way to install the package is the command

# rpm -Uvh muttprint-Version-Release.noarch.rpm

All RPM packages are signed with my GnuPG-Key (ID DDAF6454). You get more detailed information about RPM and verification of signatures in Maximum RPM.

The Debian packages are created by René Engelhard <rene@debian.org> and are normally available a few days after a new release of Muttprint. The could be installed by

# dpkg -i muttprint_[version]-[release]_all.deb

Take a look at the Debian "Developer's Corner" for more information about Debian packages.

Another possibility to install Debian packages is apt-get.

2.3.1. Mutt

You have to add or change following line in the file $HOME/.muttrc or system wide in /etc/Muttrc:

set print_command="muttprint"

Moreover you must make sure that all necessary headers are dumped when the mail is printed out. The easiest way is to write a small macro (in your ~/.muttrc) which makes sure that all headers are dumped. Only the most important headers are really printed (see Section 3.1.20).

Here's the macro:

# Dump all headers
macro index p "<display-toggle-weed> <print-message> <display-toggle-weed> <exit>"
macro pager p "<display-toggle-weed> <print-message> <display-toggle-weed>"
			

At first, the macro switches to the mode where all headers are shown, then the mail is printed and finally it switches back. It is necessary to turn the confirmation of printing off so that the macro works right:

# No confirmation before printing
set print="yes"
			

To print more than one mail sensible in one step, you should add following entry:

# Print every mail extra
set print_split
			

You'll find more information in the documentation of Mutt (/usr/share/doc/muttprint/mutt/manual.txt(.gz)).

2.3.2. Slrn

Simply add following lines in your configuration file ~/.slrnrc:

% Use Muttprint for printing
set printer_name "muttprint"
	      

If Muttprint should print more headers than this which are displayed on the screen, you have to use instead of the normal printing command y the combination ESC, 1, y (one after another). This is important for printing the X-Face header, see Section 3.1.4.

2.3.3. XFMail

In the dialogue Misc, Config Misc you have to do an entry in Print Command: /usr/bin/muttprint -f $f.

2.3.4. Pine

Enter the print command muttprint in Setup, Printer, Personally select print command. Save the changes.

2.3.5. Sylpheed

To use Muttprint permanently as printing program, call Configuration, Common preferences, Other, Printing and entry muttprint -f %s.

2.3.6. Gnus

Muttprint could be integrated in Gnus, too. I got a Lisp code from a user that realizes the integration. Please ask me no questions about this because I don't know Lisp and don't use (X)Emacs myself.

You find the code in README.Gnus and I would like to refer to this file in this manual. If you use packages for the installation you should find this file in the /usr/share/doc/muttprint/muttprint/ directory.

2.3.7. Exmh

Choose at first Preferences, then Text Print Command and set Text Print Command to muttprint -f $file.

2.3.8. Other mail clients

Muttprint works with all mail programs theoretically if they comply with following conditions:

• The output must be plain ASCII text without any formattings.

• You must be able to choose the printing command freely.

Newsreader are also supported because the To header is optional and the Newsgroups header is also evaluated.

If you use Muttprint with other programs than mentioned above, please send me a short message in which you describe how you've configured the program. I could add the description here.

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.

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.

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 [5].

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[6]. 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:

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.

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.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).