Enter your search terms Submit search form
	Web pdp-10.trailing-edge.com

.PS60,80;.LM0;.TS65;.PARA0
^&BEGINNERS GUIDE TO PHI\&	39
.I64;U15/A4
.S6
 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.
.s6
.C; ^&CONTENTS\&
.LM0;.HL1 INTRODUCTION
.LM0;.HL1 HOW TO USE THE 'PHI DOCUMENTATION SYSTEM'
.LM0;.HL1 BASIC CONCEPTS
.LM0;.HL1 THE MOST COMMONLY USED COMMANDS
.LM0;.HL1 HINTS ON USING THE COMMANDS
.LM0;.HL1 SETTING UP YOUR OWN FILES
.LM5;.HL2 COMMANDS
.LM5;.HL2 EDITING OF .PHI FILES USING SOS OR TECO
.AP;.LM0;.PG

.NUMBER LEVEL1;.LM0;.HL1 ^&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 
.I3;_.PHI PHI
.I5;at monitor level.


.LM0;.HL1 ^&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:
.AT;.LM15;.TS15;.PARA-15
_.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
.AP;.LM0;.PARA0
 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
.I3;OP/LPT
.BL
.BR;(the O gets you to the top of the subject if not already there, the P/LPT
prints the entire subject to the lineprinter).

.LM0;.HL1 ^&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'.
.LM0;.HL1 ^&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).
.BL;.LM3;.NF
(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.
.BL
(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).

.TP6;  * 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).
.BL
(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.
.LM0;.F
 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.
.I3;..PHI NEWS'PASCAL
.I5;to see if there is any news on PASCAL.
.LM0;.HL1 ^&HINTS ON USING THE COMMANDS\&
.AT;.LM5;.TS5;.PARA-5
(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.
.AP;.LM0;.PG

.LM0;.HL1 ^&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.
.BR;To create a new sub-section use the "X" command.
.BR;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.
.LM5;.HL2 ^&COMMANDS\&
.AT;.LM10;.TS10;.PARA-5
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.
.BL
 There are also commands which enable sections to be moved around
 within the tree. For details see the full documentation.

.AP;.LM5;.PARA0
.LM5;.HL2 ^&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.
.TP6
 Each section starts on a new line and has the following form:
.BR;n.title_^
.BR;text.....
.BR;.....
.BR;....._~
 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:
.BR;n.title_~