Crème Fraiche

EML to PDF Converter

Download the package

If you cannot or do not want to use the gem-utility to install Crème Fraiche, you can download the program from here. In this case, the installation of the program in your file-system lies in your own responsibility.

Program Archives

cremefraiche_0.6.1.zip

SHA256 Checksums

CremeFraiche_0.6.1.zip: a2c1c8f8fa3456e4041e3fe20e1ef47a283be914a6de0c3f6e9e07fd99f446d3

My digital signatures for the archives

cremefraiche_0.6.1.zip.sig

Crème Fraiche is free software under the terms of the GNU General Public License.

Contents of the archive

The Zip-file contains the following files and sub-folders:

cremefraiche.gem	The ruby-gem. Use this file to install the program as a gem.
bin	A folder with executable files for the commandline- and the GUI-program.
lib/doc	A directory, containing documentation, e.g. this text and the HOWTO for the graphical user-interface.
lib	This is the ruby-code of the main-program. The only file which is directly executed by the Ruby-interpreter is, though, cremefraiche.rb.
A directory lib/gui	Contains the ruby-code of the graphical user-interface (Gtk2).
A directory lib/busy_indicator	Ruby code which will provide animated text during the processing of EML-files to PDF.
A file lib/config	Contains a set of options which control how Crème Fraiche creates PDF from EML.
A shell-script lib/get_gems.sh	This shell-script will simply install the Ruby-Gems, which are needed to run Crème Fraiche.
A file lib/LANG	Controls in which language Crème Fraiche should produce output, either on screen or in a protocol-file, that you can define in the configuration.
A file lib/translations	Contains the original English version of messages and their translations to other languages (currently German and French).

Installation

Ruby

Crème Fraiche is programmed in Ruby. To run it, you need a working Ruby-interpreter on your computer. If you are using Linux, it should be easy to find Ruby in the package-management system that comes with your Linux-distribution. If not, or if you use Windows, or if you want to get a newer Ruby version, visit the Ruby homepage and get the latest version of the interpreter directly from there. Crème Fraiche was developed with Ruby 1.9.3 and you should probably avoid running the program with older versions. I have never tried that with Ruby 1.8.x but would be interested in your experience, should you want to give it a try.

Install Crème Fraiche as a Ruby-Gem

The easiest way to download and install the program is by use of the gem-utility. Just execute on a command-line

Ruby Gems needed to run Crème Fraiche

With the help of the gem-utility, download and install the gems which Crème Fraiche uses:

• Mail, to parse the components of email
• Prawn, to generate PDF
• Nokogiri, to handle HTML-mail
• Escape, to handle shell-commands where external tools are called.

Since version 0.3 Crème Fraiche comes with a graphical user-interface that you can use as an alternative to executing Crème Fraiche from the command-prompt. Prior version 0.6, the GUI has ben programmed against the Ruby-Gtk2 packages which are part of the Ruby-Gnome2 project. Since Crème Fraiche 0.6.1, the Gtk3 library is needed for the graphical user-interface to run.

Either version of Gtk can be installed as a Ruby-gem; the packages are named gtk2 and gtk3.

Location of Crème Fraiche in the file-system

If you chose to not use the gem-utility but download the program-archives I will not tell you, where to put the program folder and how to call the executable main ruby script on your system. You should certainly follow a rule that either results from your own experience or the procedure, that qualifies as best practice with your operating system.

Please note that the gem-file for the current program version is included in the program archive. You can still choose to install it by executing

Running the program

Execute Crème Fraiche once without arguments. If you installed the gem, just call cremefraiche.rb right away, otherwise use one of the following commands.

This should produce a message similar to the following output:

 ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
 ┃                Crème Fraiche version 0.4.5              ┃
 ┃                     EML to PDF converter                ┃
 ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛

 © 2011-2013 Michael Uplawski <michael.uplawski@uplawski.eu>

 Running with Ruby 1.9.3 on x86_64-linux

 Usage:
        user@machine:~$ ruby ./cremefraiche.rb [eml_file1.eml] <eml_file2.eml ... eml_file(n).eml>

 This produces 1 PDF-file for each individual email found in the given EML-file(s).
 Please see the file 'config' in the program folder for some options.


This program is free software under the terms of the GNU General Public License, 
version 3 or any later version.

