How to Use IncludeText Fields

Article contributed By Daiya Mitchell and Cindy Meister

IncludeText fields have many possible applications. Say you have information that changes frequently, but needs to be published in several different documents. You can maintain the information in one file and use IncludeText fields to pull the most recent version into the documents for publication. IncludeText fields can also be used as a substitute for the unreliable Master Document feature in Word, if you want to combine chapters of a book manuscript into one file while you continue to edit each chapter file.

Mac users, most of the Mac/Win differences have been noted in the text.

Contents

  1. Creating IncludeText Fields
  2. Basic Tips and Tricks
  3. Other Ways to Create IncludeText Fields
  4. Advanced Tips and Tricks

Creating an IncludeText Field

There are several ways to create an IncludeText field. Here is the method that is easiest to explain and hardest to get wrong, though not necessarily the quickest. This discussion will refer to “source document” and “target document,” assuming that you want to set the target document to include text from the source document. For instance, you might maintain common information in the source document, and have multiple target documents where the same common information is published.

Method 1: Use Insert>File

Decide whether you need to include the entire source document or just a portion of the source document.

If you want to include the entirety of a source document: Open up the target document. Use Insert>File and in the dialog, navigate to the source document that you want to include.

WinWord 2002 and 2003: In the Insert>File dialog, click on the little arrow attached to the Insert button, and choose "Insert as Link." This will insert the entire text of the file as an IncludeText field.

MacWord and WinWord 2000 and before: In the Insert>File dialog, check the box for “link to file.” Click Insert. This will insert the entire text of the file as an IncludeText field.

If you want to include only part of a source document, first you will need to go into the source document and set a bookmark for the text that you want to include. To set the bookmark, select the text you want to include, then go to Insert>Bookmark. Give the bookmark a name—make sure you remember the name!—and click Add.

Return to the target document where you want to include the text. Use Insert>File and in the dialog, navigate to the source document.

WinWord 2002 and 2003: In the Insert>File dialog, click on the Range button. Enter the bookmark name in the resulting dialog, and click OK. Then click on the little arrow attached to the Insert button, and choose "Insert as Link."

MacWord and WinWord 2000 and before: In the Insert>File dialog, check the box for “link to file”, and in the Range/Bookmark field, enter the name of the bookmark. Click Insert.

Caveat: Update Fields!

You may need to update the field directly after creating it. Select all and press F9 to Update Fields, or right-click and select Update Field. Always be sure to update fields regularly, as sometimes everything will look okay but fail when you attempt to update it. Or vice versa—updating can fix a field that looked entirely incorrect.

You should set Tools>Options>Print to “update fields” on printing. (Mac: Word>Preferences>Print.) If this is set, Update Fields will also trigger on Print Preview.

When you reopen the target document after editing the source document, you will need to Update Fields. Now, Word offers a setting to "update automatic links at open." (Win: Tools>Options>General; Mac: Word>Preferences>General) However, it is unreliable in WinWord 2002 and 2003 and doesn't seem to work in MacWord either, so don't trust it. For WinWord 2002 and 2003, see MSKB Article 330079 with an explanation and workarounds.

Also, please note that when you make a change in the source document, the target document stored on the hard drive or server will not magically change to reflect the new source. For the target document to change, the IncludeText field in the target document has to be updated—that's the process that pulls the new information from the source. Usually this requires opening the document and updating fields, but if you are familiar with VBA/macros, you can automate the update fields process.

Analyzing an IncludeText Field

Toggle Field Codes (Win: alt-F9; Mac: option-F9) so that you see the field code instead of the text it results in. You may see something like this sample IncludeText field:

WinWord:

{ INCLUDETEXT "C:\\My Documents\\Port Development RFP.doc" Summary }

MacWord:

{ INCLUDETEXT "Hard Drive:My Documents:Port Development RFP" Summary }

