BITESIZED: What is a Zombie?
How do I perform mail merges under LaTeX?
Background
I'm a big fan of LaTeX for word processing (in the processing sense) and desktop publishing tasks. One thing that I've found to be difficult (mostly due to the lack of documentation) is mail merges. I thought I'd do my part to remedy that by writing up some documentation for the textmerg LaTeX package.
Creating the data file
The first step to performing a mail merge is to create the data file. Here's a sample file:
John Doe 123 Nospam Avenue Regina, Saskatchewan, Canada S4T 1A1 Mr. O'No \#13--321 Someplace Street Regina, Saskatchewan, Canada S4T 2B2
Save this file as addresses.dat, in the same directory as your LaTeX file.
This data file can any format you want, as long as it's consistent (i.e., don't use 4 lines for one address and only 3 for the next). Here, we're using 4 fields per address: name, street address, city (etc) and postal code. Design your own, the textmerg package can easily cope with whatever fields (and however many fields) you design.
Notice in the second address, the street address field specifically, that standard LaTex characters (like --) are available, and that the # sign needed to be escaped. That's because these fields are imported *directly* into LaTex. This is handy for formatting because you can use use sequences like 4$^{th}$ Avenue to create nice superscripts (4th Avenue).
Wrapping textmerg around your LaTeX document
Let's take a standard LaTeX letter:
\documentclass[letterpaper,12pt]{letter}
\usepackage{textmerg}
\address{202 Some Street\\ Regina, Sask.\\ S4T 6C6}
\date{March 4$^{th}$, 2001}
\signature{Tillman Hodgson}
\begin{document}
\begin{letter}{\MyName\\ \MyAddress\\ \MyCity\\ \MyPostal}
\opening{Greetings from the Hodgson House,}
Hope this letter finds you well. Of course, it's not a real
letter, just a sample. So that explains why it's surprisingly
short.
\closing{Regards,}
\end{letter}
\end{document}
Next,we hack it up to include the textmerg information. Note the extra {}'s surrounding the entire body of the document: if you miss those, you'll be getting some very strange errors.
The \Fields{} command tells textmerg how to handle the fields in your data file. Since we've specified 4 fields (and given them names), textmerg will read from the data file in 4-line "chunks" and provide the field names as LaTeX commands (acting as variables) for your use elsewhere in the document. Here, we use them in our \begin{} statement to create our letter and in our \opening{} statement to personalize our letter.
\documentclass[letterpaper,12pt]{letter}
\usepackage{textmerg}
\address{202 Some Street\\ Regina, Sask.\\ S4T 6C6}
\date{March 4$^{th}$, 2001}
\signature{Tillman Hodgson}
\begin{document}
\Fields{\MyName\MyAddress\MyCity\MyPostal}
\Merge{addresses.dat}{
\begin{letter}{\MyName\\ \MyAddress\\ \MyCity\\ \MyPostal}
\opening{Howdy \MyName,}
Hope this letter finds you well. Of course, it's not a real
letter, just a sample. So that explains why it's surprisingly
short.
\closing{Regards,}
\end{letter}}
\end{document}
The Makefile
LaTeX is so much easier to deal with if you use Makefiles. Here's an example one that provides "make", "make ps" (for making PostScript output files), "make pdf" (for making PDF output files) and file cleaning commands.
###################################################
# Makefile for latex document 'sample_letter.tex' #
# #
# Automatically handles things like running LaTeX #
# twice to create table of contents correctly #
###################################################
sample_letter:
latex sample_letter.tex
latex sample_letter.tex
ps:
dvips -o sample_letter.ps sample_letter.dvi
pdf:
dvipdf sample_letter.dvi
cruftclean:
rm -f *.aux
rm -f *.log
clean:
rm -f *.aux
rm -f *.log
rm -f *.dvi
distclean:
rm -f *.aux
rm -f *.log
rm -f *.dvi
rm -f *.ps
That's All
And that's all there is to it. Try it out, create some PostScript output and preview it in ghostview or kghostview.
