SDA 3.5 Documentation for XCODEBK-IDOC


NAME

xcodebki - Produce an Instrument Document for HTML or printer

USAGE

xcodebk -b command_file_name

DESCRIPTION

XCODEBK produces expanded codebooks that document instruments used in computer-assisted interviewing (CAI), provided that they have been parsed and structured into IDL -- the Instrument Documentation Language. Optional specifications are placed in a batch command file, the name of which is supplied to the program after the ‘-b’ flag.

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.

CONTENTS OF THIS DOCUMENT

OVERVIEW

XCODEBK reads an IDL file, which contains information on the content and logic of a CAI instrument. This IDL file is usually produced by the QEXTRACT program, which reads CASES instrument files. However, any type of CAI instrument can be documented, provided that the information has been parsed and stored as an IDL file.

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.

FILES TO PREPARE

The program will use the contents of certain files that you can prepare and specify.

IDL File (IDL= filename)

To document a CAI instrument, an IDL file must be prepared. This file contains information on the content and logic of the CAI instrument to be documented.

Logo File (LOGO= filename)

The contents of the specified file will be placed at the top of the title page and of the main pages of each index. The purpose of this option is to allow the user to put a logo or a hypertext link at the top of the principal pages of the documentation.

Title Page File (Title= filename)

Instrument Documents have a title page at the beginning. The default title page contains the study title plus the date the IDOC was created.

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.

Introductory Material (intro= filename)

An introduction or various types of study-level information can be inserted into the IDOC before the descriptions of the items. This material should be placed in one or more ASCII files, formatted just as you want it to appear. The names of these files are then specified to the codebook program as "intro" files. Up to 100 of these introductory files may be specified.

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).

Appendices and Notes to the Codebook (appendix= filename)

Appendices, notes, or other additional material can be added to the codebook, after the descriptions of the items, by specifying certain ASCII files as appendix files. The contents of such files should be formatted just as you want them to appear. 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 output.)

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).

Template File (template= filename)

There is a default layout for the description of each item. You can create your own IDOC layout by creating a template in a file. For details see the sections on Templates for HTML IDOC Items or Templates for PRINTED IDOC Items below.

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.

CREATING AN HTML IDOC

If you are going to use mostly the default options, a simplified procedure is contained in the section on Running XCODEBK to Make an HTML IDOC in the summary document on Instrument Documentation Procedures.

OPTIONS FOR HTML IDOCS

Names of HTML Codebook Files (savefile= name)

The main codebook page is named ‘x.htm’ where ‘x’ is the user- supplied root name for the IDOC files (the default is ‘idoc’). This root name can have up to four characters. The XCODEBK program numbers the files for item descriptions from ‘x0001.htm’ to ‘x9999.htm’, where ‘x’ is again the user-supplied root name. The introductory files, appendix files, and indexes also use the same root name, followed by various suffixes. All files for the same IDOC, consequently, have names that begin with the root name.

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.

NOCASE Mode (nocase= yes)

If the instrument was translated with the ‘case insensitive’ option in CASES, there is no distinction between upper and lower case item names. For example, a command to ‘goto itemx’ means the same as ‘goto ITEMX’. The XCODEBK program needs to know whether or not the instrument was designed to operate in case- insensitive mode, in order to create the appropriate hypertext links from one item to another.

Color for Headers (hdrcolor= hex)

The headings for the HTML tables of elements have a colored background, to make them more visible. The default color (currently light blue) can be changed by giving the hexadecimal color code after the ‘hdrcolor=’ command. If you do not want a colored background, you can set the background to white by specifying ‘hdrcolor= FFFFFF’.

Size of HTML files (hsize= n)

HTML codebooks are divided into many small files, to facilitate rapid transfer to the browser of just the portion requested by the user. Each introductory file, appendix file, and index is stored as a separate file, referenced from the main codebook page.

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.

TEMPLATES FOR HTML IDOC ITEMS

XCODEBK has a default layout for the elements that describe an item. There is one template for the main HTML page for each item, and there is another template for the secondary page for each item. In order to customize this layout, prepare a file (the name of which is given after the ‘template=’ keyword) containing one or both templates. A template shows the codebook program where on the page to place the various (packages of) elements of an item description. See the Examples of HTML Templates below, to see what a template looks like.

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.

HTML Element Tags and Their Content

If the type of output is the default HTML, these tags produce HTML tables, which contain the appropriate content.