The curly braces { } denote that this is a field. The text in quotation marks denotes the filepath and filename of the source document. The ending text Summary denotes the bookmark used in the field, if you inserted only part of the source document. Note that MacWord and WinWord use different path separators. While a regular WinWord path would only use a single \ between folders, within a field the filepath requires \\.

By default, all fields in Word become shaded in grey when the cursor is inside one, to alert you that you are dealing with a field. IncludeText fields are no exception. You can control the appearance of this shading on the View tab of Tools>Options (Word>Preferences on the Mac).

You may also see bookmark brackets surrounding a selection in the source document.

brackets:

You can control whether you see bookmarks on the View tab of Tools>Options (or Word>Preferences on a Mac). If dealing with bookmarks, it is probably a good idea to be able to see them. In Word 2003, if you used a bookmarked selection for your IncludeText field, bookmarks will also show up in the target document.

Basic Tips and Tricks

You can have multiple IncludeText fields in any target document, and multiple bookmarks in any source document.

You should be aware that including the entirety of a source document brings along the last paragraph mark in the document, which controls quite a lot of formatting and can affect your target document. If you are only including part of a document consider whether you want to include the paragraph mark at the end of your selection, as including it will result in a paragraph break in the target document.

It is also possible to make changes in the IncludeText field in the target document and send the changes back to the source document. To do so, click in the field in the target document, and press control-shift-F7 (Mac: cmd-shift-F7).

As with all fields in Word, you can view field codes, lock fields, and convert fields to text.

Other Ways to Create IncludeText Fields

Method 1 was explained at the beginning of the article. Once you understand how IncludeText fields work and what they should look like, other methods may be preferable. All the Tips and Tricks will apply no matter what method you use.

Method 2: Type the Field

You can create IncludeText Fields by just typing the field by hand. First, press control-F9 to enter the field braces { } (Mac: cmd-F9), then type in the correct syntax. To get a model field that you can mimic, use Method 1, the Insert>File method explained at the beginning. (Field names do not have to be in all caps, but the field may fail without quotation marks around the filepath).

If you are creating multiple similar fields, you can copy and paste one model IncludeText field and then manually edit the bookmark name. To edit the bookmark name, Toggle Field Codes (Win: Alt-F9; Mac: Opt-F9) to show the field code instead of the field result, and edit the code.

Method 3: Use Insert>Field

You can use the Insert>Field dialog, where IncludeText is listed under Links and References. You may want to explore that dialog whether you use it or not, as clicking on Options will show you the switches available to modify the IncludeText field (these are also documented in Help). Switches can be added through the dialog, or by manually editing the field code. This is probably the slowest method.

Alert! If you use the Insert>Field method, Word will automatically add a \* MergeFormat switch to the field. In most cases, you do not want this switch and will need to delete it. The \* MergeFormat switch will change the original formatting of your included text. Help offers more information about this switch. [Thanks to newsgroup poster Chip Orange for this tip]

Advanced Tips and Tricks, and Some Caveats

Be sure to read the Help topic “Field codes: IncludeText field” for a fuller explanation of all the functions you can accomplish with IncludeText fields. If you still need assistance after reading this article and the suggested Help topics, ask on the  the Microsoft's Answers site.

Fields Within Fields

You can have fields within IncludeText fields, but then things can get a little tricky.

Word will update fields within fields by default. But, for example, if your source text includes a SaveDate field (showing the day it was last changed), then you probably want the target document to reflect the proper SaveDate for the source document, not the last day you happened to hit Update Fields in the target document. You can use a switch to tell Word not to update fields inside the IncludeText field. Sample:

{ INCLUDETEXT "C:\\My Documents\\Port Development RFP" Summary \! }

The \! at the end of this sample field is the Lock Result switch, telling Word not to update fields within the IncludeText field.

Known issue: cross-reference fields within an IncludeText field may not update correctly. For example, a cross-reference that is set to show the page number in the source document may suddenly display “see below” in the target document. The bug is intermittent and occurs only under certain circumstances, but at this time there is no known fix or prevention. At present it has been linked to WinWord 2002 and 2003.

Other Types of Source Documents

