Last modified: December 2022

URL: https://cxc.cfa.harvard.edu/ciao/ahelp/ahelp.html
AHELP for CIAO 4.16

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

Description

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>

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 toolname or concept (e.g. "pileup"), use the "ahelp -k" command:

  unix% ahelp -k <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 ahelp files

The syntax for running ahelp from the Sherpa command line is slightly different:

sherpa> ahelp("load_pha")

There is a shorthand option of using a comma (",") to indicate that the argument should be in quotes, e.g. the above command could be called as:

sherpa> ,ahelp load_pha  

It is also possible to escape the Sherpa 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% ahelp -k /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.
-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.

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 share/doc/xml/ and contrib/share/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".


Examples

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

ahelp -k grating

Displays a list of subjects that are cross-referenced using the keyword "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

ahelp -k /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.

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/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).

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

Caveats

Error: AhelpDBTable::AhelpDBTable - failed to open file '/data/ciao-4.4/doc/xml/CXCHelpDB'  (04 Jun 2008)

This message may be seen when attempting to reindex the ahelp files with "ahelp -r".

Workaround:

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.