If the usage-information is displayed, Crème Fraiche is functional.

Missing gems

If for some reason the required gem-files for prawn, mail, nokogiri, escape, gtk2 or gtk3 (for the GUI) are not found by the ruby-interpreter, Crème Fraiche will try to load and install them first. This may once again become necessary after an update of the ruby-interpreter. The fact is indicated for each of the missing gems:

user@machine:~$ cremefraiche.rb
   =>   PSE wait, installing required gem "mail"... 

The installation may take some time, as all three of the named gems depend themselves on other gems. If your gem-files are installed for system-wide usage, this operation may require administrator-rights. If a gem cannot be installed, and an error-message like the following appears, execute cremefraiche.rb once as super-user.

user@machine:~$ cremefraiche.rb
   =>   PSE wait, installing required gem "mail"... 
ERROR:  While executing gem ... (Gem::FilePermissionError)
    You don't have write permissions for the /usr/local/lib/ruby/gems/2.0.0 directory.

Repeating the command-line as super-user (root or administrator), you will see that the gems and packages, that they depend on, are installed on your system:

root@machine:~# cremefraiche.rb
   =>   PSE wait, installing required gem "mail"... 
Fetching: mime-types-1.21.gem (100%)
Successfully installed mime-types-1.21
Fetching: polyglot-0.3.3.gem (100%)
(...)

When all required gems are installed the output shown above will be created

Language-setting

At the time of this writing, Crème Fraiche will create output either in English (default), French or German, depending on the value of the environment-variable LANG. In case that this value is not set or cannot be interpreted, the language is read from the file LANG in the program directory. It contains nothing but the two-letter designator of a locale, ergo one of en, fr or de in lower or upper case. Choose your preferred language-setting or leave the file empty, which means the default English.

Further below in this document I will explain how you can add a translation to Crème Fraiche, if you want to make the program support additional languages.

Icon or shortcut

The final installation step shall provide you with a program-icon, keyboard-shortcut or similar means to call the program, whenever you wish to execute it. Take into consideration, that Crème Fraiche will usually need the name of an eml-(mail-)file as program-argument. An icon on the desktop will only make sense, when you use to convert the always same folder again and again to PDF, or the icon calls a utility like Zenity (Linux/Gnome) or whiptail (ex dialog) which will then execute Crème Fraiche with the provided arguments.

Alternatively, you can always run the program at a command-prompt, either as an argument to the ruby-interpreter ($> ruby cremefraiche.rb <emlfile.eml>) or, if the ruby-interpreter is in the system-path for executable files, by calling cremefraiche.rb directly. This also applies, if you had installed the gem ($> cremefraiche.rb <emlfile.eml>).

PDFTK to create PDF-attachments

It is not mandatory for the normal operation of Crème Fraiche to have the PDFTK-utility installed. However this nice little tool empowers you to manipulate existing PDF-files in many ways. Crème Fraiche can be configured to call pdftk to attach files to a PDF. See below in the section about mail-attachments how this will be useful.

Objective

You can convert email to PDF in many different ways. I found the easiest solution in printing a message to file. On a Linux-system, you can in this way create a postscript-file with file-extension .ps, which can afterwards be converted to PDF. More often, nowadays, you can choose to create the PDF-version at once.

However, the format of the resulting file may not be to everyone's gusto. Furthermore, when you want to archive more than one message in the PDF-format, opening and printing each one to file is cumbersome. At last, mail-attachments need to be handled separately and keeping them together with the PDF-file means an additional effort.

My aims with Crème Fraiche are the following:

• Create PDF from email independently of the software platform or email-client.
• Transform at once all the emails, currently stored in one or more folders, each into its own PDF-file.
• Handle mail-attachments in the process, so that they are available with the PDF.
• Provide a way to influence the format of the resulting PDF.
• Create equally readable documents from HTML-mails and plain text.
• Let the user choose which mail-headers she/he wants to see in the PDF-file.
• Base all the previous actions on the EML-format of the input-files.
• Publish this program as free software.

List of changes

The list of changes is usually up to date in the file changes.txt, which you find in the sub-directory doc of the gem-directory or the expanded program-archive. This is a link to the current version of that file: changes in recent versions of Crème Fraiche.

Introduction

