How to document Microsoft Word mail merge templates? [closed] - documentation

Question

Closed. This question is opinion-based. It is not currently accepting answers.
Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.
Closed 4 years ago.
Improve this question
I'm using the directory mail merge feature in Word 2010 to create a formatted document (of requirements) using an Excel 2010 spreadsheet as the source of data.
Things work, but I have a compact mess of braces, formatted single characters, and fields, with very little whitespace (as this would change my output). I inserted fields with CTRL-F9 and Word treats them as their own objects rather than individual characters.
The complications come from having a lot of conditional fields, some of which are nested, and don't have the typical cues that most code has for seeing the nesting structure (line breaks, indentation, etc.)
Is there a straightforward way to document the mail merge template code from within the document? Or will I need to maintain a separate text file if I want to take advantage of whitespace and other readability cues?

Answer 1

Things you can do to help with field code documentation include the following. But there are quite a few gotchas, which complicates the answer. I've tried to cover them below.
Use formatting characters such as paragraph marks inside field code
braces to improve layout
Use field code types with empty results such as "SET" to insert
documentation
Use hidden text inside field codes to insert documentation
Remove of QUOTATION MARK (") characters that are not absolutely
necessary
An example of (1):
If you have something like:
{ IF { MERGEFIELD A } = { bookmarka } "{ MERGEFIELD B }" "{ IF { MERGEFIELD C } = { bookmarkb } "result2" "result3" }" }
Then you can lay it out like this without altering the result of the IF fields:
{ IF { MERGEFIELD A } = { bookmarka }
"{ MERGEFIELD B }"
"{ IF { MERGEFIELD C } = { bookmarkb }
"result2"
"result3" }" }
by clicking after { bookmarka } and pressing Enter to enter a normal Word paragraph mark, then inserting some spaces before the QUOTATION MARK character.
Different people might choose different indentation patterns and ways of dealing with closing "}". There are no standards or widely used traditions in this area as there are with, say, C code.
There is a drawback. Every time you switch between field code and field results views, Word may repaginate in a long document and the chances are that you will "lose your place" in the code.
An example of (2) is that you can insert a { SET } field in many places in your code (but not all) and put pretty much any text after the "SET variablename " part. Or you could define a bookmark called "REMARK" ("COMMENT" seems too easily confused with the built-in field code COMMENTS)
e.g.
{ SET REMARK I wouldn't use "COMMENT" }
or put
{ SET REMARK "" }
at the beginning of your code then use
{ REMARK I wouldn't use "COMMENT" }
{ REMARK because it might be confused with the "COMMENTS" field }
Just bear in mind that you can't put a field code absolutely anywhere in your field code "block", because in some places Word's intepretation of the field coding will change. e.g.
{ IF 1 = 0 { MERGEFIELD X } { MERGEFIELD Y } }
should always insert the value of { MERGEFIELD Y }
but
{ IF 1 = 1 { MERGEFIELD X }{ REMARK insert X } { MERGEFIELD Y } }
would insert the result of { REMARK insert X }
You could use
{ IF 1 = 1 "{ MERGEFIELD X }{ REMARK insert X }" { MERGEFIELD Y } }
or in this case,
{ IF 1 = 1 { MERGEFIELD X { REMARK insert X } } { MERGEFIELD Y } }
On point (3) Word generally ignores hidden text in field codes, so you can use hidden text to insert documentation. But again, you have to be careful where you put it. For example, this approach is useless for field types that are normally marked as Hidden, such as TC and XE. Personally, I do not think the idea of inserting documentation then hiding it is ideal - quite apart from anything else, it would be very easy to delete without even knowing it was there. But it can be done.
As for point 4, the way Microsoft Word inserts some field types and the documentation (such as it is) for the "field code language" means that there is a tradition of surrounding some things with QUOTATION MARK characters. Examples typically show this in IF fields...
{ IF comparand-1 operator comparand-2 "result if true" "result if false" }
In that particular case, you would need the quotation marks, but if the "result if true" or "result if false" are either a single word (as far as Word is concerned) or the result of a single field code, then you can omit the quotation marks, e.g.
{ IF comparand-1 operator comparand-2 true false }
or
{ IF comparand-1 operator comparand-2 { REF bookmarka } { REF bookmarkb } }
Personally, I prefer to use the quotation marks, because it is the pattern that many users are familiar with, and if you modify the field code in some way you don't have to work out whether you need to re-insert quotaion marks, and so on. But that is just my preference. In the case where you have nested IF fields in particular, you very often have individual field codes as results and the quotation marks probably do not really increase clarity.
You also have to bear in mind that in some cases you must surround fields with quotation marks. For example, if you want to ensure that two values are compared as strings, at the very least you should quote them.
For example, suppose you have a mergefield X that could contain any text string and you want to compare that string with "3". If you use
{ IF { MERGEFIELD X } = 3 True False }
then if X is "1+2", "3", "4-1" you will get a True result. In this case you need
{ IF "{ MERGEFIELD X }" = 3 True False }
and if the "3" was replaced by some kind of variable field, you would probably need
{ IF "{ MERGEFIELD X }" = "{ theVariable }" 3 True False }
Word's tendency to evaluate simple arithmetic expressions in such scenarios is not the only thing that can go wrong. If { MERGEFIELD X } evaluates to the name of a bookmark that you have defined in your document, Word tends to dereference that, and use the value of that bookmark instead of the value of the MERGEFIELD field, unless you surround the { MERGEFIELD X } by quotation marks.