Getting Help: the HELP command and the ? token

##
Getting Help: the HELP command and the ? token

As with any SIC based program, simple call to HELP will display the various languages (e.g., SIC\, GREG\, CALIBRATE\, CLEAN\) accessible to the help documentation and list some commands with available documentation. Note that CLEAN is a command and CLEAN\ a language (i.e., a family of commands). The language of a given command is recalled in the help of each command.

Example: the command APPLY belongs to the language CALIBRATE\, it has one argument which can be AMPLI or PHASE exclusively, one optional argument gain, and one option /FLAG.

    IMAGER> help apply
            [CALIBRATE\]APPLY [AMPLI|PHASE [gain]] [/FLAG]

In the provided description, arguments within [] are optional. Upper case arguments are fixed keywords that can (in general) be abbreviated. A character separates the allowed keyword values. Lower-case arguments are expected to be numbers, text, filenames, SIC variables or expressions that can be evaluated.

A brief description of the imager program can be obtained through:

    IMAGER> help imager
    USER\IMAGER = "@ welcome.ima"

          IMAGER is a interferometric imaging package, tailored for usage
      simplicity and efficiency for multi-spectral data sets.

         The basic concept of IMAGER is the use of a simple
             READ data  - ACTION(s) - [SHOW or VIEW] - WRITE
      sequence of commands, minimizing the data I/O as much as possible.
      Automatic guesses of appropriate default values for the ACTIONs
      parameters is implemented whenever possible.

    Additional Help Available:
     Actions      BEAM_Handlin MAP_Handling UV_Handling  WebPage
     HOW_TO       MAPPING

In addition, finding documentation and help for the IMAGER commands can be done in three different ways:

- a simple call to the HELP command provides a description of the command and its arguments and options
- the command name followed by one or more questions marks will display some partial help on the command and its most useful parameters (” Command ?”), its second level parameters for advanced users (” Command ??”), all its parameters (” Command ???”).

Documentation on subtopics of a given command (e.g., Variables, Arguments, or Results) can be obtained though: HELP command subtopic. The list of available subtopics is found at the bottom of the documentation of each command:

    IMAGER> help uv_map
    [...]
    Additional Help Available:
     Mosaics      /FIELDS      /RANGE       /TRUNCATE
     Variables:
                  BEAM_STEP    MAP_CELL     MAP_CENTER   MAP_CONVOLUT MAP_FIELD
     MAP_POWER    MAP_PRECIS   MAP_ROBUST   MAP_ROUNDING MAP_SHIFT    MAP_SIZE
     MAP_TAPEREXP MAP_TRUNCATE MAP_UVTAPER  MAP_UVCELL   MAP_VERSION
     Old_Names:
                  convolution  map_angle    map_dec      map_ra       mcol
     uv_cell      uv_shift     uv_taper     taper_expo   wcol         weight_mode

Subtopics that appear in UpperCase in the Additional Help Available list are case insensitive. Subtopics that are in LowerCase of mixed case are strictly case sensitive.

Example: the following command will list the control variables of the UV_MAP function and describe the associated parameter(s):

    IMAGER> help uv_map Variables
    UV_MAP Variables:
                    [CLEAN\]UV_MAP ?
            Will list all MAP_* variables controlling the UV_MAP parameters.

        The list of control variables is (by alphabetic order, with  the  corre-
        sponding old names used by Mapping on the right)

        New names       [   unit]       -- Description --    % Old Name
        BEAM_STEP       [       ]  Channels per dirty beam  % MAP_BEAM_STEP
        MAP_CELL        [ arcsec]  Image pixel size
        MAP_CENTER      [ string]  RA, Dec of map center, and Position Angle
        MAP_CONVOLUTION [       ]  Convolution function     % CONVOLUTION
        MAP_FIELD       [ arcsec]  Map field of view
        MAP_POWER       [       ]  Maximum exponent of 3 and 5 allowed in MAP_SIZE
        MAP_PRECIS      [       ]  Fraction of pixel tolerance on beam matching
        MAP_ROBUST      [       ]  Robustness factor        % UV_CELL[2]
        MAP_ROUNDING    [       ]  Precision of MAP_SIZE
        MAP_SIZE        [       ]  Number of pixels
        MAP_TAPEREXPO   [       ]  Taper exponent           % TAPER_EXPO
        MAP_TRUNCATE    [      %]  Mosaic truncation level
        MAP_UVCELL      [      m]  UV cell size             % UV_CELL[1]
        MAP_UVTAPER     [m,m,deg]  Gaussian taper           % UV_TAPER
        MAP_VERSION     [       ]  Code version (0 new, -1 old)

        See HELP UV_MAP Old_names:  for deprecated variable names.

A more detailed description (type, size) of a given variable can be obtained through help command variable, as in this example:

    IMAGER> help uv_map map_uvtaper
    UV_MAP MAP_UVTAPER

          MAP_UVTAPER[3]  Real

        Parameters of the tapering function (Gaussian if MAP_TAPEREXPO = 2): ma-
        jor axis at 1/e level [m], minor axis at 1/e level [m], and position an-
        gle [deg].

MAP_UVTAPER is an array that requires 3 values of type Real.

The default values of the useful parameters are checked through Command ?1

     UV_MAP makes a dirty image and a dirty beam from the UV data

     Behaviour is controlled by a number of SIC Variables
     - BEAM_STEP and MAP_PRECIS control the dirty beam precision
     - MAP_CENTER controls shifting ang rotation
     - MAP_CELL[2], MAP_SIZE[2], MAP_FIELD[2] control the map sampling
     - MAP_UVTAPER[3], MAP_UVCELL and MAP_ROBUST
         control the beam shape and weighting scheme

    ---- Basic parameters                            Selected       Recommended
      Map Size (pixels)              MAP_SIZE        [ 0 0 ]   [ 0 0 ]
      Field of view (arcsec)         MAP_FIELD       [ 0 0 ]   [ 0 0 ]
      Pixel size (arcsec)            MAP_CELL        [ 0 0 ]   [ 0 0 ]
      Map center                     MAP_CENTER      [  ]
      Robust weighting parameter     MAP_ROBUST      [ 0 ]
      UV cell size (meter)           MAP_UVCELL      [ 0 ]          [ 0 ]
      UV Taper (m,m,°)               MAP_UVTAPER     [ 0 0 0 ]

For commands that support the ? mechanism, Command ? ControlVariable and, in most cases, Command ControlVariable ? are shortcuts to HELP Command ControlVariable.