S-PLUS help

Help Window System

DESCRIPTION:: Starts and controls the window system for help in S-PLUS. This system allows you to search for help files by topic and to display them. You can look at many help files at the same time and keep them on the screen as you continue working with S-PLUS itself. You can also put your own help files into the help system.

USAGE:

help.start(args, gui=options("gui")[[1]])

help.off()
help.running()
help.search()
help.topic(topic)
help.keyword(keyword)
help.name(name)
help.findsum(dirs)
help.popup(..., rescan=T)

OPTIONAL ARGUMENTS:

args:: a vector of character strings to customize the look of the help windows. The meaning depends on the graphical interface - the strings are equivalent to the command line arguments used to start other programs using the same graphical interface. For example, both understand "-geometry WxH+X+Y" (meaning to make the help W pixels wide, H high and put the upper left corner at (X,Y)).

If you are using an X11 based graphical interface, the environment variable DISPLAY should be set to indicate the name of the machine (and which display and screen on that machine) at which you are sitting. If DISPLAY is not set, args should contain "-display mach:0.0", where "0.0" indicates the display and screen numbers, and "mach" is the name of the machine at which you are sitting.

gui:

character string giving the name of the graphical user interface that should be used for the help system. Possible values are "motif" and (on systems for which it is defined) "openlook". Unless you have set the gui in .Options, the default will be "motif".

topic:

character string giving a topic for which a search is to be performed.

keyword:

character string that is one of the S-PLUS keywords (these are given in the prompt help file).

name:

character string naming an S-PLUS object for which a help window is to be created.

dirs:

character vector giving the directory databases for which you want to create help summary files.

rescan:

logical flag indicating whether help.popup should rescan the help categories. This will be the equivalent of doing help.search() followed by help.keyword("all").

...:

for the help.popup function, any remaining arguments are passed directly to help.start if the help system is not already running.

SIDE EFFECTS:

help.start turns on the help window system.

help.off turns off the help system. The help window system also shuts down when S-PLUS finishes.

help.search sends the current search path to the help system.

help.topic, help.keyword, and help.name allow you to give a topic, keyword (category) or name from an S-PLUS function and have the help window system display information on it. These are equivalent to typing an entry in the "Topic" area, selecting an entry in the "Category" menu, and selecting an entry in the list of functions, respectively. These functions allow programmatic control over the help window system; we don't expect that the casual user will use them directly.

help.findsum creates a help summary file under each directory database specified.

help.popup will make sure that the main help window is brought to the top. The window may be deiconified, if necessary, and help.start may be run if the help system is not already running.

DETAILS:

We supply help windows for the Motif graphical interface, and on Sun systems support Open Look as well. Each of these graphical interfaces gives a different look and feel to the help window. help.start used "motif" by default; if you want to use "openlook" you must set the gui option (or specify a value for the gui argument) and be running the appropriate window system for it before using help.start. To set the option, execute the command:

options(gui=xxx)

where "xxx" is "openlook" or "motif".

If you want to use Open Look rather than Motif, we recommend that you put a command to select the graphical interface into your .First function; you may want to put help.start() into your .First also.

Start the help system with the command help.start(). When the main help window pops up, you will see that it has three main parts : a list of "Categories", a list of functions (and datasets) along with short descriptions of each, and an area in which you may type in a topic. If you move the mouse so the cursor is over an entry in the "Categories" menu and click the select button (usually the left mouse button), then a new list of functions will appear in the right part of the help window. This list should include all functions (and datasets) in the current search path in that category. If you press the select button over one of the functions in that list, a new window will pop up, showing the help file for that function. In the upper left corner of the help file window there will be a menu button named "File"; pop up the menu and see that you can print the help file or close that help window. Back in the main window, you will see a type-in area labeled "Topic". You may type in a word there to get a list of functions and datasets with that word in their name or short description. You can then select from that list to see a help file for an entry.

Each time you attach or detach a directory, new help files become available or unavailable so the help system must be notified about this. The attach and detach functions call help.search to take care of this, you should not have to use this function. You may notice that whenever the path changes, the help system will take some time to update its current list of functions and to check to see if a help file you have displayed needs to be updated to show the help file by the same name in the new directory.

When you write a new set of help files (using the prompt function), you should make the help system reflect the new documentation. This allows the help system to use your new help files.

For each directory database on your search path, the help system looks for a help summary file called .Help/.Help.find.sum under the directory containing the S-PLUS objects themselves (a directory database). The file contains information about the help files in the the standard S-PLUS directory databases.

To create a help summary file for your own directory database, use this function with a character vector naming the directory database.

BACKGROUND:: Motif is put out by the Open Software Foundation, supported by Hewlett-Packard, Digital Equipment Corp, and others. OpenLook is put out by Unix International, supported by Sun, ATT, and others. Both Motif and OpenLook operate under the X window system; Motif works on virtually any X11 server while OpenLook requires that you install the OpenLook fonts, available from Sun Microsystems.

SEE ALSO:: help , Question.mark , topic , options , .First , prompt .

EXAMPLES:

# starting the help system

options(gui="motif")
help.start() # now the main help window will pop up

# creating your own help file for a function, and making a new
# help summary file with information about your new help file in it

myfunc <- function(x) x^2
prompt(myfunc, filename="myfunc.d")
!vi myfunc.d
!mkdir .Data/.Help
!mv myfunc.d .Data/.Help/myfunc
help.findsum(".Data")