Ahelp: ahelp - CIAO 3.4

Description

The ahelp command accesses the CIAO on-line documentation. By default it displays an ASCII version of the help file, although it can be used to cause HTML versions to be shown in a web browser using the "-i" or "-w" flags. The CIAO site contains HTML versions of the help files, which are also available on the European mirror site.

Finding help for a given subject

The help files are arranged by subject into contexts (both subject and context are a single word) and you access these files by either:

  unix% ahelp <subject>

  unix% ahelp <context> <subject>

depending on whether or not there are help files with the same subject but different contexts (ahelp will tell you if you need to specify a context). The ahelp tool is case insensitive when it comes to matching the subject and context values.

Searching for help

If you do not know the exact subject (for a tool, the subject is just the tool name), then you enter

  unix% about <keyword>

for a list of subjects related to your query (ie whatever value you use for <keyword>). To find out all the entries for a given context you use

  unix% ahelp -c <context>

If a search only returns one match then that page is automatically displayed, otherwise you will see a list of subjects, with context and synopsis, that match the search.

Using regular expressions

The CIAO 3.0 release of ahelp adds the ability to use a regular expression when specifying any of the subject, context, or keyword in a search. So, to find a list of all the keywords that contain the text "par", you need to say:

  unix% ahelp /par/

and to list all help files with contexts that begin with "sl":

  unix% ahelp -c /^sl/

This feature can be very useful when trying to search for help on a particular subject, since

  unix% about /bin/

will list all help files whose references include the text "bin" (so this would match bin, rebin, and binned amongst others).

There are a number of resources that describe the extended regular expression syntax used here: "man regexp" may provide details (depending on what system you are using) and there are many pages on the internet.

Listing specific sections of the help file

The "-b blockname" option, introduced in CIAO 3.0, is used to restrict the output to a given section of the help file. This can be useful if you only need specific information, such as the list of known bugs, description of a specific parameter, or the syntax of a given command.

Allowed values for the "-b blockname" option

blockname	Description
SYNOPSIS	Displays the synopsis section.
SYNTAX	Displays the syntax section.
DESC	Displays the main body of the help file, which is the part between the initial synopsis/syntax and the examples/parameter list.
QEXAMPLELIST	Displays the examples.
PARAM	Displays the parameter section. When used with the "-t name" option, only the description of the parameter matching name is listed.
ADESC	Displays any ancillary description section that is displayed after the examples/parameter list. These sections are numbered and may contain a title; if so then the "-t name" option can be used to select just that part of the description.
BUGS	Display any bugs section.
LASTMODIFIED	Displays the date the file was last modified.
VERSION	Displays the version of the help file.

It is not guaranteed that a help file will contain all these sections. The "Structure of a help file" section at the end of this file provides more details on what is included in a help file.

Finding help in ChIPS and Sherpa

The "ahelp" and "about" commands can also be used at the ChIPS and Sherpa prompts to access the help files. The context - if not explicitly specified - is taken to be the name of the tool (ie chips or sherpa). When using regular expressions it is best to surround them in single or double quotes.

Command-line options

The most useful options are given below. If no option is supplied, ahelp defaults to -l.

