<!DOCTYPE ARTICLE PUBLIC "-//OASIS//DTD DocBook V4.1//EN">

<article lang="en" id="index">
	
<articleinfo>
	<title>Muttprint -- User's guide</title>
	
	<author>
		<firstname>Bernhard</firstname>
		<surname>Walle</surname>
		<affiliation>
			<address><email>Bernhard.Walle@gmx.de</email></address>
		</affiliation>
	</author>

	<pubdate>2003-04-04</pubdate>
	
	<releaseinfo>Version 0.72</releaseinfo>   
	
		
	
	<copyright>
		<year>2000-2003</year>
		<holder role="mailto:Bernhard.Walle@gmx.de">Bernhard Walle</holder>
	</copyright>

</articleinfo>



<sect1 id="about">
	<title>About Muttprint</title>

	<para>The printing of mails from Mutt (and lots of other mail clients) is
		done as ``plain text''. Normally, that's enough, but in my opinion it's
		not so beautiful like a formatted printing, e.&nbsp;g. from 
		<application>Netscape</application>.</para>

	<para>Another fact disturbed me: The printing contains all displayed header
		information. I've configured Mutt that it displays things like
		<quote>X-Mailer</quote>, but I don't want to print this. 
		<application>XFMail</application> is quite worse: It prints all header
		information, so the printing is in my opinion unusable.</para>

	<para>Sometime I had the idea to write a script myself, which creates a
		nice printing. And here's the result. I think it looks quite better than
		plain ASCII text and is comparable with the printing of well-known
		mail clients under Microsoft Windows.</para>

		
</sect1>
<sect1 id="installation">
	<title>Installation</title>
	
	<sect2 id="sysreq">
		<title>System requirements</title>
	
		<para>Muttprint was realized in the programming language
			<emphasis>Perl</emphasis> which requires a functioning Perl interpreter
			in version 5. This should be true on every Linux systems by
			default.</para>

		<para>Make sure that a LaTeX distribution (I recommend teTeX higher
			than version 2.0) plus the programs <emphasis>psselect</emphasis> 
			and <emphasis>psnup</emphasis> from the <emphasis>PS-Utils</emphasis>
			are available on your system. The last are only necessary if you
			want to use paper save mode and/or duplex printing; and they are
			not necessary if you use CUPS and if you configured Muttprint
			to use it, see <xref linkend="printcommand">.</para>
		
		<para>If you use a Perl 5.6 then it must be a small C program compiled. It
			is required to get information about the current locale environment.
			That means that there must be a C compiler installed. If you use
			Linux this is not necessary.</para>
	
		<para>All required LaTeX packages are included in teTeX. If you use another
			LaTeX distribution, read the file <filename>README.latex</filename>, which
			contains information about all required packages. You have to install all
			packages, that are not present on your system.</para>

		<para>For parsing the date, Muttprint uses the Perl module
			<application>Date::Parse</application><footnote>
			<para>
				<ulink url="http://search.cpan.org/CPAN/authors/id/G/GB/GBARR/TimeDate-1.16.tar.gz"></ulink>
			</para>
		</footnote>
		<footnote><para>You find details about the installation in this file.
			Normally, using the following procedure should work:</para>
			
			<para>
				<prompt>$ </prompt><userInput>tar xvfz Time-Date-1.16.tar.gz</userinput>
			</para>
			<para>
				<prompt>$ </prompt><userinput>perl Makefile.PL</userinput>
			</para>
			<para>
				<prompt>$ </prompt><userinput>make</userinput>
			</para>
			<para>
				<prompt>$ </prompt><userinput>make test</userinput> 
			</para>
			<para>
				<prompt># </prompt><userinput>make install</userinput>
			</para>
			
			</footnote>. If the module is not installed, Muttprint works without 
			problems except the function to convert the time zone and print the date
			in the local language, see <xref linkend="date">.</para>




		<para>Since Muttprint 0.72 the Perl module <application>Text::Iconv</application> 
			<footnote>
			<para>
				<ulink url="http://search.cpan.org/CPAN/authors/id/M/MP/MPIOTR/Text-Iconv-1.2.tar.gz"></ulink>
			</para>
		</footnote>
		<footnote><para>You find details about the installation in this file.
			Normally, using the following procedure should work:</para>
			
			<para>
				<prompt>$ </prompt><userInput>tar xvfz Text-Iconv-1.2.tar.gz</userinput>
			</para>
			<para>
				<prompt>$ </prompt><userinput>perl Makefile.PL</userinput>
			</para>
			<para>
				<prompt>$ </prompt><userinput>make</userinput>
			</para>
			<para>
				<prompt>$ </prompt><userinput>make test</userinput> 
			</para>
			<para>
				<prompt># </prompt><userinput>make install</userinput>
			</para>
			
			</footnote>
			  has to be installed. It is used to convert between different encodings.
				At first you should check if the module is distributed with your
				operating system (on Linux: distribution). Search for a file called
				<filename>Iconv.pm</filename>. If not, install it. If you cannot install
				Perl modules on your system, Muttprint can use the external applications
				<application>iconv</application> (or even <application>recode</application>).
				This is slower and error-prone. If you want to do this, just set the
				variable <literal>ICONV_EXTERNAL</literal> to <literal>on</literal> in
				your configuration file, see <xref linkend="configfile">. But keep in
				mind that this is only a compromise solution!</para>


		<para>To have support for the charset UTF-8 the LaTeX command for
			changing the charset must support UTF-8. This is naturally not the case!
			You'll find a suitable extension in the CTAN. Just download the
			file <ulink 
			url="ftp://ftp.dante.de/tex-archive/macros/latex/contrib/supported/unicode.tar.gz"></ulink>
			and install it as described in the file <filename>INSTALL</filename> which
			is included. You only need UTF-8 support if you work in a UTF-8
			environment. You find out the current encoding under Linux with the
			command <command>locale charmap</command>, on other operating systems use
			<literal>muttprint --print-locale</literal> after Muttprint is installed.</para>
		

	</sect2>
	<sect2>
		<title>Installation of the files on your computer</title>
		
		<sect3>
			<title>Manual installation</title>
			
			<para>At first, you have to unpack the archive. This could be done
				by the command</para>
			
			<para>
				<prompt>$  </prompt>
				<UserInput>tar xvfz 
					muttprint-<replaceable>Version</replaceable>.tar.gz</UserInput>
			</para>
			
			<para>Change in the directory which was created:</para>
			
			<para>
				<prompt>$  </prompt>
				<UserInput>cd muttprint-<Replaceable>Version</Replaceable></UserInput>
			</para>
			
			<para>There is distributed a suitable
				<Filename>Makefile</Filename>  with Muttprint. To adjust the
				locations on your system,  edit the Makefile with your
				favourite editor.</para>

			<para>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 

			<para>
				<prompt>$ </prompt>
				<userinput>make</userinput>
			</para>

			<para>You need Root permissions to install the program. After you have
				changed with the <command>su</command> command to the superuser,
				perform the installation with</para>
				
			<para>
				<prompt>#  </prompt>
				<UserInput>make install</UserInput>
			</para>
			
			<para>The script should work now.</para>

			<para>If you would like to uninstall Muttprint later and all files are
				still on the same location, execute simply</para>
				
			<para>
				<prompt>#  </prompt>
				<UserInput>make uninstall</UserInput>
			</para>
						
			<para>as root.</para>
			
		</sect3>
		
		<sect3>
			<title>Installation of the packages</title>
			
			<para>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.</para>

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

			<para>
				<prompt>#  </prompt>
				<userinput>rpm -Uvh 
