Trailing-Edge
-
PDP-10 Archives
-
decuslib10-11
-
43,50535/phi.mem
There are no other files named phi.mem in the archive.
BEGINNERS GUIDE TO PHI 39
U15/A4
This is a brief description of how to use the program PHI for examining system
documentation on various subjects, and on setting up your own PHI files.
CONTENTS
1.0 INTRODUCTION
2.0 HOW TO USE THE 'PHI DOCUMENTATION SYSTEM'
3.0 BASIC CONCEPTS
4.0 THE MOST COMMONLY USED COMMANDS
5.0 HINTS ON USING THE COMMANDS
6.0 SETTING UP YOUR OWN FILES
6.1 COMMANDS
6.2 EDITING OF .PHI FILES USING SOS OR TECO
Page 2
1.0 INTRODUCTION
PHI is a program which provides a means of setting up hierarchically organised
files, examining them online, and printing them out (either in their entirety or
as selected sections).
The program can be used by a user to set up his own files, and it also forms the
basis of the 'PHI Documentation System' - a system for obtaining information on
various system features and programs.
On-line interrogation using PHI is done by selection of sub-sections from a
multi-level structure, enabling the required information to be speedily found.
It is also possible to search for the occurence of a specified string of
characters throughout the text.
The program outputs messages to guide the user and so can be used to examine
existing PHI type documentation files without any previous knowledge of the
program, however reading this document will help you to understand more about
what is going on, and to make better use of PHI.
Full details of the program can be obtained by typing
.PHI PHI
at monitor level.
2.0 HOW TO USE THE 'PHI DOCUMENTATION SYSTEM'
The 'PHI documentation system' is designed to enable users to obtain information
on various system features, programs etc.
To run the system type one of the following monitor command lines:
.PHI This command is best for 'browsing' through available
information. Just follow the instructions typed by the program.
.PHI <name> will type info about the subject <name> (if available)
.PHI'<string> where <string> is a string of characters. Titles in the system
will be searched until one is found which contains the specified
string. Thus you do not have to know the exact subject name.
e.g. .PHI'EDIT for information on editors
To get a lineprinter listing of a subject run PHI as described above, then when
you have got to the subject you want, type the command line
OP/LPT
(the O gets you to the top of the subject if not already there, the P/LPT prints
the entire subject to the lineprinter).
Page 3
3.0 BASIC CONCEPTS
A 'subject' is stored on one file, and consists of one or more sections arranged
in a hierarchical 'tree' structure. There is one top-level section , all other
sections being descendants of it. (The tree is an upside down tree, i.e. the
root is at the top and the branches hang down!)
Each section has a title and (usually) text associated with it. Subjects may be
linked together to form a 'tree' of subjects - this is how the 'PHI
documentation system' works.
When PHI is run, if a subject name has been specified, you will go in at the top
of that subject. If just 'PHI' was typed however, you will go in at the top of
the documentation system and can then move down to any of the other subjects.
Once in a subject you can move around from section to section, listing the text
in sections as desired. You can also move back up the tree to higher level
subjects, but can never move above the point at which you 'came in'.
4.0 THE MOST COMMONLY USED COMMANDS
PHI will type a * on the terminal as a prompt when it expects you to type in a
command.
The most important commands you need to start with are listed below. (The words
in brackets after each command letter are just an aid to memory - only the
single command letter should be typed).
(1) Commands to move from one section to another:
* O (Origin) - gets back up to the top of the subject
* n - where n is a number, gets you to the n'th sub-section of
the current section
* U (Up) - gets you up to the next highest section, i.e. the
section which 'contains' the current sub-section.
* R (Restart) - gets you back to where you came in. (If you
are still in the same subject then this command has the same
effect as the 'O' command.
(2) Commands to type out to the TTY (or print to lineprinter):
* Pressing 'RETURN' causes the title and text for the current
section to be typed out, together with a list of the titles of
all sub-sections (the immediate descendants of the current
section).
* Pressing the 'ESCAPE' (sometimes called 'ALTMODE') key has the
same effect except that text for the current section is not typed.
* L (List) - prints out the title of the current section
together with the titles of all its sub-sections. Thus if
this is done when at the top level, a complete list of the
contents of the subject is produced. (L/LPT prints to the
lineprinter).
Page 4
* P (Print) - prints the current section and all of its
descendant sections. Thus if this is done at the top level the
whole subject will be printed. (P/LPT prints to line-printer).
(3) Search commands:
* 'string where string is a string of characters, searches until
it finds a section whose title contains the string specified.
e.g. 'FRED searches for a section which has 'FRED' in the title.
* Fstring is the same as above except that the text is searched
as well as the titles.
e.g. FFRED searches for 'FRED' in titles and text.
You can always suppress output from the program by typing the CTRL/O character,
after which the program will be ready for the next command. (Sometimes if you
do this, the 'prompt' asterisk may not appear - if nothing appears to happen
after a couple of seconds, just press the linefeed key to get the 'prompt', then
the program will be ready for the next command).
Commands may follow the subject name on the PHI monitor command line, e.g.
.PHI NEWS'PASCAL
to see if there is any news on PASCAL.
5.0 HINTS ON USING THE COMMANDS
(i) To re-type the section you have just been looking at, press RETURN.
(ii) If you have just looked at, say, subsection 5 and then want to look at
subsection 3, type U3. (The U gets you back up a level, then the 3 gets
you down to subsection 3).
(iii) Suppose you want to type out all the information on the PHI file for a
given subject: Run PHI for that subject, then type the 'P' command. This
command can also be used when you are positioned at any particular section
to type out that section and all its subsections.
Page 5
6.0 SETTING UP YOUR OWN PHI FILES
To create or modify a new subject file, the switch /M should be specified after
the subject name.
e.g. .PHI FRED/M
To define title and text for a section use the "M" command.
To create a new sub-section use the "X" command.
User guidance messages from the program for the above two commands should be
self explanatory, but the commands are also described below.
When typing in text for a section don't start any words after column 72 because
when PHI is used to print the text at the terminal, lines will be split at the
first space character after column 72.
It is advisable not to use tab characters, as the indentation produced when
doing a P command may not be that which was intended.
Remember that no data is written to disk until a "W" command is done.
6.1 COMMANDS
W - write the .PHI file. (Any existing .PHI file will be renamed to .QHI)
It is advisable to do this at regular intervals if doing a lot of
updating.
M - "Modify". Defines title and text for current section. The program
prompts separately for title and text. If just an ESC is typed, no
change is made (useful if you type "M" by mistake).
DN - Delete current section. Its descendant tree is brought up a level to
be where the deleted section was.
DT - Delete Tree, deletes the current section AND its descendant tree.
X - Add an eXtra sub-section as an immediate descendant of the current
section. If the current section already has sub-sections, the program
will ask where you want to insert the new sub-section: type 0 for
insertion before all the other sub-sections, a number, n, for
insertion after the n'th sub-section, or press return for insertion
after all the other sub-sections. The program prompts for title and
text separately.
There are also commands which enable sections to be moved around
within the tree. For details see the full documentation.
Page 6
6.2 EDITING OF .PHI FILES USING SOS OR TECO
The text in a .PHI file can be edited using SOS or TECO. When doing so you
should be careful not to alter any of the level numbers or special
characters which terminate titles and text (see below), otherwise you are
liable to change the structure of the tree. (There are also editing
facilities available within PHI, by using the M/ command. See the full
documentation for details). If you understand the structure of a .PHI file
(described below) you can also create .PHI files using SOS or TECO.
The .PHI file consists of the title and text for each section in the order
in which sections would be printed in a P command. (i.e. a section is
always directly followed by all of its descendant sections). The top level
section is always first and is regarded as level 0, its immediate
descendants as level 1, and so on down the tree. For an example type out
any of the .PHI files on the DOC: area.
Each section starts on a new line and has the following form:
n.title^
text.....
....
....~
where n is the section level number, and the character which terminates the
text is the 'tilde' character, ASCII value 176 octal, sometimes also known
as the 'twiddle' character. (This character is not available on some of
the older teletypes, if you are using such a teletype you will have to use
TECO to insert the character by giving its ASCII numeric value).
Blank lines and formfeeds (and any other control characters) are allowed
between sections (but will not be preserved when the file is written out
using the W command).
If there is no text for a section, it could have the form:
n.title~