Difference between revisions of "HOWTO Generate Online Documentation"

Latest revision as of 22:49, 14 February 2019

How to Generate Online Documentation

This section describes some of the various methods by which users can secure VistA technical documentation. Online technical documentation pertaining to the software within any particular Application inside VistA, in addition to that which is located in the help Prompts and on the help screens which are found throughout the particular package, can be generated through the use of several Kernel options. These include, but are not limited to, the following:

• %Index
• Menu Management
• Inquire option
• Print Option File
• VA FileMan
• Data Dictionary Utilities
• List File Attributes

Entering question marks at the "Select ... Option:" Prompt can also provide users with valuable technical information. For example, a single question mark (?) lists all options which can be accessed from the current option. Entering two question marks (??) lists all options accessible from the current one, showing the formal name and lock for each. Three question marks (???) displays a brief description for each option in a menu while an option name preceded by a question mark (?OPTION) shows extended help, if available, for that option.

For a more exhaustive option listing, and further information about other utilities which supply online technical information, please consult the Kernel Reference Manual.

XINDEX (sometimes called %INDEX or ZINDEX)

This option analyzes the structure of a routine(s) to determine in part if the routine(s) adheres to the Standards and Conventions (SAC) Programming Standards. The original program was written by Bob Lushene with changes by the VA Kernel team from Joel Ivey and Wally Fort, including Ron Dimicelli. Sam Habiel of OSEHRA has updated it some as well. The XINDEX output might include the following components:

• Compiled list of errors and warnings
• Routine listing
• Local variables
• Global variables
• Naked globals
• Label references
• External references

By running XINDEX for a specified set of routines, you are afforded the opportunity to discover any deviations from SAC Programming Standards which exist in the selected routine(s), and to see how routines interact with one another (i.e., which routines call or are called by other routines).

To run XINDEX for any particular package, you must specify the package namespace at the "routine(s) ?>" Prompt.

NOTE: There are some programs which it isn't as useful to include as input to the XINDEX program, such as those used as package initialization routines which reside in the VistA system in which XINDEX is being run, compiled template routines, and local routines found within the namespace (typically they are the namespace followed by "Z" followed by some other characters). These auxiliary should be omitted at the "routine(s) ?>" Prompt. To omit routines from selection, preface the namespace with a minus sign (-).

Inquire Option

This Menu Management option provides the following information about a specified option:

• Option name
• Menu text
• Option description
• Type of option
• Lock (if any)

In addition, all items on the menu are listed for each menu option. To secure information about a particular package's options, you must specify the package's namespace.

Print Option File

This utility generates a listing of options from the OPTION file (#19). You can choose to print all of the entries in this file, or you can elect to specify a single option or range of options. For a list of all the package's options, you can refer to the Exported Options section of the relevant manual.

List File Attributes

This VA FileMan option allows you to generate documentation pertaining to files and file structure. Using the "Standard" format of this option yields the following data dictionary information for a specified file(s):

• File name and description
• Identifiers
• Cross-references
• Files pointed to by the file specified
• Files which point to the file specified
• Input, print, and sort templates

In addition, the following applicable data is supplied for each field in the file:

• Field name, number, title, and description
• Global location
• Help Prompt
• Cross-reference(s)
• Input transform
• Date last edited
• Notes

Using the "Global Map" format of this option generates an output which lists the following information:

• All cross-references for the file selected
• Global location of each field in the file
• Input, print, and sort templates.

For a comprehensive listing of all of a package's files, please refer to the Files section of the relevant manual.