ahelp

Synopsis

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

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

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.

Options for the CIAO developer

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

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

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.