I will first explain, which kind of PDF-result you can expect from Crème Fraiche, based on a simple example message, then show you, how you can influence the results with the help of some configuration-options. At last, I explain the translation mechanism, which can be extended to support more than the current three languages English, French and German for the feedback, which Crème Fraiche produces on the standard-output or in a protocol-file (see below in section Logging).

Note: The graphical user-interface to Crème Fraiche will NOT be subject of the following explanations. Instead, I describe the GUI in a separate HOWTO. None of the functionality is reserved to the users of the graphical user interface and if you are comfortable with the command-line, you do not need the GUI at all.

EML

EML is a rather simple file-format for the textual representation of email. Many email-clients are capable to store individual emails in EML-files or to export complete email-folders in eml-format. In the latter case, one EML-file will contain all the messages, which were originally found in that email-folder. Crème Fraiche will handle single mails or multiple mails in one or many EML-files alike and create 1 PDF-file for each individual message.

How you create these EML-files depends on the email-client, that you use. Mozilla-Thunderbird for example, uses to store messages by default in eml-format and not just when you choose the pertinent menu-command save as..., but also routinely each incoming message or those that you move to different mail-folders. Thus, these mail-folders are in reality EML-files, each containing one or many emails.

A test message which I have sent to my own email address, looks like this when exported to EML:

Message-ID: <4F0AD54A.9010908@uplawski.eu>
Date: Mon, 09 Jan 2012 12:53:46 +0100
From: Michael Uplawski <michael.uplawski@uplawski.eu>
User-Agent: Mozilla/5.0 (X11; Linux i686 on x86_64; rv:9.0) Gecko/20111222 Thunderbird/9.0.1
MIME-Version: 1.0
To: uplawski@web.de
Subject: TEST priority
X-Priority: 1 (Highest)
X-Enigmail-Version: 1.3.4
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Body text of the test message.
-- 
GnuPG/OpenPGP: 2048D/74A227D5 2010-04-09 [verfällt: 2012-04-08]
sub: 2048g/4E580A13 2010-04-09 [verfällt: 2012-04-08]
User: Michael Uplawski (privat) <michael.uplawski@uplawski.eu>
Fingerprint: 1E6E 87CF B2F5 EBBC ACB6 7120 0A44 0972 74A2 27D5

Apart from the body of the email message, all the original mail-headers are present in the EML-file.

Executing Crème Fraiche

To produce a PDF-file from the above simple email, you must know the file-name and path of the EML-file. Call Crème Fraiche with the file as the only argument, like in this example:

user@machine:~$ cremefraiche.rb /tmp/test_mail.eml

Note: For the time being, Crème Fraiche does not verify that the handled files are really contain text in EML-format. An attempt to transform other data will usually fail, but the exact behavior of Crème Fraiche depends on the type of the actual data. The responsibility to choose only valid EML-files is yours alone.

Now you can call Crème Fraiche just like any other program:

user@machine:~$ cremefraiche /tmp/test_mail.eml

Results

The result of the transformation is 1 PDF-file for each message in the EML-file. In the above example, a new PDF-document would be stored in the same directory (/tmp) where the input had been located: /tmp/test_mail.eml.pdf. The name of the new file will always follow the example of the original eml and only the file-extension .pdf is added.

Here is the PDF-file: test_mail.eml.pdf

You will notice, that not all the mail-headers have survived the transformation. Message-ID, User-Agent, MIME-Version, X-Priority, X-Enigmail-Version and Content-Transfer-Encoding disappeared. The Content-type appears to have moved towards the body of the message, where it got highlighted in blue.

Transforming Mail-Folders

When many emails are stored in only one EML-file (e.g. when the file represents a mail-folder), the procedure is not different in any way. Just call Crème Fraiche with the file as its argument.

However, for Crème Fraiche to be able to create separate PDF-files, the EML-file must first be split-up into individual message-files. After the transformation to PDF, these intermediate files are of no use and can be deleted again. Like the PDFs, they are numbered but otherwise have file-names that resemble the original big EML-file. There is a configuration-option, which lets you determine if the numbered EML-files should be kept or deleted after a successful transformation to PDF. See the section Configuration, below, and the excerpt from the configuration-file.

Transforming multiple EML-files

You can process multiple EML-files at one go. Just name them one by one, separated by an empty space, as arguments to Crème Fraiche.

