Next: gethistory() Up: MacAnova Help File Previous: getfilename()   Contents

gethelp()

Usage:
gethelp([Topic1,Topic2,...] [,file:FileName or orig:T or alt:T]\
  [,scrollback:T, usage:T, silent:T, printname:T])
gethelp(Topic1:Subtopic1 [,Topic2:Subtopic2,...] [,other keywords]),
  Topic1, Topic2 ...  names of topics, Subtopic1, Subtopic2, ...,
  CHARACTER scalars or vectors
gethelp(Topic, subtopic:Subtopics [,other keywords])
gethelp(Topic, subtopic:"?" [,other keywords])
gethelp(Pattern [keywords]) where Pattern has form "start*",
  "start*end", or "*mid*", "start*mid*", ...
gethelp(key:KeyName [keywords]), where KeyName is a CHARACTER scalar or
  "?"
gethelp(news), gethelp(news:yymmdd1) or gethelp(news:vector(yymmdd1, \
  yymmdd2)), where yymmdd1 and yymmdd2 are integers like 990103,
  19990103, 000717 or 20000727



Keywords: general, files
gethelp() retrieves help information from a "help file", a text file
in a special format.  It can be used directly, but is usually accessed
by macros help() or usage() which enable searching several files for
information.

gethelp() searches only the "current" help file.  This is initially
"macanova.hlp" but can be changed by keywords 'file', 'alt' and 'orig'
or by macros help() and usage().

gethelp() with no argument prints a short message giving some of the
help() and gethelp() options.

gethelp("*") lists all help topics in the current help file.  There are
over 350 topics in the default help file, macanova.hlp, so this can be a
long list.

gethelp(Topic) prints information about the named topic.  The topic name
may be unquoted (gethelp(break)) or quoted (gethelp("break")).  Only the
current help file is searched.

gethelp(Topic, usage:T) does the same, except it gives only a brief
summary of how a command is used, without lengthy details or
explanation.  This is the same information as is provided by usage() and
getusage().  In fact, gethelp(Topic, usage:T) is equivalent to
getusage(Topic).

gethelp(topic, silent:T [,usage:T]) does the same, except any warning
messages are suppressed.  silent:T does *not* suppress printing of
help or usage information.

gethelp() returns an "invisible" LOGICAL scalar whose value is True only
when at least one topic requested was found.  The value may be assigned
or tested but will not be printed automatically.

  Cmd> if (!gethelp(topic)){print("No help found")}

See topic 'variables:"invisible"'.

Most help topics are divided into subtopics that can be accessed
individually if you know what they are.  Common subtopic names are
"usage" and "example".

gethelp(Topic, subtopic:"?") lists all subtopic names, if any,
associated with Topic.  When the topic name is no longer than 10
characters, gethelp(Topic:"?") does the same.

gethelp(Topic, subtopic:Subtopics), where Subtopics is a quoted string
or CHARACTER vector gives help only on the subtopic or subtopics named
in Subtopics.  Upper and lower case is ignored in these names and all
subtopics starting with any name in Subtopics will be listed.  In the
most common case, Subtopic is a quoted string.  No other topics can be
arguments.  When the topic name is no longer than 10 characters,
gethelp(Topic:Subtopics) does the same.

Examples:
  Cmd> gethelp(anova); gethelp(macros); gethelp("break")
  Cmd> gethelp(break) #nows work; previously didn't
  Cmd> gethelp(transformations) #now works; previously didn't
  Cmd> gethelp(regress, usage:T) # same as usage(regress)
  Cmd> gethelp(anova, subtopic:"example") # or gethelp(anova:"example")
  Cmd> gethelp(regress:vector("usage","example"))
  Cmd> gethelp(transformations,subtopic:"?")
  Cmd> if (!gethelp(foo,silent:T)){print("No help on topic foo")}

See macrousage() for a way to get usage information on currently defined
macros.

See below for using keywords 'file', 'orig' and 'alt' to control the
file from which gethelp() gets information.

