The XCODEBK program has many options, which allow you to customize the output. However, the default options will usually produce satisfactory results, and the program can be run very simply if you run it in that mode. See the Examples of Command Files at the end of this document, to see how to run the program in a very uncomplicated manner. Simplified instructions are also provided in the summary document on Instrument Documentation Procedures.
Output can be either a set of HTML files ready to be viewed with a Web browser (such as Netscape or Internet Explorer) or an ASCII file formatted for printing.
To run the program, a file of commands must be prepared; the name of this file is given on the command line after the ’-b’ flag. This document describes the options applicable to creating an IDOC and how to specify those options.
Every time XCODEBK is run, a message is appended to the file named ‘XCODEBK.MSG’. If warnings or error messages are generated by the program, they are put in that file, and a message to that effect appears on the user’s screen.
If you want a special title page, prepare one in an ASCII file just as you want it to look, and specify the name of the file to the program. An IDOC created for HTML will make that file a specific page to be referenced. An IDOC created for printing will use that file as the title page.
Each introductory file will begin on a new page and may extend over as many pages as you wish. For codebooks formatted for the printer, 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 introductory 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 codebooks.)
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 main page); 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 IDOC 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)
In this example, the name of the first intro file is ‘general’ (the specified filename could be a full pathname and need not be in the current directory). Note that the heading for this 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 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 main page).
The file names and headings are specified in the same manner as 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 (or HTML main page) 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 main page).
For printed IDOCS, you can also customize the layouts for the
page header and footer and for the divider between item
descriptions. For details see the section on
Templates for Printed Headers, Footers, and
Dividers
below.
As a practical matter, it is a good idea to place the files for a single HTML IDOC in a separate directory, to avoid possible name conflicts. In particular, creating more than one HTML IDOC using the default root name will almost certainly cause problems unless separate directories are used.
The body of the HTML IDOC, containing the descriptions of the items, is divided into separate files in the following manner: Before an item description is written, the program checks the size of the current HTML file. If it exceeds the maximum file size (default = 50,000 bytes), a new file is created.
The maximum file size can be specified as an option. If the IDOC
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 100,000 bytes or more. The default size of 50,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 large number. Having many small files is generally
better than having a few large files. Note also that this
maximum file size is also used for breaking up the index files.
A description of an item comprises several elements. Every substantive element in the IDL file is part of a package of elements that is available for inclusion in the IDOC. Each package of elements can be arranged on the main item page or on the secondary item page in any desired order. The template is just a list of the desired packages of elements, one per line, in the order in which you want them to appear.
Elements for the primary item description are specified after a line beginning with ‘*variable’. Elements for the secondary item description (which is optional) are specified after a line beginning with ‘*variable2’. In a template file each package of elements to be included on one of the HTML pages for an item is referred to by one of the following tags (which may be given either in upper or lower case but may not be abbreviated). Not all tags need to be used; if a tag is omitted, the corresponding elements will not appear in the codebook.
CATEGORIES will not print any bracketed text in category labels
[the short labels].
CATEGORIESF, on the other hand, prints the full category text,
including bracketed material.
This example shows a few of the basic element tags. In this example, all the information on an item is on a single page -- instead of the two-page division used by the default template.
In HTML templates, only the order of the element tags is significant. The XCODEBK program handles the spacing and division between the elements automatically.
*variable VARNAME PARENTFORM TEXT PRETEMPLATE POSTTEMPLATE GROUP
This template shows a few basic element tags divided between a primary page for an item and a secondary page for the item. The elements to appear on the primary page for an item are specified after ‘*variable’. The elements to appear on the secondary or "see more detail" page are specified after ‘*variable2’.
Notice that you MUST include the elements which provide the links between the two pages. The element ‘IDOCLINKS’ provides the link from the primary page to the secondary page; without this link, the user could not reach the secondary page. The element ‘VARLINK’ provides the link from the secondary page back to the primary page; without this link, the user could only return to the primary page by using the ‘BACK’ button on the browser.
*variable VARNAME IDOCLINKS TEXT *variable2 VARNAME VARLINK GROUP
The default HTML template for an IDOC contains all of the possible packages of elements, except for the text for alternate languages. The elements to appear on the primary page for an item are specified after ‘*variable’. The elements to appear on the secondary or "see more detail" page are specified after ‘*variable2’. Note that on the secondary page a link back to the primary page has been placed both at the top and the bottom of the page.
*variable VARNAME IDOCLINKS PARENTFORM HLINK TEXT CATEGORIES LOGICLABEL LOGICBACK LOGICFORWARD UNITS VARMOD *variable2 VARNAME VARLINK PRETEMPLATE POSTTEMPLATE GROUP KEYWORDS VARLINK
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.
A description of an item comprises several elements. Every substantive element in the IDL file is part of a package of elements that is available for inclusion in the IDOC. Each package of elements can be arranged on the main item page or on the secondary item page in any desired order. The template is just a list of the desired packages of elements, one per line, in the order in which you want them to appear.
For templates for printed IDOCs, the INDENT to the left of an element tag is significant. The number of spaces to the left of the tag will be preserved on the printed page. Also, the number of blank lines BETWEEN element tags is significant. Additional blank lines in the template will be preserved on the printed page.
Elements of variable descriptions are specified after a line beginning with ‘*variable’. In a template file each package of elements to be included in the codebook is referred to by one of the following tags (which may be given either in upper or lower case but may not be abbreviated). Not all tags need to be used; if a tag is omitted, the corresponding elements will not appear in the codebook.
CATEGORIES will not print any bracketed text in category labels
[the short labels].
CATEGORIESF, on the other hand, prints the full category text,
including bracketed material.
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 a template for item descriptions in the template file.
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 XCODEBK 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. For an example, see the
default template
below.
The default divider is a solid underscore that begins after the left indent and continues for 72 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. For an example, see the default template below.
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 default header. For two-sided
output, there are separate default headers for odd-numbered and
even-numbered pages, so that the page number will always appear
on the outer part of a page. For one-sided output, there is only
one default header, and the page number is at the right side of
the header line.
The default template is shown here. It includes only a few of the possible element packages for an IDOC. Also included are the default templates for the page header and footer and for the divider between items. Note that the length of the default divider depends on the specified line length (default is 72).
Note how the tags are indented and how blank lines are placed after each tag. In the resulting codebook the package of elements corresponding to each tag will be printed beginning in the same column in which the tag in the template file begins (not counting the left margin). One or more blank lines placed after a tag in the template file will generate the same number of blank lines after the corresponding element in the resulting codebook.
*variable
VARNAME
TEXT
CATEGORIES
PROPERTIES
LOGICFORWARD
*divider
________________________________________________________________________
*header
%t | | Page %p
*eheader
Page %p | | %t
*footer
| %d |
This template includes all of the possible element packages for a printed IDOC, except for alternate language text. A printed IDOC with all of these elements could be quite lengthy, depending on whether or not the IDOC includes all items or only the screens.
*variable
VARNAME
TEXT
CATEGORIES
NEXTSCREEN
PARENTFORM
LOGICLABEL
LOGICBACK
LOGICFORWARD
UNITS
VARMOD
CONTEXT
PROPERTIES
KEYWORDS
SOURCE
PRETEMPLATE
POSTTEMPLATE
Keyword Possible Specification Default (if no keyword)
-----------------------------------------------------------------------
IDL= name of IDL file REQUIRED for an IDOC
(sets program to IDOC mode)
TYPE= HTML [create HTML files, HTML
using HTML tables for all
the elements]
PRINT1SIDE [format for
1-sided printing]
PRINT2SIDE [format for
2-sided printing]
SAvefile= filename to receive output ‘CODEBOOK.TXT’ if
(see note for HTML filenames) printer format;
‘hcbk’ if HTML
TItle= filename of title page Default title page
INTro= filename(heading) No introduction
for intro material
(can be repeated)
Appendix= filename(heading) No appendix
for appendix
(can be repeated)
INClude= all or screens All items for HTML; only
(items to include in IDOC) the screens for printer
TEmplate= filename containing Default template used
template(s)
LOGO= filename of logo file No logo or link put at
top of title page and
main index pages
NOCASE= YES (Ignore case in matching Distinguish upper and
item names for hypertext lower case item names
references in an HTML IDOC)
HDRCOLOR= color code (hexadecimal number) 93BED5 (Light blue)
for background of headings
in the HTML tables for the
element packages.
(For white, specify: FFFFFF)
HSIZE= maximum file size 50
(in 1000’s of bytes)
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
If other keywords are repeated, an error message will result.
IDL = sipp.idl savefile = sipp nocase = yes
idl = sipp.idl savefile = sipp logo = logofile title = mytfile # The specified headings for the intro files are used only # for the index; they are not inserted into the intro files intro = general(General Introduction to the Study) intro = sponsors(Organization and Funding of the Study) # The specified headings for the appendix files are used for # the index; they are also inserted at the top of the # appendix files (because they are preceded by ’**’) appendix = appA(**Sample Description) appendix = appB(**Description of Weighting Procedures) appendix = note1(**Codes for States and Countries) appendix = note2(**Codes for Occupational Categories)
IDL = sipp.idl type = print2side savefile = sipp.txt
IDL = fishing.idl type = print1side savefile = fishing.txt template = mytemp margin = 8 linelength = 78 pagelength = 62 title = tfile intro = intfile appendix = appA(**Sample Description) appendix = appB(**Description of Weighting Procedures)