muttprint-<replaceable>Version</replaceable>-<replaceable>Release</replaceable>.noarch.rpm
				</userinput>
			</para>
			
			<para>All RPM packages are signed with my GnuPG-Key (ID DDAF6454).
				You get more detailed information about RPM and verification of
				signatures in  <ULink url="http://www.rpm.org/maximum-rpm.ps.gz">Maximum
				RPM</ULink>.</para>

			<para>The Debian packages are created by Ren&eacute; Engelhard 
				<email>rene@debian.org</email> and are normally available
				a few days after a new release of Muttprint. The could be
				installed by</para>
				
			<para>
				<prompt>#  </prompt>
				<UserInput>dpkg -i muttprint_[version]-[release]_all.deb</UserInput>
			</para>
			
			<para>Take a look at the <ulink
				url="http://www.debian.org/devel/">Debian  <quote>Developer's
				Corner</quote></ulink> for more information about Debian
				packages.</para>

			<para>Another possibility to install Debian packages is
				<command>apt-get</command>.</para>
			
		</sect3>
		
	</sect2>
		
	<sect2>
	
		<title>Integration of Muttprint in mail and news clients</title>

		<para>Muttprint was originally developed for the use together with Mutt only.
			However, it could be integrated in following mail programs without problems. 
			I got some description of users. Muttprint would be work 
			independently of Mutt in future, too.</para>
		
		
		<sect3 id="muttconfig">
			<title>Mutt</title>
		
			<para>You have to add or change following line in the file
				<Filename>$HOME/.muttrc</Filename> or system wide in
				<FileName>##SYSCONFDIR##/Muttrc</FileName>:</para>

			<ProgramListing>set print_command="muttprint"</ProgramListing>

			<para>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 <filename>~/.muttrc</filename>)
				which makes sure that all headers are dumped. Only the
				most important headers are really printed (see 
				<xref linkend="printedheaders">).</para>

			<para>Here's the macro:</para>

			<programlisting>
