McIDAS Programmer's Manual
Version 2006

[Search Manual] [Table of Contents] [Go to Previous] [Go to Next]

Appendix A

Guidelines for Writing 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.

This appendix consists of these sections:

General guidelines for all helps

Confirm that all spelling and punctuation are correct.

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 78 columns 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:

SFCMG - Displays a surface meteorogram 
    -or-
AVGI -- Reduces image resolution by averaging

Use a series of 10 hyphens to indicate the end of the help. For example:

C ? ----------

Don't include the owner's initials in the help.

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.

See the following commands as examples if you're writing a complex help: MDX, SCFPLOT, BATCH, ZA, SFCMG, LVF, IMGCOPY, IMGOPER and GRDDISP.

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: (def=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 ADD, DEL, LIST, and HOST options of the DATALOC 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 each keyword with its required letters in uppercase and optional letters in lowercase, followed by an equal sign, a space, a vertical bar, another space, and then the description. In the example below, COLor= means the user can enter COL=, COLO=, or COLOR=.

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:

FORmat=ID    | plot the 3- to 5-character ID at each station location; see the Remarks (def)
      =IDN   | plot the 5-digit ID number at each station location
      =NAME  | plot the station name at each station location
      =POINT | plot a point at each station location

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 -- Writes text and/or symbols on the graphics frame
C ?   ZA color height justify  "text
C ? Parameters:
C ?   color | graphics color level; 0 for erase (def=1)
C ?   height | pixel height to draw text/symbols (def=10 for text; cursor
C ?            height for TCYC= symbol)
C ?   justify | text justification; specify one of the following options:
C ?                LA - left justified above center of cursor
C ?                LC - left justified at    center of cursor
C ?                LB - left justified below center of cursor (def)
C ?                CA - center justified above center of cursor
C ?                CC - center justified at    center of cursor
C ?                CB - center justified below center of cursor
C ?                RA - right justified above center of cursor
C ?                RC - right justified at    center of cursor
C ?                RB - right justified below center of cursor
C ?                M  - mouse justified; see the Remarks
C ?                N  - same as CC option, but allows numerous plots of the
C ?                     text/symbols by pressing mouse buttons; see Remarks
C ?                V  - vertically aligned; the upper-left corner of the
C ?                     first letter or symbol is placed at the cursor center;
C ?                     subsequent letters and symbols are written below
C ?   "text | text to write on the graphics frame; the following placeholders
C ?           can be specified for text substitution using information from the
C ?           frame, dataset or displayed image:
C ?             (FRAME)   - frame number of display, nnn
C ?             (DATASET) - ADDE dataset name of image, 24 char max
C ?             (POS)     - ADDE dataset position of image, nnnn
C ?             (BAND)    - band number of image, nn
C ?             (WL)      - wavelength of image, nn.nn unit
C ?             (WN)      - wave number of image, nn.nn unit
C ?             (FREQ)    - frequency of image, nn.nn unit
C ?             (ID)      - NEXRAD station ID of image, 3 char
C ?             (MEMO)    - memo field of image, 32 char max
C ?             (SS)      - sensor source number of image, nnn
C ?             (STYPE)   - image type of image, 12 char max
C ?             (ERES)    - element resolution of image, nn.nn
C ?             (LRES)    - line resolution of image, nn.nn
C ?             (RES)     - resolution of image, nn.nn
C ?             (EGEORES) - geographical element resolution of image in km, n.nn
C ?             (LGEORES) - geographical line resolution of image in km, n.nn
C ?             (GEORES)  - geographical resolution of image in km, (n.nn X n.nn KM)
C ?             (DAY)     - day of image, dd mon yy
C ?             (MDY)     - day of image, mon dd yy
C ?             (JDAY)    - Julian day of image, ccyyddd
C ?             (TIME)    - time of image, hhmmss
C ?             (HH)      - time of image, hh
C ?             (HHMM)    - time of image, hh:mm
C ?             (HHMMSS)  - time of image, hh:mm:ss
C ?   "$text | displays weather symbols or arrows on the graphics frame; see
C ?            the McIDAS User's Guide for valid choices
C ? Keywords:
C ?   Ang= | angle to write text; do not use with the FONT command or global
C ?          keyword, or keywords ENCL or TCYC
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 ?   FULlframe=YES | use the entire frame for output, regardless
C ?                   of the frame's panel configuration; do not use
C ?                   FUL=YES with the global keyword PANEL
C ?            =NO  | limit output to the current panel or the panel
C ?                   specified in the global keyword PAN (def)
C ?   Gra= | graphics frame number (def=current)
C ?   IMA= | image frame number to use for determining values of placeholders
C ?          in "text parameter (def=current)
C ?   POS=lin ele | TV line and element position to draw text, symbols or
C ?                 arrows (def=current cursor position)
C ?   TCYc=color hemi | plots a hurricane or tropical storm symbol centered
C ?                     on the cursor or the position specified in the
C ?                     POS keyword, where:
C ?                     color - graphics color level of the symbol's center;
C ?                             specify X to leave the center blank
C ?                     hemi - N or S for northern or southern hemisphere;
C ?                            determines direction of the spirals (def=S)
C ?   Wid= | graphics line width, in pixels; the maximum is 64 (def=current)
C ? Remarks:
C ?   In the "justify" parameter:
C ?     - left justified (LA, LC and LB options) means the text begins at the
C ?       cursor position and extends to the right
C ?     - right justified (RA, RC and RB options) means the text ends at the
C ?       cursor position and extends to the left
C ?     - center justified (CA, CC, CB and N options) means the text is
C ?       horizontally centered at the cursor position so it extends equal
C ?       distances to the left and right.
C ?
C ?   The (GEORES), (LGEORES) and (EGEORES) placeholders can be used only
C ?   if GEORES=YES was specified in the IMGDISP command that displayed
C ?   the image. The resolution values, listed as "n.nn" in the Parameters
C ?   section above, are in kilometers and are displayed in the format 0.nn,
C ?   n.nn, nn.n or nnn (depending on the magnitude of the resolution).
C ?   The two resolution values displayed with the (GEORES) placeholder
C ?   are the same as (LGEORES) and (EGEORES), in that order.
C ?
C ?   If you choose the M(ouse) option, clicking the middle mouse button
C ?   repositions the start of the text at the cursor location. Clicking the
C ?   right button repositions the end of the text at the cursor location.
C ?   The height is scaled as needed. Using the FONT command or global keyword
C ?   with the M option positions the text horizontally at various sizes. You
C ?   can't change the angle of the text.
C ?
C ?   If you choose the N(umerous) option, clicking the middle mouse button
C ?   draws the text, centered at the cursor location. Clicking the right
C ?   button erases the last drawn text.
C ?
C ?   When ENCL= is used, the practical maximum number of characters is 3.
C ? ----------

[Search Manual] [Table of Contents] [Go to Previous] [Go to Next]