EXPLAIN - obtain on-line information.

Note: Beginning users who want a non-technical introduction to explaining things should see "expl expl intro".

Syntax:

explain [option]* [topic or sub-topic]*
(+|-)Paginate (-)          (+|-)Verbose
Pagelength=number          (+|-)indeX (+)
Starts=string

Examples:

expl
expl fortran hints
expl b lib printf pl=10
expl ec >temp        -- directs the explain to a file

Options:

+Paginate
paginates output. EXPL will pause after displaying a number of lines to give you a chance to read what is displayed. After you've read what's there, enter a carriage return and EXPL will display more lines. You can use the Pagelength= option to specify how many lines EXPL displays before pausing. If you do not specify Pagelength=, the default is to display 18 lines at a time.
Pagelength=number
sets the number of lines EXPL displays at a time when you are using +Paginate. Specifying Pagelength= automatically implies +Paginate, so you don't have to specify +Paginate explicitly.
-indeX
does not try to find an index to display if EXPL cannot find the topic you request. If you do not specify -indeX and EXPL can't find a topic, EXPL displays the index file closest to the topic you wanted. Examples of this are given later on.
+Verbose
produces additional output. This includes the pathname where EXPL found the displayed information, and more verbose prompts and error messages.
-Verbose
does not display "not found" error messages, and generally makes output less wordy.
Starts=string
looks through the explain file for the first occurrence of the given string. If EXPL finds a match, EXPL displays the file from that point onward. If not, EXPL does not display anything from the file. For example,
Starts="Description:"

starts displaying the explain information beginning with the "Description:" line.

Description:

EXPLAIN provides on-line information about TSS commands, subsystems, language processors, and other features. Explanations are stored in files under the userid EXPL or LIBRARY/EXPL. The EXPL command automatically searches both locations to find a desired explain file.

The Searching Process:

When you enter an EXPL command, the EXPLAIN subsystem forms a pathname from the command line by replacing strings of one or more blanks with a slash. For example,

expl fortran batch

is changed into the pathname

expl/fortran/batch

EXPL then examines each piece of the pathname from left to right, verifying that the pathname component exists. In the above example, EXPL would check for the existence of

expl
expl/fortran
expl/fortran/batch

If a component of a pathname does not exist as it stands, it is truncated, first to six characters, and then to four characters if the first truncation fails. In the above example, suppose EXPL finds there is no file or directory named "expl/fortran". EXPL then tries "expl/fortra". If that also fails, EXPL looks for "expl/fort". If "expl/fort" exists, EXPL then uses this new pathname in future searches. For example, it searches for

expl/fort/batch

If that doesn't exist, EXPL truncates the final pathname component to

expl/fort/batc

If this file exists, EXPL uses takes this as the desired explain file.

If a topic has several sub-topics, its main explain file is stored in the file "expl" underneath the topic catalog. For example, the explain file corresponding to "expl fortran" is

expl/fort/expl

because "expl/fort" is a catalog.

Explain Files:

When EXPL finds an explain file corresponding to the topic on the command line, EXPL checks to see if the file is sequential or random. If the file is sequential, EXPL simply displays the contents of the file as text. If the file is random, EXPL executes the file as a program. In this way, your site may create explain files which run as programs and obtain information from a variety of sources.

Missing Explain Files:

Sometimes EXPL cannot find a file that matches your topic. This can happen because you make a typing error when entering the topic or because an explain file hasn't been created for the topic. In this case, EXPL displays "unable to explain" and asks if you want an index. If you answer "yes" or "y", EXPL displays the closest index to the topic you tried to explain. For example, suppose you enter

expl trace trace zxcvbnm

EXPL first tries to display

expl trace trace index

If this index doesn't exist, EXPL tries

expl trace index

then

expl index

If you don't want EXPL to look for an index in this way, specify the -indeX option on the command line.

Pagination Conventions:

By default, EXPL does not paginate its output. If a pagination option is specified on the command line, EXPL paginates according to the following conventions.

Even EXPL does not paginate your output, the output may still be paginated by TSS if you have used STTY to ask for pagination; see "expl stty" for more information.

See Also:

expl expl intro
for a less technical description of the EXPL command.
expl expl conventions
for tips on how to read an explain file.

Copyright © 1996, Thinkage Ltd.