| AHELP for CIAO 4.2 | ahelp |
Context: ahelp |
Synopsis
Access the CIAO help documentation.
Syntax
ahelp [-n width] [-s|-m|-l] subject ahelp [-n width] [-s|-m|-l] context subject ahelp [-n width] -b blockname [-t attribute] subject ahelp [-n width] -b blockname [-t attribute] context subject ahelp [-n width] -c context ahelp [-n width] -c ahelp -r [path] ahelp [-x default_context] [-n width ] [-s|-m|-l] -f xmlfile ahelp -k keyword about keyword
Description
The ahelp command accesses the CIAO on-line documentation. By default it displays an ASCII version of the help file. 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>
or
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>
To list all available contexts you use
unix% ahelp -c
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.
Sherpa and ChIPS ahelp files
The ahelp files for Sherpa and ChIPS contain information for both the supported languages: python and s-lang. The value of the CIAO_SCRIPT_LANG environment variable is used to determine which version of a help file to display.
From the CIAO command line, it is also possible to specify which version, or context, you would like:
unix% ahelp py.sherpa load_pha unix% ahelp sl.sherpa load_pha unix% ahelp py.chips make_figure unix% ahelp sl.chips make_figure
When calling ahelp from within Sherpa or ChIPS, the syntax for the language you are using is chosen automatically. That is, if you are runnning the python Sherpa environment, the python ahelp is always returned. The syntax for running ahelp from the Sherpa or ChIPS command line is slightly different:
sherpa> ahelp("load_pha") # Python
sherpa> ahelp("load_pha"); % S-lang
chips> ahelp("make_figure") # Python
chips> ahelp("make_figure"); % S-lang
Python users have an additional shorthand option of using a comma (",") to indicate that the argument should be in quotes, e.g. the above commands could be called as
sherpa> ,ahelp load_pha sherpa> ,ahelp make_figure
Python users are also able to do a wildcard search:
sherpa> *curve* ? sherpa> plot* ? sherpa> *psf ?
It is also possible to escape the Sherpa or ChIPS command line and run ahelp from the shell, thus allowing you to use all the options outlined in this file:
sherpa> ! ahelp -k plotting
Using regular expressions
It is possible to use a regular expression when specifying any of the subject, context, or keyword in a search. To find a list of all the keywords that contain the text "par":
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, depending on what system you are using, such as "man regexp".
Listing specific sections of the help file
The "-b blockname" option 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.
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. |
| -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. |
| -x <default_context> | Set default context to 'default_context' when parsing ahelp file. It is used with -f option for multicontext xml files |
| -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".
Example 1
ahelp
Displays this help file (it is the same as doing "ahelp ahelp").
Example 2
ahelp dmcopy
Displays the full help file for the dmcopy tool.
Example 3
about grating
Displays a list of subjects that are cross-referenced using the keyword "grating". it is equivalent to
unix% ahelp -k grating
Example 4
ahelp /struct/
Lists all help files with a subject that contains the text "struct". If there is only one match then that help file will be displayed, otherwise the subject, context, and synopsis information for each matching file will be found.
Example 5
about /struct/
Lists all help files which are cross-referenced by a string that contains the text "struct".
Example 6
ahelp /stk/ ahelp tools /stk/
The regular-expression support can be combined with restricting a search to a particular concept. The first ahelp call lists all help files whose subject contains "stk", whereas the second one restricts the search to those subjects in the "Tools" concept.
Example 7
ahelp -c dm
Gives a list of all available subjects within the "dm" context, along with their synopsis.
Example 8
ahelp -b BUGS dmstat
Displays the bugs section of the dmstat help file.
Example 9
ahelp -b QEXAMPLELIST dmstat
Displays the examples section of the dmstat help file.
Example 10
ahelp -b PARAM dmcopy
Displays the parameter section of the dmcopy help file.
Example 11
ahelp -b PARAM -t infile dmcopy
Displays the description of the infile parameter of dmcopy.
Example 12
ahelp -b ADESC dmextract
There may be additional text in a help file after the examples/parameters but before the BUGS section. These are referred to as ADESC sections, and may have a title (if so, they will be numbered). In this example we display all such sections from the dmextract help file.
Example 13
ahelp -b ADESC -t 'OUTPUT COLUMNS: RADIAL PROFILES' dmextract
If an "ADESC" section has a title then you can select just that section using the "-t" option. Here we display the 'OUTPUT COLUMNS: RADIAL PROFILES' section of the dmextract help file (note that the number preceeding the section title should not be included in the "-t" option).
Example 14
ahelp -s dmcopy
Gives a short (synopsis and syntax) help for the tool dmcopy.
Example 15
ahelp -n 35 times
Displays help information about Chandra times, formatted as 35 columns per line.
Example 16
ahelp -n 100 -b PARAMLIST acis_process_events
Displays help information on the parameters of acis_process_events assuming there are 100 columns per line. One useful trick is to use taskmonitor to display the output:
unix% taskmonitor "ahelp -n 100 -b PARAMLIST acis_process_events" &
Example 17
ahelp -s -f /mydir/myfile.xml
Processes the supplied file and displays a short version of the help information stored in /mydir/myfile.xml.
Example 18
ahelp -r /mydir/
Re-creates the database of the help files located in /mydir/doc/xml/ and /mydir/contrib/doc/xml/.
STRUCTURE OF A HELP FILE
The basic layout of a help file is as follows (although some sections will not appear in all files).
| Section | Description |
|---|---|
| SYNOPSIS | Provides a short overview of the help file |
| SYNTAX | How to call the command or tool |
| DESCRIPTION | This section contains the main body of the help text |
| EXAMPLES | Examples of how to use the tool or command |
| PARAMETERS | Lists the parameters of the tool, first as a table and then as a detailed list. |
| Additional description | This section is used to provide additional information that is not relevant to day-to-day use of the tool/command. This text (that appearing under the "Structure of a help file" title) is an example of such a section. |
| BUGS | This section describes bugs and issues that are known about the tool when CIAO was released. As described below, the CIAO web site should be consulted to see if any newer items have been found. |
| SEE ALSO | This section lists related help files in the format of "subject(context)". These can then be followed using "ahelp subject" or "ahelp context subject" on the command line, or by using the links in the HTML versions. It provides a useful way to explore the CIAO help documentation. |
To find out if any issues or bugs have come to light since the release please visit the bugs section of the CIAO web pages.
Bugs
See the bugs page for this tool on the CIAO website for an up-to-date listing of known bugs.
![[CIAO Logo]](../imgs/ciao_logo_navbar.gif){kind=logo}