gethelp(Topic, scrollback:T) is legal only on a windowed version
(Macintosh, Windows or Motif).  It cause the gethelp() output to be
automatically scrolled back to its start.  You can make this the default
behavior by setoptions(scrollback:T).  See topics setoptions(),
'options'

On the Macintosh, Help (Command+H) on the Help menu is equivalent to
'gethelp()'.  If you select a command name or other topic name in the
command window with the mouse, menu item Help gives you help on that
topic.  In the Windows and Motif versions, Help on the Help menu is like
typing 'gethelp()' and is not affected by the selection in the window.

gethelp(key:"foo") lists all topic names associated with key "foo".
Examples of keys are "Residuals", "Missing Values", "ANOVA", and
"Variables".  In matching keys, case (upper or lower) is ignored.
Moreover, you need type only enough letters to identify a key uniquely.
For example, gethelp(key:"resid") gives the same output as
gethelp(key:"Residuals").

gethelp(key:"?") lists all recognized keys.

You can also use one of keywords 'file', 'orig', or 'alt' (see below)
with 'key'.

When you aren't sure of the exact topic name, you can use the "wild
card" characters '*' and '?' in a quoted string to define a pattern to
be matched.  '*' will match any 0 or more successive letters in a topic
name and '?'  matches any single letter.  All matching names are
printed.  If only one name matches, full help will be given on that
topic.

Examples:
  gethelp("res*")     lists all topic names beginning with "res"
  gethelp("*line*")   lists all topic names containing "line"
  gethelp("*anova")   lists anova,fastanova, manova, wtanova, wtmanova
  gethelp("*plot")    lists names ending in "plot" like chplot(),
                      boxplot()
  gethelp("*pl?t")    lists all topic names whose last 4 characters or
                      "p", "l", any character, and "t" repectively
                      (plot(), lineplot() and split(), for example).
  gethelp("*tat*")    lists cellstats(), rotate(), rotation()
  gethelp("add*lin*") gives help for addlines() (only 1 matching)
  gethelp("*i*e*t")   lists all topic names containing "i" and "e", in
                      that order, and ending with "t" ('assignment' and
                      lineplot(), for example).

gethelp(Topic1,Topic2,... [,scrollback:T or usage:T] [,silent:T]) prints
information about each of the topics specified by the arguments.  If an
argument is a quoted string containing '*' or '?', it is used as a
pattern as above, but if there is more than one topic, only the first
topic in the help file whose name matches is printed.  The same rules
concerning quotes apply as when there is only one topic.

gethelp(Topic1:Subtopics1, Topic2:Subtopics2 [,...]) prints information
in the designated subtopics of Topic1, Topic2, ... .  You can also mix
in ordinary topic names without subtopics.

You can't name more than one topic when you use keyword 'subtopic'.

  gethelp(help,break) will produce this text and information about
                     syntax element 'break'
  gethelp(anova:vector("usage","examples"),option:"scrollback")
                     will print two subtopics to topic 'anova'
                     and one subtopic of topic 'option'

The help information is kept in a file in a particular format.  The
default file name is macanova.hlp.  A description of the format is near
the start of the macanova.hlp

The actual file used can be changed using keyword 'file' or restored to
the default by keyword phrase 'orig:T'.  You can retrieve the name of
the actual current help file by getfilename(help:T).

Macros help() and usage() may change the current help file.  By default,
if the current help file contains the wanted topic, or if the topic is
not found in any help file, the current help file is not changed.  If
the topic is found in another file, that file becomes the current help
file.

                              Topic 'news'
gethelp(news [,scrollback:T]) lists in reverse chronological order news
items about MacAnova starting with the most recent entry back for three
months.

gethelp(news:vector(Date1,Date2) [,scrollback:T]), where Date1 and Date2
are numbers of the form yymmdd or yyyymmdd, lists in reverse
chronological order news items about MacAnova development dated between
Date1 and Date2.  For example, gethelp(news:vector(991201,0000131)) and
gethelp(news:vector(19991201,20001230)) list all news items dated in
December, 1999 or January, 2000