The source document for an IncludeText field does not have to be a Word document. If you want to include text from a source document that is an Excel worksheet or a different type of text file, you need to tell the IncludeText field what type of document the source is, by adding a conversion switch and ClassName to the IncludeText field. Sample:

{ INCLUDETEXT “My RTF Document.rtf” \c MSRTF }

In this example, \c is the switch that signifies a conversion will be necessary and MSRTF is the ClassName that signifies which type of conversion is required.

What Types of Files Can You Include?

For all possible file formats and the appropriate ClassNames to use, see the Help topic “Class names of file converters". WinWord 2003 can use XML but it must be WordProcessingML, not just any XML file.

All Word files from Word 97 to Word 2004, Win or Mac versions, use the same basic file format, and do not need any conversion. Conversion is required for Word files from Word 95 and earlier versions. Word will have a new file format, based on XML, for versions after WinWord 2003/MacWord 2004. If this article has not been updated to deal with such cases, be sure to check Help in the most recent versions of Word.

FilePaths

Any kind of link—in a Word document, on the web—relies on a filepath to find the object of the link. The filepath can be absolute (showing the complete filepath from harddrive or server to filename) or relative (showing only that portion of the filepath which differs from the filepath of the target document). For instance, if the target and source document are in the same folder, the relative filepath consists of just the filename.

By default, Word uses absolute filepaths when you create an IncludeText field. You can change them to relative filepaths yourself, by editing the field code.

In most applications, a good way to deal with filepaths is to use relative filepaths and ensure that the folder structure is always correct. However, Word does not handle relative filepaths correctly. (Please also see the Word Help topic: "Guidelines for managing Web files and hyperlinks".)

When Word sees a relative filepath in a document, instead of checking the filepath against the filepath of the document, Word uses the currently active folder to check the relative filepaths. For instance, if you opened the target doc, then opened the source doc, Word will measure all filepaths against the source doc, as that is the currently active folder. In the target doc, your relative filepaths will suddenly stop working and will show Error! Cannot open file. If you only open the target doc, however, or reopen the target doc after opening the source doc, the relative filepaths will work fine after updating them. Again, always be sure to update fields regularly, as sometimes everything will look okay but fail when you attempt to update it. Or vice versa—updating can fix a field that looked entirely incorrect.

The really annoying thing about this behavior is that it's guaranteed to be intermittent. It will only cause a problem some of the time. You can go through the same actions, and sometimes all your links will fail, and sometimes they won't (since most of us don't pay attention to the invisible setting for the currently active folder in Word).

Workaround 1: use relative filepaths, but go into File>Properties and set a “hyperlink base” for the document. Then Word should read all relative filepaths from that base, instead of checking against the currently active folder.

Workaround 2: use absolute filepaths, but create a custom document property to store the base filepath (File>Properties>Custom). Then use a DocProperty field to carry the path info into the IncludeText fields. You can easily change the custom document property in File>Properties. The nested fields might look like this:

{ INCLUDETEXT "{ DOCPROPERTY LinkFilePath }Source.doc" Bookmark }

Update Links on Save?

Furthermore, Word 2000 added an option to “update links on save”, which will check your relative filepaths and make sure the referenced file is in the same folder. If this option is checked when you save the doc, and if the currently active folder is not the folder that holds the target doc (and you have not set a hyperlink base as above), then Word will think your links are wrong, and “helpfully” update the relative filepaths for you. Originally this checkbox only activated when saving as HTML, but in Word 2002, it was generalized to all saves. So you probably want to uncheck this box.

The relevant checkbox is buried in Tools>Options>General>Web Options, on the Files panel. (MacWord: Word>Preferences>General>Web Options, on the Files panel).

If you do let Word update the link for you, it will change the relative path to an absolute path, which will not necessarily cause a problem, unless you later move the containing folder, at which point the absolute hyperlinks will be incorrect. It will also add the \* MergeFormatINET switch to the end of the field code. This MergeFormat switch might cause an immediate problem, as it may change your formatting.