# Dump all headers
macro index p "&lt;display-toggle-weed&gt; &lt;print-message&gt; &lt;display-toggle-weed&gt; &lt;exit&gt;"
macro pager p "&lt;display-toggle-weed&gt; &lt;print-message&gt; &lt;display-toggle-weed&gt;"
			</programlisting>

			<para>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:</para>

			<programlisting>
# No confirmation before printing
set print="yes"
			</programlisting>

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

			<ProgramListing>
# Print every mail extra
set print_split
			</ProgramListing>

			<para>You'll find more information in the documentation of Mutt
				(<Filename>##DOCDIR##/mutt/manual.txt(.gz)</Filename>).</para>

		</sect3>

		<sect3>
				<title>Slrn</title>

				<para>Simply add following lines in your configuration file 
					<filename>~/.slrnrc</filename>:</para>

	      <programlisting>
% Use Muttprint for printing
set printer_name "muttprint"
	      </programlisting>

				<para>If Muttprint should print more headers than this which are
					displayed on the screen, you have to use instead of the
					normal printing command <keycap>y</keycap> the combination
					<keycap>ESC</keycap>, <keycap>1</keycap>, <keycap>y</keycap>
					(one after another). This is important for printing the
					X-Face header, see <xref linkend="xface">.</para>

		</sect3>
		<sect3>
			<title>XFMail</title>

			<para>In the dialogue <GUImenu>Misc</GUImenu>, <GUImenuItem>Config
				Misc</GUImenuItem> you have to do an entry in <GUIlabel>Print
				Command</GUIlabel>:
				<literal>##BINDIR##/muttprint -f $f</literal>.</para>

			
			<Note>				
				<para>With some versions of <Application>XFMail</Application>,
					problems are reported because XFMail does not add the
					headers in the printing. This is not a problem of Muttprint.
					To solve the problem you could look for a new version
					of XFMail which doesn't have this bug.</para>
					
				<para>See also the <ulink
					url="http://slappy.org/listarchives/xfmail/2001-June/002398.html">
					XFMail developer mailing list archive</ulink> for a solution.</para>
			</Note> 
		</sect3>

		<sect3>
			<title>Pine</title>
			
			<para>Enter the print command <literal>muttprint</literal> in
				<GUIlabel>Setup</GUIlabel>, <GUIlabel>Printer</GUIlabel>,
				<GUIlabel>Personally select print command</GUIlabel>. Save the
				changes.</para>				
		</sect3>
		
		<sect3>
			<title>Sylpheed</title>
			
			<para>To use Muttprint permanently as printing program, call
				<GUImenu>Configuration</GUImenu>, <GUImenuItem>Common
				preferences</GUImenuItem>, <GUIlabel>Other</GUIlabel>,
				<GUIlabel>Printing</GUIlabel> and entry <literal>muttprint -f
				%s</literal>.</para>
		</sect3>
		
		<sect3>
			<title>Gnus</title>


			<para>Muttprint could be integrated in
				<application>Gnus</application>, 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
				<application>(X)Emacs</application> myself.</para>
				
			<para>You find the code in <filename>README.Gnus</filename> 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
				<filename>##DOCDIR##/muttprint/</filename>
				directory.</para>
		</sect3>

		<sect3>
			<title>Exmh</title>
			
			<para>Choose at first <GUIlabel>Preferences</GUIlabel>, then
				<GUIlabel>Text Print Command</GUIlabel> and set <GUIlabel>Text
				Print Command</GUIlabel> to <literal>muttprint -f
				$file</literal>.</para>

		</sect3>
		
		<sect3>
			<title>Other mail clients</title>
			
			<para>Muttprint works with all mail programs theoretically if they
				comply with following conditions:</para>
				
			<ItemizedList spacing="compact">
				<listitem>	
					<Para>The output must be plain ASCII text without any
					  formattings.</Para>
				</listitem>
				<listitem>
					<Para>You must be able to choose the printing command freely.</Para>
				</listitem>
			</ItemizedList>
	
			<para>Newsreader are also supported because the
				<ComputerOutput>To</ComputerOutput> header is optional
				and the
				<ComputerOutput>Newsgroups</ComputerOutput> header is also
				evaluated.</para>
			
			<para>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.</para>

		</sect3>
	</sect2>
</sect1>

<sect1 id="config">
	<title>Configuration</title>
		
	<sect2 id="configfile">
		<title>The configuration file</title>
		
		<para>Some things could be configured in Muttprint. This is permanently
			done in  the configuration files <filename>$HOME/.muttprintrc</filename>
			(only for the current user) or <filename>##SYSCONFDIR##/Muttprintrc</filename>
			(global for all users). User settings override global settings.</para>
			
		<para>You can also specify an additional configuration file with the
			<option>-r <replaceable>filename</replaceable></option> 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 <emphasis>Hooks</emphasis> of
			Mutt.</para>
			
		<para>The configuration file is structured in a way that values are
			assigned to different variables -- this is different from
			<filename>.muttrc</filename>. The name of the variable stands
			first and is case sensitive; take over them exactly. Then follows a
			equal sign (<literal>=</literal>) without any whitespaces.
			At last, there's the value. Quotes (<literal>'</literal> or
			<literal>"</literal>) are optional.</para>
		
		<para>An example for a configuration file is distributed with
			Muttprint  (<filename>sample-muttprintrc</filename>). If you've
			installed a RPM  or Debian package, you'll find it in
			<filename>##DOCDIR##/muttprint/</filename>.</para>
			
		<para>An example for a correct assignment:</para>
		
		<ProgramListing>VARIABLE=value</ProgramListing>
		
		<para>Normally the script works without any adapts. But it is
			recommended to inform about the possibilities you have.</para>

		
		<sect3>
			<title>Printer</title>
			
			<para>If Muttprint should not print on the default printer, you can change 
				this by setting <literal>PRINTER</literal> to the correct value.</para>
				
			<para>To print in a file, you could use following syntax, the name
				(and location) of the file is freely chooseable:</para>

			<ProgramListing>PRINTER="TO_FILE:/foo/bar/test.ps"</ProgramListing>
			
			<para>If duplex printing is enabled, Muttprint creates a second file
				with the prefix <filename>2</filename>, e.&nbsp;g.
				<filename>test2.ps</filename>.</para>

			<para>If this variable is not set, Muttprint evaluates the
				environment variable <envar>PRINTER</envar> 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.</para>
				
			<para>As of version 0.70 Muttprint offers direct support of
			 	the new printing system CUPS. It will be turned on by
				setting <literal>PRINT_COMMAND</literal> to <literal>CUPS</literal>.
				Alternatively it is possible to set it to an arbitrary
				command which contains the string <literal>$CUPS_OPTIONS</literal>
				which is substituted by the CUPS printing options.</para>

			<tip>
				<para>You could use the setting <literal>gv -</literal> to have
					a print preview. This is useful if you test different settings.
				</para>
			</tip>

				
		</sect3>
		<sect3 id="printcommand">
			<title>Printing command</title>

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

			<tip>
				<para>You could use the setting <literal>gv -</literal> to have
					a print preview. This is useful if you test different settings.
				</para>
			</tip>
		
		</sect3>
		<sect3>
			<title>Penguin</title>
			
			<para>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 <literal>PENGUIN</literal> variable
				to the right value. The picture must be in Encapsulated
				PostScript (you could use <command>convert</command> from
				the <application>Image Magick</application> package for
				converting your favourite picture into EPS) and it is
				scaled to a height of 2&nbsp;cm (5.08 in). The logo
				must not have a higher width than height.</para>
				
			<para>If <literal>PENGUIN=on</literal>, 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.</para>
				
			<para>Additionally, Muttprint comes with some example pictures that 
				are already converted into the EPS format. After the installation,
				you'll find this in <filename>##SHAREDIR##/muttprint</filename>.</para>
				
			<para>If the printing of the graphic should turned off,
				set <literal>PENGUIN</literal> to the value <literal>off</literal>.
				</para>
			
		</sect3>
		<sect3 id="xface">
			<title>Printing of X-Faces</title>

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

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

			<para>To work right, following two programs are required:</para>
			
			<itemizedlist spacing="compact">
				<listitem>
					<para>
						<application>convert</application> from the
						<ulink url="http://www.imagemagick.org"><application>Image 
							Magick</application> package</ulink>
					</para>
				</listitem>
				<listitem>
					<para>
						<ulink 
							url="http://www.ibiblio.org/pub/Linux/apps/graphics/convert/compface-1.4.tar.gz"><application>uncompface</application></ulink>
					</para>
				</listitem>

			</itemizedlist>

		<para>Both programs should be part of common Linux distributions and
			can simply be installed.</para>
		
		<para>In any case you must make sure that this header is really dumped
			to Muttprint. If you use Mutt, see <xref linkend="muttconfig"> for a
			correct configuration. Otherwise read the documentation of your mail
			software.</para>


		</sect3>
		<sect3>
			<title>Duplex printing</title>
			
			<para>Muttprint allows manual duplex printing. It prints odd pages
				at first, waits a while and prints then even pages.</para>
				
			<para>Muttprint needs the speed of your printer to calculate
				the time when the printing of even pages will start,
				see <xref linkend="speed">.</para>
				
			<para>To activate the duplex printing, set <literal>DUPLEX</literal>
				to <literal>on</literal>.</para>
				
			<para>If you own a real Postscript printer and if this printer
				has duplex capabilities, you should set <literal>DUPLEX</literal>
				to <literal>printer</literal>. This changes the Postscript
				code in a way that tells your printer to enable automatic duplex
				printing; for CUPS a corresponding option is used.</para>				
		</sect3>
		
		<sect3>
			<title>Paper save mode</title>
			
			<para>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.</para>
			
			<para>To enable this mode, set <literal>PAPERSAVE</literal> to
				<literal>on</literal>.</para>				

			<para>If you only want to activate the papersave mode if more
				than one page is printed, set <literal>PAPERSAVE</literal>
				to <literal>optional</literal>.

			</para>
		</sect3>
	
		<sect3 id="date">
			<title>Date</title>

			<para>The <literal>DATE</literal> option allows two settings:
				<literal>original</literal> and <literal>local</literal>. If
				set to <literal>original</literal>, Muttprint print the date
				unchanged as it is in the mail header, i.&nbsp;e. in English
				and in the sender's time zone.</para>

			<para>If you set this option to <literal>local</literal>,
				Muttprint converts the time zone in the time zone of the system and
				prints the date in the local language <footnote>
					<para>This works independent from the translation file
						by using the functions of the operating system. </para>
				</footnote>.</para>

			<para>The format of the date could be specified with the
				<literal>DATE_FORMAT</literal> variable. The argument
				is a format string, e.&nbsp;g. 
				<literal>"%A, %d. %B %Y %H:%M:%S"</literal>. The quotation
				marks are necessary because the string contains spaces.
				The <citerefentry><refentrytitle>strftime</refentrytitle>
				<manvolnum>3</manvolnum></citerefentry> manpage contains
				details about it.</para>

		</sect3>
		<sect3>
			<title>Format of printed mail addresses</title>

			<para>There are different ways of writing mail address and realname
				together in the mail header. Here are some examples:</para>
		
			<ItemizedList spacing="compact">
				<ListItem><para><literal>Bernhard Walle &lt;Bernhard.Walle@gmx.de&gt;
						</literal></para></ListItem>
				<ListItem><para><literal>"Bernhard Walle &lt;Bernhard.Walle@gmx.de&gt;
						</literal></para></ListItem>
				<ListItem><para><literal>Bernhard.Walle@gmx.de (Bernhard Walle)
						</literal></para></ListItem>
			</ItemizedList>

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

			<para>If you would like uniform mail headers, you can assign a format
				string to this variable. The default setting is <literal>"%r
				&lt;%a&gt;,\n"</literal>. You can use all characters as format string,
				<literal>%r</literal> is substituted by the name (<quote>real
				name</quote>), <literal>%a</literal> by the mail address and
				<literal>\n</literal> 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.</para>

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

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

		</sect3>	
		<sect3 id="speed">
			<title>Printing speed</title>
			
			<para>As mentioned above, Muttprint requires the duration which your
				printer needs to print one page. This setting is done by setting
				the variable <literal>SPEED</literal> to the value in seconds
				(only integers are allowed). Default is 30&nbsp;seconds 
				(<literal>SPEED=30</literal>).</para>
		</sect3>
		<sect3 id="font">
			<title>Font</title>
			
			<para>You could use different fonts for the printing. The
				correspondent variable is names <literal>FONT</literal>.
				<literal>Latex</literal> (standard steting) means the standard LaTeX font
				of the EC family. <literal>Latex-bright</literal>
				uses <emphasis>Computer Modern Bright</emphasis>. This font is not
				available on many systems because of its license<footnote>
				<!-- Footnote -->
					<para>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 =
						<emphasis>Comprehensive TeX Archive Network</emphasis> consists of a
						network of several servers. The CTAN server in Germany is
						<ulink url="ftp://ftp.dante.de"></ulink>, in the United Kingdom
						<ulink url="ftp://cam.ctan.org"></ulink> and in the United States
						<ulink url="ftp://tug.ctan.org"></ulink>).
					</para>
				<!-- /Footnote -->
				</footnote>. Another choice is <literal>Latin-modern</literal> for
				the <emphasis>lmodern</emphasis> fonts (not available on most
				systems).
			</para>
			
			<para>There are several Postscript fonts which are possible here: 
				<literal>Times</literal>, <literal>Palatino</literal>,
				<literal>Utopia</literal>, <literal>Charter</literal> 
				<literal>Bookman</literal>, <literal>CentSchool</literal>
				(New Century Schoolbook), <literal>Chancery</literal>
				(Zapf Chancery), <literal>Helvetica</literal> or
				<literal>AvantGarde</literal>.</para>

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

		</sect3>		
		<sect3>
			<title>Font size</title>

			<para>You can control the font size with the variable
				<literal>FONTSIZE</literal>. Only the values <literal>10pt</literal>,
				<literal>11pt</literal> and <literal>12pt</literal> are possible.
			</para>
		</sect3>
		<sect3>
			<title>Formatting of the mail body</title>

			<para>The mail body is split into two parts: text and signature. If there
				is a signature and it should not be removed (see <xref
				linkend="remsig">), this two parts can be formatted separately.</para>

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

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

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

			<para>Here're some examples:</para>
			
			<itemizedList spacing="compact">
				<listitem>
					<para>
						<literal>fontshape=it,frame=topline</literal>: 
							italic font, border above the block
					</para>
				</listitem>
				<listitem>
					<para>
						<literal>fontfamily=helvetica,fontseries=b</literal>:
							Helvetica font, bold
					</para>
				</listitem>
				<listitem>
					<para>	
						<literal>numbers=left,stepnumber=5</literal>:
							Line numbering each fifth line
					</para>
				</listitem>
			</itemizedList>
			
		</sect3>
		<sect3>
			<title>Margin settings</title>

			<para>The margins could be set by modifying following variables:
				<literal>TOPMARGIN</literal> (top margin),
				<literal>BOTTOMMARGIN</literal> (bottom margin),
				<literal>LEFTMARGIN</literal> (left margin) and
				<literal>RIGHTMARGIN</literal> (right margin).</para>
		
			<para>This variables should be set to a integer, which specifies the
				margin in millimeters (mm). Other measuring units are not possible;
				25.4&nbsp;mm are 1&nbsp;inch.</para>

		</sect3>
		<sect3 id="wrapmargin">
			<title>Wrapping long lines</title>

			<para>The length of the longest line is specified with the 
				<literal>WRAPMARGIN</literal> variable. Longer lines are wrapped
				automatically but shorter lines are not joined.</para>

		</sect3>
		<sect3>
			<title>Rules under/over head- and footline</title>
			
			<para>There could be printed a rule under the headline
				resp. over the footline. They are turned off
				as default.</para>
				
			<para>Set the variables <literal>HEADRULE</literal>
				resp. <literal>FOOTRULE</literal> to 
				<literal>on</literal> or <literal>off</literal>.</para>
		</sect3>
		<sect3>
			<title>Design of the first pages</title>
			
			<para>There exists different possibilities to highlight the mail headers
				on the first page. Here is a listing of them:</para>
			
			<informaltable frame="topbot">
				<tgroup cols="2" align="left">
				<colspec colnum="1" colwidth="1.5in"> 
				<thead>
				<row>
					<entry>Style</entry>
					<entry>Description</entry>
				</row>
				</thead>
				<tbody>
				<row>
					<entry><literal>plain</literal></entry>
					<entry><para>no rules</para></entry>
				</row>
				<row>
					<entry><literal>border</literal></entry>
					<entry><para>rule after the headers 
					(<emphasis>default setting</emphasis>)
					</para></entry>
				</row>
                <row>
					<entry><literal>Border</literal></entry>
					<entry><para>thick rule after the headers 
					</para></entry>
				</row>
				<row>
					<entry><literal>fbox</literal></entry>
					<entry><para>simple box around the mailheaders</para></entry>
				</row>
				<row>
					<entry><literal>shadowbox</literal></entry>
					<entry><para>shadowbox around the header</para></entry>
				</row>
				<row>
					<entry><literal>ovalbox</literal></entry>
					<entry><para>box with rounded corners around the header 
						(thin lines)</para></entry>
				</row>
				<row>
					<entry><literal>Ovalbox</literal></entry>
					<entry><para>same as <literal>ovalbox</literal> but thicker
					 	lines</para></entry>
				</row>
				<row>
					<entry><literal>doublebox</literal></entry>
					<entry><para>box with double lines around the header</para></entry>
				</row>
				<row>
					<entry><literal>grey</literal></entry>
					<entry><para>grey background behind the headers</para></entry>
				</row>
				<row>
					<entry><literal>greybox</literal></entry>
					<entry><para>same as <literal>grey</literal> but with a additional
						black box</para></entry>
				</row>
				</tbody>
				</tgroup>
			</informaltable>
			
			<para>Set the variable <literal>FRONTSTYLE</literal> to a value
				from the table above.</para>
			
		</sect3>
		<sect3>
			<title>Paper format</title>
			
			<para>To set the paper format, set <literal>PAPER</literal> to the right
				value. Possible are only <literal>A4</literal> and
				<literal>letter</literal>.</para>
				
			<para>If there exists a file <filename>##SYSCONFDIR##/papersize</filename> as
				usually on Debian systems, it is evaluated, too. Own settings overwrite
				this system settings.</para>


		</sect3>
		<sect3 id="remsig">
			<title>Cut signature</title>
			
			<para>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 <quote><literal>&ndash;&ndash; </literal></quote> -- take
				a look at the whitespace (some mail clients don't generate a
				correct separator).</para>
				
			<para>To do this you've to set <literal>REM_SIG</literal> (this means
				<quote>remove signature</quote> to the value 
				<literal>on</literal>.</para>

			<para>If Muttprint should recognize other separators to indicate
				the beginning of a signature, you can set <literal>SIG_REGEXP</literal>
				to a regular expression in Perl syntax. The default setting
				is <literal>^-- $</literal>. If you don't know what this notation
				means, just don't change the default.</para>
				
		</sect3>
		<sect3>
			<title>Omit quoting</title>
			
			<para>Often the author of the mail does not quote sensibly but
				attaches the whole mail so that the printing becomes very long
				and confusing.</para>

			<para>If <literal>REM_QUOTE</literal> is set to
				<literal>on</literal>, 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 <emphasis>toggle
				quote</emphasis> function 
				(<keycombo><keycap>Shift</keycap><keycap>t</keycap></keycombo>)
				on screen.</para>
		</sect3>
		<sect3 id="printedheaders">
			<title>Printed headers</title>
			
			<para>Normally only the interesting headers are printed. You
				could change this settings with the variable 
				<literal>PRINTED_HEADERS</literal>. Specify each header
				separated with a underline (<literal>_</literal>).</para>
		
			<para>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 (<literal>*</literal>), for italic printing do the
				same with slashes (<literal>/</literal>).</para>

			<para>The default setting is:</para>
			
			<programlisting>PRINTED_HEADERS="Date_To_From_CC_Newsgroups_*Subject*"</programlisting>
			
			<para>One more example for a sensible setting:</para>
			
			<programlisting>PRINTED_HEADERS="/Date/_To_From_*Subject*_X-Mailer"</programlisting>

		</sect3>
		<sect3>
			<title>Own LaTeX code</title>

			<para>The variable <literal>LATEXCODE</literal> 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.</para>

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

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

		</sect3>
		<sect3>
			<title>Printing in the background</title>

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

			<para>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.</para>

			<para>For this, you can assign the variable <literal>BACKGROUND</literal>
				the value <literal>on</literal>. In the debug mode (see <xref
				linkend="debug">) this option has no effect.</para>
		
		<sect3 id="debug">
			<title>Error messages</title>
			
			<para>The output of <command>latex</command> and
				<command>dvips</command> are not displayed. If there are any
				problems, it would be helpful to read this output. Therefore
				you should set <literal>DEBUG</literal> to <literal>1</literal>
				in your  <filename>.muttprintrc</filename>. Now Muttprint
				creates a log file named <filename>/tmp/muttprint.log</filename>
				in the next run so that you can watch the error messages. This
				could be helpful for all bug reports, too.</para>
		</sect3>
	</sect2>
	<sect2>
		<title>Command line options</title>
		
		<para>Most configuration settings could be made by command line options as well.
			The advantage is a easier integration in the mail client (e.&nbsp;g. with
			own macros).</para>
			
		<para>You find a detailed description of all options with
			<command>muttprint</command> <option>-h</option> 
			or or in the <citerefentry><refentrytitle>muttprint</refentrytitle>
			<manvolnum>1</manvolnum></citerefentry> manpage.</para>
			
		<para>The effects of this options are the same as in the configuration file
			but command line settings override all other settings.</para>


	</sect2>
	<sect2 id="lang">
		<title>Different languages</title>
				<sect3>
			<title>Overview</title>
		
		<para>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.</para>

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

		<para>For Muttprint the variables <literal>LC_ALL</literal>,
			<literal>LANG</literal>, <literal>LC_MESSAGES</literal>,
			<literal>LC_CTYPE</literal> and <literal>LC_TIME</literal> are
			important. <literal>LC_CTYPE</literal> 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. <literal>LC_MESSAGES</literal> specifies the
			language for messages and the printing and <literal>LC_TIME</literal>
			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
			<literal>LC_MESSAGES</literal>. <literal>LC_ALL</literal> overwrites
			all other <literal>LC_</literal> variables, so if it's set, the other
			have no meaning anymore. <literal>LANG</literal> is a fallback:
			If, for example, <literal>LC_MESSAGES</literal> is not defined 
			<literal>LANG</literal> is used to determine the language for
			messages. Normally you only set the <literal>LANG</literal> variable.
		</para>

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

		<para>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.</para>

		<para>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. </para>

					
		</sect3> 
		<sect3> 
			<title>Translation file</title>
		
			<para>The Muttprint translation files are located in the
				<filename>share</filename> directory and have the name
				<filename>translation-<replaceable>language</replaceable>.pl</filename>.
				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.</para>
			
			<para>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.</para>
		
			<para>Important: The encoding of this file must be (independent of the
				current locale environment) UTF-8. Read the file
				<filename>README</filename> which is in the
				<filename>translation/</filename> directory of Muttprint (the source code
				distribution).
			</para>
		</sect3>
	</sect2>
