SDA 3.4 Documentation for IDOC

NAME

IDOC - Instrument Documentation Procedures

DESCRIPTION

For CASES version 4.3 instruments, an instrument document (IDOC) can be created as a set of linked HTML pages, to be viewed with a Web browser such as Internet Explorer or Netscape. An IDOC can also be created as a simple ASCII file formatted for printing. The procedures for creating an IDOC for CASES instruments are summarized in this document.

There are many options available to customize the content and the appearance of an IDOC. However, there are default options which will usually produce satisfactory results, at least as a starting point. One purpose of this document is to illustrate how to run the procedures in a simple way, taking advantage of the default options.

CONTENTS OF THIS DOCUMENT

Overview
Running QEXTRACT to make an IDL File
Running XCODEBK to make an HTML IDOC
Creating a Link to the IDOC Main Page
Running XCODEBK to make an IDOC to be printed
Printing the IDOC

OVERVIEW

The creation of an IDOC includes the following steps:

Translate the CASES instrument (using CASES version 4.3)
Run the CASES ‘layout’ program, using the ‘-qx’ option. Redirect (save) the output to a file; a convenient name for that file (which will take advantage of other default options) is ‘LAYOUT’. For example:
```
layout -qx > LAYOUT
```
Run the QEXTRACT program. This program extracts item definitions and logical flow information from the CASES instrument files and from the file produced by the ‘layout’ program. It produces an IDL file (an ASCII file in the instrument documentation language) which will be used for the next step.
Run the XCODEBK program. This program reads the IDL file and creates the IDOC, either as HTML files or as an ASCII file to be printed.
If the IDOC is a set of HTML files, include a reference to the IDOC main page on some Web page accessible to the desired users of the IDOC.

Many options are available to customize the IDOC. But to do so, you must consult the documentation for the QEXTRACT and/or XCODEBK programs. In this document we will illustrate how to take advantage of the default options and run the procedures in a relatively uncomplicated way.

RUNNING QEXTRACT TO MAKE AN IDL FILE

The program QEXTRACT is run in order to extract the information from the CASES instrument and layout files and to create an IDL file. The process includes the following steps:

Change to the directory containing the instrument files, using a command like this:
```
cd \xstudy\e-inst
```
Create a file of commands (here named ‘qextract.opt’)
With any text editor that creates a plain ASCII file, create a file containing commands that specify the desired options for QEXTRACT. Any name will do for the file; in this example we will call the command file ‘qextract.opt’. An example that will cover most situations is the following:
```
#__________(Command file for QEXTRACT)___________________________

# Note that lines beginning with ‘#’ are interpreted as comments.
# Begin the commands in column 1 of your file.

title = This is the title of the study
output = myfile.idl

# If you used the ’case insensitive’ option in CASES, add this line:

nocase = yes

# If you used macros in your instruments, be sure to translate
#  the instrument with the ‘-m’ option of the CASES ‘qt’ program;
#  and add this line to the commands for QEXTRACT:

macros = yes

#__________(End of command file)_________________________________
```
The above command file will work fine, assuming that you named your layout file ‘LAYOUT’, and you are running the QEXTRACT program in the same directory as the ‘.q’ files (or the macro- expanded ‘.m’ files). (For more options and explanations, see the full QEXTRACT document.)
Run the program, to create the IDL file (here named ‘myfile.idl’):
```
qextract -b qextract.opt
```
Examine diagnostic output
Diagnostic and error messages are appended to the file ‘QEXTRACT.MSG’. Items with no path to them, if any, are listed in the file ‘QEXTRACT.ORF’. Those files should be viewed. For more information on those files, see the description of Files Produced by QEXTRACT.

RUNNING XCODEBK TO MAKE AN HTML IDOC

After you have created the IDL file, run the XCODEBK program to create the IDOC files. The process of creating an HTML IDOC includes the following steps:

Create a directory to contain the HTML files.
Since an IDOC can consist of hundreds of individual files, it is best to put each IDOC in a separate directory. In this example, we assume that it is convenient to make a subdirectory named ‘idoc’ in the ‘e-inst’ directory (or wherever the instrument files are located).
```
mkdir idoc
```

Create a file of commands (here named ‘xcodebk.opt’)

With any text editor that creates a plain ASCII file, create a file containing commands that specify the desired options for XCODEBK. Any name will do for the file; in this example we will call the command file ‘xcodebk.opt’. An example that will cover most situations is the following:


#__________(Command file for XCODEBK - HTML IDOC)_______________

# Note that lines beginning with ‘#’ are interpreted as comments.
# Begin the commands in column 1 of your file.

# Specify the name of the IDL file you created

IDL = myfile.idl

# Specify the name of the logo file, if you have a logo or some links
#  to appear at the top of the title page and the main index pages.

LOGO = logofile

# The following line informs XCODEBK to create the HTML files in
#  the directory ‘idoc’.
# The files will all have the prefix ‘sdoc’.
# The main page of the IDOC will be named ‘sdoc.htm’.

savefile = idoc\sdoc


# If you used the ’case insensitive’ option in CASES
#  and the NOCASE option for QEXTRACT, add this line:

nocase = yes

#__________(End of command file)_________________________________

The above command file will work fine, assuming that you named your IDL file ‘myfile.idl’, and your logo URL and links are in the file ‘logofile’, and you are running the XCODEBK program in the parent directory of the ‘idoc’ subdirectory, where the program will store the HTML files. (For more options and explanations, see the full XCODEBK document.)

Run the program, to create the IDOC files (here given names like ‘sdoc.htm’):
```
xcodebk -b xcodebk.opt
```

CREATING A LINK TO THE IDOC MAIN PAGE

After the IDOC has been created, it can be viewed immediately on that computer with a browser. Simply point the browser at the IDOC main page (named ‘sdoc.htm’ in the example), and that will be enough to start things off.

However, to make the IDOC viewable by users on other computers, it is necessary to put it in a network-accessible location and provide users with the Web address (the URL). There are two steps involved:

Put the IDOC files in a Web-accessible directory.
The Webmaster will have to copy or move the entire set of IDOC files to a Web-accessible location. All the files for a specific IDOC will have the same prefix (‘sdoc’ in our example). And presumably they will be located in a directory all by themselves.
For purposes of illustration, assume that the entire set of IDOC files (with the prefix ‘sdoc’) has been moved to the directory ‘D:\wwwdocs\surveyx’. Note that in such a case, the URL for the main page will be something like:
```
http://www.institute.edu/surveyx/sdoc.htm
```
Include the IDOC’s URL in some user-accessible document.
One way to make the IDOC accessible is simply to make known the URL of the main page, and to let users access that page on their own.
A more user-friendly way would be to include the URL on a Web page that users have regular access to. That way, they can see what is available and just click on the reference to the IDOC. A simple example of such a file might be:

Once users reach the "welcome mat," it is easy for them to access the available IDOCs.

RUNNING XCODEBK TO MAKE AN IDOC TO BE PRINTED

After you have created the IDL file, you can run the XCODEBK program to create an ASCII IDOC file suitable for printing. The process of creating and printing out an IDOC includes the following steps:

Create a file of commands (named ‘xcodebk.opt’)
With any text editor that creates a plain ASCII file, create a file containing commands that specify the desired options for XCODEBK. Any name will do for the file; in this example we will call the command file ‘xcodebk.opt’. An example that will cover most situations is the following:
```
#__________(Command file for XCODEBK - Printed IDOC)____________

# Note that lines beginning with ‘#’ are interpreted as comments.
# Begin the commands in column 1 of your file.

# Specify the name of the IDL file you created

IDL = myfile.idl

# Specify that the IDOC is to be formatted for 2-sided printing
#   and written to the file ‘myfile.txt’

type = print2side
savefile = myfile.txt

# If you want to include all items, instead of just the screens,
#   include the following specification:

include = all

#__________(End of command file)_________________________________
```
The above command file will work fine, assuming that you named your IDL file ‘myfile.idl’; and you are running the XCODEBK program in the same directory in which the IDL file is located. (For more options and explanations, see the full XCODEBK document.)
Run the program, to create the IDOC file:
```
xcodebk -b xcodebk.opt
```

PRINTING THE IDOC

After the printer-formatted IDOC has been created, it can be viewed immediately on that computer as a simple text file. To print the file out, use the equivalent of a simple ‘print’ command, which sends an ASCII file to the printer.

For instruments with many thousands of items, the printed IDOC can require literally thousands of pages, depending on whether the IDOC is to include all items or only the screens, and on whether a template is specified that includes more elements than the default template. Users should give careful thought to the purposes and requirements for a printed IDOC, before attempting to print one out. Upon reflection it may turn out that the HTML version of an IDOC is sufficient.

CSM, UC Berkeley
January 25, 2010