XCODEBK produces documentation based either on an SDA dataset or on a DDL file (any version).
There are three kinds of output from the XCODEBK program:
This document describes the meaning and use of the various
options. It also provides instructions for preparing the
necessary input files. Since the three output options require
somewhat different preparation, the special instructions for each
output mode are given in separate sections below.
The other files described next are optional, and the name of each such file, if used, is specified in the command file. (The keywords shown in parentheses are the corresponding commands to be inserted in the command file.)
By default the codebook program looks for an SDA dataset in the same directory in which the codebook program is being run. If the SDA dataset is located in another directory, it is necessary to specify the pathname (relative or absolute) of that directory. The pathname is given in the command file, with the 'STudy=' keyword.
More than one SDA dataset can be specified, provided that they all have the same number of cases and that the cases are in the same order in each dataset. The clearest way to specify multiple SDA datasets is by repeating the 'STudy=' keyword on multiple lines in the command file. It is also possible to list multiple datasets after one 'STudy=' keyword, by separating the dataset names with a comma or a space.
Even if you specify an explicit study pathname, the program will continue to look for an SDA study in the current directory, as it searches for the variables to include in the codebook. If a variable specified in a Variable List cannot be found in any study directory, an error message will be placed in the 'XCODEBK.MSG' file.
You can also generate a codebook using only a DDL file, instead of a complete SDA dataset. Such a codebook, of course, cannot include frequencies, percentages, or summary statistics; but the basic documentation for a dataset can be produced in this way. The pathname of the DDL file is given in the command file, with the `DDL=' keyword.
Only one of these two keywords can be used for a single codebook
procedure.
If you want to limit the codebook to a subset of variables or output them in a different order, you must prepare a file with a list of variable names, given in the order in which they should appear in the codebook. The variables can be listed with one or more names on each line, separated by spaces, tabs, or commas.
The name of each variable can be listed with temporary commands
for recoding or collapsing the variable, just as the
temporary transformations
in the analysis programs.
In general, it is better to use headings with two asterisks (**). Note that with Word codebooks, headings specified with a single asterisk will not appear at all (because the table of contents is generated by scanning the body of the codebook).
It is often useful to have one template for variables with just a few categories, and to have another template for variables with many categories. The default template is designed primarily for variables with just a few categories and does not include summary statistics like means and standard deviations.
# Start out using the default template. # For plain text codebooks, note that this will NOT force the use of the default # header, footer, and divider if they have been redefined in the template file. @@ # The following headings will appear BOTH in the table of contents # AND in the body of the codebook (2 asterisks) ** Case identification CASEID charid ** Attitudes about government spending spend,spend2, spend3 spend4 # For HTML codebooks, force a new file to begin here + ** Experiment on equal opportunity # Put the explanation of the experiment here - file `exnote' in CBTEXT [exnote eqopp eqrandom ** Political ideology and party ideo party # Use a template with statistics for the following variables @cstats ** Background variables age income educ # Return to the default template @@ employed gender marital race # Use another template for the weight variable @stats ** Weight variable casewt
The specified file is copied to the output codebook directory, maintaining the same name. A link to the (copied) file will be added to the codebook under the heading "Supplementary Documentation". If an optional (but recommended) label is supplied it will be displayed next to the file link. Otherwise, only the filename link will be displayed.
Some examples of supplementary information are the following:
doclink = /mycomputer/mywork/samplinginfo.pdf(Sampling Document)
doclink = /mycomputer/mywork/networthchart.png(Chart of Networth by Age)
Note that this supplementary file option allows for more types of files than the title, intro, and appendix file options, discussed next, which are basically limited to plain text files -- such as the files created by Notepad or vi or Word using the "Save as Plain Text (.txt)" option. And this supplementary file option is the only one supported by the SDA Manager. To use the title, intro, and appendix file options, you must run the XCODEBK program in batch mode.
(The only virtue of of the title, intro, and appendix file
options is that they are carried over to the tagged files for
Microsoft Word. However, it is usually easier to use Word
directly for adding this material rather than using these
options. Furthermore, by adding them directly to a Word file,
you can use more file types.)
If you want a special title page, prepare a plain text file to use, and specify the name of the file to the program. Codebooks will use that file's contents as the title page.
If a title file is specified for an HTML codebook, the contents
will be inserted after a '<pre>' tag, which turns off the
usual HTML processing. Then after the contents have been
inserted, a '</pre>' tag will be added, to turn HTML
processing back on.
Each introductory file should be given a heading. The heading serves two purposes: (1) the heading will be inserted in the table of contents (or the HTML index); and (2) the heading can (optionally) be centered at the top of the codebook page, before inserting the contents of the specified file; prefix the heading with `**' to insert the heading into the codebook itself.
An example of a set of study-level introductory documents is the following:
intro = general(**GENERAL DESCRIPTION OF THE STUDY)
intro = sampinfo( DESCRIPTION OF SAMPLING PROCEDURES)
intro = convent1( CONVENTIONS USED IN THE DATA FILE AND CODEBOOK)
Note that the heading for the first file (minus the two asterisks) will appear BOTH in the table of contents AND in the codebook centered at the top of the page, preceded and followed by a divider, before the contents of the file named `general' (the filename can be a full pathname and need not be in the current directory). The headings for the other two files will appear only in the table of contents; presumably the files themselves contain the same or similar headings. If the heading for a file is omitted, the word "Introduction" will appear in the table of contents (or HTML index).
If an introductory file is specified for an HTML codebook, the contents will be inserted after a '<pre>' tag, which turns off the usual HTML processing. Then after the contents have been inserted, a '</pre>' tag will be added, to turn HTML processing back on.
Each introductory file will begin on a new page and may extend
over as many pages as you wish. For plain text codebooks, if the
automatic page break comes at an inappropriate point in your
file, you can force a skip to a new page by including a line
containing only `%P' in the first two columns. If you want to
force a skip to a new ODD-NUMBERED page, use `%OP'. If you want
to force a skip to a new EVEN-NUMBERED page, use `%EP'. The
first intro file will always begin on an odd-numbered page,
unless one-sided printing has been requested. Placing `%OP' at
the beginning of a subsequent intro file will ensure that the
corresponding introductory section will also begin on an odd-
numbered page. (These page commands are ignored for HTML and for
tagged output.)
If an appendix file is specified for an HTML codebook, the contents will be inserted after a '<pre>' tag, which turns off the usual HTML processing. Then after the contents have been inserted, a '</pre>' tag will be added, to turn HTML processing back on.
For plain text codebooks, the `%P', `%OP', and `%EP' commands can be inserted in the files to force a new page, as for introductory files. The contents of each file will begin on a new page. The first appendix will always begin on an odd-numbered page, unless one-sided printing has been requested. Placing `%OP' at the beginning of a subsequent appendix file will ensure that the corresponding appendix will also begin on an odd-numbered page. (These page commands are ignored for HTML and for tagged output.)
The file names and headings are specified like introductory files as follows:
appendix = filen1(Note 1: State and Country Codes)
appendix = filen2(Note 2: Codes for Ethnic Groups)
appendix = filen3(Note 3: Codes for Religious Groups)
appendix = file1(**Appendix A: Description of Weighting Procedures)
appendix = filex(**Appendix B: Outcome of Fieldwork)
appendix = filesp(**Appendix C: Text for 'other specify' Responses)
In the above example, the six note and appendix files will be output after the descriptions of individual variables. The heading for each file will be listed in the table of contents after the list(s) of variables. In addition the headings for the last three files will be centered, preceded and followed by a divider, and inserted into the codebook before the contents of each of the three appendix files. Each note or appendix will begin on a new page.
Up to 100 of these appendix or note files may be specified. If
the heading for a file is omitted, the word "Appendix" will
appear in the table of contents (or HTML index).
To use this feature, first create a subdirectory named `CBTEXT'. If the codebook is being generated from an SDA dataset, the CBTEXT directory should ordinarily be located at the same level in the SDA study directory as the VARS and STUDYINF subdirectories. If the codebook is being generated from a DDL file, the CBTEXT directory should ordinarily be a subdirectory of the current directory, where the codebook program will be run. If you want to put the CBTEXT directory in some other location, you must use the `CBTEXT=' keyword to indicate where to find the directory containing the CBTEXT directory.
After you have created the CBTEXT directory, write each block of supplementary text into a separate plain text file in that directory. If you want the contents of a file to be included WITHIN the description of a specific variable, the name of the file should be the SAME as the name of that variable. If, on the other hand, the text is to be included in the codebook BETWEEN the descriptions of two variables, the name of the file should be DIFFERENT from any variable name.
To place each block of text into the codebook, follow one of two procedures, depending on where you want the text to go:
WITHIN variable descriptions: To insert extra text WITHIN the description of a particular variable, put the keyword `CBTEXT' into the template used by that variable. The extra text (if any) will be placed into the variable description beginning at the location indicated in the template. (See the discussion below on 'Template Construction' for more information.) Not all variables need to have a file in the CBTEXT directory. But if there is such a file, and if the `CBTEXT' keyword is included in the template, the codebook program will retrieve the contents of the file and insert the text into the codebook at that point. Note that the default and built-in templates do not include the CBTEXT keyword. To use this option, you must create your own template and run the XCODEBK program in batch mode.
BETWEEN variable descriptions: To insert extra text into the codebook BETWEEN the descriptions of two variables, put the name of the file (the file that is located in the CBTEXT directory) into the variable list in the appropriate place, preceded by a left square bracket ([). For example, the following segment of a variable list would skip to a new page and then insert the contents of the file `xtext1' into the codebook after the variable description of var2 and before the description of var3:
var1 var2
[xtext1
var3
The block of text will be preceded and followed by whatever the current `divider' is (usually a horizontal line extending the width of the page). If the filename in the varlist file immediately follows a heading indicated by two asterisks (which also forces a skip to a new page, plus the output of a divider), the text reference does not force yet another skip to a new page.
In older CSA versions of the codebook program, supplementary text
WITHIN a variable description was placed in a directory named
`TEXT2', and supplementary text BETWEEN variables was placed in a
directory named `NOTES'. For purposes of compatibility with
previous versions of the codebook program, XCODEBK will still
look for files in those directories IF no directory named
`CBTEXT' is found. One difference should be noted, however: The
older codebook program put a divider after, but not before, the
supplementary text taken from the NOTES directory. XCODEBK, on
the other hand, puts a divider both before AND after such text
when it is inserted into the body of the codebook.
myvar = mypage.html
By default, the text label for the hyperlink will be: "Link to
additional information." (Alternatively, you can globally
override this default by supplying a different label in the
commands file specification.) However, if a variable-specific
link label is desired, just add the text in parentheses after the
URL. For example:
myvar = mypage.html (myvar item in questionnaire)
The position of the hyperlink, relative to other elements in the
variable description, is determined by the location of the
"HLINK" keyword in the template used with the variable. (For
details on templates see the section on
'Template Construction'
below.) Finally, to add these links, you must specify the
location of the hlink specifications file in the command file,
using the "HLINK" keyword. (For details, see the section on
'Special Options for HTML Output'
below.)
For codebooks with input taken from an SDA study, the default limit is 40 categories (after applying any selection filters), which is the approximate number that will fit on one page. For codebooks with input taken from a DDL file, the default limit is whatever number of categories are given labels in the DDL file for a variable. The user can reset the limit to any number between 1 and 1000 categories per variable.
The default label for the system missing-data category is `(No
Data)'. You may provide your own label by putting it in the
xcodebk command file after the keyword `sysmdlabel='.
(e.g., `sysmdlabel= Does not apply').
Notice, however, that if blank fields or fields with invalid characters have been converted to some numeric value by using the `blanks=' or `other=' keyword in the DDL file when the SDA dataset was created, those cases will be reported in the codebook under the value into which the blanks or other characters were converted.
The statistics produced are the following: minimum valid value
(excluding missing-data codes), maximum valid value, mean,
median, standard deviation, and variance. The mean, standard
deviation, and variance are displayed with three decimal places
by default. The user can specify between 1 and 6 decimal places
by appending the desired number in parentheses to the
`STATISTICS' keyword in the template. For example,
`STATISTICS(4)' will generate statistics with four decimal
places.
Elements of variable descriptions are specified after a line beginning with `*variable(name)', where `name' is the user- specified name given to the template. If only one template is defined for a codebook, it is not necessary to assign a name, and the form `*variable' is sufficient. However, to use more than one template in a codebook, the templates need to be named so that the variable list can specify which variables should use each template. As described above for the variable list file, all variables in that list that follow the line `@x' will use the template named `x' until another template is specified in that list. Note that the default template is always available for use, together with any user-defined templates.
If you are using the SDA Manager to create SDA datasets and
generate codebooks, you should be aware that the SDA Manager does
not allow users to upload their own template files. However,
there are four built-in templates that users can include in a
variable list for a dataset. (See them
here.)
If those templates are insufficient, you can always run XCODEBK
in batch mode and supply your own templates.
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, all defined category labels are displayed.)
It is important to note that a variable template layout specifies several things: 1) which elements will be displayed; 2) the order of these elements; 3) the indent of each element (relative to the margin); and 4) the number of blank lines between the elements.
For tagged output and for plain text codebooks ALL of these characteristics make a difference in how the codebook is displayed. For HTML codebooks, however, the indents and blank lines in a template are ignored. For HTML codebooks it only matters WHICH elements are specified in the template and IN WHAT ORDER.
IF this template is used to generate tagged output or a plain text codebook file, note how the keywords are indented and how blank lines are placed after each keyword. In the resulting codebook the element corresponding to each keyword will be printed beginning in the same column in which the keyword in the template file begins (not counting the left margin). One or more blank lines placed after a keyword in the template file will generate the same number of blank lines after the corresponding element in the resulting codebook.
IF this template is used for HTML, the only information that counts is which keywords are mentioned and what order they are in.
*variable(simple) VARNAME TEXT CATEGORIES SOURCE
This template file also contains templates for the divider, the header, and the footer for a plain text codebook file. (These specifications will be ignored, if the template is used for HTML or for tagged output.) The divider will be an unbroken series of `='s with a blank line on either side. The header for odd- numbered pages will have the study title on the left and the page number on the right. For even-numbered pages those two fields are reversed -- the page number is on the left, and the title is on the right. The footer will have the date centered in the middle of the line. (These are the same as the default headers and footers for a plain text codebook file.)
*variable(full)
VARNAME
TEXT
CBTEXT
HLINK
CATEGORIES
PROPERTIES
DATE
TITLE
SOURCE
*divider
========================================================================
*oheader
%t | | Page %p
*eheader
Page %p | | %t
*footer
| %d
Note also that the PROPERTIES and SOURCE keywords have been replaced by the single GROUP keyword.
*variable(stats)
VARNAME
TEXT
STATISTICS
GROUP
The template named `stats' from the preceding example is also included here, to illustrate the point that more than one template definition can be included in the same template file.
*variable(cstats)
VARNAME
TEXT
CATEGORIES
STATISTICS(4)
GROUP
*variable(stats)
VARNAME
TEXT
STATISTICS
GROUP
Each type of codebook output ignores any specifications that do not apply. HTML and tagged output ignore the header, footer, and divider template information. And the `HLINK' keyword is ignored for tagged and for plain text codebooks. Since each type of codebook output simply ignores specifications that do not apply, the same template can be used for more than one type of output.
*VARIABLE
VARNAME
HLINK
TEXT
CATEGORIES
GROUP
*DIVIDER
________________________________________________________________________
*HEADER
%t | | Page %p
*EHEADER
Page %p | | %t
*FOOTER
| %d |
*variable(categ)
VARNAME
TEXT
CATEGORIES
GROUP
*variable(cstats)
VARNAME
TEXT
CATEGORIES
STATISTICS
GROUP
*variable(stats)
VARNAME
TEXT
STATISTICS
GROUP
*variable(simple)
VARNAME
TEXT
GROUP
Although the version 4 SDA Manager does not permit users to upload and apply their own templates, user templates can be created in a text editor, and the XCODEBK program can be run in batch mode. Then the codebook URL can be linked to the dataset in the 'Configure Datasets' tab of the SDA Manager.
In an HTML codebook, the sequential index, the alphabetical
index, and the group indexes contain hypertext links to the
location of each variable description in the codebook files. The
index of sequential headings, on the other hand, contains links
back to the same headings in the sequential variable index. The
sequential index and the alphabetical index are usually divided
into multiple files, with links between the succeeding files.
The variable groups file can contain an unlimited number of variable group definitions. Each definition is of the form:
Note that group definitions in a file are separated by an asterisk (*) as the first non-blank character on a line. Blanks lines and lines beginning with '#' are ignored.id = [group identifier -- used in other group definitions] type = [group type] label = [group label -- used in codebook output] vars = [list of variables in group -- "vars" can be repeated] groups = [list of variable sub-groups -- "groups" can be repeated] *
An example would be as follows:
id = demo1 type = topical label = Basic Background Variables vars = age, education, gender, marital, income * id = demo2 type = topical label = Additional Background Variables vars = employed, occup, industry * id = demographics type = topical label = Background Variables groups = demo1, demo2 *
In this example, note that the group "id" is used as a way to
include a group as a subgroup in a more general group. The
"type=" specification can be omitted. If it is used, it is
intended to be a description of the type of grouping that is
being done. (At present, nothing is done with that information.)
It is possible to have XCODEBK create files with a prefix other than `hcbk' by specifying the desired prefix with the `savefile=' keyword. This specified prefix can have up to four characters; if a longer prefix is given, only the first 4 characters will be used. Most files for the same codebook, consequently, have names that begin with `hcbk' or the user-specified prefix with two exceptions:
If you want to save the codebook files in a directory other than
the current directory, you specify the (relative or absolute)
path for that directory, plus the desired prefix, after the
`savefile=' keyword. That directory must already exist before
you run the XCODEBK program. Also, you must specify the prefix,
even if it is the same as the default `hcbk'. For example, if
you specify `savename=Codebook/hcbk', the subdirectory `Codebook'
must already exist. The codebook files will then be placed in
the subdirectory named `Codebook', and the files will have the
root name `hcbk'. The files `tree_items.js' and 'hcbksub.txt'
will also be placed in that subdirectory.
The body of the HTML codebook, containing the descriptions of variables, is divided into separate files in the following manner: The maximum file size (default = 100,000 bytes) is divided in half, to produce a minimum file size. After a codebook file has reached the minimum size, the program will start a new file when it encounters a heading in the variable list (indicated by `*' or `**' in the varlist file). If the maximum file size is reached before a heading is encountered, the next variable description will start a new file anyway.
The maximum file size can be specified at the time the codebook is generated. If the codebook files are to be accessed mostly through slow modem links, the maximum might be set as low as 20,000 bytes. On the other hand, fast ethernet connections can easily support maximum file sizes of 200,000 bytes or more. The default size of 100,000 bytes is intended as a reasonable starting point for many applications. Notice that there is no particular reason to set the maximum file size to a very large number. Having many small files is generally better than having a few large files.
The valid keywords are as follows (with significant characters shown in capital letters):
TYPE OF CODEBOOK TO CREATE
Keyword Possible Specification Default (if no keyword)
_____________________________________________________________________
TYPE= HTML [create HTML files] (Required)
SOURCE OF THE DATA
Keyword Possible Specification Default (if no keyword)
_____________________________________________________________________
(Only one of the following two keywords can be used in the same run.)
STudy= path(s) of dataset directories Look for variables only
(can be repeated) in current directory
(or in a DDL file)
DDL= name of DDL file Look for an SDA dataset
VARIABLE LIST AND TEMPLATES
Keyword Possible Specification Default (if no keyword)
_____________________________________________________________________
VARlist= filename of list of variables All variables in
alphabetical order
(for an SDA study)
or in the order found
(in a DDL file)
GROUPsfile= name of file with group names No extra variable groups
and variables in each group
TEmplate= filename containing Default template used
template(s)
OUTPUT LOCATIONS
Keyword Possible Specification Default (if no keyword)
_____________________________________________________________________
SAvefile= directory/prefix for output hcbk
(see note for HTML filenames) (in current directory)
Errorfile= filename to receive messages XCODEBK.MSG
about errors and warnings
SOURCE OF SUPPLEMENTARY, INTRODUCTORY, AND APPENDIX TEXT
Keyword Possible Specification Default (if no keyword)
_____________________________________________________________________
DOCLink= filename(heading) No supplementary
(can be repeated) documents
INTro= filename(heading) No introduction
for intro material
(can be repeated)
Appendix= filename(heading) No appendix
for appendix
(can be repeated)
CBTEXT= directory in which to find SDA study directory
the /CBTEXT subdirectory (for SDA input)
(for supplementary text) or current directory
(for DDL input)
TItle= filename of title page Default title page
FILTER AND WEIGHT VARIABLES
Keyword Possible Specification Default (if no keyword)
_____________________________________________________________________
FILTer= names and codes of filter No selection filter
variables; for example:
filter=gender(1),age(18-50)
(can be repeated)
(ignored for DDL input)
Weight= name of weight variable No weighting for
(ignored for DDL input) frequencies or stats
VARIABLE FOR A STRATIFIED CODEBOOK
(Only one of the following two keywords can be used in the same run.)
ROWVAR= name of stratifying variable No row stratifier
COLUMNVAR= name of stratifying variable No column stratifier
(If 'all' is given after the name of the stratifying variable, then
all categories of the stratifying variable are shown. Otherwise,
the categories with missing data are excluded.
For example: rowvar = year all)
PROCESSING INSTRUCTIONS
Keyword Possible Specification Default (if no keyword)
_____________________________________________________________________
LANGfile= name of file with non-English English labels on
labels and messages output
MAXCat= max number of categories SDA input: 40 rows
to display or 20 columns
DDL input:
all with labels
PCt= EXCLUDE [missing data in pcts] EXCLUDE [missing data]
INCLUDE [missing data]
BOTH [kinds of percents]
NOPCT [no percentages]
NONUM [no frequencies
or percentages]
(all ignored for DDL input)
SYSMDlabel= Label for system missing-data (No Data)
(ignored for DDL input)
(overrides the "SYSMIS_LABEL"
string in the Language File)
SPECIAL OPTIONS FOR HTML OUTPUT
Keyword Possible Specification Default (if no keyword)
_____________________________________________________________________
HLINK= filename with external links
HSIZE= maximum file size 100
(in 1000's of bytes)
HEADER= name of file for header No logo, text, or links
text or for logo put at TOP of title page
and main index pages
FOOTER= name of file for footer No logo, text, or links
text or for logo put at BOTTOM of title page
and main index pages
FRAMes= YES (Create codebook Codebook created without
using HTML frames) HTML frames
Multiple filter variables can be specified either by including more than one on the line after `filter=' or by using multiple `filter=' lines. (Filter specifications are ignored for DDL input.)
If other keywords are repeated, an error message will result.
type = html study = natlrace varlist = rvarlist savefile = race template = template.cb # Show codes as `.' that were blank in the original data file; # also label them "Blank - Does Not Apply" unless another # label is available for the relevant category. blankconvert = Blank - Does Not Apply title = titlefile doclink = /mycomputer/proposal.pdf (Proposal for the Study) doclink = /mycomputer/location.jpg (Photo of the Study Location) intro = general(General Introduction to the Study) intro = sponsors(Organization and Funding of the Study) appendix = note1(Codes for States and Countries) appendix = note2(Codes for Religious Denominations) # The following headings go at the top of each appendix # file (because of the '**'), as well as in the index. appendix = appA(**Sample Description) appendix = appB(**Description of Weighting Procedures) appendix = appC(**Outcome of Fieldwork)
type = html study = natlrace varlist = rvarlist savefile = rcodebk.txt template = template.cb weight = casewt filter = race(1-5) gender(1) title = titlefile intro = introfile appendix = appA(Sample Description) appendix = appB(Description of Weighting Procedures)
type = html study = natlrace varlist = rvarlist savefile = rcodebk.txt template = template.cb columnvar = gender title = titlefile intro = introfile appendix = appA(Sample Description) appendix = appB(Description of Weighting Procedures)
In order to allow Word to read and format the tagged codebook
file correctly, it is necessary to install a special macro on the
PC that will be reading the tagged file. There is a separate
document
that describes how to install the macro and use it.
There are two differences between one-sided and two-sided output. For two-sided output, each major section of the codebook will begin on an odd-numbered page -- the table of contents, the first introductory section, the first variable description, and the first appendix section. To ensure that this happens, blank pages will be added to the end of the preceding sections when necessary. For one-sided output, no extra blank pages are generated, and each major section can begin either on an odd- numbered or an even-numbered page.
The second difference is the header. For two-sided output, there are separate headers for odd-numbered and even-numbered pages, so that the page number will always appear on the outer part of a page, and the study title os inner part of the page. For one- sided output, there is only one header, and the page number is at the right side of the header line.
For tagged output, the user cannot instruct XCODEBK to modify the contents of the header or footer (as is possible for plain text output). However, after the tagged file has been read into Word, the headers and footers can easily be changed, by using ordinary Word formatting commands.
The valid keywords are as follows (with significant characters shown in capital letters):
TYPE OF CODEBOOK TO CREATE
Keyword Possible Specification Default (if no keyword)
_____________________________________________________________________
TYPE= TAGGED1SIDE [for MS Word, (Required)
1-sided printing]
TAGGED2SIDE [for MS Word,
2-sided printing]
SOURCE OF THE DATA
Keyword Possible Specification Default (if no keyword)
_____________________________________________________________________
(Only one of the following two keywords can be used in the same run.)
STudy= path(s) of dataset directories Look for variables only
(can be repeated) in current directory
(or in a DDL file)
DDL= name of DDL file Look for an SDA dataset
VARIABLE LIST AND TEMPLATES
Keyword Possible Specification Default (if no keyword)
_____________________________________________________________________
VARlist= filename of list of variables All variables in
alphabetical order
(for an SDA study)
or in the order found
(in a DDL file)
TEmplate= filename containing Default template used
template(s)
OUTPUT LOCATIONS
Keyword Possible Specification Default (if no keyword)
_____________________________________________________________________
SAvefile= filename to receive output CODEBOOK.TXT
(see note for HTML filenames)
Errorfile= filename to receive messages XCODEBK.MSG
about errors and warnings
SOURCE OF INTRODUCTORY AND APPENDIX TEXT
Keyword Possible Specification Default (if no keyword)
_____________________________________________________________________
INTro= filename(heading) No introduction
for intro material
(can be repeated)
Appendix= filename(heading) No appendix
for appendix
(can be repeated)
CBTEXT= directory in which to find SDA study directory
the /CBTEXT subdirectory (for SDA input)
(for supplementary text) or current directory
(for DDL input)
TItle= filename of title page Default title page
FILTER AND WEIGHT VARIABLES
Keyword Possible Specification Default (if no keyword)
_____________________________________________________________________
FILTer= names and codes of filter No selection filter
variables; for example:
filter=gender(1),age(18-50)
(can be repeated)
(ignored for DDL input)
Weight= name of weight variable No weighting for
(ignored for DDL input) frequencies or stats
PROCESSING INSTRUCTIONS
Keyword Possible Specification Default (if no keyword)
_____________________________________________________________________
LANGfile= name of file with non-English English labels on
labels and messages output
MAXCat= max number of categories SDA input: 40 rows
to display or 20 columns
DDL input:
all with labels
PCt= EXCLUDE [missing data in pcts] EXCLUDE [missing data]
INCLUDE [missing data]
BOTH [kinds of percents]
NOPCT [no percentages]
NONUM [no frequencies
or percentages]
(all ignored for DDL input)
SYSMDlabel= Label for system missing-data (No Data)
(ignored for DDL input)
Multiple filter variables can be specified either by including more than one on the line after `filter=' or by using multiple `filter=' lines. (Filter specifications are ignored for DDL input.)
If other keywords are repeated, an error message will result.
type = tagged2side study = natlrace varlist = rvarlist savefile = rcodebk.txt template = template.cb title = titlefile intro = general(General Introduction to the Study) intro = sponsors(Organization and Funding of the Study) # The following headings go in the body of the codebook # as well as in the index (because of the '**') appendix = appA(**Sample Description) appendix = appB(**Description of Weighting Procedures) appendix = appC(**Outcome of Fieldwork)
If you want to print the codebook on longer or shorter paper, or to print it sideways, or to use a font with a different number of lines per inch, you will probably need to specify another number as the maximum page length. It may be necessary to experiment a bit in order to discover the proper number of lines per page to be output for a given printer and font.
The line length is used to create headers and footers for each
page. A centered heading, for instance, is centered within the
space defined by the line length. In setting the line length,
keep in mind how long the lines are for the text of each variable
and for category labels. The program checks the length of each
printed line; if a line is longer than the defined line length, a
warning message to that effect is placed in the `XCODEBK.MSG'
file, but the program will continue processing the codebook.
There are two differences between one-sided and two-sided output. For two-sided output, each major section of the codebook will begin on an odd-numbered page -- the table of contents, the first introductory section, the first variable description, and the first appendix section. To ensure that this happens, blank pages will be added to the end of the preceding sections when necessary. For one-sided output, no extra blank pages are generated, and each major section can begin either on an odd- numbered or an even-numbered page.
The second difference is the header. For one-sided output, there is only one page header, and the page number is put on the right side of the page. For two-sided output, there are separate headers for odd-numbered and even-numbered pages, so that the page number will always appear on the outer part of the page, and the study title on the inner part of the page.
Since the templates of the header, footer, and divider remain constant throughout the entire codebook, only one of each of those templates can be specified. Note that it is possible to use the default template for variable descriptions and only include templates for the header and/or footer and/or divider in the template file. By the same token, it is possible to use the default templates for header, footer, and divider and only include one or more templates for variable descriptions in the template file.
Examples of the use of header, footer, and divider templates are given above in the section 'Template Examples'.
In order to replace the standard header, put the line you want to appear at the top of each page into the template file after a line beginning with `*header'. Similarly, put your footer line in the template file after a line beginning with `*footer'. In creating your own header and footer you can use the following codes, which the codebook program will replace with the appropriate content:
%d current date (month, day, and year)
%p page number
%t title of the study
To center or right-justify a field within a header or footer line, separate the parts of the line with the "pipe" character (|). For example, the following header would put the date on the left, center the study title, and put the page number over at the right margin:
*header
%d | %t | Page %p
If nothing is to be centered, leave that segment blank. Since a codebook will usually be printed or copied onto both sides of a page, it is often desirable to have one header (or footer) for odd-numbered pages and another for even-numbered pages. (For two-sided printer format, there are separate default headers for odd-numbered pages and even-numbered pages.) Note the following keywords:
*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 is given on a separate line after
one of the above keywords. See the template example for the
default template.
The default divider is a solid underscore that begins after the left indent and continues for 70 columns (or whatever the maximum line length is set to); it is followed by a blank line. If you want a different divider between variables, put the line(s) you want to serve as the divider into the template file after a line beginning with `*divider'. A maximum of five lines can be specified. Blank lines are significant here -- a blank line appearing in the divider template will generate blank lines in the codebook. See example 2 below.
In general, keywords may be given in any order, except that a varlist specification is assumed to refer only to the preceding specification of the SDA study or DDL file. (See the section below on `Study/DDL and Varlist Repetition' for a discussion of this issue.)
The valid keywords are as follows (with significant characters shown in capital letters):
TYPE OF CODEBOOK TO CREATE
Keyword Possible Specification Default (if no keyword)
_____________________________________________________________________
TYPE= PRINT1SIDE [Plain text for print2side
1-sided printing]
PRINT2SIDE [Plain text for
2-sided printing]
SOURCE OF THE DATA
Keyword Possible Specification Default (if no keyword)
_____________________________________________________________________
(Only one of the following two keywords can be used in the same run.)
STudy= path(s) of dataset directories Look for variables only
(can be repeated) in current directory
(or in a DDL file)
DDL= name of DDL file Look for an SDA dataset
VARIABLE LIST AND TEMPLATES
Keyword Possible Specification Default (if no keyword)
_____________________________________________________________________
VARlist= filename of list of variables All variables in
alphabetical order
(for an SDA study)
or in the order found
(in a DDL file)
TEmplate= filename containing Default template used
template(s)
OUTPUT LOCATIONS
Keyword Possible Specification Default (if no keyword)
_____________________________________________________________________
SAvefile= filename to receive output `CODEBOOK.TXT' if
(see note for HTML filenames) printer format;
`hcbk' if HTML
Errorfile= filename to receive messages XCODEBK.MSG
about errors and warnings
SOURCE OF INTRODUCTORY AND APPENDIX TEXT
Keyword Possible Specification Default (if no keyword)
_____________________________________________________________________
INTro= filename(heading) No introduction
for intro material
(can be repeated)
Appendix= filename(heading) No appendix
for appendix
(can be repeated)
CBTEXT= directory in which to find SDA study directory
the /CBTEXT subdirectory (for SDA input)
(for supplementary text) or current directory
(for DDL input)
TItle= filename of title page Default title page
FILTER AND WEIGHT VARIABLES
Keyword Possible Specification Default (if no keyword)
_____________________________________________________________________
FILTer= names and codes of filter No selection filter
variables; for example:
filter=gender(1),age(18-50)
(can be repeated)
(ignored for DDL input)
Weight= name of weight variable No weighting for
(ignored for DDL input) frequencies or stats
PROCESSING INSTRUCTIONS
Keyword Possible Specification Default (if no keyword)
_____________________________________________________________________
LANGfile= name of file with non-English English labels on
labels and messages output
MAXCat= max number of categories SDA input: 40 rows
to display or 20 columns
DDL input:
all with labels
PCt= EXCLUDE [missing data in pcts] EXCLUDE [missing data]
INCLUDE [missing data]
BOTH [kinds of percents]
NOPCT [no percentages]
NONUM [no frequencies
or percentages]
(all ignored for DDL input)
SYSMDlabel= Label for system missing-data (No Data)
(ignored for DDL input)
FORMATTING FOR PLAIN TEXT FILE
Keyword Possible Specification Default (if no keyword)
_____________________________________________________________________
LINelength= number of characters in a line 72
(not counting left margin)
MARgin= number of spaces for 6
left margin
PAgelength= maximum page length (lines) 60
For codebooks in plain text format, up to five datasets (or DDL files) can be specified for inclusion in a single codebook. However, if weight or filter variables are used for the codebook, all of the datasets must have the same number of cases. (Weight and filter specifications are ignored if DDL files are specified instead of SDA study datasets.)
If multiple input datasets (or DDL files) are specified, the `study=' (or `ddl=' or `idl=') and `varlist=' keywords may each be repeated. The order in which they appear is important: the specification of the varlist for a dataset (or DDL file) must FOLLOW the specification of that dataset (or DDL file) and precede the specification of any other dataset (or DDL file).
For example, in the following command file the varlist for the "faculty" study or dataset will be "flist" and the varlist for the "students" dataset will be "slist": The name for each dataset is the pathname of the dataset directory, and the name for each list is the pathname of the file containing the list of variables. In the form given in this example, both studies would have to be subdirectories of the current directory, and both lists would have to be located in the current directory.
study = faculty varlist = flist study = students varlist = slist
If an SDA study is specified without a matching varlist, all variables in the study will be included in the codebook, in alphabetical order. If a DDL file is specified without a matching varlist, all variables in the DDL file will be included in the codebook, in the order in which they are found in the DDL file.
If a varlist is specified without a preceding `study=' or `ddl='
or `idl=' specification, the list is assumed to apply to an SDA
dataset located in the user's current directory.
Repetition of `study=', `ddl=', `idl=' and `varlist=' keywords are also allowed, as described above; however, `study=', `ddl=', and `idl=' specifications cannot be mixed for the same codebook.
Multiple filter variables can be specified either by including more than one on the line after `filter=' or by using multiple `filter=' lines. (Filter specifications are ignored for DDL input.)
If other keywords are repeated, an error message will result.
type = print1side study = natlrace varlist = rvarlist savefile = rcodebk.txt template = template.cb margin = 8 title = titlefile intro = introfile # Both appendix headings will go into the table of contents # The second heading will also go into the body of the codebook # as a heading for that appendix. appendix = appA(Sample Description) appendix = appB(**Description of Weighting Procedures)
type = print1side DDL = nrace.ddl varlist = rvarlist savefile = rcodebk.txt # Note that any template references to `statistics' or # `date' (date of creation of SDA variable) will be ignored. template = template.cb margin = 8 margin = 8 title = titlefile intro = introfile appendix = appA(Sample Description) appendix = appB(**Description of Weighting Procedures)
| Word macro | Installing Word macro for codebooks |
| xcodebk formatting | Summary of formatting instructions |
| xcodebk keywords | Summary of keywords for command files |
| internationalization | Modifying the SDA user interface language files |