</sect1>


<sect1>
	<title>Known Bugs</title>

	<para>Even Muttprint contains bugs. Following problems exists currently:</para>

	<para><emphasis role="bold">Problem with parsing of the configuration file
		(RedHat Linux).</emphasis> Because of a bug in the Perl version distributed
		with RedHat Linux 9.0, Muttprint cannot parse the configuration file
		in a UTF-8 environment. You can use Muttprint in a non-UTF-8 environment
		or upgrade Perl from <ulink
			url="ftp://ftp.redhat.com/pub/redhat/linux/rawhide/">RawHide</ulink>.
		The bug is described at <ulink 
		url="http://bugzilla.redhat.com/bugzilla/show_bug.cgi?id=98274"></ulink>.</para>

	<para><emphasis role="bold">Error in line-wrapping with Perl 5.6.</emphasis>
		Lines that contain non-ASCII characters are wrapped too early in all 
		Perl 5.6.x versions (earlier versions don't work at all). Umlauts
		and Cyrillic characters count twice. The problem occurs in all locale
		environments and bases on a bug in the standard module
		<application>Text::Wrap</application> in this Perl versions. The bug
		occurs only if the mail contains lines which are too long and you don't 
		see it in a normal German or English text. You can increase the
		value of <literal>WRAPMARGIN</literal> (see <xref linkend="wrapmargin">)
		or use a up to date Perl (recommended is 5.8.1).</para>
		
	<para><emphasis role="bold">Wrong printing of the date (Perl 5.8.0).</emphasis>
		The date is printed wrong if it's printed in the language of the country
		(see <xref linkend="date">) and if it contains non-ASCII characters. 
		The problem is that the mentioned Perl version encodes the UTF-8 encoded
		string again in UTF-8. The result is a quasi twice-encoded date.
		There are improved versions of Perl 5.8.0 where this problem is solved
		(for example the Perl distributed with Debian unstable).
	</para>
	

</sect1>








<sect1 id="nots">
	<title>Notes</title>
	
	<sect2>
		<title>Author, License</title>
		
		<para>The script has been written by Bernhard Walle 
			<email>Bernhard.Walle@gmx.de</email>.</para>
		
		<para>This program is free software; you can redistribute it and/or
			modify it under the terms of the GNU General Public License as
			published by the Free Software Foundation; either version 2 of the
			License, or (at your option) any later version.</para>
			
		<para>This program is distributed in the hope that it will be useful,
			but <emphasis>without any warranty</emphasis>; without even the
			implied warranty of <emphasis>merchantability</emphasis> or
			<emphasis>fitness for a particular purpose</emphasis>. See the GNU
			General Public License for more details.</para>

		<para>You have received a copy of the GNU General Public License along
			with this program (file <filename>COPYING</filename>).</para>
			
		<para>Please send notes, comments, improvement proposals etc. via
			e-mail to me.</para>
			
		<para>The translations are copyrighted by the respective
			translators. Read <filename>README.translations</filename> for
			the names of the translator.</para>
	</sect2>
	<sect2>
		<title>Download</title>
		
		<para>The current version and all old versions could be downloaded from
			<ulink url="http://muttprint.sourceforge.net"></ulink>.
			This is the Homepage of Muttprint.</para>

		<para>I announce new versions on <ulink
			url="http://www.freshmeat.net">Freshmeat</ulink>.</para>

	</sect2>
	<sect2>
		<title>Printing of attachments</title>
		
		<para>Muttprint is not able to print mail attachments. To reach this,
			Muttprint would have to parse the raw MIME message and decode it.
			This is quite difficult. For example Muttprint would have to decrypt
			PGP-encrypted messages, choose the right alternative in 
			<literal>multipart/alternative</literal> messages and work recursive
			for <literal>message/*</literal> -- this are only a few things.
			Short: Essential parts of a mail client must be integrated and lots of
			settings (like for PGP) must be done. Moreover, not all mail clients
			support outputting the raw message for printing.</para>
			
		<para>But Mutt has itself a comfortable function to print attachments. You
			can choose a separate printing command for each MIME type. This could be
			set in <filename>~/.mailcap</filename>. Read further information
			in the Mutt manual, section 5.3.3.1.</para>

		<para>I've written a very small script named <literal>imageprint</literal>
			for printing images (almost every format is supported). You could use it
			as template for own scripts. Here it is:</para>			

		<programlisting>
#!/bin/sh
target=/tmp/imageprint-$$.ps
convert -page A4 $1 $target
lpr $target
rm $target</programlisting>
		
		<para>Just press the <keycap>p</keycap>-key in the attachment menu of
			Mutt.</para>
		
		<para>Users of other mail clients should read the documentation for
			information about how to print attachments.</para>

	</sect2>
	<sect2>
		<title>Thanks</title>
		
		<para>to all who helped me with their bug reports to improve and
			enhance Muttprint. Especially I want to thank Roman Beigelbeck for
			providing additional pictures, Roberto Vallone for the Italian
			transation, Vincent Bernat for the French translation, Marcelo
			Ramos for the Spanish translation, Dominik Form&aacute;nek for
			the Czech translation and the Debian maintainers Dr.
			Guenter Bechly and Chanop Silpa-Anan.</para>

		<para>Finally I would like to thank all people who contributed
			to free software. Most people did this in their spare time
			without receiving a penny for this!</para>

	</sect2>
</sect1>
</article>

<!-- ViM settings
vim:tw=80 sw=2 ts=2
-->
