Access the CIAO help documentation.
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
The ahelp command accesses the CIAO command-line documentation. By default it displays an ASCII version of the help file. The CIAO site contains HTML versions of the help files.
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 toolname or concept (e.g. "pileup"), use the "about" command:
unix% about <keyword>
to get a list of subjects related to your query (i.e. whatever value used for <keyword>). To find out all the entries for a given context, use
unix% ahelp -c <context>
To list all available contexts, 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 syntax for running ahelp from the Sherpa or ChIPS command line is slightly different:
sherpa> ahelp("load_pha") chips> ahelp("make_figure")
There is a 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
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 "dm":
unix% ahelp -c /^dm/
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
|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.
The most useful options are given below. If no option is supplied, ahelp defaults to -l.
|-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 primarily useful to CIAO developers and those that install the CIAO software.
|-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 share/doc/xml/ and contrib/share/doc/xml/ sub-dirctories of <path> - if given - otherwise $ASCDS_INSTALL.|
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".
Displays this help file (it is the same as doing "ahelp ahelp").
Displays the full help file for the dmcopy tool.
Displays a list of subjects that are cross-referenced using the keyword "grating". it is equivalent to
unix% ahelp -k grating
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.
Lists all help files which are cross-referenced by a string that contains the text "struct".
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.
ahelp -c dm
Gives a list of all available subjects within the "dm" context, along with their synopsis.
ahelp -b BUGS dmstat
Displays the bugs section of the dmstat help file.
ahelp -b QEXAMPLELIST dmstat
Displays the examples section of the dmstat help file.
ahelp -b PARAM dmcopy
Displays the parameter section of the dmcopy help file.
ahelp -b PARAM -t infile dmcopy
Displays the description of the infile parameter of dmcopy.
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.
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).
ahelp -s dmcopy
Gives a short (synopsis and syntax) help for the tool dmcopy.
ahelp -n 35 times
Displays help information about Chandra times, formatted as 35 columns per line.
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" &
ahelp -s -f /mydir/myfile.xml
Processes the supplied file and displays a short version of the help information stored in /mydir/myfile.xml.
ahelp -r /mydir/
Re-creates the database of the help files located in /mydir/share/doc/xml/ and /mydir/contrib/share/doc/xml/.
Structure of an ahelp File
The basic layout of a help file is as follows (although some sections will not appear in all files).
|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.
- See also section produces garbled output
The "See Also" section of the ahelp output appears to be garbled/corrupted on some platforms.
- Error: AhelpDBTable::AhelpDBTable - failed to open file '/data/ciao-4.4/doc/xml/CXCHelpDB' (04 Jun 2008)
Confirm that the directory /data/ciao-4.4/doc/xml (in this case) has write permissions enabled and is owned by the user running the reindexing.
The user who is reindexing the ahelp files has to be the same one that installed the CIAO software. For instance, if you installed CIAO on your laptop as root, then the reindex must also be done by the root user.