Option	Details
-l	display the synopsis, syntax summary, description, and examples.
-m	display the synopsis, syntax summary, and examples.
-s	display the synopsis and syntax summary.
-b blockname	Displays only a specific section of the help file. The value of blockname can be one of: SYNOPSIS, SYNTAX, DESC, QEXAMPLELIST, PARAM, ADESC, BUGS, LASTMODIFIED, and VERSION (upper case is required).
-t attribute	Only valid when the -b option is used and blockname is either PARAM or ADESC. The output is restricted to the section that matches the value of attribute - the parameter name for PARAM or the section title (without the leading number) for ADESC.
-w	as -l, but display the HTML version (from the CIAO directory $ASCDS_INSTALL/doc/html/) in a web browser.
-i	as -l, but display the HTML version (from the CIAO web site http://cxc.harvard.edu/ciao/ahelp/) in a web browser.
-k keyword	Returns the results of a search for pages related to the supplied keyword. The keyword can be a regular expression of the form /expression/, in which case the help system is searched for all files that match the given expression. "ahelp -k keyword" is equivalent to "about keyword".
-n value	Instead of formatting the text to match the width of the screen display, use the supplied value.

Options for the CIAO developer

There are several other options that are only useful to CIAO developers and those that install the CIAO software.

Option	Details
-f <filename>	Display the contents of the supplied ahelp file.
-r [<path>]	Re-create the ahelp database using the contents of the doc/xml/ and contrib/doc/xml/ sub-dirctories of <path> - if given - otherwise $ASCDS_INSTALL.

Configuring ahelp

Ahelp uses the PAGER environment variable to find the program to use to page the ASCII output to the screen: examples of suitable values are more or "less -s".

If you make use of the "-b" option in ahelp a lot it may be worth setting up aliases for them. For instance, the following csh/tcsh commands

  unix% alias bugs     'ahelp -b BUGS '
  unix% alias params   'ahelp -b PARAM '
  unix% alias examples 'ahelp -b QEXAMPLELIST '

provide easy access to the bugs, parameter, and examples section of a help file - if they exists - by saying "bugs dmstat", "params aconvolve" ("params -t kernelspaec aconvolve" to list an individual parameter), or "examples dmfilth".

The "Choosing a web browser" section below the Examples describes how you can change what web browser to use when ahelp is called with either the -i or -w flag.

CHOOSING A WEB BROWSER

If you use the -i or -w flags than ahelp will display the help file in a web browser rather than in the terminal window. The default browser that is used is Netscape, and it will re-use an existing Netscape browser if one already exists when ahelp is called.

It is possible to change both which browser is used and its behaviour by adding to (or changing) the file .CXCdefaults in your home directory (see 'ahelp gui' for further information on this file). The default values for these fields - which can be found in $ASCDS_INSTALL/config/system/CXCdefaults - are:

  *HelpBrowser                 : netscape
  *HelpBrowserDelay            : 3
  *HelpBrowserOpenURLCommand   : netscape -remote 'openURL($)'
  *HelpBrowserOpenFILECommand  : netscape -remote 'openFile($)'

The meanings of the fields is given in the following table:

Field	Description
HelpBrowser	The name of the browser; if a running process is not found with this name then the command is run as a background process and ahelp will wait HelpBrowserDelay seconds before continuing. This field need not be set; in particular if the browser does not support a means of setting the location of an existing copy then the field should be left empty.
HelpBrowserDelay	The delay (in seconds, converted to an integer) to wait after starting the browser (name given in the HelpBrowser field). This should be increased if it is found that the browser takes so long to start up that ahelp has already finished (and so the requested page is not displayed in the browser).
HelpBrowserOpenURLCommand	This command is used to open a URL (for when 'ahelp -i' is used). If the command does not exit immediately then it must end with a '&'.
HelpBrowserOpenFILECommand	This command is used to open a file (for when 'ahelp -w' is used). If the command does not exit immediately then it must end with a '&'.

All '$' signs in the "OpenURL" and "OpenFILE" command strings will be replaced by the name of the file or URL to display (if you need to include a dollar sign then use '\$'). As an example, with the default settings,

  unix% ahelp -i dmcopy

will use the HelpBrowserOpenURLCommand value of

netscape -remote 'openURL($)'

which will be expanded to

netscape -remote 'openURL(http://cxc.harvard.edu/ciao/dmcopy.html)'

Below we provide a number of configurations suitable for some of the more popular web browsers. First we list the values suitable for the Solaris and Linux platforms.

Mozilla

  *HelpBrowser                : mozilla
  *HelpBrowserDelay           : 3
  *HelpBrowserOpenURLCommand  : mozilla -remote 'openURL($)'
  *HelpBrowserOpenFILECommand : mozilla -remote 'openFile($)'

Konqueror

With the following settings a new konqueror session will be started each time 'ahelp -i' or 'ahelp -w' is used.

  *HelpBrowser                :
  *HelpBrowserDelay           :
  *HelpBrowserOpenURLCommand  : konqueror $ &
  *HelpBrowserOpenFILECommand : konqueror $ &

Konqueror

With the following settings, 'ahelp -i' or 'ahelp -w' will use an existing konqueror (starting one if it does not).

  *HelpBrowser                : konqueror
  *HelpBrowserDelay           : 3
  *HelpBrowserOpenURLCommand  : dcop `dcop konqueror-\* | head -1` konqueror-mainwindow\* 'openURL(QString)' $
  *HelpBrowserOpenFILECommand : dcop `dcop konqueror-\* | head -1` konqueror-mainwindow\* 'openURL(QString)' $

Lynx

  *HelpBrowser                :
  *HelpBrowserDelay           :
  *HelpBrowserOpenURLCommand  :  xterm -e lynx $ &
  *HelpBrowserOpenFILECommand :  xterm -e lynx $ &

Opera

  *HelpBrowser                :  opera
  *HelpBrowserDelay           :  3
  *HelpBrowserOpenURLCommand  :  opera -remote 'openURL($)'
  *HelpBrowserOpenFILECommand :  opera -remote 'openFile($)'

For OS-X systems the configuration options look a little different:

Safari

  *HelpBrowser                :
  *HelpBrowserDelay           :
  *HelpBrowserOpenURLCommand  :  open $ &
  *HelpBrowserOpenFILECommand :  open -a Safari file://$ &

Mozilla (on OS-X)

  *HelpBrowser                :
  *HelpBrowserDelay           :
  *HelpBrowserOpenURLCommand  :  open $ &
  *HelpBrowserOpenFILECommand :  open -a Mozilla file://$ &