With the help of Geoff Heard, Geoff Roynon and Kino, I wrote two Perl macros for Nisus Writer Express 2.x for mail merging and address label printing. These macros are based on a macro written by David T. Linker three years ago.
You will find in the package:
- dl-k-Mail Merge.pl
- Merge OUTPUT.rtf
- Merge template.rtf
- Merge.rtf
- Merge.txt
- Merge template samples: (folder)
- Merge template_no_page.rtf
- Merge template_pagebreak.rtf
- Merge template_section_break_footer_page.rtf
- Merge template_section_break_header_page.rtf
The file dl-k-Mail Merge.pl is the macro file. You will put it in the folder /Users/[your_account]/Library/Application Support/Nisus Writer/Macros/.
The other files are example files. To understand how this system works, please open Merge.rtf or Merge.txt in NWE 2.x (they are the same in contents). You will find a text like this:
firstname,gift
Joe,stuffed moose
Bob,old barrel
Jeff,Over the rainbow
Hélène,favours
The first line has the keywords, delimited by a comma (,) -- notice that the comma is not followed by a space! Here, there are two keywords: firstname and gift.
Subsequent lines have the words that will replace the keywords in the output file. Each of these words are delimited by a comma (so you cannot use comma in these words...!).
Now, make sure that you have the file Merge template.rtf in the same folder as the file Merge.rtf (or Merge.txt). Open that file in NWE: you will find the following text:
Dear «firstname»
Thank you for the «gift» you gave me.
My name is «{me}». My email address is «{my email}».
Today is «{$_ = localtime}». 500 + 2 is «{500+2}».
You can now close this file. Make sure that you have the file Merge.rtf at the frontmost window; then run the macro dl-k-Mail Merge.pl from the Macro menu.
NWE opens then a file named Merge OUTPUT.rtf. It will have four pages, each page ending with a page break mark; four is the number of the lines of the words in the file Merge.rtf. You will read in the first page:
Dear Joe
Thank you for the stuffed moose you gave me.
My name is Nobumi Iyanaga. My email address is n-iyanag@ppp.bekkoame.ne.jp.
Today is Thu Jul 21 09:41:44 2005. 500 + 2 is 502.
You can see now how this system works. The «firstname» in the template file is replaced with Joe in the first page of the OUTPUT file; and the «gift» in the template is replaced with stuffed moose in the same page in the OUTPUT file.
This is the basic mail merging functionality. I added to it a special functionality that I would name "Glossary feature". To see how it works, please open the script dl-k-Mail Merge.pl; at the end of the file, after the line that says "__END__", there are these lines:
me Nobumi Iyanaga
my email n-iyanag@nifty.com
my web site http://www.bekkoame.ne.jp/~n-iyanag/
Each line has two fields, delimited by a tab. At the left side, there are "entries" or "shortcuts", and at the right side, there are corresponding "meanings" or "expanded words". You cannot use the characters "«", "{", "}", "»", tab, and return, but otherwise, you should be able to use any characters.
The words in the template file which are enclosed between "«{" and "}»", such as «{me}» and «{my email}» get replaced with the corresponding "meanings" in the glossary, if the "entry" is found in the glossary.
Now, as to the other "magic words", such as «{$_ = localtime}» and «{500+2}», they are Perl expressions; when words enclosed between "«{" and "}»" are NOT found in the "glossary" at the end of the script, the script attempts to interpret them as Perl expressions, and if that returns some string, it replaces them with the returned values. -- If the words enclosed between "«{" and "}»" are not in the "glossary", and have no meaning as Perl expressions, then an empty string ("") will replace them.
Now, I will have to explain the files in the folder Merge template samples. To see how they works, the simplest is to do the following steps:
- Select one of these files on the Finder, for example Merge template_section_break_footer_page.rtf, and press Command + D: a copy of the file, named Merge template_section_break_footer_page copy.rtf, will be generated.
- Move temporarily the file Merge template.rtf in the folder Merge template samples; move the newly generated file Merge template_section_break_footer_page copy.rtf in the parent-folder (mail_merge_06-10), and rename it Merge template.rtf.
- Open that new Merge template.rtf in NWE to see how it looks: the text is the same, but at the end of the page, you see a Section break (next page) mark; you see also that the page number is inserted in the footer, at the center; you see that on the second blank page also, the has the same page number, at the center.
- Now, close that window, and open the file Merge.rtf; then run the macro dl-k-Mail Merge.pl from the Macro menu.
You will see that each section of the file Merge OUTPUT.rtf has the same formatting as the original template file.
Opening the other sample template files in the folder Merge template samples, you will see different formattings. The default Merge template.rtf is the same file as Merge template_no_page.rtf.
To use one of the sample template files, you will follow the same steps as those described above. You can also edit your own template file. In such a case, please keep in mind that:
- If you use a section break or a page break, there will be necessarily a second page. That page must be blank, except for the header/footer setting.
- If you want to have a new page numbering restarting at each section break, you will have to specify the setting, using Section Palette, and checking the check box Starting Page, for the second page.
- Take care of the second page footer and/or header setting.
- If you put neither a page break nor a section break (this is the setting of the default template file), the macro dl-k-Mail Merge.pl will insert automatically a page break at the end of each letter.
There is another little feature that was not explained at the first release: that is the possibility of setting styles in the template file, especially for the keywords. If you want to set all the «firstname» to italic, and all the «gift» to bold, then, you can do so in the template file; and every section in the OUTPUT file will reflect these styles. But please keep in mind that you have to include the enclosing "«" and "»" when you set styles for the keywords. If you omit to do this, the macro will not work at all.
So, if you want to write a letter to several persons with the same contents, except the name and address of the recipients, etc., you will:
- Write your letter, leaving the name and address of your recipients in the format «firstname», «lastname», «address1», «address2», etc.; if you want, you can add glossary entries, enclosed between "«{" and "}»" [Be sure that you have edited the last lines of the script "dl-k-Mail Merge.pl"]. Note that you can type "«" and "»" with Option + \ and Option + Shift + \. Format the page break or section break, and header and/or footer as you want. If you want, add styles to keywords, including the enclosing "«" and "»". Save your letter in a folder, with a name followed by " template.rtf" (note the space befor "template") -- for example /Users/[your_account]/Documents/Letters/your_mail_merge_letter1/letter1 template.rtf.
- Now, write your merge data file. It can be either a plain text UTF-8 file, or an rtf file. The first line must contain the keywords for different fields, such as:
firstname,lastname,address1,address2
The subsequent lines must contain the actual data for these fields.
Note that there is NO space after the comma!
Now, save that file in the SAME folder as the template file, with the SAME name as the template file, stripped of " template" -- for example: /Users/[your_account]/Documents/Letters/your_mail_merge_letter1/letter1.rtf
- Now, with this latter file at the frontmost (the template file can be closed), run the macro named "dl-k-Mail Merge.pl" from the Macro menu.
A new file will open, with a name in which " OUTPUT" will be added instead of " template", for example /Users/[your_account]/Documents/Letters/your_mail_merge_letter1/letter1 OUTPUT.rtf. Each page or section will contain the letter with the data of each line of the data file (each letter will be separated by a page break mark (U+000C) or a section break mark -- you can find the page break mark or section break mark with "\x000C", in the PowerFind Pro mode in NWE's Find/Replace window.
B. Address label printing macro
You will find in the package:
- Label_example OUTPUT.rtf
- Label_example template.rtf
- Label_example.rtf
- Label_example.txt
- letter_label.pl
The file letter_label.pl is the macro file. You will put it in the folder /Users/[your_account]/Library/Application Support/Nisus Writer/Macros/.
To understand how this works, the best is to examine the example files: open the file "Label_example template.rtf" in NWE. Here is a captured image of some first lines of the template file:
As you see, this is a document with two columns; on the left side, there are lines for recipients addresses:
«dest_FirstName» «dest_LastName»
«dest_FirstLine»
«dest_SecondLine»
«dest_City»
«dest_PostCode»
Each of the keywords is preceded by a "prefix", which is here "dest_".
On the right side, there are lines for the sender's address:
«exp_FirstName» «exp_LastName»
«exp_FirstLine»
«exp_SecondLine»
«exp_City»
«exp_PostCode»
Each keyword is preceded by the "prefix" "exp_".
Now, have a look at the data file, "Label_example.rtf" (or Label_example.txt: you can use either an rtf file or a plain text UTF-8 file). Here is the first line:
dest,exp,FirstName,LastName,FirstLine,SecondLine,City,PostCode
The first two "keywords" are "prefixes" (without the underbar): "dest" and "exp". The other words, delimited by a comma, in the first lines are "normal keywords".
Now, the second line is:
John,Hudson,42 rue Napoléon,Toshima-ku,Tokyo,100-0010
This is the data for the first recipient;
The third line has:
Geoff,Harrison,52 High Road,Harima,Osaka,500-8000
This is the data for the first sender. [Of course, these addresses are fictive!]
The subsequent lines in the data file are in the same order: the fourth line, data for the second recipient, the fifth line, data for the second sender, and so on...
Now, make sure that you have the two files, "Label_example template.rtf" and "Label_example.rtf" in the same folder. You can close the template file; the data file must be at the frontmost. Run the macro "letter_label" from the Macro menu.
Note that if you don't have installed the /Developer folder, you will get an error message, saying that the file /Developer/Tools/SetFile cannot be found. In that case, please open the script "dl-k-Mail Merge.pl" in an editor, and add the comment mark "#" at the beginning of the line 174, the line which has:
`/Developer/Tools/SetFile -c NISX "$merge_output_file"`;
(This line sets the file as NWE file; if this line is commented out, the output file will be a generic rtf file.)
A new file, named "Label_example OUTPUT.rtf" will be generated and open in NWE. Here is a screen shot of this file:
To use this macro, you will:
- make your own template file. It must have two columns; the font size, line height, etc., must be ajusted, so that when printed on label papers, you have the wanted format. The template must contain as many recipient-sender address pairs as your data contain -- this is the most important difference from the mail merge macro.
Each record can contain several fields, identified by a keyword. Each field name must be preceded by a "prefix" (followed by an underbar "_"), different for the recipient and the sender.
The template file must be saved in the same folder as the data file; it's name must be the same as the data file, plus " template".
- You will have to create your data file. The fields are delimited by a comma (not followed by a space!). The first two fields in the first line are the "prefixes" which distinguish the recipient and the sender addresses. After these two special keywords, normal keywords will be listed in the first line.
After the first line, the subsequent lines are the actual address lines. Even-numbered lines (second, fourth, sixth, etc.) are for recipients' addresses, and odd-numbered lines (third, fifth, seventh, etc.) are for the corresponding senders' addresses.
The data file must be saved in the same folder as the template file. It has the same name as this file, except the added " template" of the template file. It can be either an rtf file or a plain text UTF-8 file.
- When the two files are ready, you can close the template file. Be sure that the data file is at the frontmost, and run the macro "letter_label" from the Macro menu.
A new file will be opened in NWE, having the data in the label format.
Download
Please download the mail merge macro for NWE 2.x from here (20K to download).
And please download the address label macro for NWE 2.x from here (7K to download).
Note that these scripts may contain bugs. Please use them with CAUTION. And if you have any comments, please write me.
Have fun!
