<p style="Heading 1"><bookmark type="start" name="top"/><bookmark type="end" name="top"/>How to Mail Merge</p>
<p style="Normal">The process involves three main steps: <a xlink:href="#datasource">creating the data source</a>, <a xlink:href="#doctemplate">creating the document template</a>, and <a xlink:href="#printing">printing the merged result</a>. Then you can <a xlink:href="#uses">get a little fancy</a>.</p>
<p style="Heading 2"><bookmark type="start" name="datasource"/><bookmark type="end" name="datasource"/>Creating the data source</p>
<p style="Normal">As of this writing, there are three common options for data source format:</p>
<p style="Normal"><c props="height:0in; display:inline; width:0in; homogeneous:1">The third option is usually more trouble than it is worth for basic mail merge operations, and the second is identical to the first only with tabs instead of commas, so this document will keep it simple by only introducing the first.</c><c props="height:0in; display:inline; width:0in; homogeneous:1"></c></p>
<p style="Normal"><c props="height:0in; display:inline; width:0in; homogeneous:1"></c>Using any text editor (or AbiWord, if you remember to save as plain text) you will create a text file with two or more rows of data. The first row is a list of field names, separated only by commas, as follows:</p>
<p style="Normal">Note that the last field on the line does not have a comma at the end. These names define what fields of data are going to be available in the data source, though you do not necessarily have to use them all in your merge. All subsequent lines in the data source will be as follows:</p>
<p style="Normal">Again, note the lack of comma (or any other unwarranted delimiter) at the beginning and end of each line. Each value is the text with which the field name will be substituted when you print your merged file. For every field, a value exists, in corresponding order within each line, and each line is a separate instance of the document (a separate copy printed). Values can be empty but must still be comma delimited:<c></c></p>
<p style="Normal">Therefore the above would leave field2 blank, without interrupting the flow of the merge. Let's make a more realistic example for later use:<c></c></p>
<p style="Example Text"><c></c>FirstName,LastName,StreetAddr,City,State,Zip<br/>Mark,Gilbert,666 Microsoft Way,Redmond,WA,<br/>David,Chart,123 Easydoc Street,Userville,MD,12345<br/>Dom,Lachowicz,777 GNU Ave.,Utopia,CA,02111</p>
<p style="Normal">In the example that follows, the above will be saved to a plain text file called mergeme.csv (csv for Comma Separated Values, if it helps). Note that there is a comma at the end of the first line. This is because, while there is no data for field Zip in that value set, the field still exists and needs to be accounted for. Forgetting to do this will cause problems; read on.<c></c></p>
<p style="Heading 2"><bookmark type="start" name="doctemplate"/><bookmark type="end" name="doctemplate"/>Creating the document template<c></c></p>
<p style="Normal">This is very simple. You create whatever document you want in AbiWord, and where you want values substituted for fields during the merge, you insert mail merge fields. The easiest way to do this involves prepopulating the mail merge field dialog with the fields in your csv file. To do so, run AbiWord with the -m argument, For example:<c></c></p>
<p style="Example Text">AbiWord-2.0 -m mergeme.csv<br/>(via the command prompt, run dialog, or shell prompt)<c></c></p>
<p style="Normal"><c props="lang:en-US">Now, to access the mail merge field insertion dialog, open the '</c><c props="lang:en-US"></c><c props="text-decoration:underline; lang:en-US">I</c><c props="lang:en-US">nsert' menu and click '</c><c props="text-decoration:underline; lang:en-US">M</c><c props="text-decoration:none; lang:en-US">ail Merge Field'. You should see a list of fields as shown in the dialog below.</c></p>
<p style="Normal" props="text-align:left">All you have to do to insert a field at the cursor's current location in the document is select the appropriate field in the list and click <c props="text-decoration:underline">I</c><c props="text-decoration:underline"></c><c props="text-decoration:none">nsert. The dialog even stays open and on top for you so you can move the cursor around in the document and insert however many fields you like, where you like. When done, click </c><c props="text-decoration:underline">C</c><c props="text-decoration:none">lose to close the dialog. Save the file as a normal AbiWord file (for this example, mergeme.abw). An example is shown below.</c></p>
<p style="Heading 2"><bookmark type="start" name="printing"/><bookmark type="end" name="printing"/>Printing the merged result</p>
<p style="Normal">There is not yet a working mechanism to print from the graphical interface, but the command to perform the merge and print is magnificently simple:</p>
<p style="Example Text">AbiWord-2.0 -m mergeme.csv -p mergeme.ps mergeme.abw<br/>(again from the command prompt, run dialog, or shell prompt)<c></c></p>
<p style="Normal">The first parameter, '-m mergeme.csv' is still simply telling the program where to get its data. The second parameter, '-p mergeme.ps' is the switch to print with the file name to print postscript to, but all the usual potential values for -p work, if you want to print directly to your printer or filter or anything else. The third and last parameter, 'mergeme.abw' is the document template you just created. Note that when you print, there's a separate copy of the entire document for every set of values in the csv source. If you print to file, the files will be named like mergeme.ps-0, mergeme.ps-1, mergeme.ps-2. That's one .ps file for every set of values, with the numbering starting at 0.<c></c></p>
<p style="Normal"><c></c></p>
<p style="Normal">Beware of a corrupted csv. If a field is not accounted for (in other words, your file is missing a comma somewhere), the merge and print process won't work. Remember, if you don't have the data for a given field in one value set, just type another comma and move on. The field will be substituted with nothing (effectively deleted for that value set).<c></c></p>
<p style="Normal">Aside from inserting names on letters, you can use the mail merge system in the same manner to create envelopes for those letters.</p>
<p style="Normal">Mail merge, despite its name, is not just for mailing. It can also be used whenever you need to efficiently substitute multiple similarly formatted value sets from a data source, for any task or project. If you can create a csv of it, you can merge it. Other sources will soon be available such as various databases types, but many such database and address book applications support exporting to csv. Use your imagination to make the most use out of merging!</p>
