4. CA MICS Facilities › 4.6 Documentation Programs

4.6 Documentation Programs

This section describes the system used for production of a
printed copy of a CA MICS document. Parts of the same system
are also used by the online Document Access facility.  Both
applications must be considered if any changes are being made
to the system.

A CA MICS document is built from a set of members found in
one or more of the CA MICS TEXT libraries. These TEXT
libraries contain the text, figure, and title members that
are used to compose the CA MICS guides. The libraries contain
variable length records, with a maximum text width of 133
characters (LRECL=137,RECFM=VB).  The CA MICS TEXT libraries
are:

    - sharedprefix.MICS.DOC.TEXT, which contains document
      text sections, figures, picklists, and title pages.

    - sharedprefix.MICS.INC.TEXT, which contains generated
      text and other members copied by several documents.

    - sharedprefix.MICS.DIC.TEXT, which contains the Data
      Dictionary data element descriptions.

Text that is printed in two column fashion must not
exceed a width of 61 characters.  This text is referred to as
"short text." Figures, titles, and other text using the
entire page width as a single column may be as wide as will
fit on the printed page (usually 130 characters).  This text
is referred to as "long text."

Data Dictionary elements reside in a separate library so
that they can follow their own separate naming convention,as
determined by other CA MICS conventions. These members are
always developed as short text.

PICKLISTS

The files that control the assembly of text members into
documents are called picklists.

The structure for a guide relies on a book-level picklist
that calls individual chapter picklists.  The chapter
picklists identify the individual files that constitute the
chapter.  This structure allows you to print an entire guide
or just one chapter.

The picklist is also the basis of the display used by
online Document Browse.  The titles displayed by Document
Browse are extracted directly from the picklist title
entries.  The order of title presentation is also determined
by the picklist.

The set of guides presented to the Document Access user
is determined by an ISPF table member, DOCLSTP4, that lists
the available guide titles and document identifiers in a
standard order.  These entries identify the book level
picklists.  All picklists should reside in the DOC.TEXT
library by convention.  DOCLSTP4 is constructed from a
special picklist named PICVOL.
DOCUMENT PRODUCTION PROCESS FLOW

Producing a printed copy of a document is a two-step process.
The first step selects the members from the TEXT libraries
and produces a single text file containing a rough form of
the document.  The second step formats the rough copy, adds
tables of contents if requested, and produces the final copy
with either one or two columns of text to a page.

The entire process is controlled by command records
identified by a "$" in column one of the record.  These
records, called "dollar commands" in this description, are
used in both steps of the process.  In the first step, dollar
commands are read from a picklist.  The picklist is a
DOC.TEXT library member which usually consists entirely of
dollar commands.  It lists the text members that make up the
document in the order in which they are to appear.  The first
step program (DOCPICK) reads the list and copies each member
named to the rough text file.

Dollar commands are also used to control the formatting
process in the second step.  These records may be contained
in either the picklist or in the section and figure text
members.  These formatting dollar commands are detected by
DOCPICK, but passed to the second step through the rough
intermediate file.  The formatting controls are used by the
second step program, sharedprefix.MICS.SOURCE(DOCUMENT).
DOCUMENT produces the final document with two columns of text
to a page.