gethelp(news:Date) lists all news items on or after Date.  For example,
gethelp(news:000101) and gethelp(news:200000100) list all news items on
or after January 1, 2000.

gethelp(news:0) lists all available news items.  This will produce many
of lines of output and is not recommended.

                         Using other help files
Currently there are ten files distributed with MacAnova which contain
help.  Some also contain the macros they provide help for.

   File                     Contents
  ----------------------------------------------------------------------
  arima.mac             Help on macros in arima.mac
  design.hlp            Help on the macros in file design.mac
  graphics.mac          Help on macros in graphics.mac
  macanova.hlp          Help on all MacAnova commands, predefined macros
                        and general information (the default help file)
  macanova.nws          Old news items and obsolete help topics removed
                        from macanova.hlp
  math.mac              Help on macros in math.mac
  mulvar.mac            Help on macros in mulvar.mac
  regress.mac           Help on macros in regress.mac
  tser.hlp              Help on the macros in file tser.mac
  userfun.hlp           Help related to programming user functions

On a single call, gethelp() scans only a single file for help.  The
default help file is macanova.hlp.

Predefined macro help() uses gethelp() to scan all files whose names are
in CHARACTER variable HELPFILES until it finds help on a requested
topic.  The default value of HELPFILES contains all the above files
except macanova.nws and userfun.hlp.  help() is used almost identically
to gethelp().

If you know which file the topic is, you can use one of the pre-defined
macros arimahelp(), designhelp(), graphicshelp(), mathhelp(),
mulvarhelp(), regresshelp(), tserhelp() and userfunhelp() for easy
retrieval of help from the other files (except macanova.nws).  These are
used essentially the same way as help().  See topics arimahelp(),
designhelp(), graphicshelp(), mathhelp(), mulvarhelp(), regresshelp(),
tserhelp() and userfunhelp() for details.  The may have an advantage
over help() in that they scan only one file.

Or you can use gethelp() with keyword 'file'.  See below.

Examples:
  arimahelp("*")           lists all topics in file arima.mac
  designhelp(aliases2)     prints help information on macro aliases2()
                           in design.mac
  mathhelp(i0,usage:T)     prints usage on macro i0() in math.mac
  regresshelp(key:"anova") lists topics related to key 'anova' in file
                           regress.mac

These macros make use of keywords 'file', 'orig' and 'alt' that direct
gethelp() to change help files.

gethelp(file:FileName) where FileName is a quoted string or CHARACTER
variable specifying the name of a file, makes that file an alternate
help file and switches over to using it.  In versions with windows
(Macintosh, Windows, Motif), when FileName is "", you use a dialog box
to select the file.  One or more topic names can follow file:FileName or
file:FileName can be the last argument.  The alternate help file remains
active until another is specified, or keyword phrase orig:T appears in a
gethelp() command.  If the file is not in the correct format for a help
file, the results are unpredictable but not pleasant.

gethelp(orig:T) restores the help file to what it was at startup.  This
will either be the standard help file or the one specified (under
Unix/Linux or DOS) by the -h option on the command line.  See topic
'launching'.  One or more topic names can follow orig:T, or orig:T can
be the last argument.

gethelp(alt:T) restores the help file to the one most recently specified
by file:fileName.  It is an error if no alternative file was previously
set.  This allows you easily to use two help files, the default one and
one alternate.  You switch back and forth between them by
gethelp(orig:T) and gethelp(alt:T).  One or more topic names can follow
alt:T, or alt:T can be the last argument.

Prior to Version 4.12, gethelp() was named help().  help() is now a
macro that uses gethelp() to search several help files.  If you want
help() to work identically to gethelp(), you can define a simplified
version by:
  Cmd> help <- macro("gethelp($0)")

Prior to Version 4.11, topics longer than 12 characters or that were
control words ('if', 'while', 'for', 'else', 'elseif', 'break',
'breakall') had to be quoted.  This is no longer the case.


Help() is a synonym for gethelp() and is used identically.


Gary Oehlert 2003-01-15