SDA 3.5 Documentation for WORDMACRO

NAME

wordmacro - Install and Use Word Macro for Codebooks

DESCRIPTION

The XCODEBK program can generate a "tagged" codebook file which can then be read into Microsoft Word. The various "tags" (within angle brackets) in the file indicate that a certain format or style is to be applied to that part of the codebook. And the definition of the various styles is defined in the SDA codebook macro package. To make this work, the SDA codebook macro package must be installed into the copy of Word that resides on the computer that is used to create the Word codebook.

This document explains how to install and use the special SDA codebook macro package. You only need to install the macro once.

PUT THE MACRO FILE ON YOUR PC

A copy of the macro file is distributed with the SDA package and can be found in the same directory as the SDA programs. The name of the file is ’sdacdbk.txt’. You can also download the file by clicking here and then saving the file.

INSTALL THE MACRO DEFINITIONS

To install the SDA macro, follow these steps:

Start the Microsoft Word program on your PC.
Click on ’Tools’, then ’Macro’, then ’Macros’.
(This brings up the "Macros" dialog box.)
Enter the macro name ’sdacdbk’ at the top of the Macro dialog box.
(This will be the name of the macro to use later.)
Click on the "Create" button
(This brings up the Visual Basic window for editing the new macro’s code.)
Delete ALL the text in the window -- THIS IS VERY IMPORTANT.
(This includes the lines beginning ’Sub sdacdbk()’ down to ’End Sub’.)
Click on ’Insert’ at the top of your screen, then on ’File’.
(This brings up the usual Windows "File" dialog box.)
Find the ’sdacdbk.txt’ file, select it, then click on ’Open’ -- this installs the macro.
(You will find this macro file in the folder or directory where you put it when you downloaded the file.)
Close the Visual Basic editor, by clicking the ’X’ in the upper right-hand corner.
(This takes you back into the usual Word environment.)
Exit from Word, saying "yes" to modification of the ’normal.dot’ template.
(The macro definitions will then be available whenever the default ’normal.dot’ template is used. If you are using some template other than the default ’normal.dot’, the macro definitions will be attached to that template.)

USING THE SDA CODEBOOK MACROS

After you have installed the macro, you can create a Word codebook file by following these steps:

Have the tagged codebook file available on your PC.
(A tagged codebook file is produced by the XCODEBK program when you specify ’type=tagged1side’ or ’type=tagged2side’ in the command file. The tagged file is a text file, with indications of where to apply each style. This is the file to which Word will apply the SDA codebook macro. If you want to download a small tagged file for testing, click here and then save the file.)
Start the Microsoft Word program on your PC.
(Unless you are already in the program)
Click on ’File’ then ’Open’, then find your tagged codebook file and bring it into Word.
(Once you find your file, you can double-click on it to bring it into Word.)
Click on ’Tools’, then ’Macro’, then ’Macros’.
(This brings up the processor for macros.)
Select ’sdacdbk’ from the drop-down list of available macros.
(It should be on that list, if you installed the macro successfully.)
Click ’Run’, on the right hand side of the dialog box.
(This indicates that you want to apply the macro to the tagged file.)
Read the instructions, then click on ’OK’.
Specify a name for the new Word file that will be created -- it must have a ’.doc’ suffix.
Wait for Word to apply the macro -- until a message box appears.
(The time required for Word to process the file depends on the size of your tagged file, and the speed of your computer. The table of contents is the last part to be generated.)
Save the new Word file.
(This new file will be a different file from the tagged file that was produced by XCODEBK.)
View and/or print the new Word document.
Exit from Word when you are finished.

Once you have generated the Word codebook, it can be edited like any other Word file. One thing to keep in mind is that the table of contents is produced dynamically. So if you make modifications that affect the page numbers, you can easily recreate the table of contents by putting your cursor anywhere in the area of the table of contents and pressing the ’F9’ key.

CUSTOMIZING WORD CODEBOOKS PRODUCED BY THE ’SDACDBK’ MACRO

There are two basic ways to modify the format of the Word codebooks produced by the "sdacdbk" macro: 1) the macro-generated codebook document can be modified afterwards, using Word; 2) the macro itself can be modified. We’ll discuss each of these approaches in turn.

1. Edit Your Word Document

The simplest approach is to run the "sdacdbk" macro as is. Once you’ve generated a Word document for your codebook, it can be edited like any other Word document by using Word’s various menus and dialogs. Since this approach is relatively easy and straightforward, this is what we recommend most users do. See also the next section, containing some tips on changing the format of Word codebooks.

2. Modify the ’SDACDBK’ Macro

If you are familiar with Visual Basic and the Word "object model" (or are willing to learn) then it might be reasonable in some circumstances to modify the "sdacdbk" macro so it automatically produces the format you want.

For example, it would be relatively simple for a Visual Basic programmer to alter the font properties in the various style definitions in the macro. If you produce a large volume of codebooks that all have the same formatting, then it might be reasonable to customize the macro code to avoid some hand- editing. (Be advised though that the "tagged" output format may be modified somewhat in future versions. So the customizations you make to the current "sdacdbk" macro may not be fully compatible with future "tagged" output versions.)

Various books and online resources are available for learning about Visual Basic programming with Word. One book we have found useful is: Steven Roman, Writing Word Macros: Learning to Program the Word Object Model Using VBA. New York: O’Reilly and Associates, 1999.

