SDA 3.5 Documentation for XCODEBK FORMATTING

NAME

xcodebk formatting - Summary of formatting instructions used by XCODEBK

DESCRIPTION

The formatting instructions listed below are recognized in templates and variable lists by the XCODEBK program. Full descriptions of their use are given in the main document for XCODEBK.

CONTENTS OF THIS DOCUMENT

ELEMENT OR OBJECT NAMES USED IN TEMPLATES FOR VARIABLE DESCRIPTIONS

Names Used for All Codebooks

A template for variable descriptions follows a line beginning: 
*variable(y)
or
*variable2(y) -- [for the 2nd page of an instrument document]
(where ‘y’ is the name assigned to the template, if more than one template is to be referenced in the variable list).

The template consists of one or more of the object names given below; they may be given either in upper or lower case. Each object name inserts into the variable description the appropriate content. The position of each object name in the template indicates to XCODEBK where the corresponding content should be put when constructing the variable descriptions.

Depending on the input to XCODEBK (DDL file, IDL file, or SDA dataset), some objects may be ignored. For example, if input is taken from a DDL or IDL file, instead of from an SDA dataset, objects which require the processing of the data file (such as STATISTICS) are ignored. Also, depending on the input, some elements of the actual content of some objects will be ignored if the corresponding information is not available.

The following list includes all of the object names used for basic codebooks plus all of the descriptive elements which each object inserts into a variable description.

VARNAME
Variable or item name AND long label

VAR
Variable or item name ONLY (no long label)

TEXT
Text for the item (text of the question)

CBTEXT
Extra text contained in the file (in the CBTEXT directory) having the same name as the variable being described

TEXT2
Same as CBTEXT (for backward compatibility)

CATEGORIES or CATEGORIES(ALL) or CATEGORIES(CASES)
Category codes and labels; also percentages, if requested and input is from an SDA dataset. If percentages are requested, they are placed to the left of the category codes.

The ‘ALL’ or ‘CASES’ specification (in parentheses) is optional. It can be used to control which categories with labels are displayed if the codebook input is taken from an SDA dataset. (If input is from a DDL file or an IDL file, all defined category labels are displayed.)

DATE
Date that the SDA variable was created (if input is from a an SDA dataset)

GROUP
Combines into one element the contents of PROPERTIES, SOURCE and (if an instrument document) CONTEXT. Those three tags can be used separately, but the display is more compact if they are combined into a group with this keyword.

HLINK
A hypertext link to supplementary information, if an HLINK file was specified and an HTML codebook is being generated.

KEYWORDS
Substantive keywords to use for constructing a keyword index of items

PROPERTIES
Instrument type, data type, allowable input codes, number of decimal places specified (if other than zero), missing-data codes( if any), and the minimum and maximum valid codes (if specified)

PARAMETERS
Same as PROPERTIES (for backward compatibility)

SOURCE
Either the input location in the data file or the instructions for creating the variable, if it is a recode or computed variable

SOURCEF
Same as SOURCE (for backward compatibility)

STATISTICS or STATISTICS(ndecimals)
Set of summary statistics for the variable (only available if input is from an SDA dataset). By default, 3 decimal places are shown for the mean, standard deviation, and variance. You can override this default by using the optional ’ndecimals’ specification. Specify the desired number of decimal places in parentheses after ‘STATISTICS’.

TITLE
Title of the study

Names Used Only for Instrument Documentation

The following list includes the object names and the descriptive elements used only for instrument documentation.

CONTEXT
In an instrument document, the module, section, and roster of the instrument in which this item was located, plus the immediately preceding item and the immediately following item in the instrument files

IDOCLINKS
In an HTML instrument document, this element inserts hypertext links into the item description. The links take the user to: (1) the secondary page (more detail) for the current item; (2) the next screen in the instrument; and (3) (for a non- frames IDOC) the main page of the IDOC.

LOGICFORWARD
Where the logical path of the instrument leads, AFTER this item

LOGICBACK
Which item(s) lead TO this item, following the logical path of the instrument

LOGICLABEL
A user-supplied description of the universe of the current item (how you can get here) and where you can go next.

NEXTSCREEN
In an HTML instrument document, a hypertext link to the next input screen in the instrument files

PARENTFORM
For items from a multi-item form (screen) in an instrument, the name of the parent form

PRETEMPLATE
The pre-template portion of an item

POSTTEMPLATE
The post-template portion of an item

TEXT.2 TEXT.3 ... TEXT.9
Text for the item in up to nine alternate languages

UNITS
Response unit (who answered the question) and analysis unit (to whom or what the data in this item applies)

VARLINK
In an HTML instrument document, a hypertext link to the main item description from the secondary item description

VARLINK2
In an HTML instrument document, a hypertext link to the secondary item description from the main item description

VARMOD
In an HTML instrument document, a list of items that contain a command that modifies the current item (especially useful for tracking down the content of items used as fills). Also included is a list of items that share one or more columns with the current item and consequently could modify the content of this item. Input items and non-input items are separated on both lists.

SYMBOLS USED IN VARIABLE LISTS

The (optional) list of variables contains the names of the variables or items in the order in which you want them to appear in the codebook. The following symbols can be included in the variable list to perform various functions. Each symbol should appear beginning in column 1 of a new line.

*abc
The text ‘abc’ will appear in the table of contents as a heading

**abc
The text ‘abc’ will ALSO appear at this point in the codebook, at the top of a page
(It is recommended always to use the two-asterisk version. For Word codebooks, a heading specified with a single asterisk will not produce anything.)

2*xyz
The text ‘xyz’ will appear in the table of contents as a second-level heading

2**xyz
The text ‘xyz’ will ALSO appear at this point in the codebook, at the top of a page
(It is recommended always to use the two-asterisk version. For Word codebooks, a heading specified with a single asterisk will not produce anything.)

[x
Insert the contents of the file ‘x’ (located in the CBTEXT directory) into the codebook at this point, at the top of a new page

@y
Use the template named ‘y’ for the variables which follow

@@
Use the default template for the variables which follow

#
The remainder of the line is a comment, not a list of variables

SYMBOLS USED ONLY FOR ASCII FILE OUTPUT

Symbols Used in Templates for Headers and Footers

(Used only for plain ASCII codebook files; ignored for HTML codebooks and those tagged for Word)

A template for a header or footer is a single line which follows a line beginning with one of the following:

*oheader
Header for ODD-numbered pages

*eheader
Header for EVEN-numbered pages

*header
Header for pages not otherwise specified

*ofooter
Footer for ODD-numbered pages

*efooter
Footer for EVEN-numbered pages

*footer
Footer for pages not otherwise specified

The header or footer template consists of a single line containing text and/or special symbols that have specific functions. The following symbols are replaced in the header or footer line by the appropriate information.

%d
Insert the current date (e.g., October 12, 2003)

%p
Insert the current page number

%t
Insert the title of the study

a | b | c
Left-justify ‘a’; center ‘b’; right-justify ‘c’

Symbols Used in Introductory and Appendix Files

(Used only for plain ASCII codebook files; ignored for HTML codebooks and those tagged for Word)

Within the text files used for introductory or appendix files, it is possible to include instructions about when to skip to a new page. Each of the following symbols must appear on a line by itself, beginning in the first column.

%P
Skip to a new page at this point

%EP
Skip to an EVEN-numbered page at this point

%OP
Skip to an ODD-numbered page at this point

SEE ALSO

xcodebk Basic information about XCODEBK
xcodebk-IDOC Produce an Instrument Document

CSM, UC Berkeley
April 12, 2011