SDA 4.1 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 on a specific PC.

CONTENTS

DOWNLOAD THE MACRO FILE ONTO 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:

USING THE SDA CODEBOOK MACROS

After you have installed the macro, you can create a Word codebook file by following these steps: 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 must be updated after all the changes have been made. So if you make modifications that affect the page numbers, you must 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:

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 distribute codebooks as PDF files, which can be e-mailed or copied onto disks or flash drives. They can also be put on the Web, so anyone with a browser can view and print them -- but cannot modify them before printing. The Adobe Acrobat "Reader" software for PDF files can be downloaded and used for free.

Current versions of Microsoft Word allow you save Word files as PDF files. Select the "Save as ..." option and select PDF as the desired file type. The file will be saved as a PDF file with the suffix '.pdf'.

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

CSM, UC Berkeley/ISA
March 18, 2019