Guidelines forWriting Helps

This appendix provides the guidelines to follow when creating or modifying a help to meet the McIDAS-X core standards. You will learn:

A sample help for the McIDAS-X command ZA is also included. See the McIDAS User's Guide and online command helps for additional examples.

General guidelines for all helps

Verify that your help contains the sections listed below. Only include examples if the help is very short.

Keep the length of each line to 76 columns or less, and the total length of the help to 79 lines or less. This will accommodate the width of the default McIDAS-X Text and Command Window, which is formatted to 80 columns.

Verify that the first line of the help contains the command name, one or two hyphens and an accurate functional description. For example:

Don't put tabs in the help. The programs that make the help files will skip lines with tabs, resulting in help files with missing information. To check for tabs in vi, use :set list.

Specific guidelines

Parameters and keywords

Check existing helps when naming parameters and keywords, since many McIDAS-X commands share parameter and keyword names and definitions. If you use a parameter or keyword with the same meaning as one in another core program, use the same name. For example, use the parameter day and keyword DAY instead of date or DATE.

Choose parameter and keyword names that are unambiguous. For example, sarea and darea, for source area and destination area, are better choices for parameter names than area1 and area2, or source and dest.

Don't write parameter and keyword descriptions as complete sentences. If the description has more than one comment, link them with semicolons.

Place default values for the parameters and keywords in parentheses at the end of the line using this format: (default=value1 value2 ...).

Use a vertical bar character ( | ) between the end of a parameter name or keyword name and its description. If possible, align these vertical bars. The vertical bar is required by the help program to list the parameters and keywords when a user requests an abbreviated help by pressing Alt ?.

Parameters only

List parameters individually, in the order they appear in the command formats, not alphabetically.

Specify a parameter name in uppercase only if it is the exact value that the user will enter; for example, the MAKE, LIST, DIR, and DEL options of the MDU command. Otherwise, parameter names are lowercase.

Keywords only

Alphabetize keywords. If a command has many keywords and you group them by function. Alphabetize them within each group. See the GRDDISP and IMGDISP commands.

Specify keywords in uppercase with an equals sign, followed by a vertical bar character and the description. For example:

COLOR= | graphics color level for contours; use positive
         numbers for solid, negative numbers for dashed (def=2)

If a keyword has several values, don't repeat the keyword name on every line. Simply list subsequent values below the first one. For example:

FORM=ALL | lists an expanded directory
    =STN | lists the standard directory (def)

If a keyword accepts many values or a range of values, use the format shown below.

LEV=l1..ln  | copies grids with these levels; for example,
              SFC, 1000, 850
BAND=b1..bn | applies the function to the specified image
              bands (def=8 for GOES IR, 4 for POES)

Remarks

Place remarks in the order of importance to the user. Since space is limited in online helps, include only those remarks that help the user understand how the program works or provide a useful suggestion.

Write the remarks section in complete sentences with proper punctuation. A remark can be several sentences long. Do not indent the beginning of the remark; instead, separate the remarks with a single blank line.

Sample help

Help for the ZA command is provided below as an example. Also look at the helps for the DSINFO, DATALOC, GRDINFO, GRDCOPY, MFPLOT, NAVDISP and TXT2MD commands. They contain a variety of standard parameters and keywords and are good examples of how to write your helps.

ZA command

C ? ZA -- Place annotation on graphics frame at cursor position
C ?   ZA color height justify <keywords> "text
C ? Parameters:
C ?  color   | graphics color level (def=1)
C ?  height  | pixel height to draw text/symbols (def=10 for
C ?            text; cursor height for TCYC= symbol)
C ?  justify | L=left, R=right, C=center, V=vertical, M=mouse
C ?            N=numerous (def=L)
C ?  "text   | text to write on the graphics frame
C ?  "$text  | displays weather symbols or arrows on the 
C ?            graphics frame
C ? Keywords:
C ?  ANG=   | angle to write text when justify=L
C ?  ENCL=C | draws a circle around the text in the N mode
C ?      =E | draws an ellipse around the text in the N mode
C ?  GRA=   | graphics frame number (def=current)
C ?  TCYC=color hemisphere |
C ?           color - plot a tropical cyclone/hurricane symbol
C ?                   with the specified graphics color level
C ?           hemisphere - determines the direction of spirals;
C ?                   N=northern hemisphere
C ?                   S=southern hemisphere (def)
C ?   WID=  | graphics line width (def=current value; maximum=64)
C ? Remarks:
C ?   When justify = M(ouse), the text positioning will be
C ?   under the control of the mouse position and the clicking
C ?   of the buttons. The MIDDLE button will cause the start
C ?   of the text to be repositioned to the cursor location,
C ?   while the RIGHT button will reposition the end of the
C ?   text. The height will be scaled as needed.
C ?
C ?   When justify = N(umerous), text positioning will be
C ?   centered at the cursor location when the MIDDLE mouse
C ?   button is clicked. The last drawn symbol will be erased
C ?   when the right button is clicked.
C ?
C ?   When ENCL= is used, the practical maximum number of
C ?   characters is 3.
C ? ----------

Appendix A

Guidelines for Writing Helps