VARNAME
This tag refers to the name of the item and its long label, if any. If there are both a primary and a secondary page for each item, this tag should appear in the template for both pages.

TEXT
The text element is usually the text of a question for an item in an instrument. However, this text element may consist of any text found in an instrument for an item. Whatever is in the IDL file after ‘text=’ will be used. If a variable was not created with a text element, the corresponding space in the codebook is left blank.

TEXT.2
Alternate language text is accessed by this tag. There may be up to eight alternate language versions, each accessed by TEXT.2, TEXT.3, and so forth.

CATEGORIES or CATEGORIESF
A set of lines with category codes and labels. Note that this tag will only retrieve categories for which a category label was defined in the instrument. For many instruments, this tag is unnecessary, and all of the available information on categories is contained in the TEXT and the POSTTEMPLATE elements.

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.

CONTEXT
Information about the item’s location within the instrument. Includes the name of the instrument file, the name and level of the roster (if any), and the section name.

GROUP
This tag is a special case. It combines into one HTML table the contents of CONTEXT, PROPERTIES, and SOURCE. Those three tags can be used separately, but the content looks a little better if they are combined into a single table.

KEYWORDS
The user-supplied keywords for the item.

LOGICBACK
The names of the items which lead directly to the current item. If there was only one direct path to the current item, also given is the name of the closest preceding item which had multiple paths to it.

LOGICFORWARD
The names of the items to which the current item can directly lead.

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

PARENTFORM
The name of the form or screen, if the current item is part of a multi-item form.

POSTTEMPLATE
The commands and definitions executed after the text for the current item has been displayed on the screen.

PRETEMPLATE
The commands and definitions executed before the text for the current item is displayed on the screen. If the item consists only of commands and definitions, does not display any text, and is not part of a multi-item form, those commands are accessed by this element tag.

PROPERTIES
The data type (numeric or character) of the current item, missing-data specifications, and number of decimal places, if any.

SOURCE
The location of the current item in the CASES internal data files. Includes the roster number, record number, and column location.

UNITS
User-supplied information about the analysis unit (who or what the current item applies to) and the response unit (who is answering the current item).

VARMOD
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.

IDOCLINKS
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.

VARLINK
This element is used on the secondary page of an item, to provide a link back to the primary page.

EXAMPLES OF HTML TEMPLATES

H-1. Minimal HTML Template - one page only

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


H-2. Simple 2-page HTML template

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


H-3. Default HTML Template

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


CREATING A PRINTED IDOC

If you are going to use mostly the default options, a simplified procedure is contained in the section on Running XCODEBK to Make an IDOC to be Printed in the summary document on Instrument Documentation Procedures.

PAGE DIMENSION OPTIONS FOR PRINTED IDOCS

Left Margin or Indent (margin= n)

The default is 6 spaces. If you plan to bind the codebook, you may want to increase the left margin.

Page Length (in lines) (pagelength= n)

The default is 60 lines, which corresponds to paper 11 inches long, with 6 lines printed per inch, allowing 3 extra lines at the top and the bottom of the page. Some printers add these extra blank lines by themselves; if your printer does not add blank lines, you could increase the page length to 66 lines.

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.

Line Length (excluding the left margin) (linelength= n)

The default is 72 characters. The valid range is 60-132 characters.

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.

TEMPLATES FOR PRINTED IDOC ITEMS

XCODEBK has a default layout for the elements that describe an item. Unlike HTML IDOCs, printed IDOCs have only one page for each item description. (There may even be more than one item description on a printed page, depending on the number of requested elements.) In order to customize this layout, create a file (the name of which is given after the ‘template=’ command) containing the template. A template shows the XCODEBK program where on the page to place the various (packages of) elements of an item description. See the Examples of Printer Templates below, to see what a template looks like.

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.

ASCII Element Tags and Their Content

VARNAME
This tag refers to the name of the item and its long label, if any.

TEXT
The text element is usually the text of a question for an item in an instrument. However, this text element may consist of any text found in an instrument for an item. Whatever is in the IDL file after ‘text=’ will be used. If a variable was not created with a text element, the corresponding space in the codebook is left blank.

TEXT.2
Alternate language text is accessed by this tag. There may be up to eight alternate language versions, each accessed by TEXT.2, TEXT.3, and so forth.

CATEGORIES or CATEGORIESF
A set of lines with category codes and labels. Note that this tag will only retrieve categories for which a category label was defined in the instrument. For many instruments, this tag is unnecessary, and all of the available information on categories is contained in the TEXT and the POSTTEMPLATE elements.

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.

CONTEXT
Information about the item’s location within the instrument. Includes the name of the instrument file, the name and level of the roster (if any), and the section name.

GROUP
This tag is a special case. It combines into one HTML table the contents of CONTEXT, PROPERTIES, and SOURCE. Those three tags can be used separately, but the content looks a little better if they are combined into a single table.

KEYWORDS
The user-supplied keywords for the item.

LOGICBACK
The names of the items which lead directly to the current item. If there was only one direct path to the current item, also given is the name of the closest preceding item which had multiple paths to it.

LOGICFORWARD
The names of the items to which the current item can directly lead.

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

NEXTSCREEN
The name of the next item in the instrument which is a screen that displays text.

PARENTFORM
The name of the form or screen, if the current item is part of a multi-item form.

POSTTEMPLATE
The commands and definitions executed after the text for the current item has been displayed on the screen.

PRETEMPLATE
The commands and definitions executed before the text for the current item is displayed on the screen. If the item consists only of commands and definitions, does not display any text, and is not part of a multi-item form, those commands are accessed by this element tag.

PROPERTIES
The data type (numeric or character) of the current item, missing-data specifications, and number of decimal places, if any.

SOURCE
The location of the current item in the CASES internal data files. Includes the roster number, record number, and column location.

UNITS
User-supplied information about the analysis unit (who or what the current item applies to) and the response unit (who is answering the current item).

VARMOD
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.

TEMPLATES FOR HEADER, FOOTER, AND DIVIDER (printed IDOCs only)

The codebook program prints a header line at the top of each page, a footer line at the bottom, and a divider string in between variable descriptions on the same page. If you want to modify the default header, footer, or divider, put the revised definitions in the template file before or after the template for item descriptions.

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.

Header and Footer

The default or standard header for odd-numbered pages has the study title beginning at the left margin and the page number right-justified over to the right margin. The default header for even-numbered pages has these two fields reversed -- that is, the page number is on the left and the study title is on the right. If one-sided printing has been selected, the header is the same for all pages and is the same as the header for odd-numbered pages. The default footer for both kinds of printer output has the date that the IDOC was created centered in the line.

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.

Divider

The program prints a divider between variable descriptions, if there is more than one on a page. The divider is also used before and after headings placed into the codebook because they were preceded by two asterisks (**) in the specification of headings for introduction and appendix files.

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.

Printer Formatting for One- or Two-Sided Printing

Since codebooks tend to be quite large, they will generally be printed or copied onto both sides of a page. The default codebook output type therefore assumes two-sided printing. However, the user can specify that one-sided printing is desired.

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.

EXAMPLES OF PRINTER TEMPLATES

P-1. The Default Template for a Printed IDOC

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 |

P-2. Template for a Printed IDOC with All Elements

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


KEYWORDS FOR COMMAND FILES

The command file contains the optional specifications for the run. These specifications are given in the form "keyword = something." Keywords may be given in any order, in upper or lower case, with one keyword per line. The valid keywords are as follows, with significant characters shown in capital letters:

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)

HTML FORMAT ONLY (ignored if printer format):


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)

PRINTER FORMAT ONLY (ignored if HTML format):


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

Abbreviations

Keywords can usually be abbreviated down to a few characters. The keyword for the output file, for instance, can be given as "savefile=" or "save=" or "sa=". Either upper or lower case may be used.

Comments

Anything on a line beginning with ‘#’ is ignored by the command processor and can therefore be used for comments. Blank lines are also ignored.

Repetition of Keywords

The ‘intro=’ and ‘appendix=’ keywords can be repeated, up to a total of 100 times each; multiple study-level introductory and appendix sections are included in this way.

If other keywords are repeated, an error message will result.

EXAMPLES OF COMMAND FILES

H-1. Create an HTML IDOC, using most defaults


IDL = sipp.idl
savefile = sipp
nocase = yes

H-2. HTML IDOC with multiple intro and appendix files


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)


P-1. IDOC to be Printed, using most defaults


IDL = sipp.idl

type = print2side
savefile = sipp.txt

P-2. IDOC for printing, using some options.


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)


CSM, UC Berkeley
April 12, 2011