McIDAS Programmer's Manual
[Table of Contents]
Guidelines for Writing Helps
appendix provides the guidelines to follow when creating or modifying a help
to meet the McIDAS-X core standards. You will learn:
- General guidelines
to use for all command helps
guidelines to use for parameters, keywords and remarks
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.
appendix consists of these sections:
guidelines for all helps
all spelling and punctuation are correct.
your help contains the sections listed below. Only include examples if the
help is very short.
- Command name
with functional description
- Command formats
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.
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
AVGI -- Reduces image resolution by averaging
Use a series
of 10 hyphens to indicate the end of the help. For example:
C ? ----------
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.
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.
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.
parameter and keyword descriptions as complete sentences. If the description
has more than one comment, link them with semicolons.
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
individually, in the order they appear in the command formats, not alphabetically.
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. 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)
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.
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.
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.
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 ? 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 ? 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 ? 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 ? When ENCL= is used, the practical maximum number of characters is 3.
C ? ----------
[Table of Contents]