Of course, you can also combine these approaches. For example, you might want all of your codebooks to have a specific font size for certain style definitions. You could achieve this by customizing the code in the "sdacdbk" macro to set your special font size for each style definition. But then you might also want to add charts and graphics that are specific to a particular codebook. For this latter type of modification, you would just edit the Word document by inserting the charts and graphics you wish, after first applying your modified "sdacdbk" macro.

TIPS ON CHANGING THE FORMAT OF WORD CODEBOOKS

Styles

The "sdacdbk" macro defines various formatting styles and adds them to the current document’s template. A "style" in Word is just a definition of various formatting properties -- such as font, point size, indentations, etc. -- that can be applied to various parts of a document. The "sdacdbk" macro’s style names all begin with "Sda" and their properties can be viewed and modified from within Word by going to the "Format" menu and clicking "Style ...". (If you want to customize the style definitions in the macro itself, the definitions are clearly identified with comments in the code.)

If you change the codebook fonts, you need to be aware of the distinction between monospace and non-monospace fonts. The variable descriptions in an SDA codebook often include a frequency distribution with numbers in columns. To line up correctly, these columns must use a monospace font -- that is, a font in which each letter takes up the same amount of space. Therefore, the "sdacdbk" macro applies the monospace "Courier New" font to those sections of the codebook -- such as variable descriptions -- where the "lining up" of text might be an issue.

Introductions and appendices are also presented in a monospace font by default, since they may also include information where spacing is an issue. However, you can easily change the default monospace font that is applied to these introductions and appendices (or parts of these sections) by using regular Word editing commands.

Updating and Modifying the Table of Contents

Modifying a Word codebook -- adding charts, inserting text, changing the fonts in certain passages, etc. -- may affect the page numbering. Whenever the table of contents needs to be updated to reflect such changes, just put the cursor anywhere in the area of the table of contents and press the ’F9’ key.

If you want to modify what appears in the table of contents, it is important to understand how it is generated by Word. The Word program looks through the entire document for material that has been characterized or "tagged" as a heading. The table of contents is then generated automatically by putting all of those heading items together. The "sdacdbk" macro characterizes or "tags" as a heading the following items:

titles of the introductions and appendices
headings for groups of variables and,
the name and label of each variable

You can add your own items to the table of contents just by applying a heading style to the text you want to appear in the table of contents. For example, if you add a chart (with a title) to your codebook, just apply an appropriate heading style to the chart’s title and update the table of contents by pressing the ’F9’ key.

Note that each heading style is defined as a level-1 heading, a level-2 heading, and so on up to a level-9 heading. You can specify the range of heading levels that your table of contents will display. By default, the sdacdbk macro will include levels 1, 2, and 3. (The headings for groups of variables are designated as levels 1 and 2, and the individual variable names and labels are designated as level 3.) If you wanted to include the headings for groups of variables, but not the individual variable names and labels, you would set the top of the range to level 2.

Word also enables you to change the format of the table of contents as a whole by providing many built-in styles that can be chosen by selecting from a list. If you are interested in modifying the appearance of your codebook’s table of contents, it is worth exploring Word’s many options in this area.

Headers and Footers

The "sdacdbk" macro creates headers and footers for the codebook pages. These headers and footers are "one-sided" or "two-sided" depending on whether the codebook "type" was specified as "tagged1side" or "tagged2side" in the XCODEBK batch options file. A "one-sided" header or footer prints in the same format on every page. A "two-sided" header or footer prints in different formats on even and odd pages to accommodate two-sided printing.

By default, the study title and the page number are printed on opposite ends of the header line. And the date the codebook was created is printed in the center of the footer line. However, you can easily change the content and the format of the headers and footers from within Word. (Go to the "View" menu and select "Header and Footer".)

Long documents in Word are typically broken up into "sections" to make certain formatting tasks easier. Page numbering, header and footer styles, and other formats can be specified individually for each section. For example, it’s customary for books to 1) have no page numbering or header/footer information on the title page; 2) use roman numerals for the page numbers in the table of contents; 3) re-start the page numbering on the first "real" page of the book and use arabic numerals.

The "sdacdbk" macro follows this convention and uses Word sections to format the codebook headers and footers accordingly. The first section, the title page, has a blank header/footer. The second section is the table of contents, with page numbers in roman numerals. The rest of the codebook is also broken up into sections -- one for the introductions, one for individual variable descriptions, and one for the appendices. The page numbering re-starts with the first introduction (in arabic numerals) and is continuous to the end of the codebook. Also, since each of these final three sections has the same header/footer format, the Word "link to previous" property is used to keep the formatting consistent.

Converting to a PDF document for the Web

Word codebooks can be printed out and distributed by hand or by mail. Users can also receive or download a copy of the Word document and print it out for themselves. Keep in mind, however, that if users obtain a copy of the Word file, they can also modify it before they print it.

It is often desirable, therefore, to put printable documents on the Web, so anyone with a browser can view and print them -- but cannot modify them before printing. Typically these documents are in "PDF" format since the Adobe Acrobat "Reader" software can be downloaded and used for free.

If you purchase the the version of Adobe Acrobat that creates PDF files, it is easy to produce a PDF-format codebook from your Word-format codebook. The newer versions of this software plug into your Word software so that you can just "Save as ..." to PDF format from within Word. No other special editing or processing is required.

Here’s an example of a codebook in Word format and the same codebook after it’s been automatically converted to PDF format from Word.

CSM, UC Berkeley
April 12, 2011