user@machine:~$ cremefraiche /tmp/test_mail.eml
      /Mail/Folders/family/Fridolin /Archives/my_mail/2011.eml

It is of no importance, how many mails are stored in each folder. Keep in mind however, that the PDF output is always created in the same directory, that contains the original EML-file. It is probably best, to first copy all the files, that you are interested in, to one dedicated folder. This will be even more interesting, when you also need to keep mail-attachments ready for later reference (see below).

Configuration

You can influence the behaviour of Crème Fraiche. The file config in the gem- or program directory contains adaptable options in YAML-format. Like in the exemplary sections shown below, each option is commented and it should be easy for you to save your preferred values.

By default, the configuration-file resides in the sub-directory lib of the downloaded source-package or the installed gem. To modify this file directly, you might need administrator rights.

User-configuration

Each user of Crème Fraiche can have her/his own version of the configuration file and set her/his own preferences there. These will then override the original settings. To create your first initial copy of the configuration, just execute cremefraiche with the program argument user-config:

user@machine:~$ cremefraiche.rb user-config

This way, Crème Fraiche creates a sub-folder .cremefraiche in your home-directory where it places the new file config. You can later execute the identical command to be notified about new or obsolete elements in future versions of the program and to have your own copy of the configuration updated accordingly.

Note, that an existing user-configuration will be renamed to config_bak and the new copy be stored alongside this file.

user@machine:~$ cremefraiche.rb user-conf

The following changes can be effectuated on your user-configuration
        + New options:
                additional
        - Obsolete Options:
                obsolete option
Do you want to replace your current user-configuration?
If you answer 'yes' a back-up copy of your old file will still be available.
But your old settings will be replaced by the defaults.
Your answer (Y/n): 

If you push y, unfortunately and for the time being, you will be obliged to once again adapt all the options to your needs. Use the backup copy for reference. On the other hand, you can also say n and just add those options that are listed as new and remove the old ones from your file. This way, you only miss the comment-section which explains each option. You can always look these up in the file that you installed with the downloaded program-package. In the future I might provide some way to access this information in a different way; please be patient.

Instead of listing and explaining each and every option once again on this page, I keep a copy of my own current configuration in the sub-folder example under doc. You can also see it right here: example_config.

Mail-Attachments

Crème Fraiche can handle mail-attachments in two different ways or ignore them completely.
See in the configuration-file the last two options at the end of the file, save attachments and attachment link color:

# Where attachments shall be stored during the transformation.
#       Default:        false
#       Value:          One of the following 
#                               'pdf'            - store files in the PDF (needs pdftk)
#                                                  The Adobe Acrobat-reader can open
#                                                  attachments to PDF-files.
#
#                               a directory path - store files in the given directory.
#                                                  A link to the file shall be provided
#                                                  in the PDF. The directory MUST EXIST. 
#
#                               'false'          - do not store the attachments
# save attachments: /tmp/mail_attachments
save attachments: pdf

# The color of the links to saved attachments, if "save attachments"
# above is set to a file path, rather than 'pdf'
#       Default:        008000
#       Value:          a hexadecimal rgb-color value
#                       in single quotes
attachment link color: '008000' 

PDF-attachments

Apart from the value false, the option save attachments can be set to either a file-path or the value pdf. In latter case, and provided, that you have the PDFTK-tool installed, the mail-attachments are again attached to the PDF-file in creation. This has the immense advantage, that you can move the PDF-file around in the file-system or transfer them anywhere but never forget that originally, the email-message came with more files attached. The Adobe Acrobat-reader™ can show the list of attached files and lets you open each one of them with a double-click. See the below screen-shot for an example.

It would be nice to program this functionality directly into Crème Fraiche, but myself I am currently unable to do so, for lack of knowledge, and the ruby-gem Prawn which is responsible for all the PDF-generation does not offer a method to create PDF-attachments. If you do not want to resort to PDFTK for some reason, see the next paragraph for an alternative way to handle mail-attachments.

Directory for mail-attachments

When storing attachments in the PDF-file itself is not possible, you can still have a link to each attachment in the content of the PDF-file. Choose an existing directory where Crème Fraiche shall store all mail-attachments. At the end of each transformed message, when it contained attachments, a link to the files will be generated. As long as you do not move them away from the dedicated directory, you can open each attachment by clicking on its link. In the following image you see such a link in the Evince document-viewer.

The color of the links is set with the configuration-option attachment link color

Logging

Crème Fraiche will report back during execution. You can determine where to put these protocol-messages and how much information you will get from the program by setting the configuration-options log level and log file. Here is the relevant section from the configuration-file:

# The log-level can be fatal, error, warn, info or debug
#       Default: UNKNOWN
#       Value: one of unknown, fatal, error, warn, info or debug
log level: debug

# Path to the protocol-file, where the logger-output will
# be directed, if configured. When left empty, stdout will
# be used.
#       Default:        STDOUT
#       Value:          a file-path
log file: /tmp/CremeFraiche.log

Setting log file to an empty value or to STDOUT will make Crème Fraiche log to the screen.

Internationalization

This too, concerns the log-function. Crème Fraiche can create log-messages in different languages; at the time of this writing those are English (default), French and German. This applies though only to messages on the log-levels info, error and warn, as I consider debug-messages of minor interest.

As indicated above, under Installation, to change the language, you open the file LANG in the program-directory and just type on the first and only line the two-letter code for the language you want: en, fr or de.

Adding languages

If you want to add a language, you need to translate yourself all the messages, contained in the file translations in the same gem- or program-directory. The structure of that file is simple. Example:

storing temporary files in %s:
  de: speichere temporäre Dateien in %s 
  fr: des fichiers temporaires seront ecrit dans %s 

replacing existing file %s:
  de: ersetze vorhandene Datei %s
  fr: fichier %s est remplacé

method %s is undefined for objects of class %s:
  de: Die Methode %s ist für Objekte der Klasse %s undefiniert
  fr: La méthode %s n'est pas défini pour les objets de la class %s 

In the example above, each block of three lines stands for one protocol-message. In the first line, you see the original English message, followed by a colon (:). The following lines contain the translation, preceded by a two-letter code and a colon. The use of the colon in this YAML-syntax unfortunately prevents me from using colons within the messages. Keep that in mind, when you provide your own translation: No colon other than those at the end of the English line and after the two-letter code!

Another speciality is the code %s which will be replaced by a variable value during the execution of the program. Keep these two characters in your translation. You are though not obliged to put them at a certain position of the message, as you see in the last block in the example, where in the German translation, they moved one word to the left.

But that is it. No more background is needed to add a language. Do not forget to change the two-letter code in LANG to the code of the new language.

You can add one translated message at a time and run Crème Fraiche without fear, as messages for which no translation exists will not create an error but instead are displayed in English.

Motivation

Without wishing to disappoint you, I must state that I have personally no use for a tool like this.
Crème Fraiche has been developed in response to an inquiry in the Framasoft forum Framagora. When I noticed, that there are only commercial tools but no free software available to convert e-mail to PDF, I felt challenged to give it a try. Wherever you need to handle text or textual representations of data to extract distinct values and put them in a different context, Ruby, like most other interpreted programming languages, appears at its best. As I am rather fond of Ruby, Crème Fraiche had to be a Ruby-program.

At first, I planned to convert the EML-files to XML, as this format can then easily be processed into many different kinds of document. The Apache-FOP utility would then be used to create PDF-files from the intermediate XML. And because XML lets you freely handle the contained data in any way you like, just as with Crème Fraiche you compose a splendid meal from otherwise frugal ingredients, I chose the name Crème Fraiche for my new utility.

Unfortunately, or luckily, already the creation of the XML-representation of emails turned out to be overly complicated, due to the diversity of email formatting options. Too many email-clients transgress standards or do not prevent malformed emails to be sent out. Sometimes a declared content-type of an email clashed with the actual character-encoding in the email-body, sometimes in a HTML-mail line-feeds where placed inside opening or closing tags. All this made processing the EML content such a chore that I had finally given up.

Today, all processing is done inside Crème Fraiche, with the exception that email-attachments can be handled by the PDFTK-utility. No XML code is ever created and thus I do not cross technology-borders, which is probably a good thing.

Crème Fraiche is the very first program, that I have ever published on Sourceforge and I am quite curious to watch how it will stand its ground after being released into the wilderness of the Open-Source-world.

---