Skip to Content

Documentation Standards & Preparation

Documentation Standards

The FRS Documentation System has been designed and developed to operate in a manner similar to the VM/CMS Help Facility. To facilitate this method of operation, source documents have been created to comply with standards developed by the UITS Information Systems Support Group (ISS). Following these common standards for document creation will permit the transfer of any FRS documentation files to the ISS documentation machine DOCADM01 without having to make radical changes. Furthermore, this process also allows one source file to be used in several different ways.

These instructions provide some very basic guidelines to follow in document preparation. More specific information on setting up the source file can be found in the document ISS General Documentation Standards which is available from the UITS Information Systems Support Group.

Source Document Formats

Each of the documentation categories available within this system follows a specific document format. To facilitate and standardize the preparation ofsource documents, template files have been created to guide the individual who is creating the source document file. The documentation categories and respective source document template template files are as follows:

Creating The Document Source File

All documentation should be produced using the mainframe based IBM Document Composition Facility (DCF) system. Document formatting is achieved by using the SCRIPT/VS text processing program together with the Generalized Markup Language (GML).

To create a source document, the individual can start from scratch with the appropriate source template file or copy and modify an existing source document if that is more convenient. Regardless of the manner in which the source document is begun, it is highly recommended that the individual creating the source document at least read the comments contained in the respective source document template file to obtain a basic understanding of the formatting principles that are described therein.

In addition to using the template files described above, other files may be imbedded into a source document to provide common document formatting and print formatting parameters. One such file is 'INSERT SCRIPT D' (FRSDOC) which is imbedded into general system documentation source files to provide these common formatting parameters.

The INSERT file

The INSERT file used in the FRS documentation system is basically the same file that is found on the DOCADM01 machine with a few minor changes. The im dsmprofN command has been omitted because it is contained in the commands set up within system EXEC'S to create HELP files and to print documents. In addition, :psc. controls have been added to vary the logical page formattiing parameters depending on the printer or display device being used. The INSERT file should be imbedded (.im insert) at the beginning of each document. This will also insure proper formatting on on the DOCADM01 machine should the source file eventually be transferred to that machine. The INSERT file is shown in Figure 1. 

		.im deffonts
       .bf sm10
       .ll 6.7i
       .tm 0i
       .pl 60
       .pm 0.5i
       .tp 08
       .***** Process specific control for 3800 page mode printing
       :psc proc='38ppur'.
       .pl 11i
       :epsc.
       .***** end 3800 specs
       .***********************************************************
       .* This will supress the running footing for 3270 printing *
       :psc proc='3270'
       .rf sup
       :epsc.
       .** End of segment control **
       .***********************************************************
	   
	      Figure 1. INSERT script file

Process Specific Controls (PSC)

Process specific controls permit the document creator to control certain formatting processes according to the device being used to print or display a document. The point to emphasize here is that not everything written in the source file to be printed will produce a suitable format for a help file display (figures and tables for example). Also, page definitions willlikely be different for the different devices used. Finally, there may be information that you want totally suppressed depending on the output device or target audience. These problems can be solved with the :PSC. command.

The PSC tag tells SCRIPT/VS to either include or ignore specific sections or controls, depending on which device is specified. The PSC tag has a PROC attribute for specifying the device as shown in this example: 

     :psc proc='38pp'.  (IBM 3800 Printing Subsystem Model 3)
     :psc proc='3270'.  (IBM 3270 Information Display Family)

The PSC format looks like this:

     :psc proc='38pp'.
               .
               .
               .
     :epsc.

The above example demonstrates that the section between the control words will only print out on the 3800 laser printer and will be suppressed on any other device.