SDA 3.5 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

The creation of an IDOC includes the following steps:

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:

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:

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:

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